Threshold Network 백서 전문

wardParametersUpdated(uint256 maliciousDkgResultNotificationRewardMultiplier, uint256 sortitionPoolRewardsBanDuration) ``` ### SlashingParametersUpdated ```solidity event SlashingParametersUpdated(uint256 maliciousDkgResultSlashingAmount) ``` ### DkgParametersUpdated ```solidity event DkgParametersUpdated(uint256 seedTimeout, uint256 resultChallengePeriodLength, uint256 resultChallengeExtraGas, uint256 resultSubmissionTimeout, uint256 resultSubmitterPrecedencePeriodLength) ``` ### GasParametersUpdated ```solidity event GasParametersUpdated(uint256 dkgResultSubmissionGas, uint256 dkgResultApprovalGasOffset, uint256 notifyOperatorInactivityGasOffset, uint256 notifySeedTimeoutGasOffset, uint256 notifyDkgTimeoutNegativeGasOffset) ``` ### RandomBeaconUpgraded ```solidity event RandomBeaconUpgraded(address randomBeacon) ``` ### WalletOwnerUpdated ```solidity event WalletOwnerUpdated(address walletOwner) ``` ### OperatorRegistered ```solidity event OperatorRegistered(address stakingProvider, address operator) ``` ### AuthorizationIncreased ```solidity event AuthorizationIncreased(address stakingProvider, address operator, uint96 fromAmount, uint96 toAmount) ``` ### AuthorizationDecreaseRequested ```solidity event AuthorizationDecreaseRequested(address stakingProvider, address operator, uint96 fromAmount, uint96 toAmount, uint64 decreasingAt) ``` ### AuthorizationDecreaseApproved ```solidity event AuthorizationDecreaseApproved(address stakingProvider) ``` ### InvoluntaryAuthorizationDecreaseFailed ```solidity event InvoluntaryAuthorizationDecreaseFailed(address stakingProvider, address operator, uint96 fromAmount, uint96 toAmount) ``` ### OperatorJoinedSortitionPool ```solidity event OperatorJoinedSortitionPool(address stakingProvider, address operator) ``` ### OperatorStatusUpdated ```solidity event OperatorStatusUpdated(address stakingProvider, address operator) ``` ### InactivityClaimed ```solidity event InactivityClaimed(bytes32 walletID, uint256 nonce, address notifier) ``` ### onlyStakingContract ```solidity modifier onlyStakingContract() ``` ### onlyWalletOwner ```solidity modifier onlyWalletOwner() ``` Reverts if called not by the Wallet Owner. ### onlyReimbursableAdmin ```solidity modifier onlyReimbursableAdmin() ``` ### constructor ```solidity constructor(contract SortitionPool _sortitionPool, contract IStaking _staking) public ``` Used to initialize immutable variables only, use `initialize` function for upgradable contract initialization on deployment. ### initialize ```solidity function initialize(contract EcdsaDkgValidator _ecdsaDkgValidator, contract IRandomBeacon _randomBeacon, contract ReimbursementPool _reimbursementPool) external ``` Initializes upgradable contract on deployment. ### withdrawRewards ```solidity function withdrawRewards(address stakingProvider) external ``` Withdraws application rewards for the given staking provider. Rewards are withdrawn to the staking provider's beneficiary address set in the staking contract. Reverts if staking provider has not registered the operator address. Emits `RewardsWithdrawn` event. ### withdrawIneligibleRewards ```solidity function withdrawIneligibleRewards(address recipient) external ``` Withdraws rewards belonging to operators marked as ineligible for sortition pool rewards. Can be called only by the contract guvnor, which should be the wallet registry governance contract. #### Parameters | Name | Type | Description | | --------- | ------- | ------------------------------- | | recipient | address | Recipient of withdrawn rewards. | ### registerOperator ```solidity function registerOperator(address operator) external ``` Used by staking provider to set operator address that will operate ECDSA node. The given staking provider can set operator address only one time. The operator address can not be changed and must be unique. Reverts if the operator is already set for the staking provider or if the operator address is already in use. Reverts if there is a pending authorization decrease for the staking provider. ### joinSortitionPool ```solidity function joinSortitionPool() external ``` Lets the operator join the sortition pool. The operator address must be known - before calling this function, it has to be appointed by the staking provider by calling `registerOperator`. Also, the operator must have the minimum authorization required by ECDSA. Function reverts if there is no minimum stake authorized or if the operator is not known. If there was an authorization decrease requested, it is activated by starting the authorization decrease delay. ### updateOperatorStatus ```solidity function updateOperatorStatus(address operator) external ``` Updates status of the operator in the sortition pool. If there was an authorization decrease requested, it is activated by starting the authorization decrease delay. Function reverts if the operator is not known. ### authorizationIncreased ```solidity function authorizationIncreased(address stakingProvider, uint96 fromAmount, uint96 toAmount) external ``` Used by T staking contract to inform the application that the authorized stake amount for the given staking provider increased. Reverts if the authorization amount is below the minimum. The function is not updating the sortition pool. Sortition pool state needs to be updated by the operator with a call to `joinSortitionPool` or `updateOperatorStatus`. Can only be called by T staking contract. ### authorizationDecreaseRequested ```solidity function authorizationDecreaseRequested(address stakingProvider, uint96 fromAmount, uint96 toAmount) external ``` Used by T staking contract to inform the application that the authorization decrease for the given staking provider has been requested. Reverts if the amount after deauthorization would be non-zero and lower than the minimum authorization. If the operator is not known (`registerOperator` was not called) it lets to `approveAuthorizationDecrease` immediatelly. If the operator is known (`registerOperator` was called), the operator needs to update state of the sortition pool with a call to `joinSortitionPool` or `updateOperatorStatus`. After the sortition pool state is in sync, authorization decrease delay starts. After authorization decrease delay passes, authorization decrease request needs to be approved with a call to `approveAuthorizationDecrease` function. If there is a pending authorization decrease request, it is overwritten. Can only be called by T staking contract. ### approveAuthorizationDecrease ```solidity function approveAuthorizationDecrease(address stakingProvider) external ``` Approves the previously registered authorization decrease request. Reverts if authorization decrease delay has not passed yet or if the authorization decrease was not requested for the given staking provider. ### involuntaryAuthorizationDecrease ```solidity function involuntaryAuthorizationDecrease(address stakingProvider, uint96 fromAmount, uint96 toAmount) external ``` Used by T staking contract to inform the application the authorization has been decreased for the given staking provider involuntarily, as a result of slashing. If the operator is not known (`registerOperator` was not called) the function does nothing. The operator was never in a sortition pool so there is nothing to update. If the operator is known, sortition pool is unlocked, and the operator is in the sortition pool, the sortition pool state is updated. If the sortition pool is locked, update needs to be postponed. Every other staker is incentivized to call `updateOperatorStatus` for the problematic operator to increase their own rewards in the pool. ### upgradeRandomBeacon ```solidity function upgradeRandomBeacon(contract IRandomBeacon _randomBeacon) external ``` Updates address of the Random Beacon. Can be called only by the contract guvnor, which should be the wallet registry governance contract. The caller is responsible for validating parameters. #### Parameters | Name | Type | Description | | -------------- | ---------------------- | ---------------------- | | \_randomBeacon | contract IRandomBeacon | Random Beacon address. | ### updateWalletOwner ```solidity function updateWalletOwner(contract IWalletOwner _walletOwner) external ``` Updates the wallet owner. Can be called only by the contract guvnor, which should be the wallet registry governance contract. The caller is responsible for validating parameters. The wallet owner has to implement `IWalletOwner` interface. #### Parameters | Name | Type | Description | | ------------- | --------------------- | ------------------------- | | \_walletOwner | contract IWalletOwner | New wallet owner address. | ### updateAuthorizationParameters ```solidity function updateAuthorizationParameters(uint96 _minimumAuthorization, uint64 _authorizationDecreaseDelay, uint64 _authorizationDecreaseChangePeriod) external ``` Updates the values of authorization parameters. Can be called only by the contract guvnor, which should be the wallet registry governance contract. The caller is responsible for validating parameters. #### Parameters | Name | Type | Description | | ----------------------------------- | ------ | ---------------------------------------------------- | | \_minimumAuthorization | uint96 | New minimum authorization amount. | | \_authorizationDecreaseDelay | uint64 | New authorization decrease delay in seconds. | | \_authorizationDecreaseChangePeriod | uint64 | New authorization decrease change period in seconds. | ### updateDkgParameters ```solidity function updateDkgParameters(uint256 _seedTimeout, uint256 _resultChallengePeriodLength, uint256 _resultChallengeExtraGas, uint256 _resultSubmissionTimeout, uint256 _submitterPrecedencePeriodLength) external ``` Updates the values of DKG parameters. Can be called only by the contract guvnor, which should be the wallet registry governance contract. The caller is responsible for validating parameters. #### Parameters | Name | Type | Description | | --------------------------------- | ------- | ------------------------------------------------------------------------------------------- | | \_seedTimeout | uint256 | New seed timeout. | | \_resultChallengePeriodLength | uint256 | New DKG result challenge period length. | | \_resultChallengeExtraGas | uint256 | New extra gas value required to be left at the end of the DKG result challenge transaction. | | \_resultSubmissionTimeout | uint256 | New DKG result submission timeout. | | \_submitterPrecedencePeriodLength | uint256 | New submitter precedence period length. | ### updateRewardParameters ```solidity function updateRewardParameters(uint256 maliciousDkgResultNotificationRewardMultiplier, uint256 sortitionPoolRewardsBanDuration) external ``` Updates the values of reward parameters. Can be called only by the contract guvnor, which should be the wallet registry governance contract. The caller is responsible for validating parameters. #### Parameters | Name | Type | Description | | ---------------------------------------------- | ------- | --------------------------------------------------------------------- | | maliciousDkgResultNotificationRewardMultiplier | uint256 | New value of the DKG malicious result notification reward multiplier. | | sortitionPoolRewardsBanDuration | uint256 | New sortition pool rewards ban duration in seconds. | ### updateSlashingParameters ```solidity function updateSlashingParameters(uint96 maliciousDkgResultSlashingAmount) external ``` Updates the values of slashing parameters. Can be called only by the contract guvnor, which should be the wallet registry governance contract. The caller is responsible for validating parameters. #### Parameters | Name | Type | Description | | -------------------------------- | ------ | ----------------------------------------- | | maliciousDkgResultSlashingAmount | uint96 | New malicious DKG result slashing amount. | ### updateGasParameters ```solidity function updateGasParameters(uint256 dkgResultSubmissionGas, uint256 dkgResultApprovalGasOffset, uint256 notifyOperatorInactivityGasOffset, uint256 notifySeedTimeoutGasOffset, uint256 notifyDkgTimeoutNegativeGasOffset) external ``` Updates the values of gas-related parameters. Can be called only by the contract guvnor, which should be the wallet registry governance contract. The caller is responsible for validating parameters. #### Parameters | Name | Type | Description | | --------------------------------- | ------- | ---------------------------------------------------------- | | dkgResultSubmissionGas | uint256 | New DKG result submission gas. | | dkgResultApprovalGasOffset | uint256 | New DKG result approval gas offset. | | notifyOperatorInactivityGasOffset | uint256 | New operator inactivity notification gas offset. | | notifySeedTimeoutGasOffset | uint256 | New seed for DKG delivery timeout notification gas offset. | | notifyDkgTimeoutNegativeGasOffset | uint256 | New DKG timeout notification gas offset. | ### requestNewWallet ```solidity function requestNewWallet() external ``` Requests a new wallet creation. Can be called only by the owner of wallets. It locks the DKG and request a new relay entry. It expects that the DKG process will be started once a new relay entry gets generated. ### closeWallet ```solidity function closeWallet(bytes32 walletID) external ``` Closes an existing wallet. Reverts if wallet with the given ID does not exist or if it has already been closed. Only a Wallet Owner can call this function. #### Parameters | Name | Type | Description | | -------- | ------- | ----------------- | | walletID | bytes32 | ID of the wallet. | ### \_\_beaconCallback ```solidity function __beaconCallback(uint256 relayEntry, uint256) external ``` A callback that is executed once a new relay entry gets generated. It starts the DKG process. Can be called only by the random beacon contract. #### Parameters | Name | Type | Description | | ---------- | ------- | ------------ | | relayEntry | uint256 | Relay entry. | | | uint256 | | ### submitDkgResult ```solidity function submitDkgResult(struct EcdsaDkg.Result dkgResult) external ``` Submits result of DKG protocol. The DKG result consists of result submitting member index, calculated group public key, bytes array of misbehaved members, concatenation of signatures from group members, indices of members corresponding to each signature and the list of group members. The result is registered optimistically and waits for an approval. The result can be challenged when it is believed to be incorrect. The challenge verifies the registered result i.a. it checks if members list corresponds to the expected set of members determined by the sortition pool. The message to be signed by each member is keccak256 hash of the chain ID, calculated group public key, misbehaved members indices and DKG start block. The calculated hash should be prefixed with `\x19Ethereum signed message:` before signing, so the message to sign is: `\x19Ethereum signed message:\n${keccak256(chainID,groupPubKey,misbehavedIndices,startBlock)}` #### Parameters | Name | Type | Description | | --------- | ---------------------- | ----------- | | dkgResult | struct EcdsaDkg.Result | DKG result. | ### approveDkgResult ```solidity function approveDkgResult(struct EcdsaDkg.Result dkgResult) external ``` Approves DKG result. Can be called when the challenge period for the submitted result is finished. Considers the submitted result as valid, bans misbehaved group members from the sortition pool rewards, and completes the group creation by activating the candidate group. For the first `resultSubmissionTimeout` blocks after the end of the challenge period can be called only by the DKG result submitter. After that time, can be called by anyone. A new wallet based on the DKG result details. #### Parameters | Name | Type | Description | | --------- | ---------------------- | ----------------------------------------------------------------------------------- | | dkgResult | struct EcdsaDkg.Result | Result to approve. Must match the submitted result stored during `submitDkgResult`. | ### notifySeedTimeout ```solidity function notifySeedTimeout() external ``` Notifies about seed for DKG delivery timeout. It is expected that a seed is delivered by the Random Beacon as a relay entry in a callback function. ### notifyDkgTimeout ```solidity function notifyDkgTimeout() external ``` Notifies about DKG timeout. ### challengeDkgResult ```solidity function challengeDkgResult(struct EcdsaDkg.Result dkgResult) external ``` Challenges DKG result. If the submitted result is proved to be invalid it reverts the DKG back to the result submission phase. Due to EIP-150 1/64 of the gas is not forwarded to the call, and will be kept to execute the remaining operations in the function after the call inside the try-catch. To eliminate a class of attacks related to the gas limit manipulation, this function requires an extra amount of gas to be left at the end of the execution. #### Parameters | Name | Type | Description | | --------- | ---------------------- | ------------------------------------------------------------------------------------- | | dkgResult | struct EcdsaDkg.Result | Result to challenge. Must match the submitted result stored during `submitDkgResult`. | ### notifyOperatorInactivity ```solidity function notifyOperatorInactivity(struct EcdsaInactivity.Claim claim, uint256 nonce, uint32[] groupMembers) external ``` Notifies about operators who are inactive. Using this function, a majority of the wallet signing group can decide about punishing specific group members who constantly fail doing their job. If the provided claim is proved to be valid and signed by sufficient number of group members, operators of members deemed as inactive are banned from sortition pool rewards for the duration specified by `sortitionPoolRewardsBanDuration` parameter. The function allows to signal about single operators being inactive as well as to signal wallet-wide heartbeat failures that are propagated to the wallet owner who should begin the procedure of moving responsibilities to another wallet given that the wallet who failed the heartbeat may soon be not able to function and provide new signatures. The sender of the claim must be one of the claim signers. This function can be called only for registered wallets #### Parameters | Name | Type | Description | | ------------ | ---------------------------- | ------------------------------------------------------------------------------------------------------ | | claim | struct EcdsaInactivity.Claim | Operator inactivity claim. | | nonce | uint256 | Current inactivity claim nonce for the given wallet signing group. Must be the same as the stored one. | | groupMembers | uint32\[] | Identifiers of the wallet signing group members. | ### seize ```solidity function seize(uint96 amount, uint256 rewardMultiplier, address notifier, bytes32 walletID, uint32[] walletMembersIDs) external ``` Allows the wallet owner to add all signing group members of the wallet with the given ID to the slashing queue of the staking . contract. The notifier will receive reward per each group member from the staking contract notifiers treasury. The reward is scaled by the `rewardMultiplier` provided as a parameter. Requirements: * The expression `keccak256(abi.encode(walletMembersIDs))` must be exactly the same as the hash stored under `membersIdsHash` for the given `walletID`. Those IDs are not directly stored in the contract for gas efficiency purposes but they can be read from appropriate `DkgResultSubmitted` and `DkgResultApproved` events. * `rewardMultiplier` must be between \[0, 100]. * This function does revert if staking contract call reverts. The calling code needs to handle the potential revert. #### Parameters | Name | Type | Description | | ---------------- | -