# 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:

```note title="GET /checkpoint?format=note"
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:

```text title="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](/open-data/consistency-proofs) 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:

```text title="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](https://c2sp.org/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)`.
