Get started
DocumentationConcepts

Attestation

Source

Each day's observations hashed into a Merkle root and signed with Ed25519, so that an edit made afterwards has to contradict something already published.

The mechanism

Every morning, the previous day's observations are hashed into a tree:

  • A leaf is sha256(0x00 || canonical JSON of the observation), with the field order fixed in platform/witness/attest.mjs.
  • An interior node is sha256(0x01 || left || right). An odd node is promoted unchanged.
  • The remaining root goes into a statement, and the statement is signed.

The two distinct prefix bytes matter: without them, a leaf hash and an interior hash are drawn from the same space, and a crafted "observation" could stand in for a subtree.

Reading the roots

bash
curl https://vitna.ai/api/v1/attestations

Newest first, each carrying the statement, the signature, and the public key that made it. The response also carries the algorithm, the statement prefix, and the three steps a check involves, served beside the data rather than linked from it.

Checking one figure

A root by itself is a claim. The path from a single figure to that root is what makes it checkable:

bash
curl https://vitna.ai/api/v1/observations/<id>/proof

That answers the leaf's own fields, its hash, its index, the sibling hashes up the tree, and the signed root the walk should reach. Rebuild the leaf, fold the path, compare, then verify the signature.

The response also carries computedRoot, which is what the endpoint calculates from the record as it stands right now. It should equal the signed root. Publishing both is what lets a reader see a disagreement rather than take Vitna's word that there is none.

What a signature proves

It proves the record for that day has not changed since it was signed.

Both sentences ship inside the API responses, because this is the claim most easily overstated by someone quoting the record.

Today is not yet signed

Roots are signed the following morning. A figure read today becomes provable tomorrow, and until then the proof endpoint answers with attestation: null and an unattested string explaining it, rather than failing.

A day older than the newest signed day that still has no root is a different case: a gap, not a wait. The proof says that instead, names the newest signed day, and promises nothing. See a day with no root.

Doing it end to end

Verify a figure yourself walks the whole path with the commands, alongside the separate check against the provider document.

Verifying the whole chain

bash
npm run witness:attest -- --verify

Rechecks every root ever signed. --new-key prints a keypair and touches no database.