> Source: https://vitna.ai/docs/verify-a-figure
> Raw Markdown: https://vitna.ai/docs/verify-a-figure.md
> Corpus index: https://vitna.ai/llms.txt

# Verify a figure yourself

The whole claim of this record is that you do not have to trust it. This page is
that claim carried out, end to end, with nothing taken on faith.

There are two independent checks, and they answer different questions. Neither
requires a key and neither asks Vitna to vouch for anything.

| Check | Answers |
|---|---|
| [The document](#the-document) | Did the provider publish this price? |
| [The signed record](#the-signed-record) | Has Vitna changed this since it was recorded? |

They are separate on purpose. A signature says nothing about a provider, and a
provider's page says nothing about whether Vitna edited the record afterwards.
Together they close both halves.

## Start with a figure

Take any row off the tape:

```bash
curl "https://vitna.ai/api/v1/markets/model/tape" | head -40
```

Every row carries the three things the checks need:

| Field | Used by |
|---|---|
| `sourceUrl` | The document check |
| `evidenceSha256` | Both |
| `observationId` | The signed-record check |

All three describe one read, the one that last confirmed this price, so the two
checks are checks of the same thing rather than of two neighbouring facts.

## The document

The strongest check, and the simplest: fetch the provider's page yourself and
see whether it hashes to what the record says it read.

First ask the record what it fetched and when:

```bash
curl "https://vitna.ai/api/v1/evidence/<evidenceSha256>"
```

That answers publicly, with no token: the URL fetched, the fetch time, the HTTP
status, the response headers, the user agent, the adapter, the parser version,
the byte count, and every later read that found the same bytes.

Now fetch the same URL and hash it:

```bash
curl -s "<the archived url>" | sha256sum
```

If the provider has not changed the page since that fetch, your hash equals
`evidenceSha256` and the figure is traceable to bytes the provider served.

> [!NOTE]
> A different hash is the ordinary case on a page that has since changed, and it
> is not a failure. It means the document moved on. What the archive records is
> what Vitna read at a stated moment, which is why the fetch time is published
> beside the hash.

The archived copy itself is behind a token, because it is a third party's page
and republishing it is a question this record does not need to answer. The hash,
the URL and the time are public, and those are what a check needs.

## The signed record

Every day of observations is hashed into a Merkle tree and the root is signed
with Ed25519. Checking one figure means walking from its leaf to that root, then
verifying the signature over it.

Take the `observationId` off the row you started from and ask for its proof:

```bash
curl "https://vitna.ai/api/v1/observations/<observationId>/proof"
```

That is the whole of the step. The rest of this section is what the answer
contains and how to check it.

If you would rather start from a day than from a figure, the published roots
carry the id range each one covers:

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

Each row carries `coversOn`, the `root`, the `statement` the signature covers,
the `signature`, the `publicKey`, the `leafCount`, and the range of observation
ids the day covers as `firstObservationId` and `lastObservationId`. Any id in
that range belongs to that day's tree.

Either way, the proof response carries the leaf's own fields as `leaf`, the
exact string its hash is computed over as `canonicalLeaf`, its hash, its index,
the sibling hashes up the tree as `proof`, the root the walk should reach, and
the signed attestation.

### The four steps

1. `leafHash = sha256(0x00 || canonicalLeaf)`, over the UTF-8 bytes of
   `canonicalLeaf` exactly as served. It must equal the `leafHash` given.
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. A figure priced once is hashed without its
   band; a figure priced in a context band is hashed with both.
3. Fold the path. Each step carries a `side` and a `hash`. Compute
   `sha256(0x01 || hash || running)` when `side` is `left`, and
   `sha256(0x01 || running || hash)` when it is `right`. An odd node is promoted
   unchanged, so it has no step.
4. The result must equal `attestation.root`, and `attestation.statement` must
   verify against `attestation.publicKey` with Ed25519.

The algorithm is named in the response as `sha256-merkle-rfc6962`, and the
statement carries the prefix `vitna-attestation-v1` so a routing config
signature can never be read as an attestation.

### Why the two prefix bytes

A leaf is hashed under `0x00` and an interior node under `0x01`. Without the
distinction the two are drawn from the same space, and a crafted leaf could
stand in for a whole subtree. This is the standard defence and it is why the
algorithm string names RFC 6962.

### Check the key, separately

A valid signature proves whoever holds that key signed the statement. It does
not prove the key is Vitna's, and no amount of arithmetic inside one response
can establish that.

Compare `publicKey` against the one published on `/witness` and on
`/api/v1/attestations`, ideally from a copy you obtained on a different day. The
mechanism is that the statement was in the open at the time, so an edit made
later has to contradict something already published.

### Two roots, published together

The proof also carries `computedRoot`, which is what the endpoint calculates
from the record as it stands right now, beside `attestation.root`, which is what
was signed. They should be equal.

Publishing both is what lets you see a disagreement rather than take the
record's word that there is none.

## The one case where the path stops

`observationId` is `null` when an instance is serving a committed snapshot
written before the ids were carried. There is nothing to walk from, and the row
says so rather than offering an id that would prove something else.

`vitna.ai` serves the record, so this affects local checkouts and any mirror
still running an older snapshot. The document check has no such gap and works
from any tape row.

## Quoting a figure somewhere else

Every figure on every board carries a `cite` mark, and it leads to a permanent
dated citation of that figure in the three shapes people paste: a footnote, a
short reference for a slide, and a schedule line for a contract.
[Cite a figure](citing-a-figure.md) is what those are, and how long the urls
keep resolving.

The two checks above are what a citation is worth. A quoted figure that nobody
can take back to a document is a number in a slide; this page is why one here
is not.

## What neither check proves

**That the price is a good deal, or one you could get.** The record holds
published list prices. Negotiated rates, committed-spend discounts and private
agreements are invisible to it.

**That Vitna read the page correctly.** The hash proves which bytes were read.
The `locator` and `parserVersion` on the observation say where in the document
the parser looked and which version looked there, which is what makes a misread
arguable against an archived document rather than a matter of opinion.

## Doing it in bulk

```bash
npm run witness:attest -- --verify
```

Rechecks every root ever signed. Because the inputs are append-only and the rule
has no free parameters, an independent implementation reading the same public
endpoints should reach the same answer, and disagreeing with this command is the
interesting result.
