Skip to main content

Quantum-safe settlement receipts

A settlement receipt is a portable record that a rollup's settlement batch was anchored to the Main Chain under a post-quantum signature. You can persist it, ship it, and hand it to an auditor or counterparty.

A receipt is a claim, not evidence

Every field in a receipt comes from whoever handed it to you — including the signature and the key it names. Verifying it therefore means re-reading the claim from the chain: verifySettlementReceipt only reports valid: true when the receipt reproduces what the chain actually holds. A receipt checked against nothing but itself proves nothing.

The anchor signature is ML-DSA-87 (Dilithium-5, FIPS-204), the same post-quantum scheme the Main Chain uses, so a receipt inherits the base chain's quantum-safe integrity.

The canonical anchor message​

Verification checks a Dilithium-5 signature over a canonical message built from the anchor. The chain has used two forms, and a verifier must use the one that was in force when the anchor was recorded.

v2 — chain v3.2.2 and later. Every variable-length field is prefixed with its length as an 8-byte big-endian integer, the chain id binds the signature to one network, and the transaction count and compressed state proof are covered because the chain computes its anchor fraud check from them:

"qorechain-multilayer-anchor-v2"
| BE64 len(chain_id) chain_id
| BE64 len(layer_id) layer_id
| BE64 layer_height
| BE64 len(state_root) state_root
| BE64 len(validator_set_hash) validator_set_hash
| BE64 transaction_count
| BE64 len(compressed_state_proof) compressed_state_proof

For a rollup batch the chain fills these in as: layer_id is the rollup's layer id, layer_height is the batch index, state_root the batch's state root, transaction_count its transaction count, and the proof empty.

v1 — before v3.2.2. layer_id || layer_height (8-byte BE) || state_root || validator_set_hash, with no length prefixes and no chain id — so its field boundaries were ambiguous and a signature was valid on every chain. It survives only for standalone anchors recorded before the switch.

The switch happened at block 6,905,034 on qorechain-diana (2026-10-02) and block 3,556,788 on qorechain-vladi (2026-10-16); a fresh chain uses v2 from genesis. The verifier picks the form by the anchor's height, never by trying both: a v1 signature carries no chain id, so accepting it where v2 is in force would re-admit exactly the weakness v2 removed. The result reports which form it checked (signBytesVersion).

anchorSignBytesV1(...) and anchorSignBytesV2(...) produce these bytes; anchorSignBytesForBatch(...) produces the v2 bytes for a rollup batch with the chain's mapping already applied. All three are checked byte-for-byte against vectors generated by the chain's own implementation, in all five languages.

Anchoring your batches​

From chain v3.2.2 a batch is anchored — and so a receipt can exist for it — only if MsgSubmitBatch carries the rollup creator's ML-DSA-87 signature over the batch's v2 anchor bytes. Without it the batch still settles, just unanchored, and no receipt can ever be built for it.

RdkTxClient.submitBatch does this for you when it can do it correctly: the client signs hybrid, and it is the rollup's creator — the chain verifies the anchor against the creator's registered key, and a refused anchor refuses the whole batch. Otherwise it submits unanchored, exactly as before.

const tx = await rdk.connectTx(signer, { gasPrice: "0.15uqor", pqcKeypair });
await tx.submitBatch(batch); // anchored when you are the creator
await tx.submitBatch(batch, { anchor: "require" }); // refuse rather than go unanchored

If your rollup uses a separate sequencer address, the sequencer submits but the creator must sign: build the bytes with anchorSignBytesForBatch, have the creator sign them, and pass the result as anchorSignature.

Build and verify (TypeScript)​

import {
createRdkClient,
buildSettlementReceipt,
verifySettlementReceipt,
} from "@qorechain/rdk";

const rdk = createRdkClient({
endpoints: { rest: "https://api-testnet.qore.host" },
});

// Build a portable receipt for one batch.
const receipt = await buildSettlementReceipt(rdk, "my-roll", 7);

// Persist it, ship it, hand it to a counterparty — it is self-contained JSON.

// Verify it: pass a client so every field is re-read from chain state.
const result = await verifySettlementReceipt(receipt, { client: rdk });

console.log(result.valid); // true only when the chain confirms the receipt
console.log(result.mode); // "chain"

Before anything is read from the chain, the receipt's schema is checked: a version other than 1 or 2, or an algorithm other than ML-DSA-87, is refused rather than guessed at, and a version-2 receipt must carry chainId, transactionCount and compressedStateProof.

Verification against a client then checks six things, each read from the chain rather than from the receipt:

  1. rollupLayerBinding — the chain says this rollup belongs to that layer.
  2. batchStateRoot — the chain's batch carries the receipt's state root (both stateRoot and batchStateRoot).
  3. anchorOnChain — an anchor actually exists on chain and agrees with the receipt on every anchor field: state root, layer height, validator-set hash, signature, Main Chain height, anchor time, transaction count and compressed state proof. A mismatch names the field.
  4. creatorAuthority — the signing key is resolved from the chain for the rollup's registered creator, never taken from the receipt.
  5. chainBinding — the receipt names the network you queried.
  6. pqcSignature — the Dilithium-5 signature over the canonical anchor message verifies under that key.

So every field of a receipt that verifies is bound to chain state. Still, read facts from the result rather than from the file: result.anchor is the chain's own anchor, and on a valid result result.verifiedReceipt is the receipt rebuilt from chain state.

if (result.valid) {
const { mainChainHeight, anchoredAt } = result.verifiedReceipt!; // read from chain
}

Signature-only mode​

Without a client you can still check the signature against a key you obtained out-of-band. This is mode: "signature-only" and is never valid by design — it shows someone signed those bytes, not that QoreChain anchored anything:

const sigOnly = await verifySettlementReceipt(receipt, {
creatorPublicKey: "<a key you obtained out-of-band>",
});
// sigOnly.mode === "signature-only"
// sigOnly.valid === false
Your trust anchor is the node you query

Chain verification is only as good as the endpoint you point at. Use a node you run or trust; a hostile endpoint can answer whatever it likes.

// Online verification: fetch the creator's PQC key from the chain.
const online = await verifySettlementReceipt(receipt, { client: rdk });

Reading anchors​

Receipts are built from a new on-chain x/multilayer Anchor query. The reads:

  • getAnchor(layerId) — the anchor for a layer.
  • getLatestAnchor() — the most recent anchor.
  • getAnchors(layerId) — the anchor history for a layer.
  • getPqcAccount(address) — a registered post-quantum account (its ML-DSA-87 key), used to verify the creator's signature.

CLI​

# Build a receipt and print it.
qorollup receipt my-roll 7

# Build, then verify it inline.
qorollup receipt my-roll 7 --verify

# Build and write it to a file.
qorollup receipt my-roll 7 --out receipt.json

# Verify a receipt SOMEBODY GAVE YOU (the relying-party path).
qorollup receipt verify receipt.json

--verify self-checks a receipt this command just built. To check a receipt you received from someone else, use qorollup receipt verify <file> — it verifies exactly what was presented to you, without rebuilding it.

See the qorollup reference.

What a receipt does not prove​

Verification tells you that the chain holds what the receipt claims. Two limits are worth stating plainly, because a receipt is most often shown to someone who was not there when it was made.

Your trust anchor is the node you query. Every check is a read against one endpoint. A receipt verified against a node the presenter chose proves only what that node says. Verify against a node you control, or one you would trust for a balance.

Which batch an anchor belongs to — settled by v2. The v1 message named neither the rollup nor the batch, so where two batches shared a state root on one layer under one creator (two freshly created rollups, or a batch that changed no state), a genuine anchor could be relabelled from one to the other. The v2 message closes that: for a rollup batch its layer_height is the batch index, and a rollup registers its layer under its own id, so two batches never sign the same bytes. Every anchor the rdk module has written is v2 — before the switch the chain did not anchor RDK batches at all — so for RDK receipts the residual no longer applies. It remains only for standalone v1 anchors from before the switch heights, where verification still binds rollupId and batchIndex through chain reads rather than through the signature.

A receipt cannot be moved between networks. A version-2 receipt records its chainId, which the v2 signature also covers, and verification refuses a receipt checked against a node for a different chain. A version-1 receipt has no chain id; it still verifies, on the strength of the anchor having been found on the chain you queried.

Other languages​

The Python, Go, Rust, and Java (JVM) clients expose the same build/verify surface. They perform the ML-DSA-87 verification through the qorechain-pqc library rather than a bundled JavaScript implementation; install it alongside the RDK client for your language.