VettedGate
VettedGate.sol is a supplementary contract that enables Node Operator creation for the vetted addresses, which serves as an entry point to CSModule.sol. Alongside Node Operator creation, a contract can assign a custom Node Operator type (bondCurveId) in CSAccounting.sol. Deployed using VettedGateFactory.sol to allow plugging of the new instances later without additional code security audits. The list of the vetted participants is upgradable for each instance of the VettedGate.sol individually.
Upgradability​
The contract uses OssifiableProxy for upgradability.
State Variables​
PAUSE_ROLE​
bytes32 public constant PAUSE_ROLE = keccak256("PAUSE_ROLE");
RESUME_ROLE​
bytes32 public constant RESUME_ROLE = keccak256("RESUME_ROLE");
RECOVERER_ROLE​
bytes32 public constant RECOVERER_ROLE = keccak256("RECOVERER_ROLE");
SET_TREE_ROLE​
bytes32 public constant SET_TREE_ROLE = keccak256("SET_TREE_ROLE");
START_REFERRAL_SEASON_ROLE​
bytes32 public constant START_REFERRAL_SEASON_ROLE = keccak256("START_REFERRAL_SEASON_ROLE");
END_REFERRAL_SEASON_ROLE​
bytes32 public constant END_REFERRAL_SEASON_ROLE = keccak256("END_REFERRAL_SEASON_ROLE");
MODULE​
Address of the Staking Module
ICSModule public immutable MODULE;
ACCOUNTING​
Address of the CS Accounting
ICSAccounting public immutable ACCOUNTING;
curveId​
Id of the bond curve to be assigned for the eligible members
uint256 public curveId;
treeRoot​
Root of the eligible members Merkle Tree
bytes32 public treeRoot;
treeCid​
CID of the eligible members Merkle Tree
string public treeCid;
isReferralProgramSeasonActive​
Optional referral program ///
bool public isReferralProgramSeasonActive;
referralProgramSeasonNumber​
uint256 public referralProgramSeasonNumber;
referralCurveId​
Id of the bond curve for referral program
uint256 public referralCurveId;
referralsThreshold​
Number of referrals required for bond curve claim
uint256 public referralsThreshold;
Functions​
resume​
Resume the contract
function resume() external onlyRole(RESUME_ROLE);
pauseFor​
Pause the contract for a given duration Pausing the contract prevent creating new node operators using VettedGate and claiming beneficial curve for the existing ones
function pauseFor(uint256 duration) external onlyRole(PAUSE_ROLE);
Parameters
| Name | Type | Description |
|---|---|---|
duration | uint256 | Duration of the pause |
startNewReferralProgramSeason​
Start referral program season
function startNewReferralProgramSeason(uint256 _referralCurveId, uint256 _referralsThreshold)
external
onlyRole(START_REFERRAL_SEASON_ROLE)
returns (uint256 season);
Parameters
| Name | Type | Description |
|---|---|---|
_referralCurveId | uint256 | Curve Id for the referral curve |
_referralsThreshold | uint256 | Minimum number of referrals to be eligible to claim the curve |
Returns
| Name | Type | Description |
|---|---|---|
season | uint256 | Id of the started season |
endCurrentReferralProgramSeason​
End referral program season
function endCurrentReferralProgramSeason() external onlyRole(END_REFERRAL_SEASON_ROLE);
addNodeOperatorETH​
Add a new Node Operator using ETH as a bond. At least one deposit data and corresponding bond should be provided
function addNodeOperatorETH(
uint256 keysCount,
bytes calldata publicKeys,
bytes calldata signatures,
NodeOperatorManagementProperties calldata managementProperties,
bytes32[] calldata proof,
address referrer
) external payable whenResumed returns (uint256 nodeOperatorId);
Parameters
| Name | Type | Description |
|---|---|---|
keysCount | uint256 | Signing keys count |
publicKeys | bytes | Public keys to submit |
signatures | bytes | Signatures of (deposit_message_root, domain) tuples https://github.com/ethereum/consensus-specs/blob/v1.4.0/specs/phase0/beacon-chain.md#signingdata |
managementProperties | NodeOperatorManagementProperties | Optional. Management properties to be used for the Node Operator. managerAddress: Used as managerAddress for the Node Operator. If not passed msg.sender will be used. rewardAddress: Used as rewardAddress for the Node Operator. If not passed msg.sender will be used. extendedManagerPermissions: Flag indicating that managerAddress will be able to change rewardAddress. If set to true resetNodeOperatorManagerAddress method will be disabled |
proof | bytes32[] | Merkle proof of the sender being eligible to join via the gate |
referrer | address | Optional. Referrer address. Should be passed when Node Operator is created using partners integration |
Returns
| Name | Type | Description |
|---|---|---|
nodeOperatorId | uint256 | Id of the created Node Operator |
addNodeOperatorStETH​
Add a new Node Operator using stETH as a bond. At least one deposit data and corresponding bond should be provided
function addNodeOperatorStETH(
uint256 keysCount,
bytes calldata publicKeys,
bytes calldata signatures,
NodeOperatorManagementProperties calldata managementProperties,
ICSAccounting.PermitInput calldata permit,
bytes32[] calldata proof,
address referrer
) external whenResumed returns (uint256 nodeOperatorId);
Parameters
| Name | Type | Description |
|---|---|---|
keysCount | uint256 | Signing keys count |
publicKeys | bytes | Public keys to submit |
signatures | bytes | Signatures of (deposit_message_root, domain) tuples https://github.com/ethereum/consensus-specs/blob/v1.4.0/specs/phase0/beacon-chain.md#signingdata |
managementProperties | NodeOperatorManagementProperties | Optional. Management properties to be used for the Node Operator. managerAddress: Used as managerAddress for the Node Operator. If not passed msg.sender will be used. rewardAddress: Used as rewardAddress for the Node Operator. If not passed msg.sender will be used. extendedManagerPermissions: Flag indicating that managerAddress will be able to change rewardAddress. If set to true resetNodeOperatorManagerAddress method will be disabled |
permit | ICSAccounting.PermitInput | Optional. Permit to use stETH as bond |
proof | bytes32[] | Merkle proof of the sender being eligible to join via the gate |
referrer | address | Optional. Referrer address. Should be passed when Node Operator is created using partners integration |
Returns
| Name | Type | Description |
|---|---|---|
nodeOperatorId | uint256 | Id of the created Node Operator |
addNodeOperatorWstETH​
Add a new Node Operator using wstETH as a bond. At least one deposit data and corresponding bond should be provided
function addNodeOperatorWstETH(
uint256 keysCount,
bytes calldata publicKeys,
bytes calldata signatures,
NodeOperatorManagementProperties calldata managementProperties,
ICSAccounting.PermitInput calldata permit,
bytes32[] calldata proof,
address referrer
) external whenResumed returns (uint256 nodeOperatorId);
Parameters
| Name | Type | Description |
|---|---|---|
keysCount | uint256 | Signing keys count |
publicKeys | bytes | Public keys to submit |
signatures | bytes | Signatures of (deposit_message_root, domain) tuples https://github.com/ethereum/consensus-specs/blob/v1.4.0/specs/phase0/beacon-chain.md#signingdata |
managementProperties | NodeOperatorManagementProperties | Optional. Management properties to be used for the Node Operator. managerAddress: Used as managerAddress for the Node Operator. If not passed msg.sender will be used. rewardAddress: Used as rewardAddress for the Node Operator. If not passed msg.sender will be used. extendedManagerPermissions: Flag indicating that managerAddress will be able to change rewardAddress. If set to true resetNodeOperatorManagerAddress method will be disabled |
permit | ICSAccounting.PermitInput | Optional. Permit to use wstETH as bond |
proof | bytes32[] | Merkle proof of the sender being eligible to join via the gate |
referrer | address | Optional. Referrer address. Should be passed when Node Operator is created using partners integration |
Returns
| Name | Type | Description |
|---|---|---|
nodeOperatorId | uint256 | Id of the created Node Operator |
claimBondCurve​
Claim the bond curve for the eligible Node Operator
Should be called by the reward address of the Node Operator In case of the extended manager permissions, should be called by the manager address
function claimBondCurve(uint256 nodeOperatorId, bytes32[] calldata proof) external whenResumed;
Parameters
| Name | Type | Description |
|---|---|---|
nodeOperatorId | uint256 | Id of the Node Operator |
proof | bytes32[] | Merkle proof of the sender being eligible to join via the gate |
claimReferrerBondCurve​
Claim the referral program bond curve for the eligible Node Operator
function claimReferrerBondCurve(uint256 nodeOperatorId, bytes32[] calldata proof) external whenResumed;
Parameters
| Name | Type | Description |
|---|---|---|
nodeOperatorId | uint256 | Id of the Node Operator |
proof | bytes32[] | Merkle proof of the sender being eligible to join via the gate |
setTreeParams​
Set the root of the eligible members Merkle Tree
function setTreeParams(bytes32 _treeRoot, string calldata _treeCid) external onlyRole(SET_TREE_ROLE);
Parameters
| Name | Type | Description |
|---|---|---|
_treeRoot | bytes32 | New root of the Merkle Tree |
_treeCid | string | New CID of the Merkle Tree |
getReferralsCount​
Get the number of referrals for the given referrer in the current or last season
function getReferralsCount(address referrer) external view returns (uint256);
Parameters
| Name | Type | Description |
|---|---|---|
referrer | address | Referrer address |
Returns
| Name | Type | Description |
|---|---|---|
<none> | uint256 | Number of referrals for the given referrer in the current or last season |
getReferralsCount​
Get the number of referrals for the given referrer in the current or last season
function getReferralsCount(address referrer, uint256 season) external view returns (uint256);
Parameters
| Name | Type | Description |
|---|---|---|
referrer | address | Referrer address |
season | uint256 |
Returns
| Name | Type | Description |
|---|---|---|
<none> | uint256 | Number of referrals for the given referrer in the current or last season |
getInitializedVersion​
Returns the initialized version of the contract
function getInitializedVersion() external view returns (uint64);
isReferrerConsumed​
Check if the address has already consumed referral program bond curve
function isReferrerConsumed(address referrer) external view returns (bool);
Parameters
| Name | Type | Description |
|---|---|---|
referrer | address | Address to check |
Returns
| Name | Type | Description |
|---|---|---|
<none> | bool | Consumed flag |
isConsumed​
Check if the address has already consumed the curve
function isConsumed(address member) public view returns (bool);
Parameters
| Name | Type | Description |
|---|---|---|
member | address | Address to check |
Returns
| Name | Type | Description |
|---|---|---|
<none> | bool | Consumed flag |
verifyProof​
Check is the address is eligible to consume beneficial curve
function verifyProof(address member, bytes32[] calldata proof) public view returns (bool);
Parameters
| Name | Type | Description |
|---|---|---|
member | address | Address to check |
proof | bytes32[] | Merkle proof of the beneficial curve eligibility |
Returns
| Name | Type | Description |
|---|---|---|
<none> | bool | Boolean flag if the proof is valid or not |
hashLeaf​
Get a hash of a leaf in the Merkle tree
Double hash the leaf to prevent second preimage attacks
function hashLeaf(address member) public pure returns (bytes32);
Parameters
| Name | Type | Description |
|---|---|---|
member | address | eligible member address |
Returns
| Name | Type | Description |
|---|---|---|
<none> | bytes32 | Hash of the leaf |
Events​
TreeSet​
event TreeSet(bytes32 indexed treeRoot, string treeCid);
Consumed​
event Consumed(address indexed member);
ReferrerConsumed​
event ReferrerConsumed(address indexed referrer, uint256 indexed season);
ReferralProgramSeasonStarted​
event ReferralProgramSeasonStarted(uint256 indexed season, uint256 referralCurveId, uint256 referralsThreshold);
ReferralProgramSeasonEnded​
event ReferralProgramSeasonEnded(uint256 indexed season);
ReferralRecorded​
event ReferralRecorded(address indexed referrer, uint256 indexed season, uint256 indexed referralNodeOperatorId);