Skip to content

Commit e955ab6

Browse files
committed
Fixup: Explain how to set correct trust period
1 parent 2820f27 commit e955ab6

1 file changed

Lines changed: 30 additions & 11 deletions

File tree

docs/node/run-your-node/advanced/sync-node-using-state-sync.md

Lines changed: 30 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -46,9 +46,10 @@ consensus:
4646
# Enable consensus state sync (i.e. CometBFT light client sync).
4747
state_sync:
4848
enabled: true
49-
# Configure trusted height & hash for the light client.
49+
# Configure trusted period, height and hash for the light client.
5050
light_client:
5151
trust:
52+
period: {{ trusted_period }}
5253
height: {{ trusted_height }}
5354
hash: "{{ trusted_height_hash }}"
5455

@@ -58,6 +59,7 @@ consensus:
5859

5960
and replace the following variables in the configuration snippet:
6061

62+
* `{{ trusted_period }}`: Trusted period is the duration for which trust remains valid.
6163
* `{{ trusted_height }}`: Trusted height defines the height at which your node should trust the chain.
6264
* `{{ trusted_height_hash }}`: Trusted height hash defines the hash of the block header corresponding to the trusted height.
6365

@@ -84,24 +86,41 @@ something like the following in your node's logs:
8486
https://docs.cometbft.com/main/explanation/core/light-client#where-to-obtain-trusted-height--hash
8587
[Wiping Node State]: ../maintenance/wiping-node-state.md#state-wipe-and-keep-node-identity
8688

87-
### Obtaining Trusted Height and Hash
89+
### Obtaining Trusted Period
90+
91+
:::caution
92+
93+
To prevent long-range attacks it is recommended that the light client trust period
94+
is shorter than the debonding period (currently 336 epochs or ~14 days). If you
95+
trust a header older than the debonding period, you risk accepting invalid headers
96+
from nodes that have already withdrawn their stake. Such nodes can no longer be
97+
penalized for their misbehaviour and you may be tricked into following the wrong chain.
98+
99+
:::
100+
101+
We recommend using `trust_period=288h` (12 days). This way the time required
102+
to verify headers, submit possible misbehavior evidence and penalize nodes
103+
is still less than the debonding period, giving nodes strong incentive not to lie.
88104

89-
To obtain the trusted height and the corresponding block header's hash, use one
90-
of the following options.
105+
106+
107+
### Obtaining Trusted Height and Hash
91108

92109
:::caution
93110

94-
Checkpoints happen approximately once per week. It is important to set
111+
Currently, checkpoints happen approximately once per week. It is important to set
95112
sufficiently old trusted height and hash, so that the network has at least one
96-
checkpoint available to serve. Moreover, to prevent a long range attack
97-
it is recommended that the light client trust period is lower than the unbonding
98-
period.
99-
100-
We recommend using the default trust period (2 weeks, no need to configure) and
101-
configuring the trusted height and hash for the block that is around 10 days old.
113+
checkpoint that is more recent than the configured trust.
102114

103115
:::
104116

117+
We recommend configuring trusted header that is around 10 days old. This way
118+
there will be checkpoints available and the trust will still be shorter than
119+
the debonding period.
120+
121+
To obtain the trusted height and the corresponding block header's hash, use one
122+
of the following options.
123+
105124
:::tip
106125

107126
If using centralized or untrusted sources it is always recommended to

0 commit comments

Comments
 (0)