Observation proof
The path from one observation up to a signed root. The other half of the attestation.
GET /api/v1/observations/{id}/proofcurl https://vitna.ai/api/v1/observations/1/proofPath parameters
| Parameter | Meaning |
|---|---|
id | An observation id. Digits only. |
Response
{
"leaf": {
"id": "445937", "fetchId": "20411", "sourceId": "...", "contentSha256": "...",
"skuId": "...", "dimensionId": "input_per_mtok", "amountUsd": "15.000000",
"observedAt": "...", "derived": false, "derivation": null, "locator": "...", "parserVersion": 3,
"bandFromTokens": 0, "bandToTokens": null
},
"canonicalLeaf": "{\"id\":\"445937\",\"fetchId\":\"20411\",...}",
"leafHash": "...",
"leafIndex": 417,
"coversOn": "2026-08-22",
"leafCount": 918,
"algorithm": "...",
"statementPrefix": "...",
"proof": [ { "side": "left", "hash": "..." } ],
"computedRoot": "...",
"attestation": { "root": "...", "statement": "...", "signature": "...", "publicKey": "..." },
"signedDay": { "state": "signed", "newestSignedDay": "2026-09-12" },
"unattested": null,
"howToVerify": [ ... ],
"proves": "This observation was among the ones the signed root covers for that day.",
"doesNotProve": "That the provider published the price. ...",
"meta": { "generatedAt": "...", "source": "database", "algorithm": "..." }
}canonicalLeaf is the exact string the leaf hash is computed over, and leaf is the same fields as an object, in the same order. The one difference is the band. leaf carries bandFromTokens and bandToTokens on every figure, as 0 and null on a figure priced once. canonicalLeaf carries them only on a figure priced in a context band, in that order, after parserVersion.
The check
Walked end to end, with the document check beside it, in Verify a figure yourself.
leafHash = sha256(0x00 || canonicalLeaf), over the UTF-8 bytes ofcanonicalLeafexactly as served. It must equal theleafHashhere.- Check that
canonicalLeafsays whatleafsays:leafwritten as JSON with the keys in the order shown, no whitespace, amounts as the strings given, andbandFromTokensandbandToTokensleft out where they are0andnull, iscanonicalLeafbyte for byte. - Fold the path. For each step:
sha256(0x01 || hash || running)whensideisleft, andsha256(0x01 || running || hash)when it isright, wherehashis that step's ownhash. - The result must equal
attestation.root, andattestation.statementmust verify againstattestation.publicKeywith Ed25519.
Deliberately short. A verification nobody can reimplement in an afternoon is one nobody will.
Nothing here has to be trusted
A verifier rebuilds the leaf from the fields, hashes it, walks the path, and compares against a root inside a statement that somebody else's copy of the signature also covers. If this endpoint lied about any of it, the arithmetic would stop agreeing.
computedRoot against attestation.root
computedRoot is what the endpoint calculates from the record as it stands now. attestation.root is what was signed.
They should be equal. Publishing both is what lets a reader see a disagreement rather than take Vitna's word that there is none.
A day with no root
Roots are signed the morning after a day closes. When no root covers coversOn, attestation is null and the endpoint still answers 200, because a missing root is a true statement about the record and not an error. It is one of two different statements, though, and signedDay.state says which. unattested says the same thing as a sentence.
signedDay.state | When | unattested |
|---|---|---|
signed | A root covers coversOn | null |
pending | coversOn is newestSignedDay or later, or no day has been signed | Not signed yet, provable once its root is cut |
unsigned | coversOn is before newestSignedDay and has no root | A gap, naming the newest signed day |
newestSignedDay is the newest day the record has signed, or null if it has signed none. The state is decided against it and never against a clock, so the same record gives the same answer whenever it is asked.
Pending is the ordinary absence. An observation from today sits in a day whose root has not been cut, and a figure read today is provable tomorrow.
Unsigned is a gap. A later day has been signed and this one has not, and the nightly run signs only the day before, so the day is not waiting its turn. The sentence names the newest signed day and makes no promise about this one. The document the figure was read from, named by contentSha256, is a separate check and does not need a root.
Errors
| Status | Code | Cause |
|---|---|---|
| 404 | unknown_observation | Not digits, or no such observation |
| 503 | no_record | Serving the snapshot. A proof cannot be built from it. |
Caching
public, max-age=60, stale-while-revalidate=3600.
