Skip to content

Commit f7fb781

Browse files
authored
docs: add transport frequency for multichain (#1642)
Update natspec & multichain docs with the following: - Transport frequency & timings - Tables are updates for `CrossChainRegistry.GenerationReservationCreated`
1 parent bfdc91e commit f7fb781

File tree

10 files changed

+22
-8
lines changed

10 files changed

+22
-8
lines changed

docs/multichain/destination/CertificateVerifier.md

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -26,10 +26,16 @@ The CertificateVerifier contracts are responsible for verifying certificates fro
2626

2727
Certificates can be created at any time, but must contain a `referenceTimestamp`, which informs the contract of which operator table for the `operatorSet` to use. Both certificate verifiers implement staleness checks based on a `maxStalenessPeriod` to ensure certificates are not verified against outdated operator information.
2828

29-
**Note: Setting a max staleness period to 0 enables certificates to be confirmed against any `referenceTimestamp`. In addition, setting a `maxStalenessPeriod` that is greater than 0 and less than the frequency of table updates (daily on testnet, weekly on mainnet) is impossible due bounds enfroced by the [`CrossChainRegistry`](../source/CrossChainRegistry.md#parameterization).** See the [staleness period](#staleness-period) in the appendix for some examples.
29+
**Note: Setting a max staleness period to 0 enables certificates to be confirmed against any `referenceTimestamp`. In addition, setting a `maxStalenessPeriod` that is greater than 0 and less than the frequency of table updates (daily on testnet at 14:00 UTC, weekly on Monday on mainnet at 14:00 UTC) is impossible due bounds enfroced by the [`CrossChainRegistry`](../source/CrossChainRegistry.md#parameterization).** See the [staleness period](#staleness-period) in the appendix for some examples.
3030

3131
Both the `BN254CertificateVerifier` and `ECDSACertificateVerifier` contain a `msgHash` parameter. This value is the the hash of a task that was completed by operators. **NOTE: The msgHash is NOT signed by operators as part of completion of a task**. The value signed by operators is the signable digest, which is the hash of the `msgHash` and `referenceTimestamp`. This signable digest is given by `certificateVerifier.calculateCertificateDigest`.
3232

33+
In addition to the table updates that occur for *all* operatorSets, the multichain protocol updates tables for single operatorSets any time the following 4 events are emitted for an operatorSet with an active generation reservation:
34+
- AllocationManager: `OperatorSlashed`
35+
- AllocationManager: `OperatorAddedToOperatorSet`
36+
- AllocationManager: `OperatorRemovedFromOperatorSet`
37+
- CrossChainRegistry: `GenerationReservationCreated`
38+
3339
---
3440

3541
## ECDSACertificateVerifier

pkg/bindings/BN254CertificateVerifier/binding.go

Lines changed: 1 addition & 1 deletion
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

pkg/bindings/CrossChainRegistry/binding.go

Lines changed: 1 addition & 1 deletion
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

pkg/bindings/ECDSACertificateVerifier/binding.go

Lines changed: 1 addition & 1 deletion
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

pkg/bindings/OperatorTableUpdater/binding.go

Lines changed: 1 addition & 1 deletion
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

pkg/bindings/TaskMailbox/binding.go

Lines changed: 1 addition & 1 deletion
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

src/contracts/interfaces/IBN254CertificateVerifier.sol

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -82,10 +82,13 @@ interface IBN254CertificateVerifier is
8282
/// @dev The `referenceTimestamp` is used to key into the operatorSet's stake weights. It is NOT when the certificate was generated off-chain
8383
/// @dev The `maxStalenessPeriod` configured in step 1c denotes if a certificate is too stale with respect to the `referenceTimestamp`
8484
/// @dev Operator tables for ALL operatorSets with an active generation reservation are updated at a set cadence. See `crossChainRegistry.tableUpdateCadence` for the frequency of table updates
85-
/// @dev To ensure that tables do not become stale between table updates (i.e. a large operator has joined or been ejected), the multichain protocol updates tables for operatorSets when the following events are emitted:
85+
/// @dev To ensure that operatorSets can immediately begin to verify certificates and that tables do not become stale between table updates (i.e. a large operator has joined or been ejected),
86+
/// the multichain protocol updates tables for operatorSets when the following events are emitted:
8687
/// - AllocationManager: `OperatorSlashed`
8788
/// - AllocationManager: `OperatorAddedToOperatorSet`
8889
/// - AllocationManager: `OperatorRemovedFromOperatorSet`
90+
/// - CrossChainRegistry: `GenerationReservationCreated`
91+
/// @dev Operator tables are updated at a cadence of `tableUpdateCadence` seconds, which is given by `CrossChainRegistry.tableUpdateCadence`. Currently daily on testnet and weekly (Monday) on mainnet at 14:00 UTC
8992
/// @dev Certificates can be replayed across all destination chains
9093
/// @dev Race conditions should be handled by the AVS. The protocol makes no guarantees about how certificates should be verified (eg. preventing certificates against tables that are NOT the latest)
9194
/// Some examples of race conditions include:

src/contracts/interfaces/ICrossChainRegistry.sol

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -238,6 +238,7 @@ interface ICrossChainRegistry is ICrossChainRegistryErrors, ICrossChainRegistryE
238238
* - InvalidTableUpdateCadence: The tableUpdateCadence is zero
239239
* @dev Emits the following events:
240240
* - TableUpdateCadenceSet: When the table update cadence is successfully set
241+
* @dev The table update cadence is weekly on mainnet and daily on testnet
241242
*/
242243
function setTableUpdateCadence(
243244
uint32 tableUpdateCadence

src/contracts/interfaces/IECDSACertificateVerifier.sol

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -73,10 +73,13 @@ interface IECDSACertificateVerifier is
7373
/// @dev The `referenceTimestamp` is used to key into the operatorSet's stake weights. It is NOT when the certificate was generated off-chain
7474
/// @dev The `maxStalenessPeriod` configured in step 1c denotes if a certificate is too stale with respect to the `referenceTimestamp`
7575
/// @dev Operator tables for ALL operatorSets with an active generation reservation are updated at a set cadence. See `crossChainRegistry.tableUpdateCadence` for the frequency of table updates
76-
/// @dev To ensure that tables do not become stale between table updates (i.e. a large operator has joined or been ejected), the multichain protocol updates tables for operatorSets when the following events are emitted:
76+
/// @dev To ensure that operatorSets can immediately begin to verify certificates and that tables do not become stale between table updates (i.e. a large operator has joined or been ejected),
77+
/// the multichain protocol updates tables for operatorSets when the following events are emitted:
7778
/// - AllocationManager: `OperatorSlashed`
7879
/// - AllocationManager: `OperatorAddedToOperatorSet`
7980
/// - AllocationManager: `OperatorRemovedFromOperatorSet`
81+
/// - CrossChainRegistry: `GenerationReservationCreated`
82+
/// @dev Operator tables are updated at a cadence of `tableUpdateCadence` seconds, which is given by `CrossChainRegistry.tableUpdateCadence`. Currently daily on testnet and weekly (Monday) on mainnet at 14:00 UTC
8083
/// @dev Certificates can be replayed across all destination chains
8184
/// @dev Race conditions should be handled by the AVS. The protocol makes no guarantees about how certificates should be verified (eg. preventing certificates against tables that are NOT the latest)
8285
/// Some examples of race conditions include:

src/contracts/interfaces/IOperatorTableUpdater.sol

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -180,6 +180,7 @@ interface IOperatorTableUpdater is
180180
* - InvalidGlobalTableRoot: provided globalTableRoot does not match stored root for referenceTimestamp
181181
* - InvalidOperatorSetProof: merkle proof verification failed
182182
* - InvalidCurveType: unsupported curve type in operatorTableBytes
183+
* @dev The operator table is updated at a cadence of `tableUpdateCadence` seconds, which is given by `CrossChainRegistry.tableUpdateCadence`
183184
*/
184185
function updateOperatorTable(
185186
uint32 referenceTimestamp,

0 commit comments

Comments
 (0)