Migrating evidence 1.0.0 → 1.4.0
An evidence file is a record of a budget whose signatures and digests can be checked offline: its signed records, vouchers, settlements and fee rows, with a manifest of content digests. A file on its own does not prove billing: the engine-signed records do not yet bind each stream's session key, so verification is complete only when paired with the on-chain settlement or the engine-signed payment records, and it is weakest in Control Mode and on the credit card rail, where there is no chain to check. Each schema is versioned from birth and additive: older files are still exported on request and still verify. The current schema is evidence/1.4.0 (Live).
Back to Changelog, versioning, deprecation and migration.
What each schema adds
| Schema | Adds |
|---|---|
evidence/1.0.0 | One session: the session view plus every signed artifact behind it (vouchers, allowance credentials, oracle attestations), settlement, refund and holdback records, and a manifest. It has no signed head, so it verifies with the notice "completeness not proven: no signed head". |
evidence/1.1.0 | One file per budget: the budget and its root mandate, every signed authority record in order, the engine-signed authority head (record count and last record hash), every stream with its vouchers, settlements, fee rows and revoke report, totals, and a manifest. The head makes completeness checkable: a dropped trailing record fails. |
evidence/1.2.0 | The payer's and payee's economic account ids and the payee identity level at admission. |
evidence/1.3.0 | The budget's signed payment records and payment head, per-stream consume rows with the attributed flag, and each hop's own-hop fields. |
evidence/1.3.1 | A signed own-hops flag (the core's own-hops setting at export, bound to the budget and both heads). When the flag says required, a hop without its delegator's signature or payee offer fails. Every payment record is checked against the stream's signed vouchers. The voucher domain names the contract version, and for contract v2 the asset's decimals, and vouchers are checked under it. |
evidence/1.4.0 | Each stream's delegatorKind (key, consented for a hosted top-up's consent root, or null), the signed terms statement (including the budget's funding mode), and optional sections for tasks, policies, recourse cases and the organisation. The verifier also requires canonical signatures and checks agent verification levels. |
Which verifiers read which schemas
Both offline verifiers read every schema from evidence/1.0.0 to evidence/1.4.0:
| Verifier | Package | Reads |
|---|---|---|
dynamo-verify (TypeScript) | evidence 1.4.0 | 1.0.0, 1.1.0, 1.2.0, 1.3.0, 1.3.1, 1.4.0 |
dynamoprotocol verify (Python) | dynamoprotocol 0.6.0 | 1.0.0, 1.1.0, 1.2.0, 1.3.0, 1.3.1, 1.4.0 |
Both read only the file and use no network. They share the same failure codes, and the repository checks that they agree on every shared vector:
cd "$DYNAMO_REPO"
pwd
make test-evidence
An older verifier cannot read a newer schema. A 1.3.x verifier never verifies a consent root, which is why a top-up budget exports only as 1.4.0.
Exporting a chosen schema
The owner API exports a budget's file at /owner/v1/budgets/{id}/evidence. Without ?schema= it answers evidence/1.1.0, unchanged since owner-api 1.5.0.
?schema= | Since owner-api | Needs |
|---|---|---|
1.1.0 (default) | 1.5.0 | nothing |
1.2.0 | 1.6.0 | nothing |
1.3.0, 1.3.1 | 1.7.0 | nothing |
1.4.0 | 1.8.0 | the request pinned with Dynamo-Version: 1.8.0 |
A budget funded by a hosted top-up, or one whose root is a human payment's consent, exports only as 1.4.0; any other schema is refused. A contract v2 budget exports only as 1.3.1 or 1.4.0. Under required own hops, a budget adopted without its owner's signed root hop intent is refused 1.3.1 and 1.4.0 (409 hop_unsigned for a client pinned at 1.8.0). The SDK's budget.exportEvidence() asks for the default schema.
Who has to act
- You keep older files: nothing to do. They still verify with the current verifiers.
- You want the newer facts (payments, own hops, terms, enterprise sections): export with
?schema=1.4.0, pinned at 1.8.0, and verify with a current verifier.
- You export top-up budgets: you must ask for
1.4.0. - You built your own verifier: add each new schema's checks before you accept that schema.
Fail closed on any schema id you do not know.
Steps
- Upgrade your verifier to the evidence 1.4.0 package or
dynamoprotocol0.6.0. - Export with
?schema=1.4.0andDynamo-Version: 1.8.0. - Verify offline. Pin the engine signer you expect with
--signer; without it the file's own
signer is used and printed so you can check it.
- Keep the older files you already hold; they stay valid.
Compatibility guarantees
- Every schema change is additive and gets a version bump and a CHANGELOG entry.
- Each new version leaves earlier exports and verdicts unchanged: every earlier vector gives the
same result.
- A tampered or missing element fails, with a named code.
- A passing verdict shows that the signatures and digests hold; on its own it does not prove
billing (see the top of this page).