> ## 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 is not yet available end to end. In the application:
>
> * The audits on the dashboard are **examples**: **synthetic** projects, repositories, contracts and findings, marked as
>   "datos de ejemplo" (demo data). They illustrate the screens and do not correspond to real audits.
> * A requested review **is registered as queued, but it is not executed**. The screen states so, and its sections remain
>   empty, which does not mean "no findings".
> * Verification of the deployed bytecode and publication of the seal will be available soon.
>
> The rest of this page describes how the product works and what each section contains.

> [!NOTE]
>
> The application interface is in Spanish. Screens, tabs and buttons are referred to by their name in the application,
> followed by their English meaning.

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

It is available at **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)

Audit dashboard with the example audits.

## Levels

| | **Automated review** (Revisión automática) | **Assisted review** (Revisión asistida) | **Audit** (Auditoría) |
| - | - | - | - |
| Input | Repository and commit | Repository, commit and passing tests | Repository, commit, specification and a kickoff meeting |
| Human review | No | Brief review of the findings | An auditor throughout the process |
| Includes | Code map, static analysis and readiness checklist | The full engine: specialists, skeptic, proofs of concept, invariants and fuzzing | All of the above, directed by the auditor |
| Report | Private | Private; can be published | Public, if the client decides so |
| Seal | No | Yes, if published | Yes |

The term "audit" is reserved for the review performed by a person. The automated review is not an audit.

## Validation grades

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

| Grade | Evidence |
| - | - |
| **G1 · Proven by execution** | A Foundry proof of concept that runs successfully in an isolated environment, with an explicit criterion: the attacker gains, an invariant breaks or someone without permission changes a state. It can be downloaded 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, that the upgrade is controlled by a regular account). |
| **Lead** | A hypothesis without proof. It is presented separately, under **Pistas sin validar** (unvalidated leads), without severity and outside the count. |

The **origin** (who proposed it: an agent, a rule, a tool or a person) and the **validation grade** (what proves it) are
separate concepts: an agent's hypothesis with a proof that runs successfully 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 exceed 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, as guidance.
* A finding marked as acknowledged keeps its severity.

## Structure of an audit

Each audit is an isolated space, like a case: its content belongs to that audit and to the organization. The top shows the
project, the repository 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 validation grade, what was covered and what was not, and the
>   disclaimers.
> * **Hallazgos (findings):** each one with its validation 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, the number of runs in which they
>   appeared, the skeptic's refutation, if any, and the reason 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 access controls, roles, value flows and external
>   calls, in a navigable diagram.
> * **Amenazas (threats):** the threat model: assets, actors, dependencies, catastrophic scenarios and the attack families
>   analyzed (and those not analyzed, with the reason).
> * **Invariantes (invariants):** the properties and their status: broken (with the sequence), not broken, under
>   verification or not exercised.
> * **Corrida (run):** the stages and 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: findings 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):** publication of the report, the current status of the seal and signature verification.
> * **Notas (notes):** the 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.

The Partial and Failed statuses are shown in amber with their cause: they correspond to a stage that did not run, not to a
risk. **What did not run was not reviewed**, and that does not mean "no findings".

## Request a review

**1. Specify the code**

A **public GitHub** repository and the **full commit hash** (40 characters): the entire report refers to that commit,
not to a branch. Uploading a zip file and private repositories will be available soon.

**2. Define the files in scope**

By default, `src/` is included, without tests, scripts or dependencies. One path or pattern is defined per line, and
the `!` prefix excludes. Anything left out is not reviewed, and the report states so.

**3. Choose the level and provide the specification**

The specification is optional, except for the Audit level. It makes it possible to flag discrepancies between what the
code does and what it should do.

> [!NOTE]
>
> Currently, the review remains **queued** and is not executed (see the warning at the top of the page). Requesting it
> does not use credits.

## Deployment and control

An audit corresponds to a specific commit. After the report, a contract can be exposed if different code is deployed, if
keys or roles are misconfigured, or if it is upgraded. This section covers those three cases:

* **Bytecode verification** against the reviewed commit: **match**, **match except metadata** or **mismatch**, with the
  first difference. For a proxy, the implementation is compared. *Available soon: an added address is shown as
  "unverified".*
* **Control report**, based on the `/v1/contract` query: who can upgrade the contract (the ProxyAdmin → Safe → timelock
  chain), who holds each permission and the following 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 is issued only from a **confirmed fact** in the query. Anything the query cannot determine (a minting cap, a
timelock the administrator can bypass, a renounced role required by the specification) is declared as not evaluated.

## Report and seal

**The report is private by default.** If it is published, 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 | Condition |
| - | - |
| **Vigente** (current) | The code and the control match what was reviewed. |
| **Código cambiado** (code changed) | The contract was upgraded to an implementation that was not reviewed. |
| **Control cambiado** (control changed) | Who controls the contract changed. It does not invalidate the code, but it is notified. |
| **Vencido** (expired) | The validity period ended without a new review. |

Anyone can verify the seal without relying on the Blockgence website: download the report, recompute its sha256, check the
signature with the public key and the timestamp with OpenTimestamps. The procedure is described in
[Methodology and evidence](https://docs.blockgence.com/en/methodology/verify-signature.md). *Publication will be available soon.*

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

Sello (seal) section of an example audit.

## API usage

| Method | Path | Function |
| - | - | - |
| GET | `/v1/audit` | The organization's audits and the example audits (marked with `demo: true`). |
| GET | `/v1/audit/{id}` | An audit's summary: run, count by severity and validation 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. Currently it remains queued, and the response states so in `note` and `queue`. |
| POST | `/v1/audit/{id}/deploy` | Add the deployed addresses on 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 (abridged) theme={null}
{
  "demo": false,
  "note": "…",
  "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" }
}
```

`note` explains the status of the review in text (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 belonging to another
organization returns the same `404` as a nonexistent one. Audit routes do not use credits. Details are in the
[API reference](https://docs.blockgence.com/en/api/reference.md).

## Scope and limitations

* **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 detect most business-logic errors.
* AI agents propose; a finding counts only with its proof (G1 to G4). **Leads may be false, and the absence of findings
  does not prove the absence of errors.**
* The report states which AI model was used and what each agent covered.
* Watchtower only observes what the contract emits: the owner of a ProxyAdmin or a Safe that was not registered is not
  covered.


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