docs/node/run-your-node: Fix state sync documentation #1552
Conversation
✅ Deploy Preview for oasisprotocol-docs ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
|
|
||
| #### Oasis CLI | ||
|
|
||
| Query our public Oasis node's endpoint using the Oasis CLI and obtain the |
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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?
martintomazic
force-pushed
the
martin/fix/state-sync-docs
branch
4 times, most recently
from
204041d to
4699725
Compare
Add new `oasis network trust` command. Also removed the part that suggested taking latest height as a trust, which won't work for the stateful nodes.
martintomazic
force-pushed
the
martin/fix/state-sync-docs
branch
from
4699725 to
1a29d05
Compare
matevz
left a comment
matevz
left a comment
There was a problem hiding this comment.
Some nits, otherwise looks good.
| 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]. |
There was a problem hiding this comment.
| 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. |
|
|
||
| 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 CLI's [trust command][oasis-network-trust]. |
There was a problem hiding this comment.
| run CLI's [trust command][oasis-network-trust]. | |
| run [`oasis network trust`] to obtain a 10-days old trusted root. |
| Moreover, it enables configuring sufficiently old trust as will be explained in the next section. | ||
|
|
||
| :::caution | ||
| [oasis-network-trust]: https://github.com/oasisprotocol/cli/blob/master/docs/network.md#trust |
There was a problem hiding this comment.
| [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 |
| 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 |
There was a problem hiding this comment.
| 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 |
| #### 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) |
There was a problem hiding this comment.
| 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) |
| 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. |
There was a problem hiding this comment.
The block height is extremely old, let's use a newer one.
| 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. |
| 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. | ||
| 2. Click on block height's number to view the block's details and obtain its | ||
| hash, e.g. `377520acaf7b8011b95686b548504a973aa414abba2db070b6a85725dec7bd21`. |
There was a problem hiding this comment.
| hash, e.g. `377520acaf7b8011b95686b548504a973aa414abba2db070b6a85725dec7bd21`. | |
| hash, e.g. `3076ae195cfeda09ad49a6c74f6f655bc623e526184f814a842b224bf1846223`. |
| To obtain recommended trust period run Oasis CLI's [trust command][oasis-network-trust]. | ||
|
|
||
| ### Obtaining Trusted Height and Hash | ||
| With current consensus parameters, setting `trust_period` to any value between `220-290h` |
There was a problem hiding this comment.
| 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.
| ### Obtaining Trusted Height and Hash | ||
| 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 | ||
| and penalize nodes is still less than the debonding period, giving remote peers strong incentive not to lie. |
There was a problem hiding this comment.
I would also mention penalty.
| 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 | ||
| and penalize nodes is still less than the debonding period, giving remote peers strong incentive not to lie. | ||
| Moreover, it enables configuring sufficiently old trust as will be explained in the next section. |
There was a problem hiding this comment.
I would remove this, if possible.
| 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]. |
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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.
## OtherThen 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 | ||
|
|
||
| ::: | ||
| It is important to set sufficiently old trust, so that the network has at least one |
There was a problem hiding this comment.
I would start differently.
- Define what trusted height is.
- Mention that trusted height is connected with checkpoints.
- Mention what is good height.
|
|
||
| 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 CLI's [trust command][oasis-network-trust]. |
There was a problem hiding this comment.
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.
| #### 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) |
There was a problem hiding this comment.
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.
Closes #1530
Preview