diff --git a/docs/developers/smart-contracts/ssvnetwork.md b/docs/developers/smart-contracts/ssvnetwork.md index 7794e0c..e98882c 100644 --- a/docs/developers/smart-contracts/ssvnetwork.md +++ b/docs/developers/smart-contracts/ssvnetwork.md @@ -4,26 +4,248 @@ sidebar_position: 1 # SSVNetwork -The SSVNetwork contract is the main contract for operations and management. +The SSVNetwork contract is the main contract for operations and management. -## Operator Methods +Methods are sorted by category: -### **`registerOperator(publicKey, operatorFee, setPrivate)`** +- [Cluster](#cluster-methods) +- [Operator](#operator-methods) +- [SSV Staking](#ssv-staking-methods) +- [Governance](#governance-methods) +- [Legacy](#legacy-methods) +- [Account](#account-methods) +- [Liquidator](#liquidator-methods) + +## Cluster Methods + +#### **`migrateClusterToETH(operatorIds, cluster)`** + +The ETH amount to deposit must be [supplied via `msg.value`](https://docs.ethers.org/v4/api-contract.html#overrides). + +| **Parameter** | **Type** | **Description** | +| ------------------- | -------- | ---------------------------------------------------- | +| operatorIds | uint64[] | An array of operator IDs of the cluster. | +| cluster | tuple\[] | Object containing the latest cluster snapshot data - obtained using the [SSV Subgraph](/developers/tools/ssv-subgraph/subgraph-examples#cluster-snapshot), or [SSV Scanner](/developers/tools/ssv-scanner) tools | + +Events: + +* `ClusterMigratedToETH(address owner, uint64[] operatorIds, uint256 ethDeposited, uint256 ssvRefunded, uint32 effectiveBalance, Cluster cluster)` +* *`ClusterReactivated(address indexed owner, uint64[] operatorIds, Cluster cluster)`* is **emitted only if** the cluster was liquidated prior to the migration. + +--- + +#### **`registerValidator(publicKey, operatorIds, shares, cluster)`** + +Registers new validator to a cluster of provided operators (ids + shares), **fails if** number of operatorIds is greater than 13. The ETH amount to deposit must be [supplied via `msg.value`](https://docs.ethers.org/v4/api-contract.html#overrides). + +:::info Breaking Changes +With the [introduction of ETH payments](https://ssv.network/blog/introduction-to-ssv-staking), the smart contract function signature has changed. The `amount` parameter has been removed, and the function is now `payable`. The ETH amount to deposit must be supplied via `msg.value`. Update your integrations accordingly, in line with [the ethers documentation](https://docs.ethers.org/v4/api-contract.html#overrides). +::: + +| **Parameter** | **Type** | **Description** | +| ------------- | -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| publicKey | bytes | The validator’s public key. | +| operatorIds | unit64\[] | List of cluster operators Ids. | +| sharesData | bytes | String of keyshares - obtained by splitting the validator key using the [SSV-Keys](../tools/ssv-keys) tool. | +| cluster | tuple\[] | Object containing the latest cluster snapshot data - obtained using the [SSV Subgraph](/developers/tools/ssv-subgraph/subgraph-examples#cluster-snapshot), or [SSV Scanner](/developers/tools/ssv-scanner) tools | +Events: + +* `ValidatorAdded(address indexed owner, uint64[] operatorIds, bytes publicKey, bytes shares, Cluster cluster)` + +--- + +#### **`bulkRegisterValidator(publicKey, operatorIds, shares, cluster)`** + +Description: Registers all the new validators provided as argument to a cluster of provided operators (ids + shares), **fails if** number of operatorIds is greater than 13. The ETH amount to deposit must be [supplied via `msg.value`](https://docs.ethers.org/v4/api-contract.html#overrides). + +:::info Breaking Changes +With the [introduction of ETH payments](https://ssv.network/blog/introduction-to-ssv-staking), the smart contract function signature has changed. The `amount` parameter has been removed, and the function is now `payable`. The ETH amount to deposit must be supplied via `msg.value`. Update your integrations accordingly, in line with [the ethers documentation](https://docs.ethers.org/v4/api-contract.html#overrides). +::: + +| **Parameter** | **Type** | **Description** | +| ------------- | -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| publicKeys | bytes\[] | An array of validators’ public keys. | +| operatorIds | unit64\[] | List of cluster operators Ids. | +| sharesData | bytes\[] | An array of strings of keyshares - obtained by splitting the validator key using the [SSV-Keys](../tools/ssv-keys) Each element in this array must relate to a public key in the publicKeys array. | +| cluster | tuple\[] | Object containing the latest cluster snapshot data - obtained using the [SSV Subgraph](/developers/tools/ssv-subgraph/subgraph-examples#cluster-snapshot), or [SSV Scanner](/developers/tools/ssv-scanner) tools | +Events: + +* `ValidatorAdded(address indexed owner, uint64[] operatorIds, bytes publicKey, bytes shares, Cluster cluster)` + +The function emits as many `ValidatorAdded` events, as is the length of the provided `publicKeys` array. + + +Please note: the number of validators that can be registered with the`bulkRegisterValidator` function is limited by the total transaction size. This depends both on the number of total public keys, as well as the number of operators in the chosen cluster, as follows: + +* 80 validator keyshares for a cluster of 4 operators +* 40 validator keyshares for a cluster of 7 operators +* 30 validator keyshares for a cluster of 10 operators +* 20 validator keyshares for a cluster of 13 operators + +--- + +#### **`removeValidator(publicKey, operatorIds, cluster)`** + +Description: Removes validator from the SSV network. + +| **Parameter** | **Type** | **Description** | +| ------------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| publicKey | bytes | The validator’s public key. | +| operatorIds | unit64\[] | List of cluster operators Ids. | +| cluster | tuple\[] | Object containing the latest cluster snapshot data - obtained using the [SSV Subgraph](../tools/ssv-subgraph/subgraph-examples.md#cluster-snapshot), or [SSV Scanner](../tools/ssv-scanner) tools. | + +Events: + +* `ValidatorRemoved(address indexed owner, uint64[] operatorIds, bytes publicKey, Cluster cluster)` + +--- + +#### **`bulkRemoveValidator(publicKey, operatorIds, cluster)`** + +Description: Removes all the validators provided as argument from the SSV network. + +| **Parameter** | **Type** | **Description** | +| ------------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| publicKeys | bytes\[] | An array of validators’ public keys. | +| operatorIds | unit64\[] | List of cluster operators Ids. | +| cluster | tuple\[] | Object containing the latest cluster snapshot data - obtained using the [SSV Subgraph](../tools/ssv-subgraph/subgraph-examples.md#cluster-snapshot), or [SSV Scanner](../tools/ssv-scanner) tools. | + +Events: + +* `ValidatorRemoved(address indexed owner, uint64[] operatorIds, bytes publicKey, Cluster cluster)` + +The function emits as many `ValidatorRemoved` events, as is the length of the provided `publicKeys` array. + +Please note: the number of validators that can be de-registered with the`bulkRemoveValidator` function is limited by the total transaction size to a maximum of **500 validator keys at a time.** + +--- + +#### **`exitValidator(publicKey, operatorIds)`** + +Description: Prompts SSV nodes to sign a voluntary exit of the validator. + +| **Parameter** | **Type** | **Description** | +| ------------- | --------- | ------------------------------ | +| publicKey | bytes | The validator’s public key. | +| operatorIds | unit64\[] | List of cluster operators Ids. | + +Events: + +* `ValidatorExited(address indexed owner, uint64[] operatorIds, bytes publicKey)` + +--- + +#### **`bulkExitValidator(publicKey, operatorIds)`** + +Description: Prompts SSV nodes to sign a voluntary exit for all the validators provided as argument. + +| **Parameter** | **Type** | **Description** | +| ------------- | --------- | ------------------------------------ | +| publicKeys | bytes\[] | An array of validators’ public keys. | +| operatorIds | unit64\[] | List of cluster operators Ids. | + +Events: + +* `ValidatorExited(address indexed owner, uint64[] operatorIds, bytes publicKey)` + +The function emits as many `ValidatorExited` events, as is the length of the provided `publicKeys` array. + + +Please note: the number of validators that can be requested to exit from the beacon chain with the`bulkExitValidator` function is limited by the total transaction size to a maximum of **500 validator keys at a time.** + + +--- + +#### **`deposit(owner, operatorIds, cluster)`** + +Description: Deposits ETH into a cluster balance, will fail if not enough tokens are approved. + +The ETH amount to deposit must be [supplied via `msg.value`](https://docs.ethers.org/v4/api-contract.html#overrides). + +:::info Breaking Changes +With the [introduction of ETH payments](https://ssv.network/blog/introduction-to-ssv-staking), the smart contract function signature has changed. The `amount` parameter has been removed, and the function is now `payable`. The ETH amount to deposit must be supplied via `msg.value`. Update your integrations accordingly, in line with [the ethers documentation](https://docs.ethers.org/v4/api-contract.html#overrides). +::: + +| **Parameter** | **Type** | **Description** | +| ------------- | -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| owner | address | The cluster owner address | +| operatorIds | unit64\[] | List of cluster operators Ids. | +| cluster | tuple\[] | Object containing the latest cluster snapshot data - obtained using the [SSV Subgraph](../tools/ssv-subgraph/subgraph-examples.md#cluster-snapshot), or [SSV Scanner](../tools/ssv-scanner) tools. | + +Events: + +* `ClusterDeposited(address indexed owner, uint64[] operatorIds, uint256 value, Cluster cluster)` + +--- + +#### **`withdraw(operatorIds, amount, cluster)`** + +Description: Withdraws a specified amount of ETH from cluster of msg.sender, **will fail if** msg.sender tries to withdraw more than the cluster’s liquidation collateral. To withdraw the entire cluster balance and stop its operation use liquidate(). + +| **Parameter** | **Type** | **Description** | +| ------------- | -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| operatorIds | unit64\[] | List of cluster operators Ids. | +| amount | uint256 | Amount to be withdrawn. Amount must be divisible by 100000 | +| cluster | tuple\[] | Object containing the latest cluster snapshot data - obtained using the [SSV Subgraph](../tools/ssv-subgraph/subgraph-examples.md#cluster-snapshot), or [SSV Scanner](../tools/ssv-scanner) tools. | + +Events: + +* `ClusterWithdrawn(address indexed owner, uint64[] operatorIds, uint256 value, Cluster cluster)` + +--- + +#### **`reactivate(operatorIds, cluster)`** + +Description: Reactivates a liquidated cluster, **will fail** if insufficient ETH to cover the cluster’s liquidation collateral have been deposited. The ETH amount to deposit must be [supplied via `msg.value`](https://docs.ethers.org/v4/api-contract.html#overrides). + +:::info Breaking Changes +With the [introduction of ETH payments](https://ssv.network/blog/introduction-to-ssv-staking), the smart contract function signature has changed. The `amount` parameter has been removed, and the function is now `payable`. The ETH amount to deposit must be supplied via `msg.value`. Update your integrations accordingly, in line with [the ethers documentation](https://docs.ethers.org/v4/api-contract.html#overrides). +::: + +| **Parameter** | **Type** | **Description** | +| ------------- | -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| operatorIds | unit64\[] | List of cluster operators Ids. | | +| cluster | tuple\[] | Object containing the latest cluster snapshot data - obtained using the [SSV Subgraph](../tools/ssv-subgraph/subgraph-examples.md#cluster-snapshot), or [SSV Scanner](../tools/ssv-scanner) tools. | + +Events: + +* `ClusterReactivated(address indexed owner, uint64[] operatorIds, Cluster cluster)` + +--- + +#### **`updateClusterBalance(cluster[], effectiveBalance, merkleProof)`** + +Description: Updates the effective balance for the cluster described by provided parameters. A merkle proof of the data has to also be provided to verify data validity. + +| **Parameter** | **Type** | **Description** | +| ------------- | --------- | ----------------------------- | +| effectiveBalance | uint32 | Cluster's new total effective balance | +| merkleProof[] | bytes32[] | Merkle proof of the data to verify data validity | +| cluster | tuple\[] | Object containing the latest cluster snapshot data - obtained using the [SSV Subgraph](../tools/ssv-subgraph/subgraph-examples.md#cluster-snapshot), or [SSV Scanner](../tools/ssv-scanner) tools. | + +Events: +* `ClusterBalanceUpdated(ctx.clusterOwner, operatorIds, ctx.blockNum, ctx.effectiveBalance, cluster)` + +## Operator Methods + +#### **`registerOperator(publicKey, fee, setPrivate)`** Description: Registers a new operator (key) with a set fee, **fails if** fee is less than the minimal fee. -| **Parameter** | **Type** | **Description** | -| ------------- | ------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| publicKey | bytes | The operator public key (generated as part of the node setup). | -| operatorFee | uint256(casted to uint64) | The fee charged by the operator (denominated as ETH per block) | -| setPrivate | bool | A flag to set the operator to private or public during registration. Calls the [**`setOperatorsPrivateUnchecked`**](ssvnetwork.md#setoperatorsprivateuncheckedoperatorids)function if set to true. | +| **Parameter** | **Type** | **Description** | +| ------------- | ------------------------------------ | --------------------------- | +| publicKey | bytes | The operator public key (generated as part of the node setup). | +| fee | uint256 | The fee charged by the operator (denominated as ETH per block) | +| setPrivate | boo | A flag to set the operator to private or public during registration. Calls the [**`setOperatorsPrivateUnchecked`**](ssvnetwork.md#setoperatorsprivateuncheckedoperatorids)function if set to true. | Events: * `OperatorAdded(uint64 indexed operatorId, address indexed owner, bytes publicKey, uint256 fee)` * `OperatorPrivacyStatusUpdated(uint64[] operatorIds, bool toPrivate)` -### **`removeOperator(operatorId)`** +--- + +#### **`removeOperator(operatorId)`** Description: Permanently removes the operator from the network (irreversible). @@ -35,20 +257,38 @@ Events: * `OperatorRemoved(uint64 indexed operatorId)` -### **`withdrawOperatorEarnings(operatorId)`** +--- + +#### **`withdrawOperatorEarnings(operatorId)`** Description: Withdraws a specified amount of ETH from provided operator balance to msg.sender, **will fail if** msg.sender is not the operator owner. -| **Parameter** | **Type** | **Description** | -| ------------- | -------------------------- | ---------------------------------------------------------------------------------------------------------------- | -| operatorId | uint64 | The operator id | -| amount | uint256 (casted to uint64) | Amount must be shrinkable (divisible by 10000000) | +| **Parameter** | **Type** | **Description** | +| ------------- | -------------------------- | --------------------------------------- | +| operatorId | uint64 | The operator id | +| amount | uint256 | Amount must be shrinkable (divisible by 100000) | + +Events: + +* `OperatorWithdrawn(address indexed owner, uint64 indexed operatorId, uint256 value)` + +--- + +#### **`withdrawAllOperatorEarnings(operatorId)`** + +Description: Withdraws all ETH earnings from provided operator balance to msg.sender, **will fail if** msg.sender is not the operator owner. + +| **Parameter** | **Type** | **Description** | +| ------------- | -------- | --------------- | +| operatorId | uint64 | The operator id | Events: * `OperatorWithdrawn(address indexed owner, uint64 indexed operatorId, uint256 value)` -### **`withdrawAllOperatorEarnings(operatorId)`** +--- + +#### **`withdrawAllVersionOperatorEarnings(operatorId)`** Description: Withdraws all ETH and SSV earnings from provided operator balance to msg.sender, **will fail if** msg.sender is not the operator owner. @@ -62,95 +302,111 @@ Events: * *`OperatorWithdrawnSSV(address indexed owner, uint64 indexed operatorId, uint256 value)`* is **emitted only if** the operator had any SSV tokens to withdraw. -### **`setOperatorsWhitelists (operatorIds, whitelisted)`** +--- + +#### **`setOperatorsWhitelists (operatorIds, whitelistAddresses)`** Description: For a list of operators provided, set a list of whitelisted addresses which can register validators to these operators. Subsequent calls of this function **extend the list** of whitelisted addresses, and **do not overwrite it**. | **Parameter** | **Type** | **Description** | | ------------- | ---------- | --------------------------------------------------------- | -| operatorId | uint64\[] | Operator ID list | -| whitelisted | address\[] | A list of ETH1 addresses to be whitelisted. | +| operatorIds | uint64\[] | Operator ID list | +| whitelistAddresses | address\[] | A list of ETH1 addresses to be whitelisted. | Events: * `OperatorMultipleWhitelistUpdated(uint64[] operatorIds, address[] whitelistAddresses)` -### **`removeOperatorsWhitelists (operatorIds, whitelisted)`** +--- + +#### **`removeOperatorsWhitelists (operatorIds, whitelistAddresses)`** Description: For a list of operators provided, remove a list of whitelisted addresses. | **Parameter** | **Type** | **Description** | | ------------- | ---------- | ------------------------------------------------------------------------ | -| operatorId | uint64\[] | Operator ID list | -| whitelisted | address\[] | A list of ETH1 addresses to be removed from the whitelist. | +| operatorIds | uint64\[] | Operator ID list | +| whitelistAddresses | address\[] | A list of ETH1 addresses to be removed from the whitelist. | Events: * `OperatorMultipleWhitelistRemoved(uint64[] operatorIds, address[] whitelistAddresses)` -### **`setOperatorsPrivateUnchecked(operatorIds)`** +--- + +#### **`setOperatorsPrivateUnchecked(operatorIds)`** Description: For a list of operators provided, set their status to private. | **Parameter** | **Type** | **Description** | | ------------- | --------- | ---------------- | -| operatorId | uint64\[] | Operator ID list | +| operatorIds | uint64\[] | Operator ID list | Events: * `OperatorPrivacyStatusUpdated(uint64[] operatorIds, bool toPrivate)` -### **`setOperatorsPublicUnchecked(operatorIds)`** +--- + +#### **`setOperatorsPublicUnchecked(operatorIds)`** Description: For a list of operators provided, set their status to public. | **Parameter** | **Type** | **Description** | | ------------- | --------- | ---------------- | -| operatorId | uint64\[] | Operator ID list | +| operatorIds | uint64\[] | Operator ID list | Events: * `OperatorPrivacyStatusUpdated(uint64[] operatorIds, bool toPrivate)` -### **`setOperatorsWhitelistingContract(operatorIds, whitelistingContract)`** +--- + +#### **`setOperatorsWhitelistingContract(operatorIds, whitelistingContract)`** Description: For a list of operators provided, set an external whitelisting contract to manage the whitelist for these operators. [Must be a valid whitelisting contract.](external-whitelist-contract-example.md) | **Parameter** | **Type** | **Description** | | -------------------- | ------------------------ | ---------------------------------------------------- | -| operatorId | uint64\[] | Operator ID list | +| operatorIds | uint64\[] | Operator ID list | | whitelistingContract | ISSVWhitelistingContract | A valid whitelisting contract address. | Events: * `OperatorWhitelistingContractUpdated(uint64[] operatorIds, address whitelistingContract)` -### **`removeOperatorsWhitelistingContract(operatorIds)`** +--- + +#### **`removeOperatorsWhitelistingContract(operatorIds)`** Description: For a list of operators provided, remove the whitelisting contract stored. | **Parameter** | **Type** | **Description** | | ------------- | --------- | ---------------- | -| operatorId | uint64\[] | Operator ID list | +| operatorIds | uint64\[] | Operator ID list | Events: * `OperatorWhitelistingContractUpdated(uint64[] operatorIds, address whitelistingContract)` -### **`declareOperatorFee(operatorId, operatorFee)`** +--- + +#### **`declareOperatorFee(operatorId, operatorFee)`** Description: Initiates the first step of the operator fee update cycle - declaration of a new fee. [After specified](ssvnetworkviews.md#getoperatorfeeperiods) time window operator will be able to change to the new fee with executeOperatorFee(). | **Parameter** | **Type** | **Description** | | ------------- | -------------------------- | ----------------------------------------------- | | operatorId | uint64 | The operator id | -| operatorFee | uint256 (casted to uint64) | New fee (denominated as ETH per block). | +| operatorFee | uint256 | New fee (denominated as ETH per block). | Events: * `OperatorFeeDeclared(address indexed owner, uint64 indexed operatorId, uint256 blockNumber, uint256 fee)` -### **`executeOperatorFee()`** +--- + +#### **`executeOperatorFee()`** Description: Activates operator’s fee change specified in previously called declareOperatorFee(). This function needs to be called within a [certain time window](ssvnetworkviews.md#getoperatorfeeperiods) following declareOperatorFee(). @@ -162,7 +418,9 @@ Events: * `OperatorFeeExecuted(address indexed owner, uint64 indexed operatorId, uint256 blockNumber, uint256 fee)` -### **`cancelDeclaredOperatorFee(operatorId)`** +--- + +#### **`cancelDeclaredOperatorFee(operatorId)`** Description: Cancels operator’s fee change requested in previously called declareOperatorFee(). @@ -174,242 +432,178 @@ Events: * `OperatorFeeDeclarationCancelled(address indexed owner, uint64 indexed operatorId)` -### **`reduceOperatorFee(operatorId, fee)`** +--- + +#### **`reduceOperatorFee(operatorId, fee)`** Description: Reduce the operator fee, does not abide by the restrictions of fee increase | Parameter | Type | Description | | ---------- | -------------------------- | ----------------------------------------------- | | operatorId | uint64 | The operator id | -| fee | uint256 (casted to uint64) | New fee (denominated as ETH per block). | +| fee | uint256 | New fee (denominated as ETH per block). | Events: * `OperatorFeeExecuted(address indexed owner, uint64 indexed operatorId, uint256 blockNumber, uint256 fee)` -## Account Methods +## SSV Staking Methods -### **`setFeeRecipientAddress(feeRecipientAddress)`** +#### **`stake(amount)`** -Description: sets a fee recipient address to receive tips from user transactions (part block proposal rewards). This address will be set for all the account’s validators (all clusters). +Description: User transfers the specified amount of SSV tokens to the contract to be staked and accrue rewards. The contract issues a corresponding amount of cSSV tokens in return, representing the stake. -| **Parameter** | **Type** | **Description** | -| ------------------- | -------- | ---------------------------------------------------- | -| feeRecipientAddress | address | An ETH1 address that receives fee recipient rewards. | +| **Parameter** | **Type** | **Description** | +| ------------- | --------- | ----------------------------- | +| amount | uint256 | SSV amount to stake, must be shrinkable (divisible by 10000000) | Events: +* `Staked(msg.sender, amount)` +* `RewardsSettled(user, pending, s.accrued[user], idx)` -* `FeeRecipientAddressUpdated(address indexed owner, address recipientAddress)` - -## Cluster Methods +--- -### **`migrateClusterToETH(operatorIds, amount, cluster)`** +#### **`claimEthRewards()`** -| **Parameter** | **Type** | **Description** | -| ------------------- | -------- | ---------------------------------------------------- | -| operatorIds | uint64[] | An array of operator IDs of the cluster. | -| amount | uint256 | Amount of ETH to deposit to cluster's balance after migration. | -| cluster | tuple\[] | Object containing the latest cluster snapshot data - obtained using the [SSV Subgraph](/developers/tools/ssv-subgraph/subgraph-examples#cluster-snapshot), or [SSV Scanner](/developers/tools/ssv-scanner) tools | +Description: Usable by former owners of cSSV tokens to claim ETH rewards accrued prior to the tokens transfer to a new owner. Initiator's address will be used. Events: +* `RewardsClaimed(msg.sender, payout)` +* `RewardsSettled(user, pending, s.accrued[user], idx)` -* `ClusterMigratedToETH(address owner, uint64[] operatorIds, uint256 ethDeposited, uint256 ssvRefunded, uint32 effectiveBalance, Cluster cluster)` -* *`ClusterReactivated(address indexed owner, uint64[] operatorIds, Cluster cluster)`* is **emitted only if** the cluster was liquidated prior to the migration. +--- -### **`registerValidator(publicKey, operatorIds, shares, cluster)`** +#### **`requestUnstake(amount)`** -Registers new validator to a cluster of provided operators (ids + shares), **fails if** number of operatorIds is greater than 13. The ETH amount to deposit must be [supplied via `msg.value`](https://docs.ethers.org/v4/api-contract.html#overrides). +Description: Request to unstake the specified amount of tokens from the contract. A cooldown period must be respected before being able to withdraw these tokens. -:::info Breaking Changes -With the [introduction of ETH payments](https://ssv.network/blog/introduction-to-ssv-staking), the smart contract function signature has changed. The `amount` parameter has been removed, and the function is now `payable`. The ETH amount to deposit must be supplied via `msg.value`. Update your integrations accordingly, in line with [the ethers documentation](https://docs.ethers.org/v4/api-contract.html#overrides). -::: +| **Parameter** | **Type** | **Description** | +| ------------- | --------- | ----------------------------- | +| amount | uint256 | Amount must be shrinkable (divisible by 100000) | -| **Parameter** | **Type** | **Description** | -| ------------- | -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| publicKey | bytes | The validator’s public key. | -| operatorIds | unit64\[] | List of cluster operators Ids. | -| sharesData | bytes | String of keyshares - obtained by splitting the validator key using the [SSV-Keys](../tools/ssv-keys) tool. | -| cluster | tuple\[] | Object containing the latest cluster snapshot data - obtained using the [SSV Subgraph](/developers/tools/ssv-subgraph/subgraph-examples#cluster-snapshot), or [SSV Scanner](/developers/tools/ssv-scanner) tools | Events: +* `UnstakeRequested(msg.sender, amount, unlockTime)` +* `RewardsSettled(user, pending, s.accrued[user], idx)` -* `ValidatorAdded(address indexed owner, uint64[] operatorIds, bytes publicKey, bytes shares, Cluster cluster)` - -### **`bulkRegisterValidator(publicKey, operatorIds, shares, cluster)`** - -Description: Registers all the new validators provided as argument to a cluster of provided operators (ids + shares), **fails if** number of operatorIds is greater than 13. The ETH amount to deposit must be [supplied via `msg.value`](https://docs.ethers.org/v4/api-contract.html#overrides). - -:::info Breaking Changes -With the [introduction of ETH payments](https://ssv.network/blog/introduction-to-ssv-staking), the smart contract function signature has changed. The `amount` parameter has been removed, and the function is now `payable`. The ETH amount to deposit must be supplied via `msg.value`. Update your integrations accordingly, in line with [the ethers documentation](https://docs.ethers.org/v4/api-contract.html#overrides). -::: - -| **Parameter** | **Type** | **Description** | -| ------------- | -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| publicKeys | bytes\[] | An array of validators’ public keys. | -| operatorIds | unit64\[] | List of cluster operators Ids. | -| sharesData | bytes\[] | An array of strings of keyshares - obtained by splitting the validator key using the [SSV-Keys](../tools/ssv-keys) Each element in this array must relate to a public key in the publicKeys array. | -| cluster | tuple\[] | Object containing the latest cluster snapshot data - obtained using the [SSV Subgraph](/developers/tools/ssv-subgraph/subgraph-examples#cluster-snapshot), or [SSV Scanner](/developers/tools/ssv-scanner) tools | -Events: - -* `ValidatorAdded(address indexed owner, uint64[] operatorIds, bytes publicKey, bytes shares, Cluster cluster)` - -The function emits as many `ValidatorAdded` events, as is the length of the provided `publicKeys` array. - - -Please note: the number of validators that can be registered with the`bulkRegisterValidator` function is limited by the total transaction size. This depends both on the number of total public keys, as well as the number of operators in the chosen cluster, as follows: - -* 80 validator keyshares for a cluster of 4 operators -* 40 validator keyshares for a cluster of 7 operators -* 30 validator keyshares for a cluster of 10 operators -* 20 validator keyshares for a cluster of 13 operators +--- -### **`removeValidator(publicKey, operatorIds, cluster)`** +#### **`withdrawUnlocked()`** -Description: Removes validator from the SSV network. - -| **Parameter** | **Type** | **Description** | -| ------------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| publicKey | bytes | The validator’s public key. | -| operatorIds | unit64\[] | List of cluster operators Ids. | -| cluster | tuple\[] | Object containing the latest cluster snapshot data - obtained using the [SSV Subgraph](../tools/ssv-subgraph/subgraph-examples.md#cluster-snapshot), or [SSV Scanner](../tools/ssv-scanner) tools. | +Description: Withdraws all previously requested amounts to be unstaked for which the cooldown period has elapsed. Initiator's address will be used. Events: +* `UnstakedWithdrawn(msg.sender, amount)` -* `ValidatorRemoved(address indexed owner, uint64[] operatorIds, bytes publicKey, Cluster cluster)` +--- -### **`bulkRemoveValidator(publicKey, operatorIds, cluster)`** +#### **`onCSSVTransfer(from, to, amount)`** -Description: Removes all the validators provided as argument from the SSV network. +Description: Ensures that rewards accrued by the sender up to the moment of transfer remain claimable by the sender, and that the receiver starts accruing rewards only from the moment they receive cSSV. Without this hook, a receiver could claim rewards earned before they held the tokens. -| **Parameter** | **Type** | **Description** | -| ------------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| publicKeys | bytes\[] | An array of validators’ public keys. | -| operatorIds | unit64\[] | List of cluster operators Ids. | -| cluster | tuple\[] | Object containing the latest cluster snapshot data - obtained using the [SSV Subgraph](../tools/ssv-subgraph/subgraph-examples.md#cluster-snapshot), or [SSV Scanner](../tools/ssv-scanner) tools. | +| **Parameter** | **Type** | **Description** | +| ------------- | --------- | ----------------------------- | +| from | address | The cSSV sender address | +| to | address | The cSSV receiver address | +| amount | uint256 | Amount must be shrinkable (divisible by 100000) | Events: +* `RewardsSettled(user, pending, s.accrued[user], idx)` -* `ValidatorRemoved(address indexed owner, uint64[] operatorIds, bytes publicKey, Cluster cluster)` - -The function emits as many `ValidatorRemoved` events, as is the length of the provided `publicKeys` array. - -Please note: the number of validators that can be de-registered with the`bulkRemoveValidator` function is limited by the total transaction size to a maximum of **500 validator keys at a time.** +--- -### **`exitValidator(publicKey, operatorIds)`** +#### **`rescueERC20(token, to, amount)`** -Description: Prompts SSV nodes to sign a voluntary exit of the validator. +Description: Transfers an ERC20 token that may have been accidentally sent to the contract. -| **Parameter** | **Type** | **Description** | -| ------------- | --------- | ------------------------------ | -| publicKey | bytes | The validator’s public key. | -| operatorIds | unit64\[] | List of cluster operators Ids. | +| **Parameter** | **Type** | **Description** | +| ------------- | --------- | ----------------------------- | +| token | address | Token's contract address | +| to | address | The cSSV receiver address | +| amount | uint256 | Amount must be shrinkable (divisible by 100000) | Events: +* `ERC20Rescued(token, to, amount)` -* `ValidatorExited(address indexed owner, uint64[] operatorIds, bytes publicKey)` +## Governance Methods -### **`bulkExitValidator(publicKey, operatorIds)`** +#### **`commitRoot(merkleRoot, blockNum)`** -Description: Prompts SSV nodes to sign a voluntary exit for all the validators provided as argument. +Description: Function used by oracles to commit a new Merkle root representing network status at a given block. -| **Parameter** | **Type** | **Description** | -| ------------- | --------- | ------------------------------------ | -| publicKeys | bytes\[] | An array of validators’ public keys. | -| operatorIds | unit64\[] | List of cluster operators Ids. | +| **Parameter** | **Type** | **Description** | +| ------------- | --------- | ----------------------------- | +| merkleRoot | bytes32 | The cluster owner | +| blockNum | uint64 | The cluster owner | Events: +* `WeightedRootProposed(merkleRoot, blockNum, accumulatedWeight, threshold, oracleId, msg.sender)` -* `ValidatorExited(address indexed owner, uint64[] operatorIds, bytes publicKey)` - -The function emits as many `ValidatorExited` events, as is the length of the provided `publicKeys` array. - - -Please note: the number of validators that can be requested to exit from the beacon chain with the`bulkExitValidator` function is limited by the total transaction size to a maximum of **500 validator keys at a time.** - - -### **`deposit(owner, operatorIds, cluster)`** +--- -Description: Deposits ETH into a cluster balance, will fail if not enough tokens are approved. +#### **`replaceOracle(oracleId, newOracle)`** -The ETH amount to deposit must be [supplied via `msg.value`](https://docs.ethers.org/v4/api-contract.html#overrides). +Description: DAO function to replace the address associated with the specified Oracle ID. -:::info Breaking Changes -With the [introduction of ETH payments](https://ssv.network/blog/introduction-to-ssv-staking), the smart contract function signature has changed. The `amount` parameter has been removed, and the function is now `payable`. The ETH amount to deposit must be supplied via `msg.value`. Update your integrations accordingly, in line with [the ethers documentation](https://docs.ethers.org/v4/api-contract.html#overrides). -::: - -| **Parameter** | **Type** | **Description** | -| ------------- | -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| owner | address | The cluster owner address | -| operatorIds | unit64\[] | List of cluster operators Ids. | -| cluster | tuple\[] | Object containing the latest cluster snapshot data - obtained using the [SSV Subgraph](../tools/ssv-subgraph/subgraph-examples.md#cluster-snapshot), or [SSV Scanner](../tools/ssv-scanner) tools. | +| **Parameter** | **Type** | **Description** | +| ------------- | --------- | ----------------------------- | +| oracleId | uint32 | The oracle's Id | +| newOracle | address | New address to replace with | Events: +* `OracleReplaced(oracleId, oldOracle, newOracle)` -* `ClusterDeposited(address indexed owner, uint64[] operatorIds, uint256 value, Cluster cluster)` +--- -### **`withdraw(operatorIds, amount, cluster)`** +#### **`setQuorumBps(quorum)`** -Description: Withdraws a specified amount of ETH from cluster of msg.sender, **will fail if** msg.sender tries to withdraw more than the cluster’s liquidation collateral. To withdraw the entire cluster balance and stop its operation use liquidate(). +Description: DAO function to set the percentage of Oracles voting on the same Merkle root, in order for this to be accepted. -| **Parameter** | **Type** | **Description** | -| ------------- | -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| operatorIds | unit64\[] | List of cluster operators Ids. | -| amount | uint256 (casted to uint64) | Amount to be withdrawn. Amount must be shrinkable (divisible by 10000000) | -| cluster | tuple\[] | Object containing the latest cluster snapshot data - obtained using the [SSV Subgraph](../tools/ssv-subgraph/subgraph-examples.md#cluster-snapshot), or [SSV Scanner](../tools/ssv-scanner) tools. | +| **Parameter** | **Type** | **Description** | +| ------------- | --------- | ----------------------------- | +| quorum | uint16 | Percentage of Oracles voting to set the new quorum | Events: +* `QuorumUpdated(quorum)` -* `ClusterWithdrawn(address indexed owner, uint64[] operatorIds, uint256 value, Cluster cluster)` - -### **`reactivate(operatorIds, cluster)`** +--- -Description: Reactivates a liquidated cluster, **will fail** if insufficient ETH to cover the cluster’s liquidation collateral have been deposited. The ETH amount to deposit must be [supplied via `msg.value`](https://docs.ethers.org/v4/api-contract.html#overrides). +#### **`setUnstakeCooldownDuration(duration)`** -:::info Breaking Changes -With the [introduction of ETH payments](https://ssv.network/blog/introduction-to-ssv-staking), the smart contract function signature has changed. The `amount` parameter has been removed, and the function is now `payable`. The ETH amount to deposit must be supplied via `msg.value`. Update your integrations accordingly, in line with [the ethers documentation](https://docs.ethers.org/v4/api-contract.html#overrides). -::: +Description: DAO function to set the time delay between the request of unstaking tokens and when such tokens can actually be withdrawn. -| **Parameter** | **Type** | **Description** | -| ------------- | -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| operatorIds | unit64\[] | List of cluster operators Ids. | | -| cluster | tuple\[] | Object containing the latest cluster snapshot data - obtained using the [SSV Subgraph](../tools/ssv-subgraph/subgraph-examples.md#cluster-snapshot), or [SSV Scanner](../tools/ssv-scanner) tools. | +| **Parameter** | **Type** | **Description** | +| ------------- | --------- | ----------------------------- | +| duration | uint64 | The unstake time delay | Events: +* `CooldownDurationUpdated(duration)` -* `ClusterReactivated(address indexed owner, uint64[] operatorIds, Cluster cluster)` - -## Liquidator Methods - -Write methods for liquidators +--- -### **`liquidate(owner, operatorIds, cluster)`** +#### **`syncFees()`** -Description: Liquidates a cluster sends their balances to the msg.sender (the Liquidator), **will fail** if the cluster is not liquidatable (see isLiquidatable()). - -| **Parameter** | **Type** | **Description** | -| ------------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| owner | address | The cluster owner address | -| operatorIds | unit64\[] | List of cluster operators Ids. | -| cluster | tuple\[] | Object containing the latest cluster snapshot data - obtained using the [SSV Subgraph](../tools/ssv-subgraph/subgraph-examples.md#cluster-snapshot), or [SSV Scanner](../tools/ssv-scanner) tools. | +Description: Recalculates the ratio between total network fees registered by the DAO and the total amount of staked tokens. Events: +* `FeesSynced(newFeesWei, s.accEthPerShare)` -* `ClusterLiquidated(address indexed owner, uint64[] operatorIds, Cluster cluster)` - -## Governance Methods +--- -### **`updateNetworkFee(networkFee)`** +#### **`updateNetworkFee(networkFee)`** Description: Updates network fee. -| **Parameter** | **Type** | **Description** | -| ------------- | -------------------------- | ------------------------------------------------------------------------------------ | +| **Parameter** | **Type** | **Description** | +| ------------- | -------------------------- | ------------------------------------ | | networkFee | uint256 (casted to uint64) | The fee charged by the network per 32 ETH (denominated as ETH per block). | Events: * `NetworkFeeUpdated(uint256 oldFee, uint256 newFee)` -### **`updateLiquidationThresholdPeriod(blocks)`** +--- + +#### **`updateLiquidationThresholdPeriod(blocks)`** Description: Sets the minimum period (in blocks) after which a cluster can be liquidated. @@ -421,43 +615,51 @@ Events: * `LiquidationThresholdPeriodUpdated(uint64 value)` -### **`updateMaxiumumOperatorFee(maxFee)`** +--- + +#### **`updateMaximumOperatorFee(maxFee)`** Description: Updates the maximum yearly fee per 32 ETH an operator can set | **Parameter** | **Type** | **Description** | | ------------- | -------- | -------------------------------------------------------- | -| maxFee | uint64 | Maximum fee (in ETH per year) an operator can set | +| maxFee | uint256 | Maximum fee (in ETH per year) an operator can set | Events: -* `OperatorMaximumFeeUpdated(uint64 maxFee)` +* `OperatorMaximumFeeUpdated(uint256 maxFee)` -### **`updateMinimumLiquidationCollateral(amount)`** +--- + +#### **`updateMinimumLiquidationCollateral(amount)`** Description: Sets the minimum collateral (in ETH) each cluster must keep in his balance. -| **Parameter** | **Type** | **Description** | -| ------------- | -------------------------- | ------------------------------------------------------------------------------------------------------------------- | -| amount | uint256 (casted to uint64) | Amount of ETH collateral. Amount must be shrinkable (divisible by 10000000) | +| **Parameter** | **Type** | **Description** | +| ------------- | -------------------------- | --------------------------------- | +| amount | uint256 | Amount of ETH collateral. Amount must be shrinkable (divisible by 10000000) | Events: * `MinimumLiquidationCollateralUpdated(uint256 value)` -### **`updateOperatorFeeIncreaseLimit(newOperatorMaxFeeIncrease)`** +--- + +#### **`updateOperatorFeeIncreaseLimit(newOperatorMaxFeeIncrease)`** Description: Sets the max amount by which operators can increase fees in each fee update cycle. This does not limit max operator fee, only the rate (%) by which it can be increased within each fee update cycle. | **Parameter** | **Type** | **Description** | | ------------------------- | -------- | --------------------------- | -| newOperatorMaxFeeIncrease | uint64 | Maximum increase percentage | +| newOperatorMaxFeeIncrease | uint256 | Maximum increase percentage | Events: * `OperatorFeeIncreaseLimitUpdated(uint64 value)` -### **`updateDeclareOperatorFeePeriod(seconds)`** +--- + +#### **`updateDeclareOperatorFeePeriod(seconds)`** Description: Sets the time window (in seconds) between the declaration and activation of a new operator fee. @@ -469,7 +671,9 @@ Events: * `DeclareOperatorFeePeriodUpdated(uint64 value)` -### **`updateExecuteOperatorFeePeriod(seconds)`** +--- + +#### **`updateExecuteOperatorFeePeriod(seconds)`** Description: Sets the time window (in seconds) in which an operator can activate a new fee. @@ -481,24 +685,39 @@ Events: * `ExecuteOperatorFeePeriodUpdated(uint64 value)` +--- + +#### **`updateMinimumOperatorEthFee(minFee)`** + +Description: DAO function to set min operator fee in gwei. + +| **Parameter** | **Type** | **Description** | +| ------------- | --------- | ----------------------------- | +| minFee | uint256 | Amount must be shrinkable (divisible by 100000) | + +Events: +* `MinimumOperatorEthFeeUpdated(minFee)` + ## Legacy Methods All methods that relate to the legacy (SSV-based) clusters. -### **`withdrawOperatorEarningsSSV(operatorId)`** +#### **`withdrawOperatorEarningsSSV(operatorId, amount)`** Description: Withdraws a specified amount of SSV tokens from provided operator balance to msg.sender, **will fail if** msg.sender is not the operator owner. | **Parameter** | **Type** | **Description** | | ------------- | -------------------------- | ---------------------------------------------------------------------------------------------------------------- | | operatorId | uint64 | The operator id | -| amount | uint256 (casted to uint64) | Amount must be shrinkable (divisible by 10000000) | +| amount | uint256 | Amount must be shrinkable (divisible by 10000000) | Events: * `OperatorWithdrawnSSV(address indexed owner, uint64 indexed operatorId, uint256 value)` -### **`withdrawAllOperatorEarningsSSV(operatorId)`** +--- + +#### **`withdrawAllOperatorEarningsSSV(operatorId)`** Description: Withdraws all SSV tokens earnings from provided operator balance to msg.sender, **will fail if** msg.sender is not the operator owner. @@ -510,7 +729,9 @@ Events: * `OperatorWithdrawnSSV(address indexed owner, uint64 indexed operatorId, uint256 value)` -### **`liquidateSSV(owner, operatorIds, cluster)`** +--- + +#### **`liquidateSSV(owner, operatorIds, cluster)`** Description: Liquidates an SSV-based cluster sends their balances to the msg.sender (the Liquidator), **will fail** if the cluster is not liquidatable (see isLiquidatable()). @@ -522,9 +743,11 @@ Description: Liquidates an SSV-based cluster sends their balances to the msg.sen Events: -* `ClusterLiquidatedSSV(address indexed owner, uint64[] operatorIds, Cluster cluster)` +* `ClusterLiquidated(address indexed owner, uint64[] operatorIds, Cluster cluster)` + +--- -### **`updateNetworkFeeSSV(networkFee)`** +#### **`updateNetworkFeeSSV(networkFee)`** Description: Updates network fee. @@ -536,7 +759,9 @@ Events: * `NetworkFeeUpdatedSSV(uint256 oldFee, uint256 newFee)` -### **`withdrawNetworkSSVEarnings(amount)`** +--- + +#### **`withdrawNetworkSSVEarnings(amount)`** Description: Withdraws accumulated network fees in SSV token to DAO treasury. @@ -548,7 +773,9 @@ Events: * `NetworkEarningsWithdrawn(uint256 value, address recipient)` -### **`updateLiquidationThresholdPeriodSSV(blocks)`** +--- + +#### **`updateLiquidationThresholdPeriodSSV(blocks)`** Description: Sets the minimum period (in blocks) after which an SSV-based cluster can be liquidated. @@ -560,7 +787,9 @@ Events: * `LiquidationThresholdPeriodSSVUpdated(uint64 value)` -### **`updateMinimumLiquidationCollateralSSV(amount)`** +--- + +#### **`updateMinimumLiquidationCollateralSSV(amount)`** Description: Sets the minimum collateral each SSV-based cluster must keep in his balance. @@ -572,3 +801,32 @@ Events: * `MinimumLiquidationCollateralSSVUpdated(uint256 value)` +## Account Methods + +#### **`setFeeRecipientAddress(feeRecipientAddress)`** + +Description: sets a fee recipient address to receive tips from user transactions (part block proposal rewards). This address will be set for all the account’s validators (all clusters). + +| **Parameter** | **Type** | **Description** | +| ------------------- | -------- | ---------------------------------------------------- | +| feeRecipientAddress | address | An ETH1 address that receives fee recipient rewards. | + +Events: + +* `FeeRecipientAddressUpdated(address indexed owner, address recipientAddress)` + +## Liquidator Methods + +#### **`liquidate(owner, operatorIds, cluster)`** + +Description: Liquidates a cluster sends their balances to the msg.sender (the Liquidator), **will fail** if the cluster is not liquidatable (see [isLiquidatable()](/developers/smart-contracts/ssvnetworkviews#isliquidatableowner-operatorids-cluster) method). + +| **Parameter** | **Type** | **Description** | +| ------------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| owner | address | The cluster owner address | +| operatorIds | unit64\[] | List of cluster operators Ids. | +| cluster | tuple\[] | Object containing the latest cluster snapshot data - obtained using the [SSV Subgraph](../tools/ssv-subgraph/subgraph-examples.md#cluster-snapshot), or [SSV Scanner](../tools/ssv-scanner) tools. | + +Events: + +* `ClusterLiquidated(address indexed owner, uint64[] operatorIds, Cluster cluster)` \ No newline at end of file diff --git a/docs/developers/smart-contracts/ssvnetworkviews.md b/docs/developers/smart-contracts/ssvnetworkviews.md index bb8134d..abaabed 100644 --- a/docs/developers/smart-contracts/ssvnetworkviews.md +++ b/docs/developers/smart-contracts/ssvnetworkviews.md @@ -6,9 +6,19 @@ sidebar_position: 2 The SSVNetworkViews contract is for reading information about the network and its participants. +Methods are sorted by category: + +- [General](#general-methods) +- [Cluster](#cluster-methods) +- [Operator](#operator-methods) +- [Oracle](#oracle-methods) +- [SSV Staking](#staking-methods) +- [Liquidator](#liquidator-methods) +- [Legacy](#legacy-methods) + ## General Methods -### **`getNetworkFee()`** +#### **`getNetworkFee()`** Description: Returns current network fee. @@ -18,7 +28,9 @@ Return values: |-----------|------|-------------| | fee | uint256 | The fee charged by the network proportional to Effective Balance (denominated as ETH per block) | -### **`getNetworkEarnings()`** +--- + +#### **`getNetworkEarnings()`** Description: Returns accumulated network fees not yet withdrawn. @@ -28,70 +40,155 @@ Return values: |-----------|------|-------------| | amount | uint256 | Amount of fees accumulated in the network treasury | -### **`getLiquidationThresholdPeriod()`** +--- + +#### **`getLiquidationThresholdPeriod()`** Description: Returns the minimum duration (in blocks) which a cluster has to have sufficient balance (liquidation collateral) to not be liquidated. -Return values +Return values: | **Parameter** | **Type** | **Description** | | ------------- | -------- | --------------------------------------------------------------------------------------------------------------------------- | | blocks | uint64 | The minimum duration (blocks) which a cluster has to have sufficient balance (liquidation collateral) to not be liquidated. | -### **`getMinimumLiquidationCollateral()`** +--- + +#### **`getMinimumLiquidationCollateral()`** Description: Returns the minimum amount which a cluster has to have sufficient balance (liquidation collateral) to not be liquidated. -Return values +Return values: | **Parameter** | **Type** | **Description** | | ------------- | -------- | ---------------------------------------------------------------------------------------------------- | | amount | uint256 | The minimum amount of ETH which a cluster has to have (liquidation collateral) to not be liquidated. | -### **`getOperatorFeeIncreaseLimit()`** +--- + +#### **`getOperatorFeeIncreaseLimit()`** Description: Returns the max amount by which operators can increase fees in each fee update cycle. This does refer to the max operator fee limitation, but to the rate (%) by which it can be increased. -Return values +Return values: | **Parameter** | **Type** | **Description** | | ------------- | -------- | ---------------------------------------------------------------------- | | amount | uint64 | The maximum increase in percentage the operator can update his fee to. | -### **`getOperatorFeePeriods()`** +--- + +#### **`getOperatorFeePeriods()`** Description: returns the time windows (in seconds) of operators declaration and execution fee periods. -Return values: +Return values: come as a tuple `OperatorFeePeriodsData[]` with the following parameters: | Parameter | Type | Description | |-----------|------|-------------| -| seconds | uint64 | The duration (seconds) until an operator can execute a fee after declaring it | -| seconds | uint64 | The duration (seconds) until an operator can execute a fee after declaring it | +| seconds | uint64 | Declaration period. The duration (seconds) until an operator can execute a fee after declaring it | +| seconds | uint64 | Execution period. The duration (seconds) until the new operator fee is executed | + +--- -### **`getMaximumOperatorFee()`** +#### **`getMaximumOperatorFee()`** Description: **Gets the operator maximum fee for operators that use ETH token** -Return values +Return values: | Parameter | Type | Description | | --------- | ------ | -------------------------------- | | maxFee | uint256 | The maximum fee value (ETH/year) | -### **`getValidatorsPerOperatorLimit()`** +--- + +#### **`getValidatorsPerOperatorLimit()`** Description: Returns the maximum amount of validators an operator may manage. -Return values +Return values: | **Parameter** | **Type** | **Description** | | --------------- | -------- | -------------------------------------------- | | Validator limit | uint32 | amount of validators an operator may manage. | -## Operator Methods -### **`getOperatorById(operatorId)`** +## Cluster Methods + +#### **`getBalance(owner, operatorIds, cluster)`** + +Description: Returns the outstanding ETH balance of a cluster. + +| Parameter | Type | Description | +|-----------|------|-------------| +| owner | address | The cluster owner address | +| operatorIds | uint64[] | List of cluster operators Ids | +| cluster | tuple[] | Object containing the latest cluster snapshot data - obtained using the [SSV Scanner](/developers/tools/ssv-scanner) tool | + +Return values: + +| Parameter | Type | Description | +|-----------|------|-------------| +| balance | uint256 | Clusters outstanding balance denominated in ETH | + +--- + +#### **`getBurnRate(owner, operatorIds, cluster)`** + +Description: Returns current ongoing expenses of ETH for a particular SSV cluster balance on per block basis (aggregates all expenses for all the validators in this cluster).\\ + +| **Parameter** | **Type** | **Description** | +| ------------- | --------- | ------------------------------------------------------------------------------------------------------------------------ | +| owner | address | The user address | +| operatorIds | uint64\[] | List of cluster operators Ids. | +| cluster | tuple\[] | Object containing the latest cluster snapshot data - obtained using the [SSV Subgraph](/developers/tools/ssv-subgraph/subgraph-examples#cluster-snapshot), or [SSV Scanner](/developers/tools/ssv-scanner) tools If this is the 1st validator within a specific cluster (unique set of operators), use - \{0,0,0,true,0\} | + +Return values: + +| **Parameter** | **Type** | **Description** | +| ------------- | -------- | --------------------------------------------------- | +| burnRate | uint256 | The rate per block in which the account spends ETH. | + +--- + +#### **`getClusterAssetType(address,uint64[])`** + +Description: Payment asset for the cluster identified by provided parameters. + +| **Parameter** | **Type** | **Description** | +| ------------- | --------- | ------------------------------------------------------------------------------------------------------------------------ | +| owner | address | The user address | +| operatorIds | uint64\[] | List of cluster operators Ids. | + +Return values: + +| **Parameter** | **Type** | **Description** | +| --------------- | -------- | -------------------------------------------- | +| Cluster asset type | uint8 | Cluster asset type | + +--- + +#### **`getEffectiveBalance(address,uint64[],tuple)`** + +Description: Total Effective Balance of the cluster identified by the provided parameters. + +| **Parameter** | **Type** | **Description** | +| ------------- | --------- | ------------------------------------------------------------------------------------------------------------------------ | +| owner | address | The user address | +| operatorIds | uint64\[] | List of cluster operators Ids. | +| cluster | tuple\[] | Object containing the latest cluster snapshot data - obtained using the [SSV Subgraph](/developers/tools/ssv-subgraph/subgraph-examples#cluster-snapshot), or [SSV Scanner](/developers/tools/ssv-scanner) tools If this is the 1st validator within a specific cluster (unique set of operators), use - \{0,0,0,true,0\} | + +Return values: + +| **Parameter** | **Type** | **Description** | +| --------------- | -------- | -------------------------------------------- | +| effectiveBalance | uint32 | Total effective balance of the identified cluster | + + +## Operator Methods + +#### **`getOperatorById(operatorId)`** Description: Returns operator's data. @@ -99,18 +196,20 @@ Description: Returns operator's data. |-----------|------|-------------| | operatorId | uint64 | The operator id | -Return values: +Return values: come as a tuple `OperatorData[]` with the following parameters: | Parameter | Type | Description | |-----------|------|-------------| | owner | address | The operator's admin address (for management purposes) | | fee | uint64256 | The fee charged by the operator (denominated as ETH per block) | | validatorCount | uint32 | The amount of managed validators | -| whitelistedContract | address | The external contract set to manage this operator's whitelisted addresses | +| whitelistedAddress | address | The external contract set to manage this operator's whitelisted addresses | | isPrivate | boolean | Indication if operator is permissioned | | active | boolean | Operator network status | -### **`getOperatorFee(operatorId)`** +--- + +#### **`getOperatorFee(operatorId)`** Description: returns current operator's fee (not declared). @@ -118,13 +217,15 @@ Description: returns current operator's fee (not declared). | ------------- | -------- | --------------- | | operatorId | uint64 | The operator id | -Return values +Return values: | **Parameter** | **Type** | **Description** | | ------------- | -------- | ---------------------------------------------------------------------- | | declaredFee | uint256 | The fee charged by the operator (denominated as ETH per block) | -### **`getOperatorDeclaredFee(operatorId)`** +--- + +#### **`getOperatorDeclaredFee(operatorId)`** Description: Returns the declared fee (not actual fee) together with the execution time window. @@ -132,13 +233,18 @@ Description: Returns the declared fee (not actual fee) together with the executi | ------------- | -------- | --------------- | | operatorId | uint64 | The operator id | -Return value +Return values: come as a tuple `OperatorDeclaredFeeData[]` with the following parameters: | **Parameter** | **Type** | **Description** | | ------------- | -------- | ---------------------------------------------------------------------- | -| declaredFee | uint256 | The fee declared by the operator (denominated as ETH per block) | +| fee | uint256 | The fee declared by the operator (denominated as ETH per block) | +| isFeeDeclared | bool | Checks whether the fee was declared | +| approvalBeginTime | uint64 | Returns the timestamp of when the fee was declared | +| approvalEndTime | uint64 | Returns the timestamp of when the declared fee can be executed | -### **`getOperatorEarnings(operatorId)`** +--- + +#### **`getOperatorEarnings(operatorId)`** Description: Returns the outstanding earnings of an operator. @@ -146,13 +252,15 @@ Description: Returns the outstanding earnings of an operator. | ------------- | -------- | --------------- | | operatorId | uint64 | The operator id | -Return values +Return values: | **Parameter** | **Type** | **Description** | | ------------- | -------- | ---------------------------------------------- | | balance | uint256 | Operators outstanding earnings in ETH. | -### **`getWhitelistedOperators(operatorIds, whitelistedAddress)`** +--- + +#### **`getWhitelistedOperators(operatorIds, whitelistedAddress)`** Description: Returns a list of operators that have this address whitelisted for them. @@ -161,13 +269,15 @@ Description: Returns a list of operators that have this address whitelisted for | operatorIds | uint64\[] | List of operators Ids. | | whitelistedAddress | address | ETH1 address | -Return values +Return values: | **Parameter** | **Type** | **Description** | | ---------------------- | --------- | ---------------------------------------------------------- | | whitelistedOperatorIds | uint64\[] | List of operator IDs that this address is whitelisted for. | -### **`isWhitelistingContract(contractAddress)`** +--- + +#### **`isWhitelistingContract(contractAddress)`** Description: Returns if a contract address is a valid whitelisting contract or not. @@ -175,13 +285,15 @@ Description: Returns if a contract address is a valid whitelisting contract or n | ------------------ | -------- | ------------------------------ | | whitelistedAddress | address | Whitelisting contract address. | -Return values +Return values: | **Parameter** | **Type** | **Description** | | ------------- | -------- | ---------------------------------------- | | isWhitelistingContract | bool | True if contract is valid, false if not. | -### **`isAddressWhitelistedInWhitelistingContract(addressToCheck, operatorId, whitelistingContract)`** +--- + +#### **`isAddressWhitelistedInWhitelistingContract(addressToCheck, operatorId, whitelistingContract)`** Description: Checks the whitelisted contract for an operator to see if the address provided is whitelisted for the given operator. @@ -191,90 +303,39 @@ Description: Checks the whitelisted contract for an operator to see if the addre | operatorId | uint256 | Operator ID. | | whitelistedAddress | address | Whitelisting contract address. | -Return values +Return values: | **Parameter** | **Type** | **Description** | | ------------- | -------- | --------------------------------------------- | | isWhitelisted | bool | True if address is whitelisted, false if not. | -## Cluster Methods - -### **`getBalance(owner, operatorIds, cluster)`** +--- -Description: Returns the outstanding ETH balance of a cluster. +#### **`getMinimumOperatorEthFee()`** -| Parameter | Type | Description | -|-----------|------|-------------| -| owner | address | The cluster owner address | -| operatorIds | uint64[] | List of cluster operators Ids | -| cluster | tuple[] | Object containing the latest cluster snapshot data - obtained using the [SSV Scanner](/developers/tools/ssv-scanner) tool | +Description: Returns if a contract address is a valid whitelisting contract or not. Return values: -| Parameter | Type | Description | -|-----------|------|-------------| -| balance | uint256 | Clusters outstanding balance denominated in ETH | - -### **`getBurnRate(owner, operatorIds, cluster)`** - -Description: Returns current ongoing expenses of ETH for a particular SSV cluster balance on per block basis (aggregates all expenses for all the validators in this cluster).\\ - -| **Parameter** | **Type** | **Description** | -| ------------- | --------- | ------------------------------------------------------------------------------------------------------------------------ | -| owner | address | The user address | -| operatorIds | uint64\[] | List of cluster operators Ids. | -| cluster | tuple\[] | Object containing the latest cluster snapshot data - obtained using the [SSV Subgraph](/developers/tools/ssv-subgraph/subgraph-examples#cluster-snapshot), or [SSV Scanner](/developers/tools/ssv-scanner) tools If this is the 1st validator within a specific cluster (unique set of operators), use - \{0,0,0,true,0\} | - -Return values - -| **Parameter** | **Type** | **Description** | -| ------------- | -------- | --------------------------------------------------- | -| burnRate | uint256 | The rate per block in which the account spends ETH. | - -### **`getClusterAssetType(address,uint64[])`** - -Description: Payment asset for the cluster identified by provided parameters. - -| **Parameter** | **Type** | **Description** | -| ------------- | --------- | ------------------------------------------------------------------------------------------------------------------------ | -| owner | address | The user address | -| operatorIds | uint64\[] | List of cluster operators Ids. | - -Return values - -| **Parameter** | **Type** | **Description** | -| --------------- | -------- | -------------------------------------------- | -| Cluster asset type | uint8 | Cluster asset type | - -### **`getEffectiveBalance(address,uint64[],tuple)`** - -Description: Total Effective Balance of the cluster identified by the provided parameters. - -| **Parameter** | **Type** | **Description** | -| ------------- | --------- | ------------------------------------------------------------------------------------------------------------------------ | -| owner | address | The user address | -| operatorIds | uint64\[] | List of cluster operators Ids. | -| cluster | tuple\[] | Object containing the latest cluster snapshot data - obtained using the [SSV Subgraph](/developers/tools/ssv-subgraph/subgraph-examples#cluster-snapshot), or [SSV Scanner](/developers/tools/ssv-scanner) tools If this is the 1st validator within a specific cluster (unique set of operators), use - \{0,0,0,true,0\} | - -Return values - -| **Parameter** | **Type** | **Description** | -| --------------- | -------- | -------------------------------------------- | -| effectiveBalance | uint32 | Total effective balance of the identified cluster | +| **Parameter** | **Type** | **Description** | +| ------------- | -------- | ---------------------------------------- | +| fee | uint256 | The minimum fee that can be charged by the operator (denominated as ETH per block). | ## Oracle Methods -### **`getActiveOracleIds()`** +#### **`getActiveOracleIds()`** Description: IDs of the currently active Oracles. -Return values +Return values: | **Parameter** | **Type** | **Description** | | --------------- | -------- | -------------------------------------------- | | oracleIds | uint32[4] | The active oracles' IDs. | -### **`getOracle(uint32)`** +--- + +#### **`getOracle(uint32)`** Description: Wallet address of the Oracle identified by the provided ID. @@ -282,13 +343,15 @@ Description: Wallet address of the Oracle identified by the provided ID. | ------------- | --------- | ------------------------------------------------------------------------------------------------------------------------ | | oracleId | uint32 | ID of the oracle to fetch. | -Return values +Return values: | **Parameter** | **Type** | **Description** | | --------------- | -------- | -------------------------------------------- | | Wallet address | address | Wallet address of the Oracle identified by the provided ID. | -### **`getOracleWeight(uint32)`** +--- + +#### **`getOracleWeight(uint32)`** Description: Delegation weight associated with the Oracle identified by the provided ID. @@ -296,38 +359,27 @@ Description: Delegation weight associated with the Oracle identified by the prov | ------------- | --------- | ------------------------------------------------------------------------------------------------------------------------ | | oracleId | uint32 | ID of the oracle to fetch. | -Return values +Return values: | **Parameter** | **Type** | **Description** | | --------------- | -------- | -------------------------------------------- | | Delegation weight | unit256 | Delegation weight associated with the Oracle identified by the provided ID. | -### **`getUserDelegation(address)`** - -Description: Returns the delegations made by the provided wallet address to the active Oracles. - -| **Parameter** | **Type** | **Description** | -| ------------- | --------- | ------------------------------------------------------------------------------------------------------------------------ | -| address | address | Wallet address to fetch delegations. | - -Return values - -| **Parameter** | **Type** | **Description** | -| --------------- | -------- | -------------------------------------------- | -| oracleIds | uint32[4] | The oracles' IDs. | -| amounts | uint256[4] | The delegations made by each Oracle. | +--- -### **`getQuorumBps()`** +#### **`getQuorumBps()`** Description: Quorum the Oracles need to reach in order to commit a Hash root, measured in Base Points. -Return values +Return values: | **Parameter** | **Type** | **Description** | | --------------- | -------- | -------------------------------------------- | | Quorum Base Points | uint16 | Quorum the Oracles need to reach in order to commit a Hash root. | -### **`getCommittedRoot(uint64)`** +--- + +#### **`getCommittedRoot(uint64)`** Description: Hash root of the total effective balance committed by the Oracles on the given block. @@ -335,35 +387,39 @@ Description: Hash root of the total effective balance committed by the Oracles o | ------------- | --------- | ------------------------------------------------------------------------------------------------------------------------ | | blockNum | uint64\[] | Block number. | -Return values +Return values: | **Parameter** | **Type** | **Description** | | --------------- | -------- | -------------------------------------------- | | Hash root | bytes32 | of the total effective balance committed by the Oracles on the given block. | -## Staking Methods +## SSV Staking Methods -### **`accEthPerShare()`** +#### **`accEthPerShare()`** Description: Global cumulative ETH reward index per 1 cSSV share (fixed-point, scaled by PRECISION). Used to compute each account’s pending ETH via shares * index - rewardDebt. -Return values +Return values: | **Parameter** | **Type** | **Description** | | --------------- | -------- | -------------------------------------------- | | ETH reward index | uint256 | Global cumulative ETH reward index | -### **`cooldownDuration()`** +--- + +#### **`cooldownDuration()`** Description: Delay between request for withdrawal of staked SSV and the availability for tokens to be withdrawn. -Return values +Return values: | **Parameter** | **Type** | **Description** | | --------------- | -------- | -------------------------------------------- | | Cooldown duration | uint256 | The delay duration | -### **`pendingUnstake(address)`** +--- + +#### **`pendingUnstake(address)`** Description: List of pending unstaked token amounts and their respective remaining cooldown. @@ -371,14 +427,16 @@ Description: List of pending unstaked token amounts and their respective remaini | ------------- | --------- | ------------------------------------------------------------------------------------------------------------------------ | | Wallet address | address | User wallet address. | -Return values +Return values: come as a tuple `UnstakeRequestsData[]` with the following parameters: | **Parameter** | **Type** | **Description** | | --------------- | -------- | -------------------------------------------- | -| amounts[] | uint256 | Amounts of pending unstaked token requests. | -| unlockTimes[] | uint256 | The unlock time for each of the unstaking requests. | +| amount | uint256 | Amounts of pending unstaked token requests. | +| unlockTime | uint256 | The unlock time for each of the unstaking requests. | + +--- -### **`previewClaimableEth(address)`** +#### **`previewClaimableEth(address)`** Description: Amount of accrued ETH the provided address can claim. @@ -386,13 +444,15 @@ Description: Amount of accrued ETH the provided address can claim. | ------------- | --------- | ------------------------------------------------------------------------------------------------------------------------ | | Wallet address | address | User wallet address. | -Return values +Return values: | **Parameter** | **Type** | **Description** | | --------------- | -------- | -------------------------------------------- | | Accrued amount | uint256 | Previewed amount of claimable ETH for the provided address. | -### **`stakedBalanceOf(address)`** +--- + +#### **`stakedBalanceOf(address)`** Description: Total amount of SSV tokens staked by the provided address. @@ -400,36 +460,39 @@ Description: Total amount of SSV tokens staked by the provided address. | ------------- | --------- | ------------------------------------------------------------------------------------------------------------------------ | | Wallet address | address | User wallet address. | -Return values +Return values: | **Parameter** | **Type** | **Description** | | --------------- | -------- | -------------------------------------------- | | Staked amount | uint256 | Total amount of SSV token staked by the provided address. | -### **`stakingEthPoolBalance()`** +--- + +#### **`stakingEthPoolBalance()`** Description: Total amount of ETH accrued in fees by the protocol. -Return values +Return values: | **Parameter** | **Type** | **Description** | | --------------- | -------- | -------------------------------------------- | -| ETH Accrued | uint64 | Total amount of ETH accrued in fees by the protocol | +| ETH Accrued | uint256 | Total amount of ETH accrued in fees by the protocol | -### **`totalStaked()`** +--- + +#### **`totalStaked()`** Description: Total amount of SSV tokens staked in the protocol. -Return values +Return values: | **Parameter** | **Type** | **Description** | | --------------- | -------- | -------------------------------------------- | | Total staked | uint256 | Amount of SSV tokens staked in the protocol. | +## Liquidator Methods -## Liquidator Methods - -### **`isLiquidatable(owner, operatorIds, cluster)`** +#### **`isLiquidatable(owner, operatorIds, cluster)`** Description: Returns true if the specified cluster is under the liquidation threshold and can be liquidated. @@ -439,13 +502,15 @@ Description: Returns true if the specified cluster is under the liquidation thre | operatorIds | uint64\[] | List of cluster operators Ids. | | cluster | tuple\[] | Object containing the latest cluster snapshot data - obtained using the [SSV Subgraph](/developers/tools/ssv-subgraph/subgraph-examples#cluster-snapshot), or [SSV Scanner](/developers/tools/ssv-scanner) tools If this is the 1st validator within a specific cluster (unique set of operators), use - \{0,0,0,true,0\} | -Return values +Return values: | **Parameter** | **Type** | **Description** | | ------------- | -------- | ------------------------------------------- | | isLiquidatable | boolean | Indication if a cluster could be liquidated | -### **`isLiquidated(owner, operatorIds, cluster)`** +--- + +#### **`isLiquidated(owner, operatorIds, cluster)`** Description: Returns true if the provided cluster is liquidated. @@ -455,7 +520,7 @@ Description: Returns true if the provided cluster is liquidated. | operatorIds | uint64\[] | List of cluster operators Ids. | | cluster | tuple\[] | Object containing the latest cluster snapshot data - obtained using the [SSV Subgraph](/developers/tools/ssv-subgraph/subgraph-examples#cluster-snapshot), or [SSV Scanner](/developers/tools/ssv-scanner) tools If this is the 1st validator within a specific cluster (unique set of operators), use - \{0,0,0,true,0\} | -Return values +Return values: | **Parameter** | **Type** | **Description** | | ------------- | -------- | ------------------------------------- | @@ -463,7 +528,7 @@ Return values ## Legacy Methods -### **`getBalanceSSV(owner, operatorIds, cluster)`** +#### **`getBalanceSSV(owner, operatorIds, cluster)`** Description: Returns the outstanding SSV balance of a legacy (SSV-based) cluster. @@ -479,7 +544,9 @@ Return values: |-----------|------|-------------| | balance | uint256 | Clusters outstanding balance denominated in SSV | -### **`getBurnRateSSV(owner, operatorIds, cluster)`** +--- + +#### **`getBurnRateSSV(owner, operatorIds, cluster)`** Description: Returns current ongoing expenses of SSV for a particular SSV cluster balance on per block basis (aggregates all expenses for all the validators in this cluster).\\ @@ -489,13 +556,15 @@ Description: Returns current ongoing expenses of SSV for a particular SSV cluste | operatorIds | uint64\[] | List of cluster operators Ids. | | cluster | tuple\[] | Object containing the latest cluster snapshot data - obtained using the [SSV Subgraph](/developers/tools/ssv-subgraph/subgraph-examples#cluster-snapshot), or [SSV Scanner](/developers/tools/ssv-scanner) tools If this is the 1st validator within a specific cluster (unique set of operators), use - \{0,0,0,true,0\} | -Return values +Return values: | **Parameter** | **Type** | **Description** | | ------------- | -------- | --------------------------------------------------- | | burnRate | uint256 | The rate per block in which the account spends ETH. | -### **`getNetworkFeeSSV()`** +--- + +#### **`getNetworkFeeSSV()`** Description: Returns current network fee for legacy (SSV-based) clusters. @@ -505,7 +574,9 @@ Return values: |-----------|------|-------------| | fee | uint256 | The fee charged by the network (denominated as SSV per block) | -### **`getNetworkEarningsSSV()`** +--- + +#### **`getNetworkEarningsSSV()`** Description: Returns accumulated network fees not yet withdrawn from the legacy (SSV-based) clusters. @@ -515,37 +586,45 @@ Return values: |-----------|------|-------------| | amount | uint256 | Amount of fees accumulated in the network treasury | -### **`getLiquidationThresholdPeriodSSV()`** +--- + +#### **`getLiquidationThresholdPeriodSSV()`** Description: Returns the minimum duration (in blocks) which legacy cluster has to have sufficient balance (liquidation collateral) to not be liquidated. -Return values +Return values: | **Parameter** | **Type** | **Description** | | ------------- | -------- | --------------------------------------------------------------------------------------------------------------------------- | | blocks | uint64 | The minimum duration (blocks) which legacy cluster has to have sufficient balance (liquidation collateral) to not be liquidated. | -### **`getMinimumLiquidationCollateralSSV()`** +--- + +#### **`getMinimumLiquidationCollateralSSV()`** Description: Returns the minimum amount which legacy cluster has to have sufficient balance (liquidation collateral) to not be liquidated. -Return values +Return values: | **Parameter** | **Type** | **Description** | | ------------- | -------- | ---------------------------------------------------------------------------------------------------- | | amount | uint256 | The minimum amount of SSV which a cluster has to have (liquidation collateral) to not be liquidated. | -### **`getMaximumOperatorFeeSSV()`** +--- + +#### **`getMaximumOperatorFeeSSV()`** Description: **Gets the operator maximum fee for operators that use SSV token** -Return values +Return values: | Parameter | Type | Description | | --------- | ------ | -------------------------------- | | maxFee | uint64 | The maximum fee value (SSV/year) | -### **`getOperatorByIdSSV(operatorId)`** +--- + +#### **`getOperatorByIdSSV(operatorId)`** Description: Returns operator's data for operators participating in legacy clusters. @@ -553,7 +632,7 @@ Description: Returns operator's data for operators participating in legacy clust |-----------|------|-------------| | operatorId | uint64 | The operator id | -Return values: +Return values: come as a tuple `[]` with the following parameters: | Parameter | Type | Description | |-----------|------|-------------| @@ -564,7 +643,9 @@ Return values: | isPrivate | boolean | Indication if operator is permissioned | | active | boolean | Operator network status | -### **`getOperatorFeeSSV(operatorId)`** +--- + +#### **`getOperatorFeeSSV(operatorId)`** Description: returns current operator's fee (not declared). @@ -572,13 +653,15 @@ Description: returns current operator's fee (not declared). | ------------- | -------- | --------------- | | operatorId | uint64 | The operator id | -Return values +Return values: | **Parameter** | **Type** | **Description** | | ------------- | -------- | ---------------------------------------------------------------------- | | declaredFee | uint256 | The fee charged by the operator (denominated as SSV per block) | -### **`getOperatorEarningsSSV(operatorId)`** +--- + +#### **`getOperatorEarningsSSV(operatorId)`** Description: Returns the outstanding earnings of an operator participating legacy cluster(s). @@ -586,13 +669,15 @@ Description: Returns the outstanding earnings of an operator participating legac | ------------- | -------- | --------------- | | operatorId | uint64 | The operator id | -Return values +Return values: | **Parameter** | **Type** | **Description** | | ------------- | -------- | ---------------------------------------------- | | balance | uint256 | Operators outstanding earnings in SSV. | -### **`isLiquidatableSSV(owner, operatorIds, cluster)`** +--- + +#### **`isLiquidatableSSV(owner, operatorIds, cluster)`** Description: Returns true if the specified legacy cluster is under the liquidation threshold and can be liquidated. @@ -602,7 +687,7 @@ Description: Returns true if the specified legacy cluster is under the liquidati | operatorIds | uint64\[] | List of cluster operators Ids. | | cluster | tuple\[] | Object containing the latest cluster snapshot data - obtained using the [SSV Subgraph](/developers/tools/ssv-subgraph/subgraph-examples#cluster-snapshot), or [SSV Scanner](/developers/tools/ssv-scanner) tools If this is the 1st validator within a specific cluster (unique set of operators), use - \{0,0,0,true,0\} | -Return values +Return values: | **Parameter** | **Type** | **Description** | | ------------- | -------- | ------------------------------------------- |