Knowledge Base

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

The Proof Lifecycle

How a Truestamp proof comes to exist and strengthens over time as an item is submitted against a set of witnesses, committed into a block via item commitment, and that block is committed to Stellar and Bitcoin via block commitment, through an epoch whose hash goes on chain.

Overview

A Truestamp proof is not created in one step. It comes to exist through a lifecycle that turns a piece of submitted data into a compact, self-contained artifact. Its integrity can be checked offline; its submission window needs online reads of public chains and sources. The artifact strengthens as commitments to public blockchains confirm. The lifecycle has four linked stages: an item is submitted and fixes the public records it witnesses, its cryptographic fingerprint is placed into a Truestamp block (item commitment), the hash of an epoch whose Merkle tree holds the block’s hash is recorded on public blockchains such as Stellar and Bitcoin (block commitment), and once at least one public commitment exists the proof becomes generatable and independently verifiable. This concept follows that arc. It does not define the proof file layout (see the proof bundle format) or the step-by-step verification checks.

Stage 1: submission

Everything starts when you submit an item. An item can be a hash of an external file, or the claims content itself when no hash is supplied. At submission Truestamp computes the item’s fingerprint: the claims hash, SHA-256(0x10 || JCS(claims)), and the item hash, SHA-256(0x11 || JCS(record)), over the item record that binds the claims hash, the item’s id and its witness hashes (see hashing and domain separation). The item hash also gives the item its item code, a 16-character short name. The item is also given an identifier whose timestamp records when it entered the system, and a freshly submitted item begins in a created state.

The same moment fixes the item’s witnesses: the block then at the head of Truestamp’s ledger, which is always named, and the newest observation captured from each public entropy source that had one. Each is recorded by hash in the item’s system-generated witness_hashes, which the composite fingerprint covers, so which records an item was submitted against is decided once, at submission, and can never be chosen or revised afterwards.

At this moment the item exists in Truestamp but has no proof. Nothing has been committed to a block yet, and no block has been committed to a public blockchain. The item is simply waiting for the next block to be built.

The proof’s timing guarantee originates here. A proof attests to a submission window: it proves the item was submitted after the records it witnesses were published, and before the public-chain transaction that later committed the block holding it. It does not prove when the underlying fact originally came to exist, only that it was submitted within a verifiable window.

Stage 2: item commitment

Truestamp builds blocks on a regular cadence. When a block is built, the fingerprints of everything waiting since the previous block, the items submitted in that interval among them, are gathered into a single Merkle tree, and the block records that tree’s root. Inclusion of an item’s fingerprint as a leaf in a finalized block is the item commitment: the item’s item_hash becomes a leaf of the block’s Merkle tree, which proves the item was submitted before that block was finalized. The submission window itself is drawn from the edges read during verification. As the item moves through this, its state advances from created to processing to committed.

Each item commitment is recorded as its own durable, immutable record that stores the Merkle inclusion proof binding the item to its block. That inclusion proof is the piece a proof later carries to show the item’s fingerprint really belongs to the block’s Merkle root.

Item commitment proves membership in a Truestamp block, but a Truestamp block by itself is still internal. The next stage, block commitment, is what makes the proof trustworthy without trusting Truestamp.

Stage 3: block commitment

A newly built block starts in a finalized state. It has a complete Merkle tree, a block record holding that tree’s root and leaf count, a block hash over the record, and a signature, but it has not yet been committed to any public blockchain. Block commitment batches blocks into an epoch: each block’s hash becomes a leaf of the epoch’s Merkle tree, and the epoch’s hash, SHA-256(0x40 || JCS({leaf_count, merkle_root})), is written to a public chain, as a Stellar transaction’s hash memo or a Bitcoin transaction’s OP_RETURN output. Once a block has been committed to at least one public blockchain, its state advances from finalized to committed. On Bitcoin, the block counts as committed once a version of its epoch’s transaction confirms, and its commitment appears in proofs once the Bitcoin block holding that transaction is 10 deep.

Because epoch hashes are recorded on chains outside Truestamp’s control, a committed block can be independently confirmed against the public chain. This is what lets a proof’s submission window be checked without contacting a Truestamp server: the epoch hash that covers the block’s fingerprint is out there, publicly and permanently. Whose key signed the proof is a separate question, which a keyring of Truestamp’s answers.

Block commitment happens on more than one chain, and the chains confirm at different speeds. A Stellar commitment typically appears within minutes, while a Bitcoin commitment takes longer. The block reaches the committed state on the first successful public commitment; later commitments to additional chains add further public evidence without changing the state. A block that has been committed to both Stellar and Bitcoin carries redundant, cross-chain evidence.

Stage 4: a verifiable proof

A proof can only be generated once the item’s block has been committed to at least one public blockchain. Ask for a proof before then and generation is refused (no_block_commitment, or commitment_not_final while no commitment is final yet): there is no public commitment yet, so the artifact would rest on Truestamp’s own signature alone, and no verifier could draw a submitted-before edge from it. This gate is the reason the earlier stages must complete first.

Once the block is committed, generating a proof assembles a single self-contained document that carries the item’s claims, its record with its witness hashes, each witness’s record, the Merkle inclusion proof from the item commitment, the block’s record, and, for each chain with a final commitment, the epoch and the chain evidence from the block commitment. Before it is signed, Truestamp checks that chain evidence against its own reads of the chains, and its own verifier checks the signed document before it is served. Nothing in it is opaque: the maps that hashes are computed over travel with the file, so a verifier recomputes each hash instead of being handed one. That artifact is what a verifier checks. You can generate and download it from the app or the API, and check it on the public verify page.

Every proof carries the records the submitted-after edge is read from; the edge itself is drawn from their sources during verification. An item’s proof carries each witness its fingerprint names: the head block it saw at submission and the entropy records it committed to, each recomputed and compared with the fingerprint, so the whole submission window can be checked without asking Truestamp for anything. The head block need not be the direct predecessor of the block holding the item; the verifier checks that its height is below that block’s, and the blocks between them are not carried. The proof also carries the ledger block that introduced the signing key once that block has a final commitment. Generation chooses only how the proof carries the constructions text that defines every recomputed value: in full (the default), as a reference to its published copy, or not at all. Each choice is its own signed document, and the verdict never depends on it. See proof claims by availability for what a proof survives.

The proof keeps strengthening after it first becomes verifiable. If it was generated when only the Stellar commitment was final, regenerating it once the Bitcoin commitment is final yields a proof that carries both chains’ evidence, and a proof regenerated after the signing key’s own key-event block is committed carries that too. The underlying facts never change; the amount of independent public corroboration grows as more commitments confirm. The witnesses are the one part that never moves: they were fixed at submission, so an early proof and a late one name exactly the same ones.

Limitations

  • A proof cannot exist before its block has a public-blockchain commitment. Submission and item commitment alone do not produce a verifiable proof.
  • A proof attests to a submission window, not to creation time or original authorship. It proves the item was submitted after the public records it witnesses were published and before the public-chain transaction that committed the block holding it, nothing more.
  • The committed block state means at least one public commitment succeeded, not that every configured chain has committed. Which chains are present depends on how far the independent commitment steps have progressed when the proof is generated.
  • A proof can only be generated while the item itself is in the committed state. If the item is later redacted or scheduled for deletion, generating a new proof is refused (subject_redacted, or subject_not_ready while it is pending deletion) until it is restored; a proof generated earlier, while the item was still committed, remains independently verifiable no matter what happens to the item afterward.
  • A proof can only be generated while the item’s stored data still reproduces the fingerprint recorded at submission. Generation recomputes the claims hash and the item hash from the stored records and checks each against what was committed, and Truestamp’s own verifier checks the proof before it is served. If anything no longer matches, generation is refused as generation_failed, rather than issuing a proof that no verifier could ever confirm. The refusal does not clear on a retry.
  • A proof never carries less than its subject names. If Truestamp cannot sign it at that moment, cannot find a witness the subject’s fingerprint commits to, cannot confirm the chain evidence it would carry, or cannot read a record the proof is built from, generation is refused and the proof is temporarily unavailable, rather than issued without that witness or record. The pages say so, and the APIs answer signing_unavailable, witness_unavailable (naming the witness), evidence_unconfirmed or lookup_failed. Nothing about the subject is at fault, and a later request can succeed.