Knowledge Base

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

Public Entropy Beacons

The public /beacons page that exposes a finalized Truestamp block hash as verifiable public randomness, the beacon fields and chain-link, the derived random-outcome tools, the fact that Truestamp can bias the value, and what a beacon proof carries and how to download and verify it.

Open resource

Overview

A Truestamp beacon is a public, verifiable snapshot of the Truestamp blockchain: the hash of a finalized (or committed) block, published as a source of public randomness and as a “moment in time” marker. Each block hash is unpredictable before the public entropy its block commits to exists and immutable once the block is finalized, because it commits, through a Merkle tree, to every item submitted and every entropy observation captured in that block’s interval. The public entry point is the /beacons page at https://www.truestamp.com/beacons, which shows the current head beacon and gives every beacon a stable, shareable permalink at /beacons/<hash>. Anyone can view a beacon, derive random outcomes from it, and download a cryptographic proof of it without an account.

The public beacon page

The beacon page is genuinely public: /beacons and /beacons/<hash> are open to both signed-in and anonymous visitors, no API key or login required. /beacons resolves the current head of the chain and redirects to that block’s permalink at /beacons/<hash>, so a shared beacon link always points at one specific, addressable block hash. A beacon is also findable by pasting its block hash or ID into the search page.

A beacon page shows:

  • The 64-character lowercase hex block hash (a SHA-256 digest).
  • The finalization timestamp, labelled “Beacon Finalized”: when Truestamp recorded the underlying block, which it creates already finalized. It is Truestamp’s record, not a time a verifier confirms, and it is not the creation time of anything a user submitted.
  • Previous and next links that walk the hash chain block by block.
  • Explanatory content about what the beacon is and why it is verifiable.

The page updates in real time. When a new block is finalized or committed, the beacon you are viewing refreshes and its “next” link lights up, so watching /beacons behaves like a live heartbeat for the chain. A new block is produced about once a minute, so the current head beacon is a fast-moving value while any specific /beacons/<hash> permalink is stable forever.

Signed-in and anonymous visitors see the same beacon data and the same tools; the only difference is that anonymous visitors also see a call to action inviting them to create an account.

What a beacon is and its fields

A beacon is a read-only virtual projection over a finalized or committed Truestamp block. The underlying block’s full detail page lives in the public block explorer; the beacon exposes only the fields that matter for treating a block hash as public randomness or a proof-of-life marker, and deliberately omits the block’s internal cryptographic machinery.

Every beacon exposes exactly four fields:

  • id - the underlying block’s UUIDv7 identifier, used for follow-up lookups and proofs.
  • hash - the beacon hash: a SHA-256 digest as 64 lowercase hex characters.
  • timestamp - ISO 8601 UTC time identifying when the underlying block was finalized.
  • previous_hash - the chain-link to the previous beacon’s hash, so a verifier can walk the chain.

Only finalized or committed blocks ever appear as beacons. The Merkle root, the signing key id, the signature, the height and other block internals are intentionally not part of the beacon shape. The previous_hash of the first block in the chain, the genesis block, is not another block’s hash: it is the hash under the byte 0x30 of the genesis object, which names a Bitcoin block that was already 10 deep when the genesis block was made (see the proof bundle format). It is still a 64-character hex string, so a client walking the chain can treat it like any other previous hash and stop there.

Because the hash cryptographically commits to everything finalized in that block, it inherits the unpredictability of the underlying entropy sources. To understand where that entropy comes from, see entropy sources; for why an unpredictable, publicly published value is a sound randomness beacon, see public randomness.

Deriving random outcomes

The beacon page turns a beacon hash into reproducible random outcomes. These tools are available to everyone on the public page and require no account. Each tool is deterministic: the same beacon hash and the same parameters always produce the same result, so anyone can independently reproduce and check the outcome.

Every tool reads the beacon the same way: the block hash’s 64 hex digits, read as one unsigned 256-bit number B (int(h, 16) in Python, BigInt("0x" + h) in JavaScript). Nothing is hashed again. A tool lists its possible outcomes in a fixed order and, when there are N of them, returns the outcome at position B mod N:

  • Coin toss: B mod 2, where 0 is heads and 1 is tails. It is heads exactly when the hash’s last hex digit is even.
  • Dice roll (any number of sides, two or more): 1 + (B mod sides), so a six-sided roll is int(h, 16) % 6 + 1.
  • Random integer within a range you choose: min + (B mod (max - min + 1)). Either end may be negative.
  • Drawing from a list: the entries are sorted first, by their UTF-8 bytes, so the result does not depend on the order you typed them, and the result is the sorted entry at position B mod n, counting from 0. The page shows the drawn entry’s position in that sorted order. The list holds at most 1,000 entries.
  • Lottery draw (a set of distinct numbers from 1 up to a range of at most 1,000, shown sorted): the numbers are drawn as from an urn. Starting from x = B, each pick takes out the number at position x mod n of the n numbers left, counting from 0, and goes on with x div n. The urn draws the smaller of the number of picks and the number of picks left out; when it drew the ones left out, the result is the rest of the range.

Reading the hash directly is sound because the block hash is a full SHA-256 output whose input format is fixed from the first block on, so hashing it again would add no unpredictability and no uniformity.

Every draw has at most 2^128 possible ordered outcomes, which keeps its distance from a perfectly uniform draw at most 2^-130, and exactly 0 when the number of outcomes is a power of two (a coin, a four- or an eight-sided die). For a lottery that limits the number of picks in a larger range: every number of picks is accepted for a range up to 49; a range of 50 refuses 25 picks; a range of 100 accepts at most 19 picks or at least 81; a range of 1,000 accepts at most 12 or at least 988. Without the limit the late picks of a large draw would be forced rather than random.

Those limits are enforced by Truestamp, not only by the form. A lottery with a range or a number of picks outside them, or a drawing from a longer list, is refused with an error message and nothing is drawn. On the page, a number a tool takes (dice sides, a range’s ends, a number of picks) written with more than 40 characters (a sign and 39 digits, enough for a range of 2^128 numbers) is not read at all, and nothing is drawn. A random integer range of more than 2^128 numbers, like one whose minimum is above its maximum, draws nothing and keeps the previous result.

The outcomes are reproducible because the rule is public: everyone computes the same outcome from the same hash. They are unpredictable because no one, Truestamp included, can know a beacon before the public entropy its block commits to exists.

Truestamp can bias the value

Truestamp builds each block after that block’s entropy is public, and it chooses the block’s id (a UUIDv7 whose last 62 bits are random), which pending items and entropy observations go in, and whether to add items of its own. Each choice gives a different block hash, so Truestamp could try many candidate blocks and publish the one it prefers: on average about two candidates are enough to decide a coin toss, and about a million to fix 20 bits of the value. Nothing in a proof shows whether it did. Ruling this out would take a different construction, such as a commitment to the block’s contents published before the entropy exists, or a delay function; the beacon uses neither. A beacon suits a decision only where everyone relying on it accepts that Truestamp could bias it.

Using a beacon for a decision

  1. One beacon, one decision. Before the block exists, publish which beacon will be used, the tool, its parameters and, for a drawing, the complete entry list (one entry per line, trimmed, blank lines dropped).
  2. Results from one beacon are related. The same tool with the same parameters always gives the same result, and different tools are linked: a 12-sided roll fixes the 6-sided and 4-sided rolls, and a random integer from 1 to 100 fixes the coin. Use a new beacon, such as the next block, for each separate decision.
  3. Several numbers for one decision come from one draw. Distinct values come from one lottery draw. Values that may repeat come from successive digits of B, where the k-th value is (B div (n_1 × … × n_(k-1))) mod n_k. Keep the product of the sizes at most 2^128.
  4. Fix every input before the beacon exists. Editing a list or a parameter afterwards is the same as drawing again.

Beacon proofs

A beacon proof is one signed JSON document, of type beacon, about the block whose hash is the beacon. It lets anyone check that the beacon hash is the hash of the block record it carries, that Truestamp signed the document, and, with an online run, that the hash was fixed before a public chain recorded it and could not have been computed before the public entropy its block holds was published. The block is both the subject and the top of the proof’s own tree, so a beacon proof has no subject member and no inclusion proof of a subject.

Nothing in the file has to be taken on trust as an opaque hash. The proof carries the block as a block node: its block_hash, the beacon value, beside its record (its height, id, leaf count, Merkle root, metadata, previous block’s hash, and the id of the key that signed it), and a verifier recomputes the block_hash from that record and compares the two. Beside the block, the proof carries:

  • its commitments, one entry per chain (Stellar, Bitcoin or both): the epoch whose hash Truestamp wrote to that chain, the inclusion proof that walks the block’s hash to the epoch tree’s root, and the chain’s pointers (the Stellar ledger, or the Bitcoin transaction with its txoutproof and header);
  • its observations: for each entropy source with a leaf in the block, the observation with the latest source time, each with its inclusion proof into the block. Each one a verifier reads back from its source and finds equal gives a candidate for the beacon’s submitted-after edge, and a block with no observation gives none;
  • the signing_key_event, the block whose key event introduced the key that signed the proof, with its own commitments, once that block has a final commitment.

A plain block proof of the same block, of type block, carries the same block and commitments but no observations, so it has no submitted-after edge. The signature covers the type member with everything else, so a beacon proof and a block proof of one block are two different signed documents, and neither passes for the other. Every beacon surface gives the beacon proof: the download on the beacon page and the public verify page’s beacon presentation. The block proof comes from the block’s own page in the public block explorer and from the verify page’s block presentation. For every member, see the proof bundle format.

A proof needs a final public commitment

Every downloadable proof, beacon proofs included, needs the underlying block to have a final commitment on at least one public chain: an epoch holding the block’s hash whose transaction Truestamp has recorded on Stellar, or that Bitcoin holds 10 blocks deep. Without one the proof would carry no commitment entry, and nothing in it could give the submitted-before edge, so Truestamp issues no proof until one exists.

A freshly finalized beacon waits a few minutes for that. During the wait the beacon page’s Verify and Download buttons stay enabled, but a download produces no file: the page says instead that the beacon’s block has not been recorded on a public blockchain yet, and that a proof becomes available after the next commitment. Once the block has a commitment that is not final yet, for example a Bitcoin epoch fewer than 10 blocks deep, the page says instead that the proof becomes available once the public blockchain’s record of the block is final. Once the block has a final commitment, the same buttons produce the proof.

Downloading a beacon proof

From any beacon page, the header’s Download Proof button hands over the beacon proof exactly as Truestamp serves it, after Truestamp’s own verifier has checked it, in one JSON file named <block_id>.proof.json, the same name as the block proof’s, so the file’s type member is what tells the two apart. The page is public, so no account is needed.

Once a file is downloaded, the header lists what it carries: the Stellar commitment, the Bitcoin commitment, and the record of how Truestamp’s signing key was introduced, which rides along only once the block that introduced the key has a final commitment of its own. While Bitcoin holds the epoch’s transaction but not yet 10 blocks deep, the file carries no Bitcoin commitment, and the page warns that a later download will include it.

If Truestamp cannot issue a committed beacon’s proof at that moment, for example because it cannot sign it just then, the page says the proof is temporarily unavailable and to try again later. Nothing is wrong with the beacon, and no incomplete proof is issued in its place.

Verifying a beacon proof

A verifier recomputes the beacon hash from the block record the proof carries, checks Truestamp’s signature over the proof, walks the block’s hash up each commitment’s inclusion proof to its epoch’s root and recomputes the epoch hash, and checks each observation’s hash and its walk into the block. Online it then reads the chains and the entropy sources. The submitted-before edge comes from the chains: the close time of the Stellar ledger that holds the epoch’s transaction, or, once the carried Bitcoin header is confirmed as the best-chain block at its height, the median time past of the block 10 above it. Each observation read back from its source gives a candidate for the submitted-after edge. Offline it reads nothing, so it shows the proof intact and signed, and draws no window. The steps are in how to verify a proof.

There are two public ways to do this.

  • The public verify page verifies the proof Truestamp serves of a beacon. Open https://www.truestamp.com/verify/beacon/<hash_or_id> for the beacon presentation, or https://www.truestamp.com/verify/block/<block_id> for the plain block presentation of the same block. Because the 64-character hash is a beacon’s natural public identifier, the beacon route accepts either that hash or the block’s id; the block route accepts the block id only. The URL always names its type; nothing is detected from the identifier alone. Both pages are public and require no account, and a beacon’s window there also reads that no one, Truestamp included, could compute the value before its submitted-after edge, and that Truestamp chooses the block contents and could bias it.
  • The command-line client at github.com/truestamp/truestamp-cli verifies a downloaded proof file from your terminal with no Truestamp account. By default it reads Truestamp’s published keyring, the chains and the entropy sources, and draws the window from what they answer; with --offline it reads nothing and binds the key against the keys built into it.

Limitations

A beacon proves timing, not authorship or creation time. Data that contains a beacon hash, such as a photograph of a printed beacon, was made after that hash could be computed, which a verifier places after the beacon proof’s submitted-after edge, the latest published time among its block’s observations that the verifier read back from their sources. The beacon says nothing about how much later the data was made, when the data was originally created, or by whom.

The programmatic beacon surfaces are not public. Beacons are also exposed over JSON:API, GraphQL, the MCP server and the console WebSocket for programmatic consumers, but those need a credential (an API key or an OAuth access token), so they are out of scope for anonymous use; see the beacon API. The public surfaces are the /beacons page, its randomness tools and proof downloads, the printable beacon artifact at /beacons/<hash>/print, the /verify/beacon/<hash_or_id> and /verify/block/<block_id> pages, and verification of a downloaded proof with an external client.