Checkpoints
A checkpoint is a signed statement of the log's size and root hash, in the C2SP signed-note format used across the transparency ecosystem.
What a checkpoint says
A checkpoint commits to the entire history of USD Network in three lines:
explorer.usd.net/usdnet-testnet-1
6
fp2ro0s/sDtChz1XJAvFBx5d2obb+1tCiAD7OKXwTWY=
— usd.net 5oGo4ucXWBCDUHDri5nLDlC10fen2MXRGAmonfOzHTl4Ti5CbuME//WamVJ7KlY4Ip08CiQCo5xYJHABHGzwIgbfMAg=| Line | Meaning |
|---|---|
| 1 | Origin. Names the log: the host and the chain ID. |
| 2 | Size. The number of leaves, which is the number of blocks, genesis included. |
| 3 | Root hash. The RFC 9162 Merkle root over all block hashes, base64. |
| blank | Separates the body from the signatures. |
— usd.net … | Signature. Key name, then base64 of a 4-byte key ID followed by the 64-byte Ed25519 signature. |
The signature covers the body: the first three lines, each followed by a newline.
The key
The sequencer's public key is sequencerKey in GET /info. In C2SP form, the verifier key is:
usd.net+<keyID hex>+<base64(0x01 ‖ public key)>The key ID is the first 4 bytes of SHA-256("usd.net" ‖ 0x0A ‖ 0x01 ‖ public key). Tools that speak the signed-note format, such as Go's golang.org/x/mod/sumdb/note, can verify USD Network checkpoints with this key directly.
How the tree is built
- Each block hash, as 32 raw bytes, is a leaf.
- Leaves are hashed as
SHA-256(0x00 ‖ leaf)and interior nodes asSHA-256(0x01 ‖ left ‖ right), as RFC 9162 specifies. - Block
nis leafn, so the log size is always the height plus one. - Each block's own
logRootfield is the root at sizeheight + 1. Every block is therefore also a commitment to the full history up to itself.
Using checkpoints
Save checkpoints as you see them. Later, ask for a consistency proof from your saved size to the current size. If the proof verifies against your saved root, nothing you saw has changed. If the network ever served you a checkpoint that does not verify, you hold signed evidence of it.
Anchors
Once an hour, if the log has grown, the latest checkpoint is written into a Solana memo:
usd.net checkpoint usdnet-testnet-1 <size> <root hex>The memo is signed by the anchor key, which GET /anchors returns along with every anchor written so far: size, root, Solana transaction and slot. To use an anchor, read the memo from any Solana explorer or node. Then request GET /proof/consistency?from=<size> and verify it against the memo's root. Solana's history can't be edited by USD.NET, so a checkpoint anchored there pins the log's history up to that size for good.
Witnesses
A witness is an independent party that checks the log for everyone else. It keeps the last checkpoint it saw. On each new checkpoint it verifies a consistency proof from the old size, and only then signs the new checkpoint with its own key. The format is C2SP tlog-cosignature (cosignature/v1):
- The signed message is
cosignature/v1\ntime <unix seconds>\nfollowed by the checkpoint body. - The witness posts its signature line,
— <name> <base64(key ID ‖ 8-byte big-endian time ‖ Ed25519 signature)>, with the checkpoint size toPOST /witness/cosign. - The key ID is the first 4 bytes of
SHA-256(name ‖ 0x0A ‖ 0x04 ‖ public key).
Once accepted, the line is added to the checkpoint note for that size, under the sequencer's own line, so one note carries both signatures. GET /witnesses lists every registered witness, its verifier key and the last checkpoint it cosigned.
To run a witness, write to witnesses@usd.net with your verifier key, name+keyid+base64(0x04 ‖ public key).