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

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

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
67 changes: 7 additions & 60 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,8 +98,9 @@ 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
We recommend using `trust_period=288h` (12 days). Even better you can query the
latest suggested trust period running `oasis network trust` (TODO insert link).
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.

### Obtaining Trusted Height and Hash
Expand Down Expand Up @@ -138,34 +139,11 @@ obtain the trusted height and hash there:
[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):
#### Oasis CLI
Copy link
Contributor Author

@martintomazic martintomazic Nov 17, 2025

Choose a reason for hiding this comment

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

Move to the top, as all other options are more centralized :).


```json
{
"software_version": "23.0.5",
"identity": {
...
},
"consensus": {
...
"latest_height": 18466200,
"latest_hash": "9611c81c7e231a281f1de491047a833364f97c38142a80abd65ce41bce123378",
"latest_time": "2023-11-27T08:31:15Z",
"latest_epoch": 30760,
...
},
...
}
```
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)
run `oasis network trust` (TODO insert link).

the values you need are `latest_height` and `latest_hash`.

Expand Down Expand Up @@ -236,34 +214,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

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

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