Get started

Observation proof

Source

The path from one observation up to a signed root. The other half of the attestation.

text
GET /api/v1/observations/{id}/proof
bash
curl https://vitna.ai/api/v1/observations/1/proof

Path parameters

ParameterMeaning
idAn observation id. Digits only.

Response

json
{
  "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.

  1. leafHash = sha256(0x00 || canonicalLeaf), over the UTF-8 bytes of canonicalLeaf exactly as served. It must equal the leafHash here.
  2. Check that canonicalLeaf says what leaf says: leaf written as JSON with the keys in the order shown, no whitespace, amounts as the strings given, and bandFromTokens and bandToTokens left out where they are 0 and null, is canonicalLeaf byte for byte.
  3. Fold the path. For each step: sha256(0x01 || hash || running) when side is left, and sha256(0x01 || running || hash) when it is right, where hash is that step's own hash.
  4. The result must equal attestation.root, and attestation.statement must verify against attestation.publicKey with 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.stateWhenunattested
signedA root covers coversOnnull
pendingcoversOn is newestSignedDay or later, or no day has been signedNot signed yet, provable once its root is cut
unsignedcoversOn is before newestSignedDay and has no rootA 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

StatusCodeCause
404unknown_observationNot digits, or no such observation
503no_recordServing the snapshot. A proof cannot be built from it.

Caching

public, max-age=60, stale-while-revalidate=3600.