> ## Documentation Index
> Fetch the complete documentation index at: https://docs.blockgence.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Audit

> Smart contract review with AI agents: the AI proposes and execution proves. Levels, validation grades, leads, report and seal.

> [!WARNING]
>
> **Audit is in preview.** The agent engine does not run end to end in the service yet. What you see in the app today:
>
> * The audits on the dashboard are **examples**: **synthetic** projects, repos, contracts and findings, marked "datos de
>   ejemplo" (demo data). They are there to show the screens. They are not real audits.
> * A review you request **is registered as queued, but it does not run**. The screen says so and its sections stay
>   empty: that does not mean "no findings".
> * Verification of the deployed bytecode and publishing the seal are not available yet.
>
> The rest of this page describes how the product works and what each section will show.

> [!NOTE]
>
> The app's interface is in Spanish. Screens, tabs and buttons are named as they appear, with their English meaning.

Audit reviews the smart contracts of a repository at a fixed commit. Specialized AI agents propose attack hypotheses,
and a finding only counts with its proof: a test that reproduces the attack, a broken invariant, a person's confirmation
or a deterministic fact. Whatever could not be proven is shown separately, as a **lead**, without severity.

Open it from **app.blockgence.com → Auditoría**.

![Audit dashboard](https://mintcdn.com/blockgence/jIDqBW86tOU_Ini-/images/products/audit/dashboard.png?fit=max\&auto=format\&n=jIDqBW86tOU_Ini-\&q=85\&s=5381584374cc1bd39812c2d3b5d26f27)

The audit dashboard, with the example audits.

## Levels

| | **Automated review** (Revisión automática) | **Assisted review** (Revisión asistida) | **Audit** (Auditoría) |
| - | - | - | - |
| Input | Repo and commit | Repo, commit and passing tests | Repo, commit, specification and a kickoff meeting |
| Human | No | Short triage of the findings | An auditor end to end |
| What it includes | Code map, static analysis and readiness checklist | The full engine: specialists, skeptic, proofs of concept, invariants and fuzzing | Everything, driven by the auditor |
| Report | Private | Private; can be published | Public if you want |
| Seal | No | Yes, if published | Yes |

The word "audit" only names what a person reviews. The automated review is not one.

## Validation grades

Each finding says **what proves it**. The grade is assigned by a fixed rule, not by an agent.

| Grade | What backs it |
| - | - |
| **G1 · Proven by execution** | A Foundry proof of concept that passes in the sandbox, with an explicit oracle: the attacker gains, an invariant breaks, or someone without permission changes a state. Downloadable as a test. |
| **G2 · Proven by fuzzing or symbolic execution** | A broken invariant, with the reduced call sequence, or a counterexample. |
| **G3 · Confirmed by review** | A person confirms it with a citation, and the skeptic could not refute it. |
| **G4 · Deterministic fact** | A rule or tool with an exact match and a citation, or an on-chain fact (for example, the upgrade is controlled by a regular account). |
| **Lead** | A hypothesis without proof. It goes separately, under **Pistas sin validar** (unvalidated leads), without severity and outside the count. |

**Origin** (who proposed it: an agent, a rule, a tool, a person) and **grade** (what proves it) are two separate
things: an agent's hypothesis with a passing proof is G1.

### Severity

Critical, High, Medium, Low, Informational and Gas.

* Critical and High require G1, G2 or G3. A G4 finding about the code does not go above Medium.
* Control warnings about what is deployed are G4 with a fixed severity (see "Deployment and control").
* A lead has no severity. It shows the severity it would have if proven, so you know where to look.
* A finding you mark as acknowledged keeps its severity.

## Inside an audit

Each audit is an isolated space, like a case: everything inside belongs to that audit and to your organization. The top
shows the project, the repo and commit, the level and the status of the run. Below are its sections:

> [accordion] Resumen, Hallazgos, Pistas and Pruebas (summary, findings, leads and proofs)
>
> * **Resumen (summary):** the count by severity and grade, what it covered and what it did not, and the disclaimers.
> * **Hallazgos (findings):** each with its grade, its location (file and line), the highlighted code, the description,
>   the impact, the recommendation and its proof or citation.
> * **Pistas (leads):** the unvalidated hypotheses, with the possible severity, in how many runs they appeared, the
>   skeptic's refutation if there is one and why they were not proven.
> * **Pruebas (proofs):** the proofs of concept and fuzzing sequences, with the Foundry output and the balances before
>   and after.

> [accordion] Mapa, Amenazas, Invariantes, Corrida and Revisiones (map, threats, invariants, run and reviews)
>
> * **Mapa (map):** contracts, inheritance, entry points with their guards, roles, value flows and external calls, in a
>   navigable diagram.
> * **Amenazas (threats):** the threat model: assets, actors, dependencies, what would be catastrophic and which attack
>   families were searched (and which were not, with the reason).
> * **Invariantes (invariants):** the properties, with their status: broken (with the sequence), not broken, being
>   verified or not exercised.
> * **Corrida (run):** the stages and the agents, the budget used, each agent's model and skills, the tokens and the
>   cost.
> * **Revisiones (reviews):** the history by commit and the comparison between two runs: fixed, new and still open.

> [accordion] Deploy y control, Sello and Notas (deployment and control, seal and notes)
>
> * **Deploy y control (deployment and control):** the deployed addresses, the bytecode verification against the
>   commit and the control report.
> * **Sello (seal):** publishing the report, the live status of the seal and how to verify the signature.
> * **Notas (notes):** your team's notes on findings and leads.

![Findings section](https://mintcdn.com/blockgence/jIDqBW86tOU_Ini-/images/products/audit/findings.png?fit=max\&auto=format\&n=jIDqBW86tOU_Ini-\&q=85\&s=c2cdc2f53b08f9b3d5cd9189029c399d)

Findings of an example audit.

Partial and Failed are shown in amber with their cause: a stage that did not run, not a risk. **What did not run was not
reviewed**, and that is not "no findings".

## Request a review

**1. The code**

A **public GitHub** repo and the **full commit hash** (40 characters): the whole report refers to that commit, not to
a branch. Uploading a zip and private repos are not available yet.

**2. The files in scope**

By default, `src/` without tests, scripts or dependencies. You edit one path or pattern per line, and a leading `!`
excludes. Whatever is left out is not reviewed, and the report says so.

**3. The level and the specification**

Pick the level. The specification is optional, except for an Audit: with it, the discrepancies between what the code
does and what it should do can be flagged.

> [!NOTE]
>
> Today the review stays **queued** and does not run (see the warning above). Requesting it does not charge credits.

## Deployment and control

An audit is a snapshot of a commit. After the report, a contract can be exposed if something different is deployed, if
keys or roles are misconfigured, or if there is an upgrade. This section covers those three things:

* **Bytecode verification** against the reviewed commit: **match**, **match except metadata** or **mismatch**, with the
  first difference. For a proxy, the implementation is compared. *Not available yet: an address you add stays
  "unverified".*
* **Control report**, from the `/v1/contract` reading: who can upgrade the contract (the ProxyAdmin → Safe → timelock
  chain), who holds each power, and these warnings with a fixed severity:

| Warning | Severity |
| - | - |
| The upgrade is controlled by a regular account | High |
| Safe with threshold 1, or with all signers equal, and at least one owner that is a regular account | High |
| Timelock of 0 seconds | Medium |

A warning only comes from a **fact** in the reading. What the reading cannot decide (a minting cap, a timelock the admin
can bypass, a renounced role the specification says should exist) is declared as not evaluated.

## Report and seal

**The report is private by default.** If you publish it, the **seal** is generated: a public page with the report, the
commit, the addresses and their network, the Blockgence signature and an OpenTimestamps timestamp. The addresses are
then watched with Watchtower, and the seal changes status:

| Status | When |
| - | - |
| **Current** (vigente) | The code and the control match what was reviewed. |
| **Code changed** (código cambiado) | There was an upgrade to an implementation that was not reviewed. |
| **Control changed** (control cambiado) | Who controls the contract changed. It does not invalidate the code, but you are notified. |
| **Expired** (vencido) | The validity period passed without a new review. |

Anyone can verify the seal without trusting the Blockgence website: download the report, recompute its sha256, check the
signature with the public key and the timestamp with OpenTimestamps. See
[Methodology and evidence](https://docs.blockgence.com/en/methodology/verify-signature.md). *Publishing is not available yet.*

![Seal section](https://mintcdn.com/blockgence/jIDqBW86tOU_Ini-/images/products/audit/seal.png?fit=max\&auto=format\&n=jIDqBW86tOU_Ini-\&q=85\&s=2b99005464feac250164feca5053c39e)

The Sello (seal) section of an example audit.

## Through the API

| Method | Path | What it does |
| - | - | - |
| GET | `/v1/audit` | Your organization's audits and the example ones (marked `demo: true`). |
| GET | `/v1/audit/{id}` | An audit's summary: run, counts by severity and grade, leads and seal. |
| GET | `/v1/audit/{id}/{section}` | One section: `resumen`, `mapa`, `amenazas`, `hallazgos`, `pistas`, `invariantes`, `pruebas`, `corrida`, `revisiones`, `deploy`, `sello` or `notas`. |
| POST | `/v1/audit` | Request a review. Today it stays queued, and the response declares it in `note` and `queue`. |
| POST | `/v1/audit/{id}/deploy` | Add the deployed addresses of one network. |
| POST | `/v1/audit/{id}/notes` | Add a team note. |

```bash Request a review theme={null}
curl -X POST https://app.blockgence.com/v1/audit \
  -H "X-API-Key: $BKG_KEY" -H "Content-Type: application/json" \
  -d '{"repo": "https://github.com/example/vault", "commit": "3f2a1c9e5b7d4a06c1e8f2b39d0a7c5e1f4b6a28", "level": "automated"}'
```

```json Response (trimmed) theme={null}
{
  "demo": false,
  "note": "El motor de auditoría no está encendido en este servidor: la revisión quedó registrada en cola, pero no va a correr hasta que se encienda. No hay resultados: las secciones vacías no son «sin hallazgos».",
  "audit_id": "aud_20a6e106dc7ab5cf",
  "audit": { "id": "aud_20a6e106dc7ab5cf", "repo": "example/vault", "level": "automated",
             "run": { "state": "queued" }, "requested": true, "findings_total": 0, "leads": 0 },
  "queue": { "state": "not_enqueued" }
}
```

The API's texts (such as `note`) are in Spanish. Each request about an audit accepts the optional `X-Audit-Id` header.
If it does not match the path, the response is `400 audit_id_mismatch`. An audit from another organization gets the same
`404` as one that does not exist. Audit routes do not charge credits. Details in the [API reference](https://docs.blockgence.com/en/api/reference.md).

## What it does not cover

* **A review is not a security guarantee.** It covers the commit and the files in scope. Code, configuration, keys and
  integrations outside that scope are not reviewed.
* Automated tools do not catch most business-logic bugs.
* AI agents propose. A finding only counts with its proof (G1 to G4). **Leads can be false, and the absence of findings
  does not prove there are no bugs.**
* The report says which AI model was used and what each agent covered.
* Watchtower only sees what the contract emits: the owner of a ProxyAdmin or a Safe that was not registered is left out.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.