Knowledge Base

Browse the concepts behind Truestamp. Follow the links between concepts, or search across everything.

Verify a Proof

How to verify a Truestamp proof on the web, the APIs or the CLI - the fifteen steps of the specification, from the envelope, key binding and signature through every recomputation, the chain and entropy reads and the submission window, to the expected hash, the report rows, codes and labels.

Open resource

Overview

A Truestamp proof is one signed JSON document that ties your data to a Truestamp block, the block to an epoch, and the epoch’s hash to a transaction on Stellar, Bitcoin or both. Verifying a proof means checking, for yourself, that the document is intact, that Truestamp signed it, and that every hash it compares offline is one it recomputes from the records the proof carries: the claims to the item hash, the item hash up the block’s Merkle tree, the block’s record to its hash, and the block hash up the epoch’s tree to the epoch hash written on chain. The chain pointers the proof carries, such as a Stellar transaction’s hash or a Bitcoin entropy block’s hash, are not recomputed: they say where to read, and support a result only after that read. An online run then reads the public chains and entropy sources the proof names, and draws the submission window from what they answer: a submitted-before edge from the chains, and, for an item, a submitted-after edge from the public records it named at submission.

Every Truestamp verifier makes the steps of the Truestamp verification specification (SPEC.md, in the truestamp-verification repository) in the same order. Truestamp’s own servers verify with the reference verifier, truestamp-verify-ex, in the role of Truestamp’s own verifier; the truestamp command-line client and any verifier someone else writes are external verifiers. The steps are the same in every role; what differs is which keyring binds the signing key (see Ed25519 signatures):

  • Truestamp’s own verifier binds against its key chain, the keys its own blocks introduce, and never against a keyring a caller supplies.
  • An external verifier online reads Truestamp’s keyring at https://www.truestamp.com/.well-known/keyring.json in each run, and that keyring replaces the one built into it. Offline it uses the built-in keyring, the compiled pin. A keyring of its own, or keyless mode, is used only when asked for.

Offline, a run checks everything the document holds and reads nothing: it can show that the proof is intact and signed by a key in the keyring, but it draws no window, so its best verdict is internally-consistent. Only an online run, which reads Stellar, a Bitcoin node or explorer and NIST’s beacon (and, for an external verifier, Truestamp’s keyring), can reach verified.

You can verify a proof four ways: the public verify web page, the JSON:API, the GraphQL API, or the command-line client. When Truestamp’s server confirms against a public source, the answer may be one it retrieved earlier: a settled Stellar transaction or a published NIST pulse never changes, so its answer is reused rather than asked for again on every view, and each result names the source that answered and when it was retrieved. This guide walks through what each step checks, how to run it, and how to read the result. For the meaning of every member of a proof, see the proof bundle format.

Before you begin

You need a proof bundle. Proofs are generated on demand for a committed subject (an item, an entropy observation, or a block); there is nothing to download until the subject reaches its committed state. There are two ways to get one:

  • Download it in the app. The pages for an item, a block, a beacon, and an entropy observation each offer a proof download, and so does the verify page once it has verified a subject. Every one hands over the signed document Truestamp serves, after its own verifier has checked it, byte for byte, in one JSON file: an item’s is named by its item code, as <CODE>.proof.json, and every other proof by its subject’s id, as <id>.proof.json. The verify page sends the very document it verified, with no second request. Beside the download, the page lists what the file carries: the Stellar commitment, the Bitcoin commitment, and the record of how the signing key was introduced. While Bitcoin has recorded the subject’s block but not yet deeply enough to be final, the file carries no Bitcoin commitment, and the page warns that a later download will include it. A redacted item’s proof can no longer be downloaded, so the item page’s redaction steps say so before you redact. Once you download the file there, they also list what it carries, and while its Bitcoin commitment is not final yet they warn that a file downloaded before the redaction will never carry it. The redaction happens only once that download is made, and so does the deletion of an item that is still committed. If the item is redacted or scheduled for deletion while its page is open, the page stops listing what an earlier download carries.

  • Generate it over the API. Send an authenticated request to the generate endpoint, declaring the subject type (there is no auto-detection):

    curl -X POST https://www.truestamp.com/api/json/proof/generate \
    -H "Authorization: Bearer $API_KEY" \
    -H "Content-Type: application/vnd.api+json" \
    -d '{"data": {"id": "<CODE>", "type": "item"}}'

    type is one of item, entropy_nist, entropy_stellar, entropy_bitcoin, block, or beacon; id is the subject’s UUIDv7, and for an item also its item code or its item_hash. The proof arrives under a result key as a string, the signed document’s exact bytes, the same document the app downloads; hand it onward exactly as produced, never re-encoded, reordered, truncated, or reformatted. The GraphQL equivalent is the generateProof query, which takes the same arguments as flat field arguments and answers with a { result, errors } envelope, the proof’s text under result: query { generateProof(id: "<CODE>", type: "item") { result errors { code message } } }. A failure (an uncommitted subject, a rate-limit refusal) is reported in that field’s own errors, so it never nulls other fields in the same document. Generation always requires an authenticated caller (an API key or OAuth bearer token) with access to the subject; because generation reads and writes nothing, an OAuth token needs only the api:read scope. GET /api/json/proof/raw/<type>/<id> answers the same bytes as the body, ready to save as the file.

    An optional constructions argument says how the proof carries the constructions text that defines every value it recomputes: full (the default) carries the text, reference a link to its published copy, and none neither. Each is its own signed document, and the verdict never depends on it. Every proof of an item carries every witness its fingerprint names; there is no smaller variant.

A proof is one JSON document: hash fields are hex strings, and keys, signatures and Merkle paths follow the proof bundle format. Its formatting is free: a pretty-printed copy of the same document verifies alike. The verify web page and the APIs take the proof’s text.

If you kept the SHA-256 of the file you timestamped (items only), you can supply it as the expected hash and have the verifier confirm the proof covers exactly that data.

To skip the chain and source reads over the API, pass offline (offline=true on the raw verify route, POST /api/json/proof/raw/verify, which takes the file’s bytes as its body). Without it, the verifier also reads the public chains to confirm each commitment, and the public sources behind any carried witness and behind an entropy subject.

Steps

A verifier runs fifteen steps, numbered 0 to 14, in this order. When you use the verify page or an API you do not run them by hand, but knowing them tells you exactly what a result means. A run that passes steps 0 to 3 gives a report, whose rows say what each check found: each row is {code, message, part, status, step, values}, where part is a JSON Pointer into the proof (or null for a row about no single member), status is pass, fail, skip, warn or info, and code names the reason whenever the status is not pass. Rows come in step order, and a skip is never a failure.

Step Name What it checks
0 CONFIGURATION the verifier’s environment, its network pins and sources, and the keyring that governs, before the file is read
1 READ the file is at most 262,144 octets
2 PARSE the file is one strict JSON text
3 ENVELOPE the document is the two-member envelope, and its key’s bytes are sound
4 ENVIRONMENT the environment marker against the verifier’s own environment
5 KEY_BINDING the signing key against the keyring that governs
6 SIGNATURE the signature over proof_hash
7 SHAPE format, version, the closed schema and the constructions text
8 POLICY every network against the verifier’s pins
9 DERIVE every recomputation and every link, offline
10 CHAIN the reads of Stellar and Bitcoin for each commitment
11 SOURCES the reads of NIST, Stellar and Bitcoin for each entropy object
12 WINDOW the submission window
13 EXPECTED_HASH your file’s hash against the claims’ hash, when you give one
14 VERDICT the label, the attribution and the window

0 to 3. Read the file

Before anything in the file is read, the verifier fixes its configuration: its environment (production, or Truestamp’s dev, staging or test), the networks it reads for each chain, and the keyring that governs. A configuration that cannot work, such as an online run with no source for a network it must read, stops the run as configuration_error.

The next three steps are hard rejections: a file that fails one gets an error and no report at all.

  • READ. A file of more than 262,144 octets is input_too_large.
  • PARSE. The file must be exactly one JSON text in UTF-8 with no byte order mark, no invalid UTF-8 and no escaped lone surrogate, no object with the same member name twice, no number that is an integer of magnitude above 2^53 - 1 and below 10^21 or that overflows a binary64, and no nesting deeper than 32 levels, the document counting as the first. Anything else is malformed_json, with a sub_reason naming the rule: syntax, invalid_utf8, lone_surrogate, duplicate_name, number or depth.
  • ENVELOPE. The document must be an object of exactly proof and signature; proof an object; signature an object of exactly alg, public_key and value; alg the string truestamp-ed25519-sha256-jcs; public_key a canonical 43-character base64url key whose bytes pass the key checks; and value a canonical 86-character base64url signature. The first that fails is invalid_envelope, with that check’s name as the sub_reason (document, proof, signature, alg, public_key or value), and the message “This file is not a Truestamp proof.” A document in any other layout fails here, whatever it resembles.

4 to 6. The gate: environment, key and signature

Nothing in the proof but its environment member is interpreted until the key is bound and the signature verified.

  • ENVIRONMENT. A production verifier requires no environment member; a verifier of Truestamp’s dev, staging or test environment requires the member to name its own environment. Anything else is environment_mismatch. A staging proof under a production verifier fails here, with the message that it was issued by Truestamp’s staging environment, which is for testing.
  • KEY_BINDING. The 32 bytes of signature.public_key must equal a key in the keyring that governs, active or retired. No key id the proof carries is read. A key not in it is key_binding_failed; a keyring that cannot be used (Truestamp’s key chain not verified, or an external verifier’s online keyring read failed) is keyring_unavailable whatever the key; keyless mode, which an external verifier enters only on request, is skip key_binding_not_performed.
  • SIGNATURE. The verifier computes proof_hash = SHA-256(0x50 || JCS(proof)) and checks the signature over its 32 bytes by the strict Ed25519 rule, else signature_invalid.

A failure at any of these ends the run: the label is failed, the attribution none, and every later step up to EXPECTED_HASH reports one row, skip prior_failure. Nothing is looked up anywhere, because everything else in such a document is an unsigned claim. Truestamp’s own verifier checks the key and the signature first, and stops if either fails.

7. Check the shape

  • format must be "truestamp-proof", else unsupported_format, and version must be 1, else unsupported_version.
  • The proof must satisfy the specification’s closed schema, else shape_invalid at the member that is missing, extra, forbidden for the type or malformed. The schema holds the type registry and every member set, pattern, cap and literal: lowercase hex everywhere but NIST’s outputValue, canonical base64url, no null, one or two commitment entries, the genesis rules, and, in every block record, a leaf_count of 0 exactly when the merkle_root is the empty root.
  • In an item, witnesses must have exactly the names of witness_hashes; every time must be the one spelling its own parse gives; and a constructions member must be a text or a reference URL whose digest the verifier accepts, else construction_mismatch. No verifier interprets the text or fetches the URL.

A failure at SHAPE ends the run as a failure at the gate does. When SHAPE passes, the report takes the proof’s type and its subject’s id.

8. Check every network against the pins

Each network the proof carries, in every commitment entry, every Stellar or Bitcoin entropy object and every genesis object, must equal the verifier’s pin for that chain or source, else network_mismatch. A production verifier pins Stellar public and Bitcoin mainnet; the document never chooses which network is read. A failure here does not end the run, but no chain or source is read after it.

9. Recompute every compared hash, offline

DERIVE recomputes each value the proof declares that a check compares, from the record it carries, compares the two, and checks every link. Chain pointers are not among those values; the reads of steps 10 and 11 use them. It makes every check and does not stop at a failure. A mismatch is derivation_mismatch unless its check names another code.

  • Subject hashes. For an item: claims_hash = SHA-256(0x10 || JCS(claims)) and item_hash = SHA-256(0x11 || JCS(record)). For an entropy subject and each beacon observation: entropy_hash = SHA-256(0x20 || JCS(entropy object)) and observation_hash = SHA-256(0x21 || JCS(record)).
  • Block nodes. For every block node, block_hash = SHA-256(0x31 || JCS(record)); for the genesis block, its height is 0 and its previous_block_hash is SHA-256(0x30 || JCS(genesis object)). Every key event a block carries is checked too (its key’s bytes, its ids, and a rotation’s place and handover signature), each failure key_event_mismatch.
  • Epochs. For every commitment entry, epoch_hash = SHA-256(0x40 || JCS(epoch record)).
  • Bitcoin evidence. For every Bitcoin entry: the raw transaction is well formed, with exactly one output script beginning 0x6a, that script exactly 0x6a 0x20 followed by the 32 bytes of the recomputed epoch_hash; transaction_hash is the transaction’s double SHA-256, byte-reversed; the txoutproof is a well-formed merkleblock that matches exactly that one transaction under its header’s Merkle root; the header meets the target its own difficulty bits encode; and header_hash, header_merkle_root and header_time equal what the header holds. A structure that is not well formed is bitcoin_evidence_invalid.
  • Inclusion. Every inclusion proof walks from its recomputed leaf to its record’s merkle_root, and its tree_size equals that record’s leaf_count: the subject’s or each observation’s into /block/record, and each commitment entry’s from the recomputed block_hash into its epoch record. Every walk starts from a recomputed hash, never a declared one; see inclusion proofs.
  • Witnesses. In an item, witness_hashes.block equals the recomputed block_hash of the witness block, and each witness_hashes.entropy_X the recomputed entropy_hash of its entropy object.
  • Order. The witness block’s height must be below the height of the item’s block, and each Stellar entropy object’s sequence must be below the top-level Stellar entry’s ledger, and each Bitcoin entropy object’s height at most the top-level Bitcoin entry’s height, on the same network. A failure is ordering_violation.
  • The signing key event. When the proof carries one, its event must introduce the proof’s own key, else key_event_mismatch. The row passes when the run attributes the proof to Truestamp, and is info not_attributable otherwise. It shows where the key came from; it never binds the key.

Nothing here is opaque: every hash a verifier compares is one it computed from bytes in hand.

10. Read the chains

CHAIN and SOURCES are the only steps that read anything outside the document, and they run only when the run is online and no row so far has failed. Otherwise each of their rows is skip offline, whose message names the read that would confirm it, or skip prior_failure after a failure. Each commitment entry, at the top level and under signing_key_event, gets one row:

  • Stellar: read the transaction by its hash on the pinned network. It must be successful, its memo type must be hash with the memo equal to the recomputed epoch_hash, and it must be in the ledger the entry names, else chain_mismatch. For a top-level entry, the ledger’s closed_at is a candidate for the submitted-before edge. A transaction the source does not hold is a skip, not_yet_indexed for a ledger within 60 ledgers of the source’s latest, or not_held_by_source for history the source does not keep, unless the source holds that ledger without the transaction, which fails.
  • Bitcoin: read the tip. A height above it is skip not_yet_indexed, and a tip below height + 10 is skip chain_not_final. Otherwise the best-chain block at the entry’s height must have the recomputed header_hash and the txoutproof’s transaction count, else chain_mismatch. That read is what places the carried header on the best chain: a header that meets only its own target costs almost nothing to make, so a Bitcoin entry supports no pass without it. For a top-level entry, the median time past of the best-chain block at height + 10 is a candidate for the submitted-before edge.
  • The genesis object: the best-chain Bitcoin block at its height must be the one it names.

CHAIN ends with one more row, at /signing_key_event, summing up the signing key event’s reads. A source that does not answer, is rate-limited or answers in a form the read cannot use gives skip source_unreachable; only a contradiction fails.

11. Read the entropy sources

Each entropy object whose hash DERIVE matched, an item’s witnesses, an entropy subject or a beacon’s observations, is read back from its source and must agree, else entropy_mismatch:

Source Read Must equal Candidate for the submitted-after edge
NIST the pulse at chainIndex and pulseIndex outputValue, timeStamp the pulse’s timeStamp
Stellar the ledger at sequence hash, closed_at the ledger’s closed_at
Bitcoin the block whose hash is hash height, and time against the header’s time that block’s median time past

A pass establishes that the value exists in the source’s records, not that it was fresh when Truestamp captured it: a source that freezes, as the NIST beacon can by republishing its last pulse during a US budget lapse, yields a genuine, re-fetchable, stale value. That is why three independent sources are captured.

12. Draw the submission window

A verifier draws both edges only from reads it made in this run, never from a time the proof carries: not header_time, not an entropy payload’s time, not the time inside an id, and not a claimed timestamp.

  • Submitted before is the earliest candidate among the top-level commitment rows that passed: a Stellar ledger’s close time, or the median time past of the Bitcoin block 10 above the transaction’s, which assumes at least 6 of those 10 blocks carry honest times. The signing key event’s commitments never give one.
  • Submitted after is the latest candidate among the entropy rows that passed: a NIST pulse time, a Stellar ledger close time, or a Bitcoin witness block’s median time past. The item’s witness block gives none, since no public source holds its time. A block proof has no submitted-after edge, and neither does an item with no entropy witness or a beacon with no observations.

The WINDOW row is skip prior_failure after any failure, fail window_inverted when the submitted-after edge is later than the submitted-before edge, info window_not_established when no submitted-before edge was drawn (always, offline), and otherwise pass. When the window passes and the time inside the subject’s id, a time Truestamp recorded, falls outside it, one more row, info recorded_time_outside_window, says so and changes no label. Each edge in the report gives its instant, its basis (stellar_ledger_close_read, bitcoin_median_time_read or nist_pulse_time_read), its stated assumption, the commitment entry or entropy object it came from, and each source it rests on, with whether that answer came from a cache and when it was fetched.

13. Compare against the file hash you hold

This step compares a hash you supply, the expected_hash argument, with the file hash an item proof’s claims record (claims.hash, under its hash_type). It is the only step that reads a member of the claims. The report’s EXPECTED_HASH row has one of these outcomes:

  • You supply nothing. The row is skip expected_hash_not_checked. That is not a failure, and the proof itself is still sound: your file was simply not compared.
  • You supply a hash that equals the recorded one. The row passes. Your value is lowercased first, and it must be hex of the length the hash_type gives (32 for md5, 40 for sha1, 56 for sha224 and sha3_224, 64 for sha256, sha3_256 and blake2s, 96 for sha384 and sha3_384, 128 for sha512, sha3_512 and blake2b). When the hash_type is md5 or sha1, whose collisions are practical, a match is warn expected_hash_weak_algorithm instead, and the label does not change.
  • Anything else fails as expected_hash_mismatch, and the row says why: the two hashes differ, your value is not hex of the length the hash_type gives, or the proof has no hash of a listed type to compare (it is not an item, or its claims hold no file hash, as when the claims are themselves the timestamped data). Supply expected_hash only for an item proof that records a file hash.

After a failure at the gate or at SHAPE, the row is skip prior_failure: the hash recorded in such a document is only what its builder wrote, and a match would vouch for your file against a document no one is known to have signed. When the attribution is not Truestamp, the row’s message says that the match is against a document not attributed to Truestamp. Read the row’s code along with its status, so “not checked” (expected_hash_not_checked) is never misread as a mismatch (expected_hash_mismatch).

14. The verdict

The report’s label is the first of these that applies:

label When
failed any row is fail; the report’s code is the first failing step’s
unattributed keyless mode: the proof is intact under the key it carries, which no keyring checked, so anyone could have made it
supplied-keyring the key is in a keyring the operator supplied; this says nothing about Truestamp
internally-consistent the proof is intact and signed by Truestamp, but no read in this run established its submitted-before edge
verified the proof is intact, signed by Truestamp, and places its subject’s submission before an instant read from a public chain in this run

attribution says whose key signed the proof: truestamp (bound under Truestamp’s key chain, the keyring read from www.truestamp.com in the run, or the compiled pin), keyring:<d> for a supplied keyring, unattributed in keyless mode, or none when the gate failed. trust_root is an object {digest, kind, location} for the keyring that governed: kind is key_chain, current_keyring, compiled_pin, supplied_keyring or none, digest is the lowercase hex SHA-256 of the keyring file’s bytes or null where no keyring file was used, and location says where the keys came from, a URL or a file, or is null. On Truestamp’s own verifier it is kind key_chain, with digest and location null. Attribution and window are separate statements: the window says when the subject was submitted, never who attested it. Truestamp’s own verifier gives only failed, internally-consistent and verified. A command-line verifier also exits with a code for its label: 0 only for verified, 7 for internally-consistent, 6 for supplied-keyring, 5 for unattributed and 3 for failed; a run that gives no verdict exits 8 for configuration_error and 4 for any other bare rejection.

What a real run reports

For an item proof that carries all four witnesses and a signing key event, checked by Truestamp’s own verifier:

  • Offline: every row through DERIVE passes (about sixty of them); every CHAIN and SOURCES row is skip offline; WINDOW is info window_not_established; the label is internally-consistent, with no edges.
  • Online: the same rows pass, then every CHAIN row (each commitment entry, the genesis object, and the signing key event’s summary) and every SOURCES row passes; WINDOW passes; the label is verified, with a submitted-before edge from the Stellar ledger that holds the epoch’s transaction and a submitted-after edge from the latest witness its source confirmed.
  • With your file’s hash: EXPECTED_HASH passes on a match. A hash that differs fails expected_hash_mismatch, and the label becomes failed even though the proof itself is sound, because the file you hold is not the one it covers.

A block proof reports no SOURCES rows and has no submitted-after edge; an entropy proof’s submitted-after edge comes from its own subject; a beacon proof’s from its observations.

Verify

Pick whichever surface fits your situation. The three surfaces below run Truestamp’s own verifier through the steps above; the command-line client runs the same steps as an external verifier, offline or online.

Verify on the web

The public verify page at https://www.truestamp.com/verify is the no-tooling path. A shareable per-subject link takes the form https://www.truestamp.com/verify/<type>/<id>, where <type> is one of item, entropy_nist, entropy_stellar, entropy_bitcoin, block, or beacon. For an item, <id> can be its ID, its item code in upper or lower case and with or without separators, or its item hash, and the page then moves to the item’s canonical link, https://www.truestamp.com/verify/item/<CODE>.

An item’s verify page shows its item code under the title, in four groups of four for reading, though a copy or a double-click takes the 16 characters with no separator, with buttons that copy the code and the page’s link, and the line “Computed from this item’s hash. Anyone holding its proof can check it.”; like every code, it is a name and is never shown with a status.

For entropy there is also a bare https://www.truestamp.com/verify/entropy/<id> convenience alias: it accepts any of the three entropy sources for that id, where the strict entropy_nist, entropy_stellar, and entropy_bitcoin types each require the id to be that specific source.

The page verifies the subject’s signed proof once with Truestamp’s own verifier, reading the public chains the proof names in this run, within one minute for the whole run, and shows what that run found. The headline gives its label (Verified, Internally consistent, or Failed), marked “Checked by Truestamp’s server”; on a server that is not production (staging, dev or test), the environment beside it with what that means for the proof, such as “This proof was issued by Truestamp’s staging environment, which is for testing. It is not a production proof.”; that environment is also shown beside the verdict at the top of the page and in the page’s title and description.

Then comes whom the signature is attributed to, and, as a separate statement, the submission window: its “Submitted after” and “Submitted before” edges, each an instant read from a public chain or source. Each edge names every source it rests on, “Read from in this run” when the answer was read live and “Read from at

Every other time on the page, such as an observation’s own time or when Truestamp captured it, or a block’s, and the subject’s ids (an item’s id and the time recorded in it, a block’s previous block hash), sits under “Recorded by Truestamp, not confirmed in this run” when the run attributes the proof to Truestamp, and under “Declared by the signer (not attributed to Truestamp)” otherwise, never with a status. Those times appear only once the run has a report; until then the ids are shown only as the subject’s identity. The raw entropy data and the proof’s own text are shown as the raw data they are, and the earliest submission of the same file, another item’s time from Truestamp’s records, has its own label, “Recorded by Truestamp when that earlier item was submitted”. It links to that item’s verify page, by its item code, only when the page can open it: a public item, or for a signed-in viewer an item of the current team. Otherwise it shows only that item’s name and time, with no link and no code.

Below the headline, every check of the run is listed with its pass, fail, skip, warn, or info status and its reason code, on cards for the signature and key, each chain the proof was committed on (Stellar’s memo hash and Bitcoin’s OP_RETURN shown as the epoch hash the run recomputed, and the source policy and each source’s outcome: for a source that answered, whether the answer came from the cache, and for one that did not, its status and code), each entropy source (with its source policy and outcomes too), the signing key’s event, the integrity checks, the window and the expected hash.

The page never quotes a proof’s environment marker: a marker no Truestamp environment uses is described as such, and the proof’s text is then not shown on the page, nor for a document the verifier refused or a run that could not finish, whose marker no check judged, though its download is the document as served.

A source that does not answer in time leaves its check skipped as unreachable, never failed, and the page stays usable while the run reads.

Anyone can view a public item’s verification page this way; a private or unknown subject returns a generic not-found so nothing leaks to a visitor who should not see it. If you are signed in, you can still open the verify page for your own item, or your team’s, before it is made public, as a preview.

If the subject’s block has not been written to a public chain yet, or that write is not final yet, the page says so and updates once it is. If Truestamp cannot issue the subject’s proof at that moment, for example because it cannot sign it just then, or its own verifier is not configured to read the proof’s chains, the page says the proof is temporarily unavailable and to try again later, rather than reporting a failed verification or blaming the proof.

A public item’s verification page can also be found by pasting its ID, its hash, or words from its name into the search page.

For an item, you can also verify a local file: the page hashes the file in your browser and checks that hash against the claims’ hash in the verification it already made, reading no chain again, so the file contents never leave your machine. If the page verifies again while it is open, for example once the subject’s block is written to its second chain, it checks the same hash against the new run’s result. While an item has no proof yet, the hash is compared with the item’s own record; for a proof the verifier refused, or a run that could not finish, no match is shown.

Verify with the JSON:API

Send the proof’s text to the verify endpoint, with the action arguments directly under the data key. Pass offline: true for a run that reads no public chain or source. Unlike the web page, the API requires an authenticated caller (an API key or OAuth bearer token).

curl -X POST https://www.truestamp.com/api/json/proof/verify \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/vnd.api+json" \
-d '{
"data": {
"proof": "<the proof file's text>",
"offline": true
}
}'

The proof is a string, at most 262,144 bytes, read exactly as a proof file is, so text that is not a proof is refused before any check: invalid JSON (or JSON holding a number no binary64 holds) as malformed_json, and JSON that is not a proof envelope as invalid_envelope, with a sub_reason naming the rule it breaks. Or send the file itself as the body of POST /api/json/proof/raw/verify, with offline=true and expected_hash as query parameters; that route answers the report alone.

The response carries the verification report under a result key, as SPEC.md 10.5 writes it: label is the verdict (verified, internally-consistent or failed), verified is true only for verified, code names the reason when it failed, attribution says whose key signed the proof and trust_root which keyring bound it, as the object {digest, kind, location} (on this verifier, kind key_chain, Truestamp’s own, with digest and location null), environment names the verifier’s environment, type and subject_id name the subject, window and the edges submitted_after and submitted_before give the submission window (both null for a failed proof), and rows lists every check in order, each with its step, status, code, part, message and values. Optional arguments: expected_hash (items only) confirms the proof covers a specific data hash, and trace: true adds the run’s trace. A well-formed request that returns label: "failed" is a successful HTTP response reporting a failed verification, which is different from a rejected malformed request.

A request body to /api/json may be at most 528,384 bytes, and one to /gql the same. That leaves room for a proof of up to 256 KB (262,144 bytes) even when it is sent escaped inside a JSON string, as the proof argument is, which can double its size. A larger body is refused with 413 and the code request_too_large; see the JSON:API reference for the details, including the 411 a body sent without its length can get.

Verify with GraphQL

Call the verifyProof query with the same arguments as flat field arguments (proof, optional expectedHash, offline and trace) and select result and errors: verifyProof(proof: $proof) { result errors { code message vars } }. The report is the JSON string under result; a refusal or a document refused before any check fills errors for that field alone. The proof argument is a String: the proof’s text, exactly as generateProof’s result holds it (typically passed through a variable). Verification is read-only on every surface, so an OAuth token needs only the api:read scope.

Reproducing the exact hashed bytes

Every hash in the chain is computed over a canonical byte encoding, and Truestamp shows you those exact bytes. The pages for an item, a block, a beacon, and an entropy observation each include a raw-contents disclosure: everything Truestamp records about that entity, rendered as a single canonical JSON object. The page displays the JSON prettified for reading, and its copy button copies the canonical form: JSON Canonicalization Scheme (RFC 8785 JCS) bytes, with sorted keys and no whitespace.

The canonical form is not just a display convenience. JCS is the same canonicalization Truestamp applies before hashing, so the hashed payloads appear inside the canonical view byte-for-byte. The claims_jcs string of an item’s raw contents holds the claims exactly as submitted: the bytes that, prefixed with the claims domain byte (0x10) and run through SHA-256, must reproduce the stored claims hash. Its claims object is those claims parsed, as the item reads them back; canonicalized, it gives the same bytes, except that a number of 10^21 or more, which claims_jcs keeps in exponent form, reads back as a whole number. The item’s witness_hashes object is the third member of its item record, {claims_hash, id, witness_hashes}, whose canonical form hashed under 0x11 must reproduce the stored item hash; an entropy observation’s raw value is the payload of its entropy object, with its source and, for Stellar and Bitcoin, its network, whose canonical form hashed under 0x20 must reproduce its entropy hash. That last relationship is also what lets a holder resolve a witness by hand: paste a committed witness hash into the search page, open the block or observation it finds, and rehash its raw contents to confirm it is the record the fingerprint named.

Claims are the submitter’s statement, and every page shows them as one. The item page, the verify page and an item’s link-preview card show its claims, name and description as claims_jcs holds them, the bytes its claims hash covers, so they are the claims a verified result speaks of. Where a claims string, in the raw contents, the claims card, or a proof’s claims on the verify page (Proof Details), holds a code point that would not show as itself, the page shows that code point by its number, such as U+202E. Those are a bidi control, a zero-width character, anything else the claims rules refuse on input, which an older item or a proof from anywhere may hold, and a few invisible characters the rules accept: the Hangul fillers U+115F, U+1160, U+3164 and U+FFA0, the combining grapheme joiner U+034F, and the Khmer vowels U+17B4 and U+17B5. The line breaks and indentation of a JSON view are its layout and show as themselves. The copy buttons still copy the exact bytes.

Troubleshooting

The report names the step and the code of every row that did not pass. When something fails, the step tells you where in the chain it broke.

  • No report at all. The file was refused before any check: input_too_large (over 262,144 octets), malformed_json (with a sub_reason: syntax, invalid_utf8, lone_surrogate, duplicate_name, number or depth), or invalid_envelope (with the sub_reason of the envelope check that failed). A truncated or edited file often lands here; download it again. A document in an older or different layout is invalid_envelope too: generate the proof again.
  • ENVIRONMENT fails (environment_mismatch). The proof was issued by another environment than the verifier’s, for example a staging proof checked by a production verifier. It is not a production proof.
  • KEY_BINDING fails. key_binding_failed: the key that signed the proof is not in the keyring that governs, because Truestamp never published it or has revoked it, or because an offline verifier’s built-in keyring is older than the key; update the verifier or run online. keyring_unavailable: the keyring could not be used at all, Truestamp’s own key chain is not verified yet, or an external verifier’s online read of the keyring failed; try again later.
  • SIGNATURE fails (signature_invalid). The signature does not verify over this proof. Any change to any member of proof, including the constructions text or the environment marker, lands here.
  • SHAPE fails. unsupported_format or unsupported_version: not a version 1 Truestamp proof. shape_invalid: a member is missing, extra, forbidden for the type or malformed, at the part the row names. construction_mismatch: the constructions text is not one the verifier accepts.
  • POLICY fails (network_mismatch). A network is not the one the verifier pins for that chain or source, as when a test-network proof meets a production verifier.
  • DERIVE fails. derivation_mismatch: a declared hash does not equal its recomputation, a walk does not reach its root, a tree_size is not its record’s leaf_count, or a witness hash is not its witness’s; the row’s values give the constructions row, the declared value and the recomputed one. bitcoin_evidence_invalid: the carried Bitcoin transaction or txoutproof is not well formed, or the header does not meet its own target. key_event_mismatch: a key event’s ids, place or handover signature do not check, or the signing key event does not introduce the proof’s key. ordering_violation: the witness block is not below the item’s block, or, on the same network, a Stellar entropy object’s sequence is not below the top-level Stellar ledger, or a Bitcoin entropy object’s height is above the top-level Bitcoin height.
  • CHAIN fails (chain_mismatch). A chain read contradicts the proof: the Stellar transaction failed, holds another memo or sits in another ledger, or the source holds the named ledger without it; or the best-chain Bitcoin block at the entry’s height is not the carried header. A Bitcoin block reorganized away after the proof was downloaded lands here; download the proof again once the transaction is mined again (while it stays unmined, Truestamp generates no new proof of that block’s subjects).
  • SOURCES fails (entropy_mismatch). The pulse, ledger or block read back differs from the entropy object the proof carries.
  • WINDOW fails (window_inverted). The submitted-after edge is later than the submitted-before edge, which a genuine proof never shows.
  • EXPECTED_HASH fails (expected_hash_mismatch). The hash you supplied does not equal the hash the proof’s claims record, is not hex of the right length, or the proof records no file hash. Either the file you hold is not the file that was timestamped, or you hashed it differently.
  • Skips are not failures. offline (no read was made), source_unreachable (a source did not answer usably), not_held_by_source (a source no longer keeps that history, as the public Stellar Horizon keeps about a year), not_yet_indexed, chain_not_final (the Bitcoin tip is below the entry’s height + 10), sources_disagree and sources_incomplete (an operator’s several sources did not agree, or too few answered), prior_failure (a row it depends on failed), key_binding_not_performed (keyless mode) and expected_hash_not_checked each leave a check unmade, with the reason. A run with skipped reads can still be verified, as long as one top-level commitment confirmed.
  • Informational rows are not checks. window_not_established (no submitted-before edge was drawn, always the case offline), recorded_time_outside_window (the time inside the subject’s id lies outside an established window; it is Truestamp’s record, not evidence) and not_attributable (the key-history rows of a run not attributed to Truestamp) change no label.
  • internally-consistent, not verified. Nothing failed and Truestamp signed the proof, but no chain read established the submitted-before edge: the run was offline, or every top-level commitment row skipped. Run online, or again later.
  • A type mismatch. If you ask for the proof of one entropy type and the observation is from another source, the request is refused with subject_type_mismatch, which reports both the type asked for and the observation’s source.

If verification still fails unexpectedly, see support and contact channels.

Citations

  1. RFC 9162: Certificate Transparency Version 2.0. The Merkle tree hash and the inclusion proof walk used at the block and epoch levels.
  2. RFC 8785: JSON Canonicalization Scheme (JCS). The canonical byte encoding of every hashed record and of the signed proof.
  3. RFC 8032: Edwards-Curve Digital Signature Algorithm (EdDSA). Ed25519, the signature checked at SIGNATURE.
  4. Bitcoin block header reference. The header time field and its rule against the median time of the previous 11 blocks, the median time past both Bitcoin edges are read from.