Knowledge Base

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

The Epoch and Block Commitment

How Truestamp batches block hashes into an epoch for each chain, writes the hash of the epoch record (its Merkle root and leaf count) to Stellar as a hash memo and to Bitcoin in an OP_RETURN output, gives each block its commitment into the epoch, and replaces an abandoned Bitcoin epoch.

Overview

An epoch is the batch that Truestamp uses to perform Block Commitment. For one public chain, Truestamp gathers the block hashes of every block after that chain’s last recorded epoch, up to the head of its ledger, builds a single Merkle tree over them, and records one value on the chain: epoch_hash, the hash of the epoch record, which holds that tree’s Merkle root and the number of leaves under it. Recording a single value instead of one transaction per block is what makes public commitment efficient: one public-chain transaction covers a whole range of blocks at once.

Once the chain holds the transaction, each block in the epoch gets its own commitment into the epoch’s tree, holding the inclusion proof that walks the block’s block_hash to the tree’s root, and each block still finalized moves to committed. This is Block Commitment, the upper of Truestamp’s two commitment levels. It is distinct from Item Commitment, where an item’s item_hash is committed into its block’s own Merkle tree. The distinction between the two is covered in Item Commitment vs Block Commitment.

Truestamp commits to two independent public chains, each in its own series of epochs. On Stellar epoch_hash is written as the transaction’s hash memo (memo type hash, its 32 bytes); on Bitcoin it is written in an OP_RETURN output whose script is the bytes 0x6a 0x20 followed by its 32 bytes. A single block can end up in one Stellar epoch and one Bitcoin epoch, giving it redundant, cross-chain public evidence. Epochs and the blocks’ commitments into them are part of the public, verifiable ledger and can be read by anyone; each block’s detail page in the public explorer shows its Stellar and Bitcoin commitments.

What an epoch batches

An epoch always describes one public chain and one contiguous range of internal blocks:

  • chain - which public chain this epoch is recorded on, either Stellar or Bitcoin.
  • network - the network of that chain Truestamp is configured for: Stellar public or testnet, Bitcoin mainnet, testnet or regtest. A configured value outside these refuses the epoch; no epoch is stored with a guessed network.
  • block range - the first and last internal block covered, inclusive, named by id and by height (from_height, to_height). The range starts at the block after the last one this chain’s last recorded epoch covered (at height 0 for the chain’s first epoch) and ends at the head of the internal chain when the epoch is formed. With no new block since the last recorded epoch, no epoch is formed.
  • the epoch record - {leaf_count, merkle_root}, where merkle_root is the root of the Merkle tree over the block_hash of every block in the range, and leaf_count is the number of blocks in the range, to_height - from_height + 1, so the tree’s size is fixed with its root. Its hash, epoch_hash, is SHA-256 of the byte 0x40 followed by the record in JSON Canonicalization Scheme form (see the epoch hash). This is the single value recorded on the public chain.

Every epoch stores its record, epoch_hash and network from the moment it is reserved, and any authenticated caller can read all three on the JSON:API and GraphQL read APIs, beside the chain and the heights; epochs are not scoped to a team. The database refuses an epoch whose leaf_count is not the length of its range. Before submitting, Truestamp reloads the range and recomputes both the root and epoch_hash, and refuses to submit an epoch whose stored values do not match.

Because each chain advances independently, Stellar epochs and Bitcoin epochs cover overlapping but separately tracked ranges. Every new epoch for a chain begins where that chain’s last recorded epoch ended, so together the epochs for one chain cover the internal chain without gaps. A Stellar commit run starts every five minutes; a Bitcoin commit run starts every fifteen minutes and sends a new epoch at most hourly, less often when fees are high, within a daily fee budget. Epochs are not signed: what makes an epoch tamper-evident is the chain’s copy of its epoch_hash, which fixes both its root and its leaf count.

The epoch Merkle tree and per-block proof

The epoch tree is the same kind of Merkle tree as a block’s (see Truestamp’s Merkle tree): its leaves are the block hashes in the range, one per block, ordered by block id, and its root is the record’s merkle_root. For every block in the epoch, Truestamp derives that block’s inclusion proof, {leaf_index, tree_size, path}: the short list of sibling hashes that, combined with the block’s own block_hash, recomputes the root, in a tree of tree_size leaves. That proof is stored on the block’s commitment into the epoch, one commitment per block per chain.

This is a two-level arrangement of Merkle trees. The lower level is a block’s own tree, whose leaves are item and observation hashes and whose root is in that block’s record (this is Item Commitment, for an item). The upper level is the epoch tree, whose leaves are block hashes; its root and leaf count form the epoch record, whose hash is recorded publicly (this is Block Commitment). A complete proof walks both levels: an item’s hash walks to its block’s Merkle root, the block’s recomputed block_hash walks to the epoch record’s merkle_root, and the recomputed hash of that record must be the epoch_hash found on the public chain. The structure of a single Merkle inclusion proof is described in Merkle inclusion proofs.

A block’s commitment does not need its own signature. Its integrity comes from Merkle math: walking the stored proof from the block’s hash either reproduces the epoch’s root in a tree of the epoch’s leaf count or it does not. There is no third outcome, so a tampered block hash or a tampered proof simply fails to verify.

Recording the epoch hash on a public chain

Recording an epoch is split into steps so that a crash or a network failure between the public-chain call and Truestamp’s own bookkeeping can never charge a fee twice or leave a half-written epoch:

  1. Reserve. Truestamp first records its intent to commit: it fixes the block range, computes the epoch tree’s root and the record’s epoch_hash, and stores a pending epoch with no chain transaction yet. On each chain, no two epochs that are not abandoned may share a last block or an epoch_hash, so two attempts can never claim the same range.
  2. Submit. Truestamp submits the epoch’s epoch_hash to the public chain. On Stellar it becomes the transaction’s hash memo; on Bitcoin it becomes the OP_RETURN output. When the chain holds the transaction (a Stellar ledger has closed with it, or a version of the Bitcoin transaction has confirmed), Truestamp records the chain’s transaction details beside the epoch and marks it submitted.
  3. Record. In one all-or-nothing step, Truestamp creates each block’s commitment into the epoch for the whole range, moves every block in the range still finalized to committed, and marks the epoch recorded, noting when. Either all of this happens or none of it does.

If a worker retries after any step, it resumes from wherever the epoch already is rather than resubmitting to the chain. Only a recorded epoch counts as the prior epoch when the next range is computed, so an in-flight reservation is always finished before any new work begins.

Truestamp also keeps a record of what each chain holds for an epoch’s write, its chain evidence. A Stellar epoch’s evidence is captured when the epoch is submitted. A Bitcoin epoch’s is captured once the chain is 10 blocks past the block that holds its transaction, and only then does a proof carry the Bitcoin commitment.

A Bitcoin epoch can also end abandoned. Every version of an epoch’s Bitcoin transaction spends one wallet coin chosen in advance, so at most one version can ever confirm. If that coin is spent by a different transaction, and Bitcoin Core gives definite answers that none of the epoch’s versions is in its mempool and that each is either unknown to its wallet or displaced by a transaction at least 10 blocks deep, no version can confirm any more. The wallet’s answers count only when it is the wallet that funded the epoch, the one that owns the coin: Bitcoin Core must say the address the coin pays is the wallet’s own. Knowing the transaction that created the coin is not enough, since the wallet that sent the coin knows it too; under any other wallet the epoch stays pending. The epoch is then marked abandoned and keeps the versions it recorded, and once the daily Bitcoin budget admits a new epoch, the same run reserves a fresh one over the blocks since the last recorded epoch, which may be the very same range with the same root and epoch_hash. An abandoned epoch is never resumed or recorded, gives no block a commitment, and its recorded fee still counts against the daily Bitcoin budget, although none of its versions confirmed. While any version could still confirm, the epoch stays pending and is checked again on the next run, so a range is paid for once. One exception: a coin from a legacy (P2PKH) address lets a miner confirm a version under an altered transaction id, which reads as a different transaction, so the epoch is abandoned and the range paid for again. That costs one extra fee and never gives a wrong proof; the wallet’s own change goes to taproot addresses, which cannot be altered this way.

Verifying an epoch against the public chain

Block Commitment is the part of a proof that anyone can re-check against an independent public chain, without trusting Truestamp. Verification takes two parts and both must hold:

  • Inclusion match. The block’s inclusion proof is walked from its recomputed block_hash and must reach the epoch record’s merkle_root, with a tree_size equal to the record’s leaf_count. A mismatch fails.
  • On-chain match. The epoch hash is recomputed from the epoch record. For Stellar, the transaction and its ledger are read from the chain, and the transaction’s hash memo must equal it. For Bitcoin, the proof carries the transaction and its txoutproof: the 32 bytes of the transaction’s OP_RETURN output must equal it, and the txoutproof must place the transaction under the block header it holds, both checked offline; online, the verifier confirms that header is the best-chain block at its height and reads the median time past of the block 10 after it. A mismatch fails, and so does a chain holding the bare root.

Only when both parts pass, the epoch’s epoch_hash is on the public chain and the block provably belongs to that epoch, does the commitment hold. Each chain has its own verification path, and a commitment on one chain holds only when that chain’s record is found and matches. A verifier’s full set of checks, the Bitcoin transaction, its block header and the depth they need among them, is in verify a proof.

Truestamp holds its own epochs to the chains this way every hour, for 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 those blocks are committed in once per run, with the reference verifier’s rules, against the epoch’s current chain evidence record: what Truestamp captured of the chain’s write. A record is never edited; after a reorganization a new record supersedes it, and only the current one is judged. The check grades in three ways, and only a contradiction is invalid: records that disagree, a stored transaction that does not carry the epoch’s epoch_hash or is not in its stored block, or a chain that holds something else. Anything that leaves the question open is unavailable, never invalid: a chain source that cannot be reached, a Bitcoin block the chain is not yet 10 blocks past, an epoch whose evidence is not captured yet, or a source that no longer holds the object. On Bitcoin it reads block headers only, the tip’s height and the best-chain block at the recorded height, and checks the stored transaction and its proof offline against that header, so a pruned node can answer it. Each block’s inclusion proof is replayed against the epoch, its size held to the epoch’s leaf count. A committed block whose commitments are all invalid can be returned to finalized, a block with any unavailable commitment is left as it is until a later run, and nothing is written to a chain again.

The end-to-end sequence that carries an item from submission through Item Commitment and Block Commitment is described in the proof lifecycle.

Reading epochs

Epochs and the blocks’ commitments into them are read-only ledger data, not scoped to a team. Any authenticated caller can list and fetch them over the JSON:API and GraphQL read APIs, and a block’s commitment is never updated or deleted, nor is an epoch once recorded. Each epoch shows its state: pending (reserved, not yet confirmed on its chain), submitted (confirmed on its chain, block commitments not yet written), recorded (every block in its range has its commitment), or abandoned (a Bitcoin epoch replaced by a fresh one, as above; it never gives a block a commitment). A block itself exposes whether it has a Stellar commitment and whether it has a Bitcoin commitment, so you can see at a glance which public chains hold it. A block that is still merely finalized holds its items’ commitments but is not yet part of any recorded epoch; watching for its transition to committed is how you know the public-chain step has completed.

Limitations

  • An epoch proves that every block in its range existed before the public chain recorded the epoch’s epoch_hash. It does not, on its own, prove anything about an individual item; that is the job of the block’s own Merkle tree (Item Commitment), which the epoch sits on top of.
  • The committed state on a block reflects the first public chain to commit it, not all configured chains. A block can be committed on Stellar while its Bitcoin epoch is still in flight, or the reverse.
  • A block is only committed once its epoch is recorded. Between finalization and the next epoch being recorded on a chain, the block is on Truestamp’s ledger but has no public commitment yet.