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
publicortestnet, Bitcoinmainnet,testnetorregtest. 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}, wheremerkle_rootis the root of the Merkle tree over theblock_hashof every block in the range, andleaf_countis 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 byte0x40followed 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:
- 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 anepoch_hash, so two attempts can never claim the same range. - Submit. Truestamp submits the epoch’s
epoch_hashto the public chain. On Stellar it becomes the transaction’s hash memo; on Bitcoin it becomes theOP_RETURNoutput. 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. - 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
finalizedtocommitted, 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_hashand must reach the epoch record’smerkle_root, with atree_sizeequal to the record’sleaf_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_RETURNoutput 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
committedstate 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.