Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
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
8 changes: 7 additions & 1 deletion docs/multichain/destination/CertificateVerifier.md
Original file line number Diff line number Diff line change
Expand Up @@ -26,10 +26,16 @@ The CertificateVerifier contracts are responsible for verifying certificates fro

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.

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

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

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:
- AllocationManager: `OperatorSlashed`
- AllocationManager: `OperatorAddedToOperatorSet`
- AllocationManager: `OperatorRemovedFromOperatorSet`
- CrossChainRegistry: `GenerationReservationCreated`

---

## ECDSACertificateVerifier
Expand Down
2 changes: 1 addition & 1 deletion pkg/bindings/BN254CertificateVerifier/binding.go

Large diffs are not rendered by default.

2 changes: 1 addition & 1 deletion pkg/bindings/CrossChainRegistry/binding.go

Large diffs are not rendered by default.

2 changes: 1 addition & 1 deletion pkg/bindings/ECDSACertificateVerifier/binding.go

Large diffs are not rendered by default.

2 changes: 1 addition & 1 deletion pkg/bindings/OperatorTableUpdater/binding.go

Large diffs are not rendered by default.

2 changes: 1 addition & 1 deletion pkg/bindings/TaskMailbox/binding.go

Large diffs are not rendered by default.

5 changes: 4 additions & 1 deletion src/contracts/interfaces/IBN254CertificateVerifier.sol
Original file line number Diff line number Diff line change
Expand Up @@ -82,10 +82,13 @@ interface IBN254CertificateVerifier is
/// @dev The `referenceTimestamp` is used to key into the operatorSet's stake weights. It is NOT when the certificate was generated off-chain
/// @dev The `maxStalenessPeriod` configured in step 1c denotes if a certificate is too stale with respect to the `referenceTimestamp`
/// @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
/// @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:
/// @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),
/// the multichain protocol updates tables for operatorSets when the following events are emitted:
/// - AllocationManager: `OperatorSlashed`
/// - AllocationManager: `OperatorAddedToOperatorSet`
/// - AllocationManager: `OperatorRemovedFromOperatorSet`
/// - CrossChainRegistry: `GenerationReservationCreated`
/// @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
/// @dev Certificates can be replayed across all destination chains
/// @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)
/// Some examples of race conditions include:
Expand Down
1 change: 1 addition & 0 deletions src/contracts/interfaces/ICrossChainRegistry.sol
Original file line number Diff line number Diff line change
Expand Up @@ -238,6 +238,7 @@ interface ICrossChainRegistry is ICrossChainRegistryErrors, ICrossChainRegistryE
* - InvalidTableUpdateCadence: The tableUpdateCadence is zero
* @dev Emits the following events:
* - TableUpdateCadenceSet: When the table update cadence is successfully set
* @dev The table update cadence is weekly on mainnet and daily on testnet
*/
function setTableUpdateCadence(
uint32 tableUpdateCadence
Expand Down
5 changes: 4 additions & 1 deletion src/contracts/interfaces/IECDSACertificateVerifier.sol
Original file line number Diff line number Diff line change
Expand Up @@ -73,10 +73,13 @@ interface IECDSACertificateVerifier is
/// @dev The `referenceTimestamp` is used to key into the operatorSet's stake weights. It is NOT when the certificate was generated off-chain
/// @dev The `maxStalenessPeriod` configured in step 1c denotes if a certificate is too stale with respect to the `referenceTimestamp`
/// @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
/// @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:
/// @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),
/// the multichain protocol updates tables for operatorSets when the following events are emitted:
/// - AllocationManager: `OperatorSlashed`
/// - AllocationManager: `OperatorAddedToOperatorSet`
/// - AllocationManager: `OperatorRemovedFromOperatorSet`
/// - CrossChainRegistry: `GenerationReservationCreated`
/// @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
/// @dev Certificates can be replayed across all destination chains
/// @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)
/// Some examples of race conditions include:
Expand Down
1 change: 1 addition & 0 deletions src/contracts/interfaces/IOperatorTableUpdater.sol
Original file line number Diff line number Diff line change
Expand Up @@ -180,6 +180,7 @@ interface IOperatorTableUpdater is
* - InvalidGlobalTableRoot: provided globalTableRoot does not match stored root for referenceTimestamp
* - InvalidOperatorSetProof: merkle proof verification failed
* - InvalidCurveType: unsupported curve type in operatorTableBytes
* @dev The operator table is updated at a cadence of `tableUpdateCadence` seconds, which is given by `CrossChainRegistry.tableUpdateCadence`
*/
function updateOperatorTable(
uint32 referenceTimestamp,
Expand Down
Loading