Sync Node Using State Sync

The State Sync is a way to quickly bootstrap a full Oasis node (either a validator node or a non-validator node) by using Tendermint's Light Client protocol. It allows one to initialize a node from a trusted height, its corresponding block's header and a trusted validator set (given in the genesis document). It does so by securely updating the node's trusted state by requesting and verifying a minimal set of data from the network's full nodes.

Tendermint's Light Client protocol requires at least 1 full node to be correct to be able to detect and submit evidence for a light client attack.

To configure your node to use the state sync, amend your node's configuration (i.e. config.yml) with:

... trimmed ...
# Consensus.
... trimmed ...
# Tendermint backend configuration.
... trimmed ...
# Enable consensus state sync (i.e. Tendermint light client sync).
enabled: true
trust_height: {{ trusted_height }}
trust_hash: "{{ trusted_height_hash }}"
# List of consensus nodes to use for syncing.
- "{{ node1_grpc_endpoint }}"
- "{{ node2_grpc_endpoint }}"
.. trimmed ...
- "{{ noden_grpc_endpoint }}"

and replace the following variables in the configuration snippet:

  • {{ trusted_height }}: Trusted height defines the height at which your node should trust the chain.

  • {{ trusted_height_hash }}: Trusted height hash defines the hash of the block header corresponding to the trusted height.

  • {{ node1_grpc_endpoint }}, {{ node2_grpc_endpoint }} , ...,

    {{ noden_grpc_endpoint }}: Addresses of a Oasis Nodes' publicly exposed gRPC endpoints of the form: [email protected]:9001.

You need to provide publicly exposed gRPC endpoints for at least 2 different consensus nodes for the state sync to work.

You need to delete any existing node state (if it exists), otherwise state sync will be skipped. To do that, follow the Wiping Node State instructions.

If existing node state is found and state sync is skipped, you will see something like the following in your node's logs:

{"caller":"full.go:1233","level":"info","module":"tendermint","msg":"state sync enabled","ts":"2021-06-21T14:40:55.033642763Z"}
{"caller":"node.go:692","level":"info","module":"tendermint:base","msg":"Found local state with non-zero height, skipping state sync","ts":"2021-06-21T14:40:55.838955955Z"}

Obtaining Trusted Height and Hash

To obtain the trusted height and the corresponding block header's hash, use one of the following options

Block Explorers

Browse to one of our block explorers (e.g. OASIS SCAN, Oasis Monitor) and obtain the trusted height and hash there:

  1. Obtain the current block height from the main page, e.g. 4819139.

  2. Click on block height's number to view the block's details and obtain its hash, e.g. 377520acaf7b8011b95686b548504a973aa414abba2db070b6a85725dec7bd21.

Public Rosetta Gateway

Query our public Rosetta Gateway instance and obtain the trusted height and hash there:

  1. TODO.

Oasis Node's gRPC Endpoint

Query our public Oasis Node's gRPC endpoint and obtain the trusted height and hash there:

  1. TODO.

Obtaining Addresses of Oasis Nodes' Publicly Exposed gRPC Endpoints

To find the addresses of Oasis Node's publicly exposed gRPC endpoints, use one of the following options.

List Registered Nodes' Descriptors via Oasis CLI from the Local Oasis Node

Run the following:

oasis-node registry node list -v -a unix:/srv/oasis/node/internal.sock | jq

replacing /srv/oasis/node/internal.sock with the path to your node's internal UNIX socket.

The publicly exposed gRPC endpoint addresses are found under the node descriptor's tls.addresses key.

For example, if a node has the following descriptor:

"v": 1,
"id": "+8Deo8sLL/YsP6IonNRsbmO1YonQuoAUYLjVQxZTgP8=",
"entity_id": "kupW3Pt0XMeERSkdDWyZMU4oZrk0wGysVXVyqX3rylc=",
"expiration": 8032,
"tls": {
"pub_key": "xqDPSoR2Pq7bJOhHG9ZlDpVKH9JKiVotVmOJHaLPR6g=",
"addresses": [
"p2p": {
"id": "EE9EMKdzE6/1h8HPre1FKdeqYyRpUskNz28lsf0u/iM=",
"addresses": [
"consensus": {
"id": "65SvYJ2OBwKr7cE+4tgKFvYqKI4jQIbPfnqah+cog+c=",
"addresses": null
"beacon": {
"point": "BKWYECVavUZd0+kG0ngi0McLhAivtt7jmDrG1LtPmIFQvxRTYUueMWUEqvMQL7CAdiQb6SaxgM2NU3HdypJhWhM="
"runtimes": [
"version": {
"minor": 3
"capabilities": {},
"extra_info": null
"roles": 1

Then its publicly exposed gRPC endpoint address is: