Skip to content

docs/node/run-your-node: Fix state sync documentation #1552

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
martintomazic wants to merge 1 commit into
base: main
Choose a base branch
from
Open

docs/node/run-your-node: Fix state sync documentation #1552

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
98 changes: 21 additions & 77 deletions docs/node/run-your-node/advanced/sync-node-using-state-sync.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -98,23 +98,23 @@ penalized for their misbehaviour and you may be tricked into following the wrong

:::

We recommend using `trust_period=288h` (12 days). This way the time required
to verify headers, submit possible misbehavior evidence and penalize nodes
is still less than the debonding period, giving nodes strong incentive not to lie.
To obtain recommended trust period run Oasis CLI's [trust command][oasis-network-trust].
Copy link
Member

@matevz matevz Dec 3, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
To obtain recommended trust period run Oasis CLI's [trust command][oasis-network-trust].
To obtain recommended trust period run the Oasis CLI's [`oasis network trust`] command.

Copy link
Contributor

@peternose peternose Dec 3, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would change title to Trust Period, then in first paragraph define what trust period is, give values for example (current) parameters, and finish with last section which describes how to obtain it.

I would probably also organize sections like this:

  • Main title
    • Intro text
    • Trust section
      • Trust definition.
      • Trusted Period sub-section
      • Trusted Height sub-section
      • Trusted Hash sub-section
    • Configuration section
    • How to obtain section (maybe a better title)

I would also:

  • replace ... trimmed .. with shorter version (we have something that says that irrelevant stuff is omitted),
  • move this section to trust or light client section, and keep here only things relevant to state sync.

Copy link
Contributor Author

@martintomazic martintomazic Dec 3, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I see your point and will take this opportunity to fix more things, although we are scope-creeping here.

The problem with your organisation is that Trust section is not not State Sync trust, but is Light Client Trust.

I suggest to define this concept inside oasis-core as e.g. light.md that describes what light client is and have a subchapter about what the trust is. We should also move the definition of Checkpoint somewhere there (different md).

Then we also move the concept of State Sync as I have already promised to document syncing modes: oasisprotocol/oasis-core#6419.

At the end this whole section becomes:

# How to configure your node for state sync

To obtain light client trust config [link to oasis core] needed for  [state sync](link to oasis core, that also references light client, trust, checkpoints etc) use one of the following options:
## Oasis cli
## Block explorers
    // here we mention how to do it manually.
## Other

Then the person working on the stateless client documentation can reference the same concepts and define its own chapter under stateless client on how to obtain correct trust (again reference core).

The point being oasis-core should describe concepts it exposes. How to guides are out of scope of it as oasis node cannot know which networks are using it (cannot know exact parameters, cli exist etc).


### Obtaining Trusted Height and Hash
With current consensus parameters, setting `trust_period` to any value between `220-290h`
Copy link
Contributor

@peternose peternose Dec 3, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
With current consensus parameters, setting `trust_period` to any value between `220-290h`
With current consensus parameters, setting `trust_period` to any value between 220-290 hours

This format was also used for days.

I would avoid using word current, as we will probably forget to update this once we update parameters. Therefore, I would be explicit and write down what are current parameters, and then expected values.

Maybe talk first about trust period in general (part from This way, the time required ...), and then give example what are recommended values based on exact parameters.

(9-12 days) is optimal. This way the time required to verify headers, submit possible misbehavior evidence
Comment on lines +103 to +104
Copy link
Member

@matevz matevz Dec 3, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
With current consensus parameters, setting `trust_period` to any value between `220-290h`
(9-12 days) is optimal. This way the time required to verify headers, submit possible misbehavior evidence
With current consensus parameters, setting `trust_period` to any value between 9 and 12 days is optimal, e.g. `220-290h`. This way the time required to verify headers, submit possible misbehavior evidence

and penalize nodes is still less than the debonding period, giving remote peers strong incentive not to lie.
Copy link
Contributor

@peternose peternose Dec 3, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would also mention penalty.

Moreover, it enables configuring sufficiently old trust as will be explained in the next section.
Copy link
Contributor

@peternose peternose Dec 3, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would remove this, if possible.


:::caution
[oasis-network-trust]: https://github.com/oasisprotocol/cli/blob/master/docs/network.md#trust
Copy link
Member

@matevz matevz Dec 3, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
[oasis-network-trust]: https://github.com/oasisprotocol/cli/blob/master/docs/network.md#trust
[`oasis network trust`]: https://github.com/oasisprotocol/cli/blob/master/docs/network.md#trust


Currently, checkpoints happen approximately once per week. It is important to set
sufficiently old trusted height and hash, so that the network has at least one
checkpoint that is more recent than the configured trust.
### Obtaining Trusted Height and Hash

:::
It is important to set sufficiently old trust, so that the network has at least one
Copy link
Contributor

@peternose peternose Dec 3, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would start differently.

  • Define what trusted height is.
  • Mention that trusted height is connected with checkpoints.
  • Mention what is good height.

checkpoint that is more recent than the configured trust. At the same time, for the trust to be valid,
it should not be older than the trust period obtained above.

We recommend configuring trusted header that is around 10 days old. This way
there will be checkpoints available and the trust will still be shorter than
the debonding period.
Currently, checkpoints happen approximately once per week. E.g. assuming a trust period
of 12 days, a 10 days old trust is recommended.

To obtain the trusted height and the corresponding block header's hash, use one
of the following options.
Expand All @@ -126,49 +126,24 @@ fetch and compare data from multiple sources.

:::

#### Oasis CLI

If you have Oasis CLI conected to an existing node that you trust, or if your
trust assumptions are fine with using (default) public grpc endpoints (e.g. testnet)
Copy link
Member

@matevz matevz Dec 3, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
trust assumptions are fine with using (default) public grpc endpoints (e.g. testnet)
trust assumptions are fine with using (default) public grpc endpoints (e.g. Testnet)

Copy link
Contributor

@peternose peternose Dec 3, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What do users know about trust assumptions? Nothing. So be strict here and just mention that they must be connected to a trusted node (e.g. own client node), otherwise they need to verify data through other sources also.

run CLI's [trust command][oasis-network-trust].
Copy link
Member

@matevz matevz Dec 3, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
run CLI's [trust command][oasis-network-trust].
run [`oasis network trust`] to obtain a 10-days old trusted root.

Copy link
Contributor

@peternose peternose Dec 3, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Repeating. Since CLI's command returns all things at once, you should mention how to obtain this data in its own (sub)section and not under very section.


#### 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 block height (10 days old) from the main page, e.g. 4819139.
1. Assuming a trust period of 12 days, obtain the block height that is 10 days old from the main page, e.g. 4819139.
Copy link
Member

@matevz matevz Dec 3, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The block height is extremely old, let's use a newer one.

Suggested change
1. Assuming a trust period of 12 days, obtain the block height that is 10 days old from the main page, e.g. 4819139.
1. Assuming a trust period of 12 days, obtain the block height that is 10 days old from the main page, e.g. `25688638` at the time of writing this chapter.

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

@matevz matevz Dec 3, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
hash, e.g. `377520acaf7b8011b95686b548504a973aa414abba2db070b6a85725dec7bd21`.
hash, e.g. `3076ae195cfeda09ad49a6c74f6f655bc623e526184f814a842b224bf1846223`.


[Oasis Explorer]: https://explorer.oasis.io/
[Oasis Scan]: https://www.oasisscan.com

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

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

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

```json
{
"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):
Expand Down Expand Up @@ -206,8 +181,8 @@ This will give you output like the following (non-relevant fields omitted):
}
```

Assuming blocks happen every 6 seconds, subtract around `140_000` blocks to
get the height that is around 10 days old and query again:
Assuming a trust period of 12 days and blocks happening every 6 seconds,
subtract around `140_000` blocks (cca 10 days) and query again:

```bash
curl -X POST https://rosetta.oasis.io/api/block \
Expand Down Expand Up @@ -236,34 +211,3 @@ The values you need are `index` and `hash`:
}
}
```

#### Oasis CLI

Query our public Oasis node's endpoint using the Oasis CLI and obtain the
Copy link
Contributor Author

@martintomazic martintomazic Nov 17, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is not suitable for the statefull trust root, but is actually desired for the stateless client state root, as otherwise you will reindex 1 week of the data (wasted resources and slow) - see doc. Given this chapter was original meant and still is for the stateful state sync I am removing it.

My suggestion would be to extend oasis network trust command with --mode (default: stateful), with non-default being stateless. This won't be even breaking. And possibly have sub-chapters here for statefull and another for stateless. cc @peternose what do you think?

Then as discussed with @amela, we should refactor this into How to Guides for how to set trust root for the state sync (could be per mode). Everything else, i.e. State sync (consensus vs runtime), Trust Root, and Light Client should go under Concepts sections, as these are generic concepts.

This is draft, just want' to brainstorm next steps first. Also splitting this into guides/concepts is a separate issue.

Copy link
Contributor Author

@martintomazic martintomazic Dec 1, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Concepts should probably be part of the oasis-core and just referenced as submodule in the docs?

Realistically hardware requirements, modes of operations and half of "run your node" section should probably be documented an maintained there?

trusted height and hash there:

```bash
oasis network status
```

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

```json
{
"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` .