Skip to main content

Using State Sync for Quick Bootstrapping

The State Sync is a way to quickly bootstrap a full Oasis node (either a validator node or a non-validator node) by using the CometBFT'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.

info

If you have access to an Oasis node that is synced with the latest height, another option to speed bootstrapping a new Oasis node is to copy state from one node to the other.

caution

CometBFT'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 (non-relevant fields omitted):

... trimmed ...

# Consensus.
consensus:

  ... trimmed ...

  # Enable consensus state sync (i.e. CometBFT light client sync).
  state_sync:
    enabled: true
  # Configure trusted height & hash for the light client.
  light_client:
    trust:
      height: {{ trusted_height }}
      hash: "{{ trusted_height_hash }}"

... trimmed ...

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.
danger

You need to delete any existing node state (if it exists), otherwise the 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:709","level":"info","module":"cometbft","msg":"state sync enabled","ts":"2023-11-16T20:06:58.56502593Z"}
{"caller":"node.go:770","level":"info","module":"cometbft:base","msg":"Found local state with non-zero height, skipping state sync","ts":"2023-11-16T20:06:59.22387592Z"}

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 Explorer, Oasis Scan) 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.

A Trusted Node​

If you have an existing node that you trust, you can use its status output to retrieve the current block height and hash by running:

oasis-node control status -a unix:/node/data/internal.sock

This will give you output like the following (non-relevant fields omitted):

{
  "software_version": "23.0.5",
  "identity": {
    ...
  },
  "consensus": {
    ...
    "latest_height": 18466200,
    "latest_hash": "9611c81c7e231a281f1de491047a833364f97c38142a80abd65ce41bce123378",
    "latest_time": "2023-11-27T08:31:15Z",
    "latest_epoch": 30760,
    ...
  },
  ...
}

the values you need are latest_height and latest_hash.

Public Rosetta Gateway​

First obtain the network's Genesis document's hash (e.g. from the Networks Parameters Page):

Query our public Rosetta Gateway instance and obtain the trusted height and hash there (replace the <chain-context> with the value obtained in the previous step):

curl -X POST https://rosetta.oasis.io/api/block \
-H "Content-Type: application/json" \
-d '{
    "network_identifier": {
        "blockchain": "Oasis",
        "network": "<chain-context>"
    },
    "block_identifier": {
        "index": 0
    }
}'

This will give you output like the following (non-relevant fields omitted):

{
	"block": {
		"block_identifier": {
			"index": 16787439,
			"hash": "443b71d835dbae7ea6233b06280ab596287d5c45f88fa76a71bf6cc52366592e"
		},
    ...
	}
}

The values you need are index and hash.

Oasis CLI​

Query our public Oasis node's endpoint using the Oasis CLI and obtain the trusted height and hash there:

oasis network status

This will give you output like the following (non-relevant fields omitted):

{
  "software_version": "23.0.5",
  "identity": {
    ...
  },
  "consensus": {
    ...
    "latest_height": 18466200,
    "latest_hash": "9611c81c7e231a281f1de491047a833364f97c38142a80abd65ce41bce123378",
    "latest_time": "2023-11-27T08:31:15Z",
    "latest_epoch": 30760,
    ...
  },
  ...
}

The values you need are latest_height and latest_hash .