Threshold Network 백서 전문

kept to execute the remaining operations in the function after the call inside the try-catch. To ensure there is no way for the caller to manipulate gas limit in such a way that the call inside try-catch fails with out-of-gas and the rest of the function is executed with the remaining 1/64 of gas, we require an extra gas amount to be left at the end of the call to the function challenging DKG result and wrapping the call to EcdsaDkgValidator and TokenStaking contracts inside a try-catch. ### isResultValid ```solidity function isResultValid(struct EcdsaDkg.Data self, struct EcdsaDkg.Result result) internal view returns (bool, string) ``` Checks if DKG result is valid for the current DKG. #### Parameters | Name | Type | Description | | ------ | ---------------------- | ----------- | | self | struct EcdsaDkg.Data | | | result | struct EcdsaDkg.Result | DKG result. | #### Return Values | Name | Type | Description | | ---- | ------ | -------------------------------------------------------------------------------------------- | | \[0] | bool | True if the result is valid. If the result is invalid it returns false and an error message. | | \[1] | string | | ### setSeedTimeout ```solidity function setSeedTimeout(struct EcdsaDkg.Data self, uint256 newSeedTimeout) internal ``` Set setSeedTimeout parameter. ### setResultChallengePeriodLength ```solidity function setResultChallengePeriodLength(struct EcdsaDkg.Data self, uint256 newResultChallengePeriodLength) internal ``` Set resultChallengePeriodLength parameter. ### setResultChallengeExtraGas ```solidity function setResultChallengeExtraGas(struct EcdsaDkg.Data self, uint256 newResultChallengeExtraGas) internal ``` Set resultChallengeExtraGas parameter. ### setResultSubmissionTimeout ```solidity function setResultSubmissionTimeout(struct EcdsaDkg.Data self, uint256 newResultSubmissionTimeout) internal ``` Set resultSubmissionTimeout parameter. ### setSubmitterPrecedencePeriodLength ```solidity function setSubmitterPrecedencePeriodLength(struct EcdsaDkg.Data self, uint256 newSubmitterPrecedencePeriodLength) internal ``` Set submitterPrecedencePeriodLength parameter. ### complete ```solidity function complete(struct EcdsaDkg.Data self) internal ``` Completes DKG by cleaning up state. Should be called after DKG times out or a result is approved. # EcdsaDkgValidator ## EcdsaDkgValidator EcdsaDkgValidator allows performing a full validation of DKG result, including checking the format of fields in the result, declared selected group members, and signatures of operators supporting the result. The operator submitting the result should perform the validation using a free contract call before submitting the result to ensure their result is valid and can not be challenged. All other network operators should perform validation of the submitted result using a free contract call and challenge the result if the validation fails. ### groupSize ```solidity uint256 groupSize ``` Size of a group in DKG. ### groupThreshold ```solidity uint256 groupThreshold ``` The minimum number of group members needed to interact according to the protocol to produce a signature. The adversary can not learn anything about the key as long as it does not break into groupThreshold+1 of members. ### activeThreshold ```solidity uint256 activeThreshold ``` The minimum number of active and properly behaving group members during the DKG needed to accept the result. This number is higher than `groupThreshold` to keep a safety margin for members becoming inactive after DKG so that the group can still produce signature. ### publicKeyByteSize ```solidity uint256 publicKeyByteSize ``` Size in bytes of a public key produced by group members during the the DKG. The length assumes uncompressed ECDSA public key. ### signatureByteSize ```solidity uint256 signatureByteSize ``` Size in bytes of a single signature produced by operator supporting DKG result. ### sortitionPool ```solidity contract SortitionPool sortitionPool ``` ### constructor ```solidity constructor(contract SortitionPool _sortitionPool) public ``` ### validate ```solidity function validate(struct EcdsaDkg.Result result, uint256 seed, uint256 startBlock) external view returns (bool isValid, string errorMsg) ``` Performs a full validation of DKG result, including checking the format of fields in the result, declared selected group members, and signatures of operators supporting the result. #### Parameters | Name | Type | Description | | ---------- | ---------------------- | --------------------------------------------------- | | result | struct EcdsaDkg.Result | | | seed | uint256 | seed used to start the DKG and select group members | | startBlock | uint256 | DKG start block | #### Return Values | Name | Type | Description | | -------- | ------ | -------------------------------------------------- | | isValid | bool | true if the result is valid, false otherwise | | errorMsg | string | validation error message; empty for a valid result | ### validateFields ```solidity function validateFields(struct EcdsaDkg.Result result) public pure returns (bool isValid, string errorMsg) ``` Performs a static validation of DKG result fields: lengths, ranges, and order of arrays. #### Return Values | Name | Type | Description | | -------- | ------ | -------------------------------------------------- | | isValid | bool | true if the result is valid, false otherwise | | errorMsg | string | validation error message; empty for a valid result | ### validateGroupMembers ```solidity function validateGroupMembers(struct EcdsaDkg.Result result, uint256 seed) public view returns (bool) ``` Performs validation of group members as declared in DKG result against group members selected by the sortition pool. #### Parameters | Name | Type | Description | | ------ | ---------------------- | --------------------------------------------------- | | result | struct EcdsaDkg.Result | | | seed | uint256 | seed used to start the DKG and select group members | #### Return Values | Name | Type | Description | | ---- | ---- | ---------------------------------------------- | | \[0] | bool | true if group members matches; false otherwise | ### validateSignatures ```solidity function validateSignatures(struct EcdsaDkg.Result result, uint256 startBlock) public view returns (bool) ``` Performs validation of signatures supplied in DKG result. Note that this function does not check if addresses which supplied signatures supporting the result are the ones selected to the group by sortition pool. This function should be used together with `validateGroupMembers`. #### Parameters | Name | Type | Description | | ---------- | ---------------------- | --------------- | | result | struct EcdsaDkg.Result | | | startBlock | uint256 | DKG start block | #### Return Values | Name | Type | Description | | ---- | ---- | ---------------------------------------------- | | \[0] | bool | true if group members matches; false otherwise | ### validateMembersHash ```solidity function validateMembersHash(struct EcdsaDkg.Result result) public pure returns (bool) ``` Performs validation of hashed group members that actively took part in DKG. #### Parameters | Name | Type | Description | | ------ | ---------------------- | ----------- | | result | struct EcdsaDkg.Result | DKG result | #### Return Values | Name | Type | Description | | ---- | ---- | --------------------------------------------------------------------------------------- | | \[0] | bool | true if calculated result's group members hash matches with the one that is challenged. | # EcdsaInactivity ## EcdsaInactivity ### Claim ```solidity struct Claim { bytes32 walletID; uint256[] inactiveMembersIndices; bool heartbeatFailed; bytes signatures; uint256[] signingMembersIndices; } ``` ### groupThreshold ```solidity uint256 groupThreshold ``` The minimum number of wallet signing group members needed to interact according to the protocol to produce a valid inactivity claim. ### signatureByteSize ```solidity uint256 signatureByteSize ``` Size in bytes of a single signature produced by member supporting the inactivity claim. ### verifyClaim ```solidity function verifyClaim(contract SortitionPool sortitionPool, struct EcdsaInactivity.Claim claim, bytes walletPubKey, uint256 nonce, uint32[] groupMembers) external view returns (uint32[] inactiveMembers) ``` Verifies the inactivity claim according to the rules defined in `Claim` struct documentation. Reverts if verification fails. Wallet signing group members hash is validated upstream in `WalletRegistry.notifyOperatorInactivity()` #### Parameters | Name | Type | Description | | ------------- | ---------------------------- | ----------------------------------------------------- | | sortitionPool | contract SortitionPool | Sortition pool reference | | claim | struct EcdsaInactivity.Claim | Inactivity claim | | walletPubKey | bytes | Public key of the wallet | | nonce | uint256 | Current inactivity nonce for wallet used in the claim | | groupMembers | uint32\[] | Identifiers of group members | #### Return Values | Name | Type | Description | | --------------- | --------- | --------------------------------------- | | inactiveMembers | uint32\[] | Identifiers of members who are inactive | ### validateMembersIndices ```solidity function validateMembersIndices(uint256[] indices, uint256 groupSize) internal pure ``` Validates members indices array. Array is considered valid if its size and each single index are in \[1, groupSize] range, indexes are unique, and sorted in an ascending order. Reverts if validation fails. #### Parameters | Name | Type | Description | | --------- | ---------- | ----------------------------- | | indices | uint256\[] | Array to validate. | | groupSize | uint256 | Group size used as reference. | # IWalletOwner ## IWalletOwner ### \_\_ecdsaWalletCreatedCallback ```solidity function __ecdsaWalletCreatedCallback(bytes32 walletID, bytes32 publicKeyX, bytes32 publicKeyY) external ``` Callback function executed once a new wallet is created. Should be callable only by the Wallet Registry. #### Parameters | Name | Type | Description | | ---------- | ------- | ----------------------------------- | | walletID | bytes32 | Wallet's unique identifier. | | publicKeyX | bytes32 | | | publicKeyY | bytes32 | Wallet's public key's X coordinate. | ### \_\_ecdsaWalletHeartbeatFailedCallback ```solidity function __ecdsaWalletHeartbeatFailedCallback(bytes32 walletID, bytes32 publicKeyX, bytes32 publicKeyY) external ``` Callback function executed once a wallet heartbeat failure is detected. Should be callable only by the Wallet Registry. #### Parameters | Name | Type | Description | | ---------- | ------- | ----------------------------------- | | walletID | bytes32 | Wallet's unique identifier. | | publicKeyX | bytes32 | | | publicKeyY | bytes32 | Wallet's public key's X coordinate. | # IWalletRegistry ## IWalletRegistry ### requestNewWallet ```solidity function requestNewWallet() external ``` Requests a new wallet creation. Only the Wallet Owner can call this function. ### closeWallet ```solidity function closeWallet(bytes32 walletID) external ``` Closes an existing wallet. Only the Wallet Owner can call this function. #### Parameters | Name | Type | Description | | -------- | ------- | ----------------- | | walletID | bytes32 | ID of the wallet. | ### seize ```solidity function seize(uint96 amount, uint256 rewardMultiplier, address notifier, bytes32 walletID, uint32[] walletMembersIDs) external ``` Adds 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. Only the Wallet Owner can call this function. 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 | | ---------------- | --------- | ---------------------------------------------------------------------------------------------------------- | | amount | uint96 | Amount of tokens to seize from each signing group member | | rewardMultiplier | uint256 | Fraction of the staking contract notifiers reward the notifier should receive; should be between \[0, 100] | | notifier | address | Address of the misbehavior notifier | | walletID | bytes32 | ID of the wallet | | walletMembersIDs | uint32\[] | Identifiers of the wallet signing group members | ### getWalletPublicKey ```solidity function getWalletPublicKey(bytes32 walletID) external view returns (bytes) ``` Gets public key of a wallet with a given wallet ID. The public key is returned in an uncompressed format as a 64-byte concatenation of X and Y coordinates. #### Parameters | Name | Type | Description | | -------- | ------- | ----------------- | | walletID | bytes32 | ID of the wallet. | #### Return Values | Name | Type | Description | | ---- | ----- | -------------------------------------- | | \[0] | bytes | Uncompressed public key of the wallet. | ### getWalletCreationState ```solidity function getWalletCreationState() external view returns (enum EcdsaDkg.State) ``` Check current wallet creation state. ### isWalletMember ```solidity function isWalletMember(bytes32 walletID, uint32[] walletMembersIDs, address operator, uint256 walletMemberIndex) external view returns (bool) ``` Checks whether the given operator is a member of the given wallet signing group. Requirements: * The `operator` parameter must be an actual sortition pool operator. * 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. * The `walletMemberIndex` must be in range \[1, walletMembersIDs.length] #### Parameters | Name | Type | Description | | ----------------- | --------- | ----------------------------------------------------------------- | | walletID | bytes32 | ID of the wallet | | walletMembersIDs | uint32\[] | Identifiers of the wallet signing group members | | operator | address | Address of the checked operator | | walletMemberIndex | uint256 | Position of the operator in the wallet signing group members list | #### Return Values | Name | Type | Description | | ---- | ---- | ---------------------------------------------------------------------------------------- | | \[0] | bool | True - if the operator is a member of the given wallet signing group. False - otherwise. | # WalletRegistry ## WalletRegistry ### authorization ```solidity struct EcdsaAuthorization.Data authorization ``` ### dkg ```solidity struct EcdsaDkg.Data dkg ``` ### wallets ```solidity struct Wallets.Data wallets ``` ### \_maliciousDkgResultSlashingAmount ```solidity uint96 _maliciousDkgResultSlashingAmount ``` Slashing amount for submitting a malicious DKG result. Every DKG result submitted can be challenged for the time of `dkg.resultChallengePeriodLength`. If the DKG result submitted is challenged and proven to be malicious, the operator who submitted the malicious result is slashed for `_maliciousDkgResultSlashingAmount`. ### \_maliciousDkgResultNotificationRewardMultiplier ```solidity uint256 _maliciousDkgResultNotificationRewardMultiplier ``` Percentage of the staking contract malicious behavior notification reward which will be transferred to the notifier reporting about a malicious DKG result. Notifiers are rewarded from a notifiers treasury pool. For example, if notification reward is 1000 and the value of the multiplier is 5, the notifier will receive: 5% of 1000 = 50 per each operator affected. ### \_sortitionPoolRewardsBanDuration ```solidity uint256 _sortitionPoolRewardsBanDuration ``` Duration of the sortition pool rewards ban imposed on operators who missed their turn for DKG result submission or who failed a heartbeat. ### \_dkgResultSubmissionGas ```solidity uint256 _dkgResultSubmissionGas ``` Calculated max gas cost for submitting a DKG result. This will be refunded as part of the DKG approval process. It is in the submitter's interest to not skip his priority turn on the approval, otherwise the refund of the DKG submission will be refunded to another group member that will call the DKG approve function. ### \_dkgResultApprovalGasOffset ```solidity uint256 _dkgResultApprovalGasOffset ``` Gas that is meant to balance the DKG result approval's overall cost. It can be updated by the governance based on the current market conditions. ### \_notifyOperatorInactivityGasOffset ```solidity uint256 _notifyOperatorInactivityGasOffset ``` Gas that is meant to balance the notification of an operator inactivity. It can be updated by the governance based on the current market conditions. ### \_notifySeedTimeoutGasOffset ```solidity uint256 _notifySeedTimeoutGasOffset ``` Gas that is meant to balance the notification of a seed for DKG delivery timeout. It can be updated by the governance based on the current market conditions. ### \_notifyDkgTimeoutNegativeGasOffset ```solidity uint256 _notifyDkgTimeoutNegativeGasOffset ``` Gas that is meant to balance the notification of a DKG protocol execution timeout. It can be updated by the governance based on the current market conditions. The value is subtracted for the refundable gas calculation, as the DKG timeout notification transaction recovers some gas when cleaning up the storage. ### inactivityClaimNonce ```solidity mapping(bytes32 => uint256) inactivityClaimNonce ``` Stores current operator inactivity claim nonce for the given wallet signing group. Each claim is made with a unique nonce which protects against claim replay. ### walletOwner ```solidity contract IWalletOwner walletOwner ``` ### sortitionPool ```solidity contract SortitionPool sortitionPool ``` ### staking ```solidity contract IStaking staking ``` ### randomBeacon ```solidity contract IRandomBeacon randomBeacon ``` ### DkgStarted ```solidity event DkgStarted(uint256 seed) ``` ### DkgResultSubmitted ```solidity event DkgResultSubmitted(bytes32 resultHash, uint256 seed, struct EcdsaDkg.Result result) ``` ### DkgTimedOut ```solidity event DkgTimedOut() ``` ### DkgResultApproved ```solidity event DkgResultApproved(bytes32 resultHash, address approver) ``` ### DkgResultChallenged ```solidity event DkgResultChallenged(bytes32 resultHash, address challenger, string reason) ``` ### DkgStateLocked ```solidity event DkgStateLocked() ``` ### DkgSeedTimedOut ```solidity event DkgSeedTimedOut() ``` ### WalletCreated ```solidity event WalletCreated(bytes32 walletID, bytes32 dkgResultHash) ``` ### WalletClosed ```solidity event WalletClosed(bytes32 walletID) ``` ### DkgMaliciousResultSlashed ```solidity event DkgMaliciousResultSlashed(bytes32 resultHash, uint256 slashingAmount, address maliciousSubmitter) ``` ### DkgMaliciousResultSlashingFailed ```solidity event DkgMaliciousResultSlashingFailed(bytes32 resultHash, uint256 slashingAmount, address maliciousSubmitter) ``` ### AuthorizationParametersUpdated ```solidity event AuthorizationParametersUpdated(uint96 minimumAuthorization, uint64 authorizationDecreaseDelay, uint64 authorizationDecreaseChangePeriod) ``` ### RewardParametersUpdated ```solidity event Re