Skip to content

Commit 3ae64cc

Browse files
ypatil12ypatil12
committed
feat: multi chain interfaces (#1423)
**Motivation:** Add all multi chain interfaces for easier development. **Modifications:** Adds the following: - `IBN254CertificateVerifier` (implements `IBaseCertificateVerifier`) - `IECDSACertificateVerifier` (implements `IBaseCertificateVerifier`) - `IBN254TableCalculator` - `IECDSATableCalculator` - `IOperatorTableUpdater` - `ICrossChainRegistry` **Result:** Multichain interfaces. Pending adding of `OperatorTableCalculator`
1 parent b6cfb82 commit 3ae64cc

File tree

8 files changed

+973
-0
lines changed

8 files changed

+973
-0
lines changed

‎src/contracts/interfaces/IBN254CertificateVerifier.sol‎

Lines changed: 104 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,104 @@
1+
// SPDX-License-Identifier: BUSL-1.1
2+
pragma solidity ^0.8.27;
3+
4+
import "src/contracts/libraries/OperatorSetLib.sol";
5+
import "src/contracts/interfaces/ICrossChainRegistry.sol";
6+
import "src/contracts/interfaces/IBaseCertificateVerifier.sol";
7+
import "src/contracts/interfaces/IBN254TableCalculator.sol";
8+
9+
interface IBN254CertificateVerifierTypes is IBN254TableCalculatorTypes {
10+
/**
11+
* @notice A witness for an operator
12+
* @param operatorIndex the index of the nonsigner in the `BN254OperatorInfo` tree
13+
* @param operatorInfoProofs merkle proofs of the nonsigner at the index. Empty if operator is in cache.
14+
* @param operatorInfo the `BN254OperatorInfo` for the operator
15+
*/
16+
struct BN254OperatorInfoWitness {
17+
uint32 operatorIndex;
18+
bytes operatorInfoProof;
19+
BN254OperatorInfo operatorInfo;
20+
}
21+
22+
/**
23+
* @notice A BN254 Certificate
24+
* @param referenceTimestamp the timestamp at which the certificate was created
25+
* @param messageHash the hash of the message that was signed by operators and used to verify the aggregated signature
26+
* @param signature the G1 signature of the message
27+
* @param apk the G2 aggregate public key
28+
* @param nonSignerWitnesses an array of witnesses of non-signing operators
29+
*/
30+
struct BN254Certificate {
31+
uint32 referenceTimestamp;
32+
bytes32 messageHash;
33+
BN254.G1Point signature;
34+
BN254.G2Point apk;
35+
BN254OperatorInfoWitness[] nonSignerWitnesses;
36+
}
37+
}
38+
39+
interface IBN254CertificateVerifierEvents is IBN254CertificateVerifierTypes {
40+
/// @notice Emitted when an BN254 table is updated
41+
event TableUpdated(OperatorSet operatorSet, uint32 referenceTimestamp, BN254OperatorSetInfo operatorSetInfo);
42+
}
43+
44+
/// @notice An interface for verifying BN254 certificates
45+
/// @notice This implements a base interface that all curve certificate verifiers (eg. BN254, ECDSA) must implement
46+
interface IBN254CertificateVerifier is IBN254CertificateVerifierEvents, IBaseCertificateVerifier {
47+
/**
48+
* @notice updates the operator table
49+
* @param operatorSet the operatorSet to update the operator table for
50+
* @param referenceTimestamp the timestamp at which the operatorInfos were sourced
51+
* @param operatorSetInfo the operatorInfos to update the operator table with
52+
* @param operatorSetConfig the configuration of the operatorSet
53+
* @dev only callable by the operatorTableUpdater for the given operatorSet
54+
* @dev The `referenceTimestamp` must be greater than the latest reference timestamp for the given operatorSet
55+
*/
56+
function updateOperatorTable(
57+
OperatorSet calldata operatorSet,
58+
uint32 referenceTimestamp,
59+
BN254OperatorSetInfo memory operatorSetInfo,
60+
OperatorSetConfig calldata operatorSetConfig
61+
) external;
62+
63+
/**
64+
* @notice verifies a certificate
65+
* @param operatorSet the operatorSet that the certificate is for
66+
* @param cert a certificate
67+
* @return signedStakes amount of stake that signed the certificate for each stake
68+
* type
69+
*/
70+
function verifyCertificate(
71+
OperatorSet memory operatorSet,
72+
BN254Certificate memory cert
73+
) external returns (uint256[] memory signedStakes);
74+
75+
/**
76+
* @notice verifies a certificate and makes sure that the signed stakes meet
77+
* provided portions of the total stake on the AVS
78+
* @param operatorSet the operatorSet that the certificate is for
79+
* @param cert a certificate
80+
* @param totalStakeProportionThresholds the proportion of total stake that
81+
* the signed stake of the certificate should meet
82+
* @return whether or not certificate is valid and meets thresholds
83+
*/
84+
function verifyCertificateProportion(
85+
OperatorSet memory operatorSet,
86+
BN254Certificate memory cert,
87+
uint16[] memory totalStakeProportionThresholds
88+
) external returns (bool);
89+
90+
/**
91+
* @notice verifies a certificate and makes sure that the signed stakes meet
92+
* provided nominal stake thresholds
93+
* @param operatorSet the operatorSet that the certificate is for
94+
* @param cert a certificate
95+
* @param totalStakeNominalThresholds the nominal amount of stake that
96+
* the signed stake of the certificate should meet
97+
* @return whether or not certificate is valid and meets thresholds
98+
*/
99+
function verifyCertificateNominal(
100+
OperatorSet memory operatorSet,
101+
BN254Certificate memory cert,
102+
uint256[] memory totalStakeNominalThresholds
103+
) external returns (bool);
104+
}

‎src/contracts/interfaces/IBN254TableCalculator.sol‎

Lines changed: 70 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,70 @@
1+
// SPDX-License-Identifier: BUSL-1.1
2+
pragma solidity ^0.8.27;
3+
4+
import "src/contracts/libraries/BN254.sol";
5+
import "src/contracts/libraries/OperatorSetLib.sol";
6+
7+
interface IBN254TableCalculatorTypes {
8+
/**
9+
* @notice A struct that contains information about a single operator
10+
* @param pubkey The G1 public key of the operator.
11+
* @param weights The weights of the operator for a single operatorSet.
12+
* @dev The `weights` array can be defined as a list of arbitrary groupings. For example,
13+
* it can be [slashable_stake, delegated_stake, strategy_i_stake, ...]
14+
*/
15+
struct BN254OperatorInfo {
16+
BN254.G1Point pubkey;
17+
uint256[] weights;
18+
}
19+
20+
/**
21+
* @notice A struct that contains information about all operators for a given operatorSet
22+
* @param operatorInfoTreeRoot The root of the operatorInfo tree.
23+
* @param numOperators The number of operators in the operatorSet.
24+
* @param aggregatePubkey The aggregate G1 public key of the operators in the operatorSet.
25+
* @param totalWeights The total weights of the operators in the operatorSet.
26+
*
27+
* @dev The operatorInfoTreeRoot is the root of a merkle tree that contains the operatorInfos for each operator in the operatorSet.
28+
* It is calculated in this function and used by the `IBN254CertificateVerifier` to verify stakes against the non-signing operators
29+
*
30+
* @dev Retrieval of the `aggregatePubKey` depends on maintaining a key registry contract, see `BLSAPKRegistry` for an example implementation.
31+
*
32+
* @dev The `totalWeights` array should be the same length as each individual `weights` array in `operatorInfos`.
33+
*/
34+
struct BN254OperatorSetInfo {
35+
bytes32 operatorInfoTreeRoot;
36+
uint256 numOperators;
37+
BN254.G1Point aggregatePubkey;
38+
uint256[] totalWeights;
39+
}
40+
}
41+
42+
interface IBN254TableCalculator is IBN254TableCalculatorTypes {
43+
/**
44+
* @notice calculates the operatorInfos for a given operatorSet
45+
* @param operatorSet the operatorSet to calculate the operator table for
46+
* @return operatorSetInfo the operatorSetInfo for the given operatorSet
47+
* @dev The output of this function is converted to bytes via the `calculateOperatorTableBytes` function
48+
*/
49+
function calculateOperatorTable(
50+
OperatorSet calldata operatorSet
51+
) external view returns (BN254OperatorSetInfo memory operatorSetInfo);
52+
53+
/**
54+
* @notice calculates the operatorInfos for a given operatorSet
55+
* @param operatorSet the operatorSet to calculate the operator table for
56+
* @return operatorTableBytes the operatorTableBytes for the given operatorSet
57+
*/
58+
function calculateOperatorTableBytes(
59+
OperatorSet calldata operatorSet
60+
) external view returns (bytes memory operatorTableBytes);
61+
62+
/**
63+
* @notice Get the operatorInfos for a given operatorSet
64+
* @param operatorSet the operatorSet to get the operatorInfos for
65+
* @return operatorInfos the operatorInfos for the given operatorSet
66+
*/
67+
function getOperatorInfos(
68+
OperatorSet calldata operatorSet
69+
) external view returns (BN254OperatorInfo[] memory operatorInfos);
70+
}

‎src/contracts/interfaces/IBaseCertificateVerifier.sol‎

Lines changed: 60 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,60 @@
1+
// SPDX-License-Identifier: BUSL-1.1
2+
pragma solidity ^0.8.27;
3+
4+
import "src/contracts/libraries/OperatorSetLib.sol";
5+
import "src/contracts/interfaces/ICrossChainRegistry.sol";
6+
7+
interface IBaseCertificateVerifierTypes is ICrossChainRegistryTypes {
8+
// TODO: use the `KeyType` from `KeyRegistrar`
9+
/**
10+
* @notice The type of key used by the operatorSet. An OperatorSet can
11+
* only generate one Operator Table for an OperatorSet for a given OperatorKeyType.
12+
*/
13+
enum OperatorKeyType {
14+
ECDSA,
15+
BN254
16+
}
17+
}
18+
19+
interface IBaseCertificateVerifierEvents is IBaseCertificateVerifierTypes {
20+
/// @notice Emitted when the owner of an operatorSet is updated
21+
event OperatorSetOwnerUpdated(OperatorSet operatorSet, address owner);
22+
23+
/// @notice Emitted when the max staleness period of an operatorSet is updated
24+
event MaxStalenessPeriodUpdated(OperatorSet operatorSet, uint32 maxStalenessPeriod);
25+
}
26+
27+
interface IBaseCertificateVerifierErrors {
28+
/// @notice Thrown when the table updater is not caller
29+
error OnlyTableUpdater();
30+
/// @notice Thrown when the table update is stale
31+
error TableUpdateStale();
32+
/// @notice Thrown when array lengths mismatch
33+
error ArrayLengthMismatch();
34+
/// @notice Thrown when the certificate is too stale
35+
error CertificateStale();
36+
/// @notice Thrown when the reference timestamp does not exist
37+
error ReferenceTimestampDoesNotExist();
38+
/// @notice Thrown when certificate verification fails
39+
error VerificationFailed();
40+
}
41+
42+
/// @notice A base interface that verifies certificates for a given operatorSet
43+
/// @notice This is a base interface that all curve certificate verifiers (eg. BN254, ECDSA) must implement
44+
/// @dev A single `CertificateVerifier` can be used for ONLY 1 operatorSet
45+
interface IBaseCertificateVerifier is IBaseCertificateVerifierEvents, IBaseCertificateVerifierErrors {
46+
/// @notice the address of the owner of the OperatorSet
47+
function getOperatorSetOwner(
48+
OperatorSet memory operatorSet
49+
) external returns (address);
50+
51+
/// @return the maximum amount of seconds that a operator table can be in the past for a given operatorSet
52+
function maxOperatorTableStaleness(
53+
OperatorSet memory operatorSet
54+
) external returns (uint32);
55+
56+
/// @notice The latest reference timestamp of the operator table for a given operatorSet
57+
function latestReferenceTimestamp(
58+
OperatorSet memory operatorSet
59+
) external returns (uint32);
60+
}

‎src/contracts/interfaces/ICrossChainRegistry.sol‎

Lines changed: 126 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,126 @@
1+
// SPDX-License-Identifier: BUSL-1.1
2+
pragma solidity ^0.8.27;
3+
4+
import "src/contracts/libraries/OperatorSetLib.sol";
5+
6+
interface IOperatorTableCalculator {
7+
// TODO: implement, stub for now
8+
}
9+
10+
interface ICrossChainRegistryErrors {
11+
/// @notice Thrown when the chainId is invalid
12+
error InvalidChainId();
13+
}
14+
15+
interface ICrossChainRegistryTypes {
16+
/**
17+
* @notice A per-operatorSet configuration struct that is transported from the CrossChainRegistry on L1.
18+
* @param owner the permissioned owner of the OperatorSet on L2 that can call the CertificateVerifier specific setters
19+
* @param maxStalenessPeriod the maximum staleness period of the operatorSet
20+
*/
21+
struct OperatorSetConfig {
22+
address owner;
23+
uint32 maxStalenessPeriod;
24+
}
25+
}
26+
27+
interface ICrossChainRegistryEvents {
28+
/// @notice Emitted when a generation reservation is made
29+
event GenerationReservationMade(OperatorSet operatorSet, IOperatorTableCalculator operatorTableCalculator);
30+
31+
/// @notice Emitted when a generation reservation is removed
32+
event GenerationReservationRemoved(OperatorSet operatorSet, IOperatorTableCalculator operatorTableCalculator);
33+
34+
/// @notice Emitted when a transport destination is added
35+
event TransportDestinationAdded(OperatorSet operatorSet, uint32 chainID);
36+
37+
/// @notice Emitted when a transport destination is removed
38+
event TransportDestinationRemoved(OperatorSet operatorSet, uint32 chainID);
39+
40+
/// @notice Emitted when a chainID is added to the whitelist
41+
event ChainIDAddedToWhitelist(uint32 chainID);
42+
43+
/// @notice Emitted when a chainID is removed from the whitelist
44+
event ChainIDRemovedFromWhitelist(uint32 chainID);
45+
}
46+
47+
interface ICrossChainRegistry is ICrossChainRegistryErrors, ICrossChainRegistryTypes, ICrossChainRegistryEvents {
48+
/**
49+
* @notice Initiates a generation reservation
50+
* @param operatorSet the operatorSet to make a reservation for
51+
* @param operatorTableCalculator the address of the operatorTableCalculator
52+
* @dev msg.sender must be UAM permissioned for operatorSet.avs
53+
*/
54+
function requestGenerationReservation(OperatorSet calldata operatorSet, address operatorTableCalculator) external;
55+
56+
/**
57+
* @notice Removes a generation reservation for a given operatorSet
58+
* @param operatorSet the operatorSet to remove
59+
* @dev msg.sender must be UAM permissioned for operatorSet.avs
60+
*/
61+
function removeGenerationReservation(
62+
OperatorSet calldata operatorSet
63+
) external;
64+
65+
/**
66+
* @notice Adds a destination chain to transport to
67+
* @param chainID to add transport to
68+
* @dev msg.sender must be UAM permissioned for operatorSet.avs
69+
*/
70+
function addTransportDestination(OperatorSet calldata operatorSet, uint32 chainID) external;
71+
72+
/**
73+
* @notice Removes a destination chain to transport to
74+
* @param chainID to remove transport to
75+
* @dev msg.sender must be UAM permissioned for operatorSet.avs
76+
*/
77+
function removeTransportDestination(OperatorSet calldata operatorSet, uint32 chainID) external;
78+
79+
/**
80+
* @notice Sets the operatorTableCalculator for the operatorSet
81+
* @param operatorSet the operatorSet whose operatorTableCalculator is desired to be set
82+
* @param calculator the contract to call to calculate the operator table
83+
* @dev msg.sender must be UAM permissioned for operatorSet.avs
84+
* @dev operatorSet must have an active reservation
85+
*/
86+
function setOperatorTableCalculator(
87+
OperatorSet calldata operatorSet,
88+
IOperatorTableCalculator calculator
89+
) external;
90+
91+
/**
92+
* @notice Adds a chainID to the whitelist of chainIDs that can be transported to
93+
* @param chainID the chainID to add to the whitelist
94+
* @dev msg.sender must be UAM permissioned for operatorSet.avs
95+
*/
96+
function addChainIDToWhitelist(
97+
uint32 chainID
98+
) external;
99+
100+
/**
101+
* @notice Removes a chainID from the whitelist of chainIDs that can be transported to
102+
* @param chainID the chainID to remove from the whitelist
103+
* @dev msg.sender must be UAM permissioned for operatorSet.avs
104+
*/
105+
function removeChainIDFromWhitelist(
106+
uint32 chainID
107+
) external;
108+
109+
/**
110+
* @notice Gets the operatorTableCalculator for a given operatorSet
111+
* @param operatorSet the operatorSet to get the operatorTableCalculator for
112+
* @return The operatorTableCalculator for the given operatorSet
113+
*/
114+
function getOperatorTableCalculator(
115+
OperatorSet calldata operatorSet
116+
) external returns (IOperatorTableCalculator);
117+
118+
/**
119+
* @notice Gets the active generation reservations
120+
* @return An array of operatorSets with active generationReservations
121+
* @return An array of the corresponding operatorTableCalculators
122+
*/
123+
function getActiveGenerationReservations()
124+
external
125+
returns (OperatorSet[] memory, IOperatorTableCalculator[] memory);
126+
}

0 commit comments

Comments
 (0)