Knowledge Base

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

Proof Bundle Wire Format

The JSON format of a Truestamp proof - the signed envelope, the proof's members by type, block and epoch nodes, subjects, witnesses and beacon observations, commitments keyed by chain, the signing key event, constructions modes, the environment marker, value classes and size limits.

Overview

A proof is the receipt you download when you timestamp something with Truestamp. It is one small JSON file that anyone can check for themselves, without asking Truestamp whether it is real: it carries every record it needs, and every hash in it can be recomputed from what it carries. Everything after this section is the field-by-field reference for developers who build software that reads these files.

What a proof establishes is a submission window. Its subject is a submitted item, an entropy observation, a Truestamp block, or a block’s beacon value. The proof ties the subject into a Truestamp block, the block into an epoch, and the epoch’s hash to a transaction on Stellar, Bitcoin or both, and for an item it carries the public records the item named when it was submitted. A verifier draws both edges of the window from reads of public chains and entropy sources that it makes during verification, never from a time the proof carries. A proof does NOT prove when the underlying content was created, who wrote it, or that any claim in it is true. For the checks, see verify a proof; for how a proof comes to exist, see the proof lifecycle.

The format is defined by the Truestamp verification specification (SPEC.md, in the truestamp-verification repository), and every proof Truestamp serves follows it. Three rules shape everything below:

  • Every object is closed. Each object has exactly the members listed for it, within their presence rules, and the only open region is the submitter’s claims. An optional member with no value is absent, never null. A verifier rejects any member the format does not list for its position.
  • Nothing opaque travels. Every hash a proof declares sits beside the record it is the hash of, and a verifier recomputes it and compares. No record contains its own hash or its own signature.
  • Formatting is free. Member order, whitespace and the spelling of an escape or a number change nothing: every hash and the signature are computed over the JSON Canonicalization Scheme (JCS, RFC 8785) encoding of the parsed values.

The envelope

The document is an object with exactly two members: proof, which holds all signed content, and signature, which has exactly three:

Member Value
signature.alg the literal truestamp-ed25519-sha256-jcs, which names the signing rule; compared with that literal, never used to choose behavior
signature.public_key the signer’s 32-byte Ed25519 public key, as 43 characters of unpadded base64url
signature.value the 64-byte Ed25519 signature, as 86 characters of unpadded base64url

The signature is pure Ed25519 by the active key over the 32 bytes of proof_hash = SHA-256(0x50 || JCS(proof)). It covers every member of proof and nothing outside it. There is no second signature, no key id, no proof_hash and no context member: a verifier computes proof_hash itself from the proof it parsed. See Ed25519 signatures for strict verification and for which keyring binds the key.

Truestamp serves the JCS of the envelope as UTF-8 with no trailing newline, at most 65,536 octets (MAX_DOCUMENT_OCTETS), with the media type application/vnd.truestamp.proof+json and the file extension .proof.json. A verifier reads a file of up to 262,144 octets (MAX_READ_OCTETS), which leaves room for a reformatted copy. A proof is identified by its proof_hash, never by the bytes of a file or its signature string: two files that differ only in formatting are the same proof.

Members of the proof

Member Presence Meaning
block always the block node of the block that includes the subject; for block and beacon, the subject itself
commitments always the commitments of that block, keyed by chain, one or two entries; only these give the submitted-before edge
constructions optional the constructions text (an object), its reference URL (a string), or absent
environment optional dev, staging or test; present exactly when a non-production environment signed the proof
format always "truestamp-proof"
observations beacon only for each source with a leaf in the block, one observation subject, 0 to 3 members
signing_key_event optional {block, commitments}: the committed block whose key event introduced the signing key; present exactly when that block has a final commitment
subject item and the entropy types the item subject or the observation subject
type always item, entropy_nist, entropy_stellar, entropy_bitcoin, block or beacon
version always 1
witnesses item only the records the item’s witness_hashes names, by the same names

A proof carries none of these: a generation time, an issuer, a proof-level key id, its own proof_hash, a download variant, a close time for any commitment’s ledger or block, the intermediate hashes a walk computes, or the blocks between the item’s witness block and its block. type is the one member that selects what a verifier runs, from a closed registry; a type the registry does not hold is rejected.

Block nodes

A block node appears at /block, /witnesses/block and /signing_key_event/block:

Member Meaning
block_hash `SHA-256(0x31
record.height 0 at genesis, then one more per block
record.id the block’s UUIDv7
record.leaf_count the number of leaves under merkle_root; 0 exactly when merkle_root is the empty root
record.merkle_root the root of the block’s tree of item and observation hashes
record.metadata {} for an ordinary block, {"key_event": ...} for a key-event block, and {"genesis": ..., "key_event": ...} for the genesis block
record.previous_block_hash the previous block’s hash; at genesis, `SHA-256(0x30
record.signing_key_id the key id of the key that signed this block record; a preimage input only, never used to choose or check the proof’s signer

The genesis object is {"bitcoin": {"header_hash", "height", "network"}}: it names a Bitcoin block that was at least 10 deep on the best chain when Truestamp’s genesis block was made, and it is present exactly on the genesis block. A key event is one of five types, and a verifier checks every key event it meets, at any block position (the signing rule is in Ed25519 signatures):

type Members Checked wherever it appears
genesis key_id, prerotation_commitment (optional), public_key, sequence (0), type key_id is the key id of public_key and equals record.signing_key_id
rotation handover_signature, height, key_id, prerotation_commitment (optional), previous_block_hash, previous_key_id, previous_public_key, public_key, reason, sequence (at least 1), type as genesis, plus previous_key_id is the key id of previous_public_key, height and previous_block_hash are those of the block record that carries the event, and handover_signature verifies under previous_public_key
emergency_rotation as rotation, with handover_signature optional as rotation, the handover signature when present
prerotation active_key_id, prerotation_commitment, type record.signing_key_id equals active_key_id; introduces no key
revocation revoked_key_id, type introduces no key, and is not checked

A key’s key id is the hex of the first 4 bytes of SHA-256(0x60 || its 32 bytes).

Commitments

commitments, at the top level and inside signing_key_event, is an object keyed by chain, bitcoin, stellar or both. Every member of each entry is required. Each entry carries the epoch whose hash it wrote to its chain, as an epoch node, and the inclusion proof of the block beside these commitments in that epoch’s tree:

Member Chain Meaning
epoch.epoch_hash both `SHA-256(0x40
epoch.record.leaf_count both the number of block hashes in the epoch’s tree
epoch.record.merkle_root both the epoch tree’s root, which the inclusion proof must reach
inclusion_proof both the walk from the recomputed block_hash to epoch.record.merkle_root
network both Stellar public or testnet; Bitcoin mainnet, testnet or regtest
transaction_hash both the transaction that holds epoch_hash; for Bitcoin, recomputed from raw_transaction
ledger Stellar the ledger that holds the transaction
height Bitcoin the height of the block that holds the transaction
raw_transaction Bitcoin the transaction serialized without witness data, at most 1,000 octets (2,000 hex characters); exactly one output script begins 0x6a, and it is 0x6a 0x20 and the 32 bytes of epoch_hash
txoutproof Bitcoin the merkleblock Bitcoin Core emits, at most 1,024 octets (2,048 hex characters): an 80-byte header and the partial Merkle tree that places the transaction in it
header_hash Bitcoin the hash of the txoutproof’s header, recomputed and compared
header_merkle_root Bitcoin the header’s Merkle root field, recomputed and compared
header_time Bitcoin the header’s time, recomputed and compared; display only, never an edge

A Stellar entry is carried once Truestamp has recorded the evidence of its transaction. A Bitcoin entry is carried only once it is final: Truestamp captures its evidence when the chain is 10 blocks past the transaction’s block. A proof of a block with no final commitment on any chain cannot be generated. epoch_hash binds the epoch’s leaf count with its root, so the chain’s copy fixes both.

Subjects

Item

"subject": {
"claims": {...},
"inclusion_proof": {"leaf_index", "path", "tree_size"},
"item_hash": SHA-256(0x11 || JCS(record)),
"record": {
"claims_hash": SHA-256(0x10 || JCS(claims)),
"id": the item's UUIDv7,
"witness_hashes": {"block": ..., "entropy_bitcoin": ..., "entropy_nist": ..., "entropy_stellar": ...}
}
}

claims are the submitter’s statements exactly as submitted: the bytes the claims hash covers, never checked as true. inclusion_proof walks from the recomputed item_hash to /block/record/merkle_root. witness_hashes always names block, the block at the head of Truestamp’s ledger at submission, by its block_hash, and names each entropy_X exactly when that source had a current observation, by its entropy_hash.

witnesses carries exactly the names of witness_hashes: block as a block node, and each entropy_X as an entropy object. A verifier recomputes each one’s hash and compares it with the entry. The witness block’s height must be below the height of the block that includes the item; the blocks between the two are not carried.

Entropy observation

An entropy proof, of type entropy_nist, entropy_stellar or entropy_bitcoin, carries the observation subject:

"subject": {
"entropy": the entropy object, its source matching the type,
"inclusion_proof": {"leaf_index", "path", "tree_size"},
"observation_hash": SHA-256(0x21 || JCS(record)),
"record": {"entropy_hash": SHA-256(0x20 || JCS(entropy)), "id": the observation's UUIDv7}
}

Block and beacon

A block proof carries only the common members: the subject is block.record, and only the submitted-before edge applies. A beacon proof adds observations: for each source with a leaf in the block, the observation subject of the leaf with the latest source time (of two at the same time, the smaller observation_hash), each with its inclusion proof into the block. An empty observations is allowed, and leaves the submitted-after edge absent. The beacon value is the block’s block_hash.

Entropy objects

An entropy object, at /subject/entropy, /witnesses/entropy_X and /observations/entropy_X/entropy, is exactly the preimage of its entropy_hash:

Source Object
NIST {"payload": {"pulse": {"chainIndex", "outputValue", "pulseIndex", "timeStamp", "version"}}, "source": "nist"}
Stellar {"network", "payload": {"closed_at", "hash", "sequence"}, "source": "stellar"}
Bitcoin {"network", "payload": {"hash", "height", "time"}, "source": "bitcoin"}

NIST’s outputValue is uppercase hex as NIST publishes it, and its timeStamp has three digits of fraction; a Bitcoin payload’s time is integer Unix seconds.

The signing key event

signing_key_event is {block, commitments}: the block whose key event (genesis, rotation or emergency_rotation) introduced signature.public_key, as a block node, and that block’s own commitments, in the same form as the top-level ones. It is present exactly when that block has a final commitment. It is provenance only: a verifier checks that the event introduces the proof’s key and that its block and commitments recompute and confirm, but it never binds the key through it, and its commitments never give an edge.

Constructions and the environment marker

constructions says how the proof carries the constructions text, a list of 28 named rules that says how each value is computed from the ones before it, up to the epoch hash on the chains, and how the two edges are read. It is documentation: no verifier interprets it, and each only checks that the text is one it accepts.

Mode constructions
full, the default the text itself, an object
reference the string https://www.truestamp.com/.well-known/constructions-<d>.json, d the text’s SHA-256
none absent

The member is inside proof, so each mode is its own signed document, and a proof’s verdict never depends on its mode. The generate action’s constructions argument chooses it.

environment is present exactly when a non-production environment signed the proof, naming it: dev, staging or test. Production writes no marker. Each environment signs with its own keys, and a verifier rejects a proof marked for any environment but its own.

Value classes

Every value a proof carries is a declaration, and a verifier treats it as its class says:

Class Values Treatment
pinned format, version, type, environment, signature.alg, constructions compared with the verifier’s own values before anything uses them
checked every record hash, every witness_hashes entry, every Merkle root an inclusion proof reaches and every tree_size, the genesis height and previous_block_hash, the Bitcoin transaction_hash and header values, the ids and signature a key event’s checks cover recomputed and compared
path input every inclusion proof’s path and leaf_index bound by the walk
preimage every leaf_count, the merkle_root of a block record no inclusion proof walks into, a key event’s type and public_key, raw_transaction, txoutproof, every entropy source and payload value inputs to a checked hash or a named check
chain pointer every network, a Stellar transaction_hash and ledger, a Bitcoin commitment’s height, NIST chainIndex and pulseIndex, a Stellar sequence, a Bitcoin entropy hash, the genesis object may cause an offline rejection (POLICY, LINK_CHAIN_ORDER), but supports a pass or an edge only after a read made during verification; a network is only compared with the verifier’s pin and never chooses what is read
submitted subject.claims bound by claims_hash; shown only as the submitter’s statement
recorded ids and the times in them, other previous_block_hash and signing_key_id values, and the rest Truestamp’s records, bound by the hashes and the signature, never a verdict input

No time a proof carries is ever an edge: not header_time, not an entropy payload’s time, not the time inside an id, and not a claimed timestamp in the claims.

Limits

  • Size. The specification sizes every type. A typical item proof in full mode is 15,899 octets, 7,302 by reference and 7,162 with no text; a typical block proof 13,832 in full mode. The largest the format admits is 55,279 octets for an item (55,303 signed in staging), so every committed subject has a proof under MAX_DOCUMENT_OCTETS. The claims are at most 20,480 octets in their JCS form.
  • Depth. A file is nested at most 32 levels, the document itself counting as the first, checked before anything is canonicalized.
  • Numbers. Every number is read as its nearest binary64 value, and no number may be an integer of magnitude above 2^53 - 1 (9007199254740991) and below 10^21, however it is written. Every number outside the claims is an integer from 0 to 2^53 - 1.
  • Paths. An inclusion proof’s path holds at most 32 hashes, and no committed tree holds more than 2^32 leaves.

Numbers in the claims

Truestamp applies the same number rule to the claims at submission, on every surface, with an error naming the member and the fix (submit an item lists the codes):

  • an integer of magnitude above 2^53 - 1 as JCS writes it, a number no double holds (1e400), or a number with digits that are not all 0 that reads as 0 (1e-400) is refused as claims_number_range;
  • a number whose canonical form has a different value from the number as written is refused as claims_number_precision: 3.14159265358979323846, which canonical form writes as 3.141592653589793, or 1000000000000000000001, written 1e+21. A change of spelling alone is accepted: 1000000000000000000000 is kept as 1e+21, and 2.50 as 2.5.

Send any such value as a string instead. A number the claims keep is therefore exactly a double, and every implementation reads back the same value and computes the same claims hash.

Versions and unknown input

format is "truestamp-proof" and version is 1. A breaking change to the format needs a new version, and a different version is a different format that a version 1 verifier rejects as unsupported_version. Since every object is closed, there are no silent additions: a member the format does not list for its position and type, an unknown type among them, fails as shape_invalid, and a document that is not the two-member envelope at all is refused before any check as invalid_envelope.

Example (JSON, item subject)

An item proof from Truestamp’s test environment, committed to Stellar and Bitcoin, carrying all four witnesses and the signing key event. It is abridged for reading: long hex and base64url values are cut after 16 characters with an ellipsis, the constructions text is shown as {...}, and the signing key event’s commitments are shown with Stellar only. On the wire every value is full length.

{
"proof": {
"block": {
"block_hash": "46447a268ae23933…",
"record": {
"height": 2,
"id": "01a17d52-7e10-7aaf-96e0-b27102b27cce",
"leaf_count": 5,
"merkle_root": "279bfb9d3e29ebb5…",
"metadata": {},
"previous_block_hash": "ad2676187fe256d1…",
"signing_key_id": "04a76bfd"
}
},
"commitments": {
"bitcoin": {
"epoch": {
"epoch_hash": "d3168aae557b9ce4…",
"record": {"leaf_count": 3, "merkle_root": "53ea0b3a968243f1…"}
},
"header_hash": "266ef8636bc45710…",
"header_merkle_root": "c65362a48ddc4e4c…",
"header_time": "2026-09-26T01:52:00Z",
"height": 222,
"inclusion_proof": {"leaf_index": 2, "path": ["bf967e551a42079f…"], "tree_size": 3},
"network": "regtest",
"raw_transaction": "0200000001d44824…",
"transaction_hash": "c65362a48ddc4e4c…",
"txoutproof": "00000020cb1b81b9…"
},
"stellar": {
"epoch": {
"epoch_hash": "d3168aae557b9ce4…",
"record": {"leaf_count": 3, "merkle_root": "53ea0b3a968243f1…"}
},
"inclusion_proof": {"leaf_index": 2, "path": ["bf967e551a42079f…"], "tree_size": 3},
"ledger": 1000255,
"network": "testnet",
"transaction_hash": "860d4085c0af0b5f…"
}
},
"constructions": {...},
"environment": "test",
"format": "truestamp-proof",
"signing_key_event": {
"block": {
"block_hash": "adf0776ab13b2051…",
"record": {
"height": 0,
"id": "01a17d52-7d0a-7f06-a24f-b586a54f5a6a",
"leaf_count": 0,
"merkle_root": "e3b0c44298fc1c14…",
"metadata": {
"genesis": {
"bitcoin": {"header_hash": "0f9188f13cb7b2c7…", "height": 0, "network": "regtest"}
},
"key_event": {
"key_id": "04a76bfd",
"public_key": "krcqBwjUBsOjj10-…",
"sequence": 0,
"type": "genesis"
}
},
"previous_block_hash": "6e82652582eea64d…",
"signing_key_id": "04a76bfd"
}
},
"commitments": {
"stellar": {
"epoch": {
"epoch_hash": "d3168aae557b9ce4…",
"record": {"leaf_count": 3, "merkle_root": "53ea0b3a968243f1…"}
},
"inclusion_proof": {"leaf_index": 0, "path": ["9fdd21468a500229…", "547a764affbe9b8e…"], "tree_size": 3},
"ledger": 1000255,
"network": "testnet",
"transaction_hash": "860d4085c0af0b5f…"
}
}
},
"subject": {
"claims": {
"description": "Item 74895d8a8d0fb01f",
"hash": "abababababababab…",
"hash_type": "sha256",
"name": "Q3 report.pdf"
},
"inclusion_proof": {
"leaf_index": 3,
"path": ["e0d1070d92cc6192…", "fcb26f56b2ab78e0…", "048d913ab15694f3…"],
"tree_size": 5
},
"item_hash": "f563a16a43cb82dd…",
"record": {
"claims_hash": "5452b7a58c79e18d…",
"id": "01a17d52-7df9-7466-a9da-aa999ea9fe91",
"witness_hashes": {
"block": "ad2676187fe256d1…",
"entropy_bitcoin": "c5e73cea68aaf799…",
"entropy_nist": "1d2d1432a7ee7221…",
"entropy_stellar": "2bfcd684973d6e72…"
}
}
},
"type": "item",
"version": 1,
"witnesses": {
"block": {
"block_hash": "ad2676187fe256d1…",
"record": {
"height": 1,
"id": "01a17d52-7de8-7011-aa03-7338ae8f7770",
"leaf_count": 1,
"merkle_root": "1111111111111111…",
"metadata": {},
"previous_block_hash": "adf0776ab13b2051…",
"signing_key_id": "04a76bfd"
}
},
"entropy_bitcoin": {
"network": "regtest",
"payload": {"hash": "4688b3b0f3274af8…", "height": 215, "time": 1790387100},
"source": "bitcoin"
},
"entropy_nist": {
"payload": {
"pulse": {
"chainIndex": 2,
"outputValue": "FDBA0E7DA81C1148…",
"pulseIndex": 1200018,
"timeStamp": "2026-09-26T01:48:00.000Z",
"version": "2.0"
}
},
"source": "nist"
},
"entropy_stellar": {
"network": "testnet",
"payload": {"closed_at": "2026-09-26T01:48:30Z", "hash": "84e52c6a94870983…", "sequence": 1000222},
"source": "stellar"
}
}
},
"signature": {
"alg": "truestamp-ed25519-sha256-jcs",
"public_key": "krcqBwjUBsOjj10-…",
"value": "Xh1eGft8flwME5w-…"
}
}

In this test-environment example, both chains’ entries name one epoch, and the signing key event’s block is the genesis block, so its record has no leaves and its merkle_root is the empty root. In full mode this proof is 15,585 octets, by reference 6,988 and with no text 6,848. A block proof drops subject and witnesses; a beacon proof drops them and adds observations; an entropy proof carries the observation subject and no witnesses. The specification’s vectors/worked-example.json, in the truestamp-verification repository, holds a worked example of the signing rule with its exact bytes.

Citations

  1. RFC 8785: JSON Canonicalization Scheme (JCS). The canonical byte form of every hashed record and of the signed proof.
  2. RFC 9162: Certificate Transparency Version 2.0. The Merkle tree and the inclusion proofs a proof carries at the block and epoch levels.
  3. RFC 8032: Edwards-Curve Digital Signature Algorithm (EdDSA). Ed25519, the signature over proof_hash.