Skip to main content

Checkpoint Verification

Unlike traditional blockchains that create blocks before execution, Sui creates checkpoints after transaction execution to provide a certified record of chain history. Checkpoints contain the cryptographic hash of the previous checkpoint, a list of all the transaction digests and the corresponding transaction effects digests that are included in the checkpoint and a set of signatures from a quorum (more than 2/3) of the validators that formed the committee at the time the checkpoint was created.

Both validators and full nodes consume checkpoints to remain synchronized with the network.

How does a client verify Sui checkpoints?​

Full nodes and validators verify a checkpoint to trust it. This verification confirms that the Sui validator committee created it and that it is authentic. Checkpoint verification requires 2 interdependent steps:

  1. A client that has the public keys of the validator committee can check the signatures on the checkpoint. Checkpoints are signed by the aggregated BLS signatures of a quorum of the committee. If the signatures are valid, the client knows the checkpoint was created by the validator committee and not another party.

  2. By validating checkpoints, the client can learn the composition of the committee. The final checkpoint of each epoch contains the validator committee for the next epoch, including the public keys of its members.

This process creates an apparent circular dependency. The client needs to know the committee to verify checkpoints, but also learns the committee through checkpoint validation. The process is bootstrapped from the genesis checkpoint, the earliest checkpoint on a Sui network. The genesis checkpoint contains the initial validator committee, which allows the client to verify all checkpoints in history by following this process:

  1. The client obtains the genesis checkpoint from some trusted source.

  2. The client loads the initial committee from the genesis checkpoint.

  3. The client uses the state sync network or Sui archive to obtain the next checkpoint.

  4. The client verifies the signatures on the checkpoint using the current committee public keys. The client also verifies that the previous checkpoint hash stored in the new checkpoint equals the hash of the last checkpoint that the client validated.

  5. If the checkpoint is invalid, the client raises an error. Otherwise, the client checks if the checkpoint is the last one of the current epoch.

    • If so, load the next committee from it, and use that committee as the current committee.
    • If not, return to step 3 and continue.

This process allows the client to verify all checkpoints up to the present time.

What is a checkpoint commitment?​

After a client verifies a checkpoint, it can use the information to execute transactions and confirm results. A checkpoint contains a list of transactions, so a full node can fetch and execute them. Because transactions are identified by their digest in the form of a cryptographic hash, the client can be sure they have not been altered.

The checkpoint also includes the effects digests of each transaction. An effects digest is the cryptographic hash of the TransactionEffects structure, which lists all transaction inputs and outputs, including the digests of all objects written by the transaction. This allows a full node to confirm it has the same execution results as the validators who signed the checkpoint. By executing checkpoints and verifying transaction outputs, a full node can build the entire state of the Sui network and trust that every byte of every object is correct.

How does a client trust the genesis checkpoint?​

The validators of the initial committee create the genesis checkpoint during the genesis ceremony. Each validator verifies and signs the genesis checkpoint with sui genesis-ceremony verify-and-sign. After all validators sign, sui genesis-ceremony finalize builds the genesis file, prints its blake2b-256 hash, and the network operators distribute the genesis state.

A client reads the initial committee from this genesis file, a genesis.blob file. For Mainnet, download the Mainnet genesis.blob file from the sui-genesis repository.

Verify checkpoints with the light client​

The sui-light-client tool automates the committee-tracking part of this process. Its sync command downloads all end-of-epoch checkpoints, checks them for validity, and caches them in the checkpoint summary directory for future runs:

$ sui-light-client --config mainnet.yaml sync

In this command, mainnet.yaml is the light client configuration file. The sync runs in 2 steps. First, it downloads the end-of-epoch checkpoint numbers into the checkpoints.yaml file, which must be present in the checkpoint summaries directory. Then it downloads the corresponding checkpoint summaries. Run sync regularly to pick up new checkpoints.