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

SchemaAdds
evidence/1.0.0One 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.0One 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.0The payer's and payee's economic account ids and the payee identity level at admission.
evidence/1.3.0The 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.1A 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.0Each 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:

VerifierPackageReads
dynamo-verify (TypeScript)evidence 1.4.01.0.0, 1.1.0, 1.2.0, 1.3.0, 1.3.1, 1.4.0
dynamoprotocol verify (Python)dynamoprotocol 0.6.01.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-apiNeeds
1.1.0 (default)1.5.0nothing
1.2.01.6.0nothing
1.3.0, 1.3.11.7.0nothing
1.4.01.8.0the 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

?schema=1.4.0, pinned at 1.8.0, and verify with a current verifier.

Fail closed on any schema id you do not know.

Steps

  1. Upgrade your verifier to the evidence 1.4.0 package or dynamoprotocol 0.6.0.
  2. Export with ?schema=1.4.0 and Dynamo-Version: 1.8.0.
  3. 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.

  1. Keep the older files you already hold; they stay valid.

Compatibility guarantees

same result.

billing (see the top of this page).