Open data

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:

GET /checkpoint?format=note
explorer.usd.net/usdnet-testnet-1
6
fp2ro0s/sDtChz1XJAvFBx5d2obb+1tCiAD7OKXwTWY=

— usd.net 5oGo4ucXWBCDUHDri5nLDlC10fen2MXRGAmonfOzHTl4Ti5CbuME//WamVJ7KlY4Ip08CiQCo5xYJHABHGzwIgbfMAg=
LineMeaning
1Origin. Names the log: the host and the chain ID.
2Size. The number of leaves, which is the number of blocks, genesis included.
3Root hash. The RFC 9162 Merkle root over all block hashes, base64.
blankSeparates 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:

Verifier key
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 as SHA-256(0x01 ‖ left ‖ right), as RFC 9162 specifies.
  • Block n is leaf n, so the log size is always the height plus one.
  • Each block's own logRoot field is the root at size height + 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:

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>\n followed 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 to POST /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).