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
| Code | Meaning |
|---|---|
schema | not an evidence file, unsupported schema, or a field missing, of the wrong type or not expected |
canonical_form | a value is not in canonical form |
manifest | an element digest or the bundle digest does not match the file |
signature | a record, voucher or credential whose hash does not recompute from its content, or whose signature does not recover to the expected signer |
foreign_record | a record belongs to another budget or funder |
hash_link | a record's parent hash, ordering or stream binding does not match the chain |
depth_ceiling | a hop sits deeper than the system ceiling or its mandate allows |
narrowing_category | a hop declares a category outside its delegator's mandate |
narrowing_widen | a hop, amendment or reported cap widens its delegator's authority |
head_missing | a 1.1.0 file carries no signed head |
head_signature | the head is malformed or not signed by the engine signer |
head_count | the head's record count differs from the records in the file |
head_last_hash | the head's last record hash differs from the file's last record |
revoked_uncovered | a stream is reported revoked with no covering revoke record |
voucher_sum | reported totals do not equal the signed vouchers and settlement records |
own_hops_flag | a 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_voucher | a 1.3.1 payment record names no signed voucher of its stream, or its cumulative amount is not that voucher's |
voucher_domain | a 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_scale | a 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:
- the "Download evidence" button on the budget page of the
GET /owner/v1/budgets/{id}/evidencewith the owner token (?schema=
picks the schema; see below);
- TypeScript:
await budget.exportEvidence("evidence.json")in
@dynamoprotocol/sdk 3.0 and later (the default schema only);
- Python:
await budget.export_evidence("evidence.json")(optional
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
| Budget | Ask for | Why |
|---|---|---|
| Control Mode or credit card | the default (evidence/1.1.0) or any listed schema | Every schema covers the whole budget |
| Stablecoin, contract version 1 | ?schema=1.3.1 | 1.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.0 | 1.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.