Verify an evidence file offline

One file records who authorised every payment in an agent network, and anyone can check its signatures offline in one command. An evidence/1.1.0 file covers a whole budget: the budget and its root mandate, every signed authority record (the budget, each delegation hop, every freeze, thaw, amendment and revocation), a signed authority head over that record set, and every stream with its signed vouchers, settlements and fee rows.

What offline verification covers. The verifier checks every signature and digest in the file. On its own the file does not prove billing: the engine-signed records do not yet bind each stream's session key. Verification is complete when you pair it with the on-chain settlement or with the engine-signed payment records. It is weakest on Control Mode and the credit card rail, where there is no chain to check.

The head is what makes the file complete rather than merely consistent. It is signed by the engine key and states how many records the budget has and the hash of the last one. A file with a record removed (for example the last revocation, so that a revoked branch looks open) no longer matches its head and fails with a named code.

Later schemas add to that file: 1.2.0 account ids and payee identity levels, 1.3.0 own-hop signatures, payee offers, payment records and consume rows, 1.3.1 the signed own-hops setting and the contract version's voucher domain, and 1.4.0 consent-attributed hops, terms, Task Allowance records and the policy, recourse and organisation sections.

Files in the earlier evidence/1.0.0 format still verify; the result carries the notice "completeness not proven: no signed head".

Status: Live.

Run the verifier

From a clone of the repository, TypeScript:

cd "$DYNAMO_REPO"
pwd
pnpm install --frozen-lockfile
pnpm --filter "@dynamo/evidence..." -r build
node packages/evidence/dist/cli.js evidence.json
node packages/evidence/dist/cli.js evidence.json --json
node packages/evidence/dist/cli.js evidence.json --signer 0xENGINE_SIGNER_ADDRESS

DYNAMO_REPO is the path of your clone. The package declares the command name dynamo-verify for the same entry; it is on your PATH only once the package is installed from a registry, which has not happened yet.

Python 3.10 or later, in its own virtual environment (the verify extra provides signature recovery):

cd "$DYNAMO_REPO"
pwd
"${PYTHON:-python3}" -m venv .venv-dynamo
.venv-dynamo/bin/pip install "./packages/sdk-python[verify]"
.venv-dynamo/bin/dynamoprotocol verify evidence.json
.venv-dynamo/bin/dynamoprotocol verify evidence.json --json --signer 0xENGINE_SIGNER_ADDRESS

Both verifiers make no network call and trust nothing in the file beyond the signatures they recover. Pass --signer with the engine signer address you obtained from the operator out of band: without it the verifier proves the file is internally consistent and signed by the key named in the file; with it, that the key is the one you expected.

Exit codes: 0 PASS, 1 FAIL (the first failure code is printed, then any further ones), 2 usage error or unreadable file.

What is checked

In order: the schema and field shapes, canonical value forms, the sha-256 manifest, every record signature against the engine signer, that every record belongs to this budget, the hash links and stream bindings between records, the depth ceiling, mandate narrowing at every hop and amendment, the signed head (signature, record count, last record hash), that every stream reported revoked has a covering revoke record, and that the reported totals equal the signed vouchers and settlement records. Later schemas add their checks in place: identity after narrowing (1.2.0), the own-hops setting and hop signatures before the head (1.3.0, 1.3.1), the voucher domain before the sums (1.3.1), then payments, consume rows, terms and the Task Allowance, policy, recourse and organisation records (1.3.0 to 1.4.0).

Failure codes

CodeMeaning
schemanot an evidence file, unsupported schema, or a field missing, of the wrong type or not expected
canonical_forma value is not in canonical form
manifestan element digest or the bundle digest does not match the file
signaturea record, voucher or credential whose hash does not recompute from its content, or whose signature does not recover to the expected signer
foreign_recorda record belongs to another budget or funder
hash_linka record's parent hash, ordering or stream binding does not match the chain
depth_ceilinga hop sits deeper than the system ceiling or its mandate allows
narrowing_categorya hop declares a category outside its delegator's mandate
narrowing_widena hop, amendment or reported cap widens its delegator's authority
head_missinga 1.1.0 file carries no signed head
head_signaturethe head is malformed or not signed by the engine signer
head_countthe head's record count differs from the records in the file
head_last_hashthe head's last record hash differs from the file's last record
revoked_uncovereda stream is reported revoked with no covering revoke record
voucher_sumreported totals do not equal the signed vouchers and settlement records
own_hops_flaga 1.3.1 file's signed own-hops flag is missing, malformed, not signed by the engine signer, or not bound to this file's budget, export time and heads
payment_vouchera 1.3.1 payment record names no signed voucher of its stream, or its cumulative amount is not that voucher's
voucher_domaina 1.3.1 file's voucher domain has an unknown name or version, a contract-v2 domain lacks valid asset decimals (or a v1 domain has them), or the vouchers were signed under another domain version
voucher_scalea contract-v2 voucher's amount is not its units in the asset's base units at the file's asset decimals
account_binding, payee_assurance(1.2.0) an account id that does not bind, or a hop whose payee identity level is unknown or below its mandate's minPayeeAssurance
hop_signature, hop_delegator, hop_replay(1.3.0) a hop signature that does not recover to its delegator, a hop signed by someone other than its delegator, or a hop-intent nonce used twice
offer_signature, offer_shape, offer_category, offer_expired(1.3.0) a payee offer not signed by the payee, malformed, not covering the hop's category, or outside its validity window
payment_shape, payment_signature, payment_link, payment_order, payment_head(1.3.0) a payment record that is malformed, wrongly signed, unlinked, out of order, or not covered by the signed payment head
consume_sum, consume_binding(1.3.0) consume rows that do not add up to the last voucher, or whose attributed flag disagrees with the request reference
hop_unsigned, offer_unsigned(1.3.1) a hop without its delegator's signature, or without its payee's signed offer, in a file whose signed own-hops setting says required
hop_consent, terms_mismatch(1.4.0) a consent-attributed hop that is malformed or not at the root of a budget whose signed record allows it, or recorded terms that do not match the stream's signed terms
task_record, policy_record, recourse_record, org_record(1.4.0) a Task Allowance, policy, recourse or organisation record that is tampered, dropped, reordered, wrongly signed or unlinked
agent_verification(1.2.0 and later) a hop whose attested agent verification level is unknown or below its mandate's minAgentVerification

The same codes, with one evidence file per case, are published as conformance vectors in packages/conformance-vectors/ (delegation/, evidence13/, evidence131/, evidence14/, identity/); the TypeScript and Python verifiers agree on every one.

An evidence/1.3.1 file (GET /owner/v1/budgets/{id}/evidence?schema=1.3.1) also carries the core's own-hops setting, signed by the engine key. When it says required, every hop must carry its delegator's signature (hop_unsigned otherwise) and its payee's offer (offer_unsigned otherwise). Its vectors are in packages/conformance-vectors/evidence131/.

Producing a file

The budget's owner exports the file from the core (owner-api 1.5.0 and later; the current core answers 1.11.0), in any of these ways:

control console;

picks the schema; see below);

@dynamoprotocol/sdk 3.0 and later (the default schema only);

schema="1.2.0"), or dynamoprotocol export-evidence <budget-id> evidence.json [--schema 1.2.0].

For 1.3.1 or 1.4.0, call the route directly; the SDK helpers do not ask for them.

Which schema to ask for

BudgetAsk forWhy
Control Mode or credit cardthe default (evidence/1.1.0) or any listed schemaEvery schema covers the whole budget
Stablecoin, contract version 1?schema=1.3.11.3.0 and 1.3.1 report what the payee settled on chain with the payee kit as settled and final; ask for one of them rather than the default 1.1.0
Stablecoin, contract version 2?schema=1.3.1 (or 1.4.0)Only 1.3.1 and 1.4.0 carry the contract version's voucher domain. An older schema answers 400 invalid_request: "a contract v2 budget exports only as evidence 1.3.1; ask for ?schema=1.3.1 (fail closed)"
A top-up budget, or one with a pay-consent root hop?schema=1.4.0 with Dynamo-Version ≥ 1.8.0 (required; preview cores default to 1.11.0)Only 1.4.0 can verify a consent-attributed hop; any other schema answers 400 invalid_request
Any budget, to include its policy, recourse, organisation or task records?schema=1.4.0 with Dynamo-Version ≥ 1.8.01.4.0 is offered only to clients pinned at 1.8.0 or later
cd "$DYNAMO_REPO"
pwd
curl -s -H "Authorization: Bearer $DYNAMO_OWNER_TOKEN" \
  "$DYNAMO_BASE_URL/owner/v1/budgets/$BUDGET_ID/evidence?schema=1.3.1" > evidence.json
node packages/evidence/dist/cli.js evidence.json

The core verifies the file before it sends it. The engine signer address to pin with --signer is the engineSigner field of GET /owner/v1/budgets/{id}/authority-head (also head.signer); take it from the operator over a channel you already trust, not from the file. See Evidence & disputes for the per-session evidence/1.0.0 bundle and its rendering.