Knowledge Base

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

Item Commitment vs Block Commitment

A commitment binds a record hash into the Merkle tree one level up, an item's item_hash into its block's tree or a block's block_hash into an epoch's tree; Item Commitment and Block Commitment mean those commitments exist, and why a proof needs both.

Overview

In Truestamp a commitment binds a record hash, its subject, into the Merkle tree one level up. There is one kind of commitment, used at two levels: an item’s item_hash (or an entropy observation’s observation_hash) committed into its block’s tree, and a block’s block_hash committed into the tree of an epoch whose hash Truestamp writes to Stellar or Bitcoin. Each commitment holds the inclusion_proof that walks its subject’s hash to that tree’s merkle_root. Item Commitment means an item’s commitment into its block exists, and moves the item to committed. Block Commitment means a block’s commitment into an epoch exists, and moves the block to committed. The first ties your item to Truestamp’s own ledger; the second ties that ledger to an independent public blockchain. A proof needs both, and the submission window a verifier draws rests on the second. Keeping the two meanings separate is essential when reading proofs, state, and verification results.

Item Commitment

Item Commitment binds a single item to one internal block. When a block is built, Truestamp constructs a Merkle tree over everything waiting since the previous block, the items submitted in that interval and the entropy observations captured in it, and each item’s item_hash becomes a leaf of that tree. The block is created already finalized, holding that tree’s root and leaf count in its signed record, and each of its items moves to processing. Truestamp then writes each item’s commitment, holding its inclusion proof into the block’s tree, and moves the item to committed in the same transaction. The commitment is not signed: its inclusion proof checks against the block’s Merkle root, which the signed block record fixes. Exactly one such commitment exists per item.

Because the item is now provably a leaf of that block’s tree, it was submitted before that block was finalized. That is a fact about Truestamp’s own ledger, and it is not yet an edge a stranger can confirm: a verifier’s submitted-before edge comes from the public chain at Block Commitment. The submitted-after edge rests on the witnesses that the item’s own record named at submission, so it was settled before Item Commitment. This is what committed means for an item: its commitment into a finalized block exists. It does not yet imply anything about any public blockchain.

Item Commitment on its own establishes an internal, self-consistent record: given the item’s record, its inclusion proof, and the block’s record, anyone can confirm the item belongs to that specific block. What it cannot do by itself is prove that Truestamp did not construct the whole block later. That is the job of Block Commitment. For how the inclusion proof itself is structured, see Merkle inclusion proofs.

Block Commitment

Block Commitment binds internal blocks to a public blockchain. Each block carries a block_hash, the hash of its record, which fixes the block’s Merkle root and leaf count. Rather than write each block_hash to a public chain on its own, Truestamp batches blocks: for each chain, the blocks after that chain’s last recorded epoch, up to the head of the ledger, become one epoch, with a Merkle tree over their block hashes. The epoch’s record holds the tree’s Merkle root and its leaf count (the number of blocks), and the value written on the chain is the record’s hash, the epoch’s epoch_hash, which fixes both. Because the public chain’s record is timestamped by a network Truestamp does not control, writing the epoch hash there proves every Truestamp block in that epoch existed before the chain recorded it.

Batching is what makes Block Commitment efficient: one public-chain transaction covers a whole range of blocks, and each block gets its own commitment, whose inclusion proof walks its block_hash to the epoch tree’s root. So a block’s block_hash is not written on-chain by itself; instead the block is proven to belong to the epoch whose hash was written. The epoch’s write to the chain is not itself a commitment: once the chain holds the transaction (on Bitcoin, once a version of it confirms), Truestamp writes one commitment per block of the epoch and, in the same transaction, moves each block still finalized to committed.

A block is created directly in a finalized state, and moves to committed at its first chain’s Block Commitment. A later commitment on the other chain adds redundant public evidence without changing the state again, so a block can carry commitments on both Stellar and Bitcoin, with committed reflecting the first one. A proof carries a block’s commitments as the entries of its commitments, keyed by chain: a Stellar entry once Truestamp has recorded the evidence of the transaction, and a Bitcoin entry once it is final, when the chain is 10 blocks past the block that holds the transaction.

Block Commitment is the piece a downstream verifier can re-check against the public chain. It recomputes the block’s hash from its record, walks the commitment’s inclusion proof to the epoch’s Merkle root, checks that the proof’s tree size is the epoch’s leaf count, and recomputes the epoch hash from the epoch’s record. The two chains are then checked differently. For Stellar it reads the transaction and its ledger from the chain, and the transaction’s hash memo must equal that epoch hash. For Bitcoin the proof carries the transaction and its txoutproof, and the verifier checks them offline against the block header the txoutproof holds: the transaction’s output whose script is 0x6a 0x20 followed by 32 bytes must hold that epoch hash. Online it confirms that header is the best-chain block at its height, and reads the median time past of the block 10 after it. See verify a proof for the full set of checks.

Truestamp makes the same check of its own blocks every hour, and a block’s committed state follows it. Each run checks the finalized blocks that have commitments, and the committed blocks from 2 to 72 hours old; a committed block older than that is not checked again. The block healer checks each epoch once per run against the epoch’s current chain evidence record, with the reference verifier’s rules, reading only block headers on Bitcoin. Only a contradiction is invalid: records that disagree, or a chain that holds something other than the record says. A source that cannot answer, a block not final yet, or evidence not captured yet is unavailable, never invalid. A finalized block whose commitments all hold moves to committed; a committed block whose commitments are all invalid can be returned to finalized, and one with any unavailable commitment is left as it is until a later run. Nothing is recommitted: the block keeps its commitments, and returns to committed once they hold again.

Why both matter

The two commitments answer two different questions, and an item proof carries both.

  • Item Commitment answers “is this specific item part of a specific Truestamp block?” It proves membership and integrity against Truestamp’s internal ledger, but that ledger is authored by Truestamp.
  • Block Commitment answers “did that Truestamp block exist before an independent public blockchain recorded it?” It removes the need to trust Truestamp’s clock or good faith, because an external network recorded the epoch hash that fixes the root the block’s hash provably walks to.

Chained together, an item with Item Commitment inside a block with Block Commitment is provably a leaf of a block whose existence was recorded by a public chain. That chain of reasoning is what lets a verifier draw the submitted-before edge of the item’s submission window from the chain, without asking anyone to trust Truestamp. A proof of the item can be generated only once its block has a final commitment on at least one chain. The end-to-end sequence that walks an item from submission through Item Commitment and Block Commitment is described in the proof lifecycle.

Reading state and terminology

The same word, committed, appears on both items and blocks and means different things.

  • An item in the committed state has Item Commitment: its commitment into a finalized block’s Merkle tree exists. This says nothing about public blockchains.
  • A block in the committed state has Block Commitment: its commitment into an epoch, whose epoch hash a public blockchain holds, exists, with an inclusion proof tying its block_hash to the epoch tree’s root.

Blocks and their commitments into epochs are part of the public, verifiable ledger and are readable by anyone through the public explorer pages; an item’s commitment can be read by whoever can read the item. A block being merely finalized means its items are already committed to it internally, but the block itself is still waiting for its first epoch to be recorded on a public chain. Watching for the block’s move to committed is how you know the public-blockchain step has completed.