IConsensusRegistry
Author: Matter Labs
Note: security-contact: security@matterlabs.dev
Functions
add
Adds a new validator to the registry.
Fails if validator owner already exists.
Fails if a validator with the same public key already exists.
function add(
address _validatorOwner,
bool _validatorIsLeader,
uint32 _validatorWeight,
BLS12_381PublicKey calldata _validatorPubKey,
BLS12_381Signature calldata _validatorPoP
) external;
Parameters
| Name | Type | Description |
|---|---|---|
_validatorOwner | address | The address of the validator's owner. |
_validatorIsLeader | bool | Flag indicating if the validator is a leader. |
_validatorWeight | uint32 | The voting weight of the validator. |
_validatorPubKey | BLS12_381PublicKey | The BLS12-381 public key of the validator. |
_validatorPoP | BLS12_381Signature | The proof-of-possession (PoP) of the validator's public key. |
remove
Removes a validator from the registry.
Only callable by the contract owner.
Verifies that the validator owner exists in the registry.
function remove(address _validatorOwner) external;
Parameters
| Name | Type | Description |
|---|---|---|
_validatorOwner | address | The address of the owner of the validator to be removed. |
changeValidatorActive
Changes the active status of a validator, determining whether it can participate in committees.
Only callable by the contract owner or the validator owner.
Verifies that the validator owner exists in the registry.
function changeValidatorActive(address _validatorOwner, bool _isActive)
external;
Parameters
| Name | Type | Description |
|---|---|---|
_validatorOwner | address | The address of the owner of the validator whose active status will be changed. |
_isActive | bool | The new active status to assign to the validator. |
changeValidatorLeader
Changes the validator's leader status in the registry.
Only callable by the contract owner.
Verifies that the validator owner exists in the registry.
function changeValidatorLeader(address _validatorOwner, bool _isLeader)
external;
Parameters
| Name | Type | Description |
|---|---|---|
_validatorOwner | address | The address of the owner of the validator whose leader status will be changed. |
_isLeader | bool | The new leader status to assign to the validator. |
changeValidatorWeight
Changes the validator weight of a validator in the registry.
Only callable by the contract owner.
Verifies that the validator owner exists in the registry.
function changeValidatorWeight(address _validatorOwner, uint32 _weight)
external;
Parameters
| Name | Type | Description |
|---|---|---|
_validatorOwner | address | The address of the owner of the validator whose weight will be changed. |
_weight | uint32 | The new validator weight to assign to the validator. |
changeValidatorKey
Changes the validator's public key and proof-of-possession in the registry.
Only callable by the contract owner or the validator owner.
Verifies that the validator owner exists in the registry.
function changeValidatorKey(
address _validatorOwner,
BLS12_381PublicKey calldata _pubKey,
BLS12_381Signature calldata _pop
) external;
Parameters
| Name | Type | Description |
|---|---|---|
_validatorOwner | address | The address of the owner of the validator whose key and PoP will be changed. |
_pubKey | BLS12_381PublicKey | The new BLS12-381 public key to assign to the validator. |
_pop | BLS12_381Signature | The new proof-of-possession (PoP) to assign to the validator. |
commitValidatorCommittee
Adds a new commit to the validator committee using the current block number plus delay.
The committee will become active after committeeActivationDelay blocks.
Only callable by the contract owner.
Reverts if validatorsCommitBlock is still in the future.
function commitValidatorCommittee() external;
getValidatorCommittee
Returns an array of ValidatorAttr structs representing the current validator committee and the current leader selection configuration.
Collects active and non-removed validators based on the latest commit to the committee.
function getValidatorCommittee()
external
view
returns (CommitteeValidator[] memory, LeaderSelectionAttr memory);
getNextValidatorCommittee
Returns an array of ValidatorAttr structs representing the pending validator committee and the pending leader selection configuration.
Collects active and non-removed validators that will form the next committee after the current commit becomes active.
Reverts if there is no pending committee (when block.number >= validatorsCommitBlock).
function getNextValidatorCommittee()
external
view
returns (CommitteeValidator[] memory, LeaderSelectionAttr memory);
setCommitteeActivationDelay
Updates the delay for committee activation
Only callable by the contract owner
function setCommitteeActivationDelay(uint256 _delay) external;
Parameters
| Name | Type | Description |
|---|---|---|
_delay | uint256 | The new delay in blocks |
updateLeaderSelection
Updates the leader selection configuration
Only callable by the contract owner
function updateLeaderSelection(uint64 _frequency, bool _weighted) external;
Parameters
| Name | Type | Description |
|---|---|---|
_frequency | uint64 | The number of views between leader changes. If it is 0 then the leader never rotates. |
_weighted | bool | Whether leaders are selected proportionally to their weight. If false, then the leader is selected round-robin. |
Events
ValidatorAdded
event ValidatorAdded(
address indexed validatorOwner,
uint32 validatorWeight,
BLS12_381PublicKey validatorPubKey,
BLS12_381Signature validatorPoP
);
ValidatorRemoved
event ValidatorRemoved(address indexed validatorOwner);
ValidatorDeleted
event ValidatorDeleted(address indexed validatorOwner);
ValidatorActiveStatusChanged
event ValidatorActiveStatusChanged(
address indexed validatorOwner, bool isActive
);
ValidatorLeaderStatusChanged
event ValidatorLeaderStatusChanged(
address indexed validatorOwner, bool isLeader
);
ValidatorWeightChanged
event ValidatorWeightChanged(address indexed validatorOwner, uint32 newWeight);
ValidatorKeyChanged
event ValidatorKeyChanged(
address indexed validatorOwner,
BLS12_381PublicKey newPubKey,
BLS12_381Signature newPoP
);
ValidatorsCommitted
event ValidatorsCommitted(
uint32 validatorsCommit, uint256 validatorsCommitBlock
);
CommitteeActivationDelayChanged
event CommitteeActivationDelayChanged(uint256 newDelay);
LeaderSelectionChanged
event LeaderSelectionChanged(LeaderSelectionAttr newLeaderSelection);
Errors
UnauthorizedOnlyOwnerOrValidatorOwner
error UnauthorizedOnlyOwnerOrValidatorOwner();
ValidatorOwnerExists
error ValidatorOwnerExists();
ValidatorOwnerDoesNotExist
error ValidatorOwnerDoesNotExist();
ValidatorOwnerNotFound
error ValidatorOwnerNotFound();
ValidatorPubKeyExists
error ValidatorPubKeyExists();
InvalidInputValidatorOwnerAddress
error InvalidInputValidatorOwnerAddress();
InvalidInputBLS12_381PublicKey
error InvalidInputBLS12_381PublicKey();
InvalidInputBLS12_381Signature
error InvalidInputBLS12_381Signature();
NoPendingCommittee
error NoPendingCommittee();
PreviousCommitStillPending
error PreviousCommitStillPending();
NoActiveLeader
error NoActiveLeader();
Structs
Validator
Represents a validator in the consensus protocol.
struct Validator {
uint32 ownerIdx;
uint32 lastSnapshotCommit;
uint32 previousSnapshotCommit;
ValidatorAttr latest;
ValidatorAttr snapshot;
ValidatorAttr previousSnapshot;
}
Properties
| Name | Type | Description |
|---|---|---|
ownerIdx | uint32 | Index of the validator owner within the array of validator owners. |
lastSnapshotCommit | uint32 | The validatorsCommit value when the last snapshot of this validator was made. |
previousSnapshotCommit | uint32 | The validatorsCommit value when the previous snapshot of this validator was made. |
latest | ValidatorAttr | Validator attributes to read if validatorsCommit > validator.lastSnapshotCommit. |
snapshot | ValidatorAttr | Validator attributes to read if validatorsCommit > validator.previousSnapshot. |
previousSnapshot | ValidatorAttr | Validator attributes to read for older commits. |
ValidatorAttr
Represents the attributes of a validator.
struct ValidatorAttr {
bool active;
bool removed;
bool leader;
uint32 weight;
BLS12_381PublicKey pubKey;
BLS12_381Signature proofOfPossession;
}
Properties
| Name | Type | Description |
|---|---|---|
active | bool | A flag stating if the validator is active. |
removed | bool | A flag stating if the validator has been removed (and is pending a deletion). |
leader | bool | A flag stating if the validator is eligible to be a leader. |
weight | uint32 | Validator's voting weight. |
pubKey | BLS12_381PublicKey | Validator's BLS12-381 public key. |
proofOfPossession | BLS12_381Signature | Validator's Proof-of-possession (a signature over the public key). |
LeaderSelection
Represents the leader selection process in the consensus protocol.
struct LeaderSelection {
uint32 lastSnapshotCommit;
uint32 previousSnapshotCommit;
LeaderSelectionAttr latest;
LeaderSelectionAttr snapshot;
LeaderSelectionAttr previousSnapshot;
}
Properties
| Name | Type | Description |
|---|---|---|
lastSnapshotCommit | uint32 | The validatorsCommit value when the last snapshot was made. |
previousSnapshotCommit | uint32 | The validatorsCommit value when the previous snapshot was made. |
latest | LeaderSelectionAttr | LeaderSelectionAttr to read if validatorsCommit > lastSnapshotCommit. |
snapshot | LeaderSelectionAttr | LeaderSelectionAttr to read if validatorsCommit > previousSnapshot. |
previousSnapshot | LeaderSelectionAttr | LeaderSelectionAttr to read for older commits. |
LeaderSelectionAttr
Attributes for the validator leader selection process.
struct LeaderSelectionAttr {
uint64 frequency;
bool weighted;
}
Properties
| Name | Type | Description |
|---|---|---|
frequency | uint64 | The number of views between leader changes. If it is 0 then the leader never rotates. |
weighted | bool | Whether leaders are selectedproportionally to their weight. If false, then the leader is selected round-robin. |
CommitteeValidator
Represents a validator within a committee.
struct CommitteeValidator {
bool leader;
uint32 weight;
BLS12_381PublicKey pubKey;
BLS12_381Signature proofOfPossession;
}
Properties
| Name | Type | Description |
|---|---|---|
leader | bool | A flag stating if the validator is eligible to be a leader. |
weight | uint32 | Validator's voting weight. |
pubKey | BLS12_381PublicKey | Validator's BLS12-381 public key. |
proofOfPossession | BLS12_381Signature | Validator's Proof-of-possession (a signature over the public key). |
BLS12_381PublicKey
Represents BLS12_381 public key.
struct BLS12_381PublicKey {
bytes32 a;
bytes32 b;
bytes32 c;
}
Properties
| Name | Type | Description |
|---|---|---|
a | bytes32 | First component of the BLS12-381 public key. |
b | bytes32 | Second component of the BLS12-381 public key. |
c | bytes32 | Third component of the BLS12-381 public key. |
BLS12_381Signature
Represents BLS12_381 signature.
struct BLS12_381Signature {
bytes32 a;
bytes16 b;
}
Properties
| Name | Type | Description |
|---|---|---|
a | bytes32 | First component of the BLS12-381 signature. |
b | bytes16 | Second component of the BLS12-381 signature. |