diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md index 762c04c..31e6efd 100644 --- a/docs/SUMMARY.md +++ b/docs/SUMMARY.md @@ -80,12 +80,89 @@ * [Get Started (PRE Mainnet)](app-development/threshold-access-control-tac/advanced-usage/proxy-re-encryption.md) * [Contribution Guide](app-development/contribution-guide.md) * [Staking Contract and DAO](app-development/staking-contract-and-dao/README.md) - * [Random Beacon API](app-development/staking-contract-and-dao/staking-contract-and-dao-api/generated-docs/index.md) + * [Staking Contract and DAO API](app-development/staking-contract-and-dao/staking-contract-and-dao-api/README.md) + * [BaseTokenholderGovernor](app-development/staking-contract-and-dao/staking-contract-and-dao-api/generated-docs/governance/BaseTokenholderGovernor.md) + * [Checkpoints](app-development/staking-contract-and-dao/staking-contract-and-dao-api/generated-docs/governance/Checkpoints.md) + * [GovernorParameters](app-development/staking-contract-and-dao/staking-contract-and-dao-api/generated-docs/governance/GovernorParameters.md) + * [IApplication](app-development/staking-contract-and-dao/staking-contract-and-dao-api/generated-docs/staking/IApplication.md) + * [ILegacyTokenStaking](app-development/staking-contract-and-dao/staking-contract-and-dao-api/generated-docs/staking/ILegacyTokenStaking.md) + * [IStaking](app-development/staking-contract-and-dao/staking-contract-and-dao-api/generated-docs/staking/IStaking.md) + * [IVotesHistory](app-development/staking-contract-and-dao/staking-contract-and-dao-api/generated-docs/governance/IVotesHistory.md) + * [KeepStake](app-development/staking-contract-and-dao/staking-contract-and-dao-api/generated-docs/staking/KeepStake.md) + * [PercentUtils](app-development/staking-contract-and-dao/staking-contract-and-dao-api/generated-docs/utils/PercentUtils.md) + * [ProxyAdminWithDeputy](app-development/staking-contract-and-dao/staking-contract-and-dao-api/generated-docs/governance/ProxyAdminWithDeputy.md) + * [SafeTUpgradeable](app-development/staking-contract-and-dao/staking-contract-and-dao-api/generated-docs/utils/SafeTUpgradeable.md) + * [StakerGovernor](app-development/staking-contract-and-dao/staking-contract-and-dao-api/generated-docs/governance/StakerGovernor.md) + * [StakerGovernorVotes](app-development/staking-contract-and-dao/staking-contract-and-dao-api/generated-docs/governance/StakerGovernorVotes.md) + * [T](app-development/staking-contract-and-dao/staking-contract-and-dao-api/generated-docs/token/T.md) + * [TokenholderGovernor](app-development/staking-contract-and-dao/staking-contract-and-dao-api/generated-docs/governance/TokenholderGovernor.md) + * [TokenholderGovernorVotes](app-development/staking-contract-and-dao/staking-contract-and-dao-api/generated-docs/governance/TokenholderGovernorVotes.md) + * [TokenStaking](app-development/staking-contract-and-dao/staking-contract-and-dao-api/generated-docs/staking/TokenStaking.md) + * [VendingMachine](app-development/staking-contract-and-dao/staking-contract-and-dao-api/generated-docs/vendingVendingMachine.md) * [Random Beacon](app-development/random-beacon/README.md) - * [Random Beacon API](app-development/random-beacon/random-beacon-api/generated-docs/index.md) -* [TBTCv2](app-development/tbtc-v2/README.md) - * [ECDSA API](app-development/tbtc-v2/ecdsa-api/generated-docs/index.md) - * [TBTCv2 API](app-development/tbtc-v2/tbtc-v2-api/generated-docs/index.md) + * [Random Beacon API](app-development/random-beacon/random-beacon-api/README.md) + * [AltBn128](app-development/random-beacon/random-beacon-api/generated-docs/libraries/AltBn128.md) + * [BeaconAuthorization](app-development/random-beacon/random-beacon-api/generated-docs/libraries/BeaconAuthorization.md) + * [BeaconDkg](app-development/random-beacon/random-beacon-api/generated-docs/libraries/BeaconDkg.md) + * [BeaconDkgValidator](app-development/random-beacon/random-beacon-api/generated-docs/BeaconDkgValidator.md) + * [BeaconInactivity](app-development/random-beacon/random-beacon-api/generated-docs/libraries/BeaconInactivity.md) + * [BLS](app-development/random-beacon/random-beacon-api/generated-docs/libraries/BLS.md) + * [BytesLib](app-development/random-beacon/random-beacon-api/generated-docs/libraries/BytesLib.md) + * [Callback](app-development/random-beacon/random-beacon-api/generated-docs/libraries/Callback.md) + * [Governable](app-development/random-beacon/random-beacon-api/generated-docs/Governable.md) + * [Groups](app-development/random-beacon/random-beacon-api/generated-docs/libraries/Groups.md) + * [IRandomBeacon](app-development/random-beacon/random-beacon-api/generated-docs/api/IRandomBeacon.md) + * [IRandomBeaconConsumer](app-development/random-beacon/random-beacon-api/generated-docs/api/IRandomBeaconConsumer.md) + * [ModUtils](app-development/random-beacon/random-beacon-api/generated-docs/libraries/ModUtils.md) + * [RandomBeacon](app-development/random-beacon/random-beacon-api/generated-docs/RandomBeacon.md) + * [RandomBeaconChaosnet](app-development/random-beacon/random-beacon-api/generated-docs/RandomBeaconChaosnet.md) + * [RandomBeaconGovernance](app-development/random-beacon/random-beacon-api/generated-docs/RandomBeaconGovernance.md) + * [Reimbursable](app-development/random-beacon/random-beacon-api/generated-docs/Reimbursable.md) + * [ReimbursementPool](app-development/random-beacon/random-beacon-api/generated-docs/ReimbursementPool.md) + * [Relay](app-development/random-beacon/random-beacon-api/generated-docs/libraries/Relay.md) +* [tBTC](app-development/tbtc-v2/README.md) + * [ECDSA API](app-development/tbtc-v2/ecdsa-api/README.md) + * [EcdsaAuthorization](app-development/tbtc-v2/ecdsa-api/generated-docs/libraries/EcdsaAuthorization.md) + * [EcdsaDkg](app-development/tbtc-v2/ecdsa-api/generated-docs/libraries/EcdsaDkg.md) + * [EcdsaDkgValidator](app-development/tbtc-v2/ecdsa-api/generated-docs/EcdsaDkgValidator.md) + * [EcdsaInactivity](app-development/tbtc-v2/ecdsa-api/generated-docs/libraries/EcdsaInactivity.md) + * [IWalletOwner](app-development/tbtc-v2/ecdsa-api/generated-docs/api/IWalletOwner.md) + * [IWalletRegistry](app-development/tbtc-v2/ecdsa-api/generated-docs/api/IWalletRegistry.md) + * [WalletRegistry](app-development/tbtc-v2/ecdsa-api/generated-docs/WalletRegistry.md) + * [WalletRegistryGovernance](app-development/tbtc-v2/ecdsa-api/generated-docs/WalletRegistryGovernance.md) + * [Wallets](app-development/tbtc-v2/ecdsa-api/generated-docs/libraries/Wallets.md) + * [Bridge API](app-development/tbtc-v2/tbtc-v2-api/README.md) + * [Bank](app-development/tbtc-v2/tbtc-v2-api/generated-docs/bank/Bank.md) + * [BitcoinTx](app-development/tbtc-v2/tbtc-v2-api/generated-docs/bridge/BitcoinTx.md) + * [Bridge](app-development/tbtc-v2/tbtc-v2-api/generated-docs/bridge/Bridge.md) + * [BridgeGovernance](app-development/tbtc-v2/tbtc-v2-api/generated-docs/bridge/BridgeGovernance.md) + * [BridgeGovernanceParameters](app-development/tbtc-v2/tbtc-v2-api/generated-docs/bridge/BridgeGovernanceParameters.md) + * [BridgeState](app-development/tbtc-v2/tbtc-v2-api/generated-docs/bridge/BridgeState.md) + * [Deposit](app-development/tbtc-v2/tbtc-v2-api/generated-docs/bridge/Deposit.md) + * [DepositSweep](app-development/tbtc-v2/tbtc-v2-api/generated-docs/bridge/DepositSweep.md) + * [DonationVault](app-development/tbtc-v2/tbtc-v2-api/generated-docs/vault/DonationVault.md) + * [EcdsaLib](app-development/tbtc-v2/tbtc-v2-api/generated-docs/bridge/EcdsaLib.md) + * [Fraud](app-development/tbtc-v2/tbtc-v2-api/generated-docs/bridge/Fraud.md) + * [GovernanceUtils](app-development/tbtc-v2/tbtc-v2-api/generated-docs/GovernanceUtils.md) + * [Heartbeat](app-development/tbtc-v2/tbtc-v2-api/generated-docs/bridge/Heartbeat.md) + * [IReceiveBalanceApproval](app-development/tbtc-v2/tbtc-v2-api/generated-docs/bank/IReceiveBalanceApproval.md) + * [IRelay](app-development/tbtc-v2/tbtc-v2-api/generated-docs/bridge/IRelay.md) + * [IVault](app-development/tbtc-v2/tbtc-v2-api/generated-docs/vault/IVault.md) + * [L2TBTC](app-development/tbtc-v2/tbtc-v2-api/generated-docs/l2/L2TBTC.md) + * [L2WormholeGateway](app-development/tbtc-v2/tbtc-v2-api/generated-docs/l2/L2WormholeGateway.md) + * [LightRelay](app-development/tbtc-v2/tbtc-v2-api/generated-docs/relay/LightRelay.md) + * [LightRelayMaintainerProxy](app-development/tbtc-v2/tbtc-v2-api/generated-docs/relay/LightRelayMaintainerProxy.md) + * [MaintainerProxy](app-development/tbtc-v2/tbtc-v2-api/generated-docs/maintainer/MaintainerProxy.md) + * [MovingFunds](app-development/tbtc-v2/tbtc-v2-api/generated-docs/bridge/MovingFunds.md) + * [Redemption](app-development/tbtc-v2/tbtc-v2-api/generated-docs/bridge/Redemption.md) + * [TBTC](app-development/tbtc-v2/tbtc-v2-api/generated-docs/token/TBTC.md) + * [TBTCOptimisticMinting](app-development/tbtc-v2/tbtc-v2-api/generated-docs/vault/TBTCOptimisticMinting.md) + * [TBTCVault](app-development/tbtc-v2/tbtc-v2-api/generated-docs/vault/TBTCVault.md) + * [VendingMachine](app-development/tbtc-v2/tbtc-v2-api/generated-docs/bridge/VendingMachine.md) + * [VendingMachineV2](app-development/tbtc-v2/tbtc-v2-api/generated-docs/bridge/VendingMachineV2.md) + * [VendingMachineV3](app-development/tbtc-v2/tbtc-v2-api/generated-docs/bridge/VendingMachineV3.md) + * [WalletCoordinator](app-development/tbtc-v2/tbtc-v2-api/generated-docs/bridge/WalletCoordinator.md) + * [Wallets](app-development/tbtc-v2/tbtc-v2-api/generated-docs/bridge/Wallets.md) ## Resources diff --git a/docs/app-development/random-beacon/random-beacon-api/README.md b/docs/app-development/random-beacon/random-beacon-api/README.md new file mode 100644 index 0000000..e37bfe7 --- /dev/null +++ b/docs/app-development/random-beacon/random-beacon-api/README.md @@ -0,0 +1,42 @@ +# Random Beacon API + +You can learn about APIs of contracts related to the Random Beacon under the +following links: + +[AltBn128](./generated-docs/libraries/AltBn128.md) + +[BeaconAuthorization](./generated-docs/libraries/BeaconAuthorization.md) + +[BeaconDkg](./generated-docs/libraries/BeaconDkg.md) + +[BeaconDkgValidator](./generated-docs/BeaconDkgValidator.md) + +[BeaconInactivity](./generated-docs/libraries/BeaconInactivity.md) + +[BLS](./generated-docs/libraries/BLS.md) + +[BytesLib](./generated-docs/libraries/BytesLib.md) + +[Callback](./generated-docs/libraries/Callback.md) + +[Governable](./generated-docs/Governable.md) + +[Groups](./generated-docs/libraries/Groups.md) + +[IRandomBeacon](./generated-docs/api/IRandomBeacon.md) + +[IRandomBeaconConsumer](./generated-docs/api/IRandomBeaconConsumer.md) + +[ModUtils](./generated-docs/libraries/ModUtils.md) + +[RandomBeacon](./generated-docs/RandomBeacon.md) + +[RandomBeaconChaosnet](./generated-docs/RandomBeaconChaosnet.md) + +[RandomBeaconGovernance](./generated-docs/RandomBeaconGovernance.md) + +[Reimbursable](./generated-docs/Reimbursable.md) + +[ReimbursementPool](./generated-docs/ReimbursementPool.md) + +[Relay](./generated-docs/libraries/Relay.md) diff --git a/docs/app-development/random-beacon/random-beacon-api/generated-docs/BeaconDkgValidator.md b/docs/app-development/random-beacon/random-beacon-api/generated-docs/BeaconDkgValidator.md new file mode 100644 index 0000000..966c273 --- /dev/null +++ b/docs/app-development/random-beacon/random-beacon-api/generated-docs/BeaconDkgValidator.md @@ -0,0 +1,175 @@ +# Solidity API + +## BeaconDkgValidator + +DKGValidator 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 the threshold relay. + +### groupThreshold + +```solidity +uint256 groupThreshold +``` + +The minimum number of group members needed to interact according to +the protocol to produce a relay entry. 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 a relay +entry. + +### 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 BeaconDkg.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 BeaconDkg.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 BeaconDkg.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 BeaconDkg.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 BeaconDkg.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 BeaconDkg.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 BeaconDkg.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 BeaconDkg.Result result) public pure returns (bool) +``` + +Performs validation of hashed group members that actively took +part in DKG. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| result | struct BeaconDkg.Result | DKG result | + +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +| [0] | bool | true if result's group members hash matches with the one that is challenged. | + diff --git a/docs/app-development/random-beacon/random-beacon-api/generated-docs/Governable.md b/docs/app-development/random-beacon/random-beacon-api/generated-docs/Governable.md new file mode 100644 index 0000000..19d0360 --- /dev/null +++ b/docs/app-development/random-beacon/random-beacon-api/generated-docs/Governable.md @@ -0,0 +1,42 @@ +# Solidity API + +## Governable + +Governable contract. + +A constructor is not defined, which makes the contract compatible with +upgradable proxies. This requires calling explicitly `_transferGovernance` +function in a child contract. + +### governance + +```solidity +address governance +``` + +### GovernanceTransferred + +```solidity +event GovernanceTransferred(address oldGovernance, address newGovernance) +``` + +### onlyGovernance + +```solidity +modifier onlyGovernance() +``` + +### transferGovernance + +```solidity +function transferGovernance(address newGovernance) external virtual +``` + +Transfers governance of the contract to `newGovernance`. + +### _transferGovernance + +```solidity +function _transferGovernance(address newGovernance) internal virtual +``` + diff --git a/docs/app-development/random-beacon/random-beacon-api/generated-docs/RandomBeacon.md b/docs/app-development/random-beacon/random-beacon-api/generated-docs/RandomBeacon.md new file mode 100644 index 0000000..141b0f0 --- /dev/null +++ b/docs/app-development/random-beacon/random-beacon-api/generated-docs/RandomBeacon.md @@ -0,0 +1,1211 @@ +# Solidity API + +## RandomBeacon + +Keep Random Beacon contract. It lets to request a new +relay entry and validates the new relay entry provided by the +network. This contract is in charge of all other Random Beacon +activities such as group lifecycle or slashing. + +Should be owned by the governance contract controlling Random Beacon +parameters. + +### genesisSeed + +```solidity +uint256 genesisSeed +``` + +Seed value used for the genesis group selection. +https://www.wolframalpha.com/input/?i=pi+to+78+digits + +### _callbackGasLimit + +```solidity +uint256 _callbackGasLimit +``` + +Relay entry callback gas limit. This is the gas limit with which +callback function provided in the relay request transaction is +executed. The callback is executed with a new relay entry value +in the same transaction the relay entry is submitted. + +### _groupCreationFrequency + +```solidity +uint256 _groupCreationFrequency +``` + +The frequency of new group creation. Groups are created with +a fixed frequency of relay requests. + +### _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`. + +### _unauthorizedSigningSlashingAmount + +```solidity +uint96 _unauthorizedSigningSlashingAmount +``` + +Slashing amount when an unauthorized signing has been proved, +which means the private key leaked and all the group members +should be punished. + +### _sortitionPoolRewardsBanDuration + +```solidity +uint256 _sortitionPoolRewardsBanDuration +``` + +Duration of the sortition pool rewards ban imposed on operators +who misbehaved during DKG by being inactive or disqualified and +for operators that were identified by the rest of group members +as inactive via `notifyOperatorInactivity`. + +### _relayEntryTimeoutNotificationRewardMultiplier + +```solidity +uint256 _relayEntryTimeoutNotificationRewardMultiplier +``` + +Percentage of the staking contract malicious behavior +notification reward which will be transferred to the notifier +reporting about relay entry timeout. 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. + +### _unauthorizedSigningNotificationRewardMultiplier + +```solidity +uint256 _unauthorizedSigningNotificationRewardMultiplier +``` + +Percentage of the staking contract malicious behavior +notification reward which will be transferred to the notifier +reporting about unauthorized signing. Notifiers are rewarded +from a notifiers treasury pool. For example, if a +notification reward is 1000 and the value of the multiplier is +5, the notifier will receive: 5% of 1000 = 50 per each +operator affected. + +### _dkgMaliciousResultNotificationRewardMultiplier + +```solidity +uint256 _dkgMaliciousResultNotificationRewardMultiplier +``` + +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. + +### _dkgResultSubmissionGas + +```solidity +uint256 _dkgResultSubmissionGas +``` + +Calculated 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. Can be updated by the governance based on the current +market conditions. + +### _notifyOperatorInactivityGasOffset + +```solidity +uint256 _notifyOperatorInactivityGasOffset +``` + +Gas that is meant to balance the operator inactivity notification +cost. Can be updated by the governance based on the current +market conditions. + +### _relayEntrySubmissionGasOffset + +```solidity +uint256 _relayEntrySubmissionGasOffset +``` + +Gas that is meant to balance the relay entry submission cost. +Can be updated by the governance based on the current market +conditions. + +### inactivityClaimNonce + +```solidity +mapping(uint64 => uint256) inactivityClaimNonce +``` + +Stores current operator inactivity claim nonce for given group. +Each claim is made with an unique nonce which protects +against claim replay. + +### authorizedRequesters + +```solidity +mapping(address => bool) authorizedRequesters +``` + +Authorized addresses that can request a relay entry. + +### sortitionPool + +```solidity +contract SortitionPool sortitionPool +``` + +### tToken + +```solidity +contract IERC20 tToken +``` + +### staking + +```solidity +contract IStaking staking +``` + +### authorization + +```solidity +struct BeaconAuthorization.Data authorization +``` + +### dkg + +```solidity +struct BeaconDkg.Data dkg +``` + +### groups + +```solidity +struct Groups.Data groups +``` + +### relay + +```solidity +struct Relay.Data relay +``` + +### callback + +```solidity +struct Callback.Data callback +``` + +### AuthorizationParametersUpdated + +```solidity +event AuthorizationParametersUpdated(uint96 minimumAuthorization, uint64 authorizationDecreaseDelay, uint64 authorizationDecreaseChangePeriod) +``` + +### RelayEntryParametersUpdated + +```solidity +event RelayEntryParametersUpdated(uint256 relayEntrySoftTimeout, uint256 relayEntryHardTimeout, uint256 callbackGasLimit) +``` + +### GroupCreationParametersUpdated + +```solidity +event GroupCreationParametersUpdated(uint256 groupCreationFrequency, uint256 groupLifetime, uint256 dkgResultChallengePeriodLength, uint256 dkgResultChallengeExtraGas, uint256 dkgResultSubmissionTimeout, uint256 dkgResultSubmitterPrecedencePeriodLength) +``` + +### RewardParametersUpdated + +```solidity +event RewardParametersUpdated(uint256 sortitionPoolRewardsBanDuration, uint256 relayEntryTimeoutNotificationRewardMultiplier, uint256 unauthorizedSigningNotificationRewardMultiplier, uint256 dkgMaliciousResultNotificationRewardMultiplier) +``` + +### SlashingParametersUpdated + +```solidity +event SlashingParametersUpdated(uint256 relayEntrySubmissionFailureSlashingAmount, uint256 maliciousDkgResultSlashingAmount, uint256 unauthorizedSigningSlashingAmount) +``` + +### GasParametersUpdated + +```solidity +event GasParametersUpdated(uint256 dkgResultSubmissionGas, uint256 dkgResultApprovalGasOffset, uint256 notifyOperatorInactivityGasOffset, uint256 relayEntrySubmissionGasOffset) +``` + +### RequesterAuthorizationUpdated + +```solidity +event RequesterAuthorizationUpdated(address requester, bool isAuthorized) +``` + +### DkgStarted + +```solidity +event DkgStarted(uint256 seed) +``` + +### DkgResultSubmitted + +```solidity +event DkgResultSubmitted(bytes32 resultHash, uint256 seed, struct BeaconDkg.Result result) +``` + +### DkgTimedOut + +```solidity +event DkgTimedOut() +``` + +### DkgResultApproved + +```solidity +event DkgResultApproved(bytes32 resultHash, address approver) +``` + +### DkgResultChallenged + +```solidity +event DkgResultChallenged(bytes32 resultHash, address challenger, string reason) +``` + +### DkgMaliciousResultSlashed + +```solidity +event DkgMaliciousResultSlashed(bytes32 resultHash, uint256 slashingAmount, address maliciousSubmitter) +``` + +### DkgMaliciousResultSlashingFailed + +```solidity +event DkgMaliciousResultSlashingFailed(bytes32 resultHash, uint256 slashingAmount, address maliciousSubmitter) +``` + +### DkgStateLocked + +```solidity +event DkgStateLocked() +``` + +### DkgSeedTimedOut + +```solidity +event DkgSeedTimedOut() +``` + +### GroupRegistered + +```solidity +event GroupRegistered(uint64 groupId, bytes groupPubKey) +``` + +### RelayEntryRequested + +```solidity +event RelayEntryRequested(uint256 requestId, uint64 groupId, bytes previousEntry) +``` + +### RelayEntrySubmitted + +```solidity +event RelayEntrySubmitted(uint256 requestId, address submitter, bytes entry) +``` + +### RelayEntryTimedOut + +```solidity +event RelayEntryTimedOut(uint256 requestId, uint64 terminatedGroupId) +``` + +### RelayEntryDelaySlashed + +```solidity +event RelayEntryDelaySlashed(uint256 requestId, uint256 slashingAmount, address[] groupMembers) +``` + +### RelayEntryDelaySlashingFailed + +```solidity +event RelayEntryDelaySlashingFailed(uint256 requestId, uint256 slashingAmount, address[] groupMembers) +``` + +### RelayEntryTimeoutSlashed + +```solidity +event RelayEntryTimeoutSlashed(uint256 requestId, uint256 slashingAmount, address[] groupMembers) +``` + +### RelayEntryTimeoutSlashingFailed + +```solidity +event RelayEntryTimeoutSlashingFailed(uint256 requestId, uint256 slashingAmount, address[] groupMembers) +``` + +### UnauthorizedSigningSlashed + +```solidity +event UnauthorizedSigningSlashed(uint64 groupId, uint256 unauthorizedSigningSlashingAmount, address[] groupMembers) +``` + +### UnauthorizedSigningSlashingFailed + +```solidity +event UnauthorizedSigningSlashingFailed(uint64 groupId, uint256 unauthorizedSigningSlashingAmount, address[] groupMembers) +``` + +### CallbackFailed + +```solidity +event CallbackFailed(uint256 entry, uint256 entrySubmittedBlock) +``` + +### InactivityClaimed + +```solidity +event InactivityClaimed(uint64 groupId, uint256 nonce, address notifier) +``` + +### 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) +``` + +### constructor + +```solidity +constructor(contract SortitionPool _sortitionPool, contract IERC20 _tToken, contract IStaking _staking, contract BeaconDkgValidator _dkgValidator, contract ReimbursementPool _reimbursementPool) public +``` + +Assigns initial values to parameters to make the beacon work +safely. These parameters are just proposed defaults and they might +be updated with `update*` functions after the contract deployment +and before transferring the ownership to the governance contract. + +### onlyStakingContract + +```solidity +modifier onlyStakingContract() +``` + +### onlyReimbursableAdmin + +```solidity +modifier onlyReimbursableAdmin() +``` + +### 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 +random beacon 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 | + +### updateRelayEntryParameters + +```solidity +function updateRelayEntryParameters(uint256 relayEntrySoftTimeout, uint256 relayEntryHardTimeout, uint256 callbackGasLimit) external +``` + +Updates the values of relay entry parameters. + +Can be called only by the contract guvnor, which should be the +random beacon governance contract. The caller is responsible for +validating parameters. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| relayEntrySoftTimeout | uint256 | New relay entry submission soft timeout | +| relayEntryHardTimeout | uint256 | New relay entry hard timeout | +| callbackGasLimit | uint256 | New callback gas limit | + +### updateGroupCreationParameters + +```solidity +function updateGroupCreationParameters(uint256 groupCreationFrequency, uint256 groupLifetime, uint256 dkgResultChallengePeriodLength, uint256 dkgResultChallengeExtraGas, uint256 dkgResultSubmissionTimeout, uint256 dkgSubmitterPrecedencePeriodLength) external +``` + +Updates the values of group creation parameters. + +Can be called only by the contract guvnor, which should be the +random beacon governance contract. The caller is responsible for +validating parameters. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| groupCreationFrequency | uint256 | New group creation frequency | +| groupLifetime | uint256 | New group lifetime in blocks | +| dkgResultChallengePeriodLength | uint256 | New DKG result challenge period length | +| dkgResultChallengeExtraGas | uint256 | New DKG result challenge extra gas | +| dkgResultSubmissionTimeout | uint256 | New DKG result submission timeout | +| dkgSubmitterPrecedencePeriodLength | uint256 | New DKG result submitter precedence period length | + +### updateRewardParameters + +```solidity +function updateRewardParameters(uint256 sortitionPoolRewardsBanDuration, uint256 relayEntryTimeoutNotificationRewardMultiplier, uint256 unauthorizedSigningNotificationRewardMultiplier, uint256 dkgMaliciousResultNotificationRewardMultiplier) external +``` + +Updates the values of reward parameters. + +Can be called only by the contract guvnor, which should be the +random beacon governance contract. The caller is responsible for +validating parameters. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| sortitionPoolRewardsBanDuration | uint256 | New sortition pool rewards ban duration in seconds. | +| relayEntryTimeoutNotificationRewardMultiplier | uint256 | New value of the relay entry timeout notification reward multiplier | +| unauthorizedSigningNotificationRewardMultiplier | uint256 | New value of the unauthorized signing notification reward multiplier | +| dkgMaliciousResultNotificationRewardMultiplier | uint256 | New value of the DKG malicious result notification reward multiplier | + +### updateSlashingParameters + +```solidity +function updateSlashingParameters(uint96 relayEntrySubmissionFailureSlashingAmount, uint96 maliciousDkgResultSlashingAmount, uint96 unauthorizedSigningSlashingAmount) external +``` + +Updates the values of slashing parameters. + +Can be called only by the contract guvnor, which should be the +random beacon governance contract. The caller is responsible for +validating parameters. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| relayEntrySubmissionFailureSlashingAmount | uint96 | New relay entry submission failure amount | +| maliciousDkgResultSlashingAmount | uint96 | New malicious DKG result slashing amount | +| unauthorizedSigningSlashingAmount | uint96 | New unauthorized signing slashing amount | + +### updateGasParameters + +```solidity +function updateGasParameters(uint256 dkgResultSubmissionGas, uint256 dkgResultApprovalGasOffset, uint256 notifyOperatorInactivityGasOffset, uint256 relayEntrySubmissionGasOffset) external +``` + +Updates the values of gas parameters. + +Can be called only by the contract guvnor, which should be the +random beacon 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 | +| relayEntrySubmissionGasOffset | uint256 | New relay entry submission gas offset | + +### setRequesterAuthorization + +```solidity +function setRequesterAuthorization(address requester, bool isAuthorized) external +``` + +Set authorization for requesters that can request a relay +entry. + +Can be called only by the contract guvnor, which should be the +random beacon governance contract. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| requester | address | Requester, can be a contract or EOA | +| isAuthorized | bool | True or false | + +### 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 +random beacon 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 a 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 the beacon. 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 beacon 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 beacon 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. + +Reverts if another authorization decrease request is pending for +the staking provider and not enough time passed since the +original request (see `authorizationDecreaseChangePeriod`). + +If the operator is not known (`registerOperator` was not called) +it lets to `approveAuthorizationDecrease` immediately. 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, but only if enough time passed since the original +request. Otherwise, the function reverts. + +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 beacon 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. + +### genesis + +```solidity +function genesis() external +``` + +Triggers group selection if there are no active groups. + +### submitDkgResult + +```solidity +function submitDkgResult(struct BeaconDkg.Result dkgResult) external +``` + +`\x19Ethereum signed message:\n` before signing, so the message to +sign is: +`\x19Ethereum signed message:\n${keccak256(chainID,groupPubKey,misbehaved,startBlock)}` + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| dkgResult | struct BeaconDkg.Result | DKG result. | + +### notifyDkgTimeout + +```solidity +function notifyDkgTimeout() external +``` + +Notifies about DKG timeout. + +### approveDkgResult + +```solidity +function approveDkgResult(struct BeaconDkg.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 `submitterPrecedencePeriodLength` +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. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| dkgResult | struct BeaconDkg.Result | Result to approve. Must match the submitted result stored during `submitDkgResult`. | + +### challengeDkgResult + +```solidity +function challengeDkgResult(struct BeaconDkg.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. +It removes a candidate group that was previously registered with +the DKG result submission. + +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 BeaconDkg.Result | Result to challenge. Must match the submitted result stored during `submitDkgResult`. | + +### getGroupCreationState + +```solidity +function getGroupCreationState() external view returns (enum BeaconDkg.State) +``` + +Check current group creation state. + +### hasDkgTimedOut + +```solidity +function hasDkgTimedOut() external view returns (bool) +``` + +Checks if DKG timed out. The DKG timeout period includes time required +for off-chain protocol execution and time for the result publication +for all group members. After this time result cannot be submitted +and DKG can be notified about the timeout. + +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +| [0] | bool | True if DKG timed out, false otherwise. | + +### getGroupsRegistry + +```solidity +function getGroupsRegistry() external view returns (bytes32[]) +``` + +### getGroup + +```solidity +function getGroup(uint64 groupId) external view returns (struct Groups.Group) +``` + +### getGroup + +```solidity +function getGroup(bytes groupPubKey) external view returns (struct Groups.Group) +``` + +### requestRelayEntry + +```solidity +function requestRelayEntry(contract IRandomBeaconConsumer callbackContract) external +``` + +Creates a request to generate a new relay entry, which will +include a random number (by signing the previous entry's +random number). Requester must be previously authorized by the +governance. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| callbackContract | contract IRandomBeaconConsumer | Beacon consumer callback contract. | + +### submitRelayEntry + +```solidity +function submitRelayEntry(bytes entry) external +``` + +Creates a new relay entry. Gas-optimized version that can be +called only before the soft timeout. This should be the majority +of cases. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| entry | bytes | Group BLS signature over the previous entry. | + +### submitRelayEntry + +```solidity +function submitRelayEntry(bytes entry, uint32[] groupMembers) external +``` + +Creates a new relay entry. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| entry | bytes | Group BLS signature over the previous entry. | +| groupMembers | uint32[] | Identifiers of group members. | + +### reportRelayEntryTimeout + +```solidity +function reportRelayEntryTimeout(uint32[] groupMembers) external +``` + +Reports a relay entry timeout. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| groupMembers | uint32[] | Identifiers of group members. | + +### reportUnauthorizedSigning + +```solidity +function reportUnauthorizedSigning(bytes signedMsgSender, uint64 groupId, uint32[] groupMembers) external +``` + +Reports unauthorized groups signing. Must provide a valid signature +of the sender's address as a message. Successful signature +verification means the private key has been leaked and all group +members should be punished by slashing their tokens. Group has +to be active or expired. Unauthorized signing cannot be reported +for a terminated group. In case of reporting unauthorized +signing for a terminated group, or when the signature is invalid, +function reverts. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| signedMsgSender | bytes | Signature of the sender's address as a message. | +| groupId | uint64 | Group that is being reported for leaking a private key. | +| groupMembers | uint32[] | Identifiers of group members. | + +### notifyOperatorInactivity + +```solidity +function notifyOperatorInactivity(struct BeaconInactivity.Claim claim, uint256 nonce, uint32[] groupMembers) external +``` + +Notifies about operators who are inactive. Using this function, +a majority of the 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 for sortition pool rewards for duration specified by +`_sortitionPoolRewardsBanDuration` parameter. The sender of +the claim must be one of the claim signers. This function can be +called only for active and non-terminated groups. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| claim | struct BeaconInactivity.Claim | Operator inactivity claim. | +| nonce | uint256 | Current inactivity claim nonce for the given group. Must be the same as the stored one. | +| groupMembers | uint32[] | Identifiers of group members. | + +### minimumAuthorization + +```solidity +function minimumAuthorization() external view returns (uint96) +``` + +The minimum authorization amount required so that operator can +participate in the random beacon. This amount is required to +execute slashing for providing a malicious DKG result or when +a relay entry times out. + +### isRelayRequestInProgress + +```solidity +function isRelayRequestInProgress() external view returns (bool) +``` + +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +| [0] | bool | Flag indicating whether a relay entry request is currently in progress. | + +### eligibleStake + +```solidity +function eligibleStake(address stakingProvider) external view returns (uint96) +``` + +Returns the current value of the staking provider's eligible +stake. Eligible stake is defined as the currently authorized +stake minus the pending authorization decrease. Eligible stake +is what is used for operator's weight in the sortition pool. +If the authorized stake minus the pending authorization decrease +is below the minimum authorization, eligible stake is 0. + +### availableRewards + +```solidity +function availableRewards(address stakingProvider) external view returns (uint96) +``` + +Returns the amount of rewards available for withdrawal for the +given staking provider. Reverts if staking provider has not +registered the operator address. + +### pendingAuthorizationDecrease + +```solidity +function pendingAuthorizationDecrease(address stakingProvider) external view returns (uint96) +``` + +Returns the amount of stake that is pending authorization +decrease for the given staking provider. If no authorization +decrease has been requested, returns zero. + +### remainingAuthorizationDecreaseDelay + +```solidity +function remainingAuthorizationDecreaseDelay(address stakingProvider) external view returns (uint64) +``` + +Returns the remaining time in seconds that needs to pass before +the requested authorization decrease can be approved. +If the sortition pool state was not updated yet by the operator +after requesting the authorization decrease, returns +`type(uint64).max`. + +### stakingProviderToOperator + +```solidity +function stakingProviderToOperator(address stakingProvider) public view returns (address) +``` + +Returns operator registered for the given staking provider. + +### operatorToStakingProvider + +```solidity +function operatorToStakingProvider(address operator) public view returns (address) +``` + +Returns staking provider of the given operator. + +### isOperatorUpToDate + +```solidity +function isOperatorUpToDate(address operator) external view returns (bool) +``` + +Checks if the operator's authorized stake is in sync with +operator's weight in the sortition pool. +If the operator is not in the sortition pool and their +authorized stake is non-zero, function returns false. + +### isOperatorInPool + +```solidity +function isOperatorInPool(address operator) external view returns (bool) +``` + +Returns true if the given operator is in the sortition pool. +Otherwise, returns false. + +### selectGroup + +```solidity +function selectGroup() external view returns (uint32[]) +``` + +Selects a new group of operators. Can only be called when DKG +is in progress and the pool is locked. +At least one operator has to be registered in the pool, +otherwise the function fails reverting the transaction. + +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +| [0] | uint32[] | IDs of selected group members. | + +### authorizationParameters + +```solidity +function authorizationParameters() external view returns (uint96 minimumAuthorization, uint64 authorizationDecreaseDelay, uint64 authorizationDecreaseChangePeriod) +``` + +Returns authorization-related parameters of the beacon. + +The minimum authorization is also returned by `minimumAuthorization()` +function, as a requirement of `IApplication` interface. + +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +| minimumAuthorization | uint96 | The minimum authorization amount required so that operator can participate in the random beacon. This amount is required to execute slashing for providing a malicious DKG result or when a relay entry times out. | +| authorizationDecreaseDelay | uint64 | Delay in seconds that needs to pass between the time authorization decrease is requested and the time that request gets approved. Protects against free-riders earning rewards and not being active in the network. | +| authorizationDecreaseChangePeriod | uint64 | Authorization decrease change period in seconds. It is the time, before authorization decrease delay end, during which the pending authorization decrease request can be overwritten. If set to 0, pending authorization decrease request can not be overwritten until the entire `authorizationDecreaseDelay` ends. If set to value equal `authorizationDecreaseDelay`, request can always be overwritten. | + +### relayEntryParameters + +```solidity +function relayEntryParameters() external view returns (uint256 relayEntrySoftTimeout, uint256 relayEntryHardTimeout, uint256 callbackGasLimit) +``` + +Returns relay-entry-related parameters of the beacon. + +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +| relayEntrySoftTimeout | uint256 | Soft timeout in blocks for a group to submit the relay entry. If the soft timeout is reached for submitting the relay entry, the slashing starts. | +| relayEntryHardTimeout | uint256 | Hard timeout in blocks for a group to submit the relay entry. After the soft timeout passes without relay entry submitted, all group members start getting slashed. The slashing amount increases linearly until the group submits the relay entry or until `relayEntryHardTimeout` is reached. When the hard timeout is reached, each group member will get slashed for `_relayEntrySubmissionFailureSlashingAmount`. | +| callbackGasLimit | uint256 | Relay entry callback gas limit. This is the gas limit with which callback function provided in the relay request transaction is executed. The callback is executed with a new relay entry value in the same transaction the relay entry is submitted. | + +### groupCreationParameters + +```solidity +function groupCreationParameters() external view returns (uint256 groupCreationFrequency, uint256 groupLifetime, uint256 dkgResultChallengePeriodLength, uint256 dkgResultChallengeExtraGas, uint256 dkgResultSubmissionTimeout, uint256 dkgSubmitterPrecedencePeriodLength) +``` + +Returns group-creation-related parameters of the beacon. + +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +| groupCreationFrequency | uint256 | The frequency of a new group creation. Groups are created with a fixed frequency of relay requests. | +| groupLifetime | uint256 | Group lifetime in blocks. When a group reached its lifetime, it is no longer selected for new relay requests but may still be responsible for submitting relay entry if relay request assigned to that group is still pending. | +| dkgResultChallengePeriodLength | uint256 | The number of blocks for which a DKG result can be challenged. Anyone can challenge DKG result for a certain number of blocks before the result is fully accepted and the group registered in the pool of active groups. If the challenge gets accepted, all operators who signed the malicious result get slashed for and the notifier gets rewarded. | +| dkgResultChallengeExtraGas | uint256 | The extra gas required to be left at the end of the challenge DKG result transaction. | +| dkgResultSubmissionTimeout | uint256 | Timeout in blocks for a group to submit the DKG result. All members are eligible to submit the DKG result. If `dkgResultSubmissionTimeout` passes without the DKG result submitted, DKG is considered as timed out and no DKG result for this group creation can be submitted anymore. | +| dkgSubmitterPrecedencePeriodLength | uint256 | Time during the DKG result approval stage when the submitter of the DKG result takes the precedence to approve the DKG result. After this time passes anyone can approve the DKG result. | + +### rewardParameters + +```solidity +function rewardParameters() external view returns (uint256 sortitionPoolRewardsBanDuration, uint256 relayEntryTimeoutNotificationRewardMultiplier, uint256 unauthorizedSigningNotificationRewardMultiplier, uint256 dkgMaliciousResultNotificationRewardMultiplier) +``` + +Returns reward-related parameters of the beacon. + +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +| sortitionPoolRewardsBanDuration | uint256 | Duration of the sortition pool rewards ban imposed on operators who misbehaved during DKG by being inactive or disqualified and for operators that were identified by the rest of group members as inactive via `notifyOperatorInactivity`. | +| relayEntryTimeoutNotificationRewardMultiplier | uint256 | Percentage of the staking contract malicious behavior notification reward which will be transferred to the notifier reporting about relay entry timeout. 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. | +| unauthorizedSigningNotificationRewardMultiplier | uint256 | Percentage of the staking contract malicious behavior notification reward which will be transferred to the notifier reporting about unauthorized signing. Notifiers are rewarded from a notifiers treasury pool. For example, if a notification reward is 1000 and the value of the multiplier is 5, the notifier will receive: 5% of 1000 = 50 per each operator affected. | +| dkgMaliciousResultNotificationRewardMultiplier | uint256 | 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. | + +### slashingParameters + +```solidity +function slashingParameters() external view returns (uint96 relayEntrySubmissionFailureSlashingAmount, uint96 maliciousDkgResultSlashingAmount, uint96 unauthorizedSigningSlashingAmount) +``` + +Returns slashing-related parameters of the beacon. + +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +| relayEntrySubmissionFailureSlashingAmount | uint96 | Slashing amount for not submitting relay entry. When relay entry hard timeout is reached without the relay entry submitted, each group member gets slashed for `relayEntrySubmissionFailureSlashingAmount`. If the relay entry gets submitted after the soft timeout, but before the hard timeout, each group member gets slashed proportionally to `relayEntrySubmissionFailureSlashingAmount` and the time passed since the soft deadline. | +| maliciousDkgResultSlashingAmount | uint96 | 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`. | +| unauthorizedSigningSlashingAmount | uint96 | Slashing amount when an unauthorized signing has been proved, which means the private key leaked and all the group members should be punished. | + +### gasParameters + +```solidity +function gasParameters() external view returns (uint256 dkgResultSubmissionGas, uint256 dkgResultApprovalGasOffset, uint256 notifyOperatorInactivityGasOffset, uint256 relayEntrySubmissionGasOffset) +``` + +Returns gas-related parameters of the beacon. + +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +| dkgResultSubmissionGas | uint256 | Calculated gas cost for submitting a DKG result. This will be refunded as part of the DKG approval process. | +| dkgResultApprovalGasOffset | uint256 | Gas that is meant to balance the DKG result approval's overall cost. | +| notifyOperatorInactivityGasOffset | uint256 | Gas that is meant to balance the operator inactivity notification cost. | +| relayEntrySubmissionGasOffset | uint256 | Gas that is meant to balance the relay entry submission cost. | + diff --git a/docs/app-development/random-beacon/random-beacon-api/generated-docs/RandomBeaconChaosnet.md b/docs/app-development/random-beacon/random-beacon-api/generated-docs/RandomBeaconChaosnet.md new file mode 100644 index 0000000..1900b29 --- /dev/null +++ b/docs/app-development/random-beacon/random-beacon-api/generated-docs/RandomBeaconChaosnet.md @@ -0,0 +1,54 @@ +# Solidity API + +## RandomBeaconChaosnet + +A stub contract that will be used temporarily until the real-world +random beacon client implementation is ready. + +### authorizedRequesters + +```solidity +mapping(address => bool) authorizedRequesters +``` + +Authorized addresses that can request a relay entry. + +### entry + +```solidity +uint256 entry +``` + +Arbitrary relay entry. Initially set to the Euler's number. +It's updated after each relay entry request. + +### RequesterAuthorizationUpdated + +```solidity +event RequesterAuthorizationUpdated(address requester, bool isAuthorized) +``` + +### requestRelayEntry + +```solidity +function requestRelayEntry(contract IRandomBeaconConsumer callbackContract) external +``` + +Executes the callback with an arbitrary relay entry number. + +The caller must be an authorized requester. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| callbackContract | contract IRandomBeaconConsumer | Beacon consumer callback contract - Wallet Registry | + +### setRequesterAuthorization + +```solidity +function setRequesterAuthorization(address requester, bool isAuthorized) external +``` + +Authorizes a requester of the relay entry. + diff --git a/docs/app-development/random-beacon/random-beacon-api/generated-docs/RandomBeaconGovernance.md b/docs/app-development/random-beacon/random-beacon-api/generated-docs/RandomBeaconGovernance.md new file mode 100644 index 0000000..7a3ca54 --- /dev/null +++ b/docs/app-development/random-beacon/random-beacon-api/generated-docs/RandomBeaconGovernance.md @@ -0,0 +1,1751 @@ +# Solidity API + +## RandomBeaconGovernance + +Owns the `RandomBeacon` contract and is responsible for updating its +governable parameters in respect to governance delay individual +for each parameter. + +### newGovernanceDelay + +```solidity +uint256 newGovernanceDelay +``` + +### governanceDelayChangeInitiated + +```solidity +uint256 governanceDelayChangeInitiated +``` + +### newRandomBeaconGovernance + +```solidity +address newRandomBeaconGovernance +``` + +### randomBeaconGovernanceTransferInitiated + +```solidity +uint256 randomBeaconGovernanceTransferInitiated +``` + +### newRelayEntrySoftTimeout + +```solidity +uint256 newRelayEntrySoftTimeout +``` + +### relayEntrySoftTimeoutChangeInitiated + +```solidity +uint256 relayEntrySoftTimeoutChangeInitiated +``` + +### newRelayEntryHardTimeout + +```solidity +uint256 newRelayEntryHardTimeout +``` + +### relayEntryHardTimeoutChangeInitiated + +```solidity +uint256 relayEntryHardTimeoutChangeInitiated +``` + +### newCallbackGasLimit + +```solidity +uint256 newCallbackGasLimit +``` + +### callbackGasLimitChangeInitiated + +```solidity +uint256 callbackGasLimitChangeInitiated +``` + +### newGroupCreationFrequency + +```solidity +uint256 newGroupCreationFrequency +``` + +### groupCreationFrequencyChangeInitiated + +```solidity +uint256 groupCreationFrequencyChangeInitiated +``` + +### newGroupLifetime + +```solidity +uint256 newGroupLifetime +``` + +### groupLifetimeChangeInitiated + +```solidity +uint256 groupLifetimeChangeInitiated +``` + +### newDkgResultChallengePeriodLength + +```solidity +uint256 newDkgResultChallengePeriodLength +``` + +### dkgResultChallengePeriodLengthChangeInitiated + +```solidity +uint256 dkgResultChallengePeriodLengthChangeInitiated +``` + +### newDkgResultChallengeExtraGas + +```solidity +uint256 newDkgResultChallengeExtraGas +``` + +### dkgResultChallengeExtraGasChangeInitiated + +```solidity +uint256 dkgResultChallengeExtraGasChangeInitiated +``` + +### newDkgResultSubmissionTimeout + +```solidity +uint256 newDkgResultSubmissionTimeout +``` + +### dkgResultSubmissionTimeoutChangeInitiated + +```solidity +uint256 dkgResultSubmissionTimeoutChangeInitiated +``` + +### newDkgSubmitterPrecedencePeriodLength + +```solidity +uint256 newDkgSubmitterPrecedencePeriodLength +``` + +### dkgSubmitterPrecedencePeriodLengthChangeInitiated + +```solidity +uint256 dkgSubmitterPrecedencePeriodLengthChangeInitiated +``` + +### newRelayEntrySubmissionFailureSlashingAmount + +```solidity +uint96 newRelayEntrySubmissionFailureSlashingAmount +``` + +### relayEntrySubmissionFailureSlashingAmountChangeInitiated + +```solidity +uint256 relayEntrySubmissionFailureSlashingAmountChangeInitiated +``` + +### newMaliciousDkgResultSlashingAmount + +```solidity +uint96 newMaliciousDkgResultSlashingAmount +``` + +### maliciousDkgResultSlashingAmountChangeInitiated + +```solidity +uint256 maliciousDkgResultSlashingAmountChangeInitiated +``` + +### newUnauthorizedSigningSlashingAmount + +```solidity +uint96 newUnauthorizedSigningSlashingAmount +``` + +### unauthorizedSigningSlashingAmountChangeInitiated + +```solidity +uint256 unauthorizedSigningSlashingAmountChangeInitiated +``` + +### newSortitionPoolRewardsBanDuration + +```solidity +uint256 newSortitionPoolRewardsBanDuration +``` + +### sortitionPoolRewardsBanDurationChangeInitiated + +```solidity +uint256 sortitionPoolRewardsBanDurationChangeInitiated +``` + +### newRelayEntryTimeoutNotificationRewardMultiplier + +```solidity +uint256 newRelayEntryTimeoutNotificationRewardMultiplier +``` + +### relayEntryTimeoutNotificationRewardMultiplierChangeInitiated + +```solidity +uint256 relayEntryTimeoutNotificationRewardMultiplierChangeInitiated +``` + +### newUnauthorizedSigningNotificationRewardMultiplier + +```solidity +uint256 newUnauthorizedSigningNotificationRewardMultiplier +``` + +### unauthorizedSigningNotificationRewardMultiplierChangeInitiated + +```solidity +uint256 unauthorizedSigningNotificationRewardMultiplierChangeInitiated +``` + +### newMinimumAuthorization + +```solidity +uint96 newMinimumAuthorization +``` + +### minimumAuthorizationChangeInitiated + +```solidity +uint256 minimumAuthorizationChangeInitiated +``` + +### newAuthorizationDecreaseDelay + +```solidity +uint64 newAuthorizationDecreaseDelay +``` + +### authorizationDecreaseDelayChangeInitiated + +```solidity +uint256 authorizationDecreaseDelayChangeInitiated +``` + +### newAuthorizationDecreaseChangePeriod + +```solidity +uint64 newAuthorizationDecreaseChangePeriod +``` + +### authorizationDecreaseChangePeriodChangeInitiated + +```solidity +uint256 authorizationDecreaseChangePeriodChangeInitiated +``` + +### newDkgMaliciousResultNotificationRewardMultiplier + +```solidity +uint256 newDkgMaliciousResultNotificationRewardMultiplier +``` + +### dkgMaliciousResultNotificationRewardMultiplierChangeInitiated + +```solidity +uint256 dkgMaliciousResultNotificationRewardMultiplierChangeInitiated +``` + +### newDkgResultSubmissionGas + +```solidity +uint256 newDkgResultSubmissionGas +``` + +### dkgResultSubmissionGasChangeInitiated + +```solidity +uint256 dkgResultSubmissionGasChangeInitiated +``` + +### newDkgResultApprovalGasOffset + +```solidity +uint256 newDkgResultApprovalGasOffset +``` + +### dkgResultApprovalGasOffsetChangeInitiated + +```solidity +uint256 dkgResultApprovalGasOffsetChangeInitiated +``` + +### newNotifyOperatorInactivityGasOffset + +```solidity +uint256 newNotifyOperatorInactivityGasOffset +``` + +### notifyOperatorInactivityGasOffsetChangeInitiated + +```solidity +uint256 notifyOperatorInactivityGasOffsetChangeInitiated +``` + +### newRelayEntrySubmissionGasOffset + +```solidity +uint256 newRelayEntrySubmissionGasOffset +``` + +### relayEntrySubmissionGasOffsetChangeInitiated + +```solidity +uint256 relayEntrySubmissionGasOffsetChangeInitiated +``` + +### randomBeacon + +```solidity +contract RandomBeacon randomBeacon +``` + +### governanceDelay + +```solidity +uint256 governanceDelay +``` + +### GovernanceDelayUpdateStarted + +```solidity +event GovernanceDelayUpdateStarted(uint256 governanceDelay, uint256 timestamp) +``` + +### GovernanceDelayUpdated + +```solidity +event GovernanceDelayUpdated(uint256 governanceDelay) +``` + +### RandomBeaconGovernanceTransferStarted + +```solidity +event RandomBeaconGovernanceTransferStarted(address newRandomBeaconGovernance, uint256 timestamp) +``` + +### RandomBeaconGovernanceTransferred + +```solidity +event RandomBeaconGovernanceTransferred(address newRandomBeaconGovernance) +``` + +### RelayEntrySoftTimeoutUpdateStarted + +```solidity +event RelayEntrySoftTimeoutUpdateStarted(uint256 relayEntrySoftTimeout, uint256 timestamp) +``` + +### RelayEntrySoftTimeoutUpdated + +```solidity +event RelayEntrySoftTimeoutUpdated(uint256 relayEntrySoftTimeout) +``` + +### RelayEntryHardTimeoutUpdateStarted + +```solidity +event RelayEntryHardTimeoutUpdateStarted(uint256 relayEntryHardTimeout, uint256 timestamp) +``` + +### RelayEntryHardTimeoutUpdated + +```solidity +event RelayEntryHardTimeoutUpdated(uint256 relayEntryHardTimeout) +``` + +### CallbackGasLimitUpdateStarted + +```solidity +event CallbackGasLimitUpdateStarted(uint256 callbackGasLimit, uint256 timestamp) +``` + +### CallbackGasLimitUpdated + +```solidity +event CallbackGasLimitUpdated(uint256 callbackGasLimit) +``` + +### GroupCreationFrequencyUpdateStarted + +```solidity +event GroupCreationFrequencyUpdateStarted(uint256 groupCreationFrequency, uint256 timestamp) +``` + +### GroupCreationFrequencyUpdated + +```solidity +event GroupCreationFrequencyUpdated(uint256 groupCreationFrequency) +``` + +### GroupLifetimeUpdateStarted + +```solidity +event GroupLifetimeUpdateStarted(uint256 groupLifetime, uint256 timestamp) +``` + +### GroupLifetimeUpdated + +```solidity +event GroupLifetimeUpdated(uint256 groupLifetime) +``` + +### DkgResultChallengePeriodLengthUpdateStarted + +```solidity +event DkgResultChallengePeriodLengthUpdateStarted(uint256 dkgResultChallengePeriodLength, uint256 timestamp) +``` + +### DkgResultChallengePeriodLengthUpdated + +```solidity +event DkgResultChallengePeriodLengthUpdated(uint256 dkgResultChallengePeriodLength) +``` + +### DkgResultChallengeExtraGasUpdateStarted + +```solidity +event DkgResultChallengeExtraGasUpdateStarted(uint256 dkgResultChallengeExtraGas, uint256 timestamp) +``` + +### DkgResultChallengeExtraGasUpdated + +```solidity +event DkgResultChallengeExtraGasUpdated(uint256 dkgResultChallengeExtraGas) +``` + +### DkgResultSubmissionTimeoutUpdateStarted + +```solidity +event DkgResultSubmissionTimeoutUpdateStarted(uint256 dkgResultSubmissionTimeout, uint256 timestamp) +``` + +### DkgResultSubmissionTimeoutUpdated + +```solidity +event DkgResultSubmissionTimeoutUpdated(uint256 dkgResultSubmissionTimeout) +``` + +### DkgSubmitterPrecedencePeriodLengthUpdateStarted + +```solidity +event DkgSubmitterPrecedencePeriodLengthUpdateStarted(uint256 submitterPrecedencePeriodLength, uint256 timestamp) +``` + +### DkgSubmitterPrecedencePeriodLengthUpdated + +```solidity +event DkgSubmitterPrecedencePeriodLengthUpdated(uint256 submitterPrecedencePeriodLength) +``` + +### RelayEntrySubmissionFailureSlashingAmountUpdateStarted + +```solidity +event RelayEntrySubmissionFailureSlashingAmountUpdateStarted(uint96 relayEntrySubmissionFailureSlashingAmount, uint256 timestamp) +``` + +### RelayEntrySubmissionFailureSlashingAmountUpdated + +```solidity +event RelayEntrySubmissionFailureSlashingAmountUpdated(uint96 relayEntrySubmissionFailureSlashingAmount) +``` + +### MaliciousDkgResultSlashingAmountUpdateStarted + +```solidity +event MaliciousDkgResultSlashingAmountUpdateStarted(uint96 maliciousDkgResultSlashingAmount, uint256 timestamp) +``` + +### MaliciousDkgResultSlashingAmountUpdated + +```solidity +event MaliciousDkgResultSlashingAmountUpdated(uint96 maliciousDkgResultSlashingAmount) +``` + +### UnauthorizedSigningSlashingAmountUpdateStarted + +```solidity +event UnauthorizedSigningSlashingAmountUpdateStarted(uint96 unauthorizedSigningSlashingAmount, uint256 timestamp) +``` + +### UnauthorizedSigningSlashingAmountUpdated + +```solidity +event UnauthorizedSigningSlashingAmountUpdated(uint96 unauthorizedSigningSlashingAmount) +``` + +### SortitionPoolRewardsBanDurationUpdateStarted + +```solidity +event SortitionPoolRewardsBanDurationUpdateStarted(uint256 sortitionPoolRewardsBanDuration, uint256 timestamp) +``` + +### SortitionPoolRewardsBanDurationUpdated + +```solidity +event SortitionPoolRewardsBanDurationUpdated(uint256 sortitionPoolRewardsBanDuration) +``` + +### RelayEntryTimeoutNotificationRewardMultiplierUpdateStarted + +```solidity +event RelayEntryTimeoutNotificationRewardMultiplierUpdateStarted(uint256 relayEntryTimeoutNotificationRewardMultiplier, uint256 timestamp) +``` + +### RelayEntryTimeoutNotificationRewardMultiplierUpdated + +```solidity +event RelayEntryTimeoutNotificationRewardMultiplierUpdated(uint256 relayEntryTimeoutNotificationRewardMultiplier) +``` + +### UnauthorizedSigningNotificationRewardMultiplierUpdateStarted + +```solidity +event UnauthorizedSigningNotificationRewardMultiplierUpdateStarted(uint256 unauthorizedSigningTimeoutNotificationRewardMultiplier, uint256 timestamp) +``` + +### UnauthorizedSigningNotificationRewardMultiplierUpdated + +```solidity +event UnauthorizedSigningNotificationRewardMultiplierUpdated(uint256 unauthorizedSigningTimeoutNotificationRewardMultiplier) +``` + +### MinimumAuthorizationUpdateStarted + +```solidity +event MinimumAuthorizationUpdateStarted(uint96 minimumAuthorization, uint256 timestamp) +``` + +### MinimumAuthorizationUpdated + +```solidity +event MinimumAuthorizationUpdated(uint96 minimumAuthorization) +``` + +### AuthorizationDecreaseDelayUpdateStarted + +```solidity +event AuthorizationDecreaseDelayUpdateStarted(uint64 authorizationDecreaseDelay, uint256 timestamp) +``` + +### AuthorizationDecreaseDelayUpdated + +```solidity +event AuthorizationDecreaseDelayUpdated(uint64 authorizationDecreaseDelay) +``` + +### AuthorizationDecreaseChangePeriodUpdateStarted + +```solidity +event AuthorizationDecreaseChangePeriodUpdateStarted(uint64 authorizationDecreaseChangePeriod, uint256 timestamp) +``` + +### AuthorizationDecreaseChangePeriodUpdated + +```solidity +event AuthorizationDecreaseChangePeriodUpdated(uint64 authorizationDecreaseChangePeriod) +``` + +### DkgMaliciousResultNotificationRewardMultiplierUpdateStarted + +```solidity +event DkgMaliciousResultNotificationRewardMultiplierUpdateStarted(uint256 dkgMaliciousResultNotificationRewardMultiplier, uint256 timestamp) +``` + +### DkgMaliciousResultNotificationRewardMultiplierUpdated + +```solidity +event DkgMaliciousResultNotificationRewardMultiplierUpdated(uint256 dkgMaliciousResultNotificationRewardMultiplier) +``` + +### DkgResultSubmissionGasUpdateStarted + +```solidity +event DkgResultSubmissionGasUpdateStarted(uint256 dkgResultSubmissionGas, uint256 timestamp) +``` + +### DkgResultSubmissionGasUpdated + +```solidity +event DkgResultSubmissionGasUpdated(uint256 dkgResultSubmissionGas) +``` + +### DkgResultApprovalGasOffsetUpdateStarted + +```solidity +event DkgResultApprovalGasOffsetUpdateStarted(uint256 dkgResultApprovalGasOffset, uint256 timestamp) +``` + +### DkgResultApprovalGasOffsetUpdated + +```solidity +event DkgResultApprovalGasOffsetUpdated(uint256 dkgResultApprovalGasOffset) +``` + +### NotifyOperatorInactivityGasOffsetUpdateStarted + +```solidity +event NotifyOperatorInactivityGasOffsetUpdateStarted(uint256 notifyOperatorInactivityGasOffset, uint256 timestamp) +``` + +### NotifyOperatorInactivityGasOffsetUpdated + +```solidity +event NotifyOperatorInactivityGasOffsetUpdated(uint256 notifyOperatorInactivityGasOffset) +``` + +### RelayEntrySubmissionGasOffsetUpdateStarted + +```solidity +event RelayEntrySubmissionGasOffsetUpdateStarted(uint256 relayEntrySubmissionGasOffset, uint256 timestamp) +``` + +### RelayEntrySubmissionGasOffsetUpdated + +```solidity +event RelayEntrySubmissionGasOffsetUpdated(uint256 relayEntrySubmissionGasOffset) +``` + +### onlyAfterGovernanceDelay + +```solidity +modifier onlyAfterGovernanceDelay(uint256 changeInitiatedTimestamp) +``` + +Reverts if called before the governance delay elapses. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| changeInitiatedTimestamp | uint256 | Timestamp indicating the beginning of the change. | + +### constructor + +```solidity +constructor(contract RandomBeacon _randomBeacon, uint256 _governanceDelay) public +``` + +### beginGovernanceDelayUpdate + +```solidity +function beginGovernanceDelayUpdate(uint256 _newGovernanceDelay) external +``` + +Begins the governance delay update process. + +Can be called only by the contract owner. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| _newGovernanceDelay | uint256 | New governance delay | + +### finalizeGovernanceDelayUpdate + +```solidity +function finalizeGovernanceDelayUpdate() external +``` + +Finalizes the governance delay update process. + +Can be called only by the contract owner, after the governance +delay elapses. + +### beginRandomBeaconGovernanceTransfer + +```solidity +function beginRandomBeaconGovernanceTransfer(address _newRandomBeaconGovernance) external +``` + +Begins the random beacon governance transfer process. + +Can be called only by the current contract governance. + +### finalizeRandomBeaconGovernanceTransfer + +```solidity +function finalizeRandomBeaconGovernanceTransfer() external +``` + +Finalizes the random beacon governance transfer process. + +Can be called only by the current contract governance, after the +governance delay elapses. + +### beginRelayEntrySoftTimeoutUpdate + +```solidity +function beginRelayEntrySoftTimeoutUpdate(uint256 _newRelayEntrySoftTimeout) external +``` + +Begins the relay entry soft timeout update process. + +Can be called only by the contract owner. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| _newRelayEntrySoftTimeout | uint256 | New relay entry submission timeout in blocks | + +### finalizeRelayEntrySoftTimeoutUpdate + +```solidity +function finalizeRelayEntrySoftTimeoutUpdate() external +``` + +Finalizes the relay entry soft timeout update process. + +Can be called only by the contract owner, after the governance +delay elapses. + +### beginRelayEntryHardTimeoutUpdate + +```solidity +function beginRelayEntryHardTimeoutUpdate(uint256 _newRelayEntryHardTimeout) external +``` + +Begins the relay entry hard timeout update process. + +Can be called only by the contract owner. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| _newRelayEntryHardTimeout | uint256 | New relay entry hard timeout in blocks | + +### finalizeRelayEntryHardTimeoutUpdate + +```solidity +function finalizeRelayEntryHardTimeoutUpdate() external +``` + +Finalizes the relay entry hard timeout update process. + +Can be called only by the contract owner, after the governance +delay elapses. + +### beginCallbackGasLimitUpdate + +```solidity +function beginCallbackGasLimitUpdate(uint256 _newCallbackGasLimit) external +``` + +Begins the callback gas limit update process. + +Can be called only by the contract owner. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| _newCallbackGasLimit | uint256 | New callback gas limit | + +### finalizeCallbackGasLimitUpdate + +```solidity +function finalizeCallbackGasLimitUpdate() external +``` + +Finalizes the callback gas limit update process. + +Can be called only by the contract owner, after the governance +delay elapses. + +### beginGroupCreationFrequencyUpdate + +```solidity +function beginGroupCreationFrequencyUpdate(uint256 _newGroupCreationFrequency) external +``` + +Begins the group creation frequency update process. + +Can be called only by the contract owner. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| _newGroupCreationFrequency | uint256 | New group creation frequency | + +### finalizeGroupCreationFrequencyUpdate + +```solidity +function finalizeGroupCreationFrequencyUpdate() external +``` + +Finalizes the group creation frequency update process. + +Can be called only by the contract owner, after the governance +delay elapses. + +### beginGroupLifetimeUpdate + +```solidity +function beginGroupLifetimeUpdate(uint256 _newGroupLifetime) external +``` + +Begins the group lifetime update process. Group lifetime needs to +be shorter than the authorization decrease delay to ensure every +active group is backed by enough stake. A new group lifetime value +is in blocks and has to be calculated based on the average block +time and authorization decrease delay which value is in seconds. + +Can be called only by the contract owner. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| _newGroupLifetime | uint256 | New group lifetime in blocks | + +### finalizeGroupLifetimeUpdate + +```solidity +function finalizeGroupLifetimeUpdate() external +``` + +Finalizes the group creation frequency update process. + +Can be called only by the contract owner, after the governance +delay elapses. + +### beginDkgResultChallengePeriodLengthUpdate + +```solidity +function beginDkgResultChallengePeriodLengthUpdate(uint256 _newDkgResultChallengePeriodLength) external +``` + +Begins the DKG result challenge period length update process. + +Can be called only by the contract owner. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| _newDkgResultChallengePeriodLength | uint256 | New DKG result challenge period length in blocks | + +### finalizeDkgResultChallengePeriodLengthUpdate + +```solidity +function finalizeDkgResultChallengePeriodLengthUpdate() external +``` + +Finalizes the DKG result challenge period length update process. + +Can be called only by the contract owner, after the governance +delay elapses. + +### beginDkgResultChallengeExtraGasUpdate + +```solidity +function beginDkgResultChallengeExtraGasUpdate(uint256 _newDkgResultChallengeExtraGas) external +``` + +Begins the DKG result challenge extra gas update process. + +Can be called only by the contract owner. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| _newDkgResultChallengeExtraGas | uint256 | New DKG result challenge extra gas | + +### finalizeDkgResultChallengeExtraGasUpdate + +```solidity +function finalizeDkgResultChallengeExtraGasUpdate() external +``` + +Finalizes the DKG result challenge extra gas update process. + +Can be called only by the contract owner, after the governance +delay elapses. + +### beginDkgResultSubmissionTimeoutUpdate + +```solidity +function beginDkgResultSubmissionTimeoutUpdate(uint256 _newDkgResultSubmissionTimeout) external +``` + +Begins the DKG result submission timeout update +process. + +Can be called only by the contract owner. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| _newDkgResultSubmissionTimeout | uint256 | New DKG result submission timeout in blocks | + +### finalizeDkgResultSubmissionTimeoutUpdate + +```solidity +function finalizeDkgResultSubmissionTimeoutUpdate() external +``` + +Finalizes the DKG result submission timeout update +process. + +Can be called only by the contract owner, after the governance +delay elapses. + +### beginDkgSubmitterPrecedencePeriodLengthUpdate + +```solidity +function beginDkgSubmitterPrecedencePeriodLengthUpdate(uint256 _newDkgSubmitterPrecedencePeriodLength) external +``` + +Begins the DKG submitter precedence period length. + +Can be called only by the contract owner. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| _newDkgSubmitterPrecedencePeriodLength | uint256 | New DKG submitter precedence period length in blocks | + +### finalizeDkgSubmitterPrecedencePeriodLengthUpdate + +```solidity +function finalizeDkgSubmitterPrecedencePeriodLengthUpdate() external +``` + +Finalizes the DKG submitter precedence period length. + +Can be called only by the contract owner, after the governance +delay elapses. + +### beginSortitionPoolRewardsBanDurationUpdate + +```solidity +function beginSortitionPoolRewardsBanDurationUpdate(uint256 _newSortitionPoolRewardsBanDuration) external +``` + +Begins the sortition pool rewards ban duration update process. + +Can be called only by the contract owner. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| _newSortitionPoolRewardsBanDuration | uint256 | New sortition pool rewards ban duration. | + +### finalizeSortitionPoolRewardsBanDurationUpdate + +```solidity +function finalizeSortitionPoolRewardsBanDurationUpdate() external +``` + +Finalizes the sortition pool rewards ban duration update process. + +Can be called only by the contract owner, after the governance +delay elapses. + +### beginRelayEntryTimeoutNotificationRewardMultiplierUpdate + +```solidity +function beginRelayEntryTimeoutNotificationRewardMultiplierUpdate(uint256 _newRelayEntryTimeoutNotificationRewardMultiplier) external +``` + +Begins the relay entry timeout notification reward multiplier +update process. + +Can be called only by the contract owner. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| _newRelayEntryTimeoutNotificationRewardMultiplier | uint256 | New relay entry timeout notification reward multiplier. | + +### beginUnauthorizedSigningNotificationRewardMultiplierUpdate + +```solidity +function beginUnauthorizedSigningNotificationRewardMultiplierUpdate(uint256 _newUnauthorizedSigningNotificationRewardMultiplier) external +``` + +Begins the unauthorized signing notification reward multiplier +update process. + +Can be called only by the contract owner. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| _newUnauthorizedSigningNotificationRewardMultiplier | uint256 | New unauthorized signing notification reward multiplier. | + +### finalizeUnauthorizedSigningNotificationRewardMultiplierUpdate + +```solidity +function finalizeUnauthorizedSigningNotificationRewardMultiplierUpdate() external +``` + +Finalizes the unauthorized signing notification reward +multiplier update process. + +Can be called only by the contract owner, after the governance +delay elapses. + +### finalizeRelayEntryTimeoutNotificationRewardMultiplierUpdate + +```solidity +function finalizeRelayEntryTimeoutNotificationRewardMultiplierUpdate() external +``` + +Finalizes the relay entry timeout notification reward +multiplier update process. + +Can be called only by the contract owner, after the governance +delay elapses. + +### beginDkgMaliciousResultNotificationRewardMultiplierUpdate + +```solidity +function beginDkgMaliciousResultNotificationRewardMultiplierUpdate(uint256 _newDkgMaliciousResultNotificationRewardMultiplier) external +``` + +Begins the DKG malicious result notification reward multiplier +update process. + +Can be called only by the contract owner. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| _newDkgMaliciousResultNotificationRewardMultiplier | uint256 | New DKG malicious result notification reward multiplier. | + +### finalizeDkgMaliciousResultNotificationRewardMultiplierUpdate + +```solidity +function finalizeDkgMaliciousResultNotificationRewardMultiplierUpdate() external +``` + +Finalizes the DKG malicious result notification reward +multiplier update process. + +Can be called only by the contract owner, after the governance +delay elapses. + +### beginRelayEntrySubmissionFailureSlashingAmountUpdate + +```solidity +function beginRelayEntrySubmissionFailureSlashingAmountUpdate(uint96 _newRelayEntrySubmissionFailureSlashingAmount) external +``` + +Begins the relay entry submission failure slashing amount update +process. + +Can be called only by the contract owner. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| _newRelayEntrySubmissionFailureSlashingAmount | uint96 | New relay entry submission failure slashing amount | + +### finalizeRelayEntrySubmissionFailureSlashingAmountUpdate + +```solidity +function finalizeRelayEntrySubmissionFailureSlashingAmountUpdate() external +``` + +Finalizes the relay entry submission failure slashing amount +update process. + +Can be called only by the contract owner, after the governance +delay elapses. + +### beginDkgResultSubmissionGasUpdate + +```solidity +function beginDkgResultSubmissionGasUpdate(uint256 _newDkgResultSubmissionGas) external +``` + +Begins the DKG result submission gas update process. + +Can be called only by the contract owner. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| _newDkgResultSubmissionGas | uint256 | New relay entry submission gas offset | + +### finalizeDkgResultSubmissionGasUpdate + +```solidity +function finalizeDkgResultSubmissionGasUpdate() external +``` + +Finalizes DKG result submission gas update process. + +Can be called only by the contract owner, after the governance +delay elapses. + +### beginDkgResultApprovalGasOffsetUpdate + +```solidity +function beginDkgResultApprovalGasOffsetUpdate(uint256 _newDkgResultApprovalGasOffset) external +``` + +Begins the DKG result approval gas offset update process. + +Can be called only by the contract owner. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| _newDkgResultApprovalGasOffset | uint256 | New DKG approval gas offset | + +### finalizeDkgResultApprovalGasOffsetUpdate + +```solidity +function finalizeDkgResultApprovalGasOffsetUpdate() external +``` + +Finalizes the DKG result approval gas offset update process. + +Can be called only by the contract owner, after the governance +delay elapses. + +### beginNotifyOperatorInactivityGasOffsetUpdate + +```solidity +function beginNotifyOperatorInactivityGasOffsetUpdate(uint256 _newNotifyOperatorInactivityGasOffset) external +``` + +Begins the notify operator inactivity gas offset update process. + +Can be called only by the contract owner. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| _newNotifyOperatorInactivityGasOffset | uint256 | New operator inactivity notification gas offset | + +### finalizeNotifyOperatorInactivityGasOffsetUpdate + +```solidity +function finalizeNotifyOperatorInactivityGasOffsetUpdate() external +``` + +Finalizes the notify operator inactivity gas offset update process. + +Can be called only by the contract owner, after the governance +delay elapses. + +### beginRelayEntrySubmissionGasOffsetUpdate + +```solidity +function beginRelayEntrySubmissionGasOffsetUpdate(uint256 _newRelayEntrySubmissionGasOffset) external +``` + +Begins the relay entry submission gas offset update process. + +Can be called only by the contract owner. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| _newRelayEntrySubmissionGasOffset | uint256 | New relay entry submission gas offset | + +### finalizeRelayEntrySubmissionGasOffsetUpdate + +```solidity +function finalizeRelayEntrySubmissionGasOffsetUpdate() external +``` + +Finalizes relay entry submission gas offset update process. + +Can be called only by the contract owner, after the governance +delay elapses. + +### beginMaliciousDkgResultSlashingAmountUpdate + +```solidity +function beginMaliciousDkgResultSlashingAmountUpdate(uint96 _newMaliciousDkgResultSlashingAmount) external +``` + +Begins the malicious DKG result slashing amount update process. + +Can be called only by the contract owner. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| _newMaliciousDkgResultSlashingAmount | uint96 | New malicious DKG result slashing amount | + +### finalizeMaliciousDkgResultSlashingAmountUpdate + +```solidity +function finalizeMaliciousDkgResultSlashingAmountUpdate() external +``` + +Finalizes the malicious DKG result slashing amount update +process. + +Can be called only by the contract owner, after the governance +delay elapses. + +### beginUnauthorizedSigningSlashingAmountUpdate + +```solidity +function beginUnauthorizedSigningSlashingAmountUpdate(uint96 _newUnauthorizedSigningSlashingAmount) external +``` + +Begins the unauthorized signing slashing amount update process. + +Can be called only by the contract owner. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| _newUnauthorizedSigningSlashingAmount | uint96 | New unauthorized signing slashing amount | + +### finalizeUnauthorizedSigningSlashingAmountUpdate + +```solidity +function finalizeUnauthorizedSigningSlashingAmountUpdate() external +``` + +Finalizes the unauthorized signing slashing amount update +process. + +Can be called only by the contract owner, after the governance +delay elapses. + +### beginMinimumAuthorizationUpdate + +```solidity +function beginMinimumAuthorizationUpdate(uint96 _newMinimumAuthorization) external +``` + +Begins the minimum authorization amount update process. + +Can be called only by the contract owner. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| _newMinimumAuthorization | uint96 | New minimum authorization amount. | + +### finalizeMinimumAuthorizationUpdate + +```solidity +function finalizeMinimumAuthorizationUpdate() external +``` + +Finalizes the minimum authorization amount update process. + +Can be called only by the contract owner, after the governance +delay elapses. + +### beginAuthorizationDecreaseDelayUpdate + +```solidity +function beginAuthorizationDecreaseDelayUpdate(uint64 _newAuthorizationDecreaseDelay) external +``` + +Begins the authorization decrease delay update process. + +Can be called only by the contract owner. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| _newAuthorizationDecreaseDelay | uint64 | New authorization decrease delay | + +### finalizeAuthorizationDecreaseDelayUpdate + +```solidity +function finalizeAuthorizationDecreaseDelayUpdate() external +``` + +Finalizes the authorization decrease delay update process. + +Can be called only by the contract owner, after the governance +delay elapses. + +### beginAuthorizationDecreaseChangePeriodUpdate + +```solidity +function beginAuthorizationDecreaseChangePeriodUpdate(uint64 _newAuthorizationDecreaseChangePeriod) external +``` + +Begins the authorization decrease change period update process. + +Can be called only by the contract owner. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| _newAuthorizationDecreaseChangePeriod | uint64 | New authorization decrease change period | + +### finalizeAuthorizationDecreaseChangePeriodUpdate + +```solidity +function finalizeAuthorizationDecreaseChangePeriodUpdate() external +``` + +Finalizes the authorization decrease change period update process. + +Can be called only by the contract owner, after the governance +delay elapses. + +### setRequesterAuthorization + +```solidity +function setRequesterAuthorization(address requester, bool isAuthorized) external +``` + +Set authorization for requesters that can request a relay +entry. It can be done by the governance only. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| requester | address | Requester, can be a contract or EOA | +| isAuthorized | bool | True or false | + +### 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 owner. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| recipient | address | Recipient of withdrawn rewards. | + +### getRemainingGovernanceDelayUpdateTime + +```solidity +function getRemainingGovernanceDelayUpdateTime() external view returns (uint256) +``` + +Get the time remaining until the governance delay can be updated. + +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +| [0] | uint256 | Remaining time in seconds. | + +### getRemainingRandomBeaconGovernanceTransferDelayTime + +```solidity +function getRemainingRandomBeaconGovernanceTransferDelayTime() external view returns (uint256) +``` + +Get the time remaining until the random beacon governance can +be transferred. + +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +| [0] | uint256 | Remaining time in seconds. | + +### getRemainingRelayEntrySoftTimeoutUpdateTime + +```solidity +function getRemainingRelayEntrySoftTimeoutUpdateTime() external view returns (uint256) +``` + +Get the time remaining until the relay entry submission soft +timeout can be updated. + +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +| [0] | uint256 | Remaining time in seconds. | + +### getRemainingRelayEntryHardTimeoutUpdateTime + +```solidity +function getRemainingRelayEntryHardTimeoutUpdateTime() external view returns (uint256) +``` + +Get the time remaining until the relay entry hard timeout can be +updated. + +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +| [0] | uint256 | Remaining time in seconds. | + +### getRemainingCallbackGasLimitUpdateTime + +```solidity +function getRemainingCallbackGasLimitUpdateTime() external view returns (uint256) +``` + +Get the time remaining until the callback gas limit can be +updated. + +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +| [0] | uint256 | Remaining time in seconds. | + +### getRemainingGroupCreationFrequencyUpdateTime + +```solidity +function getRemainingGroupCreationFrequencyUpdateTime() external view returns (uint256) +``` + +Get the time remaining until the group creation frequency can be +updated. + +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +| [0] | uint256 | Remaining time in seconds. | + +### getRemainingGroupLifetimeUpdateTime + +```solidity +function getRemainingGroupLifetimeUpdateTime() external view returns (uint256) +``` + +Get the time remaining until the group lifetime can be updated. + +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +| [0] | uint256 | Remaining time in seconds. | + +### getRemainingDkgResultChallengePeriodLengthUpdateTime + +```solidity +function getRemainingDkgResultChallengePeriodLengthUpdateTime() external view returns (uint256) +``` + +Get the time remaining until the DKG result challenge period +length can be updated. + +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +| [0] | uint256 | Remaining time in seconds. | + +### getRemainingDkgResultChallengeExtraGasUpdateTime + +```solidity +function getRemainingDkgResultChallengeExtraGasUpdateTime() external view returns (uint256) +``` + +Get the time remaining until the DKG result challenge extra +gas can be updated. + +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +| [0] | uint256 | Remaining time in seconds. | + +### getRemainingDkgResultSubmissionTimeoutUpdateTime + +```solidity +function getRemainingDkgResultSubmissionTimeoutUpdateTime() external view returns (uint256) +``` + +Get the time remaining until the DKG result submission timeout +can be updated. + +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +| [0] | uint256 | Remaining time in seconds. | + +### getRemainingDkgSubmitterPrecedencePeriodLengthUpdateTime + +```solidity +function getRemainingDkgSubmitterPrecedencePeriodLengthUpdateTime() external view returns (uint256) +``` + +Get the time remaining until the wallet owner can be updated. + +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +| [0] | uint256 | Remaining time in seconds. | + +### getRemainingRelayEntrySubmissionFailureSlashingAmountUpdateTime + +```solidity +function getRemainingRelayEntrySubmissionFailureSlashingAmountUpdateTime() external view returns (uint256) +``` + +Get the time remaining until the relay entry submission failure +slashing amount can be updated. + +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +| [0] | uint256 | Remaining time in seconds. | + +### getRemainingMaliciousDkgResultSlashingAmountUpdateTime + +```solidity +function getRemainingMaliciousDkgResultSlashingAmountUpdateTime() external view returns (uint256) +``` + +Get the time remaining until the malicious DKG result +slashing amount can be updated. + +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +| [0] | uint256 | Remaining time in seconds. | + +### getRemainingUnauthorizedSigningSlashingAmountUpdateTime + +```solidity +function getRemainingUnauthorizedSigningSlashingAmountUpdateTime() external view returns (uint256) +``` + +Get the time remaining until the unauthorized signing +slashing amount can be updated. + +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +| [0] | uint256 | Remaining time in seconds. | + +### getRemainingMimimumAuthorizationUpdateTime + +```solidity +function getRemainingMimimumAuthorizationUpdateTime() external view returns (uint256) +``` + +Get the time remaining until the minimum authorization amount +can be updated. + +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +| [0] | uint256 | Remaining time in seconds. | + +### getRemainingAuthorizationDecreaseDelayUpdateTime + +```solidity +function getRemainingAuthorizationDecreaseDelayUpdateTime() external view returns (uint256) +``` + +Get the time remaining until the authorization decrease delay +can be updated. + +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +| [0] | uint256 | Remaining time in seconds. | + +### getRemainingAuthorizationDecreaseChangePeriodUpdateTime + +```solidity +function getRemainingAuthorizationDecreaseChangePeriodUpdateTime() external view returns (uint256) +``` + +Get the time remaining until the authorization decrease change +period can be updated. + +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +| [0] | uint256 | Remaining time in seconds. | + +### getRemainingSortitionPoolRewardsBanDurationUpdateTime + +```solidity +function getRemainingSortitionPoolRewardsBanDurationUpdateTime() external view returns (uint256) +``` + +Get the time remaining until the sortition pool rewards ban +duration can be updated. + +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +| [0] | uint256 | Remaining time in seconds. | + +### getRemainingRelayEntryTimeoutNotificationRewardMultiplierUpdateTime + +```solidity +function getRemainingRelayEntryTimeoutNotificationRewardMultiplierUpdateTime() external view returns (uint256) +``` + +Get the time remaining until the relay entry timeout +notification reward multiplier duration can be updated. + +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +| [0] | uint256 | Remaining time in seconds. | + +### getRemainingUnauthorizedSigningNotificationRewardMultiplierUpdateTime + +```solidity +function getRemainingUnauthorizedSigningNotificationRewardMultiplierUpdateTime() external view returns (uint256) +``` + +Get the time remaining until the unauthorized signing +notification reward multiplier duration can be updated. + +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +| [0] | uint256 | Remaining time in seconds. | + +### getRemainingDkgMaliciousResultNotificationRewardMultiplierUpdateTime + +```solidity +function getRemainingDkgMaliciousResultNotificationRewardMultiplierUpdateTime() external view returns (uint256) +``` + +Get the time remaining until the DKG malicious result +notification reward multiplier duration can be updated. + +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +| [0] | uint256 | Remaining time in seconds. | + +### getRemainingDkgResultSubmissionGasUpdateTime + +```solidity +function getRemainingDkgResultSubmissionGasUpdateTime() external view returns (uint256) +``` + +Get the time remaining until the DKG result submission gas +duration can be updated. + +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +| [0] | uint256 | Remaining time in seconds. | + +### getRemainingDkgResultApprovalGasOffsetUpdateTime + +```solidity +function getRemainingDkgResultApprovalGasOffsetUpdateTime() external view returns (uint256) +``` + +Get the time remaining until the DKG approval gas offset duration +can be updated. + +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +| [0] | uint256 | Remaining time in seconds. | + +### getRemainingNotifyOperatorInactivityGasOffsetUpdateTime + +```solidity +function getRemainingNotifyOperatorInactivityGasOffsetUpdateTime() external view returns (uint256) +``` + +Get the time remaining until the operator inactivity notification +gas offset duration can be updated. + +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +| [0] | uint256 | Remaining time in seconds. | + +### getRemainingRelayEntrySubmissionGasOffsetUpdateTime + +```solidity +function getRemainingRelayEntrySubmissionGasOffsetUpdateTime() external view returns (uint256) +``` + +Get the time remaining until the relay entry submission gas offset +duration can be updated. + +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +| [0] | uint256 | Remaining time in seconds. | + +### getRemainingChangeTime + +```solidity +function getRemainingChangeTime(uint256 changeTimestamp) internal view returns (uint256) +``` + +Gets the time remaining until the governable parameter update +can be committed. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| changeTimestamp | uint256 | Timestamp indicating the beginning of the change. | + +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +| [0] | uint256 | Remaining time in seconds. | + diff --git a/docs/app-development/random-beacon/random-beacon-api/generated-docs/Reimbursable.md b/docs/app-development/random-beacon/random-beacon-api/generated-docs/Reimbursable.md new file mode 100644 index 0000000..bd4e06b --- /dev/null +++ b/docs/app-development/random-beacon/random-beacon-api/generated-docs/Reimbursable.md @@ -0,0 +1,34 @@ +# Solidity API + +## Reimbursable + +### reimbursementPool + +```solidity +contract ReimbursementPool reimbursementPool +``` + +### ReimbursementPoolUpdated + +```solidity +event ReimbursementPoolUpdated(address newReimbursementPool) +``` + +### refundable + +```solidity +modifier refundable(address receiver) +``` + +### onlyReimbursableAdmin + +```solidity +modifier onlyReimbursableAdmin() +``` + +### updateReimbursementPool + +```solidity +function updateReimbursementPool(contract ReimbursementPool _reimbursementPool) external +``` + diff --git a/docs/app-development/random-beacon/random-beacon-api/generated-docs/ReimbursementPool.md b/docs/app-development/random-beacon/random-beacon-api/generated-docs/ReimbursementPool.md new file mode 100644 index 0000000..c933efd --- /dev/null +++ b/docs/app-development/random-beacon/random-beacon-api/generated-docs/ReimbursementPool.md @@ -0,0 +1,197 @@ +# Solidity API + +## ReimbursementPool + +### isAuthorized + +```solidity +mapping(address => bool) isAuthorized +``` + +Authorized contracts that can interact with the reimbursment pool. +Authorization can be granted and removed by the owner. + +### staticGas + +```solidity +uint256 staticGas +``` + +Static gas includes: +- cost of the refund function +- base transaction cost + +### maxGasPrice + +```solidity +uint256 maxGasPrice +``` + +Max gas price used to reimburse a transaction submitter. Protects +against malicious operator-miners. + +### StaticGasUpdated + +```solidity +event StaticGasUpdated(uint256 newStaticGas) +``` + +### MaxGasPriceUpdated + +```solidity +event MaxGasPriceUpdated(uint256 newMaxGasPrice) +``` + +### SendingEtherFailed + +```solidity +event SendingEtherFailed(uint256 refundAmount, address receiver) +``` + +### AuthorizedContract + +```solidity +event AuthorizedContract(address thirdPartyContract) +``` + +### UnauthorizedContract + +```solidity +event UnauthorizedContract(address thirdPartyContract) +``` + +### FundsWithdrawn + +```solidity +event FundsWithdrawn(uint256 withdrawnAmount, address receiver) +``` + +### constructor + +```solidity +constructor(uint256 _staticGas, uint256 _maxGasPrice) public +``` + +### receive + +```solidity +receive() external payable +``` + +Receive ETH + +### refund + +```solidity +function refund(uint256 gasSpent, address receiver) external +``` + +Refunds ETH to a spender for executing specific transactions. + +Ignoring the result of sending ETH to a receiver is made on purpose. +For EOA receiving ETH should always work. If a receiver is a smart +contract, then we do not want to fail a transaction, because in some +cases the refund is done at the very end of multiple calls where all +the previous calls were already paid off. It is a receiver's smart +contract resposibility to make sure it can receive ETH. +Only authorized contracts are allowed calling this function. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| gasSpent | uint256 | Gas spent on a transaction that needs to be reimbursed. | +| receiver | address | Address where the reimbursment is sent. | + +### authorize + +```solidity +function authorize(address _contract) external +``` + +Authorize a contract that can interact with this reimbursment pool. +Can be authorized by the owner only. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| _contract | address | Authorized contract. | + +### unauthorize + +```solidity +function unauthorize(address _contract) external +``` + +Unauthorize a contract that was previously authorized to interact +with this reimbursment pool. Can be unauthorized by the +owner only. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| _contract | address | Authorized contract. | + +### setStaticGas + +```solidity +function setStaticGas(uint256 _staticGas) external +``` + +Setting a static gas cost for executing a transaction. Can be set +by the owner only. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| _staticGas | uint256 | Static gas cost. | + +### setMaxGasPrice + +```solidity +function setMaxGasPrice(uint256 _maxGasPrice) external +``` + +Setting a max gas price for transactions. Can be set by the +owner only. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| _maxGasPrice | uint256 | Max gas price used to reimburse tx submitters. | + +### withdrawAll + +```solidity +function withdrawAll(address receiver) external +``` + +Withdraws all ETH from this pool which are sent to a given +address. Can be set by the owner only. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| receiver | address | An address where ETH is sent. | + +### withdraw + +```solidity +function withdraw(uint256 amount, address receiver) public +``` + +Withdraws ETH amount from this pool which are sent to a given +address. Can be set by the owner only. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| amount | uint256 | Amount to withdraw from the pool. | +| receiver | address | An address where ETH is sent. | + diff --git a/docs/app-development/random-beacon/random-beacon-api/generated-docs/api/IRandomBeacon.md b/docs/app-development/random-beacon/random-beacon-api/generated-docs/api/IRandomBeacon.md new file mode 100644 index 0000000..92e9db6 --- /dev/null +++ b/docs/app-development/random-beacon/random-beacon-api/generated-docs/api/IRandomBeacon.md @@ -0,0 +1,19 @@ +# Solidity API + +## IRandomBeacon + +### requestRelayEntry + +```solidity +function requestRelayEntry(contract IRandomBeaconConsumer callbackContract) external +``` + +Creates a request to generate a new relay entry. Requires a +request fee denominated in T token. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| callbackContract | contract IRandomBeaconConsumer | Beacon consumer callback contract. | + diff --git a/docs/app-development/random-beacon/random-beacon-api/generated-docs/api/IRandomBeaconConsumer.md b/docs/app-development/random-beacon/random-beacon-api/generated-docs/api/IRandomBeaconConsumer.md new file mode 100644 index 0000000..0402323 --- /dev/null +++ b/docs/app-development/random-beacon/random-beacon-api/generated-docs/api/IRandomBeaconConsumer.md @@ -0,0 +1,20 @@ +# Solidity API + +## IRandomBeaconConsumer + +### __beaconCallback + +```solidity +function __beaconCallback(uint256 relayEntry, uint256 blockNumber) external +``` + +Receives relay entry produced by Keep Random Beacon. This function +should be called only by Keep Random Beacon. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| relayEntry | uint256 | Relay entry (random number) produced by Keep Random Beacon. | +| blockNumber | uint256 | Block number at which the relay entry was submitted to the chain. | + diff --git a/docs/app-development/random-beacon/random-beacon-api/generated-docs/index.md b/docs/app-development/random-beacon/random-beacon-api/generated-docs/index.md deleted file mode 100644 index 58c7069..0000000 --- a/docs/app-development/random-beacon/random-beacon-api/generated-docs/index.md +++ /dev/null @@ -1,5119 +0,0 @@ -# Solidity API -## Table Of Contents - - - -- [BeaconDkgValidator](#beacondkgvalidator) -- [Governable](#governable) -- [RandomBeacon](#randombeacon) -- [RandomBeaconChaosnet](#randombeaconchaosnet) -- [RandomBeaconGovernance](#randombeacongovernance) -- [Reimbursable](#reimbursable) -- [ReimbursementPool](#reimbursementpool) -- [IRandomBeacon](#irandombeacon) -- [IRandomBeaconConsumer](#irandombeaconconsumer) -- [AltBn128](#altbn128) -- [BLS](#bls) -- [BeaconAuthorization](#beaconauthorization) -- [BeaconDkg](#beacondkg) -- [BeaconInactivity](#beaconinactivity) -- [BytesLib](#byteslib) -- [Callback](#callback) -- [Groups](#groups) -- [ModUtils](#modutils) -- [Relay](#relay) - - - -## BeaconDkgValidator - -DKGValidator 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 the threshold relay. - -### groupThreshold - -```solidity -uint256 groupThreshold -``` - -The minimum number of group members needed to interact according to -the protocol to produce a relay entry. 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 a relay -entry. - -### 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 BeaconDkg.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 BeaconDkg.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 BeaconDkg.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 BeaconDkg.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 BeaconDkg.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 BeaconDkg.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 BeaconDkg.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 BeaconDkg.Result result) public pure returns (bool) -``` - -Performs validation of hashed group members that actively took -part in DKG. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| result | struct BeaconDkg.Result | DKG result | - -#### Return Values - -| Name | Type | Description | -| ---- | ---- | ----------- | -| [0] | bool | true if result's group members hash matches with the one that is challenged. | - -## Governable - -Governable contract. - -A constructor is not defined, which makes the contract compatible with -upgradable proxies. This requires calling explicitly `_transferGovernance` -function in a child contract. - -### governance - -```solidity -address governance -``` - -### GovernanceTransferred - -```solidity -event GovernanceTransferred(address oldGovernance, address newGovernance) -``` - -### onlyGovernance - -```solidity -modifier onlyGovernance() -``` - -### transferGovernance - -```solidity -function transferGovernance(address newGovernance) external virtual -``` - -Transfers governance of the contract to `newGovernance`. - -### _transferGovernance - -```solidity -function _transferGovernance(address newGovernance) internal virtual -``` - -## RandomBeacon - -Keep Random Beacon contract. It lets to request a new -relay entry and validates the new relay entry provided by the -network. This contract is in charge of all other Random Beacon -activities such as group lifecycle or slashing. - -Should be owned by the governance contract controlling Random Beacon -parameters. - -### genesisSeed - -```solidity -uint256 genesisSeed -``` - -Seed value used for the genesis group selection. -https://www.wolframalpha.com/input/?i=pi+to+78+digits - -### _callbackGasLimit - -```solidity -uint256 _callbackGasLimit -``` - -Relay entry callback gas limit. This is the gas limit with which -callback function provided in the relay request transaction is -executed. The callback is executed with a new relay entry value -in the same transaction the relay entry is submitted. - -### _groupCreationFrequency - -```solidity -uint256 _groupCreationFrequency -``` - -The frequency of new group creation. Groups are created with -a fixed frequency of relay requests. - -### _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`. - -### _unauthorizedSigningSlashingAmount - -```solidity -uint96 _unauthorizedSigningSlashingAmount -``` - -Slashing amount when an unauthorized signing has been proved, -which means the private key leaked and all the group members -should be punished. - -### _sortitionPoolRewardsBanDuration - -```solidity -uint256 _sortitionPoolRewardsBanDuration -``` - -Duration of the sortition pool rewards ban imposed on operators -who misbehaved during DKG by being inactive or disqualified and -for operators that were identified by the rest of group members -as inactive via `notifyOperatorInactivity`. - -### _relayEntryTimeoutNotificationRewardMultiplier - -```solidity -uint256 _relayEntryTimeoutNotificationRewardMultiplier -``` - -Percentage of the staking contract malicious behavior -notification reward which will be transferred to the notifier -reporting about relay entry timeout. 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. - -### _unauthorizedSigningNotificationRewardMultiplier - -```solidity -uint256 _unauthorizedSigningNotificationRewardMultiplier -``` - -Percentage of the staking contract malicious behavior -notification reward which will be transferred to the notifier -reporting about unauthorized signing. Notifiers are rewarded -from a notifiers treasury pool. For example, if a -notification reward is 1000 and the value of the multiplier is -5, the notifier will receive: 5% of 1000 = 50 per each -operator affected. - -### _dkgMaliciousResultNotificationRewardMultiplier - -```solidity -uint256 _dkgMaliciousResultNotificationRewardMultiplier -``` - -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. - -### _dkgResultSubmissionGas - -```solidity -uint256 _dkgResultSubmissionGas -``` - -Calculated 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. Can be updated by the governance based on the current -market conditions. - -### _notifyOperatorInactivityGasOffset - -```solidity -uint256 _notifyOperatorInactivityGasOffset -``` - -Gas that is meant to balance the operator inactivity notification -cost. Can be updated by the governance based on the current -market conditions. - -### _relayEntrySubmissionGasOffset - -```solidity -uint256 _relayEntrySubmissionGasOffset -``` - -Gas that is meant to balance the relay entry submission cost. -Can be updated by the governance based on the current market -conditions. - -### inactivityClaimNonce - -```solidity -mapping(uint64 => uint256) inactivityClaimNonce -``` - -Stores current operator inactivity claim nonce for given group. -Each claim is made with an unique nonce which protects -against claim replay. - -### authorizedRequesters - -```solidity -mapping(address => bool) authorizedRequesters -``` - -Authorized addresses that can request a relay entry. - -### sortitionPool - -```solidity -contract SortitionPool sortitionPool -``` - -### tToken - -```solidity -contract IERC20 tToken -``` - -### staking - -```solidity -contract IStaking staking -``` - -### authorization - -```solidity -struct BeaconAuthorization.Data authorization -``` - -### dkg - -```solidity -struct BeaconDkg.Data dkg -``` - -### groups - -```solidity -struct Groups.Data groups -``` - -### relay - -```solidity -struct Relay.Data relay -``` - -### callback - -```solidity -struct Callback.Data callback -``` - -### AuthorizationParametersUpdated - -```solidity -event AuthorizationParametersUpdated(uint96 minimumAuthorization, uint64 authorizationDecreaseDelay, uint64 authorizationDecreaseChangePeriod) -``` - -### RelayEntryParametersUpdated - -```solidity -event RelayEntryParametersUpdated(uint256 relayEntrySoftTimeout, uint256 relayEntryHardTimeout, uint256 callbackGasLimit) -``` - -### GroupCreationParametersUpdated - -```solidity -event GroupCreationParametersUpdated(uint256 groupCreationFrequency, uint256 groupLifetime, uint256 dkgResultChallengePeriodLength, uint256 dkgResultChallengeExtraGas, uint256 dkgResultSubmissionTimeout, uint256 dkgResultSubmitterPrecedencePeriodLength) -``` - -### RewardParametersUpdated - -```solidity -event RewardParametersUpdated(uint256 sortitionPoolRewardsBanDuration, uint256 relayEntryTimeoutNotificationRewardMultiplier, uint256 unauthorizedSigningNotificationRewardMultiplier, uint256 dkgMaliciousResultNotificationRewardMultiplier) -``` - -### SlashingParametersUpdated - -```solidity -event SlashingParametersUpdated(uint256 relayEntrySubmissionFailureSlashingAmount, uint256 maliciousDkgResultSlashingAmount, uint256 unauthorizedSigningSlashingAmount) -``` - -### GasParametersUpdated - -```solidity -event GasParametersUpdated(uint256 dkgResultSubmissionGas, uint256 dkgResultApprovalGasOffset, uint256 notifyOperatorInactivityGasOffset, uint256 relayEntrySubmissionGasOffset) -``` - -### RequesterAuthorizationUpdated - -```solidity -event RequesterAuthorizationUpdated(address requester, bool isAuthorized) -``` - -### DkgStarted - -```solidity -event DkgStarted(uint256 seed) -``` - -### DkgResultSubmitted - -```solidity -event DkgResultSubmitted(bytes32 resultHash, uint256 seed, struct BeaconDkg.Result result) -``` - -### DkgTimedOut - -```solidity -event DkgTimedOut() -``` - -### DkgResultApproved - -```solidity -event DkgResultApproved(bytes32 resultHash, address approver) -``` - -### DkgResultChallenged - -```solidity -event DkgResultChallenged(bytes32 resultHash, address challenger, string reason) -``` - -### DkgMaliciousResultSlashed - -```solidity -event DkgMaliciousResultSlashed(bytes32 resultHash, uint256 slashingAmount, address maliciousSubmitter) -``` - -### DkgMaliciousResultSlashingFailed - -```solidity -event DkgMaliciousResultSlashingFailed(bytes32 resultHash, uint256 slashingAmount, address maliciousSubmitter) -``` - -### DkgStateLocked - -```solidity -event DkgStateLocked() -``` - -### DkgSeedTimedOut - -```solidity -event DkgSeedTimedOut() -``` - -### GroupRegistered - -```solidity -event GroupRegistered(uint64 groupId, bytes groupPubKey) -``` - -### RelayEntryRequested - -```solidity -event RelayEntryRequested(uint256 requestId, uint64 groupId, bytes previousEntry) -``` - -### RelayEntrySubmitted - -```solidity -event RelayEntrySubmitted(uint256 requestId, address submitter, bytes entry) -``` - -### RelayEntryTimedOut - -```solidity -event RelayEntryTimedOut(uint256 requestId, uint64 terminatedGroupId) -``` - -### RelayEntryDelaySlashed - -```solidity -event RelayEntryDelaySlashed(uint256 requestId, uint256 slashingAmount, address[] groupMembers) -``` - -### RelayEntryDelaySlashingFailed - -```solidity -event RelayEntryDelaySlashingFailed(uint256 requestId, uint256 slashingAmount, address[] groupMembers) -``` - -### RelayEntryTimeoutSlashed - -```solidity -event RelayEntryTimeoutSlashed(uint256 requestId, uint256 slashingAmount, address[] groupMembers) -``` - -### RelayEntryTimeoutSlashingFailed - -```solidity -event RelayEntryTimeoutSlashingFailed(uint256 requestId, uint256 slashingAmount, address[] groupMembers) -``` - -### UnauthorizedSigningSlashed - -```solidity -event UnauthorizedSigningSlashed(uint64 groupId, uint256 unauthorizedSigningSlashingAmount, address[] groupMembers) -``` - -### UnauthorizedSigningSlashingFailed - -```solidity -event UnauthorizedSigningSlashingFailed(uint64 groupId, uint256 unauthorizedSigningSlashingAmount, address[] groupMembers) -``` - -### CallbackFailed - -```solidity -event CallbackFailed(uint256 entry, uint256 entrySubmittedBlock) -``` - -### InactivityClaimed - -```solidity -event InactivityClaimed(uint64 groupId, uint256 nonce, address notifier) -``` - -### 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) -``` - -### constructor - -```solidity -constructor(contract SortitionPool _sortitionPool, contract IERC20 _tToken, contract IStaking _staking, contract BeaconDkgValidator _dkgValidator, contract ReimbursementPool _reimbursementPool) public -``` - -Assigns initial values to parameters to make the beacon work -safely. These parameters are just proposed defaults and they might -be updated with `update*` functions after the contract deployment -and before transferring the ownership to the governance contract. - -### onlyStakingContract - -```solidity -modifier onlyStakingContract() -``` - -### onlyReimbursableAdmin - -```solidity -modifier onlyReimbursableAdmin() -``` - -### 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 -random beacon 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 | - -### updateRelayEntryParameters - -```solidity -function updateRelayEntryParameters(uint256 relayEntrySoftTimeout, uint256 relayEntryHardTimeout, uint256 callbackGasLimit) external -``` - -Updates the values of relay entry parameters. - -Can be called only by the contract guvnor, which should be the -random beacon governance contract. The caller is responsible for -validating parameters. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| relayEntrySoftTimeout | uint256 | New relay entry submission soft timeout | -| relayEntryHardTimeout | uint256 | New relay entry hard timeout | -| callbackGasLimit | uint256 | New callback gas limit | - -### updateGroupCreationParameters - -```solidity -function updateGroupCreationParameters(uint256 groupCreationFrequency, uint256 groupLifetime, uint256 dkgResultChallengePeriodLength, uint256 dkgResultChallengeExtraGas, uint256 dkgResultSubmissionTimeout, uint256 dkgSubmitterPrecedencePeriodLength) external -``` - -Updates the values of group creation parameters. - -Can be called only by the contract guvnor, which should be the -random beacon governance contract. The caller is responsible for -validating parameters. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| groupCreationFrequency | uint256 | New group creation frequency | -| groupLifetime | uint256 | New group lifetime in blocks | -| dkgResultChallengePeriodLength | uint256 | New DKG result challenge period length | -| dkgResultChallengeExtraGas | uint256 | New DKG result challenge extra gas | -| dkgResultSubmissionTimeout | uint256 | New DKG result submission timeout | -| dkgSubmitterPrecedencePeriodLength | uint256 | New DKG result submitter precedence period length | - -### updateRewardParameters - -```solidity -function updateRewardParameters(uint256 sortitionPoolRewardsBanDuration, uint256 relayEntryTimeoutNotificationRewardMultiplier, uint256 unauthorizedSigningNotificationRewardMultiplier, uint256 dkgMaliciousResultNotificationRewardMultiplier) external -``` - -Updates the values of reward parameters. - -Can be called only by the contract guvnor, which should be the -random beacon governance contract. The caller is responsible for -validating parameters. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| sortitionPoolRewardsBanDuration | uint256 | New sortition pool rewards ban duration in seconds. | -| relayEntryTimeoutNotificationRewardMultiplier | uint256 | New value of the relay entry timeout notification reward multiplier | -| unauthorizedSigningNotificationRewardMultiplier | uint256 | New value of the unauthorized signing notification reward multiplier | -| dkgMaliciousResultNotificationRewardMultiplier | uint256 | New value of the DKG malicious result notification reward multiplier | - -### updateSlashingParameters - -```solidity -function updateSlashingParameters(uint96 relayEntrySubmissionFailureSlashingAmount, uint96 maliciousDkgResultSlashingAmount, uint96 unauthorizedSigningSlashingAmount) external -``` - -Updates the values of slashing parameters. - -Can be called only by the contract guvnor, which should be the -random beacon governance contract. The caller is responsible for -validating parameters. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| relayEntrySubmissionFailureSlashingAmount | uint96 | New relay entry submission failure amount | -| maliciousDkgResultSlashingAmount | uint96 | New malicious DKG result slashing amount | -| unauthorizedSigningSlashingAmount | uint96 | New unauthorized signing slashing amount | - -### updateGasParameters - -```solidity -function updateGasParameters(uint256 dkgResultSubmissionGas, uint256 dkgResultApprovalGasOffset, uint256 notifyOperatorInactivityGasOffset, uint256 relayEntrySubmissionGasOffset) external -``` - -Updates the values of gas parameters. - -Can be called only by the contract guvnor, which should be the -random beacon 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 | -| relayEntrySubmissionGasOffset | uint256 | New relay entry submission gas offset | - -### setRequesterAuthorization - -```solidity -function setRequesterAuthorization(address requester, bool isAuthorized) external -``` - -Set authorization for requesters that can request a relay -entry. - -Can be called only by the contract guvnor, which should be the -random beacon governance contract. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| requester | address | Requester, can be a contract or EOA | -| isAuthorized | bool | True or false | - -### 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 -random beacon 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 a 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 the beacon. 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 beacon 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 beacon 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. - -Reverts if another authorization decrease request is pending for -the staking provider and not enough time passed since the -original request (see `authorizationDecreaseChangePeriod`). - -If the operator is not known (`registerOperator` was not called) -it lets to `approveAuthorizationDecrease` immediately. 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, but only if enough time passed since the original -request. Otherwise, the function reverts. - -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 beacon 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. - -### genesis - -```solidity -function genesis() external -``` - -Triggers group selection if there are no active groups. - -### submitDkgResult - -```solidity -function submitDkgResult(struct BeaconDkg.Result dkgResult) external -``` - -`\x19Ethereum signed message:\n` before signing, so the message to -sign is: -`\x19Ethereum signed message:\n${keccak256(chainID,groupPubKey,misbehaved,startBlock)}` - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| dkgResult | struct BeaconDkg.Result | DKG result. | - -### notifyDkgTimeout - -```solidity -function notifyDkgTimeout() external -``` - -Notifies about DKG timeout. - -### approveDkgResult - -```solidity -function approveDkgResult(struct BeaconDkg.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 `submitterPrecedencePeriodLength` -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. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| dkgResult | struct BeaconDkg.Result | Result to approve. Must match the submitted result stored during `submitDkgResult`. | - -### challengeDkgResult - -```solidity -function challengeDkgResult(struct BeaconDkg.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. -It removes a candidate group that was previously registered with -the DKG result submission. - -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 BeaconDkg.Result | Result to challenge. Must match the submitted result stored during `submitDkgResult`. | - -### getGroupCreationState - -```solidity -function getGroupCreationState() external view returns (enum BeaconDkg.State) -``` - -Check current group creation state. - -### hasDkgTimedOut - -```solidity -function hasDkgTimedOut() external view returns (bool) -``` - -Checks if DKG timed out. The DKG timeout period includes time required -for off-chain protocol execution and time for the result publication -for all group members. After this time result cannot be submitted -and DKG can be notified about the timeout. - -#### Return Values - -| Name | Type | Description | -| ---- | ---- | ----------- | -| [0] | bool | True if DKG timed out, false otherwise. | - -### getGroupsRegistry - -```solidity -function getGroupsRegistry() external view returns (bytes32[]) -``` - -### getGroup - -```solidity -function getGroup(uint64 groupId) external view returns (struct Groups.Group) -``` - -### getGroup - -```solidity -function getGroup(bytes groupPubKey) external view returns (struct Groups.Group) -``` - -### requestRelayEntry - -```solidity -function requestRelayEntry(contract IRandomBeaconConsumer callbackContract) external -``` - -Creates a request to generate a new relay entry, which will -include a random number (by signing the previous entry's -random number). Requester must be previously authorized by the -governance. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| callbackContract | contract IRandomBeaconConsumer | Beacon consumer callback contract. | - -### submitRelayEntry - -```solidity -function submitRelayEntry(bytes entry) external -``` - -Creates a new relay entry. Gas-optimized version that can be -called only before the soft timeout. This should be the majority -of cases. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| entry | bytes | Group BLS signature over the previous entry. | - -### submitRelayEntry - -```solidity -function submitRelayEntry(bytes entry, uint32[] groupMembers) external -``` - -Creates a new relay entry. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| entry | bytes | Group BLS signature over the previous entry. | -| groupMembers | uint32[] | Identifiers of group members. | - -### reportRelayEntryTimeout - -```solidity -function reportRelayEntryTimeout(uint32[] groupMembers) external -``` - -Reports a relay entry timeout. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| groupMembers | uint32[] | Identifiers of group members. | - -### reportUnauthorizedSigning - -```solidity -function reportUnauthorizedSigning(bytes signedMsgSender, uint64 groupId, uint32[] groupMembers) external -``` - -Reports unauthorized groups signing. Must provide a valid signature -of the sender's address as a message. Successful signature -verification means the private key has been leaked and all group -members should be punished by slashing their tokens. Group has -to be active or expired. Unauthorized signing cannot be reported -for a terminated group. In case of reporting unauthorized -signing for a terminated group, or when the signature is invalid, -function reverts. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| signedMsgSender | bytes | Signature of the sender's address as a message. | -| groupId | uint64 | Group that is being reported for leaking a private key. | -| groupMembers | uint32[] | Identifiers of group members. | - -### notifyOperatorInactivity - -```solidity -function notifyOperatorInactivity(struct BeaconInactivity.Claim claim, uint256 nonce, uint32[] groupMembers) external -``` - -Notifies about operators who are inactive. Using this function, -a majority of the 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 for sortition pool rewards for duration specified by -`_sortitionPoolRewardsBanDuration` parameter. The sender of -the claim must be one of the claim signers. This function can be -called only for active and non-terminated groups. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| claim | struct BeaconInactivity.Claim | Operator inactivity claim. | -| nonce | uint256 | Current inactivity claim nonce for the given group. Must be the same as the stored one. | -| groupMembers | uint32[] | Identifiers of group members. | - -### minimumAuthorization - -```solidity -function minimumAuthorization() external view returns (uint96) -``` - -The minimum authorization amount required so that operator can -participate in the random beacon. This amount is required to -execute slashing for providing a malicious DKG result or when -a relay entry times out. - -### isRelayRequestInProgress - -```solidity -function isRelayRequestInProgress() external view returns (bool) -``` - -#### Return Values - -| Name | Type | Description | -| ---- | ---- | ----------- | -| [0] | bool | Flag indicating whether a relay entry request is currently in progress. | - -### eligibleStake - -```solidity -function eligibleStake(address stakingProvider) external view returns (uint96) -``` - -Returns the current value of the staking provider's eligible -stake. Eligible stake is defined as the currently authorized -stake minus the pending authorization decrease. Eligible stake -is what is used for operator's weight in the sortition pool. -If the authorized stake minus the pending authorization decrease -is below the minimum authorization, eligible stake is 0. - -### availableRewards - -```solidity -function availableRewards(address stakingProvider) external view returns (uint96) -``` - -Returns the amount of rewards available for withdrawal for the -given staking provider. Reverts if staking provider has not -registered the operator address. - -### pendingAuthorizationDecrease - -```solidity -function pendingAuthorizationDecrease(address stakingProvider) external view returns (uint96) -``` - -Returns the amount of stake that is pending authorization -decrease for the given staking provider. If no authorization -decrease has been requested, returns zero. - -### remainingAuthorizationDecreaseDelay - -```solidity -function remainingAuthorizationDecreaseDelay(address stakingProvider) external view returns (uint64) -``` - -Returns the remaining time in seconds that needs to pass before -the requested authorization decrease can be approved. -If the sortition pool state was not updated yet by the operator -after requesting the authorization decrease, returns -`type(uint64).max`. - -### stakingProviderToOperator - -```solidity -function stakingProviderToOperator(address stakingProvider) public view returns (address) -``` - -Returns operator registered for the given staking provider. - -### operatorToStakingProvider - -```solidity -function operatorToStakingProvider(address operator) public view returns (address) -``` - -Returns staking provider of the given operator. - -### isOperatorUpToDate - -```solidity -function isOperatorUpToDate(address operator) external view returns (bool) -``` - -Checks if the operator's authorized stake is in sync with -operator's weight in the sortition pool. -If the operator is not in the sortition pool and their -authorized stake is non-zero, function returns false. - -### isOperatorInPool - -```solidity -function isOperatorInPool(address operator) external view returns (bool) -``` - -Returns true if the given operator is in the sortition pool. -Otherwise, returns false. - -### selectGroup - -```solidity -function selectGroup() external view returns (uint32[]) -``` - -Selects a new group of operators. Can only be called when DKG -is in progress and the pool is locked. -At least one operator has to be registered in the pool, -otherwise the function fails reverting the transaction. - -#### Return Values - -| Name | Type | Description | -| ---- | ---- | ----------- | -| [0] | uint32[] | IDs of selected group members. | - -### authorizationParameters - -```solidity -function authorizationParameters() external view returns (uint96 minimumAuthorization, uint64 authorizationDecreaseDelay, uint64 authorizationDecreaseChangePeriod) -``` - -Returns authorization-related parameters of the beacon. - -The minimum authorization is also returned by `minimumAuthorization()` -function, as a requirement of `IApplication` interface. - -#### Return Values - -| Name | Type | Description | -| ---- | ---- | ----------- | -| minimumAuthorization | uint96 | The minimum authorization amount required so that operator can participate in the random beacon. This amount is required to execute slashing for providing a malicious DKG result or when a relay entry times out. | -| authorizationDecreaseDelay | uint64 | Delay in seconds that needs to pass between the time authorization decrease is requested and the time that request gets approved. Protects against free-riders earning rewards and not being active in the network. | -| authorizationDecreaseChangePeriod | uint64 | Authorization decrease change period in seconds. It is the time, before authorization decrease delay end, during which the pending authorization decrease request can be overwritten. If set to 0, pending authorization decrease request can not be overwritten until the entire `authorizationDecreaseDelay` ends. If set to value equal `authorizationDecreaseDelay`, request can always be overwritten. | - -### relayEntryParameters - -```solidity -function relayEntryParameters() external view returns (uint256 relayEntrySoftTimeout, uint256 relayEntryHardTimeout, uint256 callbackGasLimit) -``` - -Returns relay-entry-related parameters of the beacon. - -#### Return Values - -| Name | Type | Description | -| ---- | ---- | ----------- | -| relayEntrySoftTimeout | uint256 | Soft timeout in blocks for a group to submit the relay entry. If the soft timeout is reached for submitting the relay entry, the slashing starts. | -| relayEntryHardTimeout | uint256 | Hard timeout in blocks for a group to submit the relay entry. After the soft timeout passes without relay entry submitted, all group members start getting slashed. The slashing amount increases linearly until the group submits the relay entry or until `relayEntryHardTimeout` is reached. When the hard timeout is reached, each group member will get slashed for `_relayEntrySubmissionFailureSlashingAmount`. | -| callbackGasLimit | uint256 | Relay entry callback gas limit. This is the gas limit with which callback function provided in the relay request transaction is executed. The callback is executed with a new relay entry value in the same transaction the relay entry is submitted. | - -### groupCreationParameters - -```solidity -function groupCreationParameters() external view returns (uint256 groupCreationFrequency, uint256 groupLifetime, uint256 dkgResultChallengePeriodLength, uint256 dkgResultChallengeExtraGas, uint256 dkgResultSubmissionTimeout, uint256 dkgSubmitterPrecedencePeriodLength) -``` - -Returns group-creation-related parameters of the beacon. - -#### Return Values - -| Name | Type | Description | -| ---- | ---- | ----------- | -| groupCreationFrequency | uint256 | The frequency of a new group creation. Groups are created with a fixed frequency of relay requests. | -| groupLifetime | uint256 | Group lifetime in blocks. When a group reached its lifetime, it is no longer selected for new relay requests but may still be responsible for submitting relay entry if relay request assigned to that group is still pending. | -| dkgResultChallengePeriodLength | uint256 | The number of blocks for which a DKG result can be challenged. Anyone can challenge DKG result for a certain number of blocks before the result is fully accepted and the group registered in the pool of active groups. If the challenge gets accepted, all operators who signed the malicious result get slashed for and the notifier gets rewarded. | -| dkgResultChallengeExtraGas | uint256 | The extra gas required to be left at the end of the challenge DKG result transaction. | -| dkgResultSubmissionTimeout | uint256 | Timeout in blocks for a group to submit the DKG result. All members are eligible to submit the DKG result. If `dkgResultSubmissionTimeout` passes without the DKG result submitted, DKG is considered as timed out and no DKG result for this group creation can be submitted anymore. | -| dkgSubmitterPrecedencePeriodLength | uint256 | Time during the DKG result approval stage when the submitter of the DKG result takes the precedence to approve the DKG result. After this time passes anyone can approve the DKG result. | - -### rewardParameters - -```solidity -function rewardParameters() external view returns (uint256 sortitionPoolRewardsBanDuration, uint256 relayEntryTimeoutNotificationRewardMultiplier, uint256 unauthorizedSigningNotificationRewardMultiplier, uint256 dkgMaliciousResultNotificationRewardMultiplier) -``` - -Returns reward-related parameters of the beacon. - -#### Return Values - -| Name | Type | Description | -| ---- | ---- | ----------- | -| sortitionPoolRewardsBanDuration | uint256 | Duration of the sortition pool rewards ban imposed on operators who misbehaved during DKG by being inactive or disqualified and for operators that were identified by the rest of group members as inactive via `notifyOperatorInactivity`. | -| relayEntryTimeoutNotificationRewardMultiplier | uint256 | Percentage of the staking contract malicious behavior notification reward which will be transferred to the notifier reporting about relay entry timeout. 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. | -| unauthorizedSigningNotificationRewardMultiplier | uint256 | Percentage of the staking contract malicious behavior notification reward which will be transferred to the notifier reporting about unauthorized signing. Notifiers are rewarded from a notifiers treasury pool. For example, if a notification reward is 1000 and the value of the multiplier is 5, the notifier will receive: 5% of 1000 = 50 per each operator affected. | -| dkgMaliciousResultNotificationRewardMultiplier | uint256 | 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. | - -### slashingParameters - -```solidity -function slashingParameters() external view returns (uint96 relayEntrySubmissionFailureSlashingAmount, uint96 maliciousDkgResultSlashingAmount, uint96 unauthorizedSigningSlashingAmount) -``` - -Returns slashing-related parameters of the beacon. - -#### Return Values - -| Name | Type | Description | -| ---- | ---- | ----------- | -| relayEntrySubmissionFailureSlashingAmount | uint96 | Slashing amount for not submitting relay entry. When relay entry hard timeout is reached without the relay entry submitted, each group member gets slashed for `relayEntrySubmissionFailureSlashingAmount`. If the relay entry gets submitted after the soft timeout, but before the hard timeout, each group member gets slashed proportionally to `relayEntrySubmissionFailureSlashingAmount` and the time passed since the soft deadline. | -| maliciousDkgResultSlashingAmount | uint96 | 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`. | -| unauthorizedSigningSlashingAmount | uint96 | Slashing amount when an unauthorized signing has been proved, which means the private key leaked and all the group members should be punished. | - -### gasParameters - -```solidity -function gasParameters() external view returns (uint256 dkgResultSubmissionGas, uint256 dkgResultApprovalGasOffset, uint256 notifyOperatorInactivityGasOffset, uint256 relayEntrySubmissionGasOffset) -``` - -Returns gas-related parameters of the beacon. - -#### Return Values - -| Name | Type | Description | -| ---- | ---- | ----------- | -| dkgResultSubmissionGas | uint256 | Calculated gas cost for submitting a DKG result. This will be refunded as part of the DKG approval process. | -| dkgResultApprovalGasOffset | uint256 | Gas that is meant to balance the DKG result approval's overall cost. | -| notifyOperatorInactivityGasOffset | uint256 | Gas that is meant to balance the operator inactivity notification cost. | -| relayEntrySubmissionGasOffset | uint256 | Gas that is meant to balance the relay entry submission cost. | - -## RandomBeaconChaosnet - -A stub contract that will be used temporarily until the real-world -random beacon client implementation is ready. - -### authorizedRequesters - -```solidity -mapping(address => bool) authorizedRequesters -``` - -Authorized addresses that can request a relay entry. - -### entry - -```solidity -uint256 entry -``` - -Arbitrary relay entry. Initially set to the Euler's number. -It's updated after each relay entry request. - -### RequesterAuthorizationUpdated - -```solidity -event RequesterAuthorizationUpdated(address requester, bool isAuthorized) -``` - -### requestRelayEntry - -```solidity -function requestRelayEntry(contract IRandomBeaconConsumer callbackContract) external -``` - -Executes the callback with an arbitrary relay entry number. - -The caller must be an authorized requester. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| callbackContract | contract IRandomBeaconConsumer | Beacon consumer callback contract - Wallet Registry | - -### setRequesterAuthorization - -```solidity -function setRequesterAuthorization(address requester, bool isAuthorized) external -``` - -Authorizes a requester of the relay entry. - -## RandomBeaconGovernance - -Owns the `RandomBeacon` contract and is responsible for updating its -governable parameters in respect to governance delay individual -for each parameter. - -### newGovernanceDelay - -```solidity -uint256 newGovernanceDelay -``` - -### governanceDelayChangeInitiated - -```solidity -uint256 governanceDelayChangeInitiated -``` - -### newRandomBeaconGovernance - -```solidity -address newRandomBeaconGovernance -``` - -### randomBeaconGovernanceTransferInitiated - -```solidity -uint256 randomBeaconGovernanceTransferInitiated -``` - -### newRelayEntrySoftTimeout - -```solidity -uint256 newRelayEntrySoftTimeout -``` - -### relayEntrySoftTimeoutChangeInitiated - -```solidity -uint256 relayEntrySoftTimeoutChangeInitiated -``` - -### newRelayEntryHardTimeout - -```solidity -uint256 newRelayEntryHardTimeout -``` - -### relayEntryHardTimeoutChangeInitiated - -```solidity -uint256 relayEntryHardTimeoutChangeInitiated -``` - -### newCallbackGasLimit - -```solidity -uint256 newCallbackGasLimit -``` - -### callbackGasLimitChangeInitiated - -```solidity -uint256 callbackGasLimitChangeInitiated -``` - -### newGroupCreationFrequency - -```solidity -uint256 newGroupCreationFrequency -``` - -### groupCreationFrequencyChangeInitiated - -```solidity -uint256 groupCreationFrequencyChangeInitiated -``` - -### newGroupLifetime - -```solidity -uint256 newGroupLifetime -``` - -### groupLifetimeChangeInitiated - -```solidity -uint256 groupLifetimeChangeInitiated -``` - -### newDkgResultChallengePeriodLength - -```solidity -uint256 newDkgResultChallengePeriodLength -``` - -### dkgResultChallengePeriodLengthChangeInitiated - -```solidity -uint256 dkgResultChallengePeriodLengthChangeInitiated -``` - -### newDkgResultChallengeExtraGas - -```solidity -uint256 newDkgResultChallengeExtraGas -``` - -### dkgResultChallengeExtraGasChangeInitiated - -```solidity -uint256 dkgResultChallengeExtraGasChangeInitiated -``` - -### newDkgResultSubmissionTimeout - -```solidity -uint256 newDkgResultSubmissionTimeout -``` - -### dkgResultSubmissionTimeoutChangeInitiated - -```solidity -uint256 dkgResultSubmissionTimeoutChangeInitiated -``` - -### newDkgSubmitterPrecedencePeriodLength - -```solidity -uint256 newDkgSubmitterPrecedencePeriodLength -``` - -### dkgSubmitterPrecedencePeriodLengthChangeInitiated - -```solidity -uint256 dkgSubmitterPrecedencePeriodLengthChangeInitiated -``` - -### newRelayEntrySubmissionFailureSlashingAmount - -```solidity -uint96 newRelayEntrySubmissionFailureSlashingAmount -``` - -### relayEntrySubmissionFailureSlashingAmountChangeInitiated - -```solidity -uint256 relayEntrySubmissionFailureSlashingAmountChangeInitiated -``` - -### newMaliciousDkgResultSlashingAmount - -```solidity -uint96 newMaliciousDkgResultSlashingAmount -``` - -### maliciousDkgResultSlashingAmountChangeInitiated - -```solidity -uint256 maliciousDkgResultSlashingAmountChangeInitiated -``` - -### newUnauthorizedSigningSlashingAmount - -```solidity -uint96 newUnauthorizedSigningSlashingAmount -``` - -### unauthorizedSigningSlashingAmountChangeInitiated - -```solidity -uint256 unauthorizedSigningSlashingAmountChangeInitiated -``` - -### newSortitionPoolRewardsBanDuration - -```solidity -uint256 newSortitionPoolRewardsBanDuration -``` - -### sortitionPoolRewardsBanDurationChangeInitiated - -```solidity -uint256 sortitionPoolRewardsBanDurationChangeInitiated -``` - -### newRelayEntryTimeoutNotificationRewardMultiplier - -```solidity -uint256 newRelayEntryTimeoutNotificationRewardMultiplier -``` - -### relayEntryTimeoutNotificationRewardMultiplierChangeInitiated - -```solidity -uint256 relayEntryTimeoutNotificationRewardMultiplierChangeInitiated -``` - -### newUnauthorizedSigningNotificationRewardMultiplier - -```solidity -uint256 newUnauthorizedSigningNotificationRewardMultiplier -``` - -### unauthorizedSigningNotificationRewardMultiplierChangeInitiated - -```solidity -uint256 unauthorizedSigningNotificationRewardMultiplierChangeInitiated -``` - -### newMinimumAuthorization - -```solidity -uint96 newMinimumAuthorization -``` - -### minimumAuthorizationChangeInitiated - -```solidity -uint256 minimumAuthorizationChangeInitiated -``` - -### newAuthorizationDecreaseDelay - -```solidity -uint64 newAuthorizationDecreaseDelay -``` - -### authorizationDecreaseDelayChangeInitiated - -```solidity -uint256 authorizationDecreaseDelayChangeInitiated -``` - -### newAuthorizationDecreaseChangePeriod - -```solidity -uint64 newAuthorizationDecreaseChangePeriod -``` - -### authorizationDecreaseChangePeriodChangeInitiated - -```solidity -uint256 authorizationDecreaseChangePeriodChangeInitiated -``` - -### newDkgMaliciousResultNotificationRewardMultiplier - -```solidity -uint256 newDkgMaliciousResultNotificationRewardMultiplier -``` - -### dkgMaliciousResultNotificationRewardMultiplierChangeInitiated - -```solidity -uint256 dkgMaliciousResultNotificationRewardMultiplierChangeInitiated -``` - -### newDkgResultSubmissionGas - -```solidity -uint256 newDkgResultSubmissionGas -``` - -### dkgResultSubmissionGasChangeInitiated - -```solidity -uint256 dkgResultSubmissionGasChangeInitiated -``` - -### newDkgResultApprovalGasOffset - -```solidity -uint256 newDkgResultApprovalGasOffset -``` - -### dkgResultApprovalGasOffsetChangeInitiated - -```solidity -uint256 dkgResultApprovalGasOffsetChangeInitiated -``` - -### newNotifyOperatorInactivityGasOffset - -```solidity -uint256 newNotifyOperatorInactivityGasOffset -``` - -### notifyOperatorInactivityGasOffsetChangeInitiated - -```solidity -uint256 notifyOperatorInactivityGasOffsetChangeInitiated -``` - -### newRelayEntrySubmissionGasOffset - -```solidity -uint256 newRelayEntrySubmissionGasOffset -``` - -### relayEntrySubmissionGasOffsetChangeInitiated - -```solidity -uint256 relayEntrySubmissionGasOffsetChangeInitiated -``` - -### randomBeacon - -```solidity -contract RandomBeacon randomBeacon -``` - -### governanceDelay - -```solidity -uint256 governanceDelay -``` - -### GovernanceDelayUpdateStarted - -```solidity -event GovernanceDelayUpdateStarted(uint256 governanceDelay, uint256 timestamp) -``` - -### GovernanceDelayUpdated - -```solidity -event GovernanceDelayUpdated(uint256 governanceDelay) -``` - -### RandomBeaconGovernanceTransferStarted - -```solidity -event RandomBeaconGovernanceTransferStarted(address newRandomBeaconGovernance, uint256 timestamp) -``` - -### RandomBeaconGovernanceTransferred - -```solidity -event RandomBeaconGovernanceTransferred(address newRandomBeaconGovernance) -``` - -### RelayEntrySoftTimeoutUpdateStarted - -```solidity -event RelayEntrySoftTimeoutUpdateStarted(uint256 relayEntrySoftTimeout, uint256 timestamp) -``` - -### RelayEntrySoftTimeoutUpdated - -```solidity -event RelayEntrySoftTimeoutUpdated(uint256 relayEntrySoftTimeout) -``` - -### RelayEntryHardTimeoutUpdateStarted - -```solidity -event RelayEntryHardTimeoutUpdateStarted(uint256 relayEntryHardTimeout, uint256 timestamp) -``` - -### RelayEntryHardTimeoutUpdated - -```solidity -event RelayEntryHardTimeoutUpdated(uint256 relayEntryHardTimeout) -``` - -### CallbackGasLimitUpdateStarted - -```solidity -event CallbackGasLimitUpdateStarted(uint256 callbackGasLimit, uint256 timestamp) -``` - -### CallbackGasLimitUpdated - -```solidity -event CallbackGasLimitUpdated(uint256 callbackGasLimit) -``` - -### GroupCreationFrequencyUpdateStarted - -```solidity -event GroupCreationFrequencyUpdateStarted(uint256 groupCreationFrequency, uint256 timestamp) -``` - -### GroupCreationFrequencyUpdated - -```solidity -event GroupCreationFrequencyUpdated(uint256 groupCreationFrequency) -``` - -### GroupLifetimeUpdateStarted - -```solidity -event GroupLifetimeUpdateStarted(uint256 groupLifetime, uint256 timestamp) -``` - -### GroupLifetimeUpdated - -```solidity -event GroupLifetimeUpdated(uint256 groupLifetime) -``` - -### DkgResultChallengePeriodLengthUpdateStarted - -```solidity -event DkgResultChallengePeriodLengthUpdateStarted(uint256 dkgResultChallengePeriodLength, uint256 timestamp) -``` - -### DkgResultChallengePeriodLengthUpdated - -```solidity -event DkgResultChallengePeriodLengthUpdated(uint256 dkgResultChallengePeriodLength) -``` - -### DkgResultChallengeExtraGasUpdateStarted - -```solidity -event DkgResultChallengeExtraGasUpdateStarted(uint256 dkgResultChallengeExtraGas, uint256 timestamp) -``` - -### DkgResultChallengeExtraGasUpdated - -```solidity -event DkgResultChallengeExtraGasUpdated(uint256 dkgResultChallengeExtraGas) -``` - -### DkgResultSubmissionTimeoutUpdateStarted - -```solidity -event DkgResultSubmissionTimeoutUpdateStarted(uint256 dkgResultSubmissionTimeout, uint256 timestamp) -``` - -### DkgResultSubmissionTimeoutUpdated - -```solidity -event DkgResultSubmissionTimeoutUpdated(uint256 dkgResultSubmissionTimeout) -``` - -### DkgSubmitterPrecedencePeriodLengthUpdateStarted - -```solidity -event DkgSubmitterPrecedencePeriodLengthUpdateStarted(uint256 submitterPrecedencePeriodLength, uint256 timestamp) -``` - -### DkgSubmitterPrecedencePeriodLengthUpdated - -```solidity -event DkgSubmitterPrecedencePeriodLengthUpdated(uint256 submitterPrecedencePeriodLength) -``` - -### RelayEntrySubmissionFailureSlashingAmountUpdateStarted - -```solidity -event RelayEntrySubmissionFailureSlashingAmountUpdateStarted(uint96 relayEntrySubmissionFailureSlashingAmount, uint256 timestamp) -``` - -### RelayEntrySubmissionFailureSlashingAmountUpdated - -```solidity -event RelayEntrySubmissionFailureSlashingAmountUpdated(uint96 relayEntrySubmissionFailureSlashingAmount) -``` - -### MaliciousDkgResultSlashingAmountUpdateStarted - -```solidity -event MaliciousDkgResultSlashingAmountUpdateStarted(uint96 maliciousDkgResultSlashingAmount, uint256 timestamp) -``` - -### MaliciousDkgResultSlashingAmountUpdated - -```solidity -event MaliciousDkgResultSlashingAmountUpdated(uint96 maliciousDkgResultSlashingAmount) -``` - -### UnauthorizedSigningSlashingAmountUpdateStarted - -```solidity -event UnauthorizedSigningSlashingAmountUpdateStarted(uint96 unauthorizedSigningSlashingAmount, uint256 timestamp) -``` - -### UnauthorizedSigningSlashingAmountUpdated - -```solidity -event UnauthorizedSigningSlashingAmountUpdated(uint96 unauthorizedSigningSlashingAmount) -``` - -### SortitionPoolRewardsBanDurationUpdateStarted - -```solidity -event SortitionPoolRewardsBanDurationUpdateStarted(uint256 sortitionPoolRewardsBanDuration, uint256 timestamp) -``` - -### SortitionPoolRewardsBanDurationUpdated - -```solidity -event SortitionPoolRewardsBanDurationUpdated(uint256 sortitionPoolRewardsBanDuration) -``` - -### RelayEntryTimeoutNotificationRewardMultiplierUpdateStarted - -```solidity -event RelayEntryTimeoutNotificationRewardMultiplierUpdateStarted(uint256 relayEntryTimeoutNotificationRewardMultiplier, uint256 timestamp) -``` - -### RelayEntryTimeoutNotificationRewardMultiplierUpdated - -```solidity -event RelayEntryTimeoutNotificationRewardMultiplierUpdated(uint256 relayEntryTimeoutNotificationRewardMultiplier) -``` - -### UnauthorizedSigningNotificationRewardMultiplierUpdateStarted - -```solidity -event UnauthorizedSigningNotificationRewardMultiplierUpdateStarted(uint256 unauthorizedSigningTimeoutNotificationRewardMultiplier, uint256 timestamp) -``` - -### UnauthorizedSigningNotificationRewardMultiplierUpdated - -```solidity -event UnauthorizedSigningNotificationRewardMultiplierUpdated(uint256 unauthorizedSigningTimeoutNotificationRewardMultiplier) -``` - -### MinimumAuthorizationUpdateStarted - -```solidity -event MinimumAuthorizationUpdateStarted(uint96 minimumAuthorization, uint256 timestamp) -``` - -### MinimumAuthorizationUpdated - -```solidity -event MinimumAuthorizationUpdated(uint96 minimumAuthorization) -``` - -### AuthorizationDecreaseDelayUpdateStarted - -```solidity -event AuthorizationDecreaseDelayUpdateStarted(uint64 authorizationDecreaseDelay, uint256 timestamp) -``` - -### AuthorizationDecreaseDelayUpdated - -```solidity -event AuthorizationDecreaseDelayUpdated(uint64 authorizationDecreaseDelay) -``` - -### AuthorizationDecreaseChangePeriodUpdateStarted - -```solidity -event AuthorizationDecreaseChangePeriodUpdateStarted(uint64 authorizationDecreaseChangePeriod, uint256 timestamp) -``` - -### AuthorizationDecreaseChangePeriodUpdated - -```solidity -event AuthorizationDecreaseChangePeriodUpdated(uint64 authorizationDecreaseChangePeriod) -``` - -### DkgMaliciousResultNotificationRewardMultiplierUpdateStarted - -```solidity -event DkgMaliciousResultNotificationRewardMultiplierUpdateStarted(uint256 dkgMaliciousResultNotificationRewardMultiplier, uint256 timestamp) -``` - -### DkgMaliciousResultNotificationRewardMultiplierUpdated - -```solidity -event DkgMaliciousResultNotificationRewardMultiplierUpdated(uint256 dkgMaliciousResultNotificationRewardMultiplier) -``` - -### DkgResultSubmissionGasUpdateStarted - -```solidity -event DkgResultSubmissionGasUpdateStarted(uint256 dkgResultSubmissionGas, uint256 timestamp) -``` - -### DkgResultSubmissionGasUpdated - -```solidity -event DkgResultSubmissionGasUpdated(uint256 dkgResultSubmissionGas) -``` - -### DkgResultApprovalGasOffsetUpdateStarted - -```solidity -event DkgResultApprovalGasOffsetUpdateStarted(uint256 dkgResultApprovalGasOffset, uint256 timestamp) -``` - -### DkgResultApprovalGasOffsetUpdated - -```solidity -event DkgResultApprovalGasOffsetUpdated(uint256 dkgResultApprovalGasOffset) -``` - -### NotifyOperatorInactivityGasOffsetUpdateStarted - -```solidity -event NotifyOperatorInactivityGasOffsetUpdateStarted(uint256 notifyOperatorInactivityGasOffset, uint256 timestamp) -``` - -### NotifyOperatorInactivityGasOffsetUpdated - -```solidity -event NotifyOperatorInactivityGasOffsetUpdated(uint256 notifyOperatorInactivityGasOffset) -``` - -### RelayEntrySubmissionGasOffsetUpdateStarted - -```solidity -event RelayEntrySubmissionGasOffsetUpdateStarted(uint256 relayEntrySubmissionGasOffset, uint256 timestamp) -``` - -### RelayEntrySubmissionGasOffsetUpdated - -```solidity -event RelayEntrySubmissionGasOffsetUpdated(uint256 relayEntrySubmissionGasOffset) -``` - -### onlyAfterGovernanceDelay - -```solidity -modifier onlyAfterGovernanceDelay(uint256 changeInitiatedTimestamp) -``` - -Reverts if called before the governance delay elapses. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| changeInitiatedTimestamp | uint256 | Timestamp indicating the beginning of the change. | - -### constructor - -```solidity -constructor(contract RandomBeacon _randomBeacon, uint256 _governanceDelay) public -``` - -### beginGovernanceDelayUpdate - -```solidity -function beginGovernanceDelayUpdate(uint256 _newGovernanceDelay) external -``` - -Begins the governance delay update process. - -Can be called only by the contract owner. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| _newGovernanceDelay | uint256 | New governance delay | - -### finalizeGovernanceDelayUpdate - -```solidity -function finalizeGovernanceDelayUpdate() external -``` - -Finalizes the governance delay update process. - -Can be called only by the contract owner, after the governance -delay elapses. - -### beginRandomBeaconGovernanceTransfer - -```solidity -function beginRandomBeaconGovernanceTransfer(address _newRandomBeaconGovernance) external -``` - -Begins the random beacon governance transfer process. - -Can be called only by the current contract governance. - -### finalizeRandomBeaconGovernanceTransfer - -```solidity -function finalizeRandomBeaconGovernanceTransfer() external -``` - -Finalizes the random beacon governance transfer process. - -Can be called only by the current contract governance, after the -governance delay elapses. - -### beginRelayEntrySoftTimeoutUpdate - -```solidity -function beginRelayEntrySoftTimeoutUpdate(uint256 _newRelayEntrySoftTimeout) external -``` - -Begins the relay entry soft timeout update process. - -Can be called only by the contract owner. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| _newRelayEntrySoftTimeout | uint256 | New relay entry submission timeout in blocks | - -### finalizeRelayEntrySoftTimeoutUpdate - -```solidity -function finalizeRelayEntrySoftTimeoutUpdate() external -``` - -Finalizes the relay entry soft timeout update process. - -Can be called only by the contract owner, after the governance -delay elapses. - -### beginRelayEntryHardTimeoutUpdate - -```solidity -function beginRelayEntryHardTimeoutUpdate(uint256 _newRelayEntryHardTimeout) external -``` - -Begins the relay entry hard timeout update process. - -Can be called only by the contract owner. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| _newRelayEntryHardTimeout | uint256 | New relay entry hard timeout in blocks | - -### finalizeRelayEntryHardTimeoutUpdate - -```solidity -function finalizeRelayEntryHardTimeoutUpdate() external -``` - -Finalizes the relay entry hard timeout update process. - -Can be called only by the contract owner, after the governance -delay elapses. - -### beginCallbackGasLimitUpdate - -```solidity -function beginCallbackGasLimitUpdate(uint256 _newCallbackGasLimit) external -``` - -Begins the callback gas limit update process. - -Can be called only by the contract owner. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| _newCallbackGasLimit | uint256 | New callback gas limit | - -### finalizeCallbackGasLimitUpdate - -```solidity -function finalizeCallbackGasLimitUpdate() external -``` - -Finalizes the callback gas limit update process. - -Can be called only by the contract owner, after the governance -delay elapses. - -### beginGroupCreationFrequencyUpdate - -```solidity -function beginGroupCreationFrequencyUpdate(uint256 _newGroupCreationFrequency) external -``` - -Begins the group creation frequency update process. - -Can be called only by the contract owner. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| _newGroupCreationFrequency | uint256 | New group creation frequency | - -### finalizeGroupCreationFrequencyUpdate - -```solidity -function finalizeGroupCreationFrequencyUpdate() external -``` - -Finalizes the group creation frequency update process. - -Can be called only by the contract owner, after the governance -delay elapses. - -### beginGroupLifetimeUpdate - -```solidity -function beginGroupLifetimeUpdate(uint256 _newGroupLifetime) external -``` - -Begins the group lifetime update process. Group lifetime needs to -be shorter than the authorization decrease delay to ensure every -active group is backed by enough stake. A new group lifetime value -is in blocks and has to be calculated based on the average block -time and authorization decrease delay which value is in seconds. - -Can be called only by the contract owner. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| _newGroupLifetime | uint256 | New group lifetime in blocks | - -### finalizeGroupLifetimeUpdate - -```solidity -function finalizeGroupLifetimeUpdate() external -``` - -Finalizes the group creation frequency update process. - -Can be called only by the contract owner, after the governance -delay elapses. - -### beginDkgResultChallengePeriodLengthUpdate - -```solidity -function beginDkgResultChallengePeriodLengthUpdate(uint256 _newDkgResultChallengePeriodLength) external -``` - -Begins the DKG result challenge period length update process. - -Can be called only by the contract owner. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| _newDkgResultChallengePeriodLength | uint256 | New DKG result challenge period length in blocks | - -### finalizeDkgResultChallengePeriodLengthUpdate - -```solidity -function finalizeDkgResultChallengePeriodLengthUpdate() external -``` - -Finalizes the DKG result challenge period length update process. - -Can be called only by the contract owner, after the governance -delay elapses. - -### beginDkgResultChallengeExtraGasUpdate - -```solidity -function beginDkgResultChallengeExtraGasUpdate(uint256 _newDkgResultChallengeExtraGas) external -``` - -Begins the DKG result challenge extra gas update process. - -Can be called only by the contract owner. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| _newDkgResultChallengeExtraGas | uint256 | New DKG result challenge extra gas | - -### finalizeDkgResultChallengeExtraGasUpdate - -```solidity -function finalizeDkgResultChallengeExtraGasUpdate() external -``` - -Finalizes the DKG result challenge extra gas update process. - -Can be called only by the contract owner, after the governance -delay elapses. - -### beginDkgResultSubmissionTimeoutUpdate - -```solidity -function beginDkgResultSubmissionTimeoutUpdate(uint256 _newDkgResultSubmissionTimeout) external -``` - -Begins the DKG result submission timeout update -process. - -Can be called only by the contract owner. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| _newDkgResultSubmissionTimeout | uint256 | New DKG result submission timeout in blocks | - -### finalizeDkgResultSubmissionTimeoutUpdate - -```solidity -function finalizeDkgResultSubmissionTimeoutUpdate() external -``` - -Finalizes the DKG result submission timeout update -process. - -Can be called only by the contract owner, after the governance -delay elapses. - -### beginDkgSubmitterPrecedencePeriodLengthUpdate - -```solidity -function beginDkgSubmitterPrecedencePeriodLengthUpdate(uint256 _newDkgSubmitterPrecedencePeriodLength) external -``` - -Begins the DKG submitter precedence period length. - -Can be called only by the contract owner. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| _newDkgSubmitterPrecedencePeriodLength | uint256 | New DKG submitter precedence period length in blocks | - -### finalizeDkgSubmitterPrecedencePeriodLengthUpdate - -```solidity -function finalizeDkgSubmitterPrecedencePeriodLengthUpdate() external -``` - -Finalizes the DKG submitter precedence period length. - -Can be called only by the contract owner, after the governance -delay elapses. - -### beginSortitionPoolRewardsBanDurationUpdate - -```solidity -function beginSortitionPoolRewardsBanDurationUpdate(uint256 _newSortitionPoolRewardsBanDuration) external -``` - -Begins the sortition pool rewards ban duration update process. - -Can be called only by the contract owner. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| _newSortitionPoolRewardsBanDuration | uint256 | New sortition pool rewards ban duration. | - -### finalizeSortitionPoolRewardsBanDurationUpdate - -```solidity -function finalizeSortitionPoolRewardsBanDurationUpdate() external -``` - -Finalizes the sortition pool rewards ban duration update process. - -Can be called only by the contract owner, after the governance -delay elapses. - -### beginRelayEntryTimeoutNotificationRewardMultiplierUpdate - -```solidity -function beginRelayEntryTimeoutNotificationRewardMultiplierUpdate(uint256 _newRelayEntryTimeoutNotificationRewardMultiplier) external -``` - -Begins the relay entry timeout notification reward multiplier -update process. - -Can be called only by the contract owner. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| _newRelayEntryTimeoutNotificationRewardMultiplier | uint256 | New relay entry timeout notification reward multiplier. | - -### beginUnauthorizedSigningNotificationRewardMultiplierUpdate - -```solidity -function beginUnauthorizedSigningNotificationRewardMultiplierUpdate(uint256 _newUnauthorizedSigningNotificationRewardMultiplier) external -``` - -Begins the unauthorized signing notification reward multiplier -update process. - -Can be called only by the contract owner. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| _newUnauthorizedSigningNotificationRewardMultiplier | uint256 | New unauthorized signing notification reward multiplier. | - -### finalizeUnauthorizedSigningNotificationRewardMultiplierUpdate - -```solidity -function finalizeUnauthorizedSigningNotificationRewardMultiplierUpdate() external -``` - -Finalizes the unauthorized signing notification reward -multiplier update process. - -Can be called only by the contract owner, after the governance -delay elapses. - -### finalizeRelayEntryTimeoutNotificationRewardMultiplierUpdate - -```solidity -function finalizeRelayEntryTimeoutNotificationRewardMultiplierUpdate() external -``` - -Finalizes the relay entry timeout notification reward -multiplier update process. - -Can be called only by the contract owner, after the governance -delay elapses. - -### beginDkgMaliciousResultNotificationRewardMultiplierUpdate - -```solidity -function beginDkgMaliciousResultNotificationRewardMultiplierUpdate(uint256 _newDkgMaliciousResultNotificationRewardMultiplier) external -``` - -Begins the DKG malicious result notification reward multiplier -update process. - -Can be called only by the contract owner. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| _newDkgMaliciousResultNotificationRewardMultiplier | uint256 | New DKG malicious result notification reward multiplier. | - -### finalizeDkgMaliciousResultNotificationRewardMultiplierUpdate - -```solidity -function finalizeDkgMaliciousResultNotificationRewardMultiplierUpdate() external -``` - -Finalizes the DKG malicious result notification reward -multiplier update process. - -Can be called only by the contract owner, after the governance -delay elapses. - -### beginRelayEntrySubmissionFailureSlashingAmountUpdate - -```solidity -function beginRelayEntrySubmissionFailureSlashingAmountUpdate(uint96 _newRelayEntrySubmissionFailureSlashingAmount) external -``` - -Begins the relay entry submission failure slashing amount update -process. - -Can be called only by the contract owner. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| _newRelayEntrySubmissionFailureSlashingAmount | uint96 | New relay entry submission failure slashing amount | - -### finalizeRelayEntrySubmissionFailureSlashingAmountUpdate - -```solidity -function finalizeRelayEntrySubmissionFailureSlashingAmountUpdate() external -``` - -Finalizes the relay entry submission failure slashing amount -update process. - -Can be called only by the contract owner, after the governance -delay elapses. - -### beginDkgResultSubmissionGasUpdate - -```solidity -function beginDkgResultSubmissionGasUpdate(uint256 _newDkgResultSubmissionGas) external -``` - -Begins the DKG result submission gas update process. - -Can be called only by the contract owner. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| _newDkgResultSubmissionGas | uint256 | New relay entry submission gas offset | - -### finalizeDkgResultSubmissionGasUpdate - -```solidity -function finalizeDkgResultSubmissionGasUpdate() external -``` - -Finalizes DKG result submission gas update process. - -Can be called only by the contract owner, after the governance -delay elapses. - -### beginDkgResultApprovalGasOffsetUpdate - -```solidity -function beginDkgResultApprovalGasOffsetUpdate(uint256 _newDkgResultApprovalGasOffset) external -``` - -Begins the DKG result approval gas offset update process. - -Can be called only by the contract owner. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| _newDkgResultApprovalGasOffset | uint256 | New DKG approval gas offset | - -### finalizeDkgResultApprovalGasOffsetUpdate - -```solidity -function finalizeDkgResultApprovalGasOffsetUpdate() external -``` - -Finalizes the DKG result approval gas offset update process. - -Can be called only by the contract owner, after the governance -delay elapses. - -### beginNotifyOperatorInactivityGasOffsetUpdate - -```solidity -function beginNotifyOperatorInactivityGasOffsetUpdate(uint256 _newNotifyOperatorInactivityGasOffset) external -``` - -Begins the notify operator inactivity gas offset update process. - -Can be called only by the contract owner. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| _newNotifyOperatorInactivityGasOffset | uint256 | New operator inactivity notification gas offset | - -### finalizeNotifyOperatorInactivityGasOffsetUpdate - -```solidity -function finalizeNotifyOperatorInactivityGasOffsetUpdate() external -``` - -Finalizes the notify operator inactivity gas offset update process. - -Can be called only by the contract owner, after the governance -delay elapses. - -### beginRelayEntrySubmissionGasOffsetUpdate - -```solidity -function beginRelayEntrySubmissionGasOffsetUpdate(uint256 _newRelayEntrySubmissionGasOffset) external -``` - -Begins the relay entry submission gas offset update process. - -Can be called only by the contract owner. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| _newRelayEntrySubmissionGasOffset | uint256 | New relay entry submission gas offset | - -### finalizeRelayEntrySubmissionGasOffsetUpdate - -```solidity -function finalizeRelayEntrySubmissionGasOffsetUpdate() external -``` - -Finalizes relay entry submission gas offset update process. - -Can be called only by the contract owner, after the governance -delay elapses. - -### beginMaliciousDkgResultSlashingAmountUpdate - -```solidity -function beginMaliciousDkgResultSlashingAmountUpdate(uint96 _newMaliciousDkgResultSlashingAmount) external -``` - -Begins the malicious DKG result slashing amount update process. - -Can be called only by the contract owner. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| _newMaliciousDkgResultSlashingAmount | uint96 | New malicious DKG result slashing amount | - -### finalizeMaliciousDkgResultSlashingAmountUpdate - -```solidity -function finalizeMaliciousDkgResultSlashingAmountUpdate() external -``` - -Finalizes the malicious DKG result slashing amount update -process. - -Can be called only by the contract owner, after the governance -delay elapses. - -### beginUnauthorizedSigningSlashingAmountUpdate - -```solidity -function beginUnauthorizedSigningSlashingAmountUpdate(uint96 _newUnauthorizedSigningSlashingAmount) external -``` - -Begins the unauthorized signing slashing amount update process. - -Can be called only by the contract owner. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| _newUnauthorizedSigningSlashingAmount | uint96 | New unauthorized signing slashing amount | - -### finalizeUnauthorizedSigningSlashingAmountUpdate - -```solidity -function finalizeUnauthorizedSigningSlashingAmountUpdate() external -``` - -Finalizes the unauthorized signing slashing amount update -process. - -Can be called only by the contract owner, after the governance -delay elapses. - -### beginMinimumAuthorizationUpdate - -```solidity -function beginMinimumAuthorizationUpdate(uint96 _newMinimumAuthorization) external -``` - -Begins the minimum authorization amount update process. - -Can be called only by the contract owner. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| _newMinimumAuthorization | uint96 | New minimum authorization amount. | - -### finalizeMinimumAuthorizationUpdate - -```solidity -function finalizeMinimumAuthorizationUpdate() external -``` - -Finalizes the minimum authorization amount update process. - -Can be called only by the contract owner, after the governance -delay elapses. - -### beginAuthorizationDecreaseDelayUpdate - -```solidity -function beginAuthorizationDecreaseDelayUpdate(uint64 _newAuthorizationDecreaseDelay) external -``` - -Begins the authorization decrease delay update process. - -Can be called only by the contract owner. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| _newAuthorizationDecreaseDelay | uint64 | New authorization decrease delay | - -### finalizeAuthorizationDecreaseDelayUpdate - -```solidity -function finalizeAuthorizationDecreaseDelayUpdate() external -``` - -Finalizes the authorization decrease delay update process. - -Can be called only by the contract owner, after the governance -delay elapses. - -### beginAuthorizationDecreaseChangePeriodUpdate - -```solidity -function beginAuthorizationDecreaseChangePeriodUpdate(uint64 _newAuthorizationDecreaseChangePeriod) external -``` - -Begins the authorization decrease change period update process. - -Can be called only by the contract owner. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| _newAuthorizationDecreaseChangePeriod | uint64 | New authorization decrease change period | - -### finalizeAuthorizationDecreaseChangePeriodUpdate - -```solidity -function finalizeAuthorizationDecreaseChangePeriodUpdate() external -``` - -Finalizes the authorization decrease change period update process. - -Can be called only by the contract owner, after the governance -delay elapses. - -### setRequesterAuthorization - -```solidity -function setRequesterAuthorization(address requester, bool isAuthorized) external -``` - -Set authorization for requesters that can request a relay -entry. It can be done by the governance only. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| requester | address | Requester, can be a contract or EOA | -| isAuthorized | bool | True or false | - -### 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 owner. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| recipient | address | Recipient of withdrawn rewards. | - -### getRemainingGovernanceDelayUpdateTime - -```solidity -function getRemainingGovernanceDelayUpdateTime() external view returns (uint256) -``` - -Get the time remaining until the governance delay can be updated. - -#### Return Values - -| Name | Type | Description | -| ---- | ---- | ----------- | -| [0] | uint256 | Remaining time in seconds. | - -### getRemainingRandomBeaconGovernanceTransferDelayTime - -```solidity -function getRemainingRandomBeaconGovernanceTransferDelayTime() external view returns (uint256) -``` - -Get the time remaining until the random beacon governance can -be transferred. - -#### Return Values - -| Name | Type | Description | -| ---- | ---- | ----------- | -| [0] | uint256 | Remaining time in seconds. | - -### getRemainingRelayEntrySoftTimeoutUpdateTime - -```solidity -function getRemainingRelayEntrySoftTimeoutUpdateTime() external view returns (uint256) -``` - -Get the time remaining until the relay entry submission soft -timeout can be updated. - -#### Return Values - -| Name | Type | Description | -| ---- | ---- | ----------- | -| [0] | uint256 | Remaining time in seconds. | - -### getRemainingRelayEntryHardTimeoutUpdateTime - -```solidity -function getRemainingRelayEntryHardTimeoutUpdateTime() external view returns (uint256) -``` - -Get the time remaining until the relay entry hard timeout can be -updated. - -#### Return Values - -| Name | Type | Description | -| ---- | ---- | ----------- | -| [0] | uint256 | Remaining time in seconds. | - -### getRemainingCallbackGasLimitUpdateTime - -```solidity -function getRemainingCallbackGasLimitUpdateTime() external view returns (uint256) -``` - -Get the time remaining until the callback gas limit can be -updated. - -#### Return Values - -| Name | Type | Description | -| ---- | ---- | ----------- | -| [0] | uint256 | Remaining time in seconds. | - -### getRemainingGroupCreationFrequencyUpdateTime - -```solidity -function getRemainingGroupCreationFrequencyUpdateTime() external view returns (uint256) -``` - -Get the time remaining until the group creation frequency can be -updated. - -#### Return Values - -| Name | Type | Description | -| ---- | ---- | ----------- | -| [0] | uint256 | Remaining time in seconds. | - -### getRemainingGroupLifetimeUpdateTime - -```solidity -function getRemainingGroupLifetimeUpdateTime() external view returns (uint256) -``` - -Get the time remaining until the group lifetime can be updated. - -#### Return Values - -| Name | Type | Description | -| ---- | ---- | ----------- | -| [0] | uint256 | Remaining time in seconds. | - -### getRemainingDkgResultChallengePeriodLengthUpdateTime - -```solidity -function getRemainingDkgResultChallengePeriodLengthUpdateTime() external view returns (uint256) -``` - -Get the time remaining until the DKG result challenge period -length can be updated. - -#### Return Values - -| Name | Type | Description | -| ---- | ---- | ----------- | -| [0] | uint256 | Remaining time in seconds. | - -### getRemainingDkgResultChallengeExtraGasUpdateTime - -```solidity -function getRemainingDkgResultChallengeExtraGasUpdateTime() external view returns (uint256) -``` - -Get the time remaining until the DKG result challenge extra -gas can be updated. - -#### Return Values - -| Name | Type | Description | -| ---- | ---- | ----------- | -| [0] | uint256 | Remaining time in seconds. | - -### getRemainingDkgResultSubmissionTimeoutUpdateTime - -```solidity -function getRemainingDkgResultSubmissionTimeoutUpdateTime() external view returns (uint256) -``` - -Get the time remaining until the DKG result submission timeout -can be updated. - -#### Return Values - -| Name | Type | Description | -| ---- | ---- | ----------- | -| [0] | uint256 | Remaining time in seconds. | - -### getRemainingDkgSubmitterPrecedencePeriodLengthUpdateTime - -```solidity -function getRemainingDkgSubmitterPrecedencePeriodLengthUpdateTime() external view returns (uint256) -``` - -Get the time remaining until the wallet owner can be updated. - -#### Return Values - -| Name | Type | Description | -| ---- | ---- | ----------- | -| [0] | uint256 | Remaining time in seconds. | - -### getRemainingRelayEntrySubmissionFailureSlashingAmountUpdateTime - -```solidity -function getRemainingRelayEntrySubmissionFailureSlashingAmountUpdateTime() external view returns (uint256) -``` - -Get the time remaining until the relay entry submission failure -slashing amount can be updated. - -#### Return Values - -| Name | Type | Description | -| ---- | ---- | ----------- | -| [0] | uint256 | Remaining time in seconds. | - -### getRemainingMaliciousDkgResultSlashingAmountUpdateTime - -```solidity -function getRemainingMaliciousDkgResultSlashingAmountUpdateTime() external view returns (uint256) -``` - -Get the time remaining until the malicious DKG result -slashing amount can be updated. - -#### Return Values - -| Name | Type | Description | -| ---- | ---- | ----------- | -| [0] | uint256 | Remaining time in seconds. | - -### getRemainingUnauthorizedSigningSlashingAmountUpdateTime - -```solidity -function getRemainingUnauthorizedSigningSlashingAmountUpdateTime() external view returns (uint256) -``` - -Get the time remaining until the unauthorized signing -slashing amount can be updated. - -#### Return Values - -| Name | Type | Description | -| ---- | ---- | ----------- | -| [0] | uint256 | Remaining time in seconds. | - -### getRemainingMimimumAuthorizationUpdateTime - -```solidity -function getRemainingMimimumAuthorizationUpdateTime() external view returns (uint256) -``` - -Get the time remaining until the minimum authorization amount -can be updated. - -#### Return Values - -| Name | Type | Description | -| ---- | ---- | ----------- | -| [0] | uint256 | Remaining time in seconds. | - -### getRemainingAuthorizationDecreaseDelayUpdateTime - -```solidity -function getRemainingAuthorizationDecreaseDelayUpdateTime() external view returns (uint256) -``` - -Get the time remaining until the authorization decrease delay -can be updated. - -#### Return Values - -| Name | Type | Description | -| ---- | ---- | ----------- | -| [0] | uint256 | Remaining time in seconds. | - -### getRemainingAuthorizationDecreaseChangePeriodUpdateTime - -```solidity -function getRemainingAuthorizationDecreaseChangePeriodUpdateTime() external view returns (uint256) -``` - -Get the time remaining until the authorization decrease change -period can be updated. - -#### Return Values - -| Name | Type | Description | -| ---- | ---- | ----------- | -| [0] | uint256 | Remaining time in seconds. | - -### getRemainingSortitionPoolRewardsBanDurationUpdateTime - -```solidity -function getRemainingSortitionPoolRewardsBanDurationUpdateTime() external view returns (uint256) -``` - -Get the time remaining until the sortition pool rewards ban -duration can be updated. - -#### Return Values - -| Name | Type | Description | -| ---- | ---- | ----------- | -| [0] | uint256 | Remaining time in seconds. | - -### getRemainingRelayEntryTimeoutNotificationRewardMultiplierUpdateTime - -```solidity -function getRemainingRelayEntryTimeoutNotificationRewardMultiplierUpdateTime() external view returns (uint256) -``` - -Get the time remaining until the relay entry timeout -notification reward multiplier duration can be updated. - -#### Return Values - -| Name | Type | Description | -| ---- | ---- | ----------- | -| [0] | uint256 | Remaining time in seconds. | - -### getRemainingUnauthorizedSigningNotificationRewardMultiplierUpdateTime - -```solidity -function getRemainingUnauthorizedSigningNotificationRewardMultiplierUpdateTime() external view returns (uint256) -``` - -Get the time remaining until the unauthorized signing -notification reward multiplier duration can be updated. - -#### Return Values - -| Name | Type | Description | -| ---- | ---- | ----------- | -| [0] | uint256 | Remaining time in seconds. | - -### getRemainingDkgMaliciousResultNotificationRewardMultiplierUpdateTime - -```solidity -function getRemainingDkgMaliciousResultNotificationRewardMultiplierUpdateTime() external view returns (uint256) -``` - -Get the time remaining until the DKG malicious result -notification reward multiplier duration can be updated. - -#### Return Values - -| Name | Type | Description | -| ---- | ---- | ----------- | -| [0] | uint256 | Remaining time in seconds. | - -### getRemainingDkgResultSubmissionGasUpdateTime - -```solidity -function getRemainingDkgResultSubmissionGasUpdateTime() external view returns (uint256) -``` - -Get the time remaining until the DKG result submission gas -duration can be updated. - -#### Return Values - -| Name | Type | Description | -| ---- | ---- | ----------- | -| [0] | uint256 | Remaining time in seconds. | - -### getRemainingDkgResultApprovalGasOffsetUpdateTime - -```solidity -function getRemainingDkgResultApprovalGasOffsetUpdateTime() external view returns (uint256) -``` - -Get the time remaining until the DKG approval gas offset duration -can be updated. - -#### Return Values - -| Name | Type | Description | -| ---- | ---- | ----------- | -| [0] | uint256 | Remaining time in seconds. | - -### getRemainingNotifyOperatorInactivityGasOffsetUpdateTime - -```solidity -function getRemainingNotifyOperatorInactivityGasOffsetUpdateTime() external view returns (uint256) -``` - -Get the time remaining until the operator inactivity notification -gas offset duration can be updated. - -#### Return Values - -| Name | Type | Description | -| ---- | ---- | ----------- | -| [0] | uint256 | Remaining time in seconds. | - -### getRemainingRelayEntrySubmissionGasOffsetUpdateTime - -```solidity -function getRemainingRelayEntrySubmissionGasOffsetUpdateTime() external view returns (uint256) -``` - -Get the time remaining until the relay entry submission gas offset -duration can be updated. - -#### Return Values - -| Name | Type | Description | -| ---- | ---- | ----------- | -| [0] | uint256 | Remaining time in seconds. | - -### getRemainingChangeTime - -```solidity -function getRemainingChangeTime(uint256 changeTimestamp) internal view returns (uint256) -``` - -Gets the time remaining until the governable parameter update -can be committed. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| changeTimestamp | uint256 | Timestamp indicating the beginning of the change. | - -#### Return Values - -| Name | Type | Description | -| ---- | ---- | ----------- | -| [0] | uint256 | Remaining time in seconds. | - -## Reimbursable - -### reimbursementPool - -```solidity -contract ReimbursementPool reimbursementPool -``` - -### ReimbursementPoolUpdated - -```solidity -event ReimbursementPoolUpdated(address newReimbursementPool) -``` - -### refundable - -```solidity -modifier refundable(address receiver) -``` - -### onlyReimbursableAdmin - -```solidity -modifier onlyReimbursableAdmin() -``` - -### updateReimbursementPool - -```solidity -function updateReimbursementPool(contract ReimbursementPool _reimbursementPool) external -``` - -## ReimbursementPool - -### isAuthorized - -```solidity -mapping(address => bool) isAuthorized -``` - -Authorized contracts that can interact with the reimbursment pool. -Authorization can be granted and removed by the owner. - -### staticGas - -```solidity -uint256 staticGas -``` - -Static gas includes: -- cost of the refund function -- base transaction cost - -### maxGasPrice - -```solidity -uint256 maxGasPrice -``` - -Max gas price used to reimburse a transaction submitter. Protects -against malicious operator-miners. - -### StaticGasUpdated - -```solidity -event StaticGasUpdated(uint256 newStaticGas) -``` - -### MaxGasPriceUpdated - -```solidity -event MaxGasPriceUpdated(uint256 newMaxGasPrice) -``` - -### SendingEtherFailed - -```solidity -event SendingEtherFailed(uint256 refundAmount, address receiver) -``` - -### AuthorizedContract - -```solidity -event AuthorizedContract(address thirdPartyContract) -``` - -### UnauthorizedContract - -```solidity -event UnauthorizedContract(address thirdPartyContract) -``` - -### FundsWithdrawn - -```solidity -event FundsWithdrawn(uint256 withdrawnAmount, address receiver) -``` - -### constructor - -```solidity -constructor(uint256 _staticGas, uint256 _maxGasPrice) public -``` - -### receive - -```solidity -receive() external payable -``` - -Receive ETH - -### refund - -```solidity -function refund(uint256 gasSpent, address receiver) external -``` - -Refunds ETH to a spender for executing specific transactions. - -Ignoring the result of sending ETH to a receiver is made on purpose. -For EOA receiving ETH should always work. If a receiver is a smart -contract, then we do not want to fail a transaction, because in some -cases the refund is done at the very end of multiple calls where all -the previous calls were already paid off. It is a receiver's smart -contract resposibility to make sure it can receive ETH. -Only authorized contracts are allowed calling this function. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| gasSpent | uint256 | Gas spent on a transaction that needs to be reimbursed. | -| receiver | address | Address where the reimbursment is sent. | - -### authorize - -```solidity -function authorize(address _contract) external -``` - -Authorize a contract that can interact with this reimbursment pool. -Can be authorized by the owner only. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| _contract | address | Authorized contract. | - -### unauthorize - -```solidity -function unauthorize(address _contract) external -``` - -Unauthorize a contract that was previously authorized to interact -with this reimbursment pool. Can be unauthorized by the -owner only. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| _contract | address | Authorized contract. | - -### setStaticGas - -```solidity -function setStaticGas(uint256 _staticGas) external -``` - -Setting a static gas cost for executing a transaction. Can be set -by the owner only. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| _staticGas | uint256 | Static gas cost. | - -### setMaxGasPrice - -```solidity -function setMaxGasPrice(uint256 _maxGasPrice) external -``` - -Setting a max gas price for transactions. Can be set by the -owner only. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| _maxGasPrice | uint256 | Max gas price used to reimburse tx submitters. | - -### withdrawAll - -```solidity -function withdrawAll(address receiver) external -``` - -Withdraws all ETH from this pool which are sent to a given -address. Can be set by the owner only. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| receiver | address | An address where ETH is sent. | - -### withdraw - -```solidity -function withdraw(uint256 amount, address receiver) public -``` - -Withdraws ETH amount from this pool which are sent to a given -address. Can be set by the owner only. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| amount | uint256 | Amount to withdraw from the pool. | -| receiver | address | An address where ETH is sent. | - -## IRandomBeacon - -### requestRelayEntry - -```solidity -function requestRelayEntry(contract IRandomBeaconConsumer callbackContract) external -``` - -Creates a request to generate a new relay entry. Requires a -request fee denominated in T token. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| callbackContract | contract IRandomBeaconConsumer | Beacon consumer callback contract. | - -## IRandomBeaconConsumer - -### __beaconCallback - -```solidity -function __beaconCallback(uint256 relayEntry, uint256 blockNumber) external -``` - -Receives relay entry produced by Keep Random Beacon. This function -should be called only by Keep Random Beacon. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| relayEntry | uint256 | Relay entry (random number) produced by Keep Random Beacon. | -| blockNumber | uint256 | Block number at which the relay entry was submitted to the chain. | - -## AltBn128 - -Implementations of common elliptic curve operations on Ethereum's -(poorly named) alt_bn128 curve. Whenever possible, use post-Byzantium -pre-compiled contracts to offset gas costs. Note that these -pre-compiles might not be available on all (eg private) chains. - -### G1Point - -```solidity -struct G1Point { - uint256 x; - uint256 y; -} -``` - -### gfP2 - -```solidity -struct gfP2 { - uint256 x; - uint256 y; -} -``` - -### G2Point - -```solidity -struct G2Point { - struct AltBn128.gfP2 x; - struct AltBn128.gfP2 y; -} -``` - -### p - -```solidity -uint256 p -``` - -### g1x - -```solidity -uint256 g1x -``` - -Gets generator of G1 group. -Taken from go-ethereum/crypto/bn256/cloudflare/curve.go - -### g1y - -```solidity -uint256 g1y -``` - -### g2xx - -```solidity -uint256 g2xx -``` - -Gets generator of G2 group. -Taken from go-ethereum/crypto/bn256/cloudflare/twist.go - -### g2xy - -```solidity -uint256 g2xy -``` - -### g2yx - -```solidity -uint256 g2yx -``` - -### g2yy - -```solidity -uint256 g2yy -``` - -### twistBx - -```solidity -uint256 twistBx -``` - -Gets twist curve B constant. -Taken from go-ethereum/crypto/bn256/cloudflare/twist.go - -### twistBy - -```solidity -uint256 twistBy -``` - -### hexRootX - -```solidity -uint256 hexRootX -``` - -Gets root of the point where x and y are equal. - -### hexRootY - -```solidity -uint256 hexRootY -``` - -### g1YFromX - -```solidity -function g1YFromX(uint256 x) internal view returns (uint256) -``` - -g1YFromX computes a Y value for a G1 point based on an X value. -This computation is simply evaluating the curve equation for Y on a -given X, and allows a point on the curve to be represented by just -an X value + a sign bit. - -### g1HashToPoint - -```solidity -function g1HashToPoint(bytes m) internal view returns (struct AltBn128.G1Point) -``` - -Hash a byte array message, m, and map it deterministically to a -point on G1. Note that this approach was chosen for its simplicity -and lower gas cost on the EVM, rather than good distribution of -points on G1. - -### g1Decompress - -```solidity -function g1Decompress(bytes32 m) internal view returns (struct AltBn128.G1Point) -``` - -Decompress a point on G1 from a single uint256. - -### g1Add - -```solidity -function g1Add(struct AltBn128.G1Point a, struct AltBn128.G1Point b) internal view returns (struct AltBn128.G1Point c) -``` - -Wraps the point addition pre-compile introduced in Byzantium. -Returns the sum of two points on G1. Revert if the provided points -are not on the curve. - -### isG1PointOnCurve - -```solidity -function isG1PointOnCurve(struct AltBn128.G1Point point) internal view returns (bool) -``` - -Returns true if G1 point is on the curve. - -### scalarMultiply - -```solidity -function scalarMultiply(struct AltBn128.G1Point p_1, uint256 scalar) internal view returns (struct AltBn128.G1Point p_2) -``` - -Wraps the scalar point multiplication pre-compile introduced in -Byzantium. The result of a point from G1 multiplied by a scalar -should match the point added to itself the same number of times. -Revert if the provided point isn't on the curve. - -### pairing - -```solidity -function pairing(struct AltBn128.G1Point p1, struct AltBn128.G2Point p2, struct AltBn128.G1Point p3, struct AltBn128.G2Point p4) internal view returns (bool result) -``` - -Wraps the pairing check pre-compile introduced in Byzantium. -Returns the result of a pairing check of 2 pairs -(G1 p1, G2 p2) (G1 p3, G2 p4) - -### getP - -```solidity -function getP() internal pure returns (uint256) -``` - -### g1 - -```solidity -function g1() internal pure returns (struct AltBn128.G1Point) -``` - -### g2 - -```solidity -function g2() internal pure returns (struct AltBn128.G2Point) -``` - -### g2YFromX - -```solidity -function g2YFromX(struct AltBn128.gfP2 _x) internal pure returns (struct AltBn128.gfP2 y) -``` - -g2YFromX computes a Y value for a G2 point based on an X value. -This computation is simply evaluating the curve equation for Y on a -given X, and allows a point on the curve to be represented by just -an X value + a sign bit. - -### g1Compress - -```solidity -function g1Compress(struct AltBn128.G1Point point) internal pure returns (bytes32) -``` - -Compress a point on G1 to a single uint256 for serialization. - -### g2Compress - -```solidity -function g2Compress(struct AltBn128.G2Point point) internal pure returns (bytes) -``` - -Compress a point on G2 to a pair of uint256 for serialization. - -### g1Unmarshal - -```solidity -function g1Unmarshal(bytes m) internal pure returns (struct AltBn128.G1Point) -``` - -Unmarshals a point on G1 from bytes in an uncompressed form. - -### g1Marshal - -```solidity -function g1Marshal(struct AltBn128.G1Point point) internal pure returns (bytes) -``` - -Marshals a point on G1 to bytes form. - -### g2Unmarshal - -```solidity -function g2Unmarshal(bytes m) internal pure returns (struct AltBn128.G2Point) -``` - -Unmarshals a point on G2 from bytes in an uncompressed form. - -### g2Decompress - -```solidity -function g2Decompress(bytes m) internal pure returns (struct AltBn128.G2Point) -``` - -Decompress a point on G2 from a pair of uint256. - -### gfP2Add - -```solidity -function gfP2Add(struct AltBn128.gfP2 a, struct AltBn128.gfP2 b) internal pure returns (struct AltBn128.gfP2) -``` - -Returns the sum of two gfP2 field elements. - -### gfP2Multiply - -```solidity -function gfP2Multiply(struct AltBn128.gfP2 a, struct AltBn128.gfP2 b) internal pure returns (struct AltBn128.gfP2) -``` - -Returns multiplication of two gfP2 field elements. - -### gfP2Pow - -```solidity -function gfP2Pow(struct AltBn128.gfP2 _a, uint256 _exp) internal pure returns (struct AltBn128.gfP2 result) -``` - -Returns gfP2 element to the power of the provided exponent. - -### gfP2Square - -```solidity -function gfP2Square(struct AltBn128.gfP2 a) internal pure returns (struct AltBn128.gfP2) -``` - -### gfP2Cube - -```solidity -function gfP2Cube(struct AltBn128.gfP2 a) internal pure returns (struct AltBn128.gfP2) -``` - -### gfP2CubeAddTwistB - -```solidity -function gfP2CubeAddTwistB(struct AltBn128.gfP2 a) internal pure returns (struct AltBn128.gfP2) -``` - -### g2X2y - -```solidity -function g2X2y(struct AltBn128.gfP2 x, struct AltBn128.gfP2 y) internal pure returns (bool) -``` - -Returns true if G2 point's y^2 equals x. - -### isG2PointOnCurve - -```solidity -function isG2PointOnCurve(struct AltBn128.G2Point point) internal pure returns (bool) -``` - -Returns true if G2 point is on the curve. - -## BLS - -Library for verification of 2-pairing-check BLS signatures, including -basic, aggregated, or reconstructed threshold BLS signatures, generated -using the AltBn128 curve. - -### sign - -```solidity -function sign(bytes message, uint256 secretKey) external view returns (bytes) -``` - -Creates a signature over message using the provided secret key. - -### verifyBytes - -```solidity -function verifyBytes(bytes publicKey, bytes message, bytes signature) external view returns (bool) -``` - -Wraps the functionality of BLS.verify, but hashes a message to -a point on G1 and marshal to bytes first to allow raw bytes -verification. - -### verify - -```solidity -function verify(bytes publicKey, bytes message, bytes signature) public view returns (bool) -``` - -Verify performs the pairing operation to check if the signature -is correct for the provided message and the corresponding public -key. Public key must be a valid point on G2 curve in an -uncompressed format. Message must be a valid point on G1 curve in -an uncompressed format. Signature must be a valid point on G1 -curve in an uncompressed format. - -### _verify - -```solidity -function _verify(struct AltBn128.G2Point publicKey, struct AltBn128.G1Point message, struct AltBn128.G1Point signature) public view returns (bool) -``` - -## BeaconAuthorization - -Library managing the state of stake authorizations for the operator -contract and the presence of operators in the sortition -pool based on the stake authorized for them. - -### Parameters - -```solidity -struct Parameters { - uint96 minimumAuthorization; - uint64 authorizationDecreaseDelay; - uint64 authorizationDecreaseChangePeriod; -} -``` - -### AuthorizationDecrease - -```solidity -struct AuthorizationDecrease { - uint96 decreasingBy; - uint64 decreasingAt; -} -``` - -### Data - -```solidity -struct Data { - struct BeaconAuthorization.Parameters parameters; - mapping(address => address) stakingProviderToOperator; - mapping(address => address) operatorToStakingProvider; - mapping(address => struct BeaconAuthorization.AuthorizationDecrease) pendingDecreases; -} -``` - -### 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) -``` - -### setParameters - -```solidity -function setParameters(struct BeaconAuthorization.Data self, uint96 _minimumAuthorization, uint64 _authorizationDecreaseDelay, uint64 _authorizationDecreaseChangePeriod) external -``` - -Updates authorization-related parameters. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| self | struct BeaconAuthorization.Data | | -| _minimumAuthorization | uint96 | New value of the minimum authorization for the beacon. Without at least the minimum authorization, staking provider is not eligible to join and operate in the network. | -| _authorizationDecreaseDelay | uint64 | New value of the authorization decrease delay. It is the time in seconds that needs to pass between the time authorization decrease is requested and the time the authorization decrease can be approved, no matter the authorization decrease amount. | -| _authorizationDecreaseChangePeriod | uint64 | New value of the authorization decrease change period. It is the time in seconds, before authorization decrease delay end, during which the pending authorization decrease request can be overwritten. If set to 0, pending authorization decrease request can not be overwritten until the entire `authorizationDecreaseDelay` ends. If set to value equal `authorizationDecreaseDelay`, request can always be overwritten. | - -### registerOperator - -```solidity -function registerOperator(struct BeaconAuthorization.Data self, address operator) public -``` - -Used by staking provider to set operator address that will -operate a 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. - -### authorizationIncreased - -```solidity -function authorizationIncreased(struct BeaconAuthorization.Data self, address stakingProvider, uint96 fromAmount, uint96 toAmount) external -``` - -Used by T staking contract to inform the beacon 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`. - -Should only be callable by T staking contract. - -### authorizationDecreaseRequested - -```solidity -function authorizationDecreaseRequested(struct BeaconAuthorization.Data self, address stakingProvider, uint96 fromAmount, uint96 toAmount) public -``` - -Used by T staking contract to inform the beacon 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. - -Reverts if another authorization decrease request is pending for -the staking provider and not enough time passed since the -original request (see `authorizationDecreaseChangePeriod`). - -If the operator is not known (`registerOperator` was not called) -it lets to `approveAuthorizationDecrease` immediately. 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, but only if enough time passed since the original -request. Otherwise, the function reverts. - -Should only be callable by T staking contract. - -### approveAuthorizationDecrease - -```solidity -function approveAuthorizationDecrease(struct BeaconAuthorization.Data self, contract IStaking tokenStaking, address stakingProvider) public -``` - -Approves the previously registered authorization decrease -request. Reverts if authorization decrease delay have not passed -yet or if the authorization decrease was not requested for the -given staking provider. - -### involuntaryAuthorizationDecrease - -```solidity -function involuntaryAuthorizationDecrease(struct BeaconAuthorization.Data self, contract IStaking tokenStaking, contract SortitionPool sortitionPool, address stakingProvider, uint96 fromAmount, uint96 toAmount) external -``` - -Used by T staking contract to inform the beacon 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. - -Should only be callable by T staking contract. - -### joinSortitionPool - -```solidity -function joinSortitionPool(struct BeaconAuthorization.Data self, contract IStaking tokenStaking, contract SortitionPool sortitionPool) public -``` - -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 the beacon. 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(struct BeaconAuthorization.Data self, contract IStaking tokenStaking, contract SortitionPool sortitionPool, address operator) public -``` - -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. - -### isOperatorUpToDate - -```solidity -function isOperatorUpToDate(struct BeaconAuthorization.Data self, contract IStaking tokenStaking, contract SortitionPool sortitionPool, address operator) external view returns (bool) -``` - -Checks if the operator's authorized stake is in sync with -operator's weight in the sortition pool. -If the operator is not in the sortition pool and their -authorized stake is non-zero, function returns false. - -### eligibleStake - -```solidity -function eligibleStake(struct BeaconAuthorization.Data self, contract IStaking tokenStaking, address stakingProvider) external view returns (uint96) -``` - -Returns the current value of the staking provider's eligible -stake. Eligible stake is defined as the currently authorized -stake minus the pending authorization decrease. Eligible stake -is what is used for operator's weight in the pool. If the -authorized stake minus the pending authorization decrease is -below the minimum authorization, eligible stake is 0. - -This function can be exposed to the public in contrast to the -second variant accepting `decreasingBy` as a parameter. - -### eligibleStake - -```solidity -function eligibleStake(struct BeaconAuthorization.Data self, contract IStaking tokenStaking, address stakingProvider, uint96 decreasingBy) public view returns (uint96) -``` - -Returns the current value of the staking provider's eligible -stake. Eligible stake is defined as the currently authorized -stake minus the pending authorization decrease. Eligible stake -is what is used for operator's weight in the pool. If the -authorized stake minus the pending authorization decrease is -below the minimum authorization, eligible stake is 0. - -This function is not intended to be exposes to the public. -`decreasingBy` must be fetched from `pendingDecreases` mapping and -it is passed as a parameter to optimize gas usage of functions that -call `eligibleStake` and need to use `AuthorizationDecrease` -fetched from `pendingDecreases` for some additional logic. - -### pendingAuthorizationDecrease - -```solidity -function pendingAuthorizationDecrease(struct BeaconAuthorization.Data self, address stakingProvider) public view returns (uint96) -``` - -Returns the amount of stake that is pending authorization -decrease for the given staking provider. If no authorization -decrease has been requested, returns zero. - -### remainingAuthorizationDecreaseDelay - -```solidity -function remainingAuthorizationDecreaseDelay(struct BeaconAuthorization.Data self, address stakingProvider) external view returns (uint64) -``` - -Returns the remaining time in seconds that needs to pass before -the requested authorization decrease can be approved. -If the sortition pool state was not updated yet by the operator -after requesting the authorization decrease, returns -`type(uint64).max`. - -## BeaconDkg - -### Parameters - -```solidity -struct Parameters { - uint256 resultChallengePeriodLength; - uint256 resultChallengeExtraGas; - uint256 resultSubmissionTimeout; - uint256 submitterPrecedencePeriodLength; -} -``` - -### Data - -```solidity -struct Data { - contract SortitionPool sortitionPool; - contract BeaconDkgValidator dkgValidator; - struct BeaconDkg.Parameters parameters; - uint256 startBlock; - uint256 seed; - uint256 resultSubmissionStartBlockOffset; - bytes32 submittedResultHash; - uint256 submittedResultBlock; -} -``` - -### Result - -```solidity -struct Result { - uint256 submitterMemberIndex; - bytes groupPubKey; - uint8[] misbehavedMembersIndices; - bytes signatures; - uint256[] signingMembersIndices; - uint32[] members; - bytes32 membersHash; -} -``` - -### State - -```solidity -enum State { - IDLE, - AWAITING_SEED, - KEY_GENERATION, - AWAITING_RESULT, - CHALLENGE -} -``` - -### groupSize - -```solidity -uint256 groupSize -``` - -Size of a group in the threshold relay. - -### offchainDkgTime - -```solidity -uint256 offchainDkgTime -``` - -Time in blocks after which DKG result is complete and ready to be - -### DkgStarted - -```solidity -event DkgStarted(uint256 seed) -``` - -### DkgResultSubmitted - -```solidity -event DkgResultSubmitted(bytes32 resultHash, uint256 seed, struct BeaconDkg.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() -``` - -### init - -```solidity -function init(struct BeaconDkg.Data self, contract SortitionPool _sortitionPool, contract BeaconDkgValidator _dkgValidator) internal -``` - -Initializes SortitionPool and DKGValidator addresses. -Can be performed only once. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| self | struct BeaconDkg.Data | | -| _sortitionPool | contract SortitionPool | Sortition Pool reference | -| _dkgValidator | contract BeaconDkgValidator | DKGValidator reference | - -### currentState - -```solidity -function currentState(struct BeaconDkg.Data self) internal view returns (enum BeaconDkg.State state) -``` - -Determines the current state of group creation. It doesn't take -timeouts into consideration. The timeouts should be tracked and -notified separately. - -### lockState - -```solidity -function lockState(struct BeaconDkg.Data self) internal -``` - -Locks the sortition pool and starts awaiting for the -group creation seed. - -### start - -```solidity -function start(struct BeaconDkg.Data self, uint256 seed) internal -``` - -### submitResult - -```solidity -function submitResult(struct BeaconDkg.Data self, struct BeaconDkg.Result result) external -``` - -Allows to submit a DKG result. The submitted result does not go -through a validation and before it gets accepted, it needs to -wait through the challenge period during which everyone has -a chance to challenge the result as invalid one. Submitter of -the result needs to be in the sortition pool and if the result -gets challenged, the submitter will get slashed. - -### hasDkgTimedOut - -```solidity -function hasDkgTimedOut(struct BeaconDkg.Data self) internal view returns (bool) -``` - -Checks if DKG timed out. The DKG timeout period includes time required -for off-chain protocol execution and time for the result publication. -After this time a result cannot be submitted and DKG can be notified -about the timeout. DKG period is adjusted by result submission -offset that include blocks that were mined while invalid result -has been registered until it got challenged. - -#### Return Values - -| Name | Type | Description | -| ---- | ---- | ----------- | -| [0] | bool | True if DKG timed out, false otherwise. | - -### notifyTimeout - -```solidity -function notifyTimeout(struct BeaconDkg.Data self) internal -``` - -Notifies about DKG timeout. - -### notifySeedTimedOut - -```solidity -function notifySeedTimedOut(struct BeaconDkg.Data self) internal -``` - -Notifies about the seed was not delivered and restores the -initial DKG state (IDLE). - -### approveResult - -```solidity -function approveResult(struct BeaconDkg.Data self, struct BeaconDkg.Result result) external returns (uint32[] misbehavedMembers) -``` - -Approves DKG result. Can be called when the challenge period for -the submitted result is finished. Considers the submitted result -as valid. For the first `submitterPrecedencePeriodLength` -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. - -Can be called after a challenge period for the submitted result. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| self | struct BeaconDkg.Data | | -| result | struct BeaconDkg.Result | Result to approve. Must match the submitted result stored during `submitResult`. | - -#### Return Values - -| Name | Type | Description | -| ---- | ---- | ----------- | -| misbehavedMembers | uint32[] | Identifiers of members who misbehaved during DKG. | - -### challengeResult - -```solidity -function challengeResult(struct BeaconDkg.Data self, struct BeaconDkg.Result result) external returns (bytes32 maliciousResultHash, uint32 maliciousSubmitter) -``` - -Challenges DKG result. If the submitted result is proved to be -invalid it reverts the DKG back to the result submission phase. - -Can be called during a challenge period for the submitted result. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| self | struct BeaconDkg.Data | | -| result | struct BeaconDkg.Result | Result to challenge. Must match the submitted result stored during `submitResult`. | - -#### Return Values - -| Name | Type | Description | -| ---- | ---- | ----------- | -| maliciousResultHash | bytes32 | Hash of the malicious result. | -| maliciousSubmitter | uint32 | Identifier of the malicious submitter. | - -### requireChallengeExtraGas - -```solidity -function requireChallengeExtraGas(struct BeaconDkg.Data self) internal view -``` - -Due to EIP150, 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 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 BeaconDkgValidator and TokenStaking -contracts inside a try-catch. - -### setParameters - -```solidity -function setParameters(struct BeaconDkg.Data self, uint256 _resultChallengePeriodLength, uint256 _resultChallengeExtraGas, uint256 _resultSubmissionTimeout, uint256 _submitterPrecedencePeriodLength) internal -``` - -Updates DKG-related parameters - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| self | struct BeaconDkg.Data | | -| _resultChallengePeriodLength | uint256 | New value of the result challenge period length. It is the number of blocks for which a DKG result can be challenged. | -| _resultChallengeExtraGas | uint256 | New value of the result challenge extra gas. It is the extra gas required to be left at the end of the challenge DKG result transaction. | -| _resultSubmissionTimeout | uint256 | New value of the result submission timeout in seconds. It is a timeout for a group to provide a DKG result. | -| _submitterPrecedencePeriodLength | uint256 | New value of the submitter precedence period length in blocks. It is the time during which only the original DKG result submitter can approve it. | - -### complete - -```solidity -function complete(struct BeaconDkg.Data self) internal -``` - -Completes DKG by cleaning up state. - -Should be called after DKG times out or a result is approved. - -## BeaconInactivity - -### Claim - -```solidity -struct Claim { - uint64 groupId; - uint256[] inactiveMembersIndices; - bytes signatures; - uint256[] signingMembersIndices; -} -``` - -### groupThreshold - -```solidity -uint256 groupThreshold -``` - -The minimum number of 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 BeaconInactivity.Claim claim, bytes groupPubKey, 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. - -Group members hash is validated upstream in -RandomBeacon.notifyOperatorInactivity() - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| sortitionPool | contract SortitionPool | Sortition pool reference | -| claim | struct BeaconInactivity.Claim | Inactivity claim | -| groupPubKey | bytes | Public key of the group raising the claim | -| nonce | uint256 | Current nonce for group 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 | - -## BytesLib - -### concatStorage - -```solidity -function concatStorage(bytes _preBytes, bytes _postBytes) internal -``` - -### equalStorage - -```solidity -function equalStorage(bytes _preBytes, bytes _postBytes) internal view returns (bool) -``` - -### concat - -```solidity -function concat(bytes _preBytes, bytes _postBytes) internal pure returns (bytes) -``` - -### slice - -```solidity -function slice(bytes _bytes, uint256 _start, uint256 _length) internal pure returns (bytes res) -``` - -### toAddress - -```solidity -function toAddress(bytes _bytes, uint256 _start) internal pure returns (address) -``` - -### toUint8 - -```solidity -function toUint8(bytes _bytes, uint256 _start) internal pure returns (uint8) -``` - -### toUint - -```solidity -function toUint(bytes _bytes, uint256 _start) internal pure returns (uint256) -``` - -### equal - -```solidity -function equal(bytes _preBytes, bytes _postBytes) internal pure returns (bool) -``` - -### toBytes32 - -```solidity -function toBytes32(bytes _source) internal pure returns (bytes32 result) -``` - -### keccak256Slice - -```solidity -function keccak256Slice(bytes _bytes, uint256 _start, uint256 _length) internal pure returns (bytes32 result) -``` - -## Callback - -Library for handling calls to random beacon consumer. - -### Data - -```solidity -struct Data { - contract IRandomBeaconConsumer callbackContract; -} -``` - -### CallbackFailed - -```solidity -event CallbackFailed(uint256 entry, uint256 entrySubmittedBlock) -``` - -### setCallbackContract - -```solidity -function setCallbackContract(struct Callback.Data self, contract IRandomBeaconConsumer callbackContract) internal -``` - -Sets callback contract. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| self | struct Callback.Data | | -| callbackContract | contract IRandomBeaconConsumer | Callback contract. | - -### executeCallback - -```solidity -function executeCallback(struct Callback.Data self, uint256 entry, uint256 callbackGasLimit) internal -``` - -Executes consumer specified callback for the relay entry request. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| self | struct Callback.Data | | -| entry | uint256 | The generated random number. | -| callbackGasLimit | uint256 | Callback gas limit. | - -## Groups - -This library is used as a registry of created groups. - -This library should be used along with DKG library that ensures linear -groups creation (only one group creation happens at a time). A candidate -group has to be popped or activated before adding a new candidate group. - -### Group - -```solidity -struct Group { - bytes groupPubKey; - uint256 registrationBlockNumber; - bytes32 membersHash; - bool terminated; -} -``` - -### Data - -```solidity -struct Data { - mapping(bytes32 => struct Groups.Group) groupsData; - bytes32[] groupsRegistry; - uint64[] activeTerminatedGroups; - uint64 expiredGroupOffset; - uint256 groupLifetime; -} -``` - -### GroupRegistered - -```solidity -event GroupRegistered(uint64 groupId, bytes groupPubKey) -``` - -### validatePublicKey - -```solidity -function validatePublicKey(struct Groups.Data self, bytes groupPubKey) internal view -``` - -Performs preliminary validation of a new group public key. -The group public key must be unique and have 128 bytes in length. -If the validation fails, the function reverts. This function -must be called first for a public key of a group added with -`addGroup` function. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| self | struct Groups.Data | | -| groupPubKey | bytes | Candidate group public key | - -### addGroup - -```solidity -function addGroup(struct Groups.Data self, bytes groupPubKey, bytes32 membersHash) internal -``` - -Adds a new candidate group. The group is stored with group public -key and group members, but is not yet activated. - -The group members list is stored with all misbehaved members filtered out. -The code calling this function should ensure that the number of -candidate (not activated) groups is never more than one. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| self | struct Groups.Data | | -| groupPubKey | bytes | Generated candidate group public key | -| membersHash | bytes32 | Keccak256 hash of members that actively took part in DKG. | - -### expireOldGroups - -```solidity -function expireOldGroups(struct Groups.Data self) internal -``` - -Goes through groups starting from the oldest one that is still -active and checks if it hasn't expired. If so, updates the information -about expired groups so that all expired groups are marked as such. - -### terminateGroup - -```solidity -function terminateGroup(struct Groups.Data self, uint64 groupId) internal -``` - -Terminates group with the provided index. Reverts if the group -is already terminated. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| self | struct Groups.Data | | -| groupId | uint64 | Index in the groupRegistry array. | - -### selectGroup - -```solidity -function selectGroup(struct Groups.Data self, uint256 seed) internal returns (uint64) -``` - -Returns an index of a randomly selected active group. Terminated -and expired groups are not considered as active. -Before new group is selected, information about expired groups -is updated. At least one active group needs to be present for this -function to succeed. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| self | struct Groups.Data | | -| seed | uint256 | Random number used as a group selection seed. | - -### setGroupLifetime - -```solidity -function setGroupLifetime(struct Groups.Data self, uint256 lifetime) internal -``` - -Setter for group lifetime. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| self | struct Groups.Data | | -| lifetime | uint256 | Lifetime of a group in blocks. | - -### isGroupTerminated - -```solidity -function isGroupTerminated(struct Groups.Data self, uint64 groupId) internal view returns (bool) -``` - -Checks if group with the given index is terminated. - -### groupLifetimeOf - -```solidity -function groupLifetimeOf(struct Groups.Data self, bytes32 groupPubKeyHash) internal view returns (uint256) -``` - -Gets the cutoff time until which the given group is considered -to be active assuming it hasn't been terminated before. - -### isGroupActive - -```solidity -function isGroupActive(struct Groups.Data self, uint64 groupId) internal view returns (bool) -``` - -Checks if group with the given index is active and non-terminated. - -### getGroup - -```solidity -function getGroup(struct Groups.Data self, uint64 groupId) internal view returns (struct Groups.Group) -``` - -### getGroup - -```solidity -function getGroup(struct Groups.Data self, bytes groupPubKey) internal view returns (struct Groups.Group) -``` - -### numberOfActiveGroups - -```solidity -function numberOfActiveGroups(struct Groups.Data self) internal view returns (uint64) -``` - -Gets the number of active groups. Expired and terminated -groups are not counted as active. - -### shiftByExpiredGroups - -```solidity -function shiftByExpiredGroups(struct Groups.Data self, uint64 selectedIndex) internal view returns (uint64) -``` - -Evaluates the shift of a selected group index based on the number -of expired groups. - -### shiftByTerminatedGroups - -```solidity -function shiftByTerminatedGroups(struct Groups.Data self, uint64 selectedIndex) internal view returns (uint64) -``` - -Evaluates the shift of a selected group index based on the number -of non-expired but terminated groups. - -## ModUtils - -### modExp - -```solidity -function modExp(uint256 base, uint256 exponent, uint256 p) internal view returns (uint256 o) -``` - -Wraps the modular exponent pre-compile introduced in Byzantium. -Returns base^exponent mod p. - -### modSqrt - -```solidity -function modSqrt(uint256 a, uint256 p) internal view returns (uint256) -``` - -Calculates and returns the square root of a mod p if such a square -root exists. The modulus p must be an odd prime. If a square root -does not exist, function returns 0. - -### legendre - -```solidity -function legendre(uint256 a, uint256 p) internal view returns (int256) -``` - -Calculates the Legendre symbol of the given a mod p. - -#### Return Values - -| Name | Type | Description | -| ---- | ---- | ----------- | -| [0] | int256 | Returns 1 if a is a quadratic residue mod p, -1 if it is a non-quadratic residue, and 0 if a is 0. | - -## Relay - -### Data - -```solidity -struct Data { - uint64 requestCount; - uint64 currentRequestID; - uint64 currentRequestGroupID; - uint64 currentRequestStartBlock; - struct AltBn128.G1Point previousEntry; - uint32 relayEntrySoftTimeout; - uint32 relayEntryHardTimeout; - uint96 relayEntrySubmissionFailureSlashingAmount; -} -``` - -### relaySeed - -```solidity -bytes relaySeed -``` - -Seed used as the first relay entry value. -It's a G1 point G * PI = -G * 31415926535897932384626433832795028841971693993751058209749445923078164062862 -Where G is the generator of G1 abstract cyclic group. - -### RelayEntryRequested - -```solidity -event RelayEntryRequested(uint256 requestId, uint64 groupId, bytes previousEntry) -``` - -### RelayEntrySubmitted - -```solidity -event RelayEntrySubmitted(uint256 requestId, address submitter, bytes entry) -``` - -### RelayEntryTimedOut - -```solidity -event RelayEntryTimedOut(uint256 requestId, uint64 terminatedGroupId) -``` - -### initSeedEntry - -```solidity -function initSeedEntry(struct Relay.Data self) internal -``` - -Initializes the very first `previousEntry` with an initial -`relaySeed` value. Can be performed only once. - -### requestEntry - -```solidity -function requestEntry(struct Relay.Data self, uint64 groupId) internal -``` - -Creates a request to generate a new relay entry, which will -include a random number (by signing the previous entry's -random number). - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| self | struct Relay.Data | | -| groupId | uint64 | Identifier of the group chosen to handle the request. | - -### submitEntryBeforeSoftTimeout - -```solidity -function submitEntryBeforeSoftTimeout(struct Relay.Data self, bytes entry, bytes groupPubKey) internal -``` - -Creates a new relay entry. Gas-optimized version that can be -called only before the soft timeout. This should be the majority -of cases. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| self | struct Relay.Data | | -| entry | bytes | Group BLS signature over the previous entry. | -| groupPubKey | bytes | Public key of the group which signed the relay entry. | - -### submitEntry - -```solidity -function submitEntry(struct Relay.Data self, bytes entry, bytes groupPubKey) internal returns (uint96) -``` - -Creates a new relay entry. Can be called at any time. -In case the soft timeout has not been exceeded, it is more -gas-efficient to call the second variation of `submitEntry`. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| self | struct Relay.Data | | -| entry | bytes | Group BLS signature over the previous entry. | -| groupPubKey | bytes | Public key of the group which signed the relay entry. | - -#### Return Values - -| Name | Type | Description | -| ---- | ---- | ----------- | -| [0] | uint96 | slashingAmount Amount by which group members should be slashed in case the relay entry was submitted after the soft timeout. The value is zero if entry was submitted on time. | - -### _submitEntry - -```solidity -function _submitEntry(struct Relay.Data self, bytes entry, bytes groupPubKey) internal -``` - -### calculateSlashingAmount - -```solidity -function calculateSlashingAmount(struct Relay.Data self) internal view returns (uint96) -``` - -Calculates the slashing amount for all group members. - -Must be used when a soft timeout was hit. - -#### Return Values - -| Name | Type | Description | -| ---- | ---- | ----------- | -| [0] | uint96 | Amount by which group members should be slashed in case the relay entry was submitted after the soft timeout. | - -### setTimeouts - -```solidity -function setTimeouts(struct Relay.Data self, uint256 _relayEntrySoftTimeout, uint256 _relayEntryHardTimeout) internal -``` - -Updates relay-related parameters - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| self | struct Relay.Data | | -| _relayEntrySoftTimeout | uint256 | New relay entry soft timeout value. It is the time in blocks during which a result is expected to be submitted so that the group is not slashed. | -| _relayEntryHardTimeout | uint256 | New relay entry hard timeout value. It is the time in blocks for a group to submit the relay entry before slashing for the full slashing amount happens. | - -### setRelayEntrySubmissionFailureSlashingAmount - -```solidity -function setRelayEntrySubmissionFailureSlashingAmount(struct Relay.Data self, uint96 newRelayEntrySubmissionFailureSlashingAmount) internal -``` - -Set relayEntrySubmissionFailureSlashingAmount parameter. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| self | struct Relay.Data | | -| newRelayEntrySubmissionFailureSlashingAmount | uint96 | New value of the parameter. | - -### retryOnEntryTimeout - -```solidity -function retryOnEntryTimeout(struct Relay.Data self, uint64 newGroupId) internal -``` - -Retries the current relay request in case a relay entry -timeout was reported. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| self | struct Relay.Data | | -| newGroupId | uint64 | ID of the group chosen to retry the current request. | - -### cleanupOnEntryTimeout - -```solidity -function cleanupOnEntryTimeout(struct Relay.Data self) internal -``` - -Cleans up the current relay request in case a relay entry -timeout was reported. - -### isRequestInProgress - -```solidity -function isRequestInProgress(struct Relay.Data self) internal view returns (bool) -``` - -Returns whether a relay entry request is currently in progress. - -#### Return Values - -| Name | Type | Description | -| ---- | ---- | ----------- | -| [0] | bool | True if there is a request in progress. False otherwise. | - -### hasRequestTimedOut - -```solidity -function hasRequestTimedOut(struct Relay.Data self) internal view returns (bool) -``` - -Returns whether the current relay request has timed out. - -#### Return Values - -| Name | Type | Description | -| ---- | ---- | ----------- | -| [0] | bool | True if the request timed out. False otherwise. | - -### softTimeoutBlock - -```solidity -function softTimeoutBlock(struct Relay.Data self) internal view returns (uint256) -``` - -Calculates soft timeout block for the pending relay request. - -#### Return Values - -| Name | Type | Description | -| ---- | ---- | ----------- | -| [0] | uint256 | The soft timeout block | - diff --git a/docs/app-development/random-beacon/random-beacon-api/generated-docs/libraries/AltBn128.md b/docs/app-development/random-beacon/random-beacon-api/generated-docs/libraries/AltBn128.md new file mode 100644 index 0000000..e576c63 --- /dev/null +++ b/docs/app-development/random-beacon/random-beacon-api/generated-docs/libraries/AltBn128.md @@ -0,0 +1,317 @@ +# Solidity API + +## AltBn128 + +Implementations of common elliptic curve operations on Ethereum's +(poorly named) alt_bn128 curve. Whenever possible, use post-Byzantium +pre-compiled contracts to offset gas costs. Note that these +pre-compiles might not be available on all (eg private) chains. + +### G1Point + +```solidity +struct G1Point { + uint256 x; + uint256 y; +} +``` + +### gfP2 + +```solidity +struct gfP2 { + uint256 x; + uint256 y; +} +``` + +### G2Point + +```solidity +struct G2Point { + struct AltBn128.gfP2 x; + struct AltBn128.gfP2 y; +} +``` + +### p + +```solidity +uint256 p +``` + +### g1x + +```solidity +uint256 g1x +``` + +Gets generator of G1 group. +Taken from go-ethereum/crypto/bn256/cloudflare/curve.go + +### g1y + +```solidity +uint256 g1y +``` + +### g2xx + +```solidity +uint256 g2xx +``` + +Gets generator of G2 group. +Taken from go-ethereum/crypto/bn256/cloudflare/twist.go + +### g2xy + +```solidity +uint256 g2xy +``` + +### g2yx + +```solidity +uint256 g2yx +``` + +### g2yy + +```solidity +uint256 g2yy +``` + +### twistBx + +```solidity +uint256 twistBx +``` + +Gets twist curve B constant. +Taken from go-ethereum/crypto/bn256/cloudflare/twist.go + +### twistBy + +```solidity +uint256 twistBy +``` + +### hexRootX + +```solidity +uint256 hexRootX +``` + +Gets root of the point where x and y are equal. + +### hexRootY + +```solidity +uint256 hexRootY +``` + +### g1YFromX + +```solidity +function g1YFromX(uint256 x) internal view returns (uint256) +``` + +g1YFromX computes a Y value for a G1 point based on an X value. +This computation is simply evaluating the curve equation for Y on a +given X, and allows a point on the curve to be represented by just +an X value + a sign bit. + +### g1HashToPoint + +```solidity +function g1HashToPoint(bytes m) internal view returns (struct AltBn128.G1Point) +``` + +Hash a byte array message, m, and map it deterministically to a +point on G1. Note that this approach was chosen for its simplicity +and lower gas cost on the EVM, rather than good distribution of +points on G1. + +### g1Decompress + +```solidity +function g1Decompress(bytes32 m) internal view returns (struct AltBn128.G1Point) +``` + +Decompress a point on G1 from a single uint256. + +### g1Add + +```solidity +function g1Add(struct AltBn128.G1Point a, struct AltBn128.G1Point b) internal view returns (struct AltBn128.G1Point c) +``` + +Wraps the point addition pre-compile introduced in Byzantium. +Returns the sum of two points on G1. Revert if the provided points +are not on the curve. + +### isG1PointOnCurve + +```solidity +function isG1PointOnCurve(struct AltBn128.G1Point point) internal view returns (bool) +``` + +Returns true if G1 point is on the curve. + +### scalarMultiply + +```solidity +function scalarMultiply(struct AltBn128.G1Point p_1, uint256 scalar) internal view returns (struct AltBn128.G1Point p_2) +``` + +Wraps the scalar point multiplication pre-compile introduced in +Byzantium. The result of a point from G1 multiplied by a scalar +should match the point added to itself the same number of times. +Revert if the provided point isn't on the curve. + +### pairing + +```solidity +function pairing(struct AltBn128.G1Point p1, struct AltBn128.G2Point p2, struct AltBn128.G1Point p3, struct AltBn128.G2Point p4) internal view returns (bool result) +``` + +Wraps the pairing check pre-compile introduced in Byzantium. +Returns the result of a pairing check of 2 pairs +(G1 p1, G2 p2) (G1 p3, G2 p4) + +### getP + +```solidity +function getP() internal pure returns (uint256) +``` + +### g1 + +```solidity +function g1() internal pure returns (struct AltBn128.G1Point) +``` + +### g2 + +```solidity +function g2() internal pure returns (struct AltBn128.G2Point) +``` + +### g2YFromX + +```solidity +function g2YFromX(struct AltBn128.gfP2 _x) internal pure returns (struct AltBn128.gfP2 y) +``` + +g2YFromX computes a Y value for a G2 point based on an X value. +This computation is simply evaluating the curve equation for Y on a +given X, and allows a point on the curve to be represented by just +an X value + a sign bit. + +### g1Compress + +```solidity +function g1Compress(struct AltBn128.G1Point point) internal pure returns (bytes32) +``` + +Compress a point on G1 to a single uint256 for serialization. + +### g2Compress + +```solidity +function g2Compress(struct AltBn128.G2Point point) internal pure returns (bytes) +``` + +Compress a point on G2 to a pair of uint256 for serialization. + +### g1Unmarshal + +```solidity +function g1Unmarshal(bytes m) internal pure returns (struct AltBn128.G1Point) +``` + +Unmarshals a point on G1 from bytes in an uncompressed form. + +### g1Marshal + +```solidity +function g1Marshal(struct AltBn128.G1Point point) internal pure returns (bytes) +``` + +Marshals a point on G1 to bytes form. + +### g2Unmarshal + +```solidity +function g2Unmarshal(bytes m) internal pure returns (struct AltBn128.G2Point) +``` + +Unmarshals a point on G2 from bytes in an uncompressed form. + +### g2Decompress + +```solidity +function g2Decompress(bytes m) internal pure returns (struct AltBn128.G2Point) +``` + +Decompress a point on G2 from a pair of uint256. + +### gfP2Add + +```solidity +function gfP2Add(struct AltBn128.gfP2 a, struct AltBn128.gfP2 b) internal pure returns (struct AltBn128.gfP2) +``` + +Returns the sum of two gfP2 field elements. + +### gfP2Multiply + +```solidity +function gfP2Multiply(struct AltBn128.gfP2 a, struct AltBn128.gfP2 b) internal pure returns (struct AltBn128.gfP2) +``` + +Returns multiplication of two gfP2 field elements. + +### gfP2Pow + +```solidity +function gfP2Pow(struct AltBn128.gfP2 _a, uint256 _exp) internal pure returns (struct AltBn128.gfP2 result) +``` + +Returns gfP2 element to the power of the provided exponent. + +### gfP2Square + +```solidity +function gfP2Square(struct AltBn128.gfP2 a) internal pure returns (struct AltBn128.gfP2) +``` + +### gfP2Cube + +```solidity +function gfP2Cube(struct AltBn128.gfP2 a) internal pure returns (struct AltBn128.gfP2) +``` + +### gfP2CubeAddTwistB + +```solidity +function gfP2CubeAddTwistB(struct AltBn128.gfP2 a) internal pure returns (struct AltBn128.gfP2) +``` + +### g2X2y + +```solidity +function g2X2y(struct AltBn128.gfP2 x, struct AltBn128.gfP2 y) internal pure returns (bool) +``` + +Returns true if G2 point's y^2 equals x. + +### isG2PointOnCurve + +```solidity +function isG2PointOnCurve(struct AltBn128.G2Point point) internal pure returns (bool) +``` + +Returns true if G2 point is on the curve. + diff --git a/docs/app-development/random-beacon/random-beacon-api/generated-docs/libraries/BLS.md b/docs/app-development/random-beacon/random-beacon-api/generated-docs/libraries/BLS.md new file mode 100644 index 0000000..b1ec2ee --- /dev/null +++ b/docs/app-development/random-beacon/random-beacon-api/generated-docs/libraries/BLS.md @@ -0,0 +1,45 @@ +# Solidity API + +## BLS + +Library for verification of 2-pairing-check BLS signatures, including +basic, aggregated, or reconstructed threshold BLS signatures, generated +using the AltBn128 curve. + +### sign + +```solidity +function sign(bytes message, uint256 secretKey) external view returns (bytes) +``` + +Creates a signature over message using the provided secret key. + +### verifyBytes + +```solidity +function verifyBytes(bytes publicKey, bytes message, bytes signature) external view returns (bool) +``` + +Wraps the functionality of BLS.verify, but hashes a message to +a point on G1 and marshal to bytes first to allow raw bytes +verification. + +### verify + +```solidity +function verify(bytes publicKey, bytes message, bytes signature) public view returns (bool) +``` + +Verify performs the pairing operation to check if the signature +is correct for the provided message and the corresponding public +key. Public key must be a valid point on G2 curve in an +uncompressed format. Message must be a valid point on G1 curve in +an uncompressed format. Signature must be a valid point on G1 +curve in an uncompressed format. + +### _verify + +```solidity +function _verify(struct AltBn128.G2Point publicKey, struct AltBn128.G1Point message, struct AltBn128.G1Point signature) public view returns (bool) +``` + diff --git a/docs/app-development/random-beacon/random-beacon-api/generated-docs/libraries/BeaconAuthorization.md b/docs/app-development/random-beacon/random-beacon-api/generated-docs/libraries/BeaconAuthorization.md new file mode 100644 index 0000000..01caa9a --- /dev/null +++ b/docs/app-development/random-beacon/random-beacon-api/generated-docs/libraries/BeaconAuthorization.md @@ -0,0 +1,291 @@ +# Solidity API + +## BeaconAuthorization + +Library managing the state of stake authorizations for the operator +contract and the presence of operators in the sortition +pool based on the stake authorized for them. + +### Parameters + +```solidity +struct Parameters { + uint96 minimumAuthorization; + uint64 authorizationDecreaseDelay; + uint64 authorizationDecreaseChangePeriod; +} +``` + +### AuthorizationDecrease + +```solidity +struct AuthorizationDecrease { + uint96 decreasingBy; + uint64 decreasingAt; +} +``` + +### Data + +```solidity +struct Data { + struct BeaconAuthorization.Parameters parameters; + mapping(address => address) stakingProviderToOperator; + mapping(address => address) operatorToStakingProvider; + mapping(address => struct BeaconAuthorization.AuthorizationDecrease) pendingDecreases; +} +``` + +### 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) +``` + +### setParameters + +```solidity +function setParameters(struct BeaconAuthorization.Data self, uint96 _minimumAuthorization, uint64 _authorizationDecreaseDelay, uint64 _authorizationDecreaseChangePeriod) external +``` + +Updates authorization-related parameters. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| self | struct BeaconAuthorization.Data | | +| _minimumAuthorization | uint96 | New value of the minimum authorization for the beacon. Without at least the minimum authorization, staking provider is not eligible to join and operate in the network. | +| _authorizationDecreaseDelay | uint64 | New value of the authorization decrease delay. It is the time in seconds that needs to pass between the time authorization decrease is requested and the time the authorization decrease can be approved, no matter the authorization decrease amount. | +| _authorizationDecreaseChangePeriod | uint64 | New value of the authorization decrease change period. It is the time in seconds, before authorization decrease delay end, during which the pending authorization decrease request can be overwritten. If set to 0, pending authorization decrease request can not be overwritten until the entire `authorizationDecreaseDelay` ends. If set to value equal `authorizationDecreaseDelay`, request can always be overwritten. | + +### registerOperator + +```solidity +function registerOperator(struct BeaconAuthorization.Data self, address operator) public +``` + +Used by staking provider to set operator address that will +operate a 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. + +### authorizationIncreased + +```solidity +function authorizationIncreased(struct BeaconAuthorization.Data self, address stakingProvider, uint96 fromAmount, uint96 toAmount) external +``` + +Used by T staking contract to inform the beacon 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`. + +Should only be callable by T staking contract. + +### authorizationDecreaseRequested + +```solidity +function authorizationDecreaseRequested(struct BeaconAuthorization.Data self, address stakingProvider, uint96 fromAmount, uint96 toAmount) public +``` + +Used by T staking contract to inform the beacon 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. + +Reverts if another authorization decrease request is pending for +the staking provider and not enough time passed since the +original request (see `authorizationDecreaseChangePeriod`). + +If the operator is not known (`registerOperator` was not called) +it lets to `approveAuthorizationDecrease` immediately. 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, but only if enough time passed since the original +request. Otherwise, the function reverts. + +Should only be callable by T staking contract. + +### approveAuthorizationDecrease + +```solidity +function approveAuthorizationDecrease(struct BeaconAuthorization.Data self, contract IStaking tokenStaking, address stakingProvider) public +``` + +Approves the previously registered authorization decrease +request. Reverts if authorization decrease delay have not passed +yet or if the authorization decrease was not requested for the +given staking provider. + +### involuntaryAuthorizationDecrease + +```solidity +function involuntaryAuthorizationDecrease(struct BeaconAuthorization.Data self, contract IStaking tokenStaking, contract SortitionPool sortitionPool, address stakingProvider, uint96 fromAmount, uint96 toAmount) external +``` + +Used by T staking contract to inform the beacon 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. + +Should only be callable by T staking contract. + +### joinSortitionPool + +```solidity +function joinSortitionPool(struct BeaconAuthorization.Data self, contract IStaking tokenStaking, contract SortitionPool sortitionPool) public +``` + +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 the beacon. 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(struct BeaconAuthorization.Data self, contract IStaking tokenStaking, contract SortitionPool sortitionPool, address operator) public +``` + +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. + +### isOperatorUpToDate + +```solidity +function isOperatorUpToDate(struct BeaconAuthorization.Data self, contract IStaking tokenStaking, contract SortitionPool sortitionPool, address operator) external view returns (bool) +``` + +Checks if the operator's authorized stake is in sync with +operator's weight in the sortition pool. +If the operator is not in the sortition pool and their +authorized stake is non-zero, function returns false. + +### eligibleStake + +```solidity +function eligibleStake(struct BeaconAuthorization.Data self, contract IStaking tokenStaking, address stakingProvider) external view returns (uint96) +``` + +Returns the current value of the staking provider's eligible +stake. Eligible stake is defined as the currently authorized +stake minus the pending authorization decrease. Eligible stake +is what is used for operator's weight in the pool. If the +authorized stake minus the pending authorization decrease is +below the minimum authorization, eligible stake is 0. + +This function can be exposed to the public in contrast to the +second variant accepting `decreasingBy` as a parameter. + +### eligibleStake + +```solidity +function eligibleStake(struct BeaconAuthorization.Data self, contract IStaking tokenStaking, address stakingProvider, uint96 decreasingBy) public view returns (uint96) +``` + +Returns the current value of the staking provider's eligible +stake. Eligible stake is defined as the currently authorized +stake minus the pending authorization decrease. Eligible stake +is what is used for operator's weight in the pool. If the +authorized stake minus the pending authorization decrease is +below the minimum authorization, eligible stake is 0. + +This function is not intended to be exposes to the public. +`decreasingBy` must be fetched from `pendingDecreases` mapping and +it is passed as a parameter to optimize gas usage of functions that +call `eligibleStake` and need to use `AuthorizationDecrease` +fetched from `pendingDecreases` for some additional logic. + +### pendingAuthorizationDecrease + +```solidity +function pendingAuthorizationDecrease(struct BeaconAuthorization.Data self, address stakingProvider) public view returns (uint96) +``` + +Returns the amount of stake that is pending authorization +decrease for the given staking provider. If no authorization +decrease has been requested, returns zero. + +### remainingAuthorizationDecreaseDelay + +```solidity +function remainingAuthorizationDecreaseDelay(struct BeaconAuthorization.Data self, address stakingProvider) external view returns (uint64) +``` + +Returns the remaining time in seconds that needs to pass before +the requested authorization decrease can be approved. +If the sortition pool state was not updated yet by the operator +after requesting the authorization decrease, returns +`type(uint64).max`. + diff --git a/docs/app-development/random-beacon/random-beacon-api/generated-docs/libraries/BeaconDkg.md b/docs/app-development/random-beacon/random-beacon-api/generated-docs/libraries/BeaconDkg.md new file mode 100644 index 0000000..afcdd1a --- /dev/null +++ b/docs/app-development/random-beacon/random-beacon-api/generated-docs/libraries/BeaconDkg.md @@ -0,0 +1,304 @@ +# Solidity API + +## BeaconDkg + +### Parameters + +```solidity +struct Parameters { + uint256 resultChallengePeriodLength; + uint256 resultChallengeExtraGas; + uint256 resultSubmissionTimeout; + uint256 submitterPrecedencePeriodLength; +} +``` + +### Data + +```solidity +struct Data { + contract SortitionPool sortitionPool; + contract BeaconDkgValidator dkgValidator; + struct BeaconDkg.Parameters parameters; + uint256 startBlock; + uint256 seed; + uint256 resultSubmissionStartBlockOffset; + bytes32 submittedResultHash; + uint256 submittedResultBlock; +} +``` + +### Result + +```solidity +struct Result { + uint256 submitterMemberIndex; + bytes groupPubKey; + uint8[] misbehavedMembersIndices; + bytes signatures; + uint256[] signingMembersIndices; + uint32[] members; + bytes32 membersHash; +} +``` + +### State + +```solidity +enum State { + IDLE, + AWAITING_SEED, + KEY_GENERATION, + AWAITING_RESULT, + CHALLENGE +} +``` + +### groupSize + +```solidity +uint256 groupSize +``` + +Size of a group in the threshold relay. + +### offchainDkgTime + +```solidity +uint256 offchainDkgTime +``` + +Time in blocks after which DKG result is complete and ready to be + +### DkgStarted + +```solidity +event DkgStarted(uint256 seed) +``` + +### DkgResultSubmitted + +```solidity +event DkgResultSubmitted(bytes32 resultHash, uint256 seed, struct BeaconDkg.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() +``` + +### init + +```solidity +function init(struct BeaconDkg.Data self, contract SortitionPool _sortitionPool, contract BeaconDkgValidator _dkgValidator) internal +``` + +Initializes SortitionPool and DKGValidator addresses. +Can be performed only once. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| self | struct BeaconDkg.Data | | +| _sortitionPool | contract SortitionPool | Sortition Pool reference | +| _dkgValidator | contract BeaconDkgValidator | DKGValidator reference | + +### currentState + +```solidity +function currentState(struct BeaconDkg.Data self) internal view returns (enum BeaconDkg.State state) +``` + +Determines the current state of group creation. It doesn't take +timeouts into consideration. The timeouts should be tracked and +notified separately. + +### lockState + +```solidity +function lockState(struct BeaconDkg.Data self) internal +``` + +Locks the sortition pool and starts awaiting for the +group creation seed. + +### start + +```solidity +function start(struct BeaconDkg.Data self, uint256 seed) internal +``` + +### submitResult + +```solidity +function submitResult(struct BeaconDkg.Data self, struct BeaconDkg.Result result) external +``` + +Allows to submit a DKG result. The submitted result does not go +through a validation and before it gets accepted, it needs to +wait through the challenge period during which everyone has +a chance to challenge the result as invalid one. Submitter of +the result needs to be in the sortition pool and if the result +gets challenged, the submitter will get slashed. + +### hasDkgTimedOut + +```solidity +function hasDkgTimedOut(struct BeaconDkg.Data self) internal view returns (bool) +``` + +Checks if DKG timed out. The DKG timeout period includes time required +for off-chain protocol execution and time for the result publication. +After this time a result cannot be submitted and DKG can be notified +about the timeout. DKG period is adjusted by result submission +offset that include blocks that were mined while invalid result +has been registered until it got challenged. + +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +| [0] | bool | True if DKG timed out, false otherwise. | + +### notifyTimeout + +```solidity +function notifyTimeout(struct BeaconDkg.Data self) internal +``` + +Notifies about DKG timeout. + +### notifySeedTimedOut + +```solidity +function notifySeedTimedOut(struct BeaconDkg.Data self) internal +``` + +Notifies about the seed was not delivered and restores the +initial DKG state (IDLE). + +### approveResult + +```solidity +function approveResult(struct BeaconDkg.Data self, struct BeaconDkg.Result result) external returns (uint32[] misbehavedMembers) +``` + +Approves DKG result. Can be called when the challenge period for +the submitted result is finished. Considers the submitted result +as valid. For the first `submitterPrecedencePeriodLength` +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. + +Can be called after a challenge period for the submitted result. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| self | struct BeaconDkg.Data | | +| result | struct BeaconDkg.Result | Result to approve. Must match the submitted result stored during `submitResult`. | + +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +| misbehavedMembers | uint32[] | Identifiers of members who misbehaved during DKG. | + +### challengeResult + +```solidity +function challengeResult(struct BeaconDkg.Data self, struct BeaconDkg.Result result) external returns (bytes32 maliciousResultHash, uint32 maliciousSubmitter) +``` + +Challenges DKG result. If the submitted result is proved to be +invalid it reverts the DKG back to the result submission phase. + +Can be called during a challenge period for the submitted result. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| self | struct BeaconDkg.Data | | +| result | struct BeaconDkg.Result | Result to challenge. Must match the submitted result stored during `submitResult`. | + +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +| maliciousResultHash | bytes32 | Hash of the malicious result. | +| maliciousSubmitter | uint32 | Identifier of the malicious submitter. | + +### requireChallengeExtraGas + +```solidity +function requireChallengeExtraGas(struct BeaconDkg.Data self) internal view +``` + +Due to EIP150, 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 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 BeaconDkgValidator and TokenStaking +contracts inside a try-catch. + +### setParameters + +```solidity +function setParameters(struct BeaconDkg.Data self, uint256 _resultChallengePeriodLength, uint256 _resultChallengeExtraGas, uint256 _resultSubmissionTimeout, uint256 _submitterPrecedencePeriodLength) internal +``` + +Updates DKG-related parameters + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| self | struct BeaconDkg.Data | | +| _resultChallengePeriodLength | uint256 | New value of the result challenge period length. It is the number of blocks for which a DKG result can be challenged. | +| _resultChallengeExtraGas | uint256 | New value of the result challenge extra gas. It is the extra gas required to be left at the end of the challenge DKG result transaction. | +| _resultSubmissionTimeout | uint256 | New value of the result submission timeout in seconds. It is a timeout for a group to provide a DKG result. | +| _submitterPrecedencePeriodLength | uint256 | New value of the submitter precedence period length in blocks. It is the time during which only the original DKG result submitter can approve it. | + +### complete + +```solidity +function complete(struct BeaconDkg.Data self) internal +``` + +Completes DKG by cleaning up state. + +Should be called after DKG times out or a result is approved. + diff --git a/docs/app-development/random-beacon/random-beacon-api/generated-docs/libraries/BeaconInactivity.md b/docs/app-development/random-beacon/random-beacon-api/generated-docs/libraries/BeaconInactivity.md new file mode 100644 index 0000000..5559944 --- /dev/null +++ b/docs/app-development/random-beacon/random-beacon-api/generated-docs/libraries/BeaconInactivity.md @@ -0,0 +1,79 @@ +# Solidity API + +## BeaconInactivity + +### Claim + +```solidity +struct Claim { + uint64 groupId; + uint256[] inactiveMembersIndices; + bytes signatures; + uint256[] signingMembersIndices; +} +``` + +### groupThreshold + +```solidity +uint256 groupThreshold +``` + +The minimum number of 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 BeaconInactivity.Claim claim, bytes groupPubKey, 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. + +Group members hash is validated upstream in +RandomBeacon.notifyOperatorInactivity() + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| sortitionPool | contract SortitionPool | Sortition pool reference | +| claim | struct BeaconInactivity.Claim | Inactivity claim | +| groupPubKey | bytes | Public key of the group raising the claim | +| nonce | uint256 | Current nonce for group 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 | + diff --git a/docs/app-development/random-beacon/random-beacon-api/generated-docs/libraries/BytesLib.md b/docs/app-development/random-beacon/random-beacon-api/generated-docs/libraries/BytesLib.md new file mode 100644 index 0000000..8ce7dc8 --- /dev/null +++ b/docs/app-development/random-beacon/random-beacon-api/generated-docs/libraries/BytesLib.md @@ -0,0 +1,64 @@ +# Solidity API + +## BytesLib + +### concatStorage + +```solidity +function concatStorage(bytes _preBytes, bytes _postBytes) internal +``` + +### equalStorage + +```solidity +function equalStorage(bytes _preBytes, bytes _postBytes) internal view returns (bool) +``` + +### concat + +```solidity +function concat(bytes _preBytes, bytes _postBytes) internal pure returns (bytes) +``` + +### slice + +```solidity +function slice(bytes _bytes, uint256 _start, uint256 _length) internal pure returns (bytes res) +``` + +### toAddress + +```solidity +function toAddress(bytes _bytes, uint256 _start) internal pure returns (address) +``` + +### toUint8 + +```solidity +function toUint8(bytes _bytes, uint256 _start) internal pure returns (uint8) +``` + +### toUint + +```solidity +function toUint(bytes _bytes, uint256 _start) internal pure returns (uint256) +``` + +### equal + +```solidity +function equal(bytes _preBytes, bytes _postBytes) internal pure returns (bool) +``` + +### toBytes32 + +```solidity +function toBytes32(bytes _source) internal pure returns (bytes32 result) +``` + +### keccak256Slice + +```solidity +function keccak256Slice(bytes _bytes, uint256 _start, uint256 _length) internal pure returns (bytes32 result) +``` + diff --git a/docs/app-development/random-beacon/random-beacon-api/generated-docs/libraries/Callback.md b/docs/app-development/random-beacon/random-beacon-api/generated-docs/libraries/Callback.md new file mode 100644 index 0000000..1dcf69a --- /dev/null +++ b/docs/app-development/random-beacon/random-beacon-api/generated-docs/libraries/Callback.md @@ -0,0 +1,51 @@ +# Solidity API + +## Callback + +Library for handling calls to random beacon consumer. + +### Data + +```solidity +struct Data { + contract IRandomBeaconConsumer callbackContract; +} +``` + +### CallbackFailed + +```solidity +event CallbackFailed(uint256 entry, uint256 entrySubmittedBlock) +``` + +### setCallbackContract + +```solidity +function setCallbackContract(struct Callback.Data self, contract IRandomBeaconConsumer callbackContract) internal +``` + +Sets callback contract. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| self | struct Callback.Data | | +| callbackContract | contract IRandomBeaconConsumer | Callback contract. | + +### executeCallback + +```solidity +function executeCallback(struct Callback.Data self, uint256 entry, uint256 callbackGasLimit) internal +``` + +Executes consumer specified callback for the relay entry request. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| self | struct Callback.Data | | +| entry | uint256 | The generated random number. | +| callbackGasLimit | uint256 | Callback gas limit. | + diff --git a/docs/app-development/random-beacon/random-beacon-api/generated-docs/libraries/Groups.md b/docs/app-development/random-beacon/random-beacon-api/generated-docs/libraries/Groups.md new file mode 100644 index 0000000..df02084 --- /dev/null +++ b/docs/app-development/random-beacon/random-beacon-api/generated-docs/libraries/Groups.md @@ -0,0 +1,203 @@ +# Solidity API + +## Groups + +This library is used as a registry of created groups. + +This library should be used along with DKG library that ensures linear +groups creation (only one group creation happens at a time). A candidate +group has to be popped or activated before adding a new candidate group. + +### Group + +```solidity +struct Group { + bytes groupPubKey; + uint256 registrationBlockNumber; + bytes32 membersHash; + bool terminated; +} +``` + +### Data + +```solidity +struct Data { + mapping(bytes32 => struct Groups.Group) groupsData; + bytes32[] groupsRegistry; + uint64[] activeTerminatedGroups; + uint64 expiredGroupOffset; + uint256 groupLifetime; +} +``` + +### GroupRegistered + +```solidity +event GroupRegistered(uint64 groupId, bytes groupPubKey) +``` + +### validatePublicKey + +```solidity +function validatePublicKey(struct Groups.Data self, bytes groupPubKey) internal view +``` + +Performs preliminary validation of a new group public key. +The group public key must be unique and have 128 bytes in length. +If the validation fails, the function reverts. This function +must be called first for a public key of a group added with +`addGroup` function. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| self | struct Groups.Data | | +| groupPubKey | bytes | Candidate group public key | + +### addGroup + +```solidity +function addGroup(struct Groups.Data self, bytes groupPubKey, bytes32 membersHash) internal +``` + +Adds a new candidate group. The group is stored with group public +key and group members, but is not yet activated. + +The group members list is stored with all misbehaved members filtered out. +The code calling this function should ensure that the number of +candidate (not activated) groups is never more than one. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| self | struct Groups.Data | | +| groupPubKey | bytes | Generated candidate group public key | +| membersHash | bytes32 | Keccak256 hash of members that actively took part in DKG. | + +### expireOldGroups + +```solidity +function expireOldGroups(struct Groups.Data self) internal +``` + +Goes through groups starting from the oldest one that is still +active and checks if it hasn't expired. If so, updates the information +about expired groups so that all expired groups are marked as such. + +### terminateGroup + +```solidity +function terminateGroup(struct Groups.Data self, uint64 groupId) internal +``` + +Terminates group with the provided index. Reverts if the group +is already terminated. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| self | struct Groups.Data | | +| groupId | uint64 | Index in the groupRegistry array. | + +### selectGroup + +```solidity +function selectGroup(struct Groups.Data self, uint256 seed) internal returns (uint64) +``` + +Returns an index of a randomly selected active group. Terminated +and expired groups are not considered as active. +Before new group is selected, information about expired groups +is updated. At least one active group needs to be present for this +function to succeed. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| self | struct Groups.Data | | +| seed | uint256 | Random number used as a group selection seed. | + +### setGroupLifetime + +```solidity +function setGroupLifetime(struct Groups.Data self, uint256 lifetime) internal +``` + +Setter for group lifetime. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| self | struct Groups.Data | | +| lifetime | uint256 | Lifetime of a group in blocks. | + +### isGroupTerminated + +```solidity +function isGroupTerminated(struct Groups.Data self, uint64 groupId) internal view returns (bool) +``` + +Checks if group with the given index is terminated. + +### groupLifetimeOf + +```solidity +function groupLifetimeOf(struct Groups.Data self, bytes32 groupPubKeyHash) internal view returns (uint256) +``` + +Gets the cutoff time until which the given group is considered +to be active assuming it hasn't been terminated before. + +### isGroupActive + +```solidity +function isGroupActive(struct Groups.Data self, uint64 groupId) internal view returns (bool) +``` + +Checks if group with the given index is active and non-terminated. + +### getGroup + +```solidity +function getGroup(struct Groups.Data self, uint64 groupId) internal view returns (struct Groups.Group) +``` + +### getGroup + +```solidity +function getGroup(struct Groups.Data self, bytes groupPubKey) internal view returns (struct Groups.Group) +``` + +### numberOfActiveGroups + +```solidity +function numberOfActiveGroups(struct Groups.Data self) internal view returns (uint64) +``` + +Gets the number of active groups. Expired and terminated +groups are not counted as active. + +### shiftByExpiredGroups + +```solidity +function shiftByExpiredGroups(struct Groups.Data self, uint64 selectedIndex) internal view returns (uint64) +``` + +Evaluates the shift of a selected group index based on the number +of expired groups. + +### shiftByTerminatedGroups + +```solidity +function shiftByTerminatedGroups(struct Groups.Data self, uint64 selectedIndex) internal view returns (uint64) +``` + +Evaluates the shift of a selected group index based on the number +of non-expired but terminated groups. + diff --git a/docs/app-development/random-beacon/random-beacon-api/generated-docs/libraries/ModUtils.md b/docs/app-development/random-beacon/random-beacon-api/generated-docs/libraries/ModUtils.md new file mode 100644 index 0000000..56828e4 --- /dev/null +++ b/docs/app-development/random-beacon/random-beacon-api/generated-docs/libraries/ModUtils.md @@ -0,0 +1,37 @@ +# Solidity API + +## ModUtils + +### modExp + +```solidity +function modExp(uint256 base, uint256 exponent, uint256 p) internal view returns (uint256 o) +``` + +Wraps the modular exponent pre-compile introduced in Byzantium. +Returns base^exponent mod p. + +### modSqrt + +```solidity +function modSqrt(uint256 a, uint256 p) internal view returns (uint256) +``` + +Calculates and returns the square root of a mod p if such a square +root exists. The modulus p must be an odd prime. If a square root +does not exist, function returns 0. + +### legendre + +```solidity +function legendre(uint256 a, uint256 p) internal view returns (int256) +``` + +Calculates the Legendre symbol of the given a mod p. + +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +| [0] | int256 | Returns 1 if a is a quadratic residue mod p, -1 if it is a non-quadratic residue, and 0 if a is 0. | + diff --git a/docs/app-development/random-beacon/random-beacon-api/generated-docs/libraries/Relay.md b/docs/app-development/random-beacon/random-beacon-api/generated-docs/libraries/Relay.md new file mode 100644 index 0000000..22c6d95 --- /dev/null +++ b/docs/app-development/random-beacon/random-beacon-api/generated-docs/libraries/Relay.md @@ -0,0 +1,236 @@ +# Solidity API + +## Relay + +### Data + +```solidity +struct Data { + uint64 requestCount; + uint64 currentRequestID; + uint64 currentRequestGroupID; + uint64 currentRequestStartBlock; + struct AltBn128.G1Point previousEntry; + uint32 relayEntrySoftTimeout; + uint32 relayEntryHardTimeout; + uint96 relayEntrySubmissionFailureSlashingAmount; +} +``` + +### relaySeed + +```solidity +bytes relaySeed +``` + +Seed used as the first relay entry value. +It's a G1 point G * PI = +G * 31415926535897932384626433832795028841971693993751058209749445923078164062862 +Where G is the generator of G1 abstract cyclic group. + +### RelayEntryRequested + +```solidity +event RelayEntryRequested(uint256 requestId, uint64 groupId, bytes previousEntry) +``` + +### RelayEntrySubmitted + +```solidity +event RelayEntrySubmitted(uint256 requestId, address submitter, bytes entry) +``` + +### RelayEntryTimedOut + +```solidity +event RelayEntryTimedOut(uint256 requestId, uint64 terminatedGroupId) +``` + +### initSeedEntry + +```solidity +function initSeedEntry(struct Relay.Data self) internal +``` + +Initializes the very first `previousEntry` with an initial +`relaySeed` value. Can be performed only once. + +### requestEntry + +```solidity +function requestEntry(struct Relay.Data self, uint64 groupId) internal +``` + +Creates a request to generate a new relay entry, which will +include a random number (by signing the previous entry's +random number). + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| self | struct Relay.Data | | +| groupId | uint64 | Identifier of the group chosen to handle the request. | + +### submitEntryBeforeSoftTimeout + +```solidity +function submitEntryBeforeSoftTimeout(struct Relay.Data self, bytes entry, bytes groupPubKey) internal +``` + +Creates a new relay entry. Gas-optimized version that can be +called only before the soft timeout. This should be the majority +of cases. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| self | struct Relay.Data | | +| entry | bytes | Group BLS signature over the previous entry. | +| groupPubKey | bytes | Public key of the group which signed the relay entry. | + +### submitEntry + +```solidity +function submitEntry(struct Relay.Data self, bytes entry, bytes groupPubKey) internal returns (uint96) +``` + +Creates a new relay entry. Can be called at any time. +In case the soft timeout has not been exceeded, it is more +gas-efficient to call the second variation of `submitEntry`. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| self | struct Relay.Data | | +| entry | bytes | Group BLS signature over the previous entry. | +| groupPubKey | bytes | Public key of the group which signed the relay entry. | + +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +| [0] | uint96 | slashingAmount Amount by which group members should be slashed in case the relay entry was submitted after the soft timeout. The value is zero if entry was submitted on time. | + +### _submitEntry + +```solidity +function _submitEntry(struct Relay.Data self, bytes entry, bytes groupPubKey) internal +``` + +### calculateSlashingAmount + +```solidity +function calculateSlashingAmount(struct Relay.Data self) internal view returns (uint96) +``` + +Calculates the slashing amount for all group members. + +Must be used when a soft timeout was hit. + +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +| [0] | uint96 | Amount by which group members should be slashed in case the relay entry was submitted after the soft timeout. | + +### setTimeouts + +```solidity +function setTimeouts(struct Relay.Data self, uint256 _relayEntrySoftTimeout, uint256 _relayEntryHardTimeout) internal +``` + +Updates relay-related parameters + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| self | struct Relay.Data | | +| _relayEntrySoftTimeout | uint256 | New relay entry soft timeout value. It is the time in blocks during which a result is expected to be submitted so that the group is not slashed. | +| _relayEntryHardTimeout | uint256 | New relay entry hard timeout value. It is the time in blocks for a group to submit the relay entry before slashing for the full slashing amount happens. | + +### setRelayEntrySubmissionFailureSlashingAmount + +```solidity +function setRelayEntrySubmissionFailureSlashingAmount(struct Relay.Data self, uint96 newRelayEntrySubmissionFailureSlashingAmount) internal +``` + +Set relayEntrySubmissionFailureSlashingAmount parameter. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| self | struct Relay.Data | | +| newRelayEntrySubmissionFailureSlashingAmount | uint96 | New value of the parameter. | + +### retryOnEntryTimeout + +```solidity +function retryOnEntryTimeout(struct Relay.Data self, uint64 newGroupId) internal +``` + +Retries the current relay request in case a relay entry +timeout was reported. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| self | struct Relay.Data | | +| newGroupId | uint64 | ID of the group chosen to retry the current request. | + +### cleanupOnEntryTimeout + +```solidity +function cleanupOnEntryTimeout(struct Relay.Data self) internal +``` + +Cleans up the current relay request in case a relay entry +timeout was reported. + +### isRequestInProgress + +```solidity +function isRequestInProgress(struct Relay.Data self) internal view returns (bool) +``` + +Returns whether a relay entry request is currently in progress. + +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +| [0] | bool | True if there is a request in progress. False otherwise. | + +### hasRequestTimedOut + +```solidity +function hasRequestTimedOut(struct Relay.Data self) internal view returns (bool) +``` + +Returns whether the current relay request has timed out. + +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +| [0] | bool | True if the request timed out. False otherwise. | + +### softTimeoutBlock + +```solidity +function softTimeoutBlock(struct Relay.Data self) internal view returns (uint256) +``` + +Calculates soft timeout block for the pending relay request. + +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +| [0] | uint256 | The soft timeout block | + diff --git a/docs/app-development/staking-contract-and-dao/README.md b/docs/app-development/staking-contract-and-dao/README.md index 0105d61..ea938a8 100644 --- a/docs/app-development/staking-contract-and-dao/README.md +++ b/docs/app-development/staking-contract-and-dao/README.md @@ -1,3 +1,3 @@ # Staking Contract and DAO -To get familiarized with API of contracts related to staking and DAO, go [here](staking-contracts-and-dao-api/generated-docs/index.md). +To get familiarized with API of contracts related to staking and DAO, go [here](staking-contract-and-dao-api/generated-docs/index.md). diff --git a/docs/app-development/staking-contract-and-dao/staking-contract-and-dao-api/README.md b/docs/app-development/staking-contract-and-dao/staking-contract-and-dao-api/README.md new file mode 100644 index 0000000..0fa8629 --- /dev/null +++ b/docs/app-development/staking-contract-and-dao/staking-contract-and-dao-api/README.md @@ -0,0 +1,40 @@ +# Staking Contract and DAO API + +You can learn about APIs of contracts related to staking and DAO under the +following links: + +[BaseTokenholderGovernor](./generated-docs/governance/BaseTokenholderGovernor.md) + +[Checkpoints](./generated-docs/governance/Checkpoints.md) + +[GovernorParameters](./generated-docs/governance/GovernorParameters.md) + +[IApplication](./generated-docs/staking/IApplication.md) + +[ILegacyTokenStaking](./generated-docs/staking/ILegacyTokenStaking.md) + +[IStaking](./generated-docs/staking/IStaking.md) + +[IVotesHistory](./generated-docs/governance/IVotesHistory.md) + +[KeepStake](./generated-docs/staking/KeepStake.md) + +[PercentUtils](./generated-docs/utils/PercentUtils.md) + +[ProxyAdminWithDeputy](./generated-docs/governance/ProxyAdminWithDeputy.md) + +[SafeTUpgradeable](./generated-docs/utils/SafeTUpgradeable.md) + +[StakerGovernor](./generated-docs/governance/StakerGovernor.md) + +[StakerGovernorVotes](./generated-docs/governance/StakerGovernorVotes.md) + +[T](./generated-docs/token/T.md) + +[TokenholderGovernor](./generated-docs/governance/TokenholderGovernor.md) + +[TokenholderGovernorVotes](./generated-docs/governance/TokenholderGovernorVotes.md) + +[TokenStaking](./generated-docs/staking/TokenStaking.md) + +[VendingMachine](./generated-docs/vendingVendingMachine.md) diff --git a/docs/app-development/staking-contract-and-dao/staking-contract-and-dao-api/generated-docs/governance/BaseTokenholderGovernor.md b/docs/app-development/staking-contract-and-dao/staking-contract-and-dao-api/generated-docs/governance/BaseTokenholderGovernor.md new file mode 100644 index 0000000..51e029f --- /dev/null +++ b/docs/app-development/staking-contract-and-dao/staking-contract-and-dao-api/generated-docs/governance/BaseTokenholderGovernor.md @@ -0,0 +1,88 @@ +# Solidity API + +## BaseTokenholderGovernor + +### VETO_POWER + +```solidity +bytes32 VETO_POWER +``` + +### constructor + +```solidity +constructor(contract T _token, contract IVotesHistory _staking, contract TimelockController _timelock, address _vetoer, uint256 _quorumNumerator, uint256 _proposalThresholdNumerator, uint256 votingDelay, uint256 votingPeriod, uint64 votingExtension) public +``` + +### cancel + +```solidity +function cancel(address[] targets, uint256[] values, bytes[] calldatas, bytes32 descriptionHash) external returns (uint256) +``` + +### propose + +```solidity +function propose(address[] targets, uint256[] values, bytes[] calldatas, string description) public returns (uint256) +``` + +### quorum + +```solidity +function quorum(uint256 blockNumber) public view returns (uint256) +``` + +### proposalThreshold + +```solidity +function proposalThreshold() public view returns (uint256) +``` + +### getVotes + +```solidity +function getVotes(address account, uint256 blockNumber) public view returns (uint256) +``` + +### state + +```solidity +function state(uint256 proposalId) public view returns (enum IGovernor.ProposalState) +``` + +### supportsInterface + +```solidity +function supportsInterface(bytes4 interfaceId) public view returns (bool) +``` + +### _execute + +```solidity +function _execute(uint256 proposalId, address[] targets, uint256[] values, bytes[] calldatas, bytes32 descriptionHash) internal +``` + +### _cancel + +```solidity +function _cancel(address[] targets, uint256[] values, bytes[] calldatas, bytes32 descriptionHash) internal returns (uint256) +``` + +### _executor + +```solidity +function _executor() internal view returns (address) +``` + +### proposalDeadline + +```solidity +function proposalDeadline(uint256 proposalId) public view virtual returns (uint256) +``` + +### _castVote + +```solidity +function _castVote(uint256 proposalId, address account, uint8 support, string reason) internal virtual returns (uint256) +``` + diff --git a/docs/app-development/staking-contract-and-dao/staking-contract-and-dao-api/generated-docs/governance/Checkpoints.md b/docs/app-development/staking-contract-and-dao/staking-contract-and-dao-api/generated-docs/governance/Checkpoints.md new file mode 100644 index 0000000..0b9caa9 --- /dev/null +++ b/docs/app-development/staking-contract-and-dao/staking-contract-and-dao-api/generated-docs/governance/Checkpoints.md @@ -0,0 +1,258 @@ +# Solidity API + +## Checkpoints + +Abstract contract to support checkpoints for Compound-like voting and +delegation. This implementation supports token supply up to 2^96 - 1. +This contract keeps a history (checkpoints) of each account's vote +power. Vote power can be delegated either by calling the {delegate} +function directly, or by providing a signature to be used with +{delegateBySig}. Voting power can be publicly queried through +{getVotes} and {getPastVotes}. +NOTE: Extracted from OpenZeppelin ERCVotes.sol. +This contract is upgrade-safe. + +### Checkpoint + +```solidity +struct Checkpoint { + uint32 fromBlock; + uint96 votes; +} +``` + +### _delegates + +```solidity +mapping(address => address) _delegates +``` + +### _checkpoints + +```solidity +mapping(address => uint128[]) _checkpoints +``` + +### _totalSupplyCheckpoints + +```solidity +uint128[] _totalSupplyCheckpoints +``` + +### DelegateChanged + +```solidity +event DelegateChanged(address delegator, address fromDelegate, address toDelegate) +``` + +Emitted when an account changes their delegate. + +### DelegateVotesChanged + +```solidity +event DelegateVotesChanged(address delegate, uint256 previousBalance, uint256 newBalance) +``` + +Emitted when a balance or delegate change results in changes +to an account's voting power. + +### checkpoints + +```solidity +function checkpoints(address account, uint32 pos) public view virtual returns (struct Checkpoints.Checkpoint checkpoint) +``` + +### numCheckpoints + +```solidity +function numCheckpoints(address account) public view virtual returns (uint32) +``` + +Get number of checkpoints for `account`. + +### delegates + +```solidity +function delegates(address account) public view virtual returns (address) +``` + +Get the address `account` is currently delegating to. + +### getVotes + +```solidity +function getVotes(address account) public view returns (uint96) +``` + +Gets the current votes balance for `account`. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| account | address | The address to get votes balance | + +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +| [0] | uint96 | The number of current votes for `account` | + +### getPastVotes + +```solidity +function getPastVotes(address account, uint256 blockNumber) public view returns (uint96) +``` + +Determine the prior number of votes for an account as of +a block number. + +Block number must be a finalized block or else this function will +revert to prevent misinformation. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| account | address | The address of the account to check | +| blockNumber | uint256 | The block number to get the vote balance at | + +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +| [0] | uint96 | The number of votes the account had as of the given block | + +### getPastTotalSupply + +```solidity +function getPastTotalSupply(uint256 blockNumber) public view returns (uint96) +``` + +Retrieve the `totalSupply` at the end of `blockNumber`. +Note, this value is the sum of all balances, but it is NOT the +sum of all the delegated votes! + +`blockNumber` must have been already mined + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| blockNumber | uint256 | The block number to get the total supply at | + +### delegate + +```solidity +function delegate(address delegator, address delegatee) internal virtual +``` + +Change delegation for `delegator` to `delegatee`. + +### moveVotingPower + +```solidity +function moveVotingPower(address src, address dst, uint256 amount) internal +``` + +Moves voting power from one delegate to another + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| src | address | Address of old delegate | +| dst | address | Address of new delegate | +| amount | uint256 | Voting power amount to transfer between delegates | + +### writeCheckpoint + +```solidity +function writeCheckpoint(uint128[] ckpts, function (uint256,uint256) view returns (uint256) op, uint256 delta) internal returns (uint256 oldWeight, uint256 newWeight) +``` + +Writes a new checkpoint based on operating last stored value +with a `delta`. Usually, said operation is the `add` or +`subtract` functions from this contract, but more complex +functions can be passed as parameters. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| ckpts | uint128[] | The checkpoints array to use | +| op | function (uint256,uint256) view returns (uint256) | The function to apply over the last value and the `delta` | +| delta | uint256 | Variation with respect to last stored value to be used for new checkpoint | + +### lookupCheckpoint + +```solidity +function lookupCheckpoint(uint128[] ckpts, uint256 blockNumber) internal view returns (uint96) +``` + +Lookup a value in a list of (sorted) checkpoints. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| ckpts | uint128[] | The checkpoints array to use | +| blockNumber | uint256 | Block number when we want to get the checkpoint at | + +### maxSupply + +```solidity +function maxSupply() internal view virtual returns (uint96) +``` + +Maximum token supply. Defaults to `type(uint96).max` (2^96 - 1) + +### encodeCheckpoint + +```solidity +function encodeCheckpoint(uint32 blockNumber, uint96 value) internal pure returns (uint128) +``` + +Encodes a `blockNumber` and `value` into a single `uint128` +checkpoint. + +`blockNumber` is stored in the first 32 bits, while `value` in the +remaining 96 bits. + +### decodeBlockNumber + +```solidity +function decodeBlockNumber(uint128 checkpoint) internal pure returns (uint32) +``` + +Decodes a block number from a `uint128` `checkpoint`. + +### decodeValue + +```solidity +function decodeValue(uint128 checkpoint) internal pure returns (uint96) +``` + +Decodes a voting value from a `uint128` `checkpoint`. + +### decodeCheckpoint + +```solidity +function decodeCheckpoint(uint128 checkpoint) internal pure returns (uint32 blockNumber, uint96 value) +``` + +Decodes a block number and voting value from a `uint128` +`checkpoint`. + +### add + +```solidity +function add(uint256 a, uint256 b) internal pure returns (uint256) +``` + +### subtract + +```solidity +function subtract(uint256 a, uint256 b) internal pure returns (uint256) +``` + diff --git a/docs/app-development/staking-contract-and-dao/staking-contract-and-dao-api/generated-docs/governance/GovernorParameters.md b/docs/app-development/staking-contract-and-dao/staking-contract-and-dao-api/generated-docs/governance/GovernorParameters.md new file mode 100644 index 0000000..351bc4b --- /dev/null +++ b/docs/app-development/staking-contract-and-dao/staking-contract-and-dao-api/generated-docs/governance/GovernorParameters.md @@ -0,0 +1,198 @@ +# Solidity API + +## GovernorParameters + +Abstract contract to handle governance parameters + +Based on `GovernorVotesQuorumFraction`, but without being opinionated +on what's the source of voting power, and extended to handle proposal +thresholds too. See OpenZeppelin's GovernorVotesQuorumFraction, +GovernorVotes and GovernorSettings for reference. + +### FRACTION_DENOMINATOR + +```solidity +uint256 FRACTION_DENOMINATOR +``` + +### AVERAGE_BLOCK_TIME_IN_SECONDS + +```solidity +uint64 AVERAGE_BLOCK_TIME_IN_SECONDS +``` + +### quorumNumerator + +```solidity +uint256 quorumNumerator +``` + +### proposalThresholdNumerator + +```solidity +uint256 proposalThresholdNumerator +``` + +### QuorumNumeratorUpdated + +```solidity +event QuorumNumeratorUpdated(uint256 oldQuorumNumerator, uint256 newQuorumNumerator) +``` + +### ProposalThresholdNumeratorUpdated + +```solidity +event ProposalThresholdNumeratorUpdated(uint256 oldThresholdNumerator, uint256 newThresholdNumerator) +``` + +### VotingDelaySet + +```solidity +event VotingDelaySet(uint256 oldVotingDelay, uint256 newVotingDelay) +``` + +### VotingPeriodSet + +```solidity +event VotingPeriodSet(uint256 oldVotingPeriod, uint256 newVotingPeriod) +``` + +### constructor + +```solidity +constructor(uint256 quorumNumeratorValue, uint256 proposalNumeratorValue, uint256 initialVotingDelay, uint256 initialVotingPeriod) internal +``` + +### updateQuorumNumerator + +```solidity +function updateQuorumNumerator(uint256 newQuorumNumerator) external virtual +``` + +### updateProposalThresholdNumerator + +```solidity +function updateProposalThresholdNumerator(uint256 newNumerator) external virtual +``` + +### setVotingDelay + +```solidity +function setVotingDelay(uint256 newVotingDelay) external virtual +``` + +Update the voting delay. This operation can only be performed +through a governance proposal. Emits a `VotingDelaySet` event. + +### setVotingPeriod + +```solidity +function setVotingPeriod(uint256 newVotingPeriod) external virtual +``` + +Update the voting period. This operation can only be performed +through a governance proposal. Emits a `VotingPeriodSet` event. + +### quorum + +```solidity +function quorum(uint256 blockNumber) public view virtual returns (uint256) +``` + +Compute the required amount of voting power to reach quorum + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| blockNumber | uint256 | The block number to get the quorum at | + +### proposalThreshold + +```solidity +function proposalThreshold() public view virtual returns (uint256) +``` + +Compute the required amount of voting power to create a proposal +at the last block height + +This function is implemented to comply with Governor API but we +we will actually use `proposalThreshold(uint256 blockNumber)`, +as in our DAOs the threshold amount changes according to supply. + +### proposalThreshold + +```solidity +function proposalThreshold(uint256 blockNumber) public view returns (uint256) +``` + +Compute the required amount of voting power to create a proposal + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| blockNumber | uint256 | The block number to get the proposal threshold at | + +### votingDelay + +```solidity +function votingDelay() public view virtual returns (uint256) +``` + +module:user-config + +Delay, in number of block, between the proposal is created and the vote starts. This can be increassed to +leave time for users to buy voting power, of delegate it, before the voting of a proposal starts. + +### votingPeriod + +```solidity +function votingPeriod() public view virtual returns (uint256) +``` + +module:user-config + +Delay, in number of blocks, between the vote start and vote ends. + +NOTE: The {votingDelay} can delay the start of the vote. This must be considered when setting the voting +duration compared to the voting delay. + +### _updateQuorumNumerator + +```solidity +function _updateQuorumNumerator(uint256 newQuorumNumerator) internal virtual +``` + +### _updateProposalThresholdNumerator + +```solidity +function _updateProposalThresholdNumerator(uint256 proposalNumerator) internal virtual +``` + +### _setVotingDelay + +```solidity +function _setVotingDelay(uint256 newVotingDelay) internal virtual +``` + +### _setVotingPeriod + +```solidity +function _setVotingPeriod(uint256 newVotingPeriod) internal virtual +``` + +### _getPastTotalSupply + +```solidity +function _getPastTotalSupply(uint256 blockNumber) internal view virtual returns (uint256) +``` + +Compute the past total voting power at a particular block + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| blockNumber | uint256 | The block number to get the vote power at | + diff --git a/docs/app-development/staking-contract-and-dao/staking-contract-and-dao-api/generated-docs/governance/IVotesHistory.md b/docs/app-development/staking-contract-and-dao/staking-contract-and-dao-api/generated-docs/governance/IVotesHistory.md new file mode 100644 index 0000000..4edd14a --- /dev/null +++ b/docs/app-development/staking-contract-and-dao/staking-contract-and-dao-api/generated-docs/governance/IVotesHistory.md @@ -0,0 +1,16 @@ +# Solidity API + +## IVotesHistory + +### getPastVotes + +```solidity +function getPastVotes(address account, uint256 blockNumber) external view returns (uint96) +``` + +### getPastTotalSupply + +```solidity +function getPastTotalSupply(uint256 blockNumber) external view returns (uint96) +``` + diff --git a/docs/app-development/staking-contract-and-dao/staking-contract-and-dao-api/generated-docs/governance/ProxyAdminWithDeputy.md b/docs/app-development/staking-contract-and-dao/staking-contract-and-dao-api/generated-docs/governance/ProxyAdminWithDeputy.md new file mode 100644 index 0000000..d657c08 --- /dev/null +++ b/docs/app-development/staking-contract-and-dao/staking-contract-and-dao-api/generated-docs/governance/ProxyAdminWithDeputy.md @@ -0,0 +1,74 @@ +# Solidity API + +## ProxyAdminWithDeputy + +Based on `ProxyAdmin`, an auxiliary contract in OpenZeppelin's +upgradeability approach meant to act as the admin of a +`TransparentUpgradeableProxy`. This variant allows an additional +actor, the "deputy", to perform upgrades, which originally can only +be performed by the ProxyAdmin's owner. See OpenZeppelin's +documentation for `TransparentUpgradeableProxy` for more details on +why a ProxyAdmin is recommended. + +### deputy + +```solidity +address deputy +``` + +### DeputyUpdated + +```solidity +event DeputyUpdated(address previousDeputy, address newDeputy) +``` + +### onlyOwnerOrDeputy + +```solidity +modifier onlyOwnerOrDeputy() +``` + +### constructor + +```solidity +constructor(contract StakerGovernor dao, address _deputy) public +``` + +### setDeputy + +```solidity +function setDeputy(address newDeputy) external +``` + +### upgrade + +```solidity +function upgrade(contract TransparentUpgradeableProxy proxy, address implementation) public virtual +``` + +Upgrades `proxy` to `implementation`. This contract must be the +admin of `proxy`, and the caller must be this contract's owner +or the deputy. + +### upgradeAndCall + +```solidity +function upgradeAndCall(contract TransparentUpgradeableProxy proxy, address implementation, bytes data) public payable virtual +``` + +Upgrades `proxy` to `implementation` and calls a function on the +new implementation. This contract must be the admin of `proxy`, +and the caller must be this contract's owner or the deputy. + +### _setDeputy + +```solidity +function _setDeputy(address newDeputy) internal +``` + +### _checkCallerIsOwnerOrDeputy + +```solidity +function _checkCallerIsOwnerOrDeputy() internal view +``` + diff --git a/docs/app-development/staking-contract-and-dao/staking-contract-and-dao-api/generated-docs/governance/StakerGovernor.md b/docs/app-development/staking-contract-and-dao/staking-contract-and-dao-api/generated-docs/governance/StakerGovernor.md new file mode 100644 index 0000000..eb83174 --- /dev/null +++ b/docs/app-development/staking-contract-and-dao/staking-contract-and-dao-api/generated-docs/governance/StakerGovernor.md @@ -0,0 +1,90 @@ +# Solidity API + +## StakerGovernor + +### VETO_POWER + +```solidity +bytes32 VETO_POWER +``` + +### manager + +```solidity +address manager +``` + +### constructor + +```solidity +constructor(contract IVotesHistory _staking, contract TimelockController _timelock, contract TokenholderGovernor tokenholderGovernor, address vetoer) public +``` + +### cancel + +```solidity +function cancel(address[] targets, uint256[] values, bytes[] calldatas, bytes32 descriptionHash) external returns (uint256) +``` + +### propose + +```solidity +function propose(address[] targets, uint256[] values, bytes[] calldatas, string description) public returns (uint256) +``` + +### quorum + +```solidity +function quorum(uint256 blockNumber) public view returns (uint256) +``` + +### proposalThreshold + +```solidity +function proposalThreshold() public view returns (uint256) +``` + +### getVotes + +```solidity +function getVotes(address account, uint256 blockNumber) public view returns (uint256) +``` + +### state + +```solidity +function state(uint256 proposalId) public view returns (enum IGovernor.ProposalState) +``` + +### supportsInterface + +```solidity +function supportsInterface(bytes4 interfaceId) public view returns (bool) +``` + +### _execute + +```solidity +function _execute(uint256 proposalId, address[] targets, uint256[] values, bytes[] calldatas, bytes32 descriptionHash) internal +``` + +### _cancel + +```solidity +function _cancel(address[] targets, uint256[] values, bytes[] calldatas, bytes32 descriptionHash) internal returns (uint256) +``` + +### _executor + +```solidity +function _executor() internal view returns (address) +``` + +Returns the address of the entity that acts as governance for +this contract. + +By default, Governor assumes this is either the Governor contract +itself, or a timelock if there's one configured. We override this +here for the StakerGovernor contract so it's the Tokenholder DAO's +Timelock, which we obtain at constructor time. + diff --git a/docs/app-development/staking-contract-and-dao/staking-contract-and-dao-api/generated-docs/governance/StakerGovernorVotes.md b/docs/app-development/staking-contract-and-dao/staking-contract-and-dao-api/generated-docs/governance/StakerGovernorVotes.md new file mode 100644 index 0000000..97e3a6b --- /dev/null +++ b/docs/app-development/staking-contract-and-dao/staking-contract-and-dao-api/generated-docs/governance/StakerGovernorVotes.md @@ -0,0 +1,51 @@ +# Solidity API + +## StakerGovernorVotes + +Staker DAO voting power extraction from staked T positions, + +### staking + +```solidity +contract IVotesHistory staking +``` + +### constructor + +```solidity +constructor(contract IVotesHistory tStakingAddress) internal +``` + +### getVotes + +```solidity +function getVotes(address account, uint256 blockNumber) public view virtual returns (uint256) +``` + +Read the voting weight from the snapshot mechanism in the T +staking contracts. Note that this also tracks legacy stakes +(NU/KEEP). + +See {IGovernor-getVotes} + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| account | address | Delegate account with T staking voting power | +| blockNumber | uint256 | The block number to get the vote balance at | + +### _getPastTotalSupply + +```solidity +function _getPastTotalSupply(uint256 blockNumber) internal view virtual returns (uint256) +``` + +Compute the total voting power for the Staker DAO. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| blockNumber | uint256 | The block number to get the voting power at | + diff --git a/docs/app-development/staking-contract-and-dao/staking-contract-and-dao-api/generated-docs/governance/TokenholderGovernor.md b/docs/app-development/staking-contract-and-dao/staking-contract-and-dao-api/generated-docs/governance/TokenholderGovernor.md new file mode 100644 index 0000000..2cbdf2f --- /dev/null +++ b/docs/app-development/staking-contract-and-dao/staking-contract-and-dao-api/generated-docs/governance/TokenholderGovernor.md @@ -0,0 +1,10 @@ +# Solidity API + +## TokenholderGovernor + +### constructor + +```solidity +constructor(contract T _token, contract IVotesHistory _staking, contract TimelockController _timelock, address vetoer) public +``` + diff --git a/docs/app-development/staking-contract-and-dao/staking-contract-and-dao-api/generated-docs/governance/TokenholderGovernorVotes.md b/docs/app-development/staking-contract-and-dao/staking-contract-and-dao-api/generated-docs/governance/TokenholderGovernorVotes.md new file mode 100644 index 0000000..8a85e34 --- /dev/null +++ b/docs/app-development/staking-contract-and-dao/staking-contract-and-dao-api/generated-docs/governance/TokenholderGovernorVotes.md @@ -0,0 +1,70 @@ +# Solidity API + +## TokenholderGovernorVotes + +Tokenholder DAO voting power extraction from both liquid and staked +T token positions, including legacy stakes (NU/KEEP). + +### token + +```solidity +contract IVotesHistory token +``` + +### staking + +```solidity +contract IVotesHistory staking +``` + +### constructor + +```solidity +constructor(contract IVotesHistory tokenAddress, contract IVotesHistory tStakingAddress) internal +``` + +### getVotes + +```solidity +function getVotes(address account, uint256 blockNumber) public view virtual returns (uint256) +``` + +Read the voting weight from the snapshot mechanism in the token +and staking contracts. For Tokenholder DAO, there are currently +two voting power sources: +- Liquid T, tracked by the T token contract +- Stakes in the T network, tracked by the T staking contract. +Note that this also tracks legacy stakes (NU/KEEP); legacy +stakes count for tokenholders' voting power, but not for the +total voting power of the Tokenholder DAO +(see {_getPastTotalSupply}). + +See {IGovernor-getVotes} + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| account | address | Tokenholder account in the T network | +| blockNumber | uint256 | The block number to get the vote balance at | + +### _getPastTotalSupply + +```solidity +function _getPastTotalSupply(uint256 blockNumber) internal view virtual returns (uint256) +``` + +Compute the total voting power for Tokenholder DAO. Note how it +only uses the token total supply as source, as native T tokens +that are staked continue existing, but as deposits in the +staking contract. However, legacy stakes can't contribute to the +total voting power as they're already implicitly counted as part +of Vending Machines' liquid balance; hence, we only need to read +total voting power from the token. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| blockNumber | uint256 | The block number to get the vote power at | + diff --git a/docs/app-development/staking-contract-and-dao/staking-contract-and-dao-api/generated-docs/index.md b/docs/app-development/staking-contract-and-dao/staking-contract-and-dao-api/generated-docs/index.md deleted file mode 100644 index 7b5d769..0000000 --- a/docs/app-development/staking-contract-and-dao/staking-contract-and-dao-api/generated-docs/index.md +++ /dev/null @@ -1,3088 +0,0 @@ -# Solidity API -## Table Of Contents - - - -- [BaseTokenholderGovernor](#basetokenholdergovernor) -- [Checkpoints](#checkpoints) -- [GovernorParameters](#governorparameters) -- [IVotesHistory](#ivoteshistory) -- [ProxyAdminWithDeputy](#proxyadminwithdeputy) -- [StakerGovernor](#stakergovernor) -- [StakerGovernorVotes](#stakergovernorvotes) -- [TokenholderGovernor](#tokenholdergovernor) -- [TokenholderGovernorVotes](#tokenholdergovernorvotes) -- [IApplication](#iapplication) -- [IKeepTokenStaking](#ikeeptokenstaking) -- [INuCypherStakingEscrow](#inucypherstakingescrow) -- [IStaking](#istaking) -- [IManagedGrant](#imanagedgrant) -- [KeepStake](#keepstake) -- [TokenStaking](#tokenstaking) -- [T](#t) -- [PercentUtils](#percentutils) -- [SafeTUpgradeable](#safetupgradeable) -- [VendingMachine](#vendingmachine) - - - -## BaseTokenholderGovernor - -### VETO_POWER - -```solidity -bytes32 VETO_POWER -``` - -### constructor - -```solidity -constructor(contract T _token, contract IVotesHistory _staking, contract TimelockController _timelock, address _vetoer, uint256 _quorumNumerator, uint256 _proposalThresholdNumerator, uint256 votingDelay, uint256 votingPeriod, uint64 votingExtension) public -``` - -### cancel - -```solidity -function cancel(address[] targets, uint256[] values, bytes[] calldatas, bytes32 descriptionHash) external returns (uint256) -``` - -### propose - -```solidity -function propose(address[] targets, uint256[] values, bytes[] calldatas, string description) public returns (uint256) -``` - -### quorum - -```solidity -function quorum(uint256 blockNumber) public view returns (uint256) -``` - -### proposalThreshold - -```solidity -function proposalThreshold() public view returns (uint256) -``` - -### getVotes - -```solidity -function getVotes(address account, uint256 blockNumber) public view returns (uint256) -``` - -### state - -```solidity -function state(uint256 proposalId) public view returns (enum IGovernor.ProposalState) -``` - -### supportsInterface - -```solidity -function supportsInterface(bytes4 interfaceId) public view returns (bool) -``` - -### _execute - -```solidity -function _execute(uint256 proposalId, address[] targets, uint256[] values, bytes[] calldatas, bytes32 descriptionHash) internal -``` - -### _cancel - -```solidity -function _cancel(address[] targets, uint256[] values, bytes[] calldatas, bytes32 descriptionHash) internal returns (uint256) -``` - -### _executor - -```solidity -function _executor() internal view returns (address) -``` - -### proposalDeadline - -```solidity -function proposalDeadline(uint256 proposalId) public view virtual returns (uint256) -``` - -### _castVote - -```solidity -function _castVote(uint256 proposalId, address account, uint8 support, string reason) internal virtual returns (uint256) -``` - -## Checkpoints - -Abstract contract to support checkpoints for Compound-like voting and -delegation. This implementation supports token supply up to 2^96 - 1. -This contract keeps a history (checkpoints) of each account's vote -power. Vote power can be delegated either by calling the {delegate} -function directly, or by providing a signature to be used with -{delegateBySig}. Voting power can be publicly queried through -{getVotes} and {getPastVotes}. -NOTE: Extracted from OpenZeppelin ERCVotes.sol. -This contract is upgrade-safe. - -### Checkpoint - -```solidity -struct Checkpoint { - uint32 fromBlock; - uint96 votes; -} -``` - -### _delegates - -```solidity -mapping(address => address) _delegates -``` - -### _checkpoints - -```solidity -mapping(address => uint128[]) _checkpoints -``` - -### _totalSupplyCheckpoints - -```solidity -uint128[] _totalSupplyCheckpoints -``` - -### DelegateChanged - -```solidity -event DelegateChanged(address delegator, address fromDelegate, address toDelegate) -``` - -Emitted when an account changes their delegate. - -### DelegateVotesChanged - -```solidity -event DelegateVotesChanged(address delegate, uint256 previousBalance, uint256 newBalance) -``` - -Emitted when a balance or delegate change results in changes -to an account's voting power. - -### checkpoints - -```solidity -function checkpoints(address account, uint32 pos) public view virtual returns (struct Checkpoints.Checkpoint checkpoint) -``` - -### numCheckpoints - -```solidity -function numCheckpoints(address account) public view virtual returns (uint32) -``` - -Get number of checkpoints for `account`. - -### delegates - -```solidity -function delegates(address account) public view virtual returns (address) -``` - -Get the address `account` is currently delegating to. - -### getVotes - -```solidity -function getVotes(address account) public view returns (uint96) -``` - -Gets the current votes balance for `account`. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| account | address | The address to get votes balance | - -#### Return Values - -| Name | Type | Description | -| ---- | ---- | ----------- | -| [0] | uint96 | The number of current votes for `account` | - -### getPastVotes - -```solidity -function getPastVotes(address account, uint256 blockNumber) public view returns (uint96) -``` - -Determine the prior number of votes for an account as of -a block number. - -Block number must be a finalized block or else this function will -revert to prevent misinformation. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| account | address | The address of the account to check | -| blockNumber | uint256 | The block number to get the vote balance at | - -#### Return Values - -| Name | Type | Description | -| ---- | ---- | ----------- | -| [0] | uint96 | The number of votes the account had as of the given block | - -### getPastTotalSupply - -```solidity -function getPastTotalSupply(uint256 blockNumber) public view returns (uint96) -``` - -Retrieve the `totalSupply` at the end of `blockNumber`. -Note, this value is the sum of all balances, but it is NOT the -sum of all the delegated votes! - -`blockNumber` must have been already mined - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| blockNumber | uint256 | The block number to get the total supply at | - -### delegate - -```solidity -function delegate(address delegator, address delegatee) internal virtual -``` - -Change delegation for `delegator` to `delegatee`. - -### moveVotingPower - -```solidity -function moveVotingPower(address src, address dst, uint256 amount) internal -``` - -Moves voting power from one delegate to another - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| src | address | Address of old delegate | -| dst | address | Address of new delegate | -| amount | uint256 | Voting power amount to transfer between delegates | - -### writeCheckpoint - -```solidity -function writeCheckpoint(uint128[] ckpts, function (uint256,uint256) view returns (uint256) op, uint256 delta) internal returns (uint256 oldWeight, uint256 newWeight) -``` - -Writes a new checkpoint based on operating last stored value -with a `delta`. Usually, said operation is the `add` or -`subtract` functions from this contract, but more complex -functions can be passed as parameters. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| ckpts | uint128[] | The checkpoints array to use | -| op | function (uint256,uint256) view returns (uint256) | The function to apply over the last value and the `delta` | -| delta | uint256 | Variation with respect to last stored value to be used for new checkpoint | - -### lookupCheckpoint - -```solidity -function lookupCheckpoint(uint128[] ckpts, uint256 blockNumber) internal view returns (uint96) -``` - -Lookup a value in a list of (sorted) checkpoints. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| ckpts | uint128[] | The checkpoints array to use | -| blockNumber | uint256 | Block number when we want to get the checkpoint at | - -### maxSupply - -```solidity -function maxSupply() internal view virtual returns (uint96) -``` - -Maximum token supply. Defaults to `type(uint96).max` (2^96 - 1) - -### encodeCheckpoint - -```solidity -function encodeCheckpoint(uint32 blockNumber, uint96 value) internal pure returns (uint128) -``` - -Encodes a `blockNumber` and `value` into a single `uint128` -checkpoint. - -`blockNumber` is stored in the first 32 bits, while `value` in the -remaining 96 bits. - -### decodeBlockNumber - -```solidity -function decodeBlockNumber(uint128 checkpoint) internal pure returns (uint32) -``` - -Decodes a block number from a `uint128` `checkpoint`. - -### decodeValue - -```solidity -function decodeValue(uint128 checkpoint) internal pure returns (uint96) -``` - -Decodes a voting value from a `uint128` `checkpoint`. - -### decodeCheckpoint - -```solidity -function decodeCheckpoint(uint128 checkpoint) internal pure returns (uint32 blockNumber, uint96 value) -``` - -Decodes a block number and voting value from a `uint128` -`checkpoint`. - -### add - -```solidity -function add(uint256 a, uint256 b) internal pure returns (uint256) -``` - -### subtract - -```solidity -function subtract(uint256 a, uint256 b) internal pure returns (uint256) -``` - -## GovernorParameters - -Abstract contract to handle governance parameters - -Based on `GovernorVotesQuorumFraction`, but without being opinionated -on what's the source of voting power, and extended to handle proposal -thresholds too. See OpenZeppelin's GovernorVotesQuorumFraction, -GovernorVotes and GovernorSettings for reference. - -### FRACTION_DENOMINATOR - -```solidity -uint256 FRACTION_DENOMINATOR -``` - -### AVERAGE_BLOCK_TIME_IN_SECONDS - -```solidity -uint64 AVERAGE_BLOCK_TIME_IN_SECONDS -``` - -### quorumNumerator - -```solidity -uint256 quorumNumerator -``` - -### proposalThresholdNumerator - -```solidity -uint256 proposalThresholdNumerator -``` - -### QuorumNumeratorUpdated - -```solidity -event QuorumNumeratorUpdated(uint256 oldQuorumNumerator, uint256 newQuorumNumerator) -``` - -### ProposalThresholdNumeratorUpdated - -```solidity -event ProposalThresholdNumeratorUpdated(uint256 oldThresholdNumerator, uint256 newThresholdNumerator) -``` - -### VotingDelaySet - -```solidity -event VotingDelaySet(uint256 oldVotingDelay, uint256 newVotingDelay) -``` - -### VotingPeriodSet - -```solidity -event VotingPeriodSet(uint256 oldVotingPeriod, uint256 newVotingPeriod) -``` - -### constructor - -```solidity -constructor(uint256 quorumNumeratorValue, uint256 proposalNumeratorValue, uint256 initialVotingDelay, uint256 initialVotingPeriod) internal -``` - -### updateQuorumNumerator - -```solidity -function updateQuorumNumerator(uint256 newQuorumNumerator) external virtual -``` - -### updateProposalThresholdNumerator - -```solidity -function updateProposalThresholdNumerator(uint256 newNumerator) external virtual -``` - -### setVotingDelay - -```solidity -function setVotingDelay(uint256 newVotingDelay) external virtual -``` - -Update the voting delay. This operation can only be performed -through a governance proposal. Emits a `VotingDelaySet` event. - -### setVotingPeriod - -```solidity -function setVotingPeriod(uint256 newVotingPeriod) external virtual -``` - -Update the voting period. This operation can only be performed -through a governance proposal. Emits a `VotingPeriodSet` event. - -### quorum - -```solidity -function quorum(uint256 blockNumber) public view virtual returns (uint256) -``` - -Compute the required amount of voting power to reach quorum - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| blockNumber | uint256 | The block number to get the quorum at | - -### proposalThreshold - -```solidity -function proposalThreshold() public view virtual returns (uint256) -``` - -Compute the required amount of voting power to create a proposal -at the last block height - -This function is implemented to comply with Governor API but we -we will actually use `proposalThreshold(uint256 blockNumber)`, -as in our DAOs the threshold amount changes according to supply. - -### proposalThreshold - -```solidity -function proposalThreshold(uint256 blockNumber) public view returns (uint256) -``` - -Compute the required amount of voting power to create a proposal - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| blockNumber | uint256 | The block number to get the proposal threshold at | - -### votingDelay - -```solidity -function votingDelay() public view virtual returns (uint256) -``` - -module:user-config - -Delay, in number of block, between the proposal is created and the vote starts. This can be increassed to -leave time for users to buy voting power, of delegate it, before the voting of a proposal starts. - -### votingPeriod - -```solidity -function votingPeriod() public view virtual returns (uint256) -``` - -module:user-config - -Delay, in number of blocks, between the vote start and vote ends. - -NOTE: The {votingDelay} can delay the start of the vote. This must be considered when setting the voting -duration compared to the voting delay. - -### _updateQuorumNumerator - -```solidity -function _updateQuorumNumerator(uint256 newQuorumNumerator) internal virtual -``` - -### _updateProposalThresholdNumerator - -```solidity -function _updateProposalThresholdNumerator(uint256 proposalNumerator) internal virtual -``` - -### _setVotingDelay - -```solidity -function _setVotingDelay(uint256 newVotingDelay) internal virtual -``` - -### _setVotingPeriod - -```solidity -function _setVotingPeriod(uint256 newVotingPeriod) internal virtual -``` - -### _getPastTotalSupply - -```solidity -function _getPastTotalSupply(uint256 blockNumber) internal view virtual returns (uint256) -``` - -Compute the past total voting power at a particular block - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| blockNumber | uint256 | The block number to get the vote power at | - -## IVotesHistory - -### getPastVotes - -```solidity -function getPastVotes(address account, uint256 blockNumber) external view returns (uint96) -``` - -### getPastTotalSupply - -```solidity -function getPastTotalSupply(uint256 blockNumber) external view returns (uint96) -``` - -## ProxyAdminWithDeputy - -Based on `ProxyAdmin`, an auxiliary contract in OpenZeppelin's -upgradeability approach meant to act as the admin of a -`TransparentUpgradeableProxy`. This variant allows an additional -actor, the "deputy", to perform upgrades, which originally can only -be performed by the ProxyAdmin's owner. See OpenZeppelin's -documentation for `TransparentUpgradeableProxy` for more details on -why a ProxyAdmin is recommended. - -### deputy - -```solidity -address deputy -``` - -### DeputyUpdated - -```solidity -event DeputyUpdated(address previousDeputy, address newDeputy) -``` - -### onlyOwnerOrDeputy - -```solidity -modifier onlyOwnerOrDeputy() -``` - -### constructor - -```solidity -constructor(contract StakerGovernor dao, address _deputy) public -``` - -### setDeputy - -```solidity -function setDeputy(address newDeputy) external -``` - -### upgrade - -```solidity -function upgrade(contract TransparentUpgradeableProxy proxy, address implementation) public virtual -``` - -Upgrades `proxy` to `implementation`. This contract must be the -admin of `proxy`, and the caller must be this contract's owner -or the deputy. - -### upgradeAndCall - -```solidity -function upgradeAndCall(contract TransparentUpgradeableProxy proxy, address implementation, bytes data) public payable virtual -``` - -Upgrades `proxy` to `implementation` and calls a function on the -new implementation. This contract must be the admin of `proxy`, -and the caller must be this contract's owner or the deputy. - -### _setDeputy - -```solidity -function _setDeputy(address newDeputy) internal -``` - -### _checkCallerIsOwnerOrDeputy - -```solidity -function _checkCallerIsOwnerOrDeputy() internal view -``` - -## StakerGovernor - -### VETO_POWER - -```solidity -bytes32 VETO_POWER -``` - -### manager - -```solidity -address manager -``` - -### constructor - -```solidity -constructor(contract IVotesHistory _staking, contract TimelockController _timelock, contract TokenholderGovernor tokenholderGovernor, address vetoer) public -``` - -### cancel - -```solidity -function cancel(address[] targets, uint256[] values, bytes[] calldatas, bytes32 descriptionHash) external returns (uint256) -``` - -### propose - -```solidity -function propose(address[] targets, uint256[] values, bytes[] calldatas, string description) public returns (uint256) -``` - -### quorum - -```solidity -function quorum(uint256 blockNumber) public view returns (uint256) -``` - -### proposalThreshold - -```solidity -function proposalThreshold() public view returns (uint256) -``` - -### getVotes - -```solidity -function getVotes(address account, uint256 blockNumber) public view returns (uint256) -``` - -### state - -```solidity -function state(uint256 proposalId) public view returns (enum IGovernor.ProposalState) -``` - -### supportsInterface - -```solidity -function supportsInterface(bytes4 interfaceId) public view returns (bool) -``` - -### _execute - -```solidity -function _execute(uint256 proposalId, address[] targets, uint256[] values, bytes[] calldatas, bytes32 descriptionHash) internal -``` - -### _cancel - -```solidity -function _cancel(address[] targets, uint256[] values, bytes[] calldatas, bytes32 descriptionHash) internal returns (uint256) -``` - -### _executor - -```solidity -function _executor() internal view returns (address) -``` - -Returns the address of the entity that acts as governance for -this contract. - -By default, Governor assumes this is either the Governor contract -itself, or a timelock if there's one configured. We override this -here for the StakerGovernor contract so it's the Tokenholder DAO's -Timelock, which we obtain at constructor time. - -## StakerGovernorVotes - -Staker DAO voting power extraction from staked T positions, - -### staking - -```solidity -contract IVotesHistory staking -``` - -### constructor - -```solidity -constructor(contract IVotesHistory tStakingAddress) internal -``` - -### getVotes - -```solidity -function getVotes(address account, uint256 blockNumber) public view virtual returns (uint256) -``` - -Read the voting weight from the snapshot mechanism in the T -staking contracts. Note that this also tracks legacy stakes -(NU/KEEP). - -See {IGovernor-getVotes} - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| account | address | Delegate account with T staking voting power | -| blockNumber | uint256 | The block number to get the vote balance at | - -### _getPastTotalSupply - -```solidity -function _getPastTotalSupply(uint256 blockNumber) internal view virtual returns (uint256) -``` - -Compute the total voting power for the Staker DAO. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| blockNumber | uint256 | The block number to get the voting power at | - -## TokenholderGovernor - -### constructor - -```solidity -constructor(contract T _token, contract IVotesHistory _staking, contract TimelockController _timelock, address vetoer) public -``` - -## TokenholderGovernorVotes - -Tokenholder DAO voting power extraction from both liquid and staked -T token positions, including legacy stakes (NU/KEEP). - -### token - -```solidity -contract IVotesHistory token -``` - -### staking - -```solidity -contract IVotesHistory staking -``` - -### constructor - -```solidity -constructor(contract IVotesHistory tokenAddress, contract IVotesHistory tStakingAddress) internal -``` - -### getVotes - -```solidity -function getVotes(address account, uint256 blockNumber) public view virtual returns (uint256) -``` - -Read the voting weight from the snapshot mechanism in the token -and staking contracts. For Tokenholder DAO, there are currently -two voting power sources: -- Liquid T, tracked by the T token contract -- Stakes in the T network, tracked by the T staking contract. -Note that this also tracks legacy stakes (NU/KEEP); legacy -stakes count for tokenholders' voting power, but not for the -total voting power of the Tokenholder DAO -(see {_getPastTotalSupply}). - -See {IGovernor-getVotes} - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| account | address | Tokenholder account in the T network | -| blockNumber | uint256 | The block number to get the vote balance at | - -### _getPastTotalSupply - -```solidity -function _getPastTotalSupply(uint256 blockNumber) internal view virtual returns (uint256) -``` - -Compute the total voting power for Tokenholder DAO. Note how it -only uses the token total supply as source, as native T tokens -that are staked continue existing, but as deposits in the -staking contract. However, legacy stakes can't contribute to the -total voting power as they're already implicitly counted as part -of Vending Machines' liquid balance; hence, we only need to read -total voting power from the token. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| blockNumber | uint256 | The block number to get the vote power at | - -## IApplication - -Generic interface for an application. Application is an external -smart contract or a set of smart contracts utilizing functionalities -offered by Threshold Network. Applications authorized for the given -staking provider are eligible to slash the stake delegated to that -staking provider. - -### RewardsWithdrawn - -```solidity -event RewardsWithdrawn(address stakingProvider, uint96 amount) -``` - -Event emitted by `withdrawRewards` function. - -### 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. - -Emits `RewardsWithdrawn` event. - -### authorizationIncreased - -```solidity -function authorizationIncreased(address stakingProvider, uint96 fromAmount, uint96 toAmount) external -``` - -Used by T staking contract to inform the application that the -authorized amount for the given staking provider increased. -The application may do any necessary housekeeping. The -application must revert the transaction in case the -authorization is below the minimum required. - -### 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. The application should mark the authorization as -pending decrease and respond to the staking contract with -`approveAuthorizationDecrease` at its discretion. It may -happen right away but it also may happen several months later. -If there is already a pending authorization decrease request -for the application, and the application does not agree for -overwriting it, the function should revert. - -### 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. Lets the application to -do any housekeeping neccessary. Called with 250k gas limit and -does not revert the transaction if -`involuntaryAuthorizationDecrease` call failed. - -### availableRewards - -```solidity -function availableRewards(address stakingProvider) external view returns (uint96) -``` - -Returns the amount of application rewards available for -withdrawal for the given staking provider. - -### minimumAuthorization - -```solidity -function minimumAuthorization() external view returns (uint96) -``` - -The minimum authorization amount required for the staking -provider so that they can participate in the application. - -## IKeepTokenStaking - -Interface for Keep TokenStaking contract - -### seize - -```solidity -function seize(uint256 amountToSeize, uint256 rewardMultiplier, address tattletale, address[] misbehavedOperators) external -``` - -Seize provided token amount from every member in the misbehaved -operators array. The tattletale is rewarded with 5% of the total seized -amount scaled by the reward adjustment parameter and the rest 95% is burned. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| amountToSeize | uint256 | Token amount to seize from every misbehaved operator. | -| rewardMultiplier | uint256 | Reward adjustment in percentage. Min 1% and 100% max. | -| tattletale | address | Address to receive the 5% reward. | -| misbehavedOperators | address[] | Array of addresses to seize the tokens from. | - -### getDelegationInfo - -```solidity -function getDelegationInfo(address operator) external view returns (uint256 amount, uint256 createdAt, uint256 undelegatedAt) -``` - -Gets stake delegation info for the given operator. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| operator | address | Operator address. | - -#### Return Values - -| Name | Type | Description | -| ---- | ---- | ----------- | -| amount | uint256 | The amount of tokens the given operator delegated. | -| createdAt | uint256 | The time when the stake has been delegated. | -| undelegatedAt | uint256 | The time when undelegation has been requested. If undelegation has not been requested, 0 is returned. | - -### ownerOf - -```solidity -function ownerOf(address operator) external view returns (address) -``` - -Gets the stake owner for the specified operator address. - -#### Return Values - -| Name | Type | Description | -| ---- | ---- | ----------- | -| [0] | address | Stake owner address. | - -### beneficiaryOf - -```solidity -function beneficiaryOf(address operator) external view returns (address payable) -``` - -Gets the beneficiary for the specified operator address. - -#### Return Values - -| Name | Type | Description | -| ---- | ---- | ----------- | -| [0] | address payable | Beneficiary address. | - -### authorizerOf - -```solidity -function authorizerOf(address operator) external view returns (address) -``` - -Gets the authorizer for the specified operator address. - -#### Return Values - -| Name | Type | Description | -| ---- | ---- | ----------- | -| [0] | address | Authorizer address. | - -### eligibleStake - -```solidity -function eligibleStake(address operator, address operatorContract) external view returns (uint256 balance) -``` - -Gets the eligible stake balance of the specified address. -An eligible stake is a stake that passed the initialization period -and is not currently undelegating. Also, the operator had to approve -the specified operator contract. - -Operator with a minimum required amount of eligible stake can join the -network and participate in new work selection. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| operator | address | address of stake operator. | -| operatorContract | address | address of operator contract. | - -#### Return Values - -| Name | Type | Description | -| ---- | ---- | ----------- | -| balance | uint256 | an uint256 representing the eligible stake balance. | - -## INuCypherStakingEscrow - -Interface for NuCypher StakingEscrow contract - -### slashStaker - -```solidity -function slashStaker(address staker, uint256 penalty, address investigator, uint256 reward) external -``` - -Slash the staker's stake and reward the investigator - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| staker | address | Staker's address | -| penalty | uint256 | Penalty | -| investigator | address | Investigator | -| reward | uint256 | Reward for the investigator | - -### requestMerge - -```solidity -function requestMerge(address staker, address stakingProvider) external returns (uint256) -``` - -Request merge between NuCypher staking contract and T staking contract. -Returns amount of staked tokens - -### getAllTokens - -```solidity -function getAllTokens(address staker) external view returns (uint256) -``` - -Get all tokens belonging to the staker - -## IStaking - -The staking contract enables T owners to have their wallets offline -and their stake managed by staking providers on their behalf. -The staking contract does not define operator role. The operator -responsible for running off-chain client software is appointed by -the staking provider in the particular application utilizing the -staking contract. All off-chain client software should be able -to run without exposing operator's or staking provider’s private -key and should not require any owner’s keys at all. The stake -delegation optimizes the network throughput without compromising the -security of the owners’ stake. - -### StakeType - -```solidity -enum StakeType { - NU, - KEEP, - T -} -``` - -### stake - -```solidity -function stake(address stakingProvider, address payable beneficiary, address authorizer, uint96 amount) external -``` - -Creates a delegation with `msg.sender` owner with the given -staking provider, beneficiary, and authorizer. Transfers the -given amount of T to the staking contract. - -The owner of the delegation needs to have the amount approved to -transfer to the staking contract. - -### stakeKeep - -```solidity -function stakeKeep(address stakingProvider) external -``` - -Copies delegation from the legacy KEEP staking contract to T -staking contract. No tokens are transferred. Caches the active -stake amount from KEEP staking contract. Can be called by -anyone. - -The staking provider in T staking contract is the legacy KEEP -staking contract operator. - -### stakeNu - -```solidity -function stakeNu(address stakingProvider, address payable beneficiary, address authorizer) external -``` - -Copies delegation from the legacy NU staking contract to T -staking contract, additionally appointing staking provider, -beneficiary and authorizer roles. Caches the amount staked in NU -staking contract. Can be called only by the original delegation -owner. - -### setMinimumStakeAmount - -```solidity -function setMinimumStakeAmount(uint96 amount) external -``` - -Allows the Governance to set the minimum required stake amount. -This amount is required to protect against griefing the staking -contract and individual applications are allowed to require -higher minimum stakes if necessary. - -### approveApplication - -```solidity -function approveApplication(address application) external -``` - -Allows the Governance to approve the particular application -before individual stake authorizers are able to authorize it. - -### increaseAuthorization - -```solidity -function increaseAuthorization(address stakingProvider, address application, uint96 amount) external -``` - -Increases the authorization of the given staking provider for -the given application by the given amount. Can only be called by -the authorizer for that staking provider. - -Calls `authorizationIncreased(address stakingProvider, uint256 amount)` -on the given application to notify the application about -authorization change. See `IApplication`. - -### requestAuthorizationDecrease - -```solidity -function requestAuthorizationDecrease(address stakingProvider, address application, uint96 amount) external -``` - -Requests decrease of the authorization for the given staking -provider on the given application by the provided amount. -It may not change the authorized amount immediatelly. When -it happens depends on the application. Can only be called by the -given staking provider’s authorizer. Overwrites pending -authorization decrease for the given staking provider and -application if the application agrees for that. If the -application does not agree for overwriting, the function -reverts. - -Calls `authorizationDecreaseRequested(address stakingProvider, uint256 amount)` -on the given application. See `IApplication`. - -### requestAuthorizationDecrease - -```solidity -function requestAuthorizationDecrease(address stakingProvider) external -``` - -Requests decrease of all authorizations for the given staking -provider on all applications by all authorized amount. -It may not change the authorized amount immediatelly. When -it happens depends on the application. Can only be called by the -given staking provider’s authorizer. Overwrites pending -authorization decrease for the given staking provider and -application. - -Calls `authorizationDecreaseRequested(address stakingProvider, uint256 amount)` -for each authorized application. See `IApplication`. - -### approveAuthorizationDecrease - -```solidity -function approveAuthorizationDecrease(address stakingProvider) external returns (uint96) -``` - -Called by the application at its discretion to approve the -previously requested authorization decrease request. Can only be -called by the application that was previously requested to -decrease the authorization for that staking provider. -Returns resulting authorized amount for the application. - -### forceDecreaseAuthorization - -```solidity -function forceDecreaseAuthorization(address stakingProvider, address application) external -``` - -Decreases the authorization for the given `stakingProvider` on -the given disabled `application`, for all authorized amount. -Can be called by anyone. - -### pauseApplication - -```solidity -function pauseApplication(address application) external -``` - -Pauses the given application’s eligibility to slash stakes. -Besides that stakers can't change authorization to the application. -Can be called only by the Panic Button of the particular -application. The paused application can not slash stakes until -it is approved again by the Governance using `approveApplication` -function. Should be used only in case of an emergency. - -### disableApplication - -```solidity -function disableApplication(address application) external -``` - -Disables the given application. The disabled application can't -slash stakers. Also stakers can't increase authorization to that -application but can decrease without waiting by calling -`requestAuthorizationDecrease` at any moment. Can be called only -by the governance. The disabled application can't be approved -again. Should be used only in case of an emergency. - -### setPanicButton - -```solidity -function setPanicButton(address application, address panicButton) external -``` - -Sets the Panic Button role for the given application to the -provided address. Can only be called by the Governance. If the -Panic Button for the given application should be disabled, the -role address should be set to 0x0 address. - -### setAuthorizationCeiling - -```solidity -function setAuthorizationCeiling(uint256 ceiling) external -``` - -Sets the maximum number of applications one staking provider can -have authorized. Used to protect against DoSing slashing queue. -Can only be called by the Governance. - -### topUp - -```solidity -function topUp(address stakingProvider, uint96 amount) external -``` - -Increases the amount of the stake for the given staking provider. - -The sender of this transaction needs to have the amount approved to -transfer to the staking contract. - -### topUpKeep - -```solidity -function topUpKeep(address stakingProvider) external -``` - -Propagates information about stake top-up from the legacy KEEP -staking contract to T staking contract. Can be called only by -the owner or the staking provider. - -### topUpNu - -```solidity -function topUpNu(address stakingProvider) external -``` - -Propagates information about stake top-up from the legacy NU -staking contract to T staking contract. Can be called only by -the owner or the staking provider. - -### unstakeT - -```solidity -function unstakeT(address stakingProvider, uint96 amount) external -``` - -Reduces the liquid T stake amount by the provided amount and -withdraws T to the owner. Reverts if there is at least one -authorization higher than the sum of the legacy stake and -remaining liquid T stake or if the unstake amount is higher than -the liquid T stake amount. Can be called only by the delegation -owner or the staking provider. - -### unstakeKeep - -```solidity -function unstakeKeep(address stakingProvider) external -``` - -Sets the legacy KEEP staking contract active stake amount cached -in T staking contract to 0. Reverts if the amount of liquid T -staked in T staking contract is lower than the highest -application authorization. This function allows to unstake from -KEEP staking contract and still being able to operate in T -network and earning rewards based on the liquid T staked. Can be -called only by the delegation owner or the staking provider. - -### unstakeNu - -```solidity -function unstakeNu(address stakingProvider, uint96 amount) external -``` - -Reduces cached legacy NU stake amount by the provided amount. -Reverts if there is at least one authorization higher than the -sum of remaining legacy NU stake and liquid T stake for that -staking provider or if the untaked amount is higher than the -cached legacy stake amount. If succeeded, the legacy NU stake -can be partially or fully undelegated on the legacy staking -contract. This function allows to unstake from NU staking -contract and still being able to operate in T network and -earning rewards based on the liquid T staked. Can be called only -by the delegation owner or the staking provider. - -### unstakeAll - -```solidity -function unstakeAll(address stakingProvider) external -``` - -Sets cached legacy stake amount to 0, sets the liquid T stake -amount to 0 and withdraws all liquid T from the stake to the -owner. Reverts if there is at least one non-zero authorization. -Can be called only by the delegation owner or the staking -provider. - -### notifyKeepStakeDiscrepancy - -```solidity -function notifyKeepStakeDiscrepancy(address stakingProvider) external -``` - -Notifies about the discrepancy between legacy KEEP active stake -and the amount cached in T staking contract. Slashes the staking -provider in case the amount cached is higher than the actual -active stake amount in KEEP staking contract. Needs to update -authorizations of all affected applications and execute an -involuntary allocation decrease on all affected applications. -Can be called by anyone, notifier receives a reward. - -### notifyNuStakeDiscrepancy - -```solidity -function notifyNuStakeDiscrepancy(address stakingProvider) external -``` - -Notifies about the discrepancy between legacy NU active stake -and the amount cached in T staking contract. Slashes the -staking provider in case the amount cached is higher than the -actual active stake amount in NU staking contract. Needs to -update authorizations of all affected applications and execute -an involuntary allocation decrease on all affected applications. -Can be called by anyone, notifier receives a reward. - -### setStakeDiscrepancyPenalty - -```solidity -function setStakeDiscrepancyPenalty(uint96 penalty, uint256 rewardMultiplier) external -``` - -Sets the penalty amount for stake discrepancy and reward -multiplier for reporting it. The penalty is seized from the -delegated stake, and 5% of the penalty, scaled by the -multiplier, is given to the notifier. The rest of the tokens are -burned. Can only be called by the Governance. See `seize` function. - -### setNotificationReward - -```solidity -function setNotificationReward(uint96 reward) external -``` - -Sets reward in T tokens for notification of misbehaviour -of one staking provider. Can only be called by the governance. - -### pushNotificationReward - -```solidity -function pushNotificationReward(uint96 reward) external -``` - -Transfer some amount of T tokens as reward for notifications -of misbehaviour - -### withdrawNotificationReward - -```solidity -function withdrawNotificationReward(address recipient, uint96 amount) external -``` - -Withdraw some amount of T tokens from notifiers treasury. -Can only be called by the governance. - -### slash - -```solidity -function slash(uint96 amount, address[] stakingProviders) external -``` - -Adds staking providers to the slashing queue along with the -amount that should be slashed from each one of them. Can only be -called by application authorized for all staking providers in -the array. - -### seize - -```solidity -function seize(uint96 amount, uint256 rewardMultipier, address notifier, address[] stakingProviders) external -``` - -Adds staking providers to the slashing queue along with the -amount. The notifier will receive reward per each staking -provider from notifiers treasury. Can only be called by -application authorized for all staking providers in the array. - -### processSlashing - -```solidity -function processSlashing(uint256 count) external -``` - -Takes the given number of queued slashing operations and -processes them. Receives 5% of the slashed amount. -Executes `involuntaryAllocationDecrease` function on each -affected application. - -### authorizedStake - -```solidity -function authorizedStake(address stakingProvider, address application) external view returns (uint96) -``` - -Returns the authorized stake amount of the staking provider for -the application. - -### stakes - -```solidity -function stakes(address stakingProvider) external view returns (uint96 tStake, uint96 keepInTStake, uint96 nuInTStake) -``` - -Returns staked amount of T, Keep and Nu for the specified -staking provider. - -All values are in T denomination - -### getStartStakingTimestamp - -```solidity -function getStartStakingTimestamp(address stakingProvider) external view returns (uint256) -``` - -Returns start staking timestamp. - -This value is set at most once. - -### stakedNu - -```solidity -function stakedNu(address stakingProvider) external view returns (uint256) -``` - -Returns staked amount of NU for the specified staking provider. - -### rolesOf - -```solidity -function rolesOf(address stakingProvider) external view returns (address owner, address payable beneficiary, address authorizer) -``` - -Gets the stake owner, the beneficiary and the authorizer -for the specified staking provider address. - -#### Return Values - -| Name | Type | Description | -| ---- | ---- | ----------- | -| owner | address | Stake owner address. | -| beneficiary | address payable | Beneficiary address. | -| authorizer | address | Authorizer address. | - -### getApplicationsLength - -```solidity -function getApplicationsLength() external view returns (uint256) -``` - -Returns length of application array - -### getSlashingQueueLength - -```solidity -function getSlashingQueueLength() external view returns (uint256) -``` - -Returns length of slashing queue - -### getMinStaked - -```solidity -function getMinStaked(address stakingProvider, enum IStaking.StakeType stakeTypes) external view returns (uint96) -``` - -Returns minimum possible stake for T, KEEP or NU in T -denomination. - -For example, suppose the given staking provider has 10 T, 20 T -worth of KEEP, and 30 T worth of NU all staked, and the maximum -application authorization is 40 T, then `getMinStaked` for -that staking provider returns: -* 0 T if KEEP stake type specified i.e. -min = 40 T max - (10 T + 30 T worth of NU) = 0 T -* 10 T if NU stake type specified i.e. -min = 40 T max - (10 T + 20 T worth of KEEP) = 10 T -* 0 T if T stake type specified i.e. -min = 40 T max - (20 T worth of KEEP + 30 T worth of NU) < 0 T -In other words, the minimum stake amount for the specified -stake type is the minimum amount of stake of the given type -needed to satisfy the maximum application authorization given the -staked amounts of the other stake types for that staking provider. - -### getAvailableToAuthorize - -```solidity -function getAvailableToAuthorize(address stakingProvider, address application) external view returns (uint96) -``` - -Returns available amount to authorize for the specified application - -## IManagedGrant - -### grantee - -```solidity -function grantee() external view returns (address) -``` - -## KeepStake - -T network staking contract supports existing KEEP stakes by allowing -KEEP stakers to use their stakes in T network and weights them based -on KEEP<>T token ratio. KEEP stake owner is cached in T staking -contract and used to restrict access to all functions only owner or -operator should call. To cache KEEP stake owner in T staking -contract, T staking contract first needs to resolve the owner. - -Resolving liquid KEEP stake owner is easy. Resolving token grant -stake owner is complicated and not possible to do on-chain from -a contract external to KEEP TokenStaking contract. Keep TokenStaking -knows the grant ID but does not expose it externally. - -KeepStake contract addresses this problem by exposing -operator-owner mappings snapshotted off-chain based on events and -information publicly available from KEEP TokenStaking contract and -KEEP TokenGrant contract. Additionally, it gives the Governance -ability to add new mappings in case they are ever needed; in -practice, this will be needed only if someone decides to stake their -KEEP token grant in KEEP network after 2021-11-11 when the snapshot -was taken. - -Operator-owner pairs were snapshotted 2021-11-11 in the following -way: -1. Fetch all TokenStaking events from KEEP staking contract. -2. Filter out undelegated operators. -3. Filter out canceled delegations. -4. Fetch grant stake information from KEEP TokenGrant for that -operator to determine if we are dealing with grant delegation. -5. Fetch grantee address from KEEP TokenGrant contract. -6. Check if we are dealing with ManagedGrant by looking for all -created ManagedGrants and comparing their address against grantee -address fetched from TokenGrant contract. - -### keepTokenStaking - -```solidity -contract IKeepTokenStaking keepTokenStaking -``` - -### operatorToManagedGrant - -```solidity -mapping(address => address) operatorToManagedGrant -``` - -### operatorToGrantee - -```solidity -mapping(address => address) operatorToGrantee -``` - -### constructor - -```solidity -constructor(contract IKeepTokenStaking _keepTokenStaking) public -``` - -### setManagedGrant - -```solidity -function setManagedGrant(address operator, address managedGrant) external -``` - -Allows the Governance to set new operator-managed grant pair. -This function should only be called for managed grants if -the snapshot does include this pair. - -### setGrantee - -```solidity -function setGrantee(address operator, address grantee) external -``` - -Allows the Governance to set new operator-grantee pair. -This function should only be called for non-managed grants if -the snapshot does include this pair. - -### resolveOwner - -```solidity -function resolveOwner(address operator) external view returns (address) -``` - -Resolves KEEP stake owner for the provided operator address. -Reverts if could not resolve the owner. - -### resolveSnapshottedManagedGrantees - -```solidity -function resolveSnapshottedManagedGrantees(address operator) internal view returns (address) -``` - -### resolveSnapshottedGrantees - -```solidity -function resolveSnapshottedGrantees(address operator) internal pure returns (address) -``` - -## TokenStaking - -TokenStaking is the main staking contract of the Threshold Network. -Apart from the basic usage of enabling T stakes, it also acts as a -sort of "meta-staking" contract, accepting existing legacy NU/KEEP -stakes. Additionally, it serves as application manager for the apps -that run on the Threshold Network. Note that legacy NU/KEEP staking -contracts see TokenStaking as an application (e.g., slashing is -requested by TokenStaking and performed by the legacy contracts). - -TokenStaking is upgradeable, using OpenZeppelin's Upgradeability -framework. As such, it is required to satisfy OZ's guidelines, like -restrictions on constructors, immutable variables, base contracts and -libraries. See https://docs.openzeppelin.com/upgrades-plugins/1.x/writing-upgradeable - -### ApplicationStatus - -```solidity -enum ApplicationStatus { - NOT_APPROVED, - APPROVED, - PAUSED, - DISABLED -} -``` - -### StakingProviderInfo - -```solidity -struct StakingProviderInfo { - uint96 nuInTStake; - address owner; - uint96 keepInTStake; - address payable beneficiary; - uint96 tStake; - address authorizer; - mapping(address => struct TokenStaking.AppAuthorization) authorizations; - address[] authorizedApplications; - uint256 startStakingTimestamp; -} -``` - -### AppAuthorization - -```solidity -struct AppAuthorization { - uint96 authorized; - uint96 deauthorizing; -} -``` - -### ApplicationInfo - -```solidity -struct ApplicationInfo { - enum TokenStaking.ApplicationStatus status; - address panicButton; -} -``` - -### SlashingEvent - -```solidity -struct SlashingEvent { - address stakingProvider; - uint96 amount; -} -``` - -### SLASHING_REWARD_PERCENT - -```solidity -uint256 SLASHING_REWARD_PERCENT -``` - -### MIN_STAKE_TIME - -```solidity -uint256 MIN_STAKE_TIME -``` - -### GAS_LIMIT_AUTHORIZATION_DECREASE - -```solidity -uint256 GAS_LIMIT_AUTHORIZATION_DECREASE -``` - -### CONVERSION_DIVISOR - -```solidity -uint256 CONVERSION_DIVISOR -``` - -### token - -```solidity -contract T token -``` - -### keepStakingContract - -```solidity -contract IKeepTokenStaking keepStakingContract -``` - -### keepStake - -```solidity -contract KeepStake keepStake -``` - -### nucypherStakingContract - -```solidity -contract INuCypherStakingEscrow nucypherStakingContract -``` - -### keepRatio - -```solidity -uint256 keepRatio -``` - -### nucypherRatio - -```solidity -uint256 nucypherRatio -``` - -### governance - -```solidity -address governance -``` - -### minTStakeAmount - -```solidity -uint96 minTStakeAmount -``` - -### authorizationCeiling - -```solidity -uint256 authorizationCeiling -``` - -### stakeDiscrepancyPenalty - -```solidity -uint96 stakeDiscrepancyPenalty -``` - -### stakeDiscrepancyRewardMultiplier - -```solidity -uint256 stakeDiscrepancyRewardMultiplier -``` - -### notifiersTreasury - -```solidity -uint256 notifiersTreasury -``` - -### notificationReward - -```solidity -uint256 notificationReward -``` - -### stakingProviders - -```solidity -mapping(address => struct TokenStaking.StakingProviderInfo) stakingProviders -``` - -### applicationInfo - -```solidity -mapping(address => struct TokenStaking.ApplicationInfo) applicationInfo -``` - -### applications - -```solidity -address[] applications -``` - -### slashingQueue - -```solidity -struct TokenStaking.SlashingEvent[] slashingQueue -``` - -### slashingQueueIndex - -```solidity -uint256 slashingQueueIndex -``` - -### Staked - -```solidity -event Staked(enum IStaking.StakeType stakeType, address owner, address stakingProvider, address beneficiary, address authorizer, uint96 amount) -``` - -### MinimumStakeAmountSet - -```solidity -event MinimumStakeAmountSet(uint96 amount) -``` - -### ApplicationStatusChanged - -```solidity -event ApplicationStatusChanged(address application, enum TokenStaking.ApplicationStatus newStatus) -``` - -### AuthorizationIncreased - -```solidity -event AuthorizationIncreased(address stakingProvider, address application, uint96 fromAmount, uint96 toAmount) -``` - -### AuthorizationDecreaseRequested - -```solidity -event AuthorizationDecreaseRequested(address stakingProvider, address application, uint96 fromAmount, uint96 toAmount) -``` - -### AuthorizationDecreaseApproved - -```solidity -event AuthorizationDecreaseApproved(address stakingProvider, address application, uint96 fromAmount, uint96 toAmount) -``` - -### AuthorizationInvoluntaryDecreased - -```solidity -event AuthorizationInvoluntaryDecreased(address stakingProvider, address application, uint96 fromAmount, uint96 toAmount, bool successfulCall) -``` - -### PanicButtonSet - -```solidity -event PanicButtonSet(address application, address panicButton) -``` - -### AuthorizationCeilingSet - -```solidity -event AuthorizationCeilingSet(uint256 ceiling) -``` - -### ToppedUp - -```solidity -event ToppedUp(address stakingProvider, uint96 amount) -``` - -### Unstaked - -```solidity -event Unstaked(address stakingProvider, uint96 amount) -``` - -### TokensSeized - -```solidity -event TokensSeized(address stakingProvider, uint96 amount, bool discrepancy) -``` - -### StakeDiscrepancyPenaltySet - -```solidity -event StakeDiscrepancyPenaltySet(uint96 penalty, uint256 rewardMultiplier) -``` - -### NotificationRewardSet - -```solidity -event NotificationRewardSet(uint96 reward) -``` - -### NotificationRewardPushed - -```solidity -event NotificationRewardPushed(uint96 reward) -``` - -### NotificationRewardWithdrawn - -```solidity -event NotificationRewardWithdrawn(address recipient, uint96 amount) -``` - -### NotifierRewarded - -```solidity -event NotifierRewarded(address notifier, uint256 amount) -``` - -### SlashingProcessed - -```solidity -event SlashingProcessed(address caller, uint256 count, uint256 tAmount) -``` - -### OwnerRefreshed - -```solidity -event OwnerRefreshed(address stakingProvider, address oldOwner, address newOwner) -``` - -### GovernanceTransferred - -```solidity -event GovernanceTransferred(address oldGovernance, address newGovernance) -``` - -### onlyGovernance - -```solidity -modifier onlyGovernance() -``` - -### onlyPanicButtonOf - -```solidity -modifier onlyPanicButtonOf(address application) -``` - -### onlyAuthorizerOf - -```solidity -modifier onlyAuthorizerOf(address stakingProvider) -``` - -### onlyOwnerOrStakingProvider - -```solidity -modifier onlyOwnerOrStakingProvider(address stakingProvider) -``` - -### onlyOwnerOf - -```solidity -modifier onlyOwnerOf(address stakingProvider) -``` - -### constructor - -```solidity -constructor(contract T _token, contract IKeepTokenStaking _keepStakingContract, contract INuCypherStakingEscrow _nucypherStakingContract, contract VendingMachine _keepVendingMachine, contract VendingMachine _nucypherVendingMachine, contract KeepStake _keepStake) public -``` - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| _token | contract T | Address of T token contract | -| _keepStakingContract | contract IKeepTokenStaking | Address of Keep staking contract | -| _nucypherStakingContract | contract INuCypherStakingEscrow | Address of NuCypher staking contract | -| _keepVendingMachine | contract VendingMachine | Address of Keep vending machine | -| _nucypherVendingMachine | contract VendingMachine | Address of NuCypher vending machine | -| _keepStake | contract KeepStake | Address of Keep contract with grant owners | - -### initialize - -```solidity -function initialize() external -``` - -### stake - -```solidity -function stake(address stakingProvider, address payable beneficiary, address authorizer, uint96 amount) external -``` - -Creates a delegation with `msg.sender` owner with the given -staking provider, beneficiary, and authorizer. Transfers the -given amount of T to the staking contract. - -The owner of the delegation needs to have the amount approved to -transfer to the staking contract. - -### stakeKeep - -```solidity -function stakeKeep(address stakingProvider) external -``` - -Copies delegation from the legacy KEEP staking contract to T -staking contract. No tokens are transferred. Caches the active -stake amount from KEEP staking contract. Can be called by -anyone. - -The staking provider in T staking contract is the legacy KEEP -staking contract operator. - -### stakeNu - -```solidity -function stakeNu(address stakingProvider, address payable beneficiary, address authorizer) external -``` - -Copies delegation from the legacy NU staking contract to T -staking contract, additionally appointing beneficiary and -authorizer roles. Caches the amount staked in NU staking -contract. Can be called only by the original delegation owner. - -### setMinimumStakeAmount - -```solidity -function setMinimumStakeAmount(uint96 amount) external -``` - -Allows the Governance to set the minimum required stake amount. -This amount is required to protect against griefing the staking -contract and individual applications are allowed to require -higher minimum stakes if necessary. - -Staking providers are not required to maintain a minimum T stake -all the time. 24 hours after the delegation, T stake can be reduced -below the minimum stake. The minimum stake in the staking contract -is just to protect against griefing stake operation. Please note -that each application may have its own minimum authorization though -and the authorization can not be higher than the stake. - -### approveApplication - -```solidity -function approveApplication(address application) external -``` - -Allows the Governance to approve the particular application -before individual stake authorizers are able to authorize it. - -### increaseAuthorization - -```solidity -function increaseAuthorization(address stakingProvider, address application, uint96 amount) external -``` - -Increases the authorization of the given staking provider for -the given application by the given amount. Can only be called by -the given staking provider’s authorizer. - -Calls `authorizationIncreased` callback on the given application to -notify the application about authorization change. -See `IApplication`. - -### requestAuthorizationDecrease - -```solidity -function requestAuthorizationDecrease(address stakingProvider) external -``` - -Requests decrease of all authorizations for the given staking -provider on all applications by all authorized amount. -It may not change the authorized amount immediatelly. When -it happens depends on the application. Can only be called by the -given staking provider’s authorizer. Overwrites pending -authorization decrease for the given staking provider and -application. - -Calls `authorizationDecreaseRequested` callback -for each authorized application. See `IApplication`. - -### approveAuthorizationDecrease - -```solidity -function approveAuthorizationDecrease(address stakingProvider) external returns (uint96) -``` - -Called by the application at its discretion to approve the -previously requested authorization decrease request. Can only be -called by the application that was previously requested to -decrease the authorization for that staking provider. -Returns resulting authorized amount for the application. - -### forceDecreaseAuthorization - -```solidity -function forceDecreaseAuthorization(address stakingProvider, address application) external -``` - -Decreases the authorization for the given `stakingProvider` on -the given disabled `application`, for all authorized amount. -Can be called by anyone. - -### pauseApplication - -```solidity -function pauseApplication(address application) external -``` - -Pauses the given application’s eligibility to slash stakes. -Besides that stakers can't change authorization to the application. -Can be called only by the Panic Button of the particular -application. The paused application can not slash stakes until -it is approved again by the Governance using `approveApplication` -function. Should be used only in case of an emergency. - -### disableApplication - -```solidity -function disableApplication(address application) external -``` - -Disables the given application. The disabled application can't -slash stakers. Also stakers can't increase authorization to that -application but can decrease without waiting by calling -`forceDecreaseAuthorization` at any moment. Can be called only -by the governance. The disabled application can't be approved -again. Should be used only in case of an emergency. - -### setPanicButton - -```solidity -function setPanicButton(address application, address panicButton) external -``` - -Sets the Panic Button role for the given application to the -provided address. Can only be called by the Governance. If the -Panic Button for the given application should be disabled, the -role address should be set to 0x0 address. - -### setAuthorizationCeiling - -```solidity -function setAuthorizationCeiling(uint256 ceiling) external -``` - -Sets the maximum number of applications one staking provider can -have authorized. Used to protect against DoSing slashing queue. -Can only be called by the Governance. - -### topUp - -```solidity -function topUp(address stakingProvider, uint96 amount) external -``` - -Increases the amount of the stake for the given staking provider. - -The sender of this transaction needs to have the amount approved to -transfer to the staking contract. - -### topUpKeep - -```solidity -function topUpKeep(address stakingProvider) external -``` - -Propagates information about stake top-up from the legacy KEEP -staking contract to T staking contract. Can be called only by -the owner or the staking provider. - -### topUpNu - -```solidity -function topUpNu(address stakingProvider) external -``` - -Propagates information about stake top-up from the legacy NU -staking contract to T staking contract. Can be called only by -the owner or the staking provider. - -### unstakeT - -```solidity -function unstakeT(address stakingProvider, uint96 amount) external -``` - -Reduces the liquid T stake amount by the provided amount and -withdraws T to the owner. Reverts if there is at least one -authorization higher than the sum of the legacy stake and -remaining liquid T stake or if the unstake amount is higher than -the liquid T stake amount. Can be called only by the owner or -the staking provider. Can only be called when 24h passed since -the stake has been delegated. - -### unstakeKeep - -```solidity -function unstakeKeep(address stakingProvider) external -``` - -Sets the legacy KEEP staking contract active stake amount cached -in T staking contract to 0. Reverts if the amount of liquid T -staked in T staking contract is lower than the highest -application authorization. This function allows to unstake from -KEEP staking contract and still being able to operate in T -network and earning rewards based on the liquid T staked. Can be -called only by the delegation owner or the staking provider. -Can only be called when 24h passed since the stake has been -delegated. - -This function (or `unstakeAll`) must be called before -`undelegate`/`undelegateAt` in Keep staking contract. Otherwise -provider can be slashed by `notifyKeepStakeDiscrepancy` method. - -### unstakeNu - -```solidity -function unstakeNu(address stakingProvider, uint96 amount) external -``` - -Reduces cached legacy NU stake amount by the provided amount. -Reverts if there is at least one authorization higher than the -sum of remaining legacy NU stake and liquid T stake for that -staking provider or if the untaked amount is higher than the -cached legacy stake amount. If succeeded, the legacy NU stake -can be partially or fully undelegated on the legacy staking -contract. This function allows to unstake from NU staking -contract and still being able to operate in T network and -earning rewards based on the liquid T staked. Can be called only -by the delegation owner or the staking provider. Can only be -called when 24h passed since the stake has been delegated. - -This function (or `unstakeAll`) must be called before `withdraw` -in NuCypher staking contract. Otherwise NU tokens can't be -unlocked. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| stakingProvider | address | Staking provider address | -| amount | uint96 | Amount of NU to unstake in T denomination | - -### unstakeAll - -```solidity -function unstakeAll(address stakingProvider) external -``` - -Sets cached legacy stake amount to 0, sets the liquid T stake -amount to 0 and withdraws all liquid T from the stake to the -owner. Reverts if there is at least one non-zero authorization. -Can be called only by the delegation owner or the staking -provider. Can only be called when 24h passed since the stake -has been delegated. - -### notifyKeepStakeDiscrepancy - -```solidity -function notifyKeepStakeDiscrepancy(address stakingProvider) external -``` - -Notifies about the discrepancy between legacy KEEP active stake -and the amount cached in T staking contract. Slashes the staking -provider in case the amount cached is higher than the actual -active stake amount in KEEP staking contract. Needs to update -authorizations of all affected applications and execute an -involuntary authorization decrease on all affected applications. -Can be called by anyone, notifier receives a reward. - -### notifyNuStakeDiscrepancy - -```solidity -function notifyNuStakeDiscrepancy(address stakingProvider) external -``` - -Notifies about the discrepancy between legacy NU active stake -and the amount cached in T staking contract. Slashes the -staking provider in case the amount cached is higher than the -actual active stake amount in NU staking contract. Needs to -update authorizations of all affected applications and execute an -involuntary authorization decrease on all affected applications. -Can be called by anyone, notifier receives a reward. - -Real discrepancy between T and Nu is impossible. -This method is a safeguard in case of bugs in NuCypher staking -contract - -### setStakeDiscrepancyPenalty - -```solidity -function setStakeDiscrepancyPenalty(uint96 penalty, uint256 rewardMultiplier) external -``` - -Sets the penalty amount for stake discrepancy and reward -multiplier for reporting it. The penalty is seized from the -delegated stake, and 5% of the penalty, scaled by the -multiplier, is given to the notifier. The rest of the tokens are -burned. Can only be called by the Governance. See `seize` function. - -### setNotificationReward - -```solidity -function setNotificationReward(uint96 reward) external -``` - -Sets reward in T tokens for notification of misbehaviour -of one staking provider. Can only be called by the governance. - -### pushNotificationReward - -```solidity -function pushNotificationReward(uint96 reward) external -``` - -Transfer some amount of T tokens as reward for notifications -of misbehaviour - -### withdrawNotificationReward - -```solidity -function withdrawNotificationReward(address recipient, uint96 amount) external -``` - -Withdraw some amount of T tokens from notifiers treasury. -Can only be called by the governance. - -### slash - -```solidity -function slash(uint96 amount, address[] _stakingProviders) external -``` - -Adds staking providers to the slashing queue along with the -amount that should be slashed from each one of them. Can only be -called by application authorized for all staking providers in -the array. - -This method doesn't emit events for providers that are added to -the queue. If necessary events can be added to the application -level. - -### seize - -```solidity -function seize(uint96 amount, uint256 rewardMultiplier, address notifier, address[] _stakingProviders) external -``` - -Adds staking providers to the slashing queue along with the -amount. The notifier will receive reward per each provider from -notifiers treasury. Can only be called by application -authorized for all staking providers in the array. - -This method doesn't emit events for staking providers that are -added to the queue. If necessary events can be added to the -application level. - -### processSlashing - -```solidity -function processSlashing(uint256 count) external virtual -``` - -Takes the given number of queued slashing operations and -processes them. Receives 5% of the slashed amount. -Executes `involuntaryAuthorizationDecrease` function on each -affected application. - -### delegateVoting - -```solidity -function delegateVoting(address stakingProvider, address delegatee) external -``` - -Delegate voting power from the stake associated to the -`stakingProvider` to a `delegatee` address. Caller must be the -owner of this stake. - -### transferGovernance - -```solidity -function transferGovernance(address newGuvnor) external virtual -``` - -Transfers ownership of the contract to `newGuvnor`. - -### authorizedStake - -```solidity -function authorizedStake(address stakingProvider, address application) external view returns (uint96) -``` - -Returns the authorized stake amount of the staking provider for -the application. - -### stakes - -```solidity -function stakes(address stakingProvider) external view returns (uint96 tStake, uint96 keepInTStake, uint96 nuInTStake) -``` - -Returns staked amount of T, Keep and Nu for the specified -staking provider. - -All values are in T denomination - -### getStartStakingTimestamp - -```solidity -function getStartStakingTimestamp(address stakingProvider) external view returns (uint256) -``` - -Returns start staking timestamp. - -This value is set at most once. - -### stakedNu - -```solidity -function stakedNu(address stakingProvider) external view returns (uint256 nuAmount) -``` - -Returns staked amount of NU for the specified staking provider. - -### rolesOf - -```solidity -function rolesOf(address stakingProvider) external view returns (address owner, address payable beneficiary, address authorizer) -``` - -Gets the stake owner, the beneficiary and the authorizer -for the specified staking provider address. - -#### Return Values - -| Name | Type | Description | -| ---- | ---- | ----------- | -| owner | address | Stake owner address. | -| beneficiary | address payable | Beneficiary address. | -| authorizer | address | Authorizer address. | - -### getApplicationsLength - -```solidity -function getApplicationsLength() external view returns (uint256) -``` - -Returns length of application array - -### getSlashingQueueLength - -```solidity -function getSlashingQueueLength() external view returns (uint256) -``` - -Returns length of slashing queue - -### requestAuthorizationDecrease - -```solidity -function requestAuthorizationDecrease(address stakingProvider, address application, uint96 amount) public -``` - -Requests decrease of the authorization for the given staking -provider on the given application by the provided amount. -It may not change the authorized amount immediatelly. When -it happens depends on the application. Can only be called by the -given staking provider’s authorizer. Overwrites pending -authorization decrease for the given staking provider and -application if the application agrees for that. If the -application does not agree for overwriting, the function -reverts. - -Calls `authorizationDecreaseRequested` callback on the given -application. See `IApplication`. - -### getMinStaked - -```solidity -function getMinStaked(address stakingProvider, enum IStaking.StakeType stakeTypes) public view returns (uint96) -``` - -Returns minimum possible stake for T, KEEP or NU in T denomination - -For example, suppose the given staking provider has 10 T, 20 T worth -of KEEP, and 30 T worth of NU all staked, and the maximum -application authorization is 40 T, then `getMinStaked` for -that staking provider returns: -* 0 T if KEEP stake type specified i.e. -min = 40 T max - (10 T + 30 T worth of NU) = 0 T -* 10 T if NU stake type specified i.e. -min = 40 T max - (10 T + 20 T worth of KEEP) = 10 T -* 0 T if T stake type specified i.e. -min = 40 T max - (20 T worth of KEEP + 30 T worth of NU) < 0 T -In other words, the minimum stake amount for the specified -stake type is the minimum amount of stake of the given type -needed to satisfy the maximum application authorization given -the staked amounts of the other stake types for that staking -provider. - -### getAvailableToAuthorize - -```solidity -function getAvailableToAuthorize(address stakingProvider, address application) public view returns (uint96 availableTValue) -``` - -Returns available amount to authorize for the specified -application. - -### delegate - -```solidity -function delegate(address stakingProvider, address delegatee) internal virtual -``` - -Delegate voting power from the stake associated to the -`stakingProvider` to a `delegatee` address. Caller must be the owner -of this stake. - -Original abstract function defined in Checkpoints contract had two -parameters, `delegator` and `delegatee`. Here we override it and -comply with the same signature but the semantics of the first -parameter changes to the `stakingProvider` address. - -### notify - -```solidity -function notify(uint96 amount, uint256 rewardMultiplier, address notifier, address[] _stakingProviders) internal -``` - -Adds staking providers to the slashing queue along with the -amount. The notifier will receive reward per each staking -provider from notifiers treasury. Can only be called by -application authorized for all staking providers in the array. - -### processSlashing - -```solidity -function processSlashing(struct TokenStaking.SlashingEvent slashing) internal returns (uint96 tAmountToBurn) -``` - -Processes one specified slashing event. -Executes `involuntaryAuthorizationDecrease` function on each -affected application. - -### authorizationDecrease - -```solidity -function authorizationDecrease(address stakingProvider, struct TokenStaking.StakingProviderInfo stakingProviderStruct, uint96 slashedAmount) internal -``` - -Synchronize authorizations (if needed) after slashing stake - -### seizeKeep - -```solidity -function seizeKeep(struct TokenStaking.StakingProviderInfo stakingProviderStruct, address stakingProvider, uint96 tAmountToSlash, uint256 rewardMultiplier) internal returns (uint96) -``` - -Convert amount from T to Keep and call `seize` in Keep staking contract. -Returns remainder of slashing amount in T - -Note this internal function doesn't update stake checkpoints - -### seizeNu - -```solidity -function seizeNu(struct TokenStaking.StakingProviderInfo stakingProviderStruct, uint96 tAmountToSlash, uint256 rewardMultiplier) internal returns (uint96) -``` - -Convert amount from T to NU and call `slashStaker` in NuCypher staking contract. -Returns remainder of slashing amount in T - -Note this internal function doesn't update the stake checkpoints - -### cleanAuthorizedApplications - -```solidity -function cleanAuthorizedApplications(struct TokenStaking.StakingProviderInfo stakingProviderStruct, uint256 numberToDelete) internal -``` - -Removes application with zero authorization from authorized -applications array - -### newStakeCheckpoint - -```solidity -function newStakeCheckpoint(address _delegator, uint96 _amount, bool increase) internal -``` - -Creates new checkpoints due to a change of stake amount - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| _delegator | address | Address of the staking provider acting as delegator | -| _amount | uint96 | Amount of T to increment | -| increase | bool | True if the change is an increase, false if a decrease | - -### increaseStakeCheckpoint - -```solidity -function increaseStakeCheckpoint(address _delegator, uint96 _amount) internal -``` - -Creates new checkpoints due to an increment of a stakers' stake - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| _delegator | address | Address of the staking provider acting as delegator | -| _amount | uint96 | Amount of T to increment | - -### decreaseStakeCheckpoint - -```solidity -function decreaseStakeCheckpoint(address _delegator, uint96 _amount) internal -``` - -Creates new checkpoints due to a decrease of a stakers' stake - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| _delegator | address | Address of the stake owner acting as delegator | -| _amount | uint96 | Amount of T to decrease | - -### getNuAmountInT - -```solidity -function getNuAmountInT(address owner, address stakingProvider) internal returns (uint96) -``` - -Returns amount of Nu stake in the NuCypher staking contract for -the specified staking provider. -Resulting value in T denomination - -### _transferGovernance - -```solidity -function _transferGovernance(address newGuvnor) internal virtual -``` - -### getKeepAmountInT - -```solidity -function getKeepAmountInT(address stakingProvider) internal view returns (uint96) -``` - -Returns amount of Keep stake in the Keep staking contract for -the specified staking provider. -Resulting value in T denomination - -### convertToT - -```solidity -function convertToT(uint256 amount, uint256 ratio) internal pure returns (uint96 tAmount, uint256 remainder) -``` - -Returns the T token amount that's obtained from `amount` legacy -tokens for the given `ratio`, and the remainder that can't be -converted. - -### convertFromT - -```solidity -function convertFromT(uint96 tAmount, uint256 ratio) internal pure returns (uint256 amount, uint96 tRemainder) -``` - -Returns the amount of legacy tokens that's obtained from -`tAmount` T tokens for the given `ratio`, and the T remainder -that can't be converted. - -## T - -Threshold Network T token - -By default, token balance does not account for voting power. -This makes transfers cheaper. The downside is that it requires users -to delegate to themselves to activate checkpoints and have their -voting power tracked. - -### DELEGATION_TYPEHASH - -```solidity -bytes32 DELEGATION_TYPEHASH -``` - -The EIP-712 typehash for the delegation struct used by -`delegateBySig`. - -### constructor - -```solidity -constructor() public -``` - -### delegateBySig - -```solidity -function delegateBySig(address signatory, address delegatee, uint256 deadline, uint8 v, bytes32 r, bytes32 s) external -``` - -Delegates votes from signatory to `delegatee` - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| signatory | address | | -| delegatee | address | The address to delegate votes to | -| deadline | uint256 | The time at which to expire the signature | -| v | uint8 | The recovery byte of the signature | -| r | bytes32 | Half of the ECDSA signature pair | -| s | bytes32 | Half of the ECDSA signature pair | - -### delegate - -```solidity -function delegate(address delegatee) public virtual -``` - -Delegate votes from `msg.sender` to `delegatee`. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| delegatee | address | The address to delegate votes to | - -### beforeTokenTransfer - -```solidity -function beforeTokenTransfer(address from, address to, uint256 amount) internal -``` - -Hook that is called before any transfer of tokens. This includes - minting and burning. - -Calling conditions: -- when `from` and `to` are both non-zero, `amount` of `from`'s tokens - will be to transferred to `to`. -- when `from` is zero, `amount` tokens will be minted for `to`. -- when `to` is zero, `amount` of ``from``'s tokens will be burned. -- `from` and `to` are never both zero. - -### delegate - -```solidity -function delegate(address delegator, address delegatee) internal virtual -``` - -Change delegation for `delegator` to `delegatee`. - -## PercentUtils - -### percent - -```solidity -function percent(uint256 a, uint256 b) internal pure returns (uint256) -``` - -### asPercentOf - -```solidity -function asPercentOf(uint256 a, uint256 b) internal pure returns (uint256) -``` - -## SafeTUpgradeable - -A wrapper around OpenZeppelin's `SafeERC20Upgradeable` but specific -to the T token. Use this library in upgradeable contracts. If your -contract is non-upgradeable, then the traditional `SafeERC20` works. -The motivation is to prevent upgradeable contracts that use T from -depending on the `Address` library, which can be problematic since -it uses `delegatecall`, which is discouraged by OpenZeppelin for use -in upgradeable contracts. - -This implementation force-casts T to `IERC20Upgradeable` to make it -work with `SafeERC20Upgradeable`. - -### safeTransfer - -```solidity -function safeTransfer(contract T token, address to, uint256 value) internal -``` - -### safeTransferFrom - -```solidity -function safeTransferFrom(contract T token, address from, address to, uint256 value) internal -``` - -## VendingMachine - -Contract implements a special update protocol to enable KEEP/NU -token holders to wrap their tokens and obtain T tokens according -to a fixed ratio. This will go on indefinitely and enable NU and -KEEP token holders to join T network without needing to buy or -sell any assets. Logistically, anyone holding NU or KEEP can wrap -those assets in order to upgrade to T. They can also unwrap T in -order to downgrade back to the underlying asset. There is a separate -instance of this contract deployed for KEEP holders and a separate -instance of this contract deployed for NU holders. - -### WRAPPED_TOKEN_CONVERSION_PRECISION - -```solidity -uint256 WRAPPED_TOKEN_CONVERSION_PRECISION -``` - -Number of decimal places of precision in conversion to/from -wrapped tokens (assuming typical ERC20 token with 18 decimals). -This implies that amounts of wrapped tokens below this precision -won't take part in the conversion. E.g., for a value of 3, then -for a conversion of 1.123456789 wrapped tokens, only 1.123 is -convertible (i.e., 3 decimal places), and 0.000456789 is left. - -### FLOATING_POINT_DIVISOR - -```solidity -uint256 FLOATING_POINT_DIVISOR -``` - -Divisor for precision purposes, used to represent fractions. - -### wrappedToken - -```solidity -contract IERC20 wrappedToken -``` - -The token being wrapped to T (KEEP/NU). - -### tToken - -```solidity -contract T tToken -``` - -T token contract. - -### ratio - -```solidity -uint256 ratio -``` - -The ratio with which T token is converted based on the provided -token being wrapped (KEEP/NU), expressed in 1e18 precision. - -When wrapping: -x [T] = amount [KEEP/NU] * ratio / FLOATING_POINT_DIVISOR - -When unwrapping: -x [KEEP/NU] = amount [T] * FLOATING_POINT_DIVISOR / ratio - -### wrappedBalance - -```solidity -mapping(address => uint256) wrappedBalance -``` - -The total balance of wrapped tokens for the given holder -account. Only holders that have previously wrapped KEEP/NU to T -can unwrap, up to the amount previously wrapped. - -### Wrapped - -```solidity -event Wrapped(address recipient, uint256 wrappedTokenAmount, uint256 tTokenAmount) -``` - -### Unwrapped - -```solidity -event Unwrapped(address recipient, uint256 tTokenAmount, uint256 wrappedTokenAmount) -``` - -### constructor - -```solidity -constructor(contract IERC20 _wrappedToken, contract T _tToken, uint96 _wrappedTokenAllocation, uint96 _tTokenAllocation) public -``` - -Sets the reference to `wrappedToken` and `tToken`. Initializes -conversion `ratio` between wrapped token and T based on the -provided `_tTokenAllocation` and `_wrappedTokenAllocation`. - -Multiplications in this contract can't overflow uint256 as we -restrict `_wrappedTokenAllocation` and `_tTokenAllocation` to -96 bits and FLOATING_POINT_DIVISOR fits in less than 60 bits. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| _wrappedToken | contract IERC20 | Address to ERC20 token that will be wrapped to T | -| _tToken | contract T | Address of T token | -| _wrappedTokenAllocation | uint96 | The total supply of the token that will be wrapped to T | -| _tTokenAllocation | uint96 | The allocation of T this instance of Vending Machine will receive | - -### wrap - -```solidity -function wrap(uint256 amount) external -``` - -Wraps up to the the given `amount` of the token (KEEP/NU) and -releases T token proportionally to the amount being wrapped with -respect to the wrap ratio. The token holder needs to have at -least the given amount of the wrapped token (KEEP/NU) approved -to transfer to the Vending Machine before calling this function. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| amount | uint256 | The amount of KEEP/NU to be wrapped | - -### receiveApproval - -```solidity -function receiveApproval(address from, uint256 amount, address token, bytes) external -``` - -Wraps up to the given amount of the token (KEEP/NU) and releases -T token proportionally to the amount being wrapped with respect -to the wrap ratio. This is a shortcut to `wrap` function that -avoids a separate approval transaction. Only KEEP/NU token -is allowed as a caller, so please call this function via -token's `approveAndCall`. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| from | address | Caller's address, must be the same as `wrappedToken` field | -| amount | uint256 | The amount of KEEP/NU to be wrapped | -| token | address | Token's address, must be the same as `wrappedToken` field | -| | bytes | | - -### unwrap - -```solidity -function unwrap(uint256 amount) external -``` - -Unwraps up to the given `amount` of T back to the legacy token -(KEEP/NU) according to the wrap ratio. It can only be called by -a token holder who previously wrapped their tokens in this -vending machine contract. The token holder can't unwrap more -tokens than they originally wrapped. The token holder needs to -have at least the given amount of T tokens approved to transfer -to the Vending Machine before calling this function. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| amount | uint256 | The amount of T to unwrap back to the collateral (KEEP/NU) | - -### conversionToT - -```solidity -function conversionToT(uint256 amount) public view returns (uint256 tAmount, uint256 wrappedRemainder) -``` - -Returns the T token amount that's obtained from `amount` wrapped -tokens (KEEP/NU), and the remainder that can't be upgraded. - -### conversionFromT - -```solidity -function conversionFromT(uint256 amount) public view returns (uint256 wrappedAmount, uint256 tRemainder) -``` - -The amount of wrapped tokens (KEEP/NU) that's obtained from -`amount` T tokens, and the remainder that can't be downgraded. - -### _wrap - -```solidity -function _wrap(address tokenHolder, uint256 wrappedTokenAmount) internal -``` - -### _unwrap - -```solidity -function _unwrap(address tokenHolder, uint256 tTokenAmount) internal -``` - diff --git a/docs/app-development/staking-contract-and-dao/staking-contract-and-dao-api/generated-docs/staking/IApplication.md b/docs/app-development/staking-contract-and-dao/staking-contract-and-dao-api/generated-docs/staking/IApplication.md new file mode 100644 index 0000000..fa579d2 --- /dev/null +++ b/docs/app-development/staking-contract-and-dao/staking-contract-and-dao-api/generated-docs/staking/IApplication.md @@ -0,0 +1,89 @@ +# Solidity API + +## IApplication + +Generic interface for an application. Application is an external +smart contract or a set of smart contracts utilizing functionalities +offered by Threshold Network. Applications authorized for the given +staking provider are eligible to slash the stake delegated to that +staking provider. + +### RewardsWithdrawn + +```solidity +event RewardsWithdrawn(address stakingProvider, uint96 amount) +``` + +Event emitted by `withdrawRewards` function. + +### 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. + +Emits `RewardsWithdrawn` event. + +### authorizationIncreased + +```solidity +function authorizationIncreased(address stakingProvider, uint96 fromAmount, uint96 toAmount) external +``` + +Used by T staking contract to inform the application that the +authorized amount for the given staking provider increased. +The application may do any necessary housekeeping. The +application must revert the transaction in case the +authorization is below the minimum required. + +### 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. The application should mark the authorization as +pending decrease and respond to the staking contract with +`approveAuthorizationDecrease` at its discretion. It may +happen right away but it also may happen several months later. +If there is already a pending authorization decrease request +for the application, and the application does not agree for +overwriting it, the function should revert. + +### 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. Lets the application to +do any housekeeping neccessary. Called with 250k gas limit and +does not revert the transaction if +`involuntaryAuthorizationDecrease` call failed. + +### availableRewards + +```solidity +function availableRewards(address stakingProvider) external view returns (uint96) +``` + +Returns the amount of application rewards available for +withdrawal for the given staking provider. + +### minimumAuthorization + +```solidity +function minimumAuthorization() external view returns (uint96) +``` + +The minimum authorization amount required for the staking +provider so that they can participate in the application. + diff --git a/docs/app-development/staking-contract-and-dao/staking-contract-and-dao-api/generated-docs/staking/ILegacyTokenStaking.md b/docs/app-development/staking-contract-and-dao/staking-contract-and-dao-api/generated-docs/staking/ILegacyTokenStaking.md new file mode 100644 index 0000000..3978806 --- /dev/null +++ b/docs/app-development/staking-contract-and-dao/staking-contract-and-dao-api/generated-docs/staking/ILegacyTokenStaking.md @@ -0,0 +1,154 @@ +# Solidity API + +## IKeepTokenStaking + +Interface for Keep TokenStaking contract + +### seize + +```solidity +function seize(uint256 amountToSeize, uint256 rewardMultiplier, address tattletale, address[] misbehavedOperators) external +``` + +Seize provided token amount from every member in the misbehaved +operators array. The tattletale is rewarded with 5% of the total seized +amount scaled by the reward adjustment parameter and the rest 95% is burned. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| amountToSeize | uint256 | Token amount to seize from every misbehaved operator. | +| rewardMultiplier | uint256 | Reward adjustment in percentage. Min 1% and 100% max. | +| tattletale | address | Address to receive the 5% reward. | +| misbehavedOperators | address[] | Array of addresses to seize the tokens from. | + +### getDelegationInfo + +```solidity +function getDelegationInfo(address operator) external view returns (uint256 amount, uint256 createdAt, uint256 undelegatedAt) +``` + +Gets stake delegation info for the given operator. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| operator | address | Operator address. | + +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +| amount | uint256 | The amount of tokens the given operator delegated. | +| createdAt | uint256 | The time when the stake has been delegated. | +| undelegatedAt | uint256 | The time when undelegation has been requested. If undelegation has not been requested, 0 is returned. | + +### ownerOf + +```solidity +function ownerOf(address operator) external view returns (address) +``` + +Gets the stake owner for the specified operator address. + +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +| [0] | address | Stake owner address. | + +### beneficiaryOf + +```solidity +function beneficiaryOf(address operator) external view returns (address payable) +``` + +Gets the beneficiary for the specified operator address. + +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +| [0] | address payable | Beneficiary address. | + +### authorizerOf + +```solidity +function authorizerOf(address operator) external view returns (address) +``` + +Gets the authorizer for the specified operator address. + +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +| [0] | address | Authorizer address. | + +### eligibleStake + +```solidity +function eligibleStake(address operator, address operatorContract) external view returns (uint256 balance) +``` + +Gets the eligible stake balance of the specified address. +An eligible stake is a stake that passed the initialization period +and is not currently undelegating. Also, the operator had to approve +the specified operator contract. + +Operator with a minimum required amount of eligible stake can join the +network and participate in new work selection. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| operator | address | address of stake operator. | +| operatorContract | address | address of operator contract. | + +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +| balance | uint256 | an uint256 representing the eligible stake balance. | + +## INuCypherStakingEscrow + +Interface for NuCypher StakingEscrow contract + +### slashStaker + +```solidity +function slashStaker(address staker, uint256 penalty, address investigator, uint256 reward) external +``` + +Slash the staker's stake and reward the investigator + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| staker | address | Staker's address | +| penalty | uint256 | Penalty | +| investigator | address | Investigator | +| reward | uint256 | Reward for the investigator | + +### requestMerge + +```solidity +function requestMerge(address staker, address stakingProvider) external returns (uint256) +``` + +Request merge between NuCypher staking contract and T staking contract. +Returns amount of staked tokens + +### getAllTokens + +```solidity +function getAllTokens(address staker) external view returns (uint256) +``` + +Get all tokens belonging to the staker + diff --git a/docs/app-development/staking-contract-and-dao/staking-contract-and-dao-api/generated-docs/staking/IStaking.md b/docs/app-development/staking-contract-and-dao/staking-contract-and-dao-api/generated-docs/staking/IStaking.md new file mode 100644 index 0000000..3d3cdd6 --- /dev/null +++ b/docs/app-development/staking-contract-and-dao/staking-contract-and-dao-api/generated-docs/staking/IStaking.md @@ -0,0 +1,493 @@ +# Solidity API + +## IStaking + +The staking contract enables T owners to have their wallets offline +and their stake managed by staking providers on their behalf. +The staking contract does not define operator role. The operator +responsible for running off-chain client software is appointed by +the staking provider in the particular application utilizing the +staking contract. All off-chain client software should be able +to run without exposing operator's or staking provider’s private +key and should not require any owner’s keys at all. The stake +delegation optimizes the network throughput without compromising the +security of the owners’ stake. + +### StakeType + +```solidity +enum StakeType { + NU, + KEEP, + T +} +``` + +### stake + +```solidity +function stake(address stakingProvider, address payable beneficiary, address authorizer, uint96 amount) external +``` + +Creates a delegation with `msg.sender` owner with the given +staking provider, beneficiary, and authorizer. Transfers the +given amount of T to the staking contract. + +The owner of the delegation needs to have the amount approved to +transfer to the staking contract. + +### stakeKeep + +```solidity +function stakeKeep(address stakingProvider) external +``` + +Copies delegation from the legacy KEEP staking contract to T +staking contract. No tokens are transferred. Caches the active +stake amount from KEEP staking contract. Can be called by +anyone. + +The staking provider in T staking contract is the legacy KEEP +staking contract operator. + +### stakeNu + +```solidity +function stakeNu(address stakingProvider, address payable beneficiary, address authorizer) external +``` + +Copies delegation from the legacy NU staking contract to T +staking contract, additionally appointing staking provider, +beneficiary and authorizer roles. Caches the amount staked in NU +staking contract. Can be called only by the original delegation +owner. + +### setMinimumStakeAmount + +```solidity +function setMinimumStakeAmount(uint96 amount) external +``` + +Allows the Governance to set the minimum required stake amount. +This amount is required to protect against griefing the staking +contract and individual applications are allowed to require +higher minimum stakes if necessary. + +### approveApplication + +```solidity +function approveApplication(address application) external +``` + +Allows the Governance to approve the particular application +before individual stake authorizers are able to authorize it. + +### increaseAuthorization + +```solidity +function increaseAuthorization(address stakingProvider, address application, uint96 amount) external +``` + +Increases the authorization of the given staking provider for +the given application by the given amount. Can only be called by +the authorizer for that staking provider. + +Calls `authorizationIncreased(address stakingProvider, uint256 amount)` +on the given application to notify the application about +authorization change. See `IApplication`. + +### requestAuthorizationDecrease + +```solidity +function requestAuthorizationDecrease(address stakingProvider, address application, uint96 amount) external +``` + +Requests decrease of the authorization for the given staking +provider on the given application by the provided amount. +It may not change the authorized amount immediatelly. When +it happens depends on the application. Can only be called by the +given staking provider’s authorizer. Overwrites pending +authorization decrease for the given staking provider and +application if the application agrees for that. If the +application does not agree for overwriting, the function +reverts. + +Calls `authorizationDecreaseRequested(address stakingProvider, uint256 amount)` +on the given application. See `IApplication`. + +### requestAuthorizationDecrease + +```solidity +function requestAuthorizationDecrease(address stakingProvider) external +``` + +Requests decrease of all authorizations for the given staking +provider on all applications by all authorized amount. +It may not change the authorized amount immediatelly. When +it happens depends on the application. Can only be called by the +given staking provider’s authorizer. Overwrites pending +authorization decrease for the given staking provider and +application. + +Calls `authorizationDecreaseRequested(address stakingProvider, uint256 amount)` +for each authorized application. See `IApplication`. + +### approveAuthorizationDecrease + +```solidity +function approveAuthorizationDecrease(address stakingProvider) external returns (uint96) +``` + +Called by the application at its discretion to approve the +previously requested authorization decrease request. Can only be +called by the application that was previously requested to +decrease the authorization for that staking provider. +Returns resulting authorized amount for the application. + +### forceDecreaseAuthorization + +```solidity +function forceDecreaseAuthorization(address stakingProvider, address application) external +``` + +Decreases the authorization for the given `stakingProvider` on +the given disabled `application`, for all authorized amount. +Can be called by anyone. + +### pauseApplication + +```solidity +function pauseApplication(address application) external +``` + +Pauses the given application’s eligibility to slash stakes. +Besides that stakers can't change authorization to the application. +Can be called only by the Panic Button of the particular +application. The paused application can not slash stakes until +it is approved again by the Governance using `approveApplication` +function. Should be used only in case of an emergency. + +### disableApplication + +```solidity +function disableApplication(address application) external +``` + +Disables the given application. The disabled application can't +slash stakers. Also stakers can't increase authorization to that +application but can decrease without waiting by calling +`requestAuthorizationDecrease` at any moment. Can be called only +by the governance. The disabled application can't be approved +again. Should be used only in case of an emergency. + +### setPanicButton + +```solidity +function setPanicButton(address application, address panicButton) external +``` + +Sets the Panic Button role for the given application to the +provided address. Can only be called by the Governance. If the +Panic Button for the given application should be disabled, the +role address should be set to 0x0 address. + +### setAuthorizationCeiling + +```solidity +function setAuthorizationCeiling(uint256 ceiling) external +``` + +Sets the maximum number of applications one staking provider can +have authorized. Used to protect against DoSing slashing queue. +Can only be called by the Governance. + +### topUp + +```solidity +function topUp(address stakingProvider, uint96 amount) external +``` + +Increases the amount of the stake for the given staking provider. + +The sender of this transaction needs to have the amount approved to +transfer to the staking contract. + +### topUpKeep + +```solidity +function topUpKeep(address stakingProvider) external +``` + +Propagates information about stake top-up from the legacy KEEP +staking contract to T staking contract. Can be called only by +the owner or the staking provider. + +### topUpNu + +```solidity +function topUpNu(address stakingProvider) external +``` + +Propagates information about stake top-up from the legacy NU +staking contract to T staking contract. Can be called only by +the owner or the staking provider. + +### unstakeT + +```solidity +function unstakeT(address stakingProvider, uint96 amount) external +``` + +Reduces the liquid T stake amount by the provided amount and +withdraws T to the owner. Reverts if there is at least one +authorization higher than the sum of the legacy stake and +remaining liquid T stake or if the unstake amount is higher than +the liquid T stake amount. Can be called only by the delegation +owner or the staking provider. + +### unstakeKeep + +```solidity +function unstakeKeep(address stakingProvider) external +``` + +Sets the legacy KEEP staking contract active stake amount cached +in T staking contract to 0. Reverts if the amount of liquid T +staked in T staking contract is lower than the highest +application authorization. This function allows to unstake from +KEEP staking contract and still being able to operate in T +network and earning rewards based on the liquid T staked. Can be +called only by the delegation owner or the staking provider. + +### unstakeNu + +```solidity +function unstakeNu(address stakingProvider, uint96 amount) external +``` + +Reduces cached legacy NU stake amount by the provided amount. +Reverts if there is at least one authorization higher than the +sum of remaining legacy NU stake and liquid T stake for that +staking provider or if the untaked amount is higher than the +cached legacy stake amount. If succeeded, the legacy NU stake +can be partially or fully undelegated on the legacy staking +contract. This function allows to unstake from NU staking +contract and still being able to operate in T network and +earning rewards based on the liquid T staked. Can be called only +by the delegation owner or the staking provider. + +### unstakeAll + +```solidity +function unstakeAll(address stakingProvider) external +``` + +Sets cached legacy stake amount to 0, sets the liquid T stake +amount to 0 and withdraws all liquid T from the stake to the +owner. Reverts if there is at least one non-zero authorization. +Can be called only by the delegation owner or the staking +provider. + +### notifyKeepStakeDiscrepancy + +```solidity +function notifyKeepStakeDiscrepancy(address stakingProvider) external +``` + +Notifies about the discrepancy between legacy KEEP active stake +and the amount cached in T staking contract. Slashes the staking +provider in case the amount cached is higher than the actual +active stake amount in KEEP staking contract. Needs to update +authorizations of all affected applications and execute an +involuntary allocation decrease on all affected applications. +Can be called by anyone, notifier receives a reward. + +### notifyNuStakeDiscrepancy + +```solidity +function notifyNuStakeDiscrepancy(address stakingProvider) external +``` + +Notifies about the discrepancy between legacy NU active stake +and the amount cached in T staking contract. Slashes the +staking provider in case the amount cached is higher than the +actual active stake amount in NU staking contract. Needs to +update authorizations of all affected applications and execute +an involuntary allocation decrease on all affected applications. +Can be called by anyone, notifier receives a reward. + +### setStakeDiscrepancyPenalty + +```solidity +function setStakeDiscrepancyPenalty(uint96 penalty, uint256 rewardMultiplier) external +``` + +Sets the penalty amount for stake discrepancy and reward +multiplier for reporting it. The penalty is seized from the +delegated stake, and 5% of the penalty, scaled by the +multiplier, is given to the notifier. The rest of the tokens are +burned. Can only be called by the Governance. See `seize` function. + +### setNotificationReward + +```solidity +function setNotificationReward(uint96 reward) external +``` + +Sets reward in T tokens for notification of misbehaviour +of one staking provider. Can only be called by the governance. + +### pushNotificationReward + +```solidity +function pushNotificationReward(uint96 reward) external +``` + +Transfer some amount of T tokens as reward for notifications +of misbehaviour + +### withdrawNotificationReward + +```solidity +function withdrawNotificationReward(address recipient, uint96 amount) external +``` + +Withdraw some amount of T tokens from notifiers treasury. +Can only be called by the governance. + +### slash + +```solidity +function slash(uint96 amount, address[] stakingProviders) external +``` + +Adds staking providers to the slashing queue along with the +amount that should be slashed from each one of them. Can only be +called by application authorized for all staking providers in +the array. + +### seize + +```solidity +function seize(uint96 amount, uint256 rewardMultipier, address notifier, address[] stakingProviders) external +``` + +Adds staking providers to the slashing queue along with the +amount. The notifier will receive reward per each staking +provider from notifiers treasury. Can only be called by +application authorized for all staking providers in the array. + +### processSlashing + +```solidity +function processSlashing(uint256 count) external +``` + +Takes the given number of queued slashing operations and +processes them. Receives 5% of the slashed amount. +Executes `involuntaryAllocationDecrease` function on each +affected application. + +### authorizedStake + +```solidity +function authorizedStake(address stakingProvider, address application) external view returns (uint96) +``` + +Returns the authorized stake amount of the staking provider for +the application. + +### stakes + +```solidity +function stakes(address stakingProvider) external view returns (uint96 tStake, uint96 keepInTStake, uint96 nuInTStake) +``` + +Returns staked amount of T, Keep and Nu for the specified +staking provider. + +All values are in T denomination + +### getStartStakingTimestamp + +```solidity +function getStartStakingTimestamp(address stakingProvider) external view returns (uint256) +``` + +Returns start staking timestamp. + +This value is set at most once. + +### stakedNu + +```solidity +function stakedNu(address stakingProvider) external view returns (uint256) +``` + +Returns staked amount of NU for the specified staking provider. + +### rolesOf + +```solidity +function rolesOf(address stakingProvider) external view returns (address owner, address payable beneficiary, address authorizer) +``` + +Gets the stake owner, the beneficiary and the authorizer +for the specified staking provider address. + +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +| owner | address | Stake owner address. | +| beneficiary | address payable | Beneficiary address. | +| authorizer | address | Authorizer address. | + +### getApplicationsLength + +```solidity +function getApplicationsLength() external view returns (uint256) +``` + +Returns length of application array + +### getSlashingQueueLength + +```solidity +function getSlashingQueueLength() external view returns (uint256) +``` + +Returns length of slashing queue + +### getMinStaked + +```solidity +function getMinStaked(address stakingProvider, enum IStaking.StakeType stakeTypes) external view returns (uint96) +``` + +Returns minimum possible stake for T, KEEP or NU in T +denomination. + +For example, suppose the given staking provider has 10 T, 20 T +worth of KEEP, and 30 T worth of NU all staked, and the maximum +application authorization is 40 T, then `getMinStaked` for +that staking provider returns: +* 0 T if KEEP stake type specified i.e. +min = 40 T max - (10 T + 30 T worth of NU) = 0 T +* 10 T if NU stake type specified i.e. +min = 40 T max - (10 T + 20 T worth of KEEP) = 10 T +* 0 T if T stake type specified i.e. +min = 40 T max - (20 T worth of KEEP + 30 T worth of NU) < 0 T +In other words, the minimum stake amount for the specified +stake type is the minimum amount of stake of the given type +needed to satisfy the maximum application authorization given the +staked amounts of the other stake types for that staking provider. + +### getAvailableToAuthorize + +```solidity +function getAvailableToAuthorize(address stakingProvider, address application) external view returns (uint96) +``` + +Returns available amount to authorize for the specified application + diff --git a/docs/app-development/staking-contract-and-dao/staking-contract-and-dao-api/generated-docs/staking/KeepStake.md b/docs/app-development/staking-contract-and-dao/staking-contract-and-dao-api/generated-docs/staking/KeepStake.md new file mode 100644 index 0000000..701594f --- /dev/null +++ b/docs/app-development/staking-contract-and-dao/staking-contract-and-dao-api/generated-docs/staking/KeepStake.md @@ -0,0 +1,110 @@ +# Solidity API + +## IManagedGrant + +### grantee + +```solidity +function grantee() external view returns (address) +``` + +## KeepStake + +T network staking contract supports existing KEEP stakes by allowing +KEEP stakers to use their stakes in T network and weights them based +on KEEP<>T token ratio. KEEP stake owner is cached in T staking +contract and used to restrict access to all functions only owner or +operator should call. To cache KEEP stake owner in T staking +contract, T staking contract first needs to resolve the owner. + +Resolving liquid KEEP stake owner is easy. Resolving token grant +stake owner is complicated and not possible to do on-chain from +a contract external to KEEP TokenStaking contract. Keep TokenStaking +knows the grant ID but does not expose it externally. + +KeepStake contract addresses this problem by exposing +operator-owner mappings snapshotted off-chain based on events and +information publicly available from KEEP TokenStaking contract and +KEEP TokenGrant contract. Additionally, it gives the Governance +ability to add new mappings in case they are ever needed; in +practice, this will be needed only if someone decides to stake their +KEEP token grant in KEEP network after 2021-11-11 when the snapshot +was taken. + +Operator-owner pairs were snapshotted 2021-11-11 in the following +way: +1. Fetch all TokenStaking events from KEEP staking contract. +2. Filter out undelegated operators. +3. Filter out canceled delegations. +4. Fetch grant stake information from KEEP TokenGrant for that +operator to determine if we are dealing with grant delegation. +5. Fetch grantee address from KEEP TokenGrant contract. +6. Check if we are dealing with ManagedGrant by looking for all +created ManagedGrants and comparing their address against grantee +address fetched from TokenGrant contract. + +### keepTokenStaking + +```solidity +contract IKeepTokenStaking keepTokenStaking +``` + +### operatorToManagedGrant + +```solidity +mapping(address => address) operatorToManagedGrant +``` + +### operatorToGrantee + +```solidity +mapping(address => address) operatorToGrantee +``` + +### constructor + +```solidity +constructor(contract IKeepTokenStaking _keepTokenStaking) public +``` + +### setManagedGrant + +```solidity +function setManagedGrant(address operator, address managedGrant) external +``` + +Allows the Governance to set new operator-managed grant pair. +This function should only be called for managed grants if +the snapshot does include this pair. + +### setGrantee + +```solidity +function setGrantee(address operator, address grantee) external +``` + +Allows the Governance to set new operator-grantee pair. +This function should only be called for non-managed grants if +the snapshot does include this pair. + +### resolveOwner + +```solidity +function resolveOwner(address operator) external view returns (address) +``` + +Resolves KEEP stake owner for the provided operator address. +Reverts if could not resolve the owner. + +### resolveSnapshottedManagedGrantees + +```solidity +function resolveSnapshottedManagedGrantees(address operator) internal view returns (address) +``` + +### resolveSnapshottedGrantees + +```solidity +function resolveSnapshottedGrantees(address operator) internal pure returns (address) +``` + diff --git a/docs/app-development/staking-contract-and-dao/staking-contract-and-dao-api/generated-docs/staking/TokenStaking.md b/docs/app-development/staking-contract-and-dao/staking-contract-and-dao-api/generated-docs/staking/TokenStaking.md new file mode 100644 index 0000000..b71f033 --- /dev/null +++ b/docs/app-development/staking-contract-and-dao/staking-contract-and-dao-api/generated-docs/staking/TokenStaking.md @@ -0,0 +1,1068 @@ +# Solidity API + +## TokenStaking + +TokenStaking is the main staking contract of the Threshold Network. +Apart from the basic usage of enabling T stakes, it also acts as a +sort of "meta-staking" contract, accepting existing legacy NU/KEEP +stakes. Additionally, it serves as application manager for the apps +that run on the Threshold Network. Note that legacy NU/KEEP staking +contracts see TokenStaking as an application (e.g., slashing is +requested by TokenStaking and performed by the legacy contracts). + +TokenStaking is upgradeable, using OpenZeppelin's Upgradeability +framework. As such, it is required to satisfy OZ's guidelines, like +restrictions on constructors, immutable variables, base contracts and +libraries. See https://docs.openzeppelin.com/upgrades-plugins/1.x/writing-upgradeable + +### ApplicationStatus + +```solidity +enum ApplicationStatus { + NOT_APPROVED, + APPROVED, + PAUSED, + DISABLED +} +``` + +### StakingProviderInfo + +```solidity +struct StakingProviderInfo { + uint96 nuInTStake; + address owner; + uint96 keepInTStake; + address payable beneficiary; + uint96 tStake; + address authorizer; + mapping(address => struct TokenStaking.AppAuthorization) authorizations; + address[] authorizedApplications; + uint256 startStakingTimestamp; +} +``` + +### AppAuthorization + +```solidity +struct AppAuthorization { + uint96 authorized; + uint96 deauthorizing; +} +``` + +### ApplicationInfo + +```solidity +struct ApplicationInfo { + enum TokenStaking.ApplicationStatus status; + address panicButton; +} +``` + +### SlashingEvent + +```solidity +struct SlashingEvent { + address stakingProvider; + uint96 amount; +} +``` + +### SLASHING_REWARD_PERCENT + +```solidity +uint256 SLASHING_REWARD_PERCENT +``` + +### MIN_STAKE_TIME + +```solidity +uint256 MIN_STAKE_TIME +``` + +### GAS_LIMIT_AUTHORIZATION_DECREASE + +```solidity +uint256 GAS_LIMIT_AUTHORIZATION_DECREASE +``` + +### CONVERSION_DIVISOR + +```solidity +uint256 CONVERSION_DIVISOR +``` + +### token + +```solidity +contract T token +``` + +### keepStakingContract + +```solidity +contract IKeepTokenStaking keepStakingContract +``` + +### keepStake + +```solidity +contract KeepStake keepStake +``` + +### nucypherStakingContract + +```solidity +contract INuCypherStakingEscrow nucypherStakingContract +``` + +### keepRatio + +```solidity +uint256 keepRatio +``` + +### nucypherRatio + +```solidity +uint256 nucypherRatio +``` + +### governance + +```solidity +address governance +``` + +### minTStakeAmount + +```solidity +uint96 minTStakeAmount +``` + +### authorizationCeiling + +```solidity +uint256 authorizationCeiling +``` + +### stakeDiscrepancyPenalty + +```solidity +uint96 stakeDiscrepancyPenalty +``` + +### stakeDiscrepancyRewardMultiplier + +```solidity +uint256 stakeDiscrepancyRewardMultiplier +``` + +### notifiersTreasury + +```solidity +uint256 notifiersTreasury +``` + +### notificationReward + +```solidity +uint256 notificationReward +``` + +### stakingProviders + +```solidity +mapping(address => struct TokenStaking.StakingProviderInfo) stakingProviders +``` + +### applicationInfo + +```solidity +mapping(address => struct TokenStaking.ApplicationInfo) applicationInfo +``` + +### applications + +```solidity +address[] applications +``` + +### slashingQueue + +```solidity +struct TokenStaking.SlashingEvent[] slashingQueue +``` + +### slashingQueueIndex + +```solidity +uint256 slashingQueueIndex +``` + +### Staked + +```solidity +event Staked(enum IStaking.StakeType stakeType, address owner, address stakingProvider, address beneficiary, address authorizer, uint96 amount) +``` + +### MinimumStakeAmountSet + +```solidity +event MinimumStakeAmountSet(uint96 amount) +``` + +### ApplicationStatusChanged + +```solidity +event ApplicationStatusChanged(address application, enum TokenStaking.ApplicationStatus newStatus) +``` + +### AuthorizationIncreased + +```solidity +event AuthorizationIncreased(address stakingProvider, address application, uint96 fromAmount, uint96 toAmount) +``` + +### AuthorizationDecreaseRequested + +```solidity +event AuthorizationDecreaseRequested(address stakingProvider, address application, uint96 fromAmount, uint96 toAmount) +``` + +### AuthorizationDecreaseApproved + +```solidity +event AuthorizationDecreaseApproved(address stakingProvider, address application, uint96 fromAmount, uint96 toAmount) +``` + +### AuthorizationInvoluntaryDecreased + +```solidity +event AuthorizationInvoluntaryDecreased(address stakingProvider, address application, uint96 fromAmount, uint96 toAmount, bool successfulCall) +``` + +### PanicButtonSet + +```solidity +event PanicButtonSet(address application, address panicButton) +``` + +### AuthorizationCeilingSet + +```solidity +event AuthorizationCeilingSet(uint256 ceiling) +``` + +### ToppedUp + +```solidity +event ToppedUp(address stakingProvider, uint96 amount) +``` + +### Unstaked + +```solidity +event Unstaked(address stakingProvider, uint96 amount) +``` + +### TokensSeized + +```solidity +event TokensSeized(address stakingProvider, uint96 amount, bool discrepancy) +``` + +### StakeDiscrepancyPenaltySet + +```solidity +event StakeDiscrepancyPenaltySet(uint96 penalty, uint256 rewardMultiplier) +``` + +### NotificationRewardSet + +```solidity +event NotificationRewardSet(uint96 reward) +``` + +### NotificationRewardPushed + +```solidity +event NotificationRewardPushed(uint96 reward) +``` + +### NotificationRewardWithdrawn + +```solidity +event NotificationRewardWithdrawn(address recipient, uint96 amount) +``` + +### NotifierRewarded + +```solidity +event NotifierRewarded(address notifier, uint256 amount) +``` + +### SlashingProcessed + +```solidity +event SlashingProcessed(address caller, uint256 count, uint256 tAmount) +``` + +### OwnerRefreshed + +```solidity +event OwnerRefreshed(address stakingProvider, address oldOwner, address newOwner) +``` + +### GovernanceTransferred + +```solidity +event GovernanceTransferred(address oldGovernance, address newGovernance) +``` + +### onlyGovernance + +```solidity +modifier onlyGovernance() +``` + +### onlyPanicButtonOf + +```solidity +modifier onlyPanicButtonOf(address application) +``` + +### onlyAuthorizerOf + +```solidity +modifier onlyAuthorizerOf(address stakingProvider) +``` + +### onlyOwnerOrStakingProvider + +```solidity +modifier onlyOwnerOrStakingProvider(address stakingProvider) +``` + +### onlyOwnerOf + +```solidity +modifier onlyOwnerOf(address stakingProvider) +``` + +### constructor + +```solidity +constructor(contract T _token, contract IKeepTokenStaking _keepStakingContract, contract INuCypherStakingEscrow _nucypherStakingContract, contract VendingMachine _keepVendingMachine, contract VendingMachine _nucypherVendingMachine, contract KeepStake _keepStake) public +``` + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| _token | contract T | Address of T token contract | +| _keepStakingContract | contract IKeepTokenStaking | Address of Keep staking contract | +| _nucypherStakingContract | contract INuCypherStakingEscrow | Address of NuCypher staking contract | +| _keepVendingMachine | contract VendingMachine | Address of Keep vending machine | +| _nucypherVendingMachine | contract VendingMachine | Address of NuCypher vending machine | +| _keepStake | contract KeepStake | Address of Keep contract with grant owners | + +### initialize + +```solidity +function initialize() external +``` + +### stake + +```solidity +function stake(address stakingProvider, address payable beneficiary, address authorizer, uint96 amount) external +``` + +Creates a delegation with `msg.sender` owner with the given +staking provider, beneficiary, and authorizer. Transfers the +given amount of T to the staking contract. + +The owner of the delegation needs to have the amount approved to +transfer to the staking contract. + +### stakeKeep + +```solidity +function stakeKeep(address stakingProvider) external +``` + +Copies delegation from the legacy KEEP staking contract to T +staking contract. No tokens are transferred. Caches the active +stake amount from KEEP staking contract. Can be called by +anyone. + +The staking provider in T staking contract is the legacy KEEP +staking contract operator. + +### stakeNu + +```solidity +function stakeNu(address stakingProvider, address payable beneficiary, address authorizer) external +``` + +Copies delegation from the legacy NU staking contract to T +staking contract, additionally appointing beneficiary and +authorizer roles. Caches the amount staked in NU staking +contract. Can be called only by the original delegation owner. + +### setMinimumStakeAmount + +```solidity +function setMinimumStakeAmount(uint96 amount) external +``` + +Allows the Governance to set the minimum required stake amount. +This amount is required to protect against griefing the staking +contract and individual applications are allowed to require +higher minimum stakes if necessary. + +Staking providers are not required to maintain a minimum T stake +all the time. 24 hours after the delegation, T stake can be reduced +below the minimum stake. The minimum stake in the staking contract +is just to protect against griefing stake operation. Please note +that each application may have its own minimum authorization though +and the authorization can not be higher than the stake. + +### approveApplication + +```solidity +function approveApplication(address application) external +``` + +Allows the Governance to approve the particular application +before individual stake authorizers are able to authorize it. + +### increaseAuthorization + +```solidity +function increaseAuthorization(address stakingProvider, address application, uint96 amount) external +``` + +Increases the authorization of the given staking provider for +the given application by the given amount. Can only be called by +the given staking provider’s authorizer. + +Calls `authorizationIncreased` callback on the given application to +notify the application about authorization change. +See `IApplication`. + +### requestAuthorizationDecrease + +```solidity +function requestAuthorizationDecrease(address stakingProvider) external +``` + +Requests decrease of all authorizations for the given staking +provider on all applications by all authorized amount. +It may not change the authorized amount immediatelly. When +it happens depends on the application. Can only be called by the +given staking provider’s authorizer. Overwrites pending +authorization decrease for the given staking provider and +application. + +Calls `authorizationDecreaseRequested` callback +for each authorized application. See `IApplication`. + +### approveAuthorizationDecrease + +```solidity +function approveAuthorizationDecrease(address stakingProvider) external returns (uint96) +``` + +Called by the application at its discretion to approve the +previously requested authorization decrease request. Can only be +called by the application that was previously requested to +decrease the authorization for that staking provider. +Returns resulting authorized amount for the application. + +### forceDecreaseAuthorization + +```solidity +function forceDecreaseAuthorization(address stakingProvider, address application) external +``` + +Decreases the authorization for the given `stakingProvider` on +the given disabled `application`, for all authorized amount. +Can be called by anyone. + +### pauseApplication + +```solidity +function pauseApplication(address application) external +``` + +Pauses the given application’s eligibility to slash stakes. +Besides that stakers can't change authorization to the application. +Can be called only by the Panic Button of the particular +application. The paused application can not slash stakes until +it is approved again by the Governance using `approveApplication` +function. Should be used only in case of an emergency. + +### disableApplication + +```solidity +function disableApplication(address application) external +``` + +Disables the given application. The disabled application can't +slash stakers. Also stakers can't increase authorization to that +application but can decrease without waiting by calling +`forceDecreaseAuthorization` at any moment. Can be called only +by the governance. The disabled application can't be approved +again. Should be used only in case of an emergency. + +### setPanicButton + +```solidity +function setPanicButton(address application, address panicButton) external +``` + +Sets the Panic Button role for the given application to the +provided address. Can only be called by the Governance. If the +Panic Button for the given application should be disabled, the +role address should be set to 0x0 address. + +### setAuthorizationCeiling + +```solidity +function setAuthorizationCeiling(uint256 ceiling) external +``` + +Sets the maximum number of applications one staking provider can +have authorized. Used to protect against DoSing slashing queue. +Can only be called by the Governance. + +### topUp + +```solidity +function topUp(address stakingProvider, uint96 amount) external +``` + +Increases the amount of the stake for the given staking provider. + +The sender of this transaction needs to have the amount approved to +transfer to the staking contract. + +### topUpKeep + +```solidity +function topUpKeep(address stakingProvider) external +``` + +Propagates information about stake top-up from the legacy KEEP +staking contract to T staking contract. Can be called only by +the owner or the staking provider. + +### topUpNu + +```solidity +function topUpNu(address stakingProvider) external +``` + +Propagates information about stake top-up from the legacy NU +staking contract to T staking contract. Can be called only by +the owner or the staking provider. + +### unstakeT + +```solidity +function unstakeT(address stakingProvider, uint96 amount) external +``` + +Reduces the liquid T stake amount by the provided amount and +withdraws T to the owner. Reverts if there is at least one +authorization higher than the sum of the legacy stake and +remaining liquid T stake or if the unstake amount is higher than +the liquid T stake amount. Can be called only by the owner or +the staking provider. Can only be called when 24h passed since +the stake has been delegated. + +### unstakeKeep + +```solidity +function unstakeKeep(address stakingProvider) external +``` + +Sets the legacy KEEP staking contract active stake amount cached +in T staking contract to 0. Reverts if the amount of liquid T +staked in T staking contract is lower than the highest +application authorization. This function allows to unstake from +KEEP staking contract and still being able to operate in T +network and earning rewards based on the liquid T staked. Can be +called only by the delegation owner or the staking provider. +Can only be called when 24h passed since the stake has been +delegated. + +This function (or `unstakeAll`) must be called before +`undelegate`/`undelegateAt` in Keep staking contract. Otherwise +provider can be slashed by `notifyKeepStakeDiscrepancy` method. + +### unstakeNu + +```solidity +function unstakeNu(address stakingProvider, uint96 amount) external +``` + +Reduces cached legacy NU stake amount by the provided amount. +Reverts if there is at least one authorization higher than the +sum of remaining legacy NU stake and liquid T stake for that +staking provider or if the untaked amount is higher than the +cached legacy stake amount. If succeeded, the legacy NU stake +can be partially or fully undelegated on the legacy staking +contract. This function allows to unstake from NU staking +contract and still being able to operate in T network and +earning rewards based on the liquid T staked. Can be called only +by the delegation owner or the staking provider. Can only be +called when 24h passed since the stake has been delegated. + +This function (or `unstakeAll`) must be called before `withdraw` +in NuCypher staking contract. Otherwise NU tokens can't be +unlocked. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| stakingProvider | address | Staking provider address | +| amount | uint96 | Amount of NU to unstake in T denomination | + +### unstakeAll + +```solidity +function unstakeAll(address stakingProvider) external +``` + +Sets cached legacy stake amount to 0, sets the liquid T stake +amount to 0 and withdraws all liquid T from the stake to the +owner. Reverts if there is at least one non-zero authorization. +Can be called only by the delegation owner or the staking +provider. Can only be called when 24h passed since the stake +has been delegated. + +### notifyKeepStakeDiscrepancy + +```solidity +function notifyKeepStakeDiscrepancy(address stakingProvider) external +``` + +Notifies about the discrepancy between legacy KEEP active stake +and the amount cached in T staking contract. Slashes the staking +provider in case the amount cached is higher than the actual +active stake amount in KEEP staking contract. Needs to update +authorizations of all affected applications and execute an +involuntary authorization decrease on all affected applications. +Can be called by anyone, notifier receives a reward. + +### notifyNuStakeDiscrepancy + +```solidity +function notifyNuStakeDiscrepancy(address stakingProvider) external +``` + +Notifies about the discrepancy between legacy NU active stake +and the amount cached in T staking contract. Slashes the +staking provider in case the amount cached is higher than the +actual active stake amount in NU staking contract. Needs to +update authorizations of all affected applications and execute an +involuntary authorization decrease on all affected applications. +Can be called by anyone, notifier receives a reward. + +Real discrepancy between T and Nu is impossible. +This method is a safeguard in case of bugs in NuCypher staking +contract + +### setStakeDiscrepancyPenalty + +```solidity +function setStakeDiscrepancyPenalty(uint96 penalty, uint256 rewardMultiplier) external +``` + +Sets the penalty amount for stake discrepancy and reward +multiplier for reporting it. The penalty is seized from the +delegated stake, and 5% of the penalty, scaled by the +multiplier, is given to the notifier. The rest of the tokens are +burned. Can only be called by the Governance. See `seize` function. + +### setNotificationReward + +```solidity +function setNotificationReward(uint96 reward) external +``` + +Sets reward in T tokens for notification of misbehaviour +of one staking provider. Can only be called by the governance. + +### pushNotificationReward + +```solidity +function pushNotificationReward(uint96 reward) external +``` + +Transfer some amount of T tokens as reward for notifications +of misbehaviour + +### withdrawNotificationReward + +```solidity +function withdrawNotificationReward(address recipient, uint96 amount) external +``` + +Withdraw some amount of T tokens from notifiers treasury. +Can only be called by the governance. + +### slash + +```solidity +function slash(uint96 amount, address[] _stakingProviders) external +``` + +Adds staking providers to the slashing queue along with the +amount that should be slashed from each one of them. Can only be +called by application authorized for all staking providers in +the array. + +This method doesn't emit events for providers that are added to +the queue. If necessary events can be added to the application +level. + +### seize + +```solidity +function seize(uint96 amount, uint256 rewardMultiplier, address notifier, address[] _stakingProviders) external +``` + +Adds staking providers to the slashing queue along with the +amount. The notifier will receive reward per each provider from +notifiers treasury. Can only be called by application +authorized for all staking providers in the array. + +This method doesn't emit events for staking providers that are +added to the queue. If necessary events can be added to the +application level. + +### processSlashing + +```solidity +function processSlashing(uint256 count) external virtual +``` + +Takes the given number of queued slashing operations and +processes them. Receives 5% of the slashed amount. +Executes `involuntaryAuthorizationDecrease` function on each +affected application. + +### delegateVoting + +```solidity +function delegateVoting(address stakingProvider, address delegatee) external +``` + +Delegate voting power from the stake associated to the +`stakingProvider` to a `delegatee` address. Caller must be the +owner of this stake. + +### transferGovernance + +```solidity +function transferGovernance(address newGuvnor) external virtual +``` + +Transfers ownership of the contract to `newGuvnor`. + +### authorizedStake + +```solidity +function authorizedStake(address stakingProvider, address application) external view returns (uint96) +``` + +Returns the authorized stake amount of the staking provider for +the application. + +### stakes + +```solidity +function stakes(address stakingProvider) external view returns (uint96 tStake, uint96 keepInTStake, uint96 nuInTStake) +``` + +Returns staked amount of T, Keep and Nu for the specified +staking provider. + +All values are in T denomination + +### getStartStakingTimestamp + +```solidity +function getStartStakingTimestamp(address stakingProvider) external view returns (uint256) +``` + +Returns start staking timestamp. + +This value is set at most once. + +### stakedNu + +```solidity +function stakedNu(address stakingProvider) external view returns (uint256 nuAmount) +``` + +Returns staked amount of NU for the specified staking provider. + +### rolesOf + +```solidity +function rolesOf(address stakingProvider) external view returns (address owner, address payable beneficiary, address authorizer) +``` + +Gets the stake owner, the beneficiary and the authorizer +for the specified staking provider address. + +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +| owner | address | Stake owner address. | +| beneficiary | address payable | Beneficiary address. | +| authorizer | address | Authorizer address. | + +### getApplicationsLength + +```solidity +function getApplicationsLength() external view returns (uint256) +``` + +Returns length of application array + +### getSlashingQueueLength + +```solidity +function getSlashingQueueLength() external view returns (uint256) +``` + +Returns length of slashing queue + +### requestAuthorizationDecrease + +```solidity +function requestAuthorizationDecrease(address stakingProvider, address application, uint96 amount) public +``` + +Requests decrease of the authorization for the given staking +provider on the given application by the provided amount. +It may not change the authorized amount immediatelly. When +it happens depends on the application. Can only be called by the +given staking provider’s authorizer. Overwrites pending +authorization decrease for the given staking provider and +application if the application agrees for that. If the +application does not agree for overwriting, the function +reverts. + +Calls `authorizationDecreaseRequested` callback on the given +application. See `IApplication`. + +### getMinStaked + +```solidity +function getMinStaked(address stakingProvider, enum IStaking.StakeType stakeTypes) public view returns (uint96) +``` + +Returns minimum possible stake for T, KEEP or NU in T denomination + +For example, suppose the given staking provider has 10 T, 20 T worth +of KEEP, and 30 T worth of NU all staked, and the maximum +application authorization is 40 T, then `getMinStaked` for +that staking provider returns: +* 0 T if KEEP stake type specified i.e. +min = 40 T max - (10 T + 30 T worth of NU) = 0 T +* 10 T if NU stake type specified i.e. +min = 40 T max - (10 T + 20 T worth of KEEP) = 10 T +* 0 T if T stake type specified i.e. +min = 40 T max - (20 T worth of KEEP + 30 T worth of NU) < 0 T +In other words, the minimum stake amount for the specified +stake type is the minimum amount of stake of the given type +needed to satisfy the maximum application authorization given +the staked amounts of the other stake types for that staking +provider. + +### getAvailableToAuthorize + +```solidity +function getAvailableToAuthorize(address stakingProvider, address application) public view returns (uint96 availableTValue) +``` + +Returns available amount to authorize for the specified +application. + +### delegate + +```solidity +function delegate(address stakingProvider, address delegatee) internal virtual +``` + +Delegate voting power from the stake associated to the +`stakingProvider` to a `delegatee` address. Caller must be the owner +of this stake. + +Original abstract function defined in Checkpoints contract had two +parameters, `delegator` and `delegatee`. Here we override it and +comply with the same signature but the semantics of the first +parameter changes to the `stakingProvider` address. + +### notify + +```solidity +function notify(uint96 amount, uint256 rewardMultiplier, address notifier, address[] _stakingProviders) internal +``` + +Adds staking providers to the slashing queue along with the +amount. The notifier will receive reward per each staking +provider from notifiers treasury. Can only be called by +application authorized for all staking providers in the array. + +### processSlashing + +```solidity +function processSlashing(struct TokenStaking.SlashingEvent slashing) internal returns (uint96 tAmountToBurn) +``` + +Processes one specified slashing event. +Executes `involuntaryAuthorizationDecrease` function on each +affected application. + +### authorizationDecrease + +```solidity +function authorizationDecrease(address stakingProvider, struct TokenStaking.StakingProviderInfo stakingProviderStruct, uint96 slashedAmount) internal +``` + +Synchronize authorizations (if needed) after slashing stake + +### seizeKeep + +```solidity +function seizeKeep(struct TokenStaking.StakingProviderInfo stakingProviderStruct, address stakingProvider, uint96 tAmountToSlash, uint256 rewardMultiplier) internal returns (uint96) +``` + +Convert amount from T to Keep and call `seize` in Keep staking contract. +Returns remainder of slashing amount in T + +Note this internal function doesn't update stake checkpoints + +### seizeNu + +```solidity +function seizeNu(struct TokenStaking.StakingProviderInfo stakingProviderStruct, uint96 tAmountToSlash, uint256 rewardMultiplier) internal returns (uint96) +``` + +Convert amount from T to NU and call `slashStaker` in NuCypher staking contract. +Returns remainder of slashing amount in T + +Note this internal function doesn't update the stake checkpoints + +### cleanAuthorizedApplications + +```solidity +function cleanAuthorizedApplications(struct TokenStaking.StakingProviderInfo stakingProviderStruct, uint256 numberToDelete) internal +``` + +Removes application with zero authorization from authorized +applications array + +### newStakeCheckpoint + +```solidity +function newStakeCheckpoint(address _delegator, uint96 _amount, bool increase) internal +``` + +Creates new checkpoints due to a change of stake amount + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| _delegator | address | Address of the staking provider acting as delegator | +| _amount | uint96 | Amount of T to increment | +| increase | bool | True if the change is an increase, false if a decrease | + +### increaseStakeCheckpoint + +```solidity +function increaseStakeCheckpoint(address _delegator, uint96 _amount) internal +``` + +Creates new checkpoints due to an increment of a stakers' stake + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| _delegator | address | Address of the staking provider acting as delegator | +| _amount | uint96 | Amount of T to increment | + +### decreaseStakeCheckpoint + +```solidity +function decreaseStakeCheckpoint(address _delegator, uint96 _amount) internal +``` + +Creates new checkpoints due to a decrease of a stakers' stake + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| _delegator | address | Address of the stake owner acting as delegator | +| _amount | uint96 | Amount of T to decrease | + +### getNuAmountInT + +```solidity +function getNuAmountInT(address owner, address stakingProvider) internal returns (uint96) +``` + +Returns amount of Nu stake in the NuCypher staking contract for +the specified staking provider. +Resulting value in T denomination + +### _transferGovernance + +```solidity +function _transferGovernance(address newGuvnor) internal virtual +``` + +### getKeepAmountInT + +```solidity +function getKeepAmountInT(address stakingProvider) internal view returns (uint96) +``` + +Returns amount of Keep stake in the Keep staking contract for +the specified staking provider. +Resulting value in T denomination + +### convertToT + +```solidity +function convertToT(uint256 amount, uint256 ratio) internal pure returns (uint96 tAmount, uint256 remainder) +``` + +Returns the T token amount that's obtained from `amount` legacy +tokens for the given `ratio`, and the remainder that can't be +converted. + +### convertFromT + +```solidity +function convertFromT(uint96 tAmount, uint256 ratio) internal pure returns (uint256 amount, uint96 tRemainder) +``` + +Returns the amount of legacy tokens that's obtained from +`tAmount` T tokens for the given `ratio`, and the T remainder +that can't be converted. + diff --git a/docs/app-development/staking-contract-and-dao/staking-contract-and-dao-api/generated-docs/token/T.md b/docs/app-development/staking-contract-and-dao/staking-contract-and-dao-api/generated-docs/token/T.md new file mode 100644 index 0000000..d369213 --- /dev/null +++ b/docs/app-development/staking-contract-and-dao/staking-contract-and-dao-api/generated-docs/token/T.md @@ -0,0 +1,83 @@ +# Solidity API + +## T + +Threshold Network T token + +By default, token balance does not account for voting power. +This makes transfers cheaper. The downside is that it requires users +to delegate to themselves to activate checkpoints and have their +voting power tracked. + +### DELEGATION_TYPEHASH + +```solidity +bytes32 DELEGATION_TYPEHASH +``` + +The EIP-712 typehash for the delegation struct used by +`delegateBySig`. + +### constructor + +```solidity +constructor() public +``` + +### delegateBySig + +```solidity +function delegateBySig(address signatory, address delegatee, uint256 deadline, uint8 v, bytes32 r, bytes32 s) external +``` + +Delegates votes from signatory to `delegatee` + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| signatory | address | | +| delegatee | address | The address to delegate votes to | +| deadline | uint256 | The time at which to expire the signature | +| v | uint8 | The recovery byte of the signature | +| r | bytes32 | Half of the ECDSA signature pair | +| s | bytes32 | Half of the ECDSA signature pair | + +### delegate + +```solidity +function delegate(address delegatee) public virtual +``` + +Delegate votes from `msg.sender` to `delegatee`. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| delegatee | address | The address to delegate votes to | + +### beforeTokenTransfer + +```solidity +function beforeTokenTransfer(address from, address to, uint256 amount) internal +``` + +Hook that is called before any transfer of tokens. This includes + minting and burning. + +Calling conditions: +- when `from` and `to` are both non-zero, `amount` of `from`'s tokens + will be to transferred to `to`. +- when `from` is zero, `amount` tokens will be minted for `to`. +- when `to` is zero, `amount` of ``from``'s tokens will be burned. +- `from` and `to` are never both zero. + +### delegate + +```solidity +function delegate(address delegator, address delegatee) internal virtual +``` + +Change delegation for `delegator` to `delegatee`. + diff --git a/docs/app-development/staking-contract-and-dao/staking-contract-and-dao-api/generated-docs/utils/PercentUtils.md b/docs/app-development/staking-contract-and-dao/staking-contract-and-dao-api/generated-docs/utils/PercentUtils.md new file mode 100644 index 0000000..42ce9de --- /dev/null +++ b/docs/app-development/staking-contract-and-dao/staking-contract-and-dao-api/generated-docs/utils/PercentUtils.md @@ -0,0 +1,16 @@ +# Solidity API + +## PercentUtils + +### percent + +```solidity +function percent(uint256 a, uint256 b) internal pure returns (uint256) +``` + +### asPercentOf + +```solidity +function asPercentOf(uint256 a, uint256 b) internal pure returns (uint256) +``` + diff --git a/docs/app-development/staking-contract-and-dao/staking-contract-and-dao-api/generated-docs/utils/SafeTUpgradeable.md b/docs/app-development/staking-contract-and-dao/staking-contract-and-dao-api/generated-docs/utils/SafeTUpgradeable.md new file mode 100644 index 0000000..9313656 --- /dev/null +++ b/docs/app-development/staking-contract-and-dao/staking-contract-and-dao-api/generated-docs/utils/SafeTUpgradeable.md @@ -0,0 +1,27 @@ +# Solidity API + +## SafeTUpgradeable + +A wrapper around OpenZeppelin's `SafeERC20Upgradeable` but specific +to the T token. Use this library in upgradeable contracts. If your +contract is non-upgradeable, then the traditional `SafeERC20` works. +The motivation is to prevent upgradeable contracts that use T from +depending on the `Address` library, which can be problematic since +it uses `delegatecall`, which is discouraged by OpenZeppelin for use +in upgradeable contracts. + +This implementation force-casts T to `IERC20Upgradeable` to make it +work with `SafeERC20Upgradeable`. + +### safeTransfer + +```solidity +function safeTransfer(contract T token, address to, uint256 value) internal +``` + +### safeTransferFrom + +```solidity +function safeTransferFrom(contract T token, address from, address to, uint256 value) internal +``` + diff --git a/docs/app-development/staking-contract-and-dao/staking-contract-and-dao-api/generated-docs/vending/VendingMachine.md b/docs/app-development/staking-contract-and-dao/staking-contract-and-dao-api/generated-docs/vending/VendingMachine.md new file mode 100644 index 0000000..926617e --- /dev/null +++ b/docs/app-development/staking-contract-and-dao/staking-contract-and-dao-api/generated-docs/vending/VendingMachine.md @@ -0,0 +1,201 @@ +# Solidity API + +## VendingMachine + +Contract implements a special update protocol to enable KEEP/NU +token holders to wrap their tokens and obtain T tokens according +to a fixed ratio. This will go on indefinitely and enable NU and +KEEP token holders to join T network without needing to buy or +sell any assets. Logistically, anyone holding NU or KEEP can wrap +those assets in order to upgrade to T. They can also unwrap T in +order to downgrade back to the underlying asset. There is a separate +instance of this contract deployed for KEEP holders and a separate +instance of this contract deployed for NU holders. + +### WRAPPED_TOKEN_CONVERSION_PRECISION + +```solidity +uint256 WRAPPED_TOKEN_CONVERSION_PRECISION +``` + +Number of decimal places of precision in conversion to/from +wrapped tokens (assuming typical ERC20 token with 18 decimals). +This implies that amounts of wrapped tokens below this precision +won't take part in the conversion. E.g., for a value of 3, then +for a conversion of 1.123456789 wrapped tokens, only 1.123 is +convertible (i.e., 3 decimal places), and 0.000456789 is left. + +### FLOATING_POINT_DIVISOR + +```solidity +uint256 FLOATING_POINT_DIVISOR +``` + +Divisor for precision purposes, used to represent fractions. + +### wrappedToken + +```solidity +contract IERC20 wrappedToken +``` + +The token being wrapped to T (KEEP/NU). + +### tToken + +```solidity +contract T tToken +``` + +T token contract. + +### ratio + +```solidity +uint256 ratio +``` + +The ratio with which T token is converted based on the provided +token being wrapped (KEEP/NU), expressed in 1e18 precision. + +When wrapping: +x [T] = amount [KEEP/NU] * ratio / FLOATING_POINT_DIVISOR + +When unwrapping: +x [KEEP/NU] = amount [T] * FLOATING_POINT_DIVISOR / ratio + +### wrappedBalance + +```solidity +mapping(address => uint256) wrappedBalance +``` + +The total balance of wrapped tokens for the given holder +account. Only holders that have previously wrapped KEEP/NU to T +can unwrap, up to the amount previously wrapped. + +### Wrapped + +```solidity +event Wrapped(address recipient, uint256 wrappedTokenAmount, uint256 tTokenAmount) +``` + +### Unwrapped + +```solidity +event Unwrapped(address recipient, uint256 tTokenAmount, uint256 wrappedTokenAmount) +``` + +### constructor + +```solidity +constructor(contract IERC20 _wrappedToken, contract T _tToken, uint96 _wrappedTokenAllocation, uint96 _tTokenAllocation) public +``` + +Sets the reference to `wrappedToken` and `tToken`. Initializes +conversion `ratio` between wrapped token and T based on the +provided `_tTokenAllocation` and `_wrappedTokenAllocation`. + +Multiplications in this contract can't overflow uint256 as we +restrict `_wrappedTokenAllocation` and `_tTokenAllocation` to +96 bits and FLOATING_POINT_DIVISOR fits in less than 60 bits. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| _wrappedToken | contract IERC20 | Address to ERC20 token that will be wrapped to T | +| _tToken | contract T | Address of T token | +| _wrappedTokenAllocation | uint96 | The total supply of the token that will be wrapped to T | +| _tTokenAllocation | uint96 | The allocation of T this instance of Vending Machine will receive | + +### wrap + +```solidity +function wrap(uint256 amount) external +``` + +Wraps up to the the given `amount` of the token (KEEP/NU) and +releases T token proportionally to the amount being wrapped with +respect to the wrap ratio. The token holder needs to have at +least the given amount of the wrapped token (KEEP/NU) approved +to transfer to the Vending Machine before calling this function. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| amount | uint256 | The amount of KEEP/NU to be wrapped | + +### receiveApproval + +```solidity +function receiveApproval(address from, uint256 amount, address token, bytes) external +``` + +Wraps up to the given amount of the token (KEEP/NU) and releases +T token proportionally to the amount being wrapped with respect +to the wrap ratio. This is a shortcut to `wrap` function that +avoids a separate approval transaction. Only KEEP/NU token +is allowed as a caller, so please call this function via +token's `approveAndCall`. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| from | address | Caller's address, must be the same as `wrappedToken` field | +| amount | uint256 | The amount of KEEP/NU to be wrapped | +| token | address | Token's address, must be the same as `wrappedToken` field | +| | bytes | | + +### unwrap + +```solidity +function unwrap(uint256 amount) external +``` + +Unwraps up to the given `amount` of T back to the legacy token +(KEEP/NU) according to the wrap ratio. It can only be called by +a token holder who previously wrapped their tokens in this +vending machine contract. The token holder can't unwrap more +tokens than they originally wrapped. The token holder needs to +have at least the given amount of T tokens approved to transfer +to the Vending Machine before calling this function. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| amount | uint256 | The amount of T to unwrap back to the collateral (KEEP/NU) | + +### conversionToT + +```solidity +function conversionToT(uint256 amount) public view returns (uint256 tAmount, uint256 wrappedRemainder) +``` + +Returns the T token amount that's obtained from `amount` wrapped +tokens (KEEP/NU), and the remainder that can't be upgraded. + +### conversionFromT + +```solidity +function conversionFromT(uint256 amount) public view returns (uint256 wrappedAmount, uint256 tRemainder) +``` + +The amount of wrapped tokens (KEEP/NU) that's obtained from +`amount` T tokens, and the remainder that can't be downgraded. + +### _wrap + +```solidity +function _wrap(address tokenHolder, uint256 wrappedTokenAmount) internal +``` + +### _unwrap + +```solidity +function _unwrap(address tokenHolder, uint256 tTokenAmount) internal +``` + diff --git a/docs/app-development/tbtc-v2/README.md b/docs/app-development/tbtc-v2/README.md index df923a0..943187e 100644 --- a/docs/app-development/tbtc-v2/README.md +++ b/docs/app-development/tbtc-v2/README.md @@ -1,5 +1,5 @@ -# TBTCv2 +# tBTC To get familiarized with ECDSA contracts API, go [here](ecdsa-api/generated-docs/index.md). -To get familiarized with ECDSA contracts API, go [here](tbtc-v2-api/generated-docs/index.md). +To get familiarized with Bridge contracts API, go [here](tbtc-v2-api/generated-docs/index.md). diff --git a/docs/app-development/tbtc-v2/ecdsa-api/README.md b/docs/app-development/tbtc-v2/ecdsa-api/README.md new file mode 100644 index 0000000..fdc5053 --- /dev/null +++ b/docs/app-development/tbtc-v2/ecdsa-api/README.md @@ -0,0 +1,22 @@ +# ECDSA API + +You can learn about APIs of contracts related to ECDSA under the following +links: + +[EcdsaAuthorization](./generated-docs/libraries/EcdsaAuthorization.md) + +[EcdsaDkg](./generated-docs/libraries/EcdsaDkg.md) + +[EcdsaDkgValidator](./generated-docs/EcdsaDkgValidator.md) + +[EcdsaInactivity](./generated-docs/libraries/EcdsaInactivity.md) + +[IWalletOwner](./generated-docs/api/IWalletOwner.md) + +[IWalletRegistry](./generated-docs/api/IWalletRegistry.md) + +[WalletRegistry](./generated-docs/WalletRegistry.md) + +[WalletRegistryGovernance](./generated-docs/WalletRegistryGovernance.md) + +[Wallets](./generated-docs/libraries/Wallets.md) diff --git a/docs/app-development/tbtc-v2/ecdsa-api/generated-docs/EcdsaDkgValidator.md b/docs/app-development/tbtc-v2/ecdsa-api/generated-docs/EcdsaDkgValidator.md new file mode 100644 index 0000000..7174295 --- /dev/null +++ b/docs/app-development/tbtc-v2/ecdsa-api/generated-docs/EcdsaDkgValidator.md @@ -0,0 +1,183 @@ +# Solidity API + +## 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. | + diff --git a/docs/app-development/tbtc-v2/ecdsa-api/generated-docs/WalletRegistry.md b/docs/app-development/tbtc-v2/ecdsa-api/generated-docs/WalletRegistry.md new file mode 100644 index 0000000..d2a163b --- /dev/null +++ b/docs/app-development/tbtc-v2/ecdsa-api/generated-docs/WalletRegistry.md @@ -0,0 +1,1155 @@ +# Solidity API + +## 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 RewardParametersUpdated(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:\n` 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 | +| ---- | ---- | ----------- | +| 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. | + +### isDkgResultValid + +```solidity +function isDkgResultValid(struct EcdsaDkg.Result result) external view returns (bool, string) +``` + +Checks if DKG result is valid for the current DKG. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| 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 | | + +### 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. | + +### hasSeedTimedOut + +```solidity +function hasSeedTimedOut() external view returns (bool) +``` + +Checks if awaiting seed timed out. + +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +| [0] | bool | True if awaiting seed timed out, false otherwise. | + +### hasDkgTimedOut + +```solidity +function hasDkgTimedOut() external view returns (bool) +``` + +Checks if DKG timed out. The DKG timeout period includes time required +for off-chain protocol execution and time for the result publication +for all group members. After this time result cannot be submitted +and DKG can be notified about the timeout. + +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +| [0] | bool | True if DKG timed out, false otherwise. | + +### getWallet + +```solidity +function getWallet(bytes32 walletID) external view returns (struct Wallets.Wallet) +``` + +### 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. | + +### isWalletRegistered + +```solidity +function isWalletRegistered(bytes32 walletID) external view returns (bool) +``` + +Checks if a wallet with the given ID is registered. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| walletID | bytes32 | Wallet's ID. | + +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +| [0] | bool | True if wallet is registered, false otherwise. | + +### minimumAuthorization + +```solidity +function minimumAuthorization() external view returns (uint96) +``` + +The minimum authorization amount required so that operator can +participate in ECDSA Wallet operations. + +### eligibleStake + +```solidity +function eligibleStake(address stakingProvider) external view returns (uint96) +``` + +Returns the current value of the staking provider's eligible +stake. Eligible stake is defined as the currently authorized +stake minus the pending authorization decrease. Eligible stake +is what is used for operator's weight in the sortition pool. +If the authorized stake minus the pending authorization decrease +is below the minimum authorization, eligible stake is 0. + +### availableRewards + +```solidity +function availableRewards(address stakingProvider) external view returns (uint96) +``` + +Returns the amount of rewards available for withdrawal for the +given staking provider. Reverts if staking provider has not +registered the operator address. + +### pendingAuthorizationDecrease + +```solidity +function pendingAuthorizationDecrease(address stakingProvider) external view returns (uint96) +``` + +Returns the amount of stake that is pending authorization +decrease for the given staking provider. If no authorization +decrease has been requested, returns zero. + +### remainingAuthorizationDecreaseDelay + +```solidity +function remainingAuthorizationDecreaseDelay(address stakingProvider) external view returns (uint64) +``` + +Returns the remaining time in seconds that needs to pass before +the requested authorization decrease can be approved. +If the sortition pool state was not updated yet by the operator +after requesting the authorization decrease, returns +`type(uint64).max`. + +### stakingProviderToOperator + +```solidity +function stakingProviderToOperator(address stakingProvider) public view returns (address) +``` + +Returns operator registered for the given staking provider. + +### operatorToStakingProvider + +```solidity +function operatorToStakingProvider(address operator) public view returns (address) +``` + +Returns staking provider of the given operator. + +### isOperatorUpToDate + +```solidity +function isOperatorUpToDate(address operator) external view returns (bool) +``` + +Checks if the operator's authorized stake is in sync with +operator's weight in the sortition pool. +If the operator is not in the sortition pool and their +authorized stake is non-zero, function returns false. + +### isOperatorInPool + +```solidity +function isOperatorInPool(address operator) external view returns (bool) +``` + +Returns true if the given operator is in the sortition pool. +Otherwise, returns false. + +### selectGroup + +```solidity +function selectGroup() external view returns (uint32[]) +``` + +Selects a new group of operators. Can only be called when DKG +is in progress and the pool is locked. +At least one operator has to be registered in the pool, +otherwise the function fails reverting the transaction. + +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +| [0] | uint32[] | IDs of selected group members. | + +### dkgParameters + +```solidity +function dkgParameters() external view returns (struct EcdsaDkg.Parameters) +``` + +Retrieves dkg parameters that were set in DKG library. + +### authorizationParameters + +```solidity +function authorizationParameters() external view returns (uint96 minimumAuthorization, uint64 authorizationDecreaseDelay, uint64 authorizationDecreaseChangePeriod) +``` + +Returns authorization-related parameters. + +The minimum authorization is also returned by `minimumAuthorization()` +function, as a requirement of `IApplication` interface. + +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +| minimumAuthorization | uint96 | The minimum authorization amount required so that operator can participate in the random beacon. This amount is required to execute slashing for providing a malicious DKG result or when a relay entry times out. | +| authorizationDecreaseDelay | uint64 | Delay in seconds that needs to pass between the time authorization decrease is requested and the time that request gets approved. Protects against free-riders earning rewards and not being active in the network. | +| authorizationDecreaseChangePeriod | uint64 | Authorization decrease change period in seconds. It is the time, before authorization decrease delay end, during which the pending authorization decrease request can be overwritten. If set to 0, pending authorization decrease request can not be overwritten until the entire `authorizationDecreaseDelay` ends. If set to value equal `authorizationDecreaseDelay`, request can always be overwritten. | + +### rewardParameters + +```solidity +function rewardParameters() external view returns (uint256 maliciousDkgResultNotificationRewardMultiplier, uint256 sortitionPoolRewardsBanDuration) +``` + +Retrieves reward-related parameters. + +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +| maliciousDkgResultNotificationRewardMultiplier | uint256 | 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 | uint256 | Duration of the sortition pool rewards ban imposed on operators who missed their turn for DKG result submission or who failed a heartbeat. | + +### slashingParameters + +```solidity +function slashingParameters() external view returns (uint96 maliciousDkgResultSlashingAmount) +``` + +Retrieves slashing-related parameters. + +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +| maliciousDkgResultSlashingAmount | uint96 | 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`. | + +### gasParameters + +```solidity +function gasParameters() external view returns (uint256 dkgResultSubmissionGas, uint256 dkgResultApprovalGasOffset, uint256 notifyOperatorInactivityGasOffset, uint256 notifySeedTimeoutGasOffset, uint256 notifyDkgTimeoutNegativeGasOffset) +``` + +Retrieves gas-related parameters. + +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +| dkgResultSubmissionGas | uint256 | 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 | uint256 | 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 | uint256 | 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 | uint256 | 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 | uint256 | 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. | + diff --git a/docs/app-development/tbtc-v2/ecdsa-api/generated-docs/WalletRegistryGovernance.md b/docs/app-development/tbtc-v2/ecdsa-api/generated-docs/WalletRegistryGovernance.md new file mode 100644 index 0000000..096d949 --- /dev/null +++ b/docs/app-development/tbtc-v2/ecdsa-api/generated-docs/WalletRegistryGovernance.md @@ -0,0 +1,1422 @@ +# Solidity API + +## WalletRegistryGovernance + +Owns the `WalletRegistry` contract and is responsible for updating +its governable parameters in respect to the governance delay. + +### newGovernanceDelay + +```solidity +uint256 newGovernanceDelay +``` + +### governanceDelayChangeInitiated + +```solidity +uint256 governanceDelayChangeInitiated +``` + +### newWalletRegistryGovernance + +```solidity +address newWalletRegistryGovernance +``` + +### walletRegistryGovernanceTransferInitiated + +```solidity +uint256 walletRegistryGovernanceTransferInitiated +``` + +### newWalletOwner + +```solidity +address newWalletOwner +``` + +### walletOwnerChangeInitiated + +```solidity +uint256 walletOwnerChangeInitiated +``` + +### newMinimumAuthorization + +```solidity +uint96 newMinimumAuthorization +``` + +### minimumAuthorizationChangeInitiated + +```solidity +uint256 minimumAuthorizationChangeInitiated +``` + +### newAuthorizationDecreaseDelay + +```solidity +uint64 newAuthorizationDecreaseDelay +``` + +### authorizationDecreaseDelayChangeInitiated + +```solidity +uint256 authorizationDecreaseDelayChangeInitiated +``` + +### newAuthorizationDecreaseChangePeriod + +```solidity +uint64 newAuthorizationDecreaseChangePeriod +``` + +### authorizationDecreaseChangePeriodChangeInitiated + +```solidity +uint256 authorizationDecreaseChangePeriodChangeInitiated +``` + +### newMaliciousDkgResultSlashingAmount + +```solidity +uint96 newMaliciousDkgResultSlashingAmount +``` + +### maliciousDkgResultSlashingAmountChangeInitiated + +```solidity +uint256 maliciousDkgResultSlashingAmountChangeInitiated +``` + +### newMaliciousDkgResultNotificationRewardMultiplier + +```solidity +uint256 newMaliciousDkgResultNotificationRewardMultiplier +``` + +### maliciousDkgResultNotificationRewardMultiplierChangeInitiated + +```solidity +uint256 maliciousDkgResultNotificationRewardMultiplierChangeInitiated +``` + +### newSortitionPoolRewardsBanDuration + +```solidity +uint256 newSortitionPoolRewardsBanDuration +``` + +### sortitionPoolRewardsBanDurationChangeInitiated + +```solidity +uint256 sortitionPoolRewardsBanDurationChangeInitiated +``` + +### newDkgSeedTimeout + +```solidity +uint256 newDkgSeedTimeout +``` + +### dkgSeedTimeoutChangeInitiated + +```solidity +uint256 dkgSeedTimeoutChangeInitiated +``` + +### newDkgResultChallengePeriodLength + +```solidity +uint256 newDkgResultChallengePeriodLength +``` + +### dkgResultChallengePeriodLengthChangeInitiated + +```solidity +uint256 dkgResultChallengePeriodLengthChangeInitiated +``` + +### newDkgResultChallengeExtraGas + +```solidity +uint256 newDkgResultChallengeExtraGas +``` + +### dkgResultChallengeExtraGasChangeInitiated + +```solidity +uint256 dkgResultChallengeExtraGasChangeInitiated +``` + +### newDkgResultSubmissionTimeout + +```solidity +uint256 newDkgResultSubmissionTimeout +``` + +### dkgResultSubmissionTimeoutChangeInitiated + +```solidity +uint256 dkgResultSubmissionTimeoutChangeInitiated +``` + +### newSubmitterPrecedencePeriodLength + +```solidity +uint256 newSubmitterPrecedencePeriodLength +``` + +### dkgSubmitterPrecedencePeriodLengthChangeInitiated + +```solidity +uint256 dkgSubmitterPrecedencePeriodLengthChangeInitiated +``` + +### newDkgResultSubmissionGas + +```solidity +uint256 newDkgResultSubmissionGas +``` + +### dkgResultSubmissionGasChangeInitiated + +```solidity +uint256 dkgResultSubmissionGasChangeInitiated +``` + +### newDkgResultApprovalGasOffset + +```solidity +uint256 newDkgResultApprovalGasOffset +``` + +### dkgResultApprovalGasOffsetChangeInitiated + +```solidity +uint256 dkgResultApprovalGasOffsetChangeInitiated +``` + +### newNotifyOperatorInactivityGasOffset + +```solidity +uint256 newNotifyOperatorInactivityGasOffset +``` + +### notifyOperatorInactivityGasOffsetChangeInitiated + +```solidity +uint256 notifyOperatorInactivityGasOffsetChangeInitiated +``` + +### newNotifySeedTimeoutGasOffset + +```solidity +uint256 newNotifySeedTimeoutGasOffset +``` + +### notifySeedTimeoutGasOffsetChangeInitiated + +```solidity +uint256 notifySeedTimeoutGasOffsetChangeInitiated +``` + +### newNotifyDkgTimeoutNegativeGasOffset + +```solidity +uint256 newNotifyDkgTimeoutNegativeGasOffset +``` + +### notifyDkgTimeoutNegativeGasOffsetChangeInitiated + +```solidity +uint256 notifyDkgTimeoutNegativeGasOffsetChangeInitiated +``` + +### newReimbursementPool + +```solidity +address payable newReimbursementPool +``` + +### reimbursementPoolChangeInitiated + +```solidity +uint256 reimbursementPoolChangeInitiated +``` + +### walletRegistry + +```solidity +contract WalletRegistry walletRegistry +``` + +### governanceDelay + +```solidity +uint256 governanceDelay +``` + +### GovernanceDelayUpdateStarted + +```solidity +event GovernanceDelayUpdateStarted(uint256 governanceDelay, uint256 timestamp) +``` + +### GovernanceDelayUpdated + +```solidity +event GovernanceDelayUpdated(uint256 governanceDelay) +``` + +### WalletRegistryGovernanceTransferStarted + +```solidity +event WalletRegistryGovernanceTransferStarted(address newWalletRegistryGovernance, uint256 timestamp) +``` + +### WalletRegistryGovernanceTransferred + +```solidity +event WalletRegistryGovernanceTransferred(address newWalletRegistryGovernance) +``` + +### WalletOwnerUpdateStarted + +```solidity +event WalletOwnerUpdateStarted(address walletOwner, uint256 timestamp) +``` + +### WalletOwnerUpdated + +```solidity +event WalletOwnerUpdated(address walletOwner) +``` + +### MinimumAuthorizationUpdateStarted + +```solidity +event MinimumAuthorizationUpdateStarted(uint96 minimumAuthorization, uint256 timestamp) +``` + +### MinimumAuthorizationUpdated + +```solidity +event MinimumAuthorizationUpdated(uint96 minimumAuthorization) +``` + +### AuthorizationDecreaseDelayUpdateStarted + +```solidity +event AuthorizationDecreaseDelayUpdateStarted(uint64 authorizationDecreaseDelay, uint256 timestamp) +``` + +### AuthorizationDecreaseDelayUpdated + +```solidity +event AuthorizationDecreaseDelayUpdated(uint64 authorizationDecreaseDelay) +``` + +### AuthorizationDecreaseChangePeriodUpdateStarted + +```solidity +event AuthorizationDecreaseChangePeriodUpdateStarted(uint64 authorizationDecreaseChangePeriod, uint256 timestamp) +``` + +### AuthorizationDecreaseChangePeriodUpdated + +```solidity +event AuthorizationDecreaseChangePeriodUpdated(uint64 authorizationDecreaseChangePeriod) +``` + +### MaliciousDkgResultSlashingAmountUpdateStarted + +```solidity +event MaliciousDkgResultSlashingAmountUpdateStarted(uint256 maliciousDkgResultSlashingAmount, uint256 timestamp) +``` + +### MaliciousDkgResultSlashingAmountUpdated + +```solidity +event MaliciousDkgResultSlashingAmountUpdated(uint256 maliciousDkgResultSlashingAmount) +``` + +### MaliciousDkgResultNotificationRewardMultiplierUpdateStarted + +```solidity +event MaliciousDkgResultNotificationRewardMultiplierUpdateStarted(uint256 maliciousDkgResultNotificationRewardMultiplier, uint256 timestamp) +``` + +### MaliciousDkgResultNotificationRewardMultiplierUpdated + +```solidity +event MaliciousDkgResultNotificationRewardMultiplierUpdated(uint256 maliciousDkgResultNotificationRewardMultiplier) +``` + +### SortitionPoolRewardsBanDurationUpdateStarted + +```solidity +event SortitionPoolRewardsBanDurationUpdateStarted(uint256 sortitionPoolRewardsBanDuration, uint256 timestamp) +``` + +### SortitionPoolRewardsBanDurationUpdated + +```solidity +event SortitionPoolRewardsBanDurationUpdated(uint256 sortitionPoolRewardsBanDuration) +``` + +### DkgSeedTimeoutUpdateStarted + +```solidity +event DkgSeedTimeoutUpdateStarted(uint256 dkgSeedTimeout, uint256 timestamp) +``` + +### DkgSeedTimeoutUpdated + +```solidity +event DkgSeedTimeoutUpdated(uint256 dkgSeedTimeout) +``` + +### DkgResultChallengePeriodLengthUpdateStarted + +```solidity +event DkgResultChallengePeriodLengthUpdateStarted(uint256 dkgResultChallengePeriodLength, uint256 timestamp) +``` + +### DkgResultChallengePeriodLengthUpdated + +```solidity +event DkgResultChallengePeriodLengthUpdated(uint256 dkgResultChallengePeriodLength) +``` + +### DkgResultChallengeExtraGasUpdateStarted + +```solidity +event DkgResultChallengeExtraGasUpdateStarted(uint256 dkgResultChallengeExtraGas, uint256 timestamp) +``` + +### DkgResultChallengeExtraGasUpdated + +```solidity +event DkgResultChallengeExtraGasUpdated(uint256 dkgResultChallengeExtraGas) +``` + +### DkgResultSubmissionTimeoutUpdateStarted + +```solidity +event DkgResultSubmissionTimeoutUpdateStarted(uint256 dkgResultSubmissionTimeout, uint256 timestamp) +``` + +### DkgResultSubmissionTimeoutUpdated + +```solidity +event DkgResultSubmissionTimeoutUpdated(uint256 dkgResultSubmissionTimeout) +``` + +### DkgSubmitterPrecedencePeriodLengthUpdateStarted + +```solidity +event DkgSubmitterPrecedencePeriodLengthUpdateStarted(uint256 submitterPrecedencePeriodLength, uint256 timestamp) +``` + +### DkgSubmitterPrecedencePeriodLengthUpdated + +```solidity +event DkgSubmitterPrecedencePeriodLengthUpdated(uint256 submitterPrecedencePeriodLength) +``` + +### DkgResultSubmissionGasUpdateStarted + +```solidity +event DkgResultSubmissionGasUpdateStarted(uint256 dkgResultSubmissionGas, uint256 timestamp) +``` + +### DkgResultSubmissionGasUpdated + +```solidity +event DkgResultSubmissionGasUpdated(uint256 dkgResultSubmissionGas) +``` + +### DkgResultApprovalGasOffsetUpdateStarted + +```solidity +event DkgResultApprovalGasOffsetUpdateStarted(uint256 dkgResultApprovalGasOffset, uint256 timestamp) +``` + +### DkgResultApprovalGasOffsetUpdated + +```solidity +event DkgResultApprovalGasOffsetUpdated(uint256 dkgResultApprovalGasOffset) +``` + +### NotifyOperatorInactivityGasOffsetUpdateStarted + +```solidity +event NotifyOperatorInactivityGasOffsetUpdateStarted(uint256 notifyOperatorInactivityGasOffset, uint256 timestamp) +``` + +### NotifyOperatorInactivityGasOffsetUpdated + +```solidity +event NotifyOperatorInactivityGasOffsetUpdated(uint256 notifyOperatorInactivityGasOffset) +``` + +### NotifySeedTimeoutGasOffsetUpdateStarted + +```solidity +event NotifySeedTimeoutGasOffsetUpdateStarted(uint256 notifySeedTimeoutGasOffset, uint256 timestamp) +``` + +### NotifySeedTimeoutGasOffsetUpdated + +```solidity +event NotifySeedTimeoutGasOffsetUpdated(uint256 notifySeedTimeoutGasOffset) +``` + +### NotifyDkgTimeoutNegativeGasOffsetUpdateStarted + +```solidity +event NotifyDkgTimeoutNegativeGasOffsetUpdateStarted(uint256 notifyDkgTimeoutNegativeGasOffset, uint256 timestamp) +``` + +### NotifyDkgTimeoutNegativeGasOffsetUpdated + +```solidity +event NotifyDkgTimeoutNegativeGasOffsetUpdated(uint256 notifyDkgTimeoutNegativeGasOffset) +``` + +### ReimbursementPoolUpdateStarted + +```solidity +event ReimbursementPoolUpdateStarted(address reimbursementPool, uint256 timestamp) +``` + +### ReimbursementPoolUpdated + +```solidity +event ReimbursementPoolUpdated(address reimbursementPool) +``` + +### onlyAfterGovernanceDelay + +```solidity +modifier onlyAfterGovernanceDelay(uint256 changeInitiatedTimestamp) +``` + +Reverts if called before the governance delay elapses. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| changeInitiatedTimestamp | uint256 | Timestamp indicating the beginning of the change. | + +### constructor + +```solidity +constructor(contract WalletRegistry _walletRegistry, uint256 _governanceDelay) public +``` + +### upgradeRandomBeacon + +```solidity +function upgradeRandomBeacon(address _newRandomBeacon) external +``` + +Upgrades the random beacon. + +Can be called only by the contract owner. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| _newRandomBeacon | address | New random beacon address | + +### initializeWalletOwner + +```solidity +function initializeWalletOwner(address _walletOwner) external +``` + +Initializes the Wallet Owner's address. + +Can be called only by the contract owner. It can be called only if +walletOwner has not been set before. It doesn't enforce a governance +delay for the initial update. Any subsequent updates should be performed +with beginWalletOwnerUpdate/finalizeWalletOwnerUpdate with respect +of a governance delay. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| _walletOwner | address | The Wallet Owner's address | + +### beginGovernanceDelayUpdate + +```solidity +function beginGovernanceDelayUpdate(uint256 _newGovernanceDelay) external +``` + +Begins the governance delay update process. + +Can be called only by the contract owner. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| _newGovernanceDelay | uint256 | New governance delay | + +### finalizeGovernanceDelayUpdate + +```solidity +function finalizeGovernanceDelayUpdate() external +``` + +Finalizes the governance delay update process. + +Can be called only by the contract owner, after the governance +delay elapses. + +### beginWalletRegistryGovernanceTransfer + +```solidity +function beginWalletRegistryGovernanceTransfer(address _newWalletRegistryGovernance) external +``` + +Begins the wallet registry governance transfer process. + +Can be called only by the contract owner. + +### finalizeWalletRegistryGovernanceTransfer + +```solidity +function finalizeWalletRegistryGovernanceTransfer() external +``` + +Finalizes the wallet registry governance transfer process. + +Can be called only by the contract owner, after the governance +delay elapses. + +### beginWalletOwnerUpdate + +```solidity +function beginWalletOwnerUpdate(address _newWalletOwner) external +``` + +Begins the wallet owner update process. + +Can be called only by the contract owner. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| _newWalletOwner | address | New wallet owner address | + +### finalizeWalletOwnerUpdate + +```solidity +function finalizeWalletOwnerUpdate() external +``` + +Finalizes the wallet owner update process. + +Can be called only by the contract owner, after the governance +delay elapses. + +### beginMinimumAuthorizationUpdate + +```solidity +function beginMinimumAuthorizationUpdate(uint96 _newMinimumAuthorization) external +``` + +Begins the minimum authorization amount update process. + +Can be called only by the contract owner. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| _newMinimumAuthorization | uint96 | New minimum authorization amount. | + +### finalizeMinimumAuthorizationUpdate + +```solidity +function finalizeMinimumAuthorizationUpdate() external +``` + +Finalizes the minimum authorization amount update process. + +Can be called only by the contract owner, after the governance +delay elapses. + +### beginAuthorizationDecreaseDelayUpdate + +```solidity +function beginAuthorizationDecreaseDelayUpdate(uint64 _newAuthorizationDecreaseDelay) external +``` + +Begins the authorization decrease delay update process. + +Can be called only by the contract owner. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| _newAuthorizationDecreaseDelay | uint64 | New authorization decrease delay | + +### finalizeAuthorizationDecreaseDelayUpdate + +```solidity +function finalizeAuthorizationDecreaseDelayUpdate() external +``` + +Finalizes the authorization decrease delay update process. + +Can be called only by the contract owner, after the governance +delay elapses. + +### beginAuthorizationDecreaseChangePeriodUpdate + +```solidity +function beginAuthorizationDecreaseChangePeriodUpdate(uint64 _newAuthorizationDecreaseChangePeriod) external +``` + +Begins the authorization decrease change period update process. + +Can be called only by the contract owner. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| _newAuthorizationDecreaseChangePeriod | uint64 | New authorization decrease change period | + +### finalizeAuthorizationDecreaseChangePeriodUpdate + +```solidity +function finalizeAuthorizationDecreaseChangePeriodUpdate() external +``` + +Finalizes the authorization decrease change period update process. + +Can be called only by the contract owner, after the governance +delay elapses. + +### beginMaliciousDkgResultSlashingAmountUpdate + +```solidity +function beginMaliciousDkgResultSlashingAmountUpdate(uint96 _newMaliciousDkgResultSlashingAmount) external +``` + +Begins the malicious DKG result slashing amount update process. + +Can be called only by the contract owner. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| _newMaliciousDkgResultSlashingAmount | uint96 | New malicious DKG result slashing amount | + +### finalizeMaliciousDkgResultSlashingAmountUpdate + +```solidity +function finalizeMaliciousDkgResultSlashingAmountUpdate() external +``` + +Finalizes the malicious DKG result slashing amount update +process. + +Can be called only by the contract owner, after the governance +delay elapses. + +### beginMaliciousDkgResultNotificationRewardMultiplierUpdate + +```solidity +function beginMaliciousDkgResultNotificationRewardMultiplierUpdate(uint256 _newMaliciousDkgResultNotificationRewardMultiplier) external +``` + +Begins the DKG malicious result notification reward multiplier +update process. + +Can be called only by the contract owner. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| _newMaliciousDkgResultNotificationRewardMultiplier | uint256 | New DKG malicious result notification reward multiplier. | + +### finalizeMaliciousDkgResultNotificationRewardMultiplierUpdate + +```solidity +function finalizeMaliciousDkgResultNotificationRewardMultiplierUpdate() external +``` + +Finalizes the DKG malicious result notification reward +multiplier update process. + +Can be called only by the contract owner, after the governance +delay elapses. + +### beginDkgResultSubmissionGasUpdate + +```solidity +function beginDkgResultSubmissionGasUpdate(uint256 _newDkgResultSubmissionGas) external +``` + +Begins the dkg result submission gas update process. + +Can be called only by the contract owner. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| _newDkgResultSubmissionGas | uint256 | New DKG result submission gas. | + +### finalizeDkgResultSubmissionGasUpdate + +```solidity +function finalizeDkgResultSubmissionGasUpdate() external +``` + +Finalizes the dkg result submission gas update process. + +Can be called only by the contract owner, after the governance +delay elapses. + +### beginDkgResultApprovalGasOffsetUpdate + +```solidity +function beginDkgResultApprovalGasOffsetUpdate(uint256 _newDkgResultApprovalGasOffset) external +``` + +Begins the dkg approval gas offset update process. + +Can be called only by the contract owner. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| _newDkgResultApprovalGasOffset | uint256 | New DKG result approval gas. | + +### finalizeDkgResultApprovalGasOffsetUpdate + +```solidity +function finalizeDkgResultApprovalGasOffsetUpdate() external +``` + +Finalizes the dkg result approval gas offset update process. + +Can be called only by the contract owner, after the governance +delay elapses. + +### beginNotifyOperatorInactivityGasOffsetUpdate + +```solidity +function beginNotifyOperatorInactivityGasOffsetUpdate(uint256 _newNotifyOperatorInactivityGasOffset) external +``` + +Begins the notify operator inactivity gas offset update process. + +Can be called only by the contract owner. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| _newNotifyOperatorInactivityGasOffset | uint256 | New operator inactivity notification gas offset | + +### finalizeNotifyOperatorInactivityGasOffsetUpdate + +```solidity +function finalizeNotifyOperatorInactivityGasOffsetUpdate() external +``` + +Finalizes the notify operator inactivity gas offset update process. + +Can be called only by the contract owner, after the governance +delay elapses. + +### beginNotifySeedTimeoutGasOffsetUpdate + +```solidity +function beginNotifySeedTimeoutGasOffsetUpdate(uint256 _newNotifySeedTimeoutGasOffset) external +``` + +Begins the notify seed for DKG delivery timeout gas offset update +process. + +Can be called only by the contract owner. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| _newNotifySeedTimeoutGasOffset | uint256 | New seed for DKG delivery timeout notification gas offset | + +### finalizeNotifySeedTimeoutGasOffsetUpdate + +```solidity +function finalizeNotifySeedTimeoutGasOffsetUpdate() external +``` + +Finalizes the notify seed for DKG delivery timeout gas offset +update process. + +Can be called only by the contract owner, after the governance +delay elapses. + +### beginNotifyDkgTimeoutNegativeGasOffsetUpdate + +```solidity +function beginNotifyDkgTimeoutNegativeGasOffsetUpdate(uint256 _newNotifyDkgTimeoutNegativeGasOffset) external +``` + +Begins the notify DKG timeout negative gas offset update process. + +Can be called only by the contract owner. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| _newNotifyDkgTimeoutNegativeGasOffset | uint256 | New DKG timeout negative gas notification gas offset | + +### finalizeNotifyDkgTimeoutNegativeGasOffsetUpdate + +```solidity +function finalizeNotifyDkgTimeoutNegativeGasOffsetUpdate() external +``` + +Finalizes the notify DKG timeout negative gas offset update process. + +Can be called only by the contract owner, after the governance +delay elapses. + +### beginReimbursementPoolUpdate + +```solidity +function beginReimbursementPoolUpdate(address payable _newReimbursementPool) external +``` + +Begins the reimbursement pool update process. + +Can be called only by the contract owner. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| _newReimbursementPool | address payable | New reimbursement pool. | + +### finalizeReimbursementPoolUpdate + +```solidity +function finalizeReimbursementPoolUpdate() external +``` + +Finalizes the reimbursement pool update process. + +Can be called only by the contract owner, after the governance +delay elapses. + +### beginSortitionPoolRewardsBanDurationUpdate + +```solidity +function beginSortitionPoolRewardsBanDurationUpdate(uint256 _newSortitionPoolRewardsBanDuration) external +``` + +Begins the sortition pool rewards ban duration update process. + +Can be called only by the contract owner. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| _newSortitionPoolRewardsBanDuration | uint256 | New sortition pool rewards ban duration. | + +### finalizeSortitionPoolRewardsBanDurationUpdate + +```solidity +function finalizeSortitionPoolRewardsBanDurationUpdate() external +``` + +Finalizes the sortition pool rewards ban duration update process. + +Can be called only by the contract owner, after the governance +delay elapses. + +### beginDkgSeedTimeoutUpdate + +```solidity +function beginDkgSeedTimeoutUpdate(uint256 _newDkgSeedTimeout) external +``` + +Begins the DKG seed timeout update process. + +Can be called only by the contract owner. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| _newDkgSeedTimeout | uint256 | New DKG seed timeout in blocks | + +### finalizeDkgSeedTimeoutUpdate + +```solidity +function finalizeDkgSeedTimeoutUpdate() external +``` + +Finalizes the DKG seed timeout update process. + +Can be called only by the contract owner, after the governance +delay elapses. + +### beginDkgResultChallengePeriodLengthUpdate + +```solidity +function beginDkgResultChallengePeriodLengthUpdate(uint256 _newDkgResultChallengePeriodLength) external +``` + +Begins the DKG result challenge period length update process. + +Can be called only by the contract owner. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| _newDkgResultChallengePeriodLength | uint256 | New DKG result challenge period length in blocks | + +### finalizeDkgResultChallengePeriodLengthUpdate + +```solidity +function finalizeDkgResultChallengePeriodLengthUpdate() external +``` + +Finalizes the DKG result challenge period length update process. + +Can be called only by the contract owner, after the governance +delay elapses. + +### beginDkgResultChallengeExtraGasUpdate + +```solidity +function beginDkgResultChallengeExtraGasUpdate(uint256 _newDkgResultChallengeExtraGas) external +``` + +Begins the DKG result challenge extra gas update process. + +Can be called only by the contract owner. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| _newDkgResultChallengeExtraGas | uint256 | New DKG result challenge extra gas | + +### finalizeDkgResultChallengeExtraGasUpdate + +```solidity +function finalizeDkgResultChallengeExtraGasUpdate() external +``` + +Finalizes the DKG result challenge extra gas update process. + +Can be called only by the contract owner, after the governance +delay elapses. + +### beginDkgResultSubmissionTimeoutUpdate + +```solidity +function beginDkgResultSubmissionTimeoutUpdate(uint256 _newDkgResultSubmissionTimeout) external +``` + +Begins the DKG result submission timeout update +process. + +Can be called only by the contract owner. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| _newDkgResultSubmissionTimeout | uint256 | New DKG result submission timeout in blocks | + +### finalizeDkgResultSubmissionTimeoutUpdate + +```solidity +function finalizeDkgResultSubmissionTimeoutUpdate() external +``` + +Finalizes the DKG result submission timeout update +process. + +Can be called only by the contract owner, after the governance +delay elapses. + +### beginDkgSubmitterPrecedencePeriodLengthUpdate + +```solidity +function beginDkgSubmitterPrecedencePeriodLengthUpdate(uint256 _newSubmitterPrecedencePeriodLength) external +``` + +Begins the DKG submitter precedence period length update +process. + +Can be called only by the contract owner. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| _newSubmitterPrecedencePeriodLength | uint256 | New DKG submitter precedence period length in blocks | + +### finalizeDkgSubmitterPrecedencePeriodLengthUpdate + +```solidity +function finalizeDkgSubmitterPrecedencePeriodLengthUpdate() external +``` + +Finalizes the DKG submitter precedence period length update +process. + +Can be called only by the contract owner, after the governance +delay elapses. + +### 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 owner. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| recipient | address | Recipient of withdrawn rewards. | + +### getRemainingGovernanceDelayUpdateTime + +```solidity +function getRemainingGovernanceDelayUpdateTime() external view returns (uint256) +``` + +Get the time remaining until the governance delay can be updated. + +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +| [0] | uint256 | Remaining time in seconds. | + +### getRemainingWalletRegistryGovernanceTransferDelayTime + +```solidity +function getRemainingWalletRegistryGovernanceTransferDelayTime() external view returns (uint256) +``` + +Get the time remaining until the wallet registry governance can +be transferred. + +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +| [0] | uint256 | Remaining time in seconds. | + +### getRemainingMimimumAuthorizationUpdateTime + +```solidity +function getRemainingMimimumAuthorizationUpdateTime() external view returns (uint256) +``` + +Get the time remaining until the minimum authorization amount +can be updated. + +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +| [0] | uint256 | Remaining time in seconds. | + +### getRemainingAuthorizationDecreaseDelayUpdateTime + +```solidity +function getRemainingAuthorizationDecreaseDelayUpdateTime() external view returns (uint256) +``` + +Get the time remaining until the authorization decrease delay +can be updated. + +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +| [0] | uint256 | Remaining time in seconds. | + +### getRemainingAuthorizationDecreaseChangePeriodUpdateTime + +```solidity +function getRemainingAuthorizationDecreaseChangePeriodUpdateTime() external view returns (uint256) +``` + +Get the time remaining until the authorization decrease change +period can be updated. + +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +| [0] | uint256 | Remaining time in seconds. | + +### getRemainingMaliciousDkgResultSlashingAmountUpdateTime + +```solidity +function getRemainingMaliciousDkgResultSlashingAmountUpdateTime() external view returns (uint256) +``` + +Get the time remaining until the malicious DKG result +slashing amount can be updated. + +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +| [0] | uint256 | Remaining time in seconds. | + +### getRemainingMaliciousDkgResultNotificationRewardMultiplierUpdateTime + +```solidity +function getRemainingMaliciousDkgResultNotificationRewardMultiplierUpdateTime() external view returns (uint256) +``` + +Get the time remaining until the DKG malicious result +notification reward multiplier duration can be updated. + +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +| [0] | uint256 | Remaining time in seconds. | + +### getRemainingSortitionPoolRewardsBanDurationUpdateTime + +```solidity +function getRemainingSortitionPoolRewardsBanDurationUpdateTime() external view returns (uint256) +``` + +Get the time remaining until the sortition pool rewards ban +duration can be updated. + +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +| [0] | uint256 | Remaining time in seconds. | + +### getRemainingDkgSeedTimeoutUpdateTime + +```solidity +function getRemainingDkgSeedTimeoutUpdateTime() external view returns (uint256) +``` + +Get the time remaining until the DKG seed timeout can be updated. + +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +| [0] | uint256 | Remaining time in seconds. | + +### getRemainingDkgResultChallengePeriodLengthUpdateTime + +```solidity +function getRemainingDkgResultChallengePeriodLengthUpdateTime() external view returns (uint256) +``` + +Get the time remaining until the DKG result challenge period +length can be updated. + +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +| [0] | uint256 | Remaining time in seconds. | + +### getRemainingDkgResultChallengeExtraGasUpdateTime + +```solidity +function getRemainingDkgResultChallengeExtraGasUpdateTime() external view returns (uint256) +``` + +### getRemainingDkgResultSubmissionTimeoutUpdateTime + +```solidity +function getRemainingDkgResultSubmissionTimeoutUpdateTime() external view returns (uint256) +``` + +Get the time remaining until the DKG result submission timeout +can be updated. + +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +| [0] | uint256 | Remaining time in seconds. | + +### getRemainingWalletOwnerUpdateTime + +```solidity +function getRemainingWalletOwnerUpdateTime() external view returns (uint256) +``` + +Get the time remaining until the wallet owner can be updated. + +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +| [0] | uint256 | Remaining time in seconds. | + +### getRemainingDkgSubmitterPrecedencePeriodLengthUpdateTime + +```solidity +function getRemainingDkgSubmitterPrecedencePeriodLengthUpdateTime() external view returns (uint256) +``` + +Get the time remaining until the wallet owner can be updated. + +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +| [0] | uint256 | Remaining time in seconds. | + +### getRemainingDkgResultSubmissionGasUpdateTime + +```solidity +function getRemainingDkgResultSubmissionGasUpdateTime() external view returns (uint256) +``` + +Get the time remaining until the dkg result submission gas can +be updated. + +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +| [0] | uint256 | Remaining time in seconds. | + +### getRemainingDkgResultApprovalGasOffsetUpdateTime + +```solidity +function getRemainingDkgResultApprovalGasOffsetUpdateTime() external view returns (uint256) +``` + +Get the time remaining until the dkg result approval gas offset +can be updated. + +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +| [0] | uint256 | Remaining time in seconds. | + +### getRemainingNotifyOperatorInactivityGasOffsetUpdateTime + +```solidity +function getRemainingNotifyOperatorInactivityGasOffsetUpdateTime() external view returns (uint256) +``` + +Get the time remaining until the operator inactivity gas offset +can be updated. + +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +| [0] | uint256 | Remaining time in seconds. | + +### getRemainingNotifySeedTimeoutGasOffsetUpdateTime + +```solidity +function getRemainingNotifySeedTimeoutGasOffsetUpdateTime() external view returns (uint256) +``` + +Get the time remaining until the seed for DKG delivery timeout +gas offset can be updated. + +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +| [0] | uint256 | Remaining time in seconds. | + +### getRemainingNotifyDkgTimeoutNegativeGasOffsetUpdateTime + +```solidity +function getRemainingNotifyDkgTimeoutNegativeGasOffsetUpdateTime() external view returns (uint256) +``` + +Get the time remaining until the DKG timeout negative gas offset +can be updated. + +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +| [0] | uint256 | Remaining time in seconds. | + +### getRemainingReimbursementPoolUpdateTime + +```solidity +function getRemainingReimbursementPoolUpdateTime() external view returns (uint256) +``` + +Get the time remaining until reimbursement pool can be updated. + +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +| [0] | uint256 | Remaining time in seconds. | + +### getRemainingChangeTime + +```solidity +function getRemainingChangeTime(uint256 changeTimestamp) internal view returns (uint256) +``` + +Gets the time remaining until the governable parameter update +can be committed. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| changeTimestamp | uint256 | Timestamp indicating the beginning of the change. | + +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +| [0] | uint256 | Remaining time in seconds. | + diff --git a/docs/app-development/tbtc-v2/ecdsa-api/generated-docs/api/IWalletOwner.md b/docs/app-development/tbtc-v2/ecdsa-api/generated-docs/api/IWalletOwner.md new file mode 100644 index 0000000..008b68e --- /dev/null +++ b/docs/app-development/tbtc-v2/ecdsa-api/generated-docs/api/IWalletOwner.md @@ -0,0 +1,41 @@ +# Solidity API + +## 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. | + diff --git a/docs/app-development/tbtc-v2/ecdsa-api/generated-docs/api/IWalletRegistry.md b/docs/app-development/tbtc-v2/ecdsa-api/generated-docs/api/IWalletRegistry.md new file mode 100644 index 0000000..3db619e --- /dev/null +++ b/docs/app-development/tbtc-v2/ecdsa-api/generated-docs/api/IWalletRegistry.md @@ -0,0 +1,128 @@ +# Solidity API + +## 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. | + diff --git a/docs/app-development/tbtc-v2/ecdsa-api/generated-docs/index.md b/docs/app-development/tbtc-v2/ecdsa-api/generated-docs/index.md deleted file mode 100644 index b1bcea2..0000000 --- a/docs/app-development/tbtc-v2/ecdsa-api/generated-docs/index.md +++ /dev/null @@ -1,3845 +0,0 @@ -# Solidity API -## Table Of Contents - - - -- [EcdsaDkgValidator](#ecdsadkgvalidator) -- [WalletRegistry](#walletregistry) -- [WalletRegistryGovernance](#walletregistrygovernance) -- [IWalletOwner](#iwalletowner) -- [IWalletRegistry](#iwalletregistry) -- [EcdsaAuthorization](#ecdsaauthorization) -- [EcdsaDkg](#ecdsadkg) -- [EcdsaInactivity](#ecdsainactivity) -- [Wallets](#wallets) - - - -## 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. | - -## 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 RewardParametersUpdated(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:\n` 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 | -| ---- | ---- | ----------- | -| 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. | - -### isDkgResultValid - -```solidity -function isDkgResultValid(struct EcdsaDkg.Result result) external view returns (bool, string) -``` - -Checks if DKG result is valid for the current DKG. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| 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 | | - -### 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. | - -### hasSeedTimedOut - -```solidity -function hasSeedTimedOut() external view returns (bool) -``` - -Checks if awaiting seed timed out. - -#### Return Values - -| Name | Type | Description | -| ---- | ---- | ----------- | -| [0] | bool | True if awaiting seed timed out, false otherwise. | - -### hasDkgTimedOut - -```solidity -function hasDkgTimedOut() external view returns (bool) -``` - -Checks if DKG timed out. The DKG timeout period includes time required -for off-chain protocol execution and time for the result publication -for all group members. After this time result cannot be submitted -and DKG can be notified about the timeout. - -#### Return Values - -| Name | Type | Description | -| ---- | ---- | ----------- | -| [0] | bool | True if DKG timed out, false otherwise. | - -### getWallet - -```solidity -function getWallet(bytes32 walletID) external view returns (struct Wallets.Wallet) -``` - -### 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. | - -### isWalletRegistered - -```solidity -function isWalletRegistered(bytes32 walletID) external view returns (bool) -``` - -Checks if a wallet with the given ID is registered. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| walletID | bytes32 | Wallet's ID. | - -#### Return Values - -| Name | Type | Description | -| ---- | ---- | ----------- | -| [0] | bool | True if wallet is registered, false otherwise. | - -### minimumAuthorization - -```solidity -function minimumAuthorization() external view returns (uint96) -``` - -The minimum authorization amount required so that operator can -participate in ECDSA Wallet operations. - -### eligibleStake - -```solidity -function eligibleStake(address stakingProvider) external view returns (uint96) -``` - -Returns the current value of the staking provider's eligible -stake. Eligible stake is defined as the currently authorized -stake minus the pending authorization decrease. Eligible stake -is what is used for operator's weight in the sortition pool. -If the authorized stake minus the pending authorization decrease -is below the minimum authorization, eligible stake is 0. - -### availableRewards - -```solidity -function availableRewards(address stakingProvider) external view returns (uint96) -``` - -Returns the amount of rewards available for withdrawal for the -given staking provider. Reverts if staking provider has not -registered the operator address. - -### pendingAuthorizationDecrease - -```solidity -function pendingAuthorizationDecrease(address stakingProvider) external view returns (uint96) -``` - -Returns the amount of stake that is pending authorization -decrease for the given staking provider. If no authorization -decrease has been requested, returns zero. - -### remainingAuthorizationDecreaseDelay - -```solidity -function remainingAuthorizationDecreaseDelay(address stakingProvider) external view returns (uint64) -``` - -Returns the remaining time in seconds that needs to pass before -the requested authorization decrease can be approved. -If the sortition pool state was not updated yet by the operator -after requesting the authorization decrease, returns -`type(uint64).max`. - -### stakingProviderToOperator - -```solidity -function stakingProviderToOperator(address stakingProvider) public view returns (address) -``` - -Returns operator registered for the given staking provider. - -### operatorToStakingProvider - -```solidity -function operatorToStakingProvider(address operator) public view returns (address) -``` - -Returns staking provider of the given operator. - -### isOperatorUpToDate - -```solidity -function isOperatorUpToDate(address operator) external view returns (bool) -``` - -Checks if the operator's authorized stake is in sync with -operator's weight in the sortition pool. -If the operator is not in the sortition pool and their -authorized stake is non-zero, function returns false. - -### isOperatorInPool - -```solidity -function isOperatorInPool(address operator) external view returns (bool) -``` - -Returns true if the given operator is in the sortition pool. -Otherwise, returns false. - -### selectGroup - -```solidity -function selectGroup() external view returns (uint32[]) -``` - -Selects a new group of operators. Can only be called when DKG -is in progress and the pool is locked. -At least one operator has to be registered in the pool, -otherwise the function fails reverting the transaction. - -#### Return Values - -| Name | Type | Description | -| ---- | ---- | ----------- | -| [0] | uint32[] | IDs of selected group members. | - -### dkgParameters - -```solidity -function dkgParameters() external view returns (struct EcdsaDkg.Parameters) -``` - -Retrieves dkg parameters that were set in DKG library. - -### authorizationParameters - -```solidity -function authorizationParameters() external view returns (uint96 minimumAuthorization, uint64 authorizationDecreaseDelay, uint64 authorizationDecreaseChangePeriod) -``` - -Returns authorization-related parameters. - -The minimum authorization is also returned by `minimumAuthorization()` -function, as a requirement of `IApplication` interface. - -#### Return Values - -| Name | Type | Description | -| ---- | ---- | ----------- | -| minimumAuthorization | uint96 | The minimum authorization amount required so that operator can participate in the random beacon. This amount is required to execute slashing for providing a malicious DKG result or when a relay entry times out. | -| authorizationDecreaseDelay | uint64 | Delay in seconds that needs to pass between the time authorization decrease is requested and the time that request gets approved. Protects against free-riders earning rewards and not being active in the network. | -| authorizationDecreaseChangePeriod | uint64 | Authorization decrease change period in seconds. It is the time, before authorization decrease delay end, during which the pending authorization decrease request can be overwritten. If set to 0, pending authorization decrease request can not be overwritten until the entire `authorizationDecreaseDelay` ends. If set to value equal `authorizationDecreaseDelay`, request can always be overwritten. | - -### rewardParameters - -```solidity -function rewardParameters() external view returns (uint256 maliciousDkgResultNotificationRewardMultiplier, uint256 sortitionPoolRewardsBanDuration) -``` - -Retrieves reward-related parameters. - -#### Return Values - -| Name | Type | Description | -| ---- | ---- | ----------- | -| maliciousDkgResultNotificationRewardMultiplier | uint256 | 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 | uint256 | Duration of the sortition pool rewards ban imposed on operators who missed their turn for DKG result submission or who failed a heartbeat. | - -### slashingParameters - -```solidity -function slashingParameters() external view returns (uint96 maliciousDkgResultSlashingAmount) -``` - -Retrieves slashing-related parameters. - -#### Return Values - -| Name | Type | Description | -| ---- | ---- | ----------- | -| maliciousDkgResultSlashingAmount | uint96 | 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`. | - -### gasParameters - -```solidity -function gasParameters() external view returns (uint256 dkgResultSubmissionGas, uint256 dkgResultApprovalGasOffset, uint256 notifyOperatorInactivityGasOffset, uint256 notifySeedTimeoutGasOffset, uint256 notifyDkgTimeoutNegativeGasOffset) -``` - -Retrieves gas-related parameters. - -#### Return Values - -| Name | Type | Description | -| ---- | ---- | ----------- | -| dkgResultSubmissionGas | uint256 | 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 | uint256 | 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 | uint256 | 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 | uint256 | 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 | uint256 | 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. | - -## WalletRegistryGovernance - -Owns the `WalletRegistry` contract and is responsible for updating -its governable parameters in respect to the governance delay. - -### newGovernanceDelay - -```solidity -uint256 newGovernanceDelay -``` - -### governanceDelayChangeInitiated - -```solidity -uint256 governanceDelayChangeInitiated -``` - -### newWalletRegistryGovernance - -```solidity -address newWalletRegistryGovernance -``` - -### walletRegistryGovernanceTransferInitiated - -```solidity -uint256 walletRegistryGovernanceTransferInitiated -``` - -### newWalletOwner - -```solidity -address newWalletOwner -``` - -### walletOwnerChangeInitiated - -```solidity -uint256 walletOwnerChangeInitiated -``` - -### newMinimumAuthorization - -```solidity -uint96 newMinimumAuthorization -``` - -### minimumAuthorizationChangeInitiated - -```solidity -uint256 minimumAuthorizationChangeInitiated -``` - -### newAuthorizationDecreaseDelay - -```solidity -uint64 newAuthorizationDecreaseDelay -``` - -### authorizationDecreaseDelayChangeInitiated - -```solidity -uint256 authorizationDecreaseDelayChangeInitiated -``` - -### newAuthorizationDecreaseChangePeriod - -```solidity -uint64 newAuthorizationDecreaseChangePeriod -``` - -### authorizationDecreaseChangePeriodChangeInitiated - -```solidity -uint256 authorizationDecreaseChangePeriodChangeInitiated -``` - -### newMaliciousDkgResultSlashingAmount - -```solidity -uint96 newMaliciousDkgResultSlashingAmount -``` - -### maliciousDkgResultSlashingAmountChangeInitiated - -```solidity -uint256 maliciousDkgResultSlashingAmountChangeInitiated -``` - -### newMaliciousDkgResultNotificationRewardMultiplier - -```solidity -uint256 newMaliciousDkgResultNotificationRewardMultiplier -``` - -### maliciousDkgResultNotificationRewardMultiplierChangeInitiated - -```solidity -uint256 maliciousDkgResultNotificationRewardMultiplierChangeInitiated -``` - -### newSortitionPoolRewardsBanDuration - -```solidity -uint256 newSortitionPoolRewardsBanDuration -``` - -### sortitionPoolRewardsBanDurationChangeInitiated - -```solidity -uint256 sortitionPoolRewardsBanDurationChangeInitiated -``` - -### newDkgSeedTimeout - -```solidity -uint256 newDkgSeedTimeout -``` - -### dkgSeedTimeoutChangeInitiated - -```solidity -uint256 dkgSeedTimeoutChangeInitiated -``` - -### newDkgResultChallengePeriodLength - -```solidity -uint256 newDkgResultChallengePeriodLength -``` - -### dkgResultChallengePeriodLengthChangeInitiated - -```solidity -uint256 dkgResultChallengePeriodLengthChangeInitiated -``` - -### newDkgResultChallengeExtraGas - -```solidity -uint256 newDkgResultChallengeExtraGas -``` - -### dkgResultChallengeExtraGasChangeInitiated - -```solidity -uint256 dkgResultChallengeExtraGasChangeInitiated -``` - -### newDkgResultSubmissionTimeout - -```solidity -uint256 newDkgResultSubmissionTimeout -``` - -### dkgResultSubmissionTimeoutChangeInitiated - -```solidity -uint256 dkgResultSubmissionTimeoutChangeInitiated -``` - -### newSubmitterPrecedencePeriodLength - -```solidity -uint256 newSubmitterPrecedencePeriodLength -``` - -### dkgSubmitterPrecedencePeriodLengthChangeInitiated - -```solidity -uint256 dkgSubmitterPrecedencePeriodLengthChangeInitiated -``` - -### newDkgResultSubmissionGas - -```solidity -uint256 newDkgResultSubmissionGas -``` - -### dkgResultSubmissionGasChangeInitiated - -```solidity -uint256 dkgResultSubmissionGasChangeInitiated -``` - -### newDkgResultApprovalGasOffset - -```solidity -uint256 newDkgResultApprovalGasOffset -``` - -### dkgResultApprovalGasOffsetChangeInitiated - -```solidity -uint256 dkgResultApprovalGasOffsetChangeInitiated -``` - -### newNotifyOperatorInactivityGasOffset - -```solidity -uint256 newNotifyOperatorInactivityGasOffset -``` - -### notifyOperatorInactivityGasOffsetChangeInitiated - -```solidity -uint256 notifyOperatorInactivityGasOffsetChangeInitiated -``` - -### newNotifySeedTimeoutGasOffset - -```solidity -uint256 newNotifySeedTimeoutGasOffset -``` - -### notifySeedTimeoutGasOffsetChangeInitiated - -```solidity -uint256 notifySeedTimeoutGasOffsetChangeInitiated -``` - -### newNotifyDkgTimeoutNegativeGasOffset - -```solidity -uint256 newNotifyDkgTimeoutNegativeGasOffset -``` - -### notifyDkgTimeoutNegativeGasOffsetChangeInitiated - -```solidity -uint256 notifyDkgTimeoutNegativeGasOffsetChangeInitiated -``` - -### newReimbursementPool - -```solidity -address payable newReimbursementPool -``` - -### reimbursementPoolChangeInitiated - -```solidity -uint256 reimbursementPoolChangeInitiated -``` - -### walletRegistry - -```solidity -contract WalletRegistry walletRegistry -``` - -### governanceDelay - -```solidity -uint256 governanceDelay -``` - -### GovernanceDelayUpdateStarted - -```solidity -event GovernanceDelayUpdateStarted(uint256 governanceDelay, uint256 timestamp) -``` - -### GovernanceDelayUpdated - -```solidity -event GovernanceDelayUpdated(uint256 governanceDelay) -``` - -### WalletRegistryGovernanceTransferStarted - -```solidity -event WalletRegistryGovernanceTransferStarted(address newWalletRegistryGovernance, uint256 timestamp) -``` - -### WalletRegistryGovernanceTransferred - -```solidity -event WalletRegistryGovernanceTransferred(address newWalletRegistryGovernance) -``` - -### WalletOwnerUpdateStarted - -```solidity -event WalletOwnerUpdateStarted(address walletOwner, uint256 timestamp) -``` - -### WalletOwnerUpdated - -```solidity -event WalletOwnerUpdated(address walletOwner) -``` - -### MinimumAuthorizationUpdateStarted - -```solidity -event MinimumAuthorizationUpdateStarted(uint96 minimumAuthorization, uint256 timestamp) -``` - -### MinimumAuthorizationUpdated - -```solidity -event MinimumAuthorizationUpdated(uint96 minimumAuthorization) -``` - -### AuthorizationDecreaseDelayUpdateStarted - -```solidity -event AuthorizationDecreaseDelayUpdateStarted(uint64 authorizationDecreaseDelay, uint256 timestamp) -``` - -### AuthorizationDecreaseDelayUpdated - -```solidity -event AuthorizationDecreaseDelayUpdated(uint64 authorizationDecreaseDelay) -``` - -### AuthorizationDecreaseChangePeriodUpdateStarted - -```solidity -event AuthorizationDecreaseChangePeriodUpdateStarted(uint64 authorizationDecreaseChangePeriod, uint256 timestamp) -``` - -### AuthorizationDecreaseChangePeriodUpdated - -```solidity -event AuthorizationDecreaseChangePeriodUpdated(uint64 authorizationDecreaseChangePeriod) -``` - -### MaliciousDkgResultSlashingAmountUpdateStarted - -```solidity -event MaliciousDkgResultSlashingAmountUpdateStarted(uint256 maliciousDkgResultSlashingAmount, uint256 timestamp) -``` - -### MaliciousDkgResultSlashingAmountUpdated - -```solidity -event MaliciousDkgResultSlashingAmountUpdated(uint256 maliciousDkgResultSlashingAmount) -``` - -### MaliciousDkgResultNotificationRewardMultiplierUpdateStarted - -```solidity -event MaliciousDkgResultNotificationRewardMultiplierUpdateStarted(uint256 maliciousDkgResultNotificationRewardMultiplier, uint256 timestamp) -``` - -### MaliciousDkgResultNotificationRewardMultiplierUpdated - -```solidity -event MaliciousDkgResultNotificationRewardMultiplierUpdated(uint256 maliciousDkgResultNotificationRewardMultiplier) -``` - -### SortitionPoolRewardsBanDurationUpdateStarted - -```solidity -event SortitionPoolRewardsBanDurationUpdateStarted(uint256 sortitionPoolRewardsBanDuration, uint256 timestamp) -``` - -### SortitionPoolRewardsBanDurationUpdated - -```solidity -event SortitionPoolRewardsBanDurationUpdated(uint256 sortitionPoolRewardsBanDuration) -``` - -### DkgSeedTimeoutUpdateStarted - -```solidity -event DkgSeedTimeoutUpdateStarted(uint256 dkgSeedTimeout, uint256 timestamp) -``` - -### DkgSeedTimeoutUpdated - -```solidity -event DkgSeedTimeoutUpdated(uint256 dkgSeedTimeout) -``` - -### DkgResultChallengePeriodLengthUpdateStarted - -```solidity -event DkgResultChallengePeriodLengthUpdateStarted(uint256 dkgResultChallengePeriodLength, uint256 timestamp) -``` - -### DkgResultChallengePeriodLengthUpdated - -```solidity -event DkgResultChallengePeriodLengthUpdated(uint256 dkgResultChallengePeriodLength) -``` - -### DkgResultChallengeExtraGasUpdateStarted - -```solidity -event DkgResultChallengeExtraGasUpdateStarted(uint256 dkgResultChallengeExtraGas, uint256 timestamp) -``` - -### DkgResultChallengeExtraGasUpdated - -```solidity -event DkgResultChallengeExtraGasUpdated(uint256 dkgResultChallengeExtraGas) -``` - -### DkgResultSubmissionTimeoutUpdateStarted - -```solidity -event DkgResultSubmissionTimeoutUpdateStarted(uint256 dkgResultSubmissionTimeout, uint256 timestamp) -``` - -### DkgResultSubmissionTimeoutUpdated - -```solidity -event DkgResultSubmissionTimeoutUpdated(uint256 dkgResultSubmissionTimeout) -``` - -### DkgSubmitterPrecedencePeriodLengthUpdateStarted - -```solidity -event DkgSubmitterPrecedencePeriodLengthUpdateStarted(uint256 submitterPrecedencePeriodLength, uint256 timestamp) -``` - -### DkgSubmitterPrecedencePeriodLengthUpdated - -```solidity -event DkgSubmitterPrecedencePeriodLengthUpdated(uint256 submitterPrecedencePeriodLength) -``` - -### DkgResultSubmissionGasUpdateStarted - -```solidity -event DkgResultSubmissionGasUpdateStarted(uint256 dkgResultSubmissionGas, uint256 timestamp) -``` - -### DkgResultSubmissionGasUpdated - -```solidity -event DkgResultSubmissionGasUpdated(uint256 dkgResultSubmissionGas) -``` - -### DkgResultApprovalGasOffsetUpdateStarted - -```solidity -event DkgResultApprovalGasOffsetUpdateStarted(uint256 dkgResultApprovalGasOffset, uint256 timestamp) -``` - -### DkgResultApprovalGasOffsetUpdated - -```solidity -event DkgResultApprovalGasOffsetUpdated(uint256 dkgResultApprovalGasOffset) -``` - -### NotifyOperatorInactivityGasOffsetUpdateStarted - -```solidity -event NotifyOperatorInactivityGasOffsetUpdateStarted(uint256 notifyOperatorInactivityGasOffset, uint256 timestamp) -``` - -### NotifyOperatorInactivityGasOffsetUpdated - -```solidity -event NotifyOperatorInactivityGasOffsetUpdated(uint256 notifyOperatorInactivityGasOffset) -``` - -### NotifySeedTimeoutGasOffsetUpdateStarted - -```solidity -event NotifySeedTimeoutGasOffsetUpdateStarted(uint256 notifySeedTimeoutGasOffset, uint256 timestamp) -``` - -### NotifySeedTimeoutGasOffsetUpdated - -```solidity -event NotifySeedTimeoutGasOffsetUpdated(uint256 notifySeedTimeoutGasOffset) -``` - -### NotifyDkgTimeoutNegativeGasOffsetUpdateStarted - -```solidity -event NotifyDkgTimeoutNegativeGasOffsetUpdateStarted(uint256 notifyDkgTimeoutNegativeGasOffset, uint256 timestamp) -``` - -### NotifyDkgTimeoutNegativeGasOffsetUpdated - -```solidity -event NotifyDkgTimeoutNegativeGasOffsetUpdated(uint256 notifyDkgTimeoutNegativeGasOffset) -``` - -### ReimbursementPoolUpdateStarted - -```solidity -event ReimbursementPoolUpdateStarted(address reimbursementPool, uint256 timestamp) -``` - -### ReimbursementPoolUpdated - -```solidity -event ReimbursementPoolUpdated(address reimbursementPool) -``` - -### onlyAfterGovernanceDelay - -```solidity -modifier onlyAfterGovernanceDelay(uint256 changeInitiatedTimestamp) -``` - -Reverts if called before the governance delay elapses. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| changeInitiatedTimestamp | uint256 | Timestamp indicating the beginning of the change. | - -### constructor - -```solidity -constructor(contract WalletRegistry _walletRegistry, uint256 _governanceDelay) public -``` - -### upgradeRandomBeacon - -```solidity -function upgradeRandomBeacon(address _newRandomBeacon) external -``` - -Upgrades the random beacon. - -Can be called only by the contract owner. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| _newRandomBeacon | address | New random beacon address | - -### initializeWalletOwner - -```solidity -function initializeWalletOwner(address _walletOwner) external -``` - -Initializes the Wallet Owner's address. - -Can be called only by the contract owner. It can be called only if -walletOwner has not been set before. It doesn't enforce a governance -delay for the initial update. Any subsequent updates should be performed -with beginWalletOwnerUpdate/finalizeWalletOwnerUpdate with respect -of a governance delay. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| _walletOwner | address | The Wallet Owner's address | - -### beginGovernanceDelayUpdate - -```solidity -function beginGovernanceDelayUpdate(uint256 _newGovernanceDelay) external -``` - -Begins the governance delay update process. - -Can be called only by the contract owner. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| _newGovernanceDelay | uint256 | New governance delay | - -### finalizeGovernanceDelayUpdate - -```solidity -function finalizeGovernanceDelayUpdate() external -``` - -Finalizes the governance delay update process. - -Can be called only by the contract owner, after the governance -delay elapses. - -### beginWalletRegistryGovernanceTransfer - -```solidity -function beginWalletRegistryGovernanceTransfer(address _newWalletRegistryGovernance) external -``` - -Begins the wallet registry governance transfer process. - -Can be called only by the contract owner. - -### finalizeWalletRegistryGovernanceTransfer - -```solidity -function finalizeWalletRegistryGovernanceTransfer() external -``` - -Finalizes the wallet registry governance transfer process. - -Can be called only by the contract owner, after the governance -delay elapses. - -### beginWalletOwnerUpdate - -```solidity -function beginWalletOwnerUpdate(address _newWalletOwner) external -``` - -Begins the wallet owner update process. - -Can be called only by the contract owner. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| _newWalletOwner | address | New wallet owner address | - -### finalizeWalletOwnerUpdate - -```solidity -function finalizeWalletOwnerUpdate() external -``` - -Finalizes the wallet owner update process. - -Can be called only by the contract owner, after the governance -delay elapses. - -### beginMinimumAuthorizationUpdate - -```solidity -function beginMinimumAuthorizationUpdate(uint96 _newMinimumAuthorization) external -``` - -Begins the minimum authorization amount update process. - -Can be called only by the contract owner. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| _newMinimumAuthorization | uint96 | New minimum authorization amount. | - -### finalizeMinimumAuthorizationUpdate - -```solidity -function finalizeMinimumAuthorizationUpdate() external -``` - -Finalizes the minimum authorization amount update process. - -Can be called only by the contract owner, after the governance -delay elapses. - -### beginAuthorizationDecreaseDelayUpdate - -```solidity -function beginAuthorizationDecreaseDelayUpdate(uint64 _newAuthorizationDecreaseDelay) external -``` - -Begins the authorization decrease delay update process. - -Can be called only by the contract owner. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| _newAuthorizationDecreaseDelay | uint64 | New authorization decrease delay | - -### finalizeAuthorizationDecreaseDelayUpdate - -```solidity -function finalizeAuthorizationDecreaseDelayUpdate() external -``` - -Finalizes the authorization decrease delay update process. - -Can be called only by the contract owner, after the governance -delay elapses. - -### beginAuthorizationDecreaseChangePeriodUpdate - -```solidity -function beginAuthorizationDecreaseChangePeriodUpdate(uint64 _newAuthorizationDecreaseChangePeriod) external -``` - -Begins the authorization decrease change period update process. - -Can be called only by the contract owner. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| _newAuthorizationDecreaseChangePeriod | uint64 | New authorization decrease change period | - -### finalizeAuthorizationDecreaseChangePeriodUpdate - -```solidity -function finalizeAuthorizationDecreaseChangePeriodUpdate() external -``` - -Finalizes the authorization decrease change period update process. - -Can be called only by the contract owner, after the governance -delay elapses. - -### beginMaliciousDkgResultSlashingAmountUpdate - -```solidity -function beginMaliciousDkgResultSlashingAmountUpdate(uint96 _newMaliciousDkgResultSlashingAmount) external -``` - -Begins the malicious DKG result slashing amount update process. - -Can be called only by the contract owner. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| _newMaliciousDkgResultSlashingAmount | uint96 | New malicious DKG result slashing amount | - -### finalizeMaliciousDkgResultSlashingAmountUpdate - -```solidity -function finalizeMaliciousDkgResultSlashingAmountUpdate() external -``` - -Finalizes the malicious DKG result slashing amount update -process. - -Can be called only by the contract owner, after the governance -delay elapses. - -### beginMaliciousDkgResultNotificationRewardMultiplierUpdate - -```solidity -function beginMaliciousDkgResultNotificationRewardMultiplierUpdate(uint256 _newMaliciousDkgResultNotificationRewardMultiplier) external -``` - -Begins the DKG malicious result notification reward multiplier -update process. - -Can be called only by the contract owner. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| _newMaliciousDkgResultNotificationRewardMultiplier | uint256 | New DKG malicious result notification reward multiplier. | - -### finalizeMaliciousDkgResultNotificationRewardMultiplierUpdate - -```solidity -function finalizeMaliciousDkgResultNotificationRewardMultiplierUpdate() external -``` - -Finalizes the DKG malicious result notification reward -multiplier update process. - -Can be called only by the contract owner, after the governance -delay elapses. - -### beginDkgResultSubmissionGasUpdate - -```solidity -function beginDkgResultSubmissionGasUpdate(uint256 _newDkgResultSubmissionGas) external -``` - -Begins the dkg result submission gas update process. - -Can be called only by the contract owner. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| _newDkgResultSubmissionGas | uint256 | New DKG result submission gas. | - -### finalizeDkgResultSubmissionGasUpdate - -```solidity -function finalizeDkgResultSubmissionGasUpdate() external -``` - -Finalizes the dkg result submission gas update process. - -Can be called only by the contract owner, after the governance -delay elapses. - -### beginDkgResultApprovalGasOffsetUpdate - -```solidity -function beginDkgResultApprovalGasOffsetUpdate(uint256 _newDkgResultApprovalGasOffset) external -``` - -Begins the dkg approval gas offset update process. - -Can be called only by the contract owner. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| _newDkgResultApprovalGasOffset | uint256 | New DKG result approval gas. | - -### finalizeDkgResultApprovalGasOffsetUpdate - -```solidity -function finalizeDkgResultApprovalGasOffsetUpdate() external -``` - -Finalizes the dkg result approval gas offset update process. - -Can be called only by the contract owner, after the governance -delay elapses. - -### beginNotifyOperatorInactivityGasOffsetUpdate - -```solidity -function beginNotifyOperatorInactivityGasOffsetUpdate(uint256 _newNotifyOperatorInactivityGasOffset) external -``` - -Begins the notify operator inactivity gas offset update process. - -Can be called only by the contract owner. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| _newNotifyOperatorInactivityGasOffset | uint256 | New operator inactivity notification gas offset | - -### finalizeNotifyOperatorInactivityGasOffsetUpdate - -```solidity -function finalizeNotifyOperatorInactivityGasOffsetUpdate() external -``` - -Finalizes the notify operator inactivity gas offset update process. - -Can be called only by the contract owner, after the governance -delay elapses. - -### beginNotifySeedTimeoutGasOffsetUpdate - -```solidity -function beginNotifySeedTimeoutGasOffsetUpdate(uint256 _newNotifySeedTimeoutGasOffset) external -``` - -Begins the notify seed for DKG delivery timeout gas offset update -process. - -Can be called only by the contract owner. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| _newNotifySeedTimeoutGasOffset | uint256 | New seed for DKG delivery timeout notification gas offset | - -### finalizeNotifySeedTimeoutGasOffsetUpdate - -```solidity -function finalizeNotifySeedTimeoutGasOffsetUpdate() external -``` - -Finalizes the notify seed for DKG delivery timeout gas offset -update process. - -Can be called only by the contract owner, after the governance -delay elapses. - -### beginNotifyDkgTimeoutNegativeGasOffsetUpdate - -```solidity -function beginNotifyDkgTimeoutNegativeGasOffsetUpdate(uint256 _newNotifyDkgTimeoutNegativeGasOffset) external -``` - -Begins the notify DKG timeout negative gas offset update process. - -Can be called only by the contract owner. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| _newNotifyDkgTimeoutNegativeGasOffset | uint256 | New DKG timeout negative gas notification gas offset | - -### finalizeNotifyDkgTimeoutNegativeGasOffsetUpdate - -```solidity -function finalizeNotifyDkgTimeoutNegativeGasOffsetUpdate() external -``` - -Finalizes the notify DKG timeout negative gas offset update process. - -Can be called only by the contract owner, after the governance -delay elapses. - -### beginReimbursementPoolUpdate - -```solidity -function beginReimbursementPoolUpdate(address payable _newReimbursementPool) external -``` - -Begins the reimbursement pool update process. - -Can be called only by the contract owner. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| _newReimbursementPool | address payable | New reimbursement pool. | - -### finalizeReimbursementPoolUpdate - -```solidity -function finalizeReimbursementPoolUpdate() external -``` - -Finalizes the reimbursement pool update process. - -Can be called only by the contract owner, after the governance -delay elapses. - -### beginSortitionPoolRewardsBanDurationUpdate - -```solidity -function beginSortitionPoolRewardsBanDurationUpdate(uint256 _newSortitionPoolRewardsBanDuration) external -``` - -Begins the sortition pool rewards ban duration update process. - -Can be called only by the contract owner. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| _newSortitionPoolRewardsBanDuration | uint256 | New sortition pool rewards ban duration. | - -### finalizeSortitionPoolRewardsBanDurationUpdate - -```solidity -function finalizeSortitionPoolRewardsBanDurationUpdate() external -``` - -Finalizes the sortition pool rewards ban duration update process. - -Can be called only by the contract owner, after the governance -delay elapses. - -### beginDkgSeedTimeoutUpdate - -```solidity -function beginDkgSeedTimeoutUpdate(uint256 _newDkgSeedTimeout) external -``` - -Begins the DKG seed timeout update process. - -Can be called only by the contract owner. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| _newDkgSeedTimeout | uint256 | New DKG seed timeout in blocks | - -### finalizeDkgSeedTimeoutUpdate - -```solidity -function finalizeDkgSeedTimeoutUpdate() external -``` - -Finalizes the DKG seed timeout update process. - -Can be called only by the contract owner, after the governance -delay elapses. - -### beginDkgResultChallengePeriodLengthUpdate - -```solidity -function beginDkgResultChallengePeriodLengthUpdate(uint256 _newDkgResultChallengePeriodLength) external -``` - -Begins the DKG result challenge period length update process. - -Can be called only by the contract owner. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| _newDkgResultChallengePeriodLength | uint256 | New DKG result challenge period length in blocks | - -### finalizeDkgResultChallengePeriodLengthUpdate - -```solidity -function finalizeDkgResultChallengePeriodLengthUpdate() external -``` - -Finalizes the DKG result challenge period length update process. - -Can be called only by the contract owner, after the governance -delay elapses. - -### beginDkgResultChallengeExtraGasUpdate - -```solidity -function beginDkgResultChallengeExtraGasUpdate(uint256 _newDkgResultChallengeExtraGas) external -``` - -Begins the DKG result challenge extra gas update process. - -Can be called only by the contract owner. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| _newDkgResultChallengeExtraGas | uint256 | New DKG result challenge extra gas | - -### finalizeDkgResultChallengeExtraGasUpdate - -```solidity -function finalizeDkgResultChallengeExtraGasUpdate() external -``` - -Finalizes the DKG result challenge extra gas update process. - -Can be called only by the contract owner, after the governance -delay elapses. - -### beginDkgResultSubmissionTimeoutUpdate - -```solidity -function beginDkgResultSubmissionTimeoutUpdate(uint256 _newDkgResultSubmissionTimeout) external -``` - -Begins the DKG result submission timeout update -process. - -Can be called only by the contract owner. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| _newDkgResultSubmissionTimeout | uint256 | New DKG result submission timeout in blocks | - -### finalizeDkgResultSubmissionTimeoutUpdate - -```solidity -function finalizeDkgResultSubmissionTimeoutUpdate() external -``` - -Finalizes the DKG result submission timeout update -process. - -Can be called only by the contract owner, after the governance -delay elapses. - -### beginDkgSubmitterPrecedencePeriodLengthUpdate - -```solidity -function beginDkgSubmitterPrecedencePeriodLengthUpdate(uint256 _newSubmitterPrecedencePeriodLength) external -``` - -Begins the DKG submitter precedence period length update -process. - -Can be called only by the contract owner. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| _newSubmitterPrecedencePeriodLength | uint256 | New DKG submitter precedence period length in blocks | - -### finalizeDkgSubmitterPrecedencePeriodLengthUpdate - -```solidity -function finalizeDkgSubmitterPrecedencePeriodLengthUpdate() external -``` - -Finalizes the DKG submitter precedence period length update -process. - -Can be called only by the contract owner, after the governance -delay elapses. - -### 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 owner. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| recipient | address | Recipient of withdrawn rewards. | - -### getRemainingGovernanceDelayUpdateTime - -```solidity -function getRemainingGovernanceDelayUpdateTime() external view returns (uint256) -``` - -Get the time remaining until the governance delay can be updated. - -#### Return Values - -| Name | Type | Description | -| ---- | ---- | ----------- | -| [0] | uint256 | Remaining time in seconds. | - -### getRemainingWalletRegistryGovernanceTransferDelayTime - -```solidity -function getRemainingWalletRegistryGovernanceTransferDelayTime() external view returns (uint256) -``` - -Get the time remaining until the wallet registry governance can -be transferred. - -#### Return Values - -| Name | Type | Description | -| ---- | ---- | ----------- | -| [0] | uint256 | Remaining time in seconds. | - -### getRemainingMimimumAuthorizationUpdateTime - -```solidity -function getRemainingMimimumAuthorizationUpdateTime() external view returns (uint256) -``` - -Get the time remaining until the minimum authorization amount -can be updated. - -#### Return Values - -| Name | Type | Description | -| ---- | ---- | ----------- | -| [0] | uint256 | Remaining time in seconds. | - -### getRemainingAuthorizationDecreaseDelayUpdateTime - -```solidity -function getRemainingAuthorizationDecreaseDelayUpdateTime() external view returns (uint256) -``` - -Get the time remaining until the authorization decrease delay -can be updated. - -#### Return Values - -| Name | Type | Description | -| ---- | ---- | ----------- | -| [0] | uint256 | Remaining time in seconds. | - -### getRemainingAuthorizationDecreaseChangePeriodUpdateTime - -```solidity -function getRemainingAuthorizationDecreaseChangePeriodUpdateTime() external view returns (uint256) -``` - -Get the time remaining until the authorization decrease change -period can be updated. - -#### Return Values - -| Name | Type | Description | -| ---- | ---- | ----------- | -| [0] | uint256 | Remaining time in seconds. | - -### getRemainingMaliciousDkgResultSlashingAmountUpdateTime - -```solidity -function getRemainingMaliciousDkgResultSlashingAmountUpdateTime() external view returns (uint256) -``` - -Get the time remaining until the malicious DKG result -slashing amount can be updated. - -#### Return Values - -| Name | Type | Description | -| ---- | ---- | ----------- | -| [0] | uint256 | Remaining time in seconds. | - -### getRemainingMaliciousDkgResultNotificationRewardMultiplierUpdateTime - -```solidity -function getRemainingMaliciousDkgResultNotificationRewardMultiplierUpdateTime() external view returns (uint256) -``` - -Get the time remaining until the DKG malicious result -notification reward multiplier duration can be updated. - -#### Return Values - -| Name | Type | Description | -| ---- | ---- | ----------- | -| [0] | uint256 | Remaining time in seconds. | - -### getRemainingSortitionPoolRewardsBanDurationUpdateTime - -```solidity -function getRemainingSortitionPoolRewardsBanDurationUpdateTime() external view returns (uint256) -``` - -Get the time remaining until the sortition pool rewards ban -duration can be updated. - -#### Return Values - -| Name | Type | Description | -| ---- | ---- | ----------- | -| [0] | uint256 | Remaining time in seconds. | - -### getRemainingDkgSeedTimeoutUpdateTime - -```solidity -function getRemainingDkgSeedTimeoutUpdateTime() external view returns (uint256) -``` - -Get the time remaining until the DKG seed timeout can be updated. - -#### Return Values - -| Name | Type | Description | -| ---- | ---- | ----------- | -| [0] | uint256 | Remaining time in seconds. | - -### getRemainingDkgResultChallengePeriodLengthUpdateTime - -```solidity -function getRemainingDkgResultChallengePeriodLengthUpdateTime() external view returns (uint256) -``` - -Get the time remaining until the DKG result challenge period -length can be updated. - -#### Return Values - -| Name | Type | Description | -| ---- | ---- | ----------- | -| [0] | uint256 | Remaining time in seconds. | - -### getRemainingDkgResultChallengeExtraGasUpdateTime - -```solidity -function getRemainingDkgResultChallengeExtraGasUpdateTime() external view returns (uint256) -``` - -### getRemainingDkgResultSubmissionTimeoutUpdateTime - -```solidity -function getRemainingDkgResultSubmissionTimeoutUpdateTime() external view returns (uint256) -``` - -Get the time remaining until the DKG result submission timeout -can be updated. - -#### Return Values - -| Name | Type | Description | -| ---- | ---- | ----------- | -| [0] | uint256 | Remaining time in seconds. | - -### getRemainingWalletOwnerUpdateTime - -```solidity -function getRemainingWalletOwnerUpdateTime() external view returns (uint256) -``` - -Get the time remaining until the wallet owner can be updated. - -#### Return Values - -| Name | Type | Description | -| ---- | ---- | ----------- | -| [0] | uint256 | Remaining time in seconds. | - -### getRemainingDkgSubmitterPrecedencePeriodLengthUpdateTime - -```solidity -function getRemainingDkgSubmitterPrecedencePeriodLengthUpdateTime() external view returns (uint256) -``` - -Get the time remaining until the wallet owner can be updated. - -#### Return Values - -| Name | Type | Description | -| ---- | ---- | ----------- | -| [0] | uint256 | Remaining time in seconds. | - -### getRemainingDkgResultSubmissionGasUpdateTime - -```solidity -function getRemainingDkgResultSubmissionGasUpdateTime() external view returns (uint256) -``` - -Get the time remaining until the dkg result submission gas can -be updated. - -#### Return Values - -| Name | Type | Description | -| ---- | ---- | ----------- | -| [0] | uint256 | Remaining time in seconds. | - -### getRemainingDkgResultApprovalGasOffsetUpdateTime - -```solidity -function getRemainingDkgResultApprovalGasOffsetUpdateTime() external view returns (uint256) -``` - -Get the time remaining until the dkg result approval gas offset -can be updated. - -#### Return Values - -| Name | Type | Description | -| ---- | ---- | ----------- | -| [0] | uint256 | Remaining time in seconds. | - -### getRemainingNotifyOperatorInactivityGasOffsetUpdateTime - -```solidity -function getRemainingNotifyOperatorInactivityGasOffsetUpdateTime() external view returns (uint256) -``` - -Get the time remaining until the operator inactivity gas offset -can be updated. - -#### Return Values - -| Name | Type | Description | -| ---- | ---- | ----------- | -| [0] | uint256 | Remaining time in seconds. | - -### getRemainingNotifySeedTimeoutGasOffsetUpdateTime - -```solidity -function getRemainingNotifySeedTimeoutGasOffsetUpdateTime() external view returns (uint256) -``` - -Get the time remaining until the seed for DKG delivery timeout -gas offset can be updated. - -#### Return Values - -| Name | Type | Description | -| ---- | ---- | ----------- | -| [0] | uint256 | Remaining time in seconds. | - -### getRemainingNotifyDkgTimeoutNegativeGasOffsetUpdateTime - -```solidity -function getRemainingNotifyDkgTimeoutNegativeGasOffsetUpdateTime() external view returns (uint256) -``` - -Get the time remaining until the DKG timeout negative gas offset -can be updated. - -#### Return Values - -| Name | Type | Description | -| ---- | ---- | ----------- | -| [0] | uint256 | Remaining time in seconds. | - -### getRemainingReimbursementPoolUpdateTime - -```solidity -function getRemainingReimbursementPoolUpdateTime() external view returns (uint256) -``` - -Get the time remaining until reimbursement pool can be updated. - -#### Return Values - -| Name | Type | Description | -| ---- | ---- | ----------- | -| [0] | uint256 | Remaining time in seconds. | - -### getRemainingChangeTime - -```solidity -function getRemainingChangeTime(uint256 changeTimestamp) internal view returns (uint256) -``` - -Gets the time remaining until the governable parameter update -can be committed. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| changeTimestamp | uint256 | Timestamp indicating the beginning of the change. | - -#### Return Values - -| Name | Type | Description | -| ---- | ---- | ----------- | -| [0] | uint256 | Remaining time in seconds. | - -## 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 - -### 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. | - -## EcdsaAuthorization - -Library managing the state of stake authorizations for ECDSA -operator contract and the presence of operators in the sortition -pool based on the stake authorized for them. - -### Parameters - -```solidity -struct Parameters { - uint96 minimumAuthorization; - uint64 authorizationDecreaseDelay; - uint64 authorizationDecreaseChangePeriod; -} -``` - -### AuthorizationDecrease - -```solidity -struct AuthorizationDecrease { - uint96 decreasingBy; - uint64 decreasingAt; -} -``` - -### Data - -```solidity -struct Data { - struct EcdsaAuthorization.Parameters parameters; - mapping(address => address) stakingProviderToOperator; - mapping(address => address) operatorToStakingProvider; - mapping(address => struct EcdsaAuthorization.AuthorizationDecrease) pendingDecreases; - uint256[46] __gap; -} -``` - -### 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) -``` - -### setMinimumAuthorization - -```solidity -function setMinimumAuthorization(struct EcdsaAuthorization.Data self, uint96 _minimumAuthorization) internal -``` - -Sets the minimum authorization for ECDSA application. Without -at least the minimum authorization, staking provider is not -eligible to join and operate in the network. - -### setAuthorizationDecreaseDelay - -```solidity -function setAuthorizationDecreaseDelay(struct EcdsaAuthorization.Data self, uint64 _authorizationDecreaseDelay) internal -``` - -Sets the authorization decrease delay. It is the time in seconds -that needs to pass between the time authorization decrease is -requested and the time the authorization decrease can be -approved, no matter the authorization decrease amount. - -### setAuthorizationDecreaseChangePeriod - -```solidity -function setAuthorizationDecreaseChangePeriod(struct EcdsaAuthorization.Data self, uint64 _authorizationDecreaseChangePeriod) internal -``` - -Sets the authorization decrease change period. It is the time -period before the authorization decrease delay end, -during which the authorization decrease request can be -overwritten. - -### registerOperator - -```solidity -function registerOperator(struct EcdsaAuthorization.Data self, address operator) internal -``` - -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. - -### authorizationIncreased - -```solidity -function authorizationIncreased(struct EcdsaAuthorization.Data self, address stakingProvider, uint96 fromAmount, uint96 toAmount) internal -``` - -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`. - -Should only be callable by T staking contract. - -### authorizationDecreaseRequested - -```solidity -function authorizationDecreaseRequested(struct EcdsaAuthorization.Data self, address stakingProvider, uint96 fromAmount, uint96 toAmount) internal -``` - -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. - -Reverts if another authorization decrease request is pending for -the staking provider and not enough time passed since the -original request (see `authorizationDecreaseChangePeriod`). - -If the operator is not known (`registerOperator` was not called) -it lets to `approveAuthorizationDecrease` immediately. 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, but only if enough time passed since the original -request. Otherwise, the function reverts. - -Should only be callable by T staking contract. - -### approveAuthorizationDecrease - -```solidity -function approveAuthorizationDecrease(struct EcdsaAuthorization.Data self, contract IStaking tokenStaking, address stakingProvider) internal -``` - -Approves the previously registered authorization decrease -request. Reverts if authorization decrease delay have not passed -yet or if the authorization decrease was not requested for the -given staking provider. - -### involuntaryAuthorizationDecrease - -```solidity -function involuntaryAuthorizationDecrease(struct EcdsaAuthorization.Data self, contract IStaking tokenStaking, contract SortitionPool sortitionPool, address stakingProvider, uint96 fromAmount, uint96 toAmount) internal -``` - -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. - -Should only be callable by T staking contract. - -### joinSortitionPool - -```solidity -function joinSortitionPool(struct EcdsaAuthorization.Data self, contract IStaking tokenStaking, contract SortitionPool sortitionPool) internal -``` - -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(struct EcdsaAuthorization.Data self, contract IStaking tokenStaking, contract SortitionPool sortitionPool, address operator) internal -``` - -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. - -### isOperatorUpToDate - -```solidity -function isOperatorUpToDate(struct EcdsaAuthorization.Data self, contract IStaking tokenStaking, contract SortitionPool sortitionPool, address operator) internal view returns (bool) -``` - -Checks if the operator's authorized stake is in sync with -operator's weight in the sortition pool. -If the operator is not in the sortition pool and their -authorized stake is non-zero, function returns false. - -### eligibleStake - -```solidity -function eligibleStake(struct EcdsaAuthorization.Data self, contract IStaking tokenStaking, address stakingProvider) internal view returns (uint96) -``` - -Returns the current value of the staking provider's eligible -stake. Eligible stake is defined as the currently authorized -stake minus the pending authorization decrease. Eligible stake -is what is used for operator's weight in the pool. If the -authorized stake minus the pending authorization decrease is -below the minimum authorization, eligible stake is 0. - -This function can be exposed to the public in contrast to the -second variant accepting `decreasingBy` as a parameter. - -### eligibleStake - -```solidity -function eligibleStake(struct EcdsaAuthorization.Data self, contract IStaking tokenStaking, address stakingProvider, uint96 decreasingBy) internal view returns (uint96) -``` - -Returns the current value of the staking provider's eligible -stake. Eligible stake is defined as the currently authorized -stake minus the pending authorization decrease. Eligible stake -is what is used for operator's weight in the pool. If the -authorized stake minus the pending authorization decrease is -below the minimum authorization, eligible stake is 0. - -This function is not intended to be exposes to the public. -`decreasingBy` must be fetched from `pendingDecreases` mapping and -it is passed as a parameter to optimize gas usage of functions that -call `eligibleStake` and need to use `AuthorizationDecrease` -fetched from `pendingDecreases` for some additional logic. - -### pendingAuthorizationDecrease - -```solidity -function pendingAuthorizationDecrease(struct EcdsaAuthorization.Data self, address stakingProvider) internal view returns (uint96) -``` - -Returns the amount of stake that is pending authorization -decrease for the given staking provider. If no authorization -decrease has been requested, returns zero. - -### remainingAuthorizationDecreaseDelay - -```solidity -function remainingAuthorizationDecreaseDelay(struct EcdsaAuthorization.Data self, address stakingProvider) internal view returns (uint64) -``` - -Returns the remaining time in seconds that needs to pass before -the requested authorization decrease can be approved. -If the sortition pool state was not updated yet by the operator -after requesting the authorization decrease, returns -`type(uint64).max`. - -## EcdsaDkg - -### Parameters - -```solidity -struct Parameters { - uint256 seedTimeout; - uint256 resultChallengePeriodLength; - uint256 resultChallengeExtraGas; - uint256 resultSubmissionTimeout; - uint256 submitterPrecedencePeriodLength; -} -``` - -### Data - -```solidity -struct Data { - contract SortitionPool sortitionPool; - contract EcdsaDkgValidator dkgValidator; - struct EcdsaDkg.Parameters parameters; - uint256 stateLockBlock; - uint256 startBlock; - uint256 seed; - uint256 resultSubmissionStartBlockOffset; - bytes32 submittedResultHash; - uint256 submittedResultBlock; - uint256[38] __gap; -} -``` - -### Result - -```solidity -struct Result { - uint256 submitterMemberIndex; - bytes groupPubKey; - uint8[] misbehavedMembersIndices; - bytes signatures; - uint256[] signingMembersIndices; - uint32[] members; - bytes32 membersHash; -} -``` - -### State - -```solidity -enum State { - IDLE, - AWAITING_SEED, - AWAITING_RESULT, - CHALLENGE -} -``` - -### groupSize - -```solidity -uint256 groupSize -``` - -Size of a group in ECDSA wallet. - -### 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() -``` - -### init - -```solidity -function init(struct EcdsaDkg.Data self, contract SortitionPool _sortitionPool, contract EcdsaDkgValidator _dkgValidator) internal -``` - -Initializes SortitionPool and EcdsaDkgValidator addresses. -Can be performed only once. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| self | struct EcdsaDkg.Data | | -| _sortitionPool | contract SortitionPool | Sortition Pool reference | -| _dkgValidator | contract EcdsaDkgValidator | EcdsaDkgValidator reference | - -### currentState - -```solidity -function currentState(struct EcdsaDkg.Data self) internal view returns (enum EcdsaDkg.State state) -``` - -Determines the current state of group creation. It doesn't take -timeouts into consideration. The timeouts should be tracked and -notified separately. - -### lockState - -```solidity -function lockState(struct EcdsaDkg.Data self) internal -``` - -Locks the sortition pool and starts awaiting for the -group creation seed. - -### start - -```solidity -function start(struct EcdsaDkg.Data self, uint256 seed) internal -``` - -### submitResult - -```solidity -function submitResult(struct EcdsaDkg.Data self, struct EcdsaDkg.Result result) internal -``` - -Allows to submit a DKG result. The submitted result does not go -through a validation and before it gets accepted, it needs to -wait through the challenge period during which everyone has -a chance to challenge the result as invalid one. Submitter of -the result needs to be in the sortition pool and if the result -gets challenged, the submitter will get slashed. - -### hasSeedTimedOut - -```solidity -function hasSeedTimedOut(struct EcdsaDkg.Data self) internal view returns (bool) -``` - -Checks if awaiting seed timed out. - -#### Return Values - -| Name | Type | Description | -| ---- | ---- | ----------- | -| [0] | bool | True if awaiting seed timed out, false otherwise. | - -### hasDkgTimedOut - -```solidity -function hasDkgTimedOut(struct EcdsaDkg.Data self) internal view returns (bool) -``` - -Checks if DKG timed out. The DKG timeout period includes time required -for off-chain protocol execution and time for the result publication. -After this time a result cannot be submitted and DKG can be notified -about the timeout. DKG period is adjusted by result submission -offset that include blocks that were mined while invalid result -has been registered until it got challenged. - -#### Return Values - -| Name | Type | Description | -| ---- | ---- | ----------- | -| [0] | bool | True if DKG timed out, false otherwise. | - -### notifySeedTimeout - -```solidity -function notifySeedTimeout(struct EcdsaDkg.Data self) internal -``` - -Notifies about the seed was not delivered and restores the -initial DKG state (IDLE). - -### notifyDkgTimeout - -```solidity -function notifyDkgTimeout(struct EcdsaDkg.Data self) internal -``` - -Notifies about DKG timeout. - -### approveResult - -```solidity -function approveResult(struct EcdsaDkg.Data self, struct EcdsaDkg.Result result) internal returns (uint32[] misbehavedMembers) -``` - -Approves DKG result. Can be called when the challenge period for -the submitted result is finished. Considers the submitted result -as valid. For the first `submitterPrecedencePeriodLength` -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. - -Can be called after a challenge period for the submitted result. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| self | struct EcdsaDkg.Data | | -| result | struct EcdsaDkg.Result | Result to approve. Must match the submitted result stored during `submitResult`. | - -#### Return Values - -| Name | Type | Description | -| ---- | ---- | ----------- | -| misbehavedMembers | uint32[] | Identifiers of members who misbehaved during DKG. | - -### challengeResult - -```solidity -function challengeResult(struct EcdsaDkg.Data self, struct EcdsaDkg.Result result) internal returns (bytes32 maliciousResultHash, uint32 maliciousSubmitter) -``` - -Challenges DKG result. If the submitted result is proved to be -invalid it reverts the DKG back to the result submission phase. - -Can be called during a challenge period for the submitted result. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| self | struct EcdsaDkg.Data | | -| result | struct EcdsaDkg.Result | Result to challenge. Must match the submitted result stored during `submitResult`. | - -#### Return Values - -| Name | Type | Description | -| ---- | ---- | ----------- | -| maliciousResultHash | bytes32 | Hash of the malicious result. | -| maliciousSubmitter | uint32 | Identifier of the malicious submitter. | - -### requireChallengeExtraGas - -```solidity -function requireChallengeExtraGas(struct EcdsaDkg.Data self) internal view -``` - -Due to EIP150, 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 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. - -## 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. | - -## Wallets - -### Wallet - -```solidity -struct Wallet { - bytes32 membersIdsHash; - bytes32 publicKeyX; - bytes32 publicKeyY; -} -``` - -### Data - -```solidity -struct Data { - mapping(bytes32 => struct Wallets.Wallet) registry; - uint256[49] __gap; -} -``` - -### validatePublicKey - -```solidity -function validatePublicKey(struct Wallets.Data self, bytes publicKey) internal view -``` - -Performs preliminary validation of a new group public key. -The group public key must be unique and have 64 bytes in length. -If the validation fails, the function reverts. This function -must be called first for a public key of a wallet added with -`addWallet` function. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| self | struct Wallets.Data | | -| publicKey | bytes | Uncompressed public key of a new wallet. | - -### addWallet - -```solidity -function addWallet(struct Wallets.Data self, bytes32 membersIdsHash, bytes publicKey) internal returns (bytes32 walletID, bytes32 publicKeyX, bytes32 publicKeyY) -``` - -Registers a new wallet. This function does not validate -parameters. The code calling this function must call -`validatePublicKey` first. - -Uses a public key hash as a unique identifier of a wallet. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| self | struct Wallets.Data | | -| membersIdsHash | bytes32 | Keccak256 hash of group members identifiers array | -| publicKey | bytes | Uncompressed public key | - -#### Return Values - -| Name | Type | Description | -| ---- | ---- | ----------- | -| walletID | bytes32 | Wallet's ID | -| publicKeyX | bytes32 | Wallet's public key's X coordinate | -| publicKeyY | bytes32 | Wallet's public key's Y coordinate | - -### deleteWallet - -```solidity -function deleteWallet(struct Wallets.Data self, bytes32 walletID) internal -``` - -Deletes wallet with the given ID from the registry. Reverts -if wallet with the given ID has not been registered or if it -has already been closed. - -### isWalletRegistered - -```solidity -function isWalletRegistered(struct Wallets.Data self, bytes32 walletID) internal view returns (bool) -``` - -Checks if a wallet with the given ID is registered. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| self | struct Wallets.Data | | -| walletID | bytes32 | Wallet's ID | - -#### Return Values - -| Name | Type | Description | -| ---- | ---- | ----------- | -| [0] | bool | True if a wallet is registered, false otherwise | - -### getWalletMembersIdsHash - -```solidity -function getWalletMembersIdsHash(struct Wallets.Data self, bytes32 walletID) internal view returns (bytes32) -``` - -Returns Keccak256 hash of the wallet signing group members -identifiers array. Group members do not include operators -selected by the sortition pool that misbehaved during DKG. -Reverts if wallet with the given ID is not registered. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| self | struct Wallets.Data | | -| walletID | bytes32 | ID of the wallet | - -#### Return Values - -| Name | Type | Description | -| ---- | ---- | ----------- | -| [0] | bytes32 | Wallet signing group members hash | - -### getWalletPublicKeyCoordinates - -```solidity -function getWalletPublicKeyCoordinates(struct Wallets.Data self, bytes32 walletID) internal view returns (bytes32 x, bytes32 y) -``` - -Gets public key of a wallet with the given wallet ID. -The public key is returned as X and Y coordinates. -Reverts if wallet with the given ID is not registered. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| self | struct Wallets.Data | | -| walletID | bytes32 | ID of the wallet | - -#### Return Values - -| Name | Type | Description | -| ---- | ---- | ----------- | -| x | bytes32 | Public key X coordinate | -| y | bytes32 | Public key Y coordinate | - -### getWalletPublicKey - -```solidity -function getWalletPublicKey(struct Wallets.Data self, bytes32 walletID) internal view returns (bytes) -``` - -Gets public key of a wallet with the given wallet ID. -The public key is returned in an uncompressed format as a 64-byte -concatenation of X and Y coordinates. -Reverts if wallet with the given ID is not registered. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| self | struct Wallets.Data | | -| walletID | bytes32 | ID of the wallet | - -#### Return Values - -| Name | Type | Description | -| ---- | ---- | ----------- | -| [0] | bytes | Uncompressed public key of the wallet | - diff --git a/docs/app-development/tbtc-v2/ecdsa-api/generated-docs/libraries/EcdsaAuthorization.md b/docs/app-development/tbtc-v2/ecdsa-api/generated-docs/libraries/EcdsaAuthorization.md new file mode 100644 index 0000000..e93840b --- /dev/null +++ b/docs/app-development/tbtc-v2/ecdsa-api/generated-docs/libraries/EcdsaAuthorization.md @@ -0,0 +1,307 @@ +# Solidity API + +## EcdsaAuthorization + +Library managing the state of stake authorizations for ECDSA +operator contract and the presence of operators in the sortition +pool based on the stake authorized for them. + +### Parameters + +```solidity +struct Parameters { + uint96 minimumAuthorization; + uint64 authorizationDecreaseDelay; + uint64 authorizationDecreaseChangePeriod; +} +``` + +### AuthorizationDecrease + +```solidity +struct AuthorizationDecrease { + uint96 decreasingBy; + uint64 decreasingAt; +} +``` + +### Data + +```solidity +struct Data { + struct EcdsaAuthorization.Parameters parameters; + mapping(address => address) stakingProviderToOperator; + mapping(address => address) operatorToStakingProvider; + mapping(address => struct EcdsaAuthorization.AuthorizationDecrease) pendingDecreases; + uint256[46] __gap; +} +``` + +### 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) +``` + +### setMinimumAuthorization + +```solidity +function setMinimumAuthorization(struct EcdsaAuthorization.Data self, uint96 _minimumAuthorization) internal +``` + +Sets the minimum authorization for ECDSA application. Without +at least the minimum authorization, staking provider is not +eligible to join and operate in the network. + +### setAuthorizationDecreaseDelay + +```solidity +function setAuthorizationDecreaseDelay(struct EcdsaAuthorization.Data self, uint64 _authorizationDecreaseDelay) internal +``` + +Sets the authorization decrease delay. It is the time in seconds +that needs to pass between the time authorization decrease is +requested and the time the authorization decrease can be +approved, no matter the authorization decrease amount. + +### setAuthorizationDecreaseChangePeriod + +```solidity +function setAuthorizationDecreaseChangePeriod(struct EcdsaAuthorization.Data self, uint64 _authorizationDecreaseChangePeriod) internal +``` + +Sets the authorization decrease change period. It is the time +period before the authorization decrease delay end, +during which the authorization decrease request can be +overwritten. + +### registerOperator + +```solidity +function registerOperator(struct EcdsaAuthorization.Data self, address operator) internal +``` + +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. + +### authorizationIncreased + +```solidity +function authorizationIncreased(struct EcdsaAuthorization.Data self, address stakingProvider, uint96 fromAmount, uint96 toAmount) internal +``` + +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`. + +Should only be callable by T staking contract. + +### authorizationDecreaseRequested + +```solidity +function authorizationDecreaseRequested(struct EcdsaAuthorization.Data self, address stakingProvider, uint96 fromAmount, uint96 toAmount) internal +``` + +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. + +Reverts if another authorization decrease request is pending for +the staking provider and not enough time passed since the +original request (see `authorizationDecreaseChangePeriod`). + +If the operator is not known (`registerOperator` was not called) +it lets to `approveAuthorizationDecrease` immediately. 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, but only if enough time passed since the original +request. Otherwise, the function reverts. + +Should only be callable by T staking contract. + +### approveAuthorizationDecrease + +```solidity +function approveAuthorizationDecrease(struct EcdsaAuthorization.Data self, contract IStaking tokenStaking, address stakingProvider) internal +``` + +Approves the previously registered authorization decrease +request. Reverts if authorization decrease delay have not passed +yet or if the authorization decrease was not requested for the +given staking provider. + +### involuntaryAuthorizationDecrease + +```solidity +function involuntaryAuthorizationDecrease(struct EcdsaAuthorization.Data self, contract IStaking tokenStaking, contract SortitionPool sortitionPool, address stakingProvider, uint96 fromAmount, uint96 toAmount) internal +``` + +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. + +Should only be callable by T staking contract. + +### joinSortitionPool + +```solidity +function joinSortitionPool(struct EcdsaAuthorization.Data self, contract IStaking tokenStaking, contract SortitionPool sortitionPool) internal +``` + +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(struct EcdsaAuthorization.Data self, contract IStaking tokenStaking, contract SortitionPool sortitionPool, address operator) internal +``` + +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. + +### isOperatorUpToDate + +```solidity +function isOperatorUpToDate(struct EcdsaAuthorization.Data self, contract IStaking tokenStaking, contract SortitionPool sortitionPool, address operator) internal view returns (bool) +``` + +Checks if the operator's authorized stake is in sync with +operator's weight in the sortition pool. +If the operator is not in the sortition pool and their +authorized stake is non-zero, function returns false. + +### eligibleStake + +```solidity +function eligibleStake(struct EcdsaAuthorization.Data self, contract IStaking tokenStaking, address stakingProvider) internal view returns (uint96) +``` + +Returns the current value of the staking provider's eligible +stake. Eligible stake is defined as the currently authorized +stake minus the pending authorization decrease. Eligible stake +is what is used for operator's weight in the pool. If the +authorized stake minus the pending authorization decrease is +below the minimum authorization, eligible stake is 0. + +This function can be exposed to the public in contrast to the +second variant accepting `decreasingBy` as a parameter. + +### eligibleStake + +```solidity +function eligibleStake(struct EcdsaAuthorization.Data self, contract IStaking tokenStaking, address stakingProvider, uint96 decreasingBy) internal view returns (uint96) +``` + +Returns the current value of the staking provider's eligible +stake. Eligible stake is defined as the currently authorized +stake minus the pending authorization decrease. Eligible stake +is what is used for operator's weight in the pool. If the +authorized stake minus the pending authorization decrease is +below the minimum authorization, eligible stake is 0. + +This function is not intended to be exposes to the public. +`decreasingBy` must be fetched from `pendingDecreases` mapping and +it is passed as a parameter to optimize gas usage of functions that +call `eligibleStake` and need to use `AuthorizationDecrease` +fetched from `pendingDecreases` for some additional logic. + +### pendingAuthorizationDecrease + +```solidity +function pendingAuthorizationDecrease(struct EcdsaAuthorization.Data self, address stakingProvider) internal view returns (uint96) +``` + +Returns the amount of stake that is pending authorization +decrease for the given staking provider. If no authorization +decrease has been requested, returns zero. + +### remainingAuthorizationDecreaseDelay + +```solidity +function remainingAuthorizationDecreaseDelay(struct EcdsaAuthorization.Data self, address stakingProvider) internal view returns (uint64) +``` + +Returns the remaining time in seconds that needs to pass before +the requested authorization decrease can be approved. +If the sortition pool state was not updated yet by the operator +after requesting the authorization decrease, returns +`type(uint64).max`. + diff --git a/docs/app-development/tbtc-v2/ecdsa-api/generated-docs/libraries/EcdsaDkg.md b/docs/app-development/tbtc-v2/ecdsa-api/generated-docs/libraries/EcdsaDkg.md new file mode 100644 index 0000000..a883620 --- /dev/null +++ b/docs/app-development/tbtc-v2/ecdsa-api/generated-docs/libraries/EcdsaDkg.md @@ -0,0 +1,356 @@ +# Solidity API + +## EcdsaDkg + +### Parameters + +```solidity +struct Parameters { + uint256 seedTimeout; + uint256 resultChallengePeriodLength; + uint256 resultChallengeExtraGas; + uint256 resultSubmissionTimeout; + uint256 submitterPrecedencePeriodLength; +} +``` + +### Data + +```solidity +struct Data { + contract SortitionPool sortitionPool; + contract EcdsaDkgValidator dkgValidator; + struct EcdsaDkg.Parameters parameters; + uint256 stateLockBlock; + uint256 startBlock; + uint256 seed; + uint256 resultSubmissionStartBlockOffset; + bytes32 submittedResultHash; + uint256 submittedResultBlock; + uint256[38] __gap; +} +``` + +### Result + +```solidity +struct Result { + uint256 submitterMemberIndex; + bytes groupPubKey; + uint8[] misbehavedMembersIndices; + bytes signatures; + uint256[] signingMembersIndices; + uint32[] members; + bytes32 membersHash; +} +``` + +### State + +```solidity +enum State { + IDLE, + AWAITING_SEED, + AWAITING_RESULT, + CHALLENGE +} +``` + +### groupSize + +```solidity +uint256 groupSize +``` + +Size of a group in ECDSA wallet. + +### 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() +``` + +### init + +```solidity +function init(struct EcdsaDkg.Data self, contract SortitionPool _sortitionPool, contract EcdsaDkgValidator _dkgValidator) internal +``` + +Initializes SortitionPool and EcdsaDkgValidator addresses. +Can be performed only once. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| self | struct EcdsaDkg.Data | | +| _sortitionPool | contract SortitionPool | Sortition Pool reference | +| _dkgValidator | contract EcdsaDkgValidator | EcdsaDkgValidator reference | + +### currentState + +```solidity +function currentState(struct EcdsaDkg.Data self) internal view returns (enum EcdsaDkg.State state) +``` + +Determines the current state of group creation. It doesn't take +timeouts into consideration. The timeouts should be tracked and +notified separately. + +### lockState + +```solidity +function lockState(struct EcdsaDkg.Data self) internal +``` + +Locks the sortition pool and starts awaiting for the +group creation seed. + +### start + +```solidity +function start(struct EcdsaDkg.Data self, uint256 seed) internal +``` + +### submitResult + +```solidity +function submitResult(struct EcdsaDkg.Data self, struct EcdsaDkg.Result result) internal +``` + +Allows to submit a DKG result. The submitted result does not go +through a validation and before it gets accepted, it needs to +wait through the challenge period during which everyone has +a chance to challenge the result as invalid one. Submitter of +the result needs to be in the sortition pool and if the result +gets challenged, the submitter will get slashed. + +### hasSeedTimedOut + +```solidity +function hasSeedTimedOut(struct EcdsaDkg.Data self) internal view returns (bool) +``` + +Checks if awaiting seed timed out. + +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +| [0] | bool | True if awaiting seed timed out, false otherwise. | + +### hasDkgTimedOut + +```solidity +function hasDkgTimedOut(struct EcdsaDkg.Data self) internal view returns (bool) +``` + +Checks if DKG timed out. The DKG timeout period includes time required +for off-chain protocol execution and time for the result publication. +After this time a result cannot be submitted and DKG can be notified +about the timeout. DKG period is adjusted by result submission +offset that include blocks that were mined while invalid result +has been registered until it got challenged. + +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +| [0] | bool | True if DKG timed out, false otherwise. | + +### notifySeedTimeout + +```solidity +function notifySeedTimeout(struct EcdsaDkg.Data self) internal +``` + +Notifies about the seed was not delivered and restores the +initial DKG state (IDLE). + +### notifyDkgTimeout + +```solidity +function notifyDkgTimeout(struct EcdsaDkg.Data self) internal +``` + +Notifies about DKG timeout. + +### approveResult + +```solidity +function approveResult(struct EcdsaDkg.Data self, struct EcdsaDkg.Result result) internal returns (uint32[] misbehavedMembers) +``` + +Approves DKG result. Can be called when the challenge period for +the submitted result is finished. Considers the submitted result +as valid. For the first `submitterPrecedencePeriodLength` +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. + +Can be called after a challenge period for the submitted result. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| self | struct EcdsaDkg.Data | | +| result | struct EcdsaDkg.Result | Result to approve. Must match the submitted result stored during `submitResult`. | + +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +| misbehavedMembers | uint32[] | Identifiers of members who misbehaved during DKG. | + +### challengeResult + +```solidity +function challengeResult(struct EcdsaDkg.Data self, struct EcdsaDkg.Result result) internal returns (bytes32 maliciousResultHash, uint32 maliciousSubmitter) +``` + +Challenges DKG result. If the submitted result is proved to be +invalid it reverts the DKG back to the result submission phase. + +Can be called during a challenge period for the submitted result. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| self | struct EcdsaDkg.Data | | +| result | struct EcdsaDkg.Result | Result to challenge. Must match the submitted result stored during `submitResult`. | + +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +| maliciousResultHash | bytes32 | Hash of the malicious result. | +| maliciousSubmitter | uint32 | Identifier of the malicious submitter. | + +### requireChallengeExtraGas + +```solidity +function requireChallengeExtraGas(struct EcdsaDkg.Data self) internal view +``` + +Due to EIP150, 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 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. + diff --git a/docs/app-development/tbtc-v2/ecdsa-api/generated-docs/libraries/EcdsaInactivity.md b/docs/app-development/tbtc-v2/ecdsa-api/generated-docs/libraries/EcdsaInactivity.md new file mode 100644 index 0000000..3a2ee32 --- /dev/null +++ b/docs/app-development/tbtc-v2/ecdsa-api/generated-docs/libraries/EcdsaInactivity.md @@ -0,0 +1,81 @@ +# Solidity API + +## 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. | + diff --git a/docs/app-development/tbtc-v2/ecdsa-api/generated-docs/libraries/Wallets.md b/docs/app-development/tbtc-v2/ecdsa-api/generated-docs/libraries/Wallets.md new file mode 100644 index 0000000..ad1f022 --- /dev/null +++ b/docs/app-development/tbtc-v2/ecdsa-api/generated-docs/libraries/Wallets.md @@ -0,0 +1,173 @@ +# Solidity API + +## Wallets + +### Wallet + +```solidity +struct Wallet { + bytes32 membersIdsHash; + bytes32 publicKeyX; + bytes32 publicKeyY; +} +``` + +### Data + +```solidity +struct Data { + mapping(bytes32 => struct Wallets.Wallet) registry; + uint256[49] __gap; +} +``` + +### validatePublicKey + +```solidity +function validatePublicKey(struct Wallets.Data self, bytes publicKey) internal view +``` + +Performs preliminary validation of a new group public key. +The group public key must be unique and have 64 bytes in length. +If the validation fails, the function reverts. This function +must be called first for a public key of a wallet added with +`addWallet` function. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| self | struct Wallets.Data | | +| publicKey | bytes | Uncompressed public key of a new wallet. | + +### addWallet + +```solidity +function addWallet(struct Wallets.Data self, bytes32 membersIdsHash, bytes publicKey) internal returns (bytes32 walletID, bytes32 publicKeyX, bytes32 publicKeyY) +``` + +Registers a new wallet. This function does not validate +parameters. The code calling this function must call +`validatePublicKey` first. + +Uses a public key hash as a unique identifier of a wallet. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| self | struct Wallets.Data | | +| membersIdsHash | bytes32 | Keccak256 hash of group members identifiers array | +| publicKey | bytes | Uncompressed public key | + +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +| walletID | bytes32 | Wallet's ID | +| publicKeyX | bytes32 | Wallet's public key's X coordinate | +| publicKeyY | bytes32 | Wallet's public key's Y coordinate | + +### deleteWallet + +```solidity +function deleteWallet(struct Wallets.Data self, bytes32 walletID) internal +``` + +Deletes wallet with the given ID from the registry. Reverts +if wallet with the given ID has not been registered or if it +has already been closed. + +### isWalletRegistered + +```solidity +function isWalletRegistered(struct Wallets.Data self, bytes32 walletID) internal view returns (bool) +``` + +Checks if a wallet with the given ID is registered. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| self | struct Wallets.Data | | +| walletID | bytes32 | Wallet's ID | + +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +| [0] | bool | True if a wallet is registered, false otherwise | + +### getWalletMembersIdsHash + +```solidity +function getWalletMembersIdsHash(struct Wallets.Data self, bytes32 walletID) internal view returns (bytes32) +``` + +Returns Keccak256 hash of the wallet signing group members +identifiers array. Group members do not include operators +selected by the sortition pool that misbehaved during DKG. +Reverts if wallet with the given ID is not registered. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| self | struct Wallets.Data | | +| walletID | bytes32 | ID of the wallet | + +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +| [0] | bytes32 | Wallet signing group members hash | + +### getWalletPublicKeyCoordinates + +```solidity +function getWalletPublicKeyCoordinates(struct Wallets.Data self, bytes32 walletID) internal view returns (bytes32 x, bytes32 y) +``` + +Gets public key of a wallet with the given wallet ID. +The public key is returned as X and Y coordinates. +Reverts if wallet with the given ID is not registered. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| self | struct Wallets.Data | | +| walletID | bytes32 | ID of the wallet | + +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +| x | bytes32 | Public key X coordinate | +| y | bytes32 | Public key Y coordinate | + +### getWalletPublicKey + +```solidity +function getWalletPublicKey(struct Wallets.Data self, bytes32 walletID) internal view returns (bytes) +``` + +Gets public key of a wallet with the given wallet ID. +The public key is returned in an uncompressed format as a 64-byte +concatenation of X and Y coordinates. +Reverts if wallet with the given ID is not registered. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| self | struct Wallets.Data | | +| walletID | bytes32 | ID of the wallet | + +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +| [0] | bytes | Uncompressed public key of the wallet | + diff --git a/docs/app-development/tbtc-v2/tbtc-v2-api/README.md b/docs/app-development/tbtc-v2/tbtc-v2-api/README.md new file mode 100644 index 0000000..a3707a5 --- /dev/null +++ b/docs/app-development/tbtc-v2/tbtc-v2-api/README.md @@ -0,0 +1,66 @@ +# Bridge API + +You can learn about APIs of contracts related to the Bridge under the following +links: + +[Bank](./generated-docs/bank/Bank.md) + +[BitcoinTx](./generated-docs/bridge/BitcoinTx.md) + +[Bridge](./generated-docs/bridge/Bridge.md) + +[BridgeGovernance](./generated-docs/bridge/BridgeGovernance.md) + +[BridgeGovernanceParameters](./generated-docs/bridge/BridgeGovernanceParameters.md) + +[BridgeState](./generated-docs/bridge/BridgeState.md) + +[Deposit](./generated-docs/bridge/Deposit.md) + +[DepositSweep](./generated-docs/bridge/DepositSweep.md) + +[DonationVault](./generated-docs/vault/DonationVault.md) + +[EcdsaLib](./generated-docs/bridge/EcdsaLib.md) + +[Fraud](./generated-docs/bridge/Fraud.md) + +[GovernanceUtils](./generated-docs/GovernanceUtils.md) + +[Heartbeat](./generated-docs/bridge/Heartbeat.md) + +[IReceiveBalanceApproval](./generated-docs/bank/IReceiveBalanceApproval.md) + +[IRelay](./generated-docs/bridge/IRelay.md) + +[IVault](./generated-docs/vault/IVault.md) + +[L2TBTC](./generated-docs/l2/L2TBTC.md) + +[L2WormholeGateway](./generated-docs/l2/L2WormholeGateway.md) + +[LightRelay](./generated-docs/relay/LightRelay.md) + +[LightRelayMaintainerProxy](./generated-docs/relay/LightRelayMaintainerProxy.md) + +[MaintainerProxy](./generated-docs/maintainer/MaintainerProxy.md) + +[MovingFunds](./generated-docs/bridge/MovingFunds.md) + +[Redemption](./generated-docs/bridge/Redemption.md) + +[TBTC](./generated-docs/token/TBTC.md) + +[TBTCOptimisticMinting](./generated-docs/vault/TBTCOptimisticMinting.md) + +[TBTCVault](./generated-docs/vault/TBTCVault.md) + +[VendingMachine](./generated-docs/bridge/VendingMachine.md) + +[VendingMachineV2](./generated-docs/bridge/VendingMachineV2.md) + +[VendingMachineV3](./generated-docs/bridge/VendingMachineV3.md) + +[WalletCoordinator](./generated-docs/bridge/WalletCoordinator.md) + +[Wallets](./generated-docs/bridge/Wallets.md) diff --git a/docs/app-development/tbtc-v2/tbtc-v2-api/generated-docs/GovernanceUtils.md b/docs/app-development/tbtc-v2/tbtc-v2-api/generated-docs/GovernanceUtils.md new file mode 100644 index 0000000..6843fd6 --- /dev/null +++ b/docs/app-development/tbtc-v2/tbtc-v2-api/generated-docs/GovernanceUtils.md @@ -0,0 +1,43 @@ +# Solidity API + +## GovernanceUtils + +### onlyAfterGovernanceDelay + +```solidity +function onlyAfterGovernanceDelay(uint256 changeInitiatedTimestamp, uint256 delay) internal view +``` + +Reverts if the governance delay has not passed since +the change initiated time or if the change has not been +initiated. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| changeInitiatedTimestamp | uint256 | The timestamp at which the change has been initiated. | +| delay | uint256 | Governance delay. | + +### getRemainingGovernanceDelay + +```solidity +function getRemainingGovernanceDelay(uint256 changeInitiatedTimestamp, uint256 delay) internal view returns (uint256) +``` + +Gets the time remaining until the governable parameter update +can be committed. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| changeInitiatedTimestamp | uint256 | Timestamp indicating the beginning of the change. | +| delay | uint256 | Governance delay. | + +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +| [0] | uint256 | Remaining time in seconds. | + diff --git a/docs/app-development/tbtc-v2/tbtc-v2-api/generated-docs/bank/Bank.md b/docs/app-development/tbtc-v2/tbtc-v2-api/generated-docs/bank/Bank.md new file mode 100644 index 0000000..14a7663 --- /dev/null +++ b/docs/app-development/tbtc-v2/tbtc-v2-api/generated-docs/bank/Bank.md @@ -0,0 +1,395 @@ +# Solidity API + +## Bank + +Bank is a central component tracking Bitcoin balances. Balances can +be transferred between balance owners, and balance owners can +approve their balances to be spent by others. Balances in the Bank +are updated for depositors who deposited their Bitcoin into the +Bridge and only the Bridge can increase balances. + +Bank is a governable contract and the Governance can upgrade the Bridge +address. + +### bridge + +```solidity +address bridge +``` + +### balanceOf + +```solidity +mapping(address => uint256) balanceOf +``` + +The balance of the given account in the Bank. Zero by default. + +### allowance + +```solidity +mapping(address => mapping(address => uint256)) allowance +``` + +The remaining amount of balance a spender will be +allowed to transfer on behalf of an owner using +`transferBalanceFrom`. Zero by default. + +### nonces + +```solidity +mapping(address => uint256) nonces +``` + +Returns the current nonce for an EIP2612 permission for the +provided balance owner to protect against replay attacks. Used +to construct an EIP2612 signature provided to the `permit` +function. + +### cachedChainId + +```solidity +uint256 cachedChainId +``` + +### cachedDomainSeparator + +```solidity +bytes32 cachedDomainSeparator +``` + +### PERMIT_TYPEHASH + +```solidity +bytes32 PERMIT_TYPEHASH +``` + +Returns an EIP2612 Permit message hash. Used to construct +an EIP2612 signature provided to the `permit` function. + +### BalanceTransferred + +```solidity +event BalanceTransferred(address from, address to, uint256 amount) +``` + +### BalanceApproved + +```solidity +event BalanceApproved(address owner, address spender, uint256 amount) +``` + +### BalanceIncreased + +```solidity +event BalanceIncreased(address owner, uint256 amount) +``` + +### BalanceDecreased + +```solidity +event BalanceDecreased(address owner, uint256 amount) +``` + +### BridgeUpdated + +```solidity +event BridgeUpdated(address newBridge) +``` + +### onlyBridge + +```solidity +modifier onlyBridge() +``` + +### constructor + +```solidity +constructor() public +``` + +### updateBridge + +```solidity +function updateBridge(address _bridge) external +``` + +Allows the Governance to upgrade the Bridge address. + +The function does not implement any governance delay and does not +check the status of the Bridge. The Governance implementation needs +to ensure all requirements for the upgrade are satisfied before +executing this function. +Requirements: +- The new Bridge address must not be zero. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| _bridge | address | The new Bridge address. | + +### transferBalance + +```solidity +function transferBalance(address recipient, uint256 amount) external +``` + +Moves the given `amount` of balance from the caller to +`recipient`. + +Requirements: +- `recipient` cannot be the zero address, +- the caller must have a balance of at least `amount`. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| recipient | address | The recipient of the balance. | +| amount | uint256 | The amount of the balance transferred. | + +### approveBalance + +```solidity +function approveBalance(address spender, uint256 amount) external +``` + +Sets `amount` as the allowance of `spender` over the caller's +balance. Does not allow updating an existing allowance to +a value that is non-zero to avoid someone using both the old and +the new allowance by unfortunate transaction ordering. To update +an allowance to a non-zero value please set it to zero first or +use `increaseBalanceAllowance` or `decreaseBalanceAllowance` for +an atomic update. + +If the `amount` is set to `type(uint256).max`, +`transferBalanceFrom` will not reduce an allowance. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| spender | address | The address that will be allowed to spend the balance. | +| amount | uint256 | The amount the spender is allowed to spend. | + +### approveBalanceAndCall + +```solidity +function approveBalanceAndCall(address spender, uint256 amount, bytes extraData) external +``` + +Sets the `amount` as an allowance of a smart contract `spender` +over the caller's balance and calls the `spender` via +`receiveBalanceApproval`. + +If the `amount` is set to `type(uint256).max`, the potential +`transferBalanceFrom` executed in `receiveBalanceApproval` of +`spender` will not reduce an allowance. Beware that changing an +allowance with this function brings the risk that `spender` may use +both the old and the new allowance by unfortunate transaction +ordering. Please use `increaseBalanceAllowance` and +`decreaseBalanceAllowance` to eliminate the risk. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| spender | address | The smart contract that will be allowed to spend the balance. | +| amount | uint256 | The amount the spender contract is allowed to spend. | +| extraData | bytes | Extra data passed to the `spender` contract via `receiveBalanceApproval` call. | + +### increaseBalanceAllowance + +```solidity +function increaseBalanceAllowance(address spender, uint256 addedValue) external +``` + +Atomically increases the caller's balance allowance granted to +`spender` by the given `addedValue`. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| spender | address | The spender address for which the allowance is increased. | +| addedValue | uint256 | The amount by which the allowance is increased. | + +### decreaseBalanceAllowance + +```solidity +function decreaseBalanceAllowance(address spender, uint256 subtractedValue) external +``` + +Atomically decreases the caller's balance allowance granted to +`spender` by the given `subtractedValue`. + +Requirements: +- `spender` must not be the zero address, +- the current allowance for `spender` must not be lower than +the `subtractedValue`. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| spender | address | The spender address for which the allowance is decreased. | +| subtractedValue | uint256 | The amount by which the allowance is decreased. | + +### transferBalanceFrom + +```solidity +function transferBalanceFrom(address spender, address recipient, uint256 amount) external +``` + +Moves `amount` of balance from `spender` to `recipient` using the +allowance mechanism. `amount` is then deducted from the caller's +allowance unless the allowance was made for `type(uint256).max`. + +Requirements: +- `recipient` cannot be the zero address, +- `spender` must have a balance of at least `amount`, +- the caller must have an allowance for `spender`'s balance of at +least `amount`. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| spender | address | The address from which the balance is transferred. | +| recipient | address | The address to which the balance is transferred. | +| amount | uint256 | The amount of balance that is transferred. | + +### permit + +```solidity +function permit(address owner, address spender, uint256 amount, uint256 deadline, uint8 v, bytes32 r, bytes32 s) external +``` + +An EIP2612 approval made with secp256k1 signature. Users can +authorize a transfer of their balance with a signature +conforming to the EIP712 standard, rather than an on-chain +transaction from their address. Anyone can submit this signature +on the user's behalf by calling the `permit` function, paying +gas fees, and possibly performing other actions in the same +transaction. + +The deadline argument can be set to `type(uint256).max to create +permits that effectively never expire. If the `amount` is set +to `type(uint256).max` then `transferBalanceFrom` will not +reduce an allowance. Beware that changing an allowance with this +function brings the risk that someone may use both the old and the +new allowance by unfortunate transaction ordering. Please use +`increaseBalanceAllowance` and `decreaseBalanceAllowance` to +eliminate the risk. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| owner | address | The balance owner who signed the permission. | +| spender | address | The address that will be allowed to spend the balance. | +| amount | uint256 | The amount the spender is allowed to spend. | +| deadline | uint256 | The UNIX time until which the permit is valid. | +| v | uint8 | V part of the permit signature. | +| r | bytes32 | R part of the permit signature. | +| s | bytes32 | S part of the permit signature. | + +### increaseBalances + +```solidity +function increaseBalances(address[] recipients, uint256[] amounts) external +``` + +Increases balances of the provided `recipients` by the provided +`amounts`. Can only be called by the Bridge. + +Requirements: +- length of `recipients` and `amounts` must be the same, +- none of `recipients` addresses must point to the Bank. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| recipients | address[] | Balance increase recipients. | +| amounts | uint256[] | Amounts by which balances are increased. | + +### increaseBalance + +```solidity +function increaseBalance(address recipient, uint256 amount) external +``` + +Increases balance of the provided `recipient` by the provided +`amount`. Can only be called by the Bridge. + +Requirements: +- `recipient` address must not point to the Bank. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| recipient | address | Balance increase recipient. | +| amount | uint256 | Amount by which the balance is increased. | + +### increaseBalanceAndCall + +```solidity +function increaseBalanceAndCall(address vault, address[] recipients, uint256[] amounts) external +``` + +Increases the given smart contract `vault`'s balance and +notifies the `vault` contract about it. +Can be called only by the Bridge. + +Requirements: +- `vault` must implement `IVault` interface, +- length of `recipients` and `amounts` must be the same. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| vault | address | Address of `IVault` recipient contract. | +| recipients | address[] | Balance increase recipients. | +| amounts | uint256[] | Amounts by which balances are increased. | + +### decreaseBalance + +```solidity +function decreaseBalance(uint256 amount) external +``` + +Decreases caller's balance by the provided `amount`. There is no +way to restore the balance so do not call this function unless +you really know what you are doing! + +Requirements: +- The caller must have a balance of at least `amount`. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| amount | uint256 | The amount by which the balance is decreased. | + +### DOMAIN_SEPARATOR + +```solidity +function DOMAIN_SEPARATOR() public view returns (bytes32) +``` + +Returns hash of EIP712 Domain struct with `TBTC Bank` as +a signing domain and Bank contract as a verifying contract. +Used to construct an EIP2612 signature provided to the `permit` +function. + +### _increaseBalance + +```solidity +function _increaseBalance(address recipient, uint256 amount) internal +``` + diff --git a/docs/app-development/tbtc-v2/tbtc-v2-api/generated-docs/bank/IReceiveBalanceApproval.md b/docs/app-development/tbtc-v2/tbtc-v2-api/generated-docs/bank/IReceiveBalanceApproval.md new file mode 100644 index 0000000..c4ae265 --- /dev/null +++ b/docs/app-development/tbtc-v2/tbtc-v2-api/generated-docs/bank/IReceiveBalanceApproval.md @@ -0,0 +1,36 @@ +# Solidity API + +## IReceiveBalanceApproval + +`IReceiveBalanceApproval` is an interface for a smart contract +consuming Bank balances approved to them in the same transaction by +other contracts or externally owned accounts (EOA). + +### receiveBalanceApproval + +```solidity +function receiveBalanceApproval(address owner, uint256 amount, bytes extraData) external +``` + +Called by the Bank in `approveBalanceAndCall` function after +the balance `owner` approved `amount` of their balance in the +Bank for the contract. This way, the depositor can approve +balance and call the contract to use the approved balance in +a single transaction. + +The implementation must ensure this function can only be called +by the Bank. The Bank does _not_ guarantee that the `amount` +approved by the `owner` currently exists on their balance. That is, +the `owner` could approve more balance than they currently have. +This works the same as `Bank.approve` function. The contract must +ensure the actual balance is checked before performing any action +based on it. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| owner | address | Address of the Bank balance owner who approved their balance to be used by the contract. | +| amount | uint256 | The amount of the Bank balance approved by the owner to be used by the contract. | +| extraData | bytes | The `extraData` passed to `Bank.approveBalanceAndCall`. | + diff --git a/docs/app-development/tbtc-v2/tbtc-v2-api/generated-docs/bridge/BitcoinTx.md b/docs/app-development/tbtc-v2/tbtc-v2-api/generated-docs/bridge/BitcoinTx.md new file mode 100644 index 0000000..6862007 --- /dev/null +++ b/docs/app-development/tbtc-v2/tbtc-v2-api/generated-docs/bridge/BitcoinTx.md @@ -0,0 +1,238 @@ +# Solidity API + +## BitcoinTx + +Allows to reference Bitcoin raw transaction in Solidity. + +See https://developer.bitcoin.org/reference/transactions.html#raw-transaction-format + +Raw Bitcoin transaction data: + +| Bytes | Name | BTC type | Description | +|--------|--------------|------------------------|---------------------------| +| 4 | version | int32_t (LE) | TX version number | +| varies | tx_in_count | compactSize uint (LE) | Number of TX inputs | +| varies | tx_in | txIn[] | TX inputs | +| varies | tx_out_count | compactSize uint (LE) | Number of TX outputs | +| varies | tx_out | txOut[] | TX outputs | +| 4 | lock_time | uint32_t (LE) | Unix time or block number | + +Non-coinbase transaction input (txIn): + +| Bytes | Name | BTC type | Description | +|--------|------------------|------------------------|---------------------------------------------| +| 36 | previous_output | outpoint | The previous outpoint being spent | +| varies | script_bytes | compactSize uint (LE) | The number of bytes in the signature script | +| varies | signature_script | char[] | The signature script, empty for P2WSH | +| 4 | sequence | uint32_t (LE) | Sequence number | + +The reference to transaction being spent (outpoint): + +| Bytes | Name | BTC type | Description | +|-------|-------|---------------|------------------------------------------| +| 32 | hash | char[32] | Hash of the transaction to spend | +| 4 | index | uint32_t (LE) | Index of the specific output from the TX | + +Transaction output (txOut): + +| Bytes | Name | BTC type | Description | +|--------|-----------------|-----------------------|--------------------------------------| +| 8 | value | int64_t (LE) | Number of satoshis to spend | +| 1+ | pk_script_bytes | compactSize uint (LE) | Number of bytes in the pubkey script | +| varies | pk_script | char[] | Pubkey script | + +compactSize uint format: + +| Value | Bytes | Format | +|-----------------------------------------|-------|----------------------------------------------| +| >= 0 && <= 252 | 1 | uint8_t | +| >= 253 && <= 0xffff | 3 | 0xfd followed by the number as uint16_t (LE) | +| >= 0x10000 && <= 0xffffffff | 5 | 0xfe followed by the number as uint32_t (LE) | +| >= 0x100000000 && <= 0xffffffffffffffff | 9 | 0xff followed by the number as uint64_t (LE) | + +(*) compactSize uint is often references as VarInt) + +Coinbase transaction input (txIn): + +| Bytes | Name | BTC type | Description | +|--------|------------------|------------------------|---------------------------------------------| +| 32 | hash | char[32] | A 32-byte 0x0 null (no previous_outpoint) | +| 4 | index | uint32_t (LE) | 0xffffffff (no previous_outpoint) | +| varies | script_bytes | compactSize uint (LE) | The number of bytes in the coinbase script | +| varies | height | char[] | The block height of this block (BIP34) (*) | +| varies | coinbase_script | none | Arbitrary data, max 100 bytes | +| 4 | sequence | uint32_t (LE) | Sequence number + +(*) Uses script language: starts with a data-pushing opcode that indicates how many bytes to push to +the stack followed by the block height as a little-endian unsigned integer. This script must be as +short as possible, otherwise it may be rejected. The data-pushing opcode will be 0x03 and the total +size four bytes until block 16,777,216 about 300 years from now. + +### Info + +```solidity +struct Info { + bytes4 version; + bytes inputVector; + bytes outputVector; + bytes4 locktime; +} +``` + +### Proof + +```solidity +struct Proof { + bytes merkleProof; + uint256 txIndexInBlock; + bytes bitcoinHeaders; +} +``` + +### UTXO + +```solidity +struct UTXO { + bytes32 txHash; + uint32 txOutputIndex; + uint64 txOutputValue; +} +``` + +### RSVSignature + +```solidity +struct RSVSignature { + bytes32 r; + bytes32 s; + uint8 v; +} +``` + +### validateProof + +```solidity +function validateProof(struct BridgeState.Storage self, struct BitcoinTx.Info txInfo, struct BitcoinTx.Proof proof) internal view returns (bytes32 txHash) +``` + +Validates the SPV proof of the Bitcoin transaction. +Reverts in case the validation or proof verification fail. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| self | struct BridgeState.Storage | | +| txInfo | struct BitcoinTx.Info | Bitcoin transaction data. | +| proof | struct BitcoinTx.Proof | Bitcoin proof data. | + +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +| txHash | bytes32 | Proven 32-byte transaction hash. | + +### evaluateProofDifficulty + +```solidity +function evaluateProofDifficulty(struct BridgeState.Storage self, bytes bitcoinHeaders) internal view +``` + +Evaluates the given Bitcoin proof difficulty against the actual +Bitcoin chain difficulty provided by the relay oracle. +Reverts in case the evaluation fails. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| self | struct BridgeState.Storage | | +| bitcoinHeaders | bytes | Bitcoin headers chain being part of the SPV proof. Used to extract the observed proof difficulty. | + +### extractPubKeyHash + +```solidity +function extractPubKeyHash(struct BridgeState.Storage, bytes output) internal pure returns (bytes20 pubKeyHash) +``` + +Extracts public key hash from the provided P2PKH or P2WPKH output. +Reverts if the validation fails. + +Requirements: +- The output must be of P2PKH or P2WPKH type and lock the funds +on a 20-byte public key hash. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| | struct BridgeState.Storage | | +| output | bytes | The transaction output. | + +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +| pubKeyHash | bytes20 | 20-byte public key hash the output locks funds on. | + +### makeP2PKHScript + +```solidity +function makeP2PKHScript(bytes20 pubKeyHash) internal pure returns (bytes26) +``` + +Build the P2PKH script from the given public key hash. + +The P2PKH script has the following byte format: +<0x1976a914> <20-byte PKH> <0x88ac>. According to +https://en.bitcoin.it/wiki/Script#Opcodes this translates to: +- 0x19: Byte length of the entire script +- 0x76: OP_DUP +- 0xa9: OP_HASH160 +- 0x14: Byte length of the public key hash +- 0x88: OP_EQUALVERIFY +- 0xac: OP_CHECKSIG +which matches the P2PKH structure as per: +https://en.bitcoin.it/wiki/Transaction#Pay-to-PubkeyHash + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| pubKeyHash | bytes20 | The 20-byte public key hash. | + +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +| [0] | bytes26 | The P2PKH script. | + +### makeP2WPKHScript + +```solidity +function makeP2WPKHScript(bytes20 pubKeyHash) internal pure returns (bytes23) +``` + +Build the P2WPKH script from the given public key hash. + +The P2WPKH script has the following format: +<0x160014> <20-byte PKH>. According to +https://en.bitcoin.it/wiki/Script#Opcodes this translates to: +- 0x16: Byte length of the entire script +- 0x00: OP_0 +- 0x14: Byte length of the public key hash +which matches the P2WPKH structure as per: +https://github.com/bitcoin/bips/blob/master/bip-0141.mediawiki#P2WPKH + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| pubKeyHash | bytes20 | The 20-byte public key hash. | + +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +| [0] | bytes23 | The P2WPKH script. | + diff --git a/docs/app-development/tbtc-v2/tbtc-v2-api/generated-docs/bridge/Bridge.md b/docs/app-development/tbtc-v2/tbtc-v2-api/generated-docs/bridge/Bridge.md new file mode 100644 index 0000000..66b3252 --- /dev/null +++ b/docs/app-development/tbtc-v2/tbtc-v2-api/generated-docs/bridge/Bridge.md @@ -0,0 +1,1536 @@ +# Solidity API + +## Bridge + +Bridge manages BTC deposit and redemption flow and is increasing and +decreasing balances in the Bank as a result of BTC deposit and +redemption operations performed by depositors and redeemers. + +Depositors send BTC funds to the most recently created off-chain +ECDSA wallet of the bridge using pay-to-script-hash (P2SH) or +pay-to-witness-script-hash (P2WSH) containing hashed information +about the depositor’s Ethereum address. Then, the depositor reveals +their Ethereum address along with their deposit blinding factor, +refund public key hash and refund locktime to the Bridge on Ethereum +chain. The off-chain ECDSA wallet listens for these sorts of +messages and when it gets one, it checks the Bitcoin network to make +sure the deposit lines up. If it does, the off-chain ECDSA wallet +may decide to pick the deposit transaction for sweeping, and when +the sweep operation is confirmed on the Bitcoin network, the ECDSA +wallet informs the Bridge about the sweep increasing appropriate +balances in the Bank. + +Bridge is an upgradeable component of the Bank. The order of +functionalities in this contract is: deposit, sweep, redemption, +moving funds, wallet lifecycle, frauds, parameters. + +### self + +```solidity +struct BridgeState.Storage self +``` + +### DepositRevealed + +```solidity +event DepositRevealed(bytes32 fundingTxHash, uint32 fundingOutputIndex, address depositor, uint64 amount, bytes8 blindingFactor, bytes20 walletPubKeyHash, bytes20 refundPubKeyHash, bytes4 refundLocktime, address vault) +``` + +### DepositsSwept + +```solidity +event DepositsSwept(bytes20 walletPubKeyHash, bytes32 sweepTxHash) +``` + +### RedemptionRequested + +```solidity +event RedemptionRequested(bytes20 walletPubKeyHash, bytes redeemerOutputScript, address redeemer, uint64 requestedAmount, uint64 treasuryFee, uint64 txMaxFee) +``` + +### RedemptionsCompleted + +```solidity +event RedemptionsCompleted(bytes20 walletPubKeyHash, bytes32 redemptionTxHash) +``` + +### RedemptionTimedOut + +```solidity +event RedemptionTimedOut(bytes20 walletPubKeyHash, bytes redeemerOutputScript) +``` + +### WalletMovingFunds + +```solidity +event WalletMovingFunds(bytes32 ecdsaWalletID, bytes20 walletPubKeyHash) +``` + +### MovingFundsCommitmentSubmitted + +```solidity +event MovingFundsCommitmentSubmitted(bytes20 walletPubKeyHash, bytes20[] targetWallets, address submitter) +``` + +### MovingFundsTimeoutReset + +```solidity +event MovingFundsTimeoutReset(bytes20 walletPubKeyHash) +``` + +### MovingFundsCompleted + +```solidity +event MovingFundsCompleted(bytes20 walletPubKeyHash, bytes32 movingFundsTxHash) +``` + +### MovingFundsTimedOut + +```solidity +event MovingFundsTimedOut(bytes20 walletPubKeyHash) +``` + +### MovingFundsBelowDustReported + +```solidity +event MovingFundsBelowDustReported(bytes20 walletPubKeyHash) +``` + +### MovedFundsSwept + +```solidity +event MovedFundsSwept(bytes20 walletPubKeyHash, bytes32 sweepTxHash) +``` + +### MovedFundsSweepTimedOut + +```solidity +event MovedFundsSweepTimedOut(bytes20 walletPubKeyHash, bytes32 movingFundsTxHash, uint32 movingFundsTxOutputIndex) +``` + +### NewWalletRequested + +```solidity +event NewWalletRequested() +``` + +### NewWalletRegistered + +```solidity +event NewWalletRegistered(bytes32 ecdsaWalletID, bytes20 walletPubKeyHash) +``` + +### WalletClosing + +```solidity +event WalletClosing(bytes32 ecdsaWalletID, bytes20 walletPubKeyHash) +``` + +### WalletClosed + +```solidity +event WalletClosed(bytes32 ecdsaWalletID, bytes20 walletPubKeyHash) +``` + +### WalletTerminated + +```solidity +event WalletTerminated(bytes32 ecdsaWalletID, bytes20 walletPubKeyHash) +``` + +### FraudChallengeSubmitted + +```solidity +event FraudChallengeSubmitted(bytes20 walletPubKeyHash, bytes32 sighash, uint8 v, bytes32 r, bytes32 s) +``` + +### FraudChallengeDefeated + +```solidity +event FraudChallengeDefeated(bytes20 walletPubKeyHash, bytes32 sighash) +``` + +### FraudChallengeDefeatTimedOut + +```solidity +event FraudChallengeDefeatTimedOut(bytes20 walletPubKeyHash, bytes32 sighash) +``` + +### VaultStatusUpdated + +```solidity +event VaultStatusUpdated(address vault, bool isTrusted) +``` + +### SpvMaintainerStatusUpdated + +```solidity +event SpvMaintainerStatusUpdated(address spvMaintainer, bool isTrusted) +``` + +### DepositParametersUpdated + +```solidity +event DepositParametersUpdated(uint64 depositDustThreshold, uint64 depositTreasuryFeeDivisor, uint64 depositTxMaxFee, uint32 depositRevealAheadPeriod) +``` + +### RedemptionParametersUpdated + +```solidity +event RedemptionParametersUpdated(uint64 redemptionDustThreshold, uint64 redemptionTreasuryFeeDivisor, uint64 redemptionTxMaxFee, uint64 redemptionTxMaxTotalFee, uint32 redemptionTimeout, uint96 redemptionTimeoutSlashingAmount, uint32 redemptionTimeoutNotifierRewardMultiplier) +``` + +### MovingFundsParametersUpdated + +```solidity +event MovingFundsParametersUpdated(uint64 movingFundsTxMaxTotalFee, uint64 movingFundsDustThreshold, uint32 movingFundsTimeoutResetDelay, uint32 movingFundsTimeout, uint96 movingFundsTimeoutSlashingAmount, uint32 movingFundsTimeoutNotifierRewardMultiplier, uint16 movingFundsCommitmentGasOffset, uint64 movedFundsSweepTxMaxTotalFee, uint32 movedFundsSweepTimeout, uint96 movedFundsSweepTimeoutSlashingAmount, uint32 movedFundsSweepTimeoutNotifierRewardMultiplier) +``` + +### WalletParametersUpdated + +```solidity +event WalletParametersUpdated(uint32 walletCreationPeriod, uint64 walletCreationMinBtcBalance, uint64 walletCreationMaxBtcBalance, uint64 walletClosureMinBtcBalance, uint32 walletMaxAge, uint64 walletMaxBtcTransfer, uint32 walletClosingPeriod) +``` + +### FraudParametersUpdated + +```solidity +event FraudParametersUpdated(uint96 fraudChallengeDepositAmount, uint32 fraudChallengeDefeatTimeout, uint96 fraudSlashingAmount, uint32 fraudNotifierRewardMultiplier) +``` + +### TreasuryUpdated + +```solidity +event TreasuryUpdated(address treasury) +``` + +### onlySpvMaintainer + +```solidity +modifier onlySpvMaintainer() +``` + +### constructor + +```solidity +constructor() public +``` + +### initialize + +```solidity +function initialize(address _bank, address _relay, address _treasury, address _ecdsaWalletRegistry, address payable _reimbursementPool, uint96 _txProofDifficultyFactor) external +``` + +Initializes upgradable contract on deployment. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| _bank | address | Address of the Bank the Bridge belongs to. | +| _relay | address | Address of the Bitcoin relay providing the current Bitcoin network difficulty. | +| _treasury | address | Address where the deposit and redemption treasury fees will be sent to. | +| _ecdsaWalletRegistry | address | Address of the ECDSA Wallet Registry contract. | +| _reimbursementPool | address payable | Address of the Reimbursement Pool contract. | +| _txProofDifficultyFactor | uint96 | The number of confirmations on the Bitcoin chain required to successfully evaluate an SPV proof. | + +### revealDeposit + +```solidity +function revealDeposit(struct BitcoinTx.Info fundingTx, struct Deposit.DepositRevealInfo reveal) external +``` + +Used by the depositor to reveal information about their P2(W)SH +Bitcoin deposit to the Bridge on Ethereum chain. The off-chain +wallet listens for revealed deposit events and may decide to +include the revealed deposit in the next executed sweep. +Information about the Bitcoin deposit can be revealed before or +after the Bitcoin transaction with P2(W)SH deposit is mined on +the Bitcoin chain. Worth noting, the gas cost of this function +scales with the number of P2(W)SH transaction inputs and +outputs. The deposit may be routed to one of the trusted vaults. +When a deposit is routed to a vault, vault gets notified when +the deposit gets swept and it may execute the appropriate action. + +Requirements: +- This function must be called by the same Ethereum address as the +one used in the P2(W)SH BTC deposit transaction as a depositor, +- `reveal.walletPubKeyHash` must identify a `Live` wallet, +- `reveal.vault` must be 0x0 or point to a trusted vault, +- `reveal.fundingOutputIndex` must point to the actual P2(W)SH +output of the BTC deposit transaction, +- `reveal.blindingFactor` must be the blinding factor used in the +P2(W)SH BTC deposit transaction, +- `reveal.walletPubKeyHash` must be the wallet pub key hash used in +the P2(W)SH BTC deposit transaction, +- `reveal.refundPubKeyHash` must be the refund pub key hash used in +the P2(W)SH BTC deposit transaction, +- `reveal.refundLocktime` must be the refund locktime used in the +P2(W)SH BTC deposit transaction, +- BTC deposit for the given `fundingTxHash`, `fundingOutputIndex` +can be revealed only one time. + +If any of these requirements is not met, the wallet _must_ refuse +to sweep the deposit and the depositor has to wait until the +deposit script unlocks to receive their BTC back. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| fundingTx | struct BitcoinTx.Info | Bitcoin funding transaction data, see `BitcoinTx.Info`. | +| reveal | struct Deposit.DepositRevealInfo | Deposit reveal data, see `RevealInfo struct. | + +### submitDepositSweepProof + +```solidity +function submitDepositSweepProof(struct BitcoinTx.Info sweepTx, struct BitcoinTx.Proof sweepProof, struct BitcoinTx.UTXO mainUtxo, address vault) external +``` + +Used by the wallet to prove the BTC deposit sweep transaction +and to update Bank balances accordingly. Sweep is only accepted +if it satisfies SPV proof. + +The function is performing Bank balance updates by first +computing the Bitcoin fee for the sweep transaction. The fee is +divided evenly between all swept deposits. Each depositor +receives a balance in the bank equal to the amount inferred +during the reveal transaction, minus their fee share. + +It is possible to prove the given sweep only one time. + +Requirements: +- `sweepTx` components must match the expected structure. See +`BitcoinTx.Info` docs for reference. Their values must exactly +correspond to appropriate Bitcoin transaction fields to produce +a provable transaction hash, +- The `sweepTx` should represent a Bitcoin transaction with 1..n +inputs. If the wallet has no main UTXO, all n inputs should +correspond to P2(W)SH revealed deposits UTXOs. If the wallet has +an existing main UTXO, one of the n inputs must point to that +main UTXO and remaining n-1 inputs should correspond to P2(W)SH +revealed deposits UTXOs. That transaction must have only +one P2(W)PKH output locking funds on the 20-byte wallet public +key hash, +- All revealed deposits that are swept by `sweepTx` must have +their `vault` parameters set to the same address as the address +passed in the `vault` function parameter, +- `sweepProof` components must match the expected structure. See +`BitcoinTx.Proof` docs for reference. The `bitcoinHeaders` +field must contain a valid number of block headers, not less +than the `txProofDifficultyFactor` contract constant, +- `mainUtxo` components must point to the recent main UTXO +of the given wallet, as currently known on the Ethereum chain. +If there is no main UTXO, this parameter is ignored. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| sweepTx | struct BitcoinTx.Info | Bitcoin sweep transaction data. | +| sweepProof | struct BitcoinTx.Proof | Bitcoin sweep proof data. | +| mainUtxo | struct BitcoinTx.UTXO | Data of the wallet's main UTXO, as currently known on the Ethereum chain. If no main UTXO exists for the given wallet, this parameter is ignored. | +| vault | address | Optional address of the vault where all swept deposits should be routed to. All deposits swept as part of the transaction must have their `vault` parameters set to the same address. If this parameter is set to an address of a trusted vault, swept deposits are routed to that vault. If this parameter is set to the zero address or to an address of a non-trusted vault, swept deposits are not routed to a vault but depositors' balances are increased in the Bank individually. | + +### requestRedemption + +```solidity +function requestRedemption(bytes20 walletPubKeyHash, struct BitcoinTx.UTXO mainUtxo, bytes redeemerOutputScript, uint64 amount) external +``` + +Requests redemption of the given amount from the specified +wallet to the redeemer Bitcoin output script. Handles the +simplest case in which the redeemer's balance is decreased in +the Bank. + +Requirements: +- Wallet behind `walletPubKeyHash` must be live, +- `mainUtxo` components must point to the recent main UTXO +of the given wallet, as currently known on the Ethereum chain, +- `redeemerOutputScript` must be a proper Bitcoin script, +- `redeemerOutputScript` cannot have wallet PKH as payload, +- `amount` must be above or equal the `redemptionDustThreshold`, +- Given `walletPubKeyHash` and `redeemerOutputScript` pair can be +used for only one pending request at the same time, +- Wallet must have enough Bitcoin balance to process the request, +- Redeemer must make an allowance in the Bank that the Bridge +contract can spend the given `amount`. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| walletPubKeyHash | bytes20 | The 20-byte wallet public key hash (computed using Bitcoin HASH160 over the compressed ECDSA public key). | +| mainUtxo | struct BitcoinTx.UTXO | Data of the wallet's main UTXO, as currently known on the Ethereum chain. | +| redeemerOutputScript | bytes | The redeemer's length-prefixed output script (P2PKH, P2WPKH, P2SH or P2WSH) that will be used to lock redeemed BTC. | +| amount | uint64 | Requested amount in satoshi. This is also the Bank balance that is taken from the `balanceOwner` upon request. Once the request is handled, the actual amount of BTC locked on the redeemer output script will be always lower than this value since the treasury and Bitcoin transaction fees must be incurred. The minimal amount satisfying the request can be computed as: `amount - (amount / redemptionTreasuryFeeDivisor) - redemptionTxMaxFee`. Fees values are taken at the moment of request creation. | + +### receiveBalanceApproval + +```solidity +function receiveBalanceApproval(address balanceOwner, uint256 amount, bytes redemptionData) external +``` + +Requests redemption of the given amount from the specified +wallet to the redeemer Bitcoin output script. Used by +`Bank.approveBalanceAndCall`. Can handle more complex cases +where balance owner may be someone else than the redeemer. +For example, vault redeeming its balance for some depositor. + +Requirements: +- The caller must be the Bank, +- Wallet behind `walletPubKeyHash` must be live, +- `mainUtxo` components must point to the recent main UTXO +of the given wallet, as currently known on the Ethereum chain, +- `redeemerOutputScript` must be a proper Bitcoin script, +- `redeemerOutputScript` cannot have wallet PKH as payload, +- `amount` must be above or equal the `redemptionDustThreshold`, +- Given `walletPubKeyHash` and `redeemerOutputScript` pair can be +used for only one pending request at the same time, +- Wallet must have enough Bitcoin balance to process the request. + +Note on upgradeability: +Bridge is an upgradeable contract deployed behind +a TransparentUpgradeableProxy. Accepting redemption data as bytes +provides great flexibility. The Bridge is just like any other +contract with a balance approved in the Bank and can be upgraded +to another version without being bound to a particular interface +forever. This flexibility comes with the cost - developers +integrating their vaults and dApps with `Bridge` using +`approveBalanceAndCall` need to pay extra attention to +`redemptionData` and adjust the code in case the expected structure +of `redemptionData` changes. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| balanceOwner | address | The address of the Bank balance owner whose balance is getting redeemed. | +| amount | uint256 | Requested amount in satoshi. This is also the Bank balance that is taken from the `balanceOwner` upon request. Once the request is handled, the actual amount of BTC locked on the redeemer output script will be always lower than this value since the treasury and Bitcoin transaction fees must be incurred. The minimal amount satisfying the request can be computed as: `amount - (amount / redemptionTreasuryFeeDivisor) - redemptionTxMaxFee`. Fees values are taken at the moment of request creation. | +| redemptionData | bytes | ABI-encoded redemption data: [ address redeemer, bytes20 walletPubKeyHash, bytes32 mainUtxoTxHash, uint32 mainUtxoTxOutputIndex, uint64 mainUtxoTxOutputValue, bytes redeemerOutputScript ] - redeemer: The Ethereum address of the redeemer who will be able to claim Bank balance if anything goes wrong during the redemption. In the most basic case, when someone redeems their balance from the Bank, `balanceOwner` is the same as `redeemer`. However, when a Vault is redeeming part of its balance for some redeemer address (for example, someone who has earlier deposited into that Vault), `balanceOwner` is the Vault, and `redeemer` is the address for which the vault is redeeming its balance to, - walletPubKeyHash: The 20-byte wallet public key hash (computed using Bitcoin HASH160 over the compressed ECDSA public key), - mainUtxoTxHash: Data of the wallet's main UTXO TX hash, as currently known on the Ethereum chain, - mainUtxoTxOutputIndex: Data of the wallet's main UTXO output index, as currently known on Ethereum chain, - mainUtxoTxOutputValue: Data of the wallet's main UTXO output value, as currently known on Ethereum chain, - redeemerOutputScript The redeemer's length-prefixed output script (P2PKH, P2WPKH, P2SH or P2WSH) that will be used to lock redeemed BTC. | + +### submitRedemptionProof + +```solidity +function submitRedemptionProof(struct BitcoinTx.Info redemptionTx, struct BitcoinTx.Proof redemptionProof, struct BitcoinTx.UTXO mainUtxo, bytes20 walletPubKeyHash) external +``` + +Used by the wallet to prove the BTC redemption transaction +and to make the necessary bookkeeping. Redemption is only +accepted if it satisfies SPV proof. + +The function is performing Bank balance updates by burning +the total redeemed Bitcoin amount from Bridge balance and +transferring the treasury fee sum to the treasury address. + +It is possible to prove the given redemption only one time. + +Requirements: +- `redemptionTx` components must match the expected structure. See +`BitcoinTx.Info` docs for reference. Their values must exactly +correspond to appropriate Bitcoin transaction fields to produce +a provable transaction hash, +- The `redemptionTx` should represent a Bitcoin transaction with +exactly 1 input that refers to the wallet's main UTXO. That +transaction should have 1..n outputs handling existing pending +redemption requests or pointing to reported timed out requests. +There can be also 1 optional output representing the +change and pointing back to the 20-byte wallet public key hash. +The change should be always present if the redeemed value sum +is lower than the total wallet's BTC balance, +- `redemptionProof` components must match the expected structure. +See `BitcoinTx.Proof` docs for reference. The `bitcoinHeaders` +field must contain a valid number of block headers, not less +than the `txProofDifficultyFactor` contract constant, +- `mainUtxo` components must point to the recent main UTXO +of the given wallet, as currently known on the Ethereum chain. +Additionally, the recent main UTXO on Ethereum must be set, +- `walletPubKeyHash` must be connected with the main UTXO used +as transaction single input. +Other remarks: +- Putting the change output as the first transaction output can +save some gas because the output processing loop begins each +iteration by checking whether the given output is the change +thus uses some gas for making the comparison. Once the change +is identified, that check is omitted in further iterations. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| redemptionTx | struct BitcoinTx.Info | Bitcoin redemption transaction data. | +| redemptionProof | struct BitcoinTx.Proof | Bitcoin redemption proof data. | +| mainUtxo | struct BitcoinTx.UTXO | Data of the wallet's main UTXO, as currently known on the Ethereum chain. | +| walletPubKeyHash | bytes20 | 20-byte public key hash (computed using Bitcoin HASH160 over the compressed ECDSA public key) of the wallet which performed the redemption transaction. | + +### notifyRedemptionTimeout + +```solidity +function notifyRedemptionTimeout(bytes20 walletPubKeyHash, uint32[] walletMembersIDs, bytes redeemerOutputScript) external +``` + +Notifies that there is a pending redemption request associated +with the given wallet, that has timed out. The redemption +request is identified by the key built as +`keccak256(keccak256(redeemerOutputScript) | walletPubKeyHash)`. +The results of calling this function: +- The pending redemptions value for the wallet will be decreased +by the requested amount (minus treasury fee), +- The tokens taken from the redeemer on redemption request will +be returned to the redeemer, +- The request will be moved from pending redemptions to +timed-out redemptions, +- If the state of the wallet is `Live` or `MovingFunds`, the +wallet operators will be slashed and the notifier will be +rewarded, +- If the state of wallet is `Live`, the wallet will be closed or +marked as `MovingFunds` (depending on the presence or absence +of the wallet's main UTXO) and the wallet will no longer be +marked as the active wallet (if it was marked as such). + +Requirements: +- The wallet must be in the Live or MovingFunds or Terminated state, +- The redemption request identified by `walletPubKeyHash` and +`redeemerOutputScript` must exist, +- 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 of the `WalletRegistry` contract, +- The amount of time defined by `redemptionTimeout` must have +passed since the redemption was requested (the request must be +timed-out). + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| walletPubKeyHash | bytes20 | 20-byte public key hash of the wallet. | +| walletMembersIDs | uint32[] | Identifiers of the wallet signing group members. | +| redeemerOutputScript | bytes | The redeemer's length-prefixed output script (P2PKH, P2WPKH, P2SH or P2WSH). | + +### submitMovingFundsCommitment + +```solidity +function submitMovingFundsCommitment(bytes20 walletPubKeyHash, struct BitcoinTx.UTXO walletMainUtxo, uint32[] walletMembersIDs, uint256 walletMemberIndex, bytes20[] targetWallets) external +``` + +Submits the moving funds target wallets commitment. +Once all requirements are met, that function registers the +target wallets commitment and opens the way for moving funds +proof submission. +The caller is reimbursed for the transaction costs. + +Requirements: +- The source wallet must be in the MovingFunds state, +- The source wallet must not have pending redemption requests, +- The source wallet must not have pending moved funds sweep requests, +- The source wallet must not have submitted its commitment already, +- The expression `keccak256(abi.encode(walletMembersIDs))` must +be exactly the same as the hash stored under `membersIdsHash` +for the given source wallet in the ECDSA registry. 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], +- The caller must be the member of the source wallet signing group +at the position indicated by `walletMemberIndex` parameter, +- The `walletMainUtxo` components must point to the recent main +UTXO of the source wallet, as currently known on the Ethereum +chain, +- Source wallet BTC balance must be greater than zero, +- At least one Live wallet must exist in the system, +- Submitted target wallets count must match the expected count +`N = min(liveWalletsCount, ceil(walletBtcBalance / walletMaxBtcTransfer))` +where `N > 0`, +- Each target wallet must be not equal to the source wallet, +- Each target wallet must follow the expected order i.e. all +target wallets 20-byte public key hashes represented as numbers +must form a strictly increasing sequence without duplicates, +- Each target wallet must be in Live state. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| walletPubKeyHash | bytes20 | 20-byte public key hash of the source wallet. | +| walletMainUtxo | struct BitcoinTx.UTXO | Data of the source wallet's main UTXO, as currently known on the Ethereum chain. | +| walletMembersIDs | uint32[] | Identifiers of the source wallet signing group members. | +| walletMemberIndex | uint256 | Position of the caller in the source wallet signing group members list. | +| targetWallets | bytes20[] | List of 20-byte public key hashes of the target wallets that the source wallet commits to move the funds to. | + +### resetMovingFundsTimeout + +```solidity +function resetMovingFundsTimeout(bytes20 walletPubKeyHash) external +``` + +Resets the moving funds timeout for the given wallet if the +target wallet commitment cannot be submitted due to a lack +of live wallets in the system. + +Requirements: +- The wallet must be in the MovingFunds state, +- The target wallets commitment must not be already submitted for +the given moving funds wallet, +- Live wallets count must be zero, +- The moving funds timeout reset delay must be elapsed. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| walletPubKeyHash | bytes20 | 20-byte public key hash of the moving funds wallet. | + +### submitMovingFundsProof + +```solidity +function submitMovingFundsProof(struct BitcoinTx.Info movingFundsTx, struct BitcoinTx.Proof movingFundsProof, struct BitcoinTx.UTXO mainUtxo, bytes20 walletPubKeyHash) external +``` + +Used by the wallet to prove the BTC moving funds transaction +and to make the necessary state changes. Moving funds is only +accepted if it satisfies SPV proof. + +The function validates the moving funds transaction structure +by checking if it actually spends the main UTXO of the declared +wallet and locks the value on the pre-committed target wallets +using a reasonable transaction fee. If all preconditions are +met, this functions closes the source wallet. + +It is possible to prove the given moving funds transaction only +one time. + +Requirements: +- `movingFundsTx` components must match the expected structure. See +`BitcoinTx.Info` docs for reference. Their values must exactly +correspond to appropriate Bitcoin transaction fields to produce +a provable transaction hash, +- The `movingFundsTx` should represent a Bitcoin transaction with +exactly 1 input that refers to the wallet's main UTXO. That +transaction should have 1..n outputs corresponding to the +pre-committed target wallets. Outputs must be ordered in the +same way as their corresponding target wallets are ordered +within the target wallets commitment, +- `movingFundsProof` components must match the expected structure. +See `BitcoinTx.Proof` docs for reference. The `bitcoinHeaders` +field must contain a valid number of block headers, not less +than the `txProofDifficultyFactor` contract constant, +- `mainUtxo` components must point to the recent main UTXO +of the given wallet, as currently known on the Ethereum chain. +Additionally, the recent main UTXO on Ethereum must be set, +- `walletPubKeyHash` must be connected with the main UTXO used +as transaction single input, +- The wallet that `walletPubKeyHash` points to must be in the +MovingFunds state, +- The target wallets commitment must be submitted by the wallet +that `walletPubKeyHash` points to, +- The total Bitcoin transaction fee must be lesser or equal +to `movingFundsTxMaxTotalFee` governable parameter. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| movingFundsTx | struct BitcoinTx.Info | Bitcoin moving funds transaction data. | +| movingFundsProof | struct BitcoinTx.Proof | Bitcoin moving funds proof data. | +| mainUtxo | struct BitcoinTx.UTXO | Data of the wallet's main UTXO, as currently known on the Ethereum chain. | +| walletPubKeyHash | bytes20 | 20-byte public key hash (computed using Bitcoin HASH160 over the compressed ECDSA public key) of the wallet which performed the moving funds transaction. | + +### notifyMovingFundsTimeout + +```solidity +function notifyMovingFundsTimeout(bytes20 walletPubKeyHash, uint32[] walletMembersIDs) external +``` + +Notifies about a timed out moving funds process. Terminates +the wallet and slashes signing group members as a result. + +Requirements: +- The wallet must be in the MovingFunds state, +- The moving funds timeout must be actually exceeded, +- 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 of the `WalletRegistry` contract. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| walletPubKeyHash | bytes20 | 20-byte public key hash of the wallet. | +| walletMembersIDs | uint32[] | Identifiers of the wallet signing group members. | + +### notifyMovingFundsBelowDust + +```solidity +function notifyMovingFundsBelowDust(bytes20 walletPubKeyHash, struct BitcoinTx.UTXO mainUtxo) external +``` + +Notifies about a moving funds wallet whose BTC balance is +below the moving funds dust threshold. Ends the moving funds +process and begins wallet closing immediately. + +Requirements: +- The wallet must be in the MovingFunds state, +- The `mainUtxo` components must point to the recent main UTXO +of the given wallet, as currently known on the Ethereum chain. +If the wallet has no main UTXO, this parameter can be empty as it +is ignored, +- The wallet BTC balance must be below the moving funds threshold. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| walletPubKeyHash | bytes20 | 20-byte public key hash of the wallet | +| mainUtxo | struct BitcoinTx.UTXO | Data of the wallet's main UTXO, as currently known on the Ethereum chain. | + +### submitMovedFundsSweepProof + +```solidity +function submitMovedFundsSweepProof(struct BitcoinTx.Info sweepTx, struct BitcoinTx.Proof sweepProof, struct BitcoinTx.UTXO mainUtxo) external +``` + +Used by the wallet to prove the BTC moved funds sweep +transaction and to make the necessary state changes. Moved +funds sweep is only accepted if it satisfies SPV proof. + +The function validates the sweep transaction structure by +checking if it actually spends the moved funds UTXO and the +sweeping wallet's main UTXO (optionally), and if it locks the +value on the sweeping wallet's 20-byte public key hash using a +reasonable transaction fee. If all preconditions are +met, this function updates the sweeping wallet main UTXO, thus +their BTC balance. + +It is possible to prove the given sweep transaction only +one time. + +Requirements: +- `sweepTx` components must match the expected structure. See +`BitcoinTx.Info` docs for reference. Their values must exactly +correspond to appropriate Bitcoin transaction fields to produce +a provable transaction hash, +- The `sweepTx` should represent a Bitcoin transaction with +the first input pointing to a moved funds sweep request targeted +to the wallet, and optionally, the second input pointing to the +wallet's main UTXO, if the sweeping wallet has a main UTXO set. +There should be only one output locking funds on the sweeping +wallet 20-byte public key hash, +- `sweepProof` components must match the expected structure. +See `BitcoinTx.Proof` docs for reference. The `bitcoinHeaders` +field must contain a valid number of block headers, not less +than the `txProofDifficultyFactor` contract constant, +- `mainUtxo` components must point to the recent main UTXO +of the sweeping wallet, as currently known on the Ethereum chain. +If there is no main UTXO, this parameter is ignored, +- The sweeping wallet must be in the Live or MovingFunds state, +- The total Bitcoin transaction fee must be lesser or equal +to `movedFundsSweepTxMaxTotalFee` governable parameter. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| sweepTx | struct BitcoinTx.Info | Bitcoin sweep funds transaction data. | +| sweepProof | struct BitcoinTx.Proof | Bitcoin sweep funds proof data. | +| mainUtxo | struct BitcoinTx.UTXO | Data of the sweeping wallet's main UTXO, as currently known on the Ethereum chain. | + +### notifyMovedFundsSweepTimeout + +```solidity +function notifyMovedFundsSweepTimeout(bytes32 movingFundsTxHash, uint32 movingFundsTxOutputIndex, uint32[] walletMembersIDs) external +``` + +Notifies about a timed out moved funds sweep process. If the +wallet is not terminated yet, that function terminates +the wallet and slashes signing group members as a result. +Marks the given sweep request as TimedOut. + +Requirements: +- The moved funds sweep request must be in the Pending state, +- The moved funds sweep timeout must be actually exceeded, +- The wallet must be either in the Live or MovingFunds or +Terminated state, +- 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 of the `WalletRegistry` contract. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| movingFundsTxHash | bytes32 | 32-byte hash of the moving funds transaction that caused the sweep request to be created. | +| movingFundsTxOutputIndex | uint32 | Index of the moving funds transaction output that is subject of the sweep request. | +| walletMembersIDs | uint32[] | Identifiers of the wallet signing group members. | + +### requestNewWallet + +```solidity +function requestNewWallet(struct BitcoinTx.UTXO activeWalletMainUtxo) external +``` + +Requests creation of a new wallet. This function just +forms a request and the creation process is performed +asynchronously. Once a wallet is created, the ECDSA Wallet +Registry will notify this contract by calling the +`__ecdsaWalletCreatedCallback` function. + +Requirements: +- `activeWalletMainUtxo` components must point to the recent main +UTXO of the given active wallet, as currently known on the +Ethereum chain. If there is no active wallet at the moment, or +the active wallet has no main UTXO, this parameter can be +empty as it is ignored, +- Wallet creation must not be in progress, +- If the active wallet is set, one of the following +conditions must be true: +- The active wallet BTC balance is above the minimum threshold +and the active wallet is old enough, i.e. the creation period +was elapsed since its creation time, +- The active wallet BTC balance is above the maximum threshold. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| activeWalletMainUtxo | struct BitcoinTx.UTXO | Data of the active wallet's main UTXO, as currently known on the Ethereum chain. | + +### __ecdsaWalletCreatedCallback + +```solidity +function __ecdsaWalletCreatedCallback(bytes32 ecdsaWalletID, bytes32 publicKeyX, bytes32 publicKeyY) external +``` + +A callback function that is called by the ECDSA Wallet Registry +once a new ECDSA wallet is created. + +Requirements: +- The only caller authorized to call this function is `registry`, +- Given wallet data must not belong to an already registered wallet. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| ecdsaWalletID | bytes32 | Wallet's unique identifier. | +| publicKeyX | bytes32 | Wallet's public key's X coordinate. | +| publicKeyY | bytes32 | Wallet's public key's Y coordinate. | + +### __ecdsaWalletHeartbeatFailedCallback + +```solidity +function __ecdsaWalletHeartbeatFailedCallback(bytes32, bytes32 publicKeyX, bytes32 publicKeyY) external +``` + +A callback function that is called by the ECDSA Wallet Registry +once a wallet heartbeat failure is detected. + +Requirements: +- The only caller authorized to call this function is `registry`, +- Wallet must be in Live state. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| | bytes32 | | +| publicKeyX | bytes32 | Wallet's public key's X coordinate. | +| publicKeyY | bytes32 | Wallet's public key's Y coordinate. | + +### notifyWalletCloseable + +```solidity +function notifyWalletCloseable(bytes20 walletPubKeyHash, struct BitcoinTx.UTXO walletMainUtxo) external +``` + +Notifies that the wallet is either old enough or has too few +satoshi left and qualifies to be closed. + +Requirements: +- Wallet must not be set as the current active wallet, +- Wallet must exceed the wallet maximum age OR the wallet BTC +balance must be lesser than the minimum threshold. If the latter +case is true, the `walletMainUtxo` components must point to the +recent main UTXO of the given wallet, as currently known on the +Ethereum chain. If the wallet has no main UTXO, this parameter +can be empty as it is ignored since the wallet balance is +assumed to be zero, +- Wallet must be in Live state. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| walletPubKeyHash | bytes20 | 20-byte public key hash of the wallet. | +| walletMainUtxo | struct BitcoinTx.UTXO | Data of the wallet's main UTXO, as currently known on the Ethereum chain. | + +### notifyWalletClosingPeriodElapsed + +```solidity +function notifyWalletClosingPeriodElapsed(bytes20 walletPubKeyHash) external +``` + +Notifies about the end of the closing period for the given wallet. +Closes the wallet ultimately and notifies the ECDSA registry +about this fact. + +Requirements: +- The wallet must be in the Closing state, +- The wallet closing period must have elapsed. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| walletPubKeyHash | bytes20 | 20-byte public key hash of the wallet. | + +### submitFraudChallenge + +```solidity +function submitFraudChallenge(bytes walletPublicKey, bytes preimageSha256, struct BitcoinTx.RSVSignature signature) external payable +``` + +Submits a fraud challenge indicating that a UTXO being under +wallet control was unlocked by the wallet but was not used +according to the protocol rules. That means the wallet signed +a transaction input pointing to that UTXO and there is a unique +sighash and signature pair associated with that input. This +function uses those parameters to create a fraud accusation that +proves a given transaction input unlocking the given UTXO was +actually signed by the wallet. This function cannot determine +whether the transaction was actually broadcast and the input was +consumed in a fraudulent way so it just opens a challenge period +during which the wallet can defeat the challenge by submitting +proof of a transaction that consumes the given input according +to protocol rules. To prevent spurious allegations, the caller +must deposit ETH that is returned back upon justified fraud +challenge or confiscated otherwise. + +Requirements: +- Wallet behind `walletPublicKey` must be in Live or MovingFunds +or Closing state, +- The challenger must send appropriate amount of ETH used as +fraud challenge deposit, +- The signature (represented by r, s and v) must be generated by +the wallet behind `walletPubKey` during signing of `sighash` +which was calculated from `preimageSha256`, +- Wallet can be challenged for the given signature only once. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| walletPublicKey | bytes | The public key of the wallet in the uncompressed and unprefixed format (64 bytes). | +| preimageSha256 | bytes | The hash that was generated by applying SHA-256 one time over the preimage used during input signing. The preimage is a serialized subset of the transaction and its structure depends on the transaction input (see BIP-143 for reference). Notice that applying SHA-256 over the `preimageSha256` results in `sighash`. The path from `preimage` to `sighash` looks like this: preimage -> (SHA-256) -> preimageSha256 -> (SHA-256) -> sighash. | +| signature | struct BitcoinTx.RSVSignature | Bitcoin signature in the R/S/V format. | + +### defeatFraudChallenge + +```solidity +function defeatFraudChallenge(bytes walletPublicKey, bytes preimage, bool witness) external +``` + +Allows to defeat a pending fraud challenge against a wallet if +the transaction that spends the UTXO follows the protocol rules. +In order to defeat the challenge the same `walletPublicKey` and +signature (represented by `r`, `s` and `v`) must be provided as +were used to calculate the sighash during input signing. +The fraud challenge defeat attempt will only succeed if the +inputs in the preimage are considered honestly spent by the +wallet. Therefore the transaction spending the UTXO must be +proven in the Bridge before a challenge defeat is called. +If successfully defeated, the fraud challenge is marked as +resolved and the amount of ether deposited by the challenger is +sent to the treasury. + +Requirements: +- `walletPublicKey` and `sighash` calculated as `hash256(preimage)` +must identify an open fraud challenge, +- the preimage must be a valid preimage of a transaction generated +according to the protocol rules and already proved in the Bridge, +- before a defeat attempt is made the transaction that spends the +given UTXO must be proven in the Bridge. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| walletPublicKey | bytes | The public key of the wallet in the uncompressed and unprefixed format (64 bytes). | +| preimage | bytes | The preimage which produces sighash used to generate the ECDSA signature that is the subject of the fraud claim. It is a serialized subset of the transaction. The exact subset used as the preimage depends on the transaction input the signature is produced for. See BIP-143 for reference. | +| witness | bool | Flag indicating whether the preimage was produced for a witness input. True for witness, false for non-witness input. | + +### defeatFraudChallengeWithHeartbeat + +```solidity +function defeatFraudChallengeWithHeartbeat(bytes walletPublicKey, bytes heartbeatMessage) external +``` + +Allows to defeat a pending fraud challenge against a wallet by +proving the sighash and signature were produced for an off-chain +wallet heartbeat message following a strict format. +In order to defeat the challenge the same `walletPublicKey` and +signature (represented by `r`, `s` and `v`) must be provided as +were used to calculate the sighash during heartbeat message +signing. The fraud challenge defeat attempt will only succeed if +the signed message follows a strict format required for +heartbeat messages. If successfully defeated, the fraud +challenge is marked as resolved and the amount of ether +deposited by the challenger is sent to the treasury. + +Requirements: +- `walletPublicKey` and `sighash` calculated as +`hash256(heartbeatMessage)` must identify an open fraud challenge, +- `heartbeatMessage` must follow a strict format of heartbeat +messages. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| walletPublicKey | bytes | The public key of the wallet in the uncompressed and unprefixed format (64 bytes). | +| heartbeatMessage | bytes | Off-chain heartbeat message meeting the heartbeat message format requirements which produces sighash used to generate the ECDSA signature that is the subject of the fraud claim. | + +### notifyFraudChallengeDefeatTimeout + +```solidity +function notifyFraudChallengeDefeatTimeout(bytes walletPublicKey, uint32[] walletMembersIDs, bytes preimageSha256) external +``` + +Notifies about defeat timeout for the given fraud challenge. +Can be called only if there was a fraud challenge identified by +the provided `walletPublicKey` and `sighash` and it was not +defeated on time. The amount of time that needs to pass after +a fraud challenge is reported is indicated by the +`challengeDefeatTimeout`. After a successful fraud challenge +defeat timeout notification the fraud challenge is marked as +resolved, the stake of each operator is slashed, the ether +deposited is returned to the challenger and the challenger is +rewarded. + +Requirements: +- The wallet must be in the Live or MovingFunds or Closing or +Terminated state, +- The `walletPublicKey` and `sighash` calculated from +`preimageSha256` must identify an open fraud challenge, +- 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 of the `WalletRegistry` contract, +- The amount of time indicated by `challengeDefeatTimeout` must pass +after the challenge was reported. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| walletPublicKey | bytes | The public key of the wallet in the uncompressed and unprefixed format (64 bytes). | +| walletMembersIDs | uint32[] | Identifiers of the wallet signing group members. | +| preimageSha256 | bytes | The hash that was generated by applying SHA-256 one time over the preimage used during input signing. The preimage is a serialized subset of the transaction and its structure depends on the transaction input (see BIP-143 for reference). Notice that applying SHA-256 over the `preimageSha256` results in `sighash`. The path from `preimage` to `sighash` looks like this: preimage -> (SHA-256) -> preimageSha256 -> (SHA-256) -> sighash. | + +### setVaultStatus + +```solidity +function setVaultStatus(address vault, bool isTrusted) external +``` + +Allows the Governance to mark the given vault address as trusted +or no longer trusted. Vaults are not trusted by default. +Trusted vault must meet the following criteria: +- `IVault.receiveBalanceIncrease` must have a known, low gas +cost, +- `IVault.receiveBalanceIncrease` must never revert. + +Without restricting reveal only to trusted vaults, malicious +vaults not meeting the criteria would be able to nuke sweep proof +transactions executed by ECDSA wallet with deposits routed to +them. +Can only be called by the Governance. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| vault | address | The address of the vault. | +| isTrusted | bool | flag indicating whether the vault is trusted or not. | + +### setSpvMaintainerStatus + +```solidity +function setSpvMaintainerStatus(address spvMaintainer, bool isTrusted) external +``` + +Allows the Governance to mark the given address as trusted +or no longer trusted SPV maintainer. Addresses are not trusted +as SPV maintainers by default. + +The SPV proof does not check whether the transaction is a part of +the Bitcoin mainnet, it only checks whether the transaction has been +mined performing the required amount of work as on Bitcoin mainnet. +The possibility of submitting SPV proofs is limited to trusted SPV +maintainers. The system expects transaction confirmations with the +required work accumulated, so trusted SPV maintainers can not prove +the transaction without providing the required Bitcoin proof of work. +Trusted maintainers address the issue of an economic game between +tBTC and Bitcoin mainnet where large Bitcoin mining pools can decide +to use their hash power to mine fake Bitcoin blocks to prove them in +tBTC instead of receiving Bitcoin miner rewards. +Can only be called by the Governance. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| spvMaintainer | address | The address of the SPV maintainer. | +| isTrusted | bool | flag indicating whether the address is trusted or not. | + +### updateDepositParameters + +```solidity +function updateDepositParameters(uint64 depositDustThreshold, uint64 depositTreasuryFeeDivisor, uint64 depositTxMaxFee, uint32 depositRevealAheadPeriod) external +``` + +of `depositTreasuryFeeDivisor` and `depositTxMaxFee` parameters +in order to make requests that can incur the treasury and +transaction fee and still satisfy the depositor. + +Requirements: +- Deposit dust threshold must be greater than zero, +- Deposit dust threshold must be greater than deposit TX max fee, +- Deposit transaction max fee must be greater than zero. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| depositDustThreshold | uint64 | | +| depositTreasuryFeeDivisor | uint64 | New value of the treasury fee divisor. It is the divisor used to compute the treasury fee taken from each deposit and transferred to the treasury upon sweep proof submission. That fee is computed as follows: `treasuryFee = depositedAmount / depositTreasuryFeeDivisor` For example, if the treasury fee needs to be 2% of each deposit, the `depositTreasuryFeeDivisor` should be set to `50` because `1/50 = 0.02 = 2%`. | +| depositTxMaxFee | uint64 | New value of the deposit tx max fee in satoshis. It is the maximum amount of BTC transaction fee that can be incurred by each swept deposit being part of the given sweep transaction. If the maximum BTC transaction fee is exceeded, such transaction is considered a fraud. | +| depositRevealAheadPeriod | uint32 | New value of the deposit reveal ahead period parameter in seconds. It defines the length of the period that must be preserved between the deposit reveal time and the deposit refund locktime. | + +### updateRedemptionParameters + +```solidity +function updateRedemptionParameters(uint64 redemptionDustThreshold, uint64 redemptionTreasuryFeeDivisor, uint64 redemptionTxMaxFee, uint64 redemptionTxMaxTotalFee, uint32 redemptionTimeout, uint96 redemptionTimeoutSlashingAmount, uint32 redemptionTimeoutNotifierRewardMultiplier) external +``` + +Updates parameters of redemptions. + +Requirements: +- Redemption dust threshold must be greater than moving funds dust +threshold, +- Redemption dust threshold must be greater than the redemption TX +max fee, +- Redemption transaction max fee must be greater than zero, +- Redemption transaction max total fee must be greater than or +equal to the redemption transaction per-request max fee, +- Redemption timeout must be greater than zero, +- Redemption timeout notifier reward multiplier must be in the +range [0, 100]. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| redemptionDustThreshold | uint64 | New value of the redemption dust threshold in satoshis. It is the minimal amount that can be requested for redemption. Value of this parameter must take into account the value of `redemptionTreasuryFeeDivisor` and `redemptionTxMaxFee` parameters in order to make requests that can incur the treasury and transaction fee and still satisfy the redeemer. | +| redemptionTreasuryFeeDivisor | uint64 | New value of the redemption treasury fee divisor. It is the divisor used to compute the treasury fee taken from each redemption request and transferred to the treasury upon successful request finalization. That fee is computed as follows: `treasuryFee = requestedAmount / redemptionTreasuryFeeDivisor` For example, if the treasury fee needs to be 2% of each redemption request, the `redemptionTreasuryFeeDivisor` should be set to `50` because `1/50 = 0.02 = 2%`. | +| redemptionTxMaxFee | uint64 | New value of the redemption transaction max fee in satoshis. It is the maximum amount of BTC transaction fee that can be incurred by each redemption request being part of the given redemption transaction. If the maximum BTC transaction fee is exceeded, such transaction is considered a fraud. This is a per-redemption output max fee for the redemption transaction. | +| redemptionTxMaxTotalFee | uint64 | New value of the redemption transaction max total fee in satoshis. It is the maximum amount of the total BTC transaction fee that is acceptable in a single redemption transaction. This is a _total_ max fee for the entire redemption transaction. | +| redemptionTimeout | uint32 | New value of the redemption timeout in seconds. It is the time after which the redemption request can be reported as timed out. It is counted from the moment when the redemption request was created via `requestRedemption` call. Reported timed out requests are cancelled and locked balance is returned to the redeemer in full amount. | +| redemptionTimeoutSlashingAmount | uint96 | New value of the redemption timeout slashing amount in T, it is the amount slashed from each wallet member for redemption timeout. | +| redemptionTimeoutNotifierRewardMultiplier | uint32 | New value of the redemption timeout notifier reward multiplier as percentage, it determines the percentage of the notifier reward from the staking contact the notifier of a redemption timeout receives. The value must be in the range [0, 100]. | + +### updateMovingFundsParameters + +```solidity +function updateMovingFundsParameters(uint64 movingFundsTxMaxTotalFee, uint64 movingFundsDustThreshold, uint32 movingFundsTimeoutResetDelay, uint32 movingFundsTimeout, uint96 movingFundsTimeoutSlashingAmount, uint32 movingFundsTimeoutNotifierRewardMultiplier, uint16 movingFundsCommitmentGasOffset, uint64 movedFundsSweepTxMaxTotalFee, uint32 movedFundsSweepTimeout, uint96 movedFundsSweepTimeoutSlashingAmount, uint32 movedFundsSweepTimeoutNotifierRewardMultiplier) external +``` + +Updates parameters of moving funds. + +Requirements: +- Moving funds transaction max total fee must be greater than zero, +- Moving funds dust threshold must be greater than zero and lower +than the redemption dust threshold, +- Moving funds timeout reset delay must be greater than zero, +- Moving funds timeout must be greater than the moving funds +timeout reset delay, +- Moving funds timeout notifier reward multiplier must be in the +range [0, 100], +- Moved funds sweep transaction max total fee must be greater than zero, +- Moved funds sweep timeout must be greater than zero, +- Moved funds sweep timeout notifier reward multiplier must be in the +range [0, 100]. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| movingFundsTxMaxTotalFee | uint64 | New value of the moving funds transaction max total fee in satoshis. It is the maximum amount of the total BTC transaction fee that is acceptable in a single moving funds transaction. This is a _total_ max fee for the entire moving funds transaction. | +| movingFundsDustThreshold | uint64 | New value of the moving funds dust threshold. It is the minimal satoshi amount that makes sense to be transferred during the moving funds process. Moving funds wallets having their BTC balance below that value can begin closing immediately as transferring such a low value may not be possible due to BTC network fees. | +| movingFundsTimeoutResetDelay | uint32 | New value of the moving funds timeout reset delay in seconds. It is the time after which the moving funds timeout can be reset in case the target wallet commitment cannot be submitted due to a lack of live wallets in the system. It is counted from the moment when the wallet was requested to move their funds and switched to the MovingFunds state or from the moment the timeout was reset the last time. | +| movingFundsTimeout | uint32 | New value of the moving funds timeout in seconds. It is the time after which the moving funds process can be reported as timed out. It is counted from the moment when the wallet was requested to move their funds and switched to the MovingFunds state. | +| movingFundsTimeoutSlashingAmount | uint96 | New value of the moving funds timeout slashing amount in T, it is the amount slashed from each wallet member for moving funds timeout. | +| movingFundsTimeoutNotifierRewardMultiplier | uint32 | New value of the moving funds timeout notifier reward multiplier as percentage, it determines the percentage of the notifier reward from the staking contact the notifier of a moving funds timeout receives. The value must be in the range [0, 100]. | +| movingFundsCommitmentGasOffset | uint16 | New value of the gas offset for moving funds target wallet commitment transaction gas costs reimbursement. | +| movedFundsSweepTxMaxTotalFee | uint64 | New value of the moved funds sweep transaction max total fee in satoshis. It is the maximum amount of the total BTC transaction fee that is acceptable in a single moved funds sweep transaction. This is a _total_ max fee for the entire moved funds sweep transaction. | +| movedFundsSweepTimeout | uint32 | New value of the moved funds sweep timeout in seconds. It is the time after which the moved funds sweep process can be reported as timed out. It is counted from the moment when the wallet was requested to sweep the received funds. | +| movedFundsSweepTimeoutSlashingAmount | uint96 | New value of the moved funds sweep timeout slashing amount in T, it is the amount slashed from each wallet member for moved funds sweep timeout. | +| movedFundsSweepTimeoutNotifierRewardMultiplier | uint32 | New value of the moved funds sweep timeout notifier reward multiplier as percentage, it determines the percentage of the notifier reward from the staking contact the notifier of a moved funds sweep timeout receives. The value must be in the range [0, 100]. | + +### updateWalletParameters + +```solidity +function updateWalletParameters(uint32 walletCreationPeriod, uint64 walletCreationMinBtcBalance, uint64 walletCreationMaxBtcBalance, uint64 walletClosureMinBtcBalance, uint32 walletMaxAge, uint64 walletMaxBtcTransfer, uint32 walletClosingPeriod) external +``` + +Requirements: +- Wallet maximum BTC balance must be greater than the wallet +minimum BTC balance, +- Wallet maximum BTC transfer must be greater than zero, +- Wallet closing period must be greater than zero. + +### updateFraudParameters + +```solidity +function updateFraudParameters(uint96 fraudChallengeDepositAmount, uint32 fraudChallengeDefeatTimeout, uint96 fraudSlashingAmount, uint32 fraudNotifierRewardMultiplier) external +``` + +Updates parameters related to frauds. + +Requirements: +- Fraud challenge defeat timeout must be greater than 0, +- Fraud notifier reward multiplier must be in the range [0, 100]. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| fraudChallengeDepositAmount | uint96 | New value of the fraud challenge deposit amount in wei, it is the amount of ETH the party challenging the wallet for fraud needs to deposit. | +| fraudChallengeDefeatTimeout | uint32 | New value of the challenge defeat timeout in seconds, it is the amount of time the wallet has to defeat a fraud challenge. The value must be greater than zero. | +| fraudSlashingAmount | uint96 | New value of the fraud slashing amount in T, it is the amount slashed from each wallet member for committing a fraud. | +| fraudNotifierRewardMultiplier | uint32 | New value of the fraud notifier reward multiplier as percentage, it determines the percentage of the notifier reward from the staking contact the notifier of a fraud receives. The value must be in the range [0, 100]. | + +### updateTreasury + +```solidity +function updateTreasury(address treasury) external +``` + +Updates treasury address. The treasury receives the system fees. + +The treasury address must not be 0x0. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| treasury | address | New value of the treasury address. | + +### deposits + +```solidity +function deposits(uint256 depositKey) external view returns (struct Deposit.DepositRequest) +``` + +Collection of all revealed deposits indexed by +keccak256(fundingTxHash | fundingOutputIndex). +The fundingTxHash is bytes32 (ordered as in Bitcoin internally) +and fundingOutputIndex an uint32. This mapping may contain valid +and invalid deposits and the wallet is responsible for +validating them before attempting to execute a sweep. + +### pendingRedemptions + +```solidity +function pendingRedemptions(uint256 redemptionKey) external view returns (struct Redemption.RedemptionRequest) +``` + +Collection of all pending redemption requests indexed by +redemption key built as +`keccak256(keccak256(redeemerOutputScript) | walletPubKeyHash)`. +The walletPubKeyHash is the 20-byte wallet's public key hash +(computed using Bitcoin HASH160 over the compressed ECDSA +public key) and `redeemerOutputScript` is a Bitcoin script +(P2PKH, P2WPKH, P2SH or P2WSH) that will be used to lock +redeemed BTC as requested by the redeemer. Requests are added +to this mapping by the `requestRedemption` method (duplicates +not allowed) and are removed by one of the following methods: +- `submitRedemptionProof` in case the request was handled +successfully, +- `notifyRedemptionTimeout` in case the request was reported +to be timed out. + +### timedOutRedemptions + +```solidity +function timedOutRedemptions(uint256 redemptionKey) external view returns (struct Redemption.RedemptionRequest) +``` + +Collection of all timed out redemptions requests indexed by +redemption key built as +`keccak256(keccak256(redeemerOutputScript) | walletPubKeyHash)`. +The walletPubKeyHash is the 20-byte wallet's public key hash +(computed using Bitcoin HASH160 over the compressed ECDSA +public key) and `redeemerOutputScript` is the Bitcoin script +(P2PKH, P2WPKH, P2SH or P2WSH) that is involved in the timed +out request. +Only one method can add to this mapping: +- `notifyRedemptionTimeout` which puts the redemption key +to this mapping based on a timed out request stored +previously in `pendingRedemptions` mapping. +Only one method can remove entries from this mapping: +- `submitRedemptionProof` in case the timed out redemption +request was a part of the proven transaction. + +### spentMainUTXOs + +```solidity +function spentMainUTXOs(uint256 utxoKey) external view returns (bool) +``` + +Collection of main UTXOs that are honestly spent indexed by +keccak256(fundingTxHash | fundingOutputIndex). The fundingTxHash +is bytes32 (ordered as in Bitcoin internally) and +fundingOutputIndex an uint32. A main UTXO is considered honestly +spent if it was used as an input of a transaction that have been +proven in the Bridge. + +### wallets + +```solidity +function wallets(bytes20 walletPubKeyHash) external view returns (struct Wallets.Wallet) +``` + +Gets details about a registered wallet. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| walletPubKeyHash | bytes20 | The 20-byte wallet public key hash (computed using Bitcoin HASH160 over the compressed ECDSA public key). | + +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +| [0] | struct Wallets.Wallet | Wallet details. | + +### activeWalletPubKeyHash + +```solidity +function activeWalletPubKeyHash() external view returns (bytes20) +``` + +Gets the public key hash of the active wallet. + +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +| [0] | bytes20 | The 20-byte public key hash (computed using Bitcoin HASH160 over the compressed ECDSA public key) of the active wallet. Returns bytes20(0) if there is no active wallet at the moment. | + +### liveWalletsCount + +```solidity +function liveWalletsCount() external view returns (uint32) +``` + +Gets the live wallets count. + +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +| [0] | uint32 | The current count of wallets being in the Live state. | + +### fraudChallenges + +```solidity +function fraudChallenges(uint256 challengeKey) external view returns (struct Fraud.FraudChallenge) +``` + +Returns the fraud challenge identified by the given key built +as keccak256(walletPublicKey|sighash). + +### movedFundsSweepRequests + +```solidity +function movedFundsSweepRequests(uint256 requestKey) external view returns (struct MovingFunds.MovedFundsSweepRequest) +``` + +Collection of all moved funds sweep requests indexed by +`keccak256(movingFundsTxHash | movingFundsOutputIndex)`. +The `movingFundsTxHash` is `bytes32` (ordered as in Bitcoin +internally) and `movingFundsOutputIndex` an `uint32`. Each entry +is actually an UTXO representing the moved funds and is supposed +to be swept with the current main UTXO of the recipient wallet. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| requestKey | uint256 | Request key built as `keccak256(movingFundsTxHash | movingFundsOutputIndex)`. | + +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +| [0] | struct MovingFunds.MovedFundsSweepRequest | Details of the moved funds sweep request. | + +### isVaultTrusted + +```solidity +function isVaultTrusted(address vault) external view returns (bool) +``` + +Indicates if the vault with the given address is trusted or not. +Depositors can route their revealed deposits only to trusted +vaults and have trusted vaults notified about new deposits as +soon as these deposits get swept. Vaults not trusted by the +Bridge can still be used by Bank balance owners on their own +responsibility - anyone can approve their Bank balance to any +address. + +### depositParameters + +```solidity +function depositParameters() external view returns (uint64 depositDustThreshold, uint64 depositTreasuryFeeDivisor, uint64 depositTxMaxFee, uint32 depositRevealAheadPeriod) +``` + +Returns the current values of Bridge deposit parameters. + +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +| depositDustThreshold | uint64 | The minimal amount that can be requested to deposit. Value of this parameter must take into account the value of `depositTreasuryFeeDivisor` and `depositTxMaxFee` parameters in order to make requests that can incur the treasury and transaction fee and still satisfy the depositor. | +| depositTreasuryFeeDivisor | uint64 | Divisor used to compute the treasury fee taken from each deposit and transferred to the treasury upon sweep proof submission. That fee is computed as follows: `treasuryFee = depositedAmount / depositTreasuryFeeDivisor` For example, if the treasury fee needs to be 2% of each deposit, the `depositTreasuryFeeDivisor` should be set to `50` because `1/50 = 0.02 = 2%`. | +| depositTxMaxFee | uint64 | Maximum amount of BTC transaction fee that can be incurred by each swept deposit being part of the given sweep transaction. If the maximum BTC transaction fee is exceeded, such transaction is considered a fraud. | +| depositRevealAheadPeriod | uint32 | Defines the length of the period that must be preserved between the deposit reveal time and the deposit refund locktime. For example, if the deposit become refundable on August 1st, and the ahead period is 7 days, the latest moment for deposit reveal is July 25th. Value in seconds. | + +### redemptionParameters + +```solidity +function redemptionParameters() external view returns (uint64 redemptionDustThreshold, uint64 redemptionTreasuryFeeDivisor, uint64 redemptionTxMaxFee, uint64 redemptionTxMaxTotalFee, uint32 redemptionTimeout, uint96 redemptionTimeoutSlashingAmount, uint32 redemptionTimeoutNotifierRewardMultiplier) +``` + +Returns the current values of Bridge redemption parameters. + +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +| redemptionDustThreshold | uint64 | The minimal amount that can be requested for redemption. Value of this parameter must take into account the value of `redemptionTreasuryFeeDivisor` and `redemptionTxMaxFee` parameters in order to make requests that can incur the treasury and transaction fee and still satisfy the redeemer. | +| redemptionTreasuryFeeDivisor | uint64 | Divisor used to compute the treasury fee taken from each redemption request and transferred to the treasury upon successful request finalization. That fee is computed as follows: `treasuryFee = requestedAmount / redemptionTreasuryFeeDivisor` For example, if the treasury fee needs to be 2% of each redemption request, the `redemptionTreasuryFeeDivisor` should be set to `50` because `1/50 = 0.02 = 2%`. | +| redemptionTxMaxFee | uint64 | Maximum amount of BTC transaction fee that can be incurred by each redemption request being part of the given redemption transaction. If the maximum BTC transaction fee is exceeded, such transaction is considered a fraud. This is a per-redemption output max fee for the redemption transaction. | +| redemptionTxMaxTotalFee | uint64 | Maximum amount of the total BTC transaction fee that is acceptable in a single redemption transaction. This is a _total_ max fee for the entire redemption transaction. | +| redemptionTimeout | uint32 | Time after which the redemption request can be reported as timed out. It is counted from the moment when the redemption request was created via `requestRedemption` call. Reported timed out requests are cancelled and locked balance is returned to the redeemer in full amount. | +| redemptionTimeoutSlashingAmount | uint96 | The amount of stake slashed from each member of a wallet for a redemption timeout. | +| redemptionTimeoutNotifierRewardMultiplier | uint32 | The percentage of the notifier reward from the staking contract the notifier of a redemption timeout receives. The value is in the range [0, 100]. | + +### movingFundsParameters + +```solidity +function movingFundsParameters() external view returns (uint64 movingFundsTxMaxTotalFee, uint64 movingFundsDustThreshold, uint32 movingFundsTimeoutResetDelay, uint32 movingFundsTimeout, uint96 movingFundsTimeoutSlashingAmount, uint32 movingFundsTimeoutNotifierRewardMultiplier, uint16 movingFundsCommitmentGasOffset, uint64 movedFundsSweepTxMaxTotalFee, uint32 movedFundsSweepTimeout, uint96 movedFundsSweepTimeoutSlashingAmount, uint32 movedFundsSweepTimeoutNotifierRewardMultiplier) +``` + +Returns the current values of Bridge moving funds between +wallets parameters. + +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +| movingFundsTxMaxTotalFee | uint64 | Maximum amount of the total BTC transaction fee that is acceptable in a single moving funds transaction. This is a _total_ max fee for the entire moving funds transaction. | +| movingFundsDustThreshold | uint64 | The minimal satoshi amount that makes sense to be transferred during the moving funds process. Moving funds wallets having their BTC balance below that value can begin closing immediately as transferring such a low value may not be possible due to BTC network fees. | +| movingFundsTimeoutResetDelay | uint32 | Time after which the moving funds timeout can be reset in case the target wallet commitment cannot be submitted due to a lack of live wallets in the system. It is counted from the moment when the wallet was requested to move their funds and switched to the MovingFunds state or from the moment the timeout was reset the last time. Value in seconds This value should be lower than the value of the `movingFundsTimeout`. | +| movingFundsTimeout | uint32 | Time after which the moving funds process can be reported as timed out. It is counted from the moment when the wallet was requested to move their funds and switched to the MovingFunds state. Value in seconds. | +| movingFundsTimeoutSlashingAmount | uint96 | The amount of stake slashed from each member of a wallet for a moving funds timeout. | +| movingFundsTimeoutNotifierRewardMultiplier | uint32 | The percentage of the notifier reward from the staking contract the notifier of a moving funds timeout receives. The value is in the range [0, 100]. | +| movingFundsCommitmentGasOffset | uint16 | The gas offset used for the moving funds target wallet commitment transaction cost reimbursement. | +| movedFundsSweepTxMaxTotalFee | uint64 | Maximum amount of the total BTC transaction fee that is acceptable in a single moved funds sweep transaction. This is a _total_ max fee for the entire moved funds sweep transaction. | +| movedFundsSweepTimeout | uint32 | Time after which the moved funds sweep process can be reported as timed out. It is counted from the moment when the wallet was requested to sweep the received funds. Value in seconds. | +| movedFundsSweepTimeoutSlashingAmount | uint96 | The amount of stake slashed from each member of a wallet for a moved funds sweep timeout. | +| movedFundsSweepTimeoutNotifierRewardMultiplier | uint32 | The percentage of the notifier reward from the staking contract the notifier of a moved funds sweep timeout receives. The value is in the range [0, 100]. | + +### walletParameters + +```solidity +function walletParameters() external view returns (uint32 walletCreationPeriod, uint64 walletCreationMinBtcBalance, uint64 walletCreationMaxBtcBalance, uint64 walletClosureMinBtcBalance, uint32 walletMaxAge, uint64 walletMaxBtcTransfer, uint32 walletClosingPeriod) +``` + +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +| walletCreationPeriod | uint32 | Determines how frequently a new wallet creation can be requested. Value in seconds. | +| walletCreationMinBtcBalance | uint64 | The minimum BTC threshold in satoshi that is used to decide about wallet creation. | +| walletCreationMaxBtcBalance | uint64 | The maximum BTC threshold in satoshi that is used to decide about wallet creation. | +| walletClosureMinBtcBalance | uint64 | The minimum BTC threshold in satoshi that is used to decide about wallet closure. | +| walletMaxAge | uint32 | The maximum age of a wallet in seconds, after which the wallet moving funds process can be requested. | +| walletMaxBtcTransfer | uint64 | The maximum BTC amount in satoshi than can be transferred to a single target wallet during the moving funds process. | +| walletClosingPeriod | uint32 | Determines the length of the wallet closing period, i.e. the period when the wallet remains in the Closing state and can be subject of deposit fraud challenges. Value in seconds. | + +### fraudParameters + +```solidity +function fraudParameters() external view returns (uint96 fraudChallengeDepositAmount, uint32 fraudChallengeDefeatTimeout, uint96 fraudSlashingAmount, uint32 fraudNotifierRewardMultiplier) +``` + +Returns the current values of Bridge fraud parameters. + +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +| fraudChallengeDepositAmount | uint96 | The amount of ETH in wei the party challenging the wallet for fraud needs to deposit. | +| fraudChallengeDefeatTimeout | uint32 | The amount of time the wallet has to defeat a fraud challenge. | +| fraudSlashingAmount | uint96 | The amount slashed from each wallet member for committing a fraud. | +| fraudNotifierRewardMultiplier | uint32 | The percentage of the notifier reward from the staking contract the notifier of a fraud receives. The value is in the range [0, 100]. | + +### contractReferences + +```solidity +function contractReferences() external view returns (contract Bank bank, contract IRelay relay, contract IWalletRegistry ecdsaWalletRegistry, contract ReimbursementPool reimbursementPool) +``` + +Returns the addresses of contracts Bridge is interacting with. + +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +| bank | contract Bank | Address of the Bank the Bridge belongs to. | +| relay | contract IRelay | Address of the Bitcoin relay providing the current Bitcoin network difficulty. | +| ecdsaWalletRegistry | contract IWalletRegistry | Address of the ECDSA Wallet Registry. | +| reimbursementPool | contract ReimbursementPool | Address of the Reimbursement Pool. | + +### treasury + +```solidity +function treasury() external view returns (address) +``` + +Address where the deposit treasury fees will be sent to. +Treasury takes part in the operators rewarding process. + +### txProofDifficultyFactor + +```solidity +function txProofDifficultyFactor() external view returns (uint256) +``` + +The number of confirmations on the Bitcoin chain required to +successfully evaluate an SPV proof. + diff --git a/docs/app-development/tbtc-v2/tbtc-v2-api/generated-docs/bridge/BridgeGovernance.md b/docs/app-development/tbtc-v2/tbtc-v2-api/generated-docs/bridge/BridgeGovernance.md new file mode 100644 index 0000000..8146516 --- /dev/null +++ b/docs/app-development/tbtc-v2/tbtc-v2-api/generated-docs/bridge/BridgeGovernance.md @@ -0,0 +1,1519 @@ +# Solidity API + +## BridgeGovernance + +Owns the `Bridge` contract and is responsible for updating +its governable parameters in respect to governance delay individual +for each parameter. The other responsibility is marking a vault +address as trusted or no longer trusted. + +### depositData + +```solidity +struct BridgeGovernanceParameters.DepositData depositData +``` + +### redemptionData + +```solidity +struct BridgeGovernanceParameters.RedemptionData redemptionData +``` + +### movingFundsData + +```solidity +struct BridgeGovernanceParameters.MovingFundsData movingFundsData +``` + +### walletData + +```solidity +struct BridgeGovernanceParameters.WalletData walletData +``` + +### fraudData + +```solidity +struct BridgeGovernanceParameters.FraudData fraudData +``` + +### treasuryData + +```solidity +struct BridgeGovernanceParameters.TreasuryData treasuryData +``` + +### bridge + +```solidity +contract Bridge bridge +``` + +### governanceDelays + +```solidity +uint256[3] governanceDelays +``` + +### bridgeGovernanceTransferChangeInitiated + +```solidity +uint256 bridgeGovernanceTransferChangeInitiated +``` + +### newBridgeGovernance + +```solidity +address newBridgeGovernance +``` + +### BridgeGovernanceTransferStarted + +```solidity +event BridgeGovernanceTransferStarted(address newBridgeGovernance, uint256 timestamp) +``` + +### DepositDustThresholdUpdateStarted + +```solidity +event DepositDustThresholdUpdateStarted(uint64 newDepositDustThreshold, uint256 timestamp) +``` + +### DepositDustThresholdUpdated + +```solidity +event DepositDustThresholdUpdated(uint64 depositDustThreshold) +``` + +### DepositTreasuryFeeDivisorUpdateStarted + +```solidity +event DepositTreasuryFeeDivisorUpdateStarted(uint64 depositTreasuryFeeDivisor, uint256 timestamp) +``` + +### DepositTreasuryFeeDivisorUpdated + +```solidity +event DepositTreasuryFeeDivisorUpdated(uint64 depositTreasuryFeeDivisor) +``` + +### DepositTxMaxFeeUpdateStarted + +```solidity +event DepositTxMaxFeeUpdateStarted(uint64 newDepositTxMaxFee, uint256 timestamp) +``` + +### DepositTxMaxFeeUpdated + +```solidity +event DepositTxMaxFeeUpdated(uint64 depositTxMaxFee) +``` + +### DepositRevealAheadPeriodUpdateStarted + +```solidity +event DepositRevealAheadPeriodUpdateStarted(uint32 newDepositRevealAheadPeriod, uint256 timestamp) +``` + +### DepositRevealAheadPeriodUpdated + +```solidity +event DepositRevealAheadPeriodUpdated(uint32 depositRevealAheadPeriod) +``` + +### RedemptionDustThresholdUpdateStarted + +```solidity +event RedemptionDustThresholdUpdateStarted(uint64 newRedemptionDustThreshold, uint256 timestamp) +``` + +### RedemptionDustThresholdUpdated + +```solidity +event RedemptionDustThresholdUpdated(uint64 redemptionDustThreshold) +``` + +### RedemptionTreasuryFeeDivisorUpdateStarted + +```solidity +event RedemptionTreasuryFeeDivisorUpdateStarted(uint64 newRedemptionTreasuryFeeDivisor, uint256 timestamp) +``` + +### RedemptionTreasuryFeeDivisorUpdated + +```solidity +event RedemptionTreasuryFeeDivisorUpdated(uint64 redemptionTreasuryFeeDivisor) +``` + +### RedemptionTxMaxFeeUpdateStarted + +```solidity +event RedemptionTxMaxFeeUpdateStarted(uint64 newRedemptionTxMaxFee, uint256 timestamp) +``` + +### RedemptionTxMaxFeeUpdated + +```solidity +event RedemptionTxMaxFeeUpdated(uint64 redemptionTxMaxFee) +``` + +### RedemptionTxMaxTotalFeeUpdateStarted + +```solidity +event RedemptionTxMaxTotalFeeUpdateStarted(uint64 newRedemptionTxMaxTotalFee, uint256 timestamp) +``` + +### RedemptionTxMaxTotalFeeUpdated + +```solidity +event RedemptionTxMaxTotalFeeUpdated(uint64 redemptionTxMaxTotalFee) +``` + +### RedemptionTimeoutUpdateStarted + +```solidity +event RedemptionTimeoutUpdateStarted(uint32 newRedemptionTimeout, uint256 timestamp) +``` + +### RedemptionTimeoutUpdated + +```solidity +event RedemptionTimeoutUpdated(uint32 redemptionTimeout) +``` + +### RedemptionTimeoutSlashingAmountUpdateStarted + +```solidity +event RedemptionTimeoutSlashingAmountUpdateStarted(uint96 newRedemptionTimeoutSlashingAmount, uint256 timestamp) +``` + +### RedemptionTimeoutSlashingAmountUpdated + +```solidity +event RedemptionTimeoutSlashingAmountUpdated(uint96 redemptionTimeoutSlashingAmount) +``` + +### RedemptionTimeoutNotifierRewardMultiplierUpdateStarted + +```solidity +event RedemptionTimeoutNotifierRewardMultiplierUpdateStarted(uint32 newRedemptionTimeoutNotifierRewardMultiplier, uint256 timestamp) +``` + +### RedemptionTimeoutNotifierRewardMultiplierUpdated + +```solidity +event RedemptionTimeoutNotifierRewardMultiplierUpdated(uint32 redemptionTimeoutNotifierRewardMultiplier) +``` + +### MovingFundsTxMaxTotalFeeUpdateStarted + +```solidity +event MovingFundsTxMaxTotalFeeUpdateStarted(uint64 newMovingFundsTxMaxTotalFee, uint256 timestamp) +``` + +### MovingFundsTxMaxTotalFeeUpdated + +```solidity +event MovingFundsTxMaxTotalFeeUpdated(uint64 movingFundsTxMaxTotalFee) +``` + +### MovingFundsDustThresholdUpdateStarted + +```solidity +event MovingFundsDustThresholdUpdateStarted(uint64 newMovingFundsDustThreshold, uint256 timestamp) +``` + +### MovingFundsDustThresholdUpdated + +```solidity +event MovingFundsDustThresholdUpdated(uint64 movingFundsDustThreshold) +``` + +### MovingFundsTimeoutResetDelayUpdateStarted + +```solidity +event MovingFundsTimeoutResetDelayUpdateStarted(uint32 newMovingFundsTimeoutResetDelay, uint256 timestamp) +``` + +### MovingFundsTimeoutResetDelayUpdated + +```solidity +event MovingFundsTimeoutResetDelayUpdated(uint32 movingFundsTimeoutResetDelay) +``` + +### MovingFundsTimeoutUpdateStarted + +```solidity +event MovingFundsTimeoutUpdateStarted(uint32 newMovingFundsTimeout, uint256 timestamp) +``` + +### MovingFundsTimeoutUpdated + +```solidity +event MovingFundsTimeoutUpdated(uint32 movingFundsTimeout) +``` + +### MovingFundsTimeoutSlashingAmountUpdateStarted + +```solidity +event MovingFundsTimeoutSlashingAmountUpdateStarted(uint96 newMovingFundsTimeoutSlashingAmount, uint256 timestamp) +``` + +### MovingFundsTimeoutSlashingAmountUpdated + +```solidity +event MovingFundsTimeoutSlashingAmountUpdated(uint96 movingFundsTimeoutSlashingAmount) +``` + +### MovingFundsTimeoutNotifierRewardMultiplierUpdateStarted + +```solidity +event MovingFundsTimeoutNotifierRewardMultiplierUpdateStarted(uint32 newMovingFundsTimeoutNotifierRewardMultiplier, uint256 timestamp) +``` + +### MovingFundsTimeoutNotifierRewardMultiplierUpdated + +```solidity +event MovingFundsTimeoutNotifierRewardMultiplierUpdated(uint32 movingFundsTimeoutNotifierRewardMultiplier) +``` + +### MovingFundsCommitmentGasOffsetUpdateStarted + +```solidity +event MovingFundsCommitmentGasOffsetUpdateStarted(uint16 newMovingFundsCommitmentGasOffset, uint256 timestamp) +``` + +### MovingFundsCommitmentGasOffsetUpdated + +```solidity +event MovingFundsCommitmentGasOffsetUpdated(uint16 movingFundsCommitmentGasOffset) +``` + +### MovedFundsSweepTxMaxTotalFeeUpdateStarted + +```solidity +event MovedFundsSweepTxMaxTotalFeeUpdateStarted(uint64 newMovedFundsSweepTxMaxTotalFee, uint256 timestamp) +``` + +### MovedFundsSweepTxMaxTotalFeeUpdated + +```solidity +event MovedFundsSweepTxMaxTotalFeeUpdated(uint64 movedFundsSweepTxMaxTotalFee) +``` + +### MovedFundsSweepTimeoutUpdateStarted + +```solidity +event MovedFundsSweepTimeoutUpdateStarted(uint32 newMovedFundsSweepTimeout, uint256 timestamp) +``` + +### MovedFundsSweepTimeoutUpdated + +```solidity +event MovedFundsSweepTimeoutUpdated(uint32 movedFundsSweepTimeout) +``` + +### MovedFundsSweepTimeoutSlashingAmountUpdateStarted + +```solidity +event MovedFundsSweepTimeoutSlashingAmountUpdateStarted(uint96 newMovedFundsSweepTimeoutSlashingAmount, uint256 timestamp) +``` + +### MovedFundsSweepTimeoutSlashingAmountUpdated + +```solidity +event MovedFundsSweepTimeoutSlashingAmountUpdated(uint96 movedFundsSweepTimeoutSlashingAmount) +``` + +### MovedFundsSweepTimeoutNotifierRewardMultiplierUpdateStarted + +```solidity +event MovedFundsSweepTimeoutNotifierRewardMultiplierUpdateStarted(uint32 newMovedFundsSweepTimeoutNotifierRewardMultiplier, uint256 timestamp) +``` + +### MovedFundsSweepTimeoutNotifierRewardMultiplierUpdated + +```solidity +event MovedFundsSweepTimeoutNotifierRewardMultiplierUpdated(uint32 movedFundsSweepTimeoutNotifierRewardMultiplier) +``` + +### WalletCreationPeriodUpdateStarted + +```solidity +event WalletCreationPeriodUpdateStarted(uint32 newWalletCreationPeriod, uint256 timestamp) +``` + +### WalletCreationPeriodUpdated + +```solidity +event WalletCreationPeriodUpdated(uint32 walletCreationPeriod) +``` + +### WalletCreationMinBtcBalanceUpdateStarted + +```solidity +event WalletCreationMinBtcBalanceUpdateStarted(uint64 newWalletCreationMinBtcBalance, uint256 timestamp) +``` + +### WalletCreationMinBtcBalanceUpdated + +```solidity +event WalletCreationMinBtcBalanceUpdated(uint64 walletCreationMinBtcBalance) +``` + +### WalletCreationMaxBtcBalanceUpdateStarted + +```solidity +event WalletCreationMaxBtcBalanceUpdateStarted(uint64 newWalletCreationMaxBtcBalance, uint256 timestamp) +``` + +### WalletCreationMaxBtcBalanceUpdated + +```solidity +event WalletCreationMaxBtcBalanceUpdated(uint64 walletCreationMaxBtcBalance) +``` + +### WalletClosureMinBtcBalanceUpdateStarted + +```solidity +event WalletClosureMinBtcBalanceUpdateStarted(uint64 newWalletClosureMinBtcBalance, uint256 timestamp) +``` + +### WalletClosureMinBtcBalanceUpdated + +```solidity +event WalletClosureMinBtcBalanceUpdated(uint64 walletClosureMinBtcBalance) +``` + +### WalletMaxAgeUpdateStarted + +```solidity +event WalletMaxAgeUpdateStarted(uint32 newWalletMaxAge, uint256 timestamp) +``` + +### WalletMaxAgeUpdated + +```solidity +event WalletMaxAgeUpdated(uint32 walletMaxAge) +``` + +### WalletMaxBtcTransferUpdateStarted + +```solidity +event WalletMaxBtcTransferUpdateStarted(uint64 newWalletMaxBtcTransfer, uint256 timestamp) +``` + +### WalletMaxBtcTransferUpdated + +```solidity +event WalletMaxBtcTransferUpdated(uint64 walletMaxBtcTransfer) +``` + +### WalletClosingPeriodUpdateStarted + +```solidity +event WalletClosingPeriodUpdateStarted(uint32 newWalletClosingPeriod, uint256 timestamp) +``` + +### WalletClosingPeriodUpdated + +```solidity +event WalletClosingPeriodUpdated(uint32 walletClosingPeriod) +``` + +### FraudChallengeDepositAmountUpdateStarted + +```solidity +event FraudChallengeDepositAmountUpdateStarted(uint96 newFraudChallengeDepositAmount, uint256 timestamp) +``` + +### FraudChallengeDepositAmountUpdated + +```solidity +event FraudChallengeDepositAmountUpdated(uint96 fraudChallengeDepositAmount) +``` + +### FraudChallengeDefeatTimeoutUpdateStarted + +```solidity +event FraudChallengeDefeatTimeoutUpdateStarted(uint32 newFraudChallengeDefeatTimeout, uint256 timestamp) +``` + +### FraudChallengeDefeatTimeoutUpdated + +```solidity +event FraudChallengeDefeatTimeoutUpdated(uint32 fraudChallengeDefeatTimeout) +``` + +### FraudSlashingAmountUpdateStarted + +```solidity +event FraudSlashingAmountUpdateStarted(uint96 newFraudSlashingAmount, uint256 timestamp) +``` + +### FraudSlashingAmountUpdated + +```solidity +event FraudSlashingAmountUpdated(uint96 fraudSlashingAmount) +``` + +### FraudNotifierRewardMultiplierUpdateStarted + +```solidity +event FraudNotifierRewardMultiplierUpdateStarted(uint32 newFraudNotifierRewardMultiplier, uint256 timestamp) +``` + +### FraudNotifierRewardMultiplierUpdated + +```solidity +event FraudNotifierRewardMultiplierUpdated(uint32 fraudNotifierRewardMultiplier) +``` + +### TreasuryUpdateStarted + +```solidity +event TreasuryUpdateStarted(address newTreasury, uint256 timestamp) +``` + +### TreasuryUpdated + +```solidity +event TreasuryUpdated(address treasury) +``` + +### constructor + +```solidity +constructor(contract Bridge _bridge, uint256 _governanceDelay) public +``` + +### setVaultStatus + +```solidity +function setVaultStatus(address vault, bool isTrusted) external +``` + +Allows the Governance to mark the given vault address as trusted +or no longer trusted. Vaults are not trusted by default. +Trusted vault must meet the following criteria: +- `IVault.receiveBalanceIncrease` must have a known, low gas +cost, +- `IVault.receiveBalanceIncrease` must never revert. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| vault | address | The address of the vault. | +| isTrusted | bool | flag indicating whether the vault is trusted or not. | + +### setSpvMaintainerStatus + +```solidity +function setSpvMaintainerStatus(address spvMaintainer, bool isTrusted) external +``` + +Allows the Governance to mark the given address as trusted +or no longer trusted SPV maintainer. Addresses are not trusted +as SPV maintainers by default. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| spvMaintainer | address | The address of the SPV maintainer. | +| isTrusted | bool | flag indicating whether the address is trusted or not. | + +### beginGovernanceDelayUpdate + +```solidity +function beginGovernanceDelayUpdate(uint256 _newGovernanceDelay) external +``` + +Begins the governance delay update process. + +Can be called only by the contract owner. The event that informs about +the start of the governance delay was skipped on purpose to trim +the contract size. All the params inside of the `governanceDelays` +array are public and can be easily fetched. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| _newGovernanceDelay | uint256 | New governance delay | + +### finalizeGovernanceDelayUpdate + +```solidity +function finalizeGovernanceDelayUpdate() external +``` + +Finalizes the governance delay update process. + +Can be called only by the contract owner, after the governance +delay elapses. Updated event was skipped on purpose to trim the +contract size. All the params inside of the `governanceDelays` +array are public and can be easily fetched. + +### beginBridgeGovernanceTransfer + +```solidity +function beginBridgeGovernanceTransfer(address _newBridgeGovernance) external +``` + +Begins the Bridge governance transfer process. + +Can be called only by the contract owner. It is the governance +responsibility to validate the correctness of the new Bridge +Governance contract. The other reason for not adding this check is +to go down with the contract size and leaving only the essential code. + +### finalizeBridgeGovernanceTransfer + +```solidity +function finalizeBridgeGovernanceTransfer() external +``` + +Finalizes the bridge governance transfer process. + +Can be called only by the contract owner, after the governance +delay elapses. Bridge governance transferred event can be read +from the Governable bridge contract 'GovernanceTransferred(old, new)'. +Event that informs about the transfer in this function is skipped on +purpose to go down with the contract size. + +### beginDepositDustThresholdUpdate + +```solidity +function beginDepositDustThresholdUpdate(uint64 _newDepositDustThreshold) external +``` + +Begins the deposit dust threshold amount update process. + +Can be called only by the contract owner. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| _newDepositDustThreshold | uint64 | New deposit dust threshold amount. | + +### finalizeDepositDustThresholdUpdate + +```solidity +function finalizeDepositDustThresholdUpdate() external +``` + +Finalizes the deposit dust threshold amount update process. + +Can be called only by the contract owner, after the governance +delay elapses. + +### beginDepositTreasuryFeeDivisorUpdate + +```solidity +function beginDepositTreasuryFeeDivisorUpdate(uint64 _newDepositTreasuryFeeDivisor) external +``` + +Begins the deposit treasury fee divisor amount update process. + +Can be called only by the contract owner. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| _newDepositTreasuryFeeDivisor | uint64 | New deposit treasury fee divisor. | + +### finalizeDepositTreasuryFeeDivisorUpdate + +```solidity +function finalizeDepositTreasuryFeeDivisorUpdate() external +``` + +Finalizes the deposit treasury fee divisor amount update process. + +Can be called only by the contract owner, after the governance +delay elapses. + +### beginDepositTxMaxFeeUpdate + +```solidity +function beginDepositTxMaxFeeUpdate(uint64 _newDepositTxMaxFee) external +``` + +Begins the deposit tx max fee amount update process. + +Can be called only by the contract owner. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| _newDepositTxMaxFee | uint64 | New deposit tx max fee. | + +### finalizeDepositTxMaxFeeUpdate + +```solidity +function finalizeDepositTxMaxFeeUpdate() external +``` + +Finalizes the deposit tx max fee amount update process. + +Can be called only by the contract owner, after the governance +delay elapses. + +### beginDepositRevealAheadPeriodUpdate + +```solidity +function beginDepositRevealAheadPeriodUpdate(uint32 _newDepositRevealAheadPeriod) external +``` + +Begins the deposit reveal ahead period update process. + +Can be called only by the contract owner. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| _newDepositRevealAheadPeriod | uint32 | New deposit reveal ahead period. | + +### finalizeDepositRevealAheadPeriodUpdate + +```solidity +function finalizeDepositRevealAheadPeriodUpdate() external +``` + +Finalizes the deposit reveal ahead period update process. + +Can be called only by the contract owner, after the governance +delay elapses. + +### beginRedemptionDustThresholdUpdate + +```solidity +function beginRedemptionDustThresholdUpdate(uint64 _newRedemptionDustThreshold) external +``` + +Begins the redemption dust threshold amount update process. + +Can be called only by the contract owner. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| _newRedemptionDustThreshold | uint64 | New redemption dust threshold. | + +### finalizeRedemptionDustThresholdUpdate + +```solidity +function finalizeRedemptionDustThresholdUpdate() external +``` + +Finalizes the dust threshold amount update process. + +Can be called only by the contract owner, after the governance +delay elapses. + +### beginRedemptionTreasuryFeeDivisorUpdate + +```solidity +function beginRedemptionTreasuryFeeDivisorUpdate(uint64 _newRedemptionTreasuryFeeDivisor) external +``` + +Begins the redemption treasury fee divisor amount update process. + +Can be called only by the contract owner. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| _newRedemptionTreasuryFeeDivisor | uint64 | New redemption treasury fee divisor. | + +### finalizeRedemptionTreasuryFeeDivisorUpdate + +```solidity +function finalizeRedemptionTreasuryFeeDivisorUpdate() external +``` + +Finalizes the redemption treasury fee divisor amount update process. + +Can be called only by the contract owner, after the governance +delay elapses. + +### beginRedemptionTxMaxFeeUpdate + +```solidity +function beginRedemptionTxMaxFeeUpdate(uint64 _newRedemptionTxMaxFee) external +``` + +Begins the redemption tx max fee amount update process. + +Can be called only by the contract owner. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| _newRedemptionTxMaxFee | uint64 | New redemption tx max fee. | + +### finalizeRedemptionTxMaxFeeUpdate + +```solidity +function finalizeRedemptionTxMaxFeeUpdate() external +``` + +Finalizes the redemption tx max fee amount update process. + +Can be called only by the contract owner, after the governance +delay elapses. + +### beginRedemptionTxMaxTotalFeeUpdate + +```solidity +function beginRedemptionTxMaxTotalFeeUpdate(uint64 _newRedemptionTxMaxTotalFee) external +``` + +Begins the redemption tx max total fee amount update process. + +Can be called only by the contract owner. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| _newRedemptionTxMaxTotalFee | uint64 | New redemption tx max total fee. | + +### finalizeRedemptionTxMaxTotalFeeUpdate + +```solidity +function finalizeRedemptionTxMaxTotalFeeUpdate() external +``` + +Finalizes the redemption tx max total fee amount update process. + +Can be called only by the contract owner, after the governance +delay elapses. + +### beginRedemptionTimeoutUpdate + +```solidity +function beginRedemptionTimeoutUpdate(uint32 _newRedemptionTimeout) external +``` + +Begins the redemption timeout amount update process. + +Can be called only by the contract owner. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| _newRedemptionTimeout | uint32 | New redemption timeout. | + +### finalizeRedemptionTimeoutUpdate + +```solidity +function finalizeRedemptionTimeoutUpdate() external +``` + +Finalizes the redemption timeout amount update process. + +Can be called only by the contract owner, after the governance +delay elapses. + +### beginRedemptionTimeoutSlashingAmountUpdate + +```solidity +function beginRedemptionTimeoutSlashingAmountUpdate(uint96 _newRedemptionTimeoutSlashingAmount) external +``` + +Begins the redemption timeout slashing amount update process. + +Can be called only by the contract owner. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| _newRedemptionTimeoutSlashingAmount | uint96 | New redemption timeout slashing amount. | + +### finalizeRedemptionTimeoutSlashingAmountUpdate + +```solidity +function finalizeRedemptionTimeoutSlashingAmountUpdate() external +``` + +Finalizes the redemption timeout slashing amount update process. + +Can be called only by the contract owner, after the governance +delay elapses. + +### beginRedemptionTimeoutNotifierRewardMultiplierUpdate + +```solidity +function beginRedemptionTimeoutNotifierRewardMultiplierUpdate(uint32 _newRedemptionTimeoutNotifierRewardMultiplier) external +``` + +Begins the redemption timeout notifier reward multiplier amount +update process. + +Can be called only by the contract owner. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| _newRedemptionTimeoutNotifierRewardMultiplier | uint32 | New redemption timeout notifier reward multiplier. | + +### finalizeRedemptionTimeoutNotifierRewardMultiplierUpdate + +```solidity +function finalizeRedemptionTimeoutNotifierRewardMultiplierUpdate() external +``` + +Finalizes the redemption timeout notifier reward multiplier amount +update process. + +Can be called only by the contract owner, after the governance +delay elapses. + +### beginMovingFundsTxMaxTotalFeeUpdate + +```solidity +function beginMovingFundsTxMaxTotalFeeUpdate(uint64 _newMovingFundsTxMaxTotalFee) external +``` + +Begins the moving funds tx max total fee update process. + +Can be called only by the contract owner. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| _newMovingFundsTxMaxTotalFee | uint64 | New moving funds tx max total fee. | + +### finalizeMovingFundsTxMaxTotalFeeUpdate + +```solidity +function finalizeMovingFundsTxMaxTotalFeeUpdate() external +``` + +Finalizes the moving funds tx max total fee update process. + +Can be called only by the contract owner, after the governance +delay elapses. + +### beginMovingFundsDustThresholdUpdate + +```solidity +function beginMovingFundsDustThresholdUpdate(uint64 _newMovingFundsDustThreshold) external +``` + +Begins the moving funds dust threshold update process. + +Can be called only by the contract owner. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| _newMovingFundsDustThreshold | uint64 | New moving funds dust threshold. | + +### finalizeMovingFundsDustThresholdUpdate + +```solidity +function finalizeMovingFundsDustThresholdUpdate() external +``` + +Finalizes the moving funds dust threshold update process. + +Can be called only by the contract owner, after the governance +delay elapses. + +### beginMovingFundsTimeoutResetDelayUpdate + +```solidity +function beginMovingFundsTimeoutResetDelayUpdate(uint32 _newMovingFundsTimeoutResetDelay) external +``` + +Begins the moving funds timeout reset delay update process. + +Can be called only by the contract owner. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| _newMovingFundsTimeoutResetDelay | uint32 | New moving funds timeout reset delay. | + +### finalizeMovingFundsTimeoutResetDelayUpdate + +```solidity +function finalizeMovingFundsTimeoutResetDelayUpdate() external +``` + +Finalizes the moving funds timeout reset delay update process. + +Can be called only by the contract owner, after the governance +delay elapses. + +### beginMovingFundsTimeoutUpdate + +```solidity +function beginMovingFundsTimeoutUpdate(uint32 _newMovingFundsTimeout) external +``` + +Begins the moving funds timeout update process. + +Can be called only by the contract owner. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| _newMovingFundsTimeout | uint32 | New moving funds timeout. | + +### finalizeMovingFundsTimeoutUpdate + +```solidity +function finalizeMovingFundsTimeoutUpdate() external +``` + +Finalizes the moving funds timeout update process. + +Can be called only by the contract owner, after the governance +delay elapses. + +### beginMovingFundsTimeoutSlashingAmountUpdate + +```solidity +function beginMovingFundsTimeoutSlashingAmountUpdate(uint96 _newMovingFundsTimeoutSlashingAmount) external +``` + +Begins the moving funds timeout slashing amount update process. + +Can be called only by the contract owner. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| _newMovingFundsTimeoutSlashingAmount | uint96 | New moving funds timeout slashing amount. | + +### finalizeMovingFundsTimeoutSlashingAmountUpdate + +```solidity +function finalizeMovingFundsTimeoutSlashingAmountUpdate() external +``` + +Finalizes the moving funds timeout slashing amount update process. + +Can be called only by the contract owner, after the governance +delay elapses. + +### beginMovingFundsTimeoutNotifierRewardMultiplierUpdate + +```solidity +function beginMovingFundsTimeoutNotifierRewardMultiplierUpdate(uint32 _newMovingFundsTimeoutNotifierRewardMultiplier) external +``` + +Begins the moving funds timeout notifier reward multiplier update +process. + +Can be called only by the contract owner. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| _newMovingFundsTimeoutNotifierRewardMultiplier | uint32 | New moving funds timeout notifier reward multiplier. | + +### finalizeMovingFundsTimeoutNotifierRewardMultiplierUpdate + +```solidity +function finalizeMovingFundsTimeoutNotifierRewardMultiplierUpdate() external +``` + +Finalizes the moving funds timeout notifier reward multiplier +update process. + +Can be called only by the contract owner, after the governance +delay elapses. + +### beginMovingFundsCommitmentGasOffsetUpdate + +```solidity +function beginMovingFundsCommitmentGasOffsetUpdate(uint16 _newMovingFundsCommitmentGasOffset) external +``` + +Begins the moving funds commitment gas offset update process. + +Can be called only by the contract owner. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| _newMovingFundsCommitmentGasOffset | uint16 | New moving funds commitment gas offset. | + +### finalizeMovingFundsCommitmentGasOffsetUpdate + +```solidity +function finalizeMovingFundsCommitmentGasOffsetUpdate() external +``` + +Finalizes the moving funds commitment gas offset update process. + +Can be called only by the contract owner, after the governance +delay elapses. + +### beginMovedFundsSweepTxMaxTotalFeeUpdate + +```solidity +function beginMovedFundsSweepTxMaxTotalFeeUpdate(uint64 _newMovedFundsSweepTxMaxTotalFee) external +``` + +Begins the moved funds sweep tx max total fee update process. + +Can be called only by the contract owner. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| _newMovedFundsSweepTxMaxTotalFee | uint64 | New moved funds sweep tx max total fee. | + +### finalizeMovedFundsSweepTxMaxTotalFeeUpdate + +```solidity +function finalizeMovedFundsSweepTxMaxTotalFeeUpdate() external +``` + +Finalizes the moved funds sweep tx max total fee update process. + +Can be called only by the contract owner, after the governance +delay elapses. + +### beginMovedFundsSweepTimeoutUpdate + +```solidity +function beginMovedFundsSweepTimeoutUpdate(uint32 _newMovedFundsSweepTimeout) external +``` + +Begins the moved funds sweep timeout update process. + +Can be called only by the contract owner. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| _newMovedFundsSweepTimeout | uint32 | New moved funds sweep timeout. | + +### finalizeMovedFundsSweepTimeoutUpdate + +```solidity +function finalizeMovedFundsSweepTimeoutUpdate() external +``` + +Finalizes the moved funds sweep timeout update process. + +Can be called only by the contract owner, after the governance +delay elapses. + +### beginMovedFundsSweepTimeoutSlashingAmountUpdate + +```solidity +function beginMovedFundsSweepTimeoutSlashingAmountUpdate(uint96 _newMovedFundsSweepTimeoutSlashingAmount) external +``` + +Begins the moved funds sweep timeout slashing amount update process. + +Can be called only by the contract owner. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| _newMovedFundsSweepTimeoutSlashingAmount | uint96 | New moved funds sweep timeout slashing amount. | + +### finalizeMovedFundsSweepTimeoutSlashingAmountUpdate + +```solidity +function finalizeMovedFundsSweepTimeoutSlashingAmountUpdate() external +``` + +Finalizes the moved funds sweep timeout slashing amount update +process. + +Can be called only by the contract owner, after the governance +delay elapses. + +### beginMovedFundsSweepTimeoutNotifierRewardMultiplierUpdate + +```solidity +function beginMovedFundsSweepTimeoutNotifierRewardMultiplierUpdate(uint32 _newMovedFundsSweepTimeoutNotifierRewardMultiplier) external +``` + +Begins the moved funds sweep timeout notifier reward multiplier +update process. + +Can be called only by the contract owner. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| _newMovedFundsSweepTimeoutNotifierRewardMultiplier | uint32 | New moved funds sweep timeout notifier reward multiplier. | + +### finalizeMovedFundsSweepTimeoutNotifierRewardMultiplierUpdate + +```solidity +function finalizeMovedFundsSweepTimeoutNotifierRewardMultiplierUpdate() external +``` + +Finalizes the moved funds sweep timeout notifier reward multiplier +update process. + +Can be called only by the contract owner, after the governance +delay elapses. + +### beginWalletCreationPeriodUpdate + +```solidity +function beginWalletCreationPeriodUpdate(uint32 _newWalletCreationPeriod) external +``` + +Begins the wallet creation period update process. + +Can be called only by the contract owner. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| _newWalletCreationPeriod | uint32 | New wallet creation period. | + +### finalizeWalletCreationPeriodUpdate + +```solidity +function finalizeWalletCreationPeriodUpdate() external +``` + +Finalizes the wallet creation period update process. + +Can be called only by the contract owner, after the governance +delay elapses. + +### beginWalletCreationMinBtcBalanceUpdate + +```solidity +function beginWalletCreationMinBtcBalanceUpdate(uint64 _newWalletCreationMinBtcBalance) external +``` + +Begins the wallet creation min btc balance update process. + +Can be called only by the contract owner. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| _newWalletCreationMinBtcBalance | uint64 | New wallet creation min btc balance. | + +### finalizeWalletCreationMinBtcBalanceUpdate + +```solidity +function finalizeWalletCreationMinBtcBalanceUpdate() external +``` + +Finalizes the wallet creation min btc balance update process. + +Can be called only by the contract owner, after the governance +delay elapses. + +### beginWalletCreationMaxBtcBalanceUpdate + +```solidity +function beginWalletCreationMaxBtcBalanceUpdate(uint64 _newWalletCreationMaxBtcBalance) external +``` + +Begins the wallet creation max btc balance update process. + +Can be called only by the contract owner. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| _newWalletCreationMaxBtcBalance | uint64 | New wallet creation max btc balance. | + +### finalizeWalletCreationMaxBtcBalanceUpdate + +```solidity +function finalizeWalletCreationMaxBtcBalanceUpdate() external +``` + +Finalizes the wallet creation max btc balance update process. + +Can be called only by the contract owner, after the governance +delay elapses. + +### beginWalletClosureMinBtcBalanceUpdate + +```solidity +function beginWalletClosureMinBtcBalanceUpdate(uint64 _newWalletClosureMinBtcBalance) external +``` + +Begins the wallet closure min btc balance update process. + +Can be called only by the contract owner. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| _newWalletClosureMinBtcBalance | uint64 | New wallet closure min btc balance. | + +### finalizeWalletClosureMinBtcBalanceUpdate + +```solidity +function finalizeWalletClosureMinBtcBalanceUpdate() external +``` + +Finalizes the wallet closure min btc balance update process. + +Can be called only by the contract owner, after the governance +delay elapses. + +### beginWalletMaxAgeUpdate + +```solidity +function beginWalletMaxAgeUpdate(uint32 _newWalletMaxAge) external +``` + +Begins the wallet max age update process. + +Can be called only by the contract owner. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| _newWalletMaxAge | uint32 | New wallet max age. | + +### finalizeWalletMaxAgeUpdate + +```solidity +function finalizeWalletMaxAgeUpdate() external +``` + +Finalizes the wallet max age update process. + +Can be called only by the contract owner, after the governance +delay elapses. + +### beginWalletMaxBtcTransferUpdate + +```solidity +function beginWalletMaxBtcTransferUpdate(uint64 _newWalletMaxBtcTransfer) external +``` + +Begins the wallet max btc transfer amount update process. + +Can be called only by the contract owner. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| _newWalletMaxBtcTransfer | uint64 | New wallet max btc transfer. | + +### finalizeWalletMaxBtcTransferUpdate + +```solidity +function finalizeWalletMaxBtcTransferUpdate() external +``` + +Finalizes the wallet max btc transfer amount update process. + +Can be called only by the contract owner, after the governance +delay elapses. + +### beginWalletClosingPeriodUpdate + +```solidity +function beginWalletClosingPeriodUpdate(uint32 _newWalletClosingPeriod) external +``` + +Begins the wallet closing period update process. + +Can be called only by the contract owner. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| _newWalletClosingPeriod | uint32 | New wallet closing period. | + +### finalizeWalletClosingPeriodUpdate + +```solidity +function finalizeWalletClosingPeriodUpdate() external +``` + +Finalizes the wallet closing period update process. + +Can be called only by the contract owner, after the governance +delay elapses. + +### beginFraudChallengeDepositAmountUpdate + +```solidity +function beginFraudChallengeDepositAmountUpdate(uint96 _newFraudChallengeDepositAmount) external +``` + +Begins the fraud challenge deposit amount update process. + +Can be called only by the contract owner. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| _newFraudChallengeDepositAmount | uint96 | New fraud challenge deposit amount. | + +### finalizeFraudChallengeDepositAmountUpdate + +```solidity +function finalizeFraudChallengeDepositAmountUpdate() external +``` + +Finalizes the fraud challenge deposit amount update process. + +Can be called only by the contract owner, after the governance +delay elapses. + +### beginFraudChallengeDefeatTimeoutUpdate + +```solidity +function beginFraudChallengeDefeatTimeoutUpdate(uint32 _newFraudChallengeDefeatTimeout) external +``` + +Begins the fraud challenge defeat timeout update process. + +Can be called only by the contract owner. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| _newFraudChallengeDefeatTimeout | uint32 | New fraud challenge defeat timeout. | + +### finalizeFraudChallengeDefeatTimeoutUpdate + +```solidity +function finalizeFraudChallengeDefeatTimeoutUpdate() external +``` + +Finalizes the fraud challenge defeat timeout update process. + +Can be called only by the contract owner, after the governance +delay elapses. + +### beginFraudSlashingAmountUpdate + +```solidity +function beginFraudSlashingAmountUpdate(uint96 _newFraudSlashingAmount) external +``` + +Begins the fraud slashing amount update process. + +Can be called only by the contract owner. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| _newFraudSlashingAmount | uint96 | New fraud slashing amount. | + +### finalizeFraudSlashingAmountUpdate + +```solidity +function finalizeFraudSlashingAmountUpdate() external +``` + +Finalizes the fraud slashing amount update process. + +Can be called only by the contract owner, after the governance +delay elapses. + +### beginFraudNotifierRewardMultiplierUpdate + +```solidity +function beginFraudNotifierRewardMultiplierUpdate(uint32 _newFraudNotifierRewardMultiplier) external +``` + +Begins the fraud notifier reward multiplier update process. + +Can be called only by the contract owner. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| _newFraudNotifierRewardMultiplier | uint32 | New fraud notifier reward multiplier. | + +### finalizeFraudNotifierRewardMultiplierUpdate + +```solidity +function finalizeFraudNotifierRewardMultiplierUpdate() external +``` + +Finalizes the fraud notifier reward multiplier update process. + +Can be called only by the contract owner, after the governance +delay elapses. + +### beginTreasuryUpdate + +```solidity +function beginTreasuryUpdate(address _newTreasury) external +``` + +Begins the treasury address update process. + +Can be called only by the contract owner. It does not perform +any parameter validation. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| _newTreasury | address | New treasury address. | + +### finalizeTreasuryUpdate + +```solidity +function finalizeTreasuryUpdate() external +``` + +Finalizes the treasury address update process. + +Can be called only by the contract owner, after the governance +delay elapses. + +### governanceDelay + +```solidity +function governanceDelay() internal view returns (uint256) +``` + +Gets the governance delay parameter. + diff --git a/docs/app-development/tbtc-v2/tbtc-v2-api/generated-docs/bridge/BridgeGovernanceParameters.md b/docs/app-development/tbtc-v2/tbtc-v2-api/generated-docs/bridge/BridgeGovernanceParameters.md new file mode 100644 index 0000000..c5762fa --- /dev/null +++ b/docs/app-development/tbtc-v2/tbtc-v2-api/generated-docs/bridge/BridgeGovernanceParameters.md @@ -0,0 +1,1398 @@ +# Solidity API + +## BridgeGovernanceParameters + +### TreasuryData + +```solidity +struct TreasuryData { + address newTreasury; + uint256 treasuryChangeInitiated; +} +``` + +### DepositData + +```solidity +struct DepositData { + uint64 newDepositDustThreshold; + uint256 depositDustThresholdChangeInitiated; + uint64 newDepositTreasuryFeeDivisor; + uint256 depositTreasuryFeeDivisorChangeInitiated; + uint64 newDepositTxMaxFee; + uint256 depositTxMaxFeeChangeInitiated; + uint32 newDepositRevealAheadPeriod; + uint256 depositRevealAheadPeriodChangeInitiated; +} +``` + +### RedemptionData + +```solidity +struct RedemptionData { + uint64 newRedemptionDustThreshold; + uint256 redemptionDustThresholdChangeInitiated; + uint64 newRedemptionTreasuryFeeDivisor; + uint256 redemptionTreasuryFeeDivisorChangeInitiated; + uint64 newRedemptionTxMaxFee; + uint256 redemptionTxMaxFeeChangeInitiated; + uint64 newRedemptionTxMaxTotalFee; + uint256 redemptionTxMaxTotalFeeChangeInitiated; + uint32 newRedemptionTimeout; + uint256 redemptionTimeoutChangeInitiated; + uint96 newRedemptionTimeoutSlashingAmount; + uint256 redemptionTimeoutSlashingAmountChangeInitiated; + uint32 newRedemptionTimeoutNotifierRewardMultiplier; + uint256 redemptionTimeoutNotifierRewardMultiplierChangeInitiated; +} +``` + +### MovingFundsData + +```solidity +struct MovingFundsData { + uint64 newMovingFundsTxMaxTotalFee; + uint256 movingFundsTxMaxTotalFeeChangeInitiated; + uint64 newMovingFundsDustThreshold; + uint256 movingFundsDustThresholdChangeInitiated; + uint32 newMovingFundsTimeoutResetDelay; + uint256 movingFundsTimeoutResetDelayChangeInitiated; + uint32 newMovingFundsTimeout; + uint256 movingFundsTimeoutChangeInitiated; + uint96 newMovingFundsTimeoutSlashingAmount; + uint256 movingFundsTimeoutSlashingAmountChangeInitiated; + uint32 newMovingFundsTimeoutNotifierRewardMultiplier; + uint256 movingFundsTimeoutNotifierRewardMultiplierChangeInitiated; + uint16 newMovingFundsCommitmentGasOffset; + uint256 movingFundsCommitmentGasOffsetChangeInitiated; + uint64 newMovedFundsSweepTxMaxTotalFee; + uint256 movedFundsSweepTxMaxTotalFeeChangeInitiated; + uint32 newMovedFundsSweepTimeout; + uint256 movedFundsSweepTimeoutChangeInitiated; + uint96 newMovedFundsSweepTimeoutSlashingAmount; + uint256 movedFundsSweepTimeoutSlashingAmountChangeInitiated; + uint32 newMovedFundsSweepTimeoutNotifierRewardMultiplier; + uint256 movedFundsSweepTimeoutNotifierRewardMultiplierChangeInitiated; +} +``` + +### WalletData + +```solidity +struct WalletData { + uint32 newWalletCreationPeriod; + uint256 walletCreationPeriodChangeInitiated; + uint64 newWalletCreationMinBtcBalance; + uint256 walletCreationMinBtcBalanceChangeInitiated; + uint64 newWalletCreationMaxBtcBalance; + uint256 walletCreationMaxBtcBalanceChangeInitiated; + uint64 newWalletClosureMinBtcBalance; + uint256 walletClosureMinBtcBalanceChangeInitiated; + uint32 newWalletMaxAge; + uint256 walletMaxAgeChangeInitiated; + uint64 newWalletMaxBtcTransfer; + uint256 walletMaxBtcTransferChangeInitiated; + uint32 newWalletClosingPeriod; + uint256 walletClosingPeriodChangeInitiated; +} +``` + +### FraudData + +```solidity +struct FraudData { + uint96 newFraudChallengeDepositAmount; + uint256 fraudChallengeDepositAmountChangeInitiated; + uint32 newFraudChallengeDefeatTimeout; + uint256 fraudChallengeDefeatTimeoutChangeInitiated; + uint96 newFraudSlashingAmount; + uint256 fraudSlashingAmountChangeInitiated; + uint32 newFraudNotifierRewardMultiplier; + uint256 fraudNotifierRewardMultiplierChangeInitiated; +} +``` + +### DepositDustThresholdUpdateStarted + +```solidity +event DepositDustThresholdUpdateStarted(uint64 newDepositDustThreshold, uint256 timestamp) +``` + +### DepositDustThresholdUpdated + +```solidity +event DepositDustThresholdUpdated(uint64 depositDustThreshold) +``` + +### DepositTreasuryFeeDivisorUpdateStarted + +```solidity +event DepositTreasuryFeeDivisorUpdateStarted(uint64 depositTreasuryFeeDivisor, uint256 timestamp) +``` + +### DepositTreasuryFeeDivisorUpdated + +```solidity +event DepositTreasuryFeeDivisorUpdated(uint64 depositTreasuryFeeDivisor) +``` + +### DepositTxMaxFeeUpdateStarted + +```solidity +event DepositTxMaxFeeUpdateStarted(uint64 newDepositTxMaxFee, uint256 timestamp) +``` + +### DepositTxMaxFeeUpdated + +```solidity +event DepositTxMaxFeeUpdated(uint64 depositTxMaxFee) +``` + +### DepositRevealAheadPeriodUpdateStarted + +```solidity +event DepositRevealAheadPeriodUpdateStarted(uint32 newDepositRevealAheadPeriod, uint256 timestamp) +``` + +### DepositRevealAheadPeriodUpdated + +```solidity +event DepositRevealAheadPeriodUpdated(uint32 depositRevealAheadPeriod) +``` + +### RedemptionDustThresholdUpdateStarted + +```solidity +event RedemptionDustThresholdUpdateStarted(uint64 newRedemptionDustThreshold, uint256 timestamp) +``` + +### RedemptionDustThresholdUpdated + +```solidity +event RedemptionDustThresholdUpdated(uint64 redemptionDustThreshold) +``` + +### RedemptionTreasuryFeeDivisorUpdateStarted + +```solidity +event RedemptionTreasuryFeeDivisorUpdateStarted(uint64 newRedemptionTreasuryFeeDivisor, uint256 timestamp) +``` + +### RedemptionTreasuryFeeDivisorUpdated + +```solidity +event RedemptionTreasuryFeeDivisorUpdated(uint64 redemptionTreasuryFeeDivisor) +``` + +### RedemptionTxMaxFeeUpdateStarted + +```solidity +event RedemptionTxMaxFeeUpdateStarted(uint64 newRedemptionTxMaxFee, uint256 timestamp) +``` + +### RedemptionTxMaxFeeUpdated + +```solidity +event RedemptionTxMaxFeeUpdated(uint64 redemptionTxMaxFee) +``` + +### RedemptionTxMaxTotalFeeUpdateStarted + +```solidity +event RedemptionTxMaxTotalFeeUpdateStarted(uint64 newRedemptionTxMaxTotalFee, uint256 timestamp) +``` + +### RedemptionTxMaxTotalFeeUpdated + +```solidity +event RedemptionTxMaxTotalFeeUpdated(uint64 redemptionTxMaxTotalFee) +``` + +### RedemptionTimeoutUpdateStarted + +```solidity +event RedemptionTimeoutUpdateStarted(uint32 newRedemptionTimeout, uint256 timestamp) +``` + +### RedemptionTimeoutUpdated + +```solidity +event RedemptionTimeoutUpdated(uint32 redemptionTimeout) +``` + +### RedemptionTimeoutSlashingAmountUpdateStarted + +```solidity +event RedemptionTimeoutSlashingAmountUpdateStarted(uint96 newRedemptionTimeoutSlashingAmount, uint256 timestamp) +``` + +### RedemptionTimeoutSlashingAmountUpdated + +```solidity +event RedemptionTimeoutSlashingAmountUpdated(uint96 redemptionTimeoutSlashingAmount) +``` + +### RedemptionTimeoutNotifierRewardMultiplierUpdateStarted + +```solidity +event RedemptionTimeoutNotifierRewardMultiplierUpdateStarted(uint32 newRedemptionTimeoutNotifierRewardMultiplier, uint256 timestamp) +``` + +### RedemptionTimeoutNotifierRewardMultiplierUpdated + +```solidity +event RedemptionTimeoutNotifierRewardMultiplierUpdated(uint32 redemptionTimeoutNotifierRewardMultiplier) +``` + +### MovingFundsTxMaxTotalFeeUpdateStarted + +```solidity +event MovingFundsTxMaxTotalFeeUpdateStarted(uint64 newMovingFundsTxMaxTotalFee, uint256 timestamp) +``` + +### MovingFundsTxMaxTotalFeeUpdated + +```solidity +event MovingFundsTxMaxTotalFeeUpdated(uint64 movingFundsTxMaxTotalFee) +``` + +### MovingFundsDustThresholdUpdateStarted + +```solidity +event MovingFundsDustThresholdUpdateStarted(uint64 newMovingFundsDustThreshold, uint256 timestamp) +``` + +### MovingFundsDustThresholdUpdated + +```solidity +event MovingFundsDustThresholdUpdated(uint64 movingFundsDustThreshold) +``` + +### MovingFundsTimeoutResetDelayUpdateStarted + +```solidity +event MovingFundsTimeoutResetDelayUpdateStarted(uint32 newMovingFundsTimeoutResetDelay, uint256 timestamp) +``` + +### MovingFundsTimeoutResetDelayUpdated + +```solidity +event MovingFundsTimeoutResetDelayUpdated(uint32 movingFundsTimeoutResetDelay) +``` + +### MovingFundsTimeoutUpdateStarted + +```solidity +event MovingFundsTimeoutUpdateStarted(uint32 newMovingFundsTimeout, uint256 timestamp) +``` + +### MovingFundsTimeoutUpdated + +```solidity +event MovingFundsTimeoutUpdated(uint32 movingFundsTimeout) +``` + +### MovingFundsTimeoutSlashingAmountUpdateStarted + +```solidity +event MovingFundsTimeoutSlashingAmountUpdateStarted(uint96 newMovingFundsTimeoutSlashingAmount, uint256 timestamp) +``` + +### MovingFundsTimeoutSlashingAmountUpdated + +```solidity +event MovingFundsTimeoutSlashingAmountUpdated(uint96 movingFundsTimeoutSlashingAmount) +``` + +### MovingFundsTimeoutNotifierRewardMultiplierUpdateStarted + +```solidity +event MovingFundsTimeoutNotifierRewardMultiplierUpdateStarted(uint32 newMovingFundsTimeoutNotifierRewardMultiplier, uint256 timestamp) +``` + +### MovingFundsTimeoutNotifierRewardMultiplierUpdated + +```solidity +event MovingFundsTimeoutNotifierRewardMultiplierUpdated(uint32 movingFundsTimeoutNotifierRewardMultiplier) +``` + +### MovingFundsCommitmentGasOffsetUpdateStarted + +```solidity +event MovingFundsCommitmentGasOffsetUpdateStarted(uint16 newMovingFundsCommitmentGasOffset, uint256 timestamp) +``` + +### MovingFundsCommitmentGasOffsetUpdated + +```solidity +event MovingFundsCommitmentGasOffsetUpdated(uint16 movingFundsCommitmentGasOffset) +``` + +### MovedFundsSweepTxMaxTotalFeeUpdateStarted + +```solidity +event MovedFundsSweepTxMaxTotalFeeUpdateStarted(uint64 newMovedFundsSweepTxMaxTotalFee, uint256 timestamp) +``` + +### MovedFundsSweepTxMaxTotalFeeUpdated + +```solidity +event MovedFundsSweepTxMaxTotalFeeUpdated(uint64 movedFundsSweepTxMaxTotalFee) +``` + +### MovedFundsSweepTimeoutUpdateStarted + +```solidity +event MovedFundsSweepTimeoutUpdateStarted(uint32 newMovedFundsSweepTimeout, uint256 timestamp) +``` + +### MovedFundsSweepTimeoutUpdated + +```solidity +event MovedFundsSweepTimeoutUpdated(uint32 movedFundsSweepTimeout) +``` + +### MovedFundsSweepTimeoutSlashingAmountUpdateStarted + +```solidity +event MovedFundsSweepTimeoutSlashingAmountUpdateStarted(uint96 newMovedFundsSweepTimeoutSlashingAmount, uint256 timestamp) +``` + +### MovedFundsSweepTimeoutSlashingAmountUpdated + +```solidity +event MovedFundsSweepTimeoutSlashingAmountUpdated(uint96 movedFundsSweepTimeoutSlashingAmount) +``` + +### MovedFundsSweepTimeoutNotifierRewardMultiplierUpdateStarted + +```solidity +event MovedFundsSweepTimeoutNotifierRewardMultiplierUpdateStarted(uint32 newMovedFundsSweepTimeoutNotifierRewardMultiplier, uint256 timestamp) +``` + +### MovedFundsSweepTimeoutNotifierRewardMultiplierUpdated + +```solidity +event MovedFundsSweepTimeoutNotifierRewardMultiplierUpdated(uint32 movedFundsSweepTimeoutNotifierRewardMultiplier) +``` + +### WalletCreationPeriodUpdateStarted + +```solidity +event WalletCreationPeriodUpdateStarted(uint32 newWalletCreationPeriod, uint256 timestamp) +``` + +### WalletCreationPeriodUpdated + +```solidity +event WalletCreationPeriodUpdated(uint32 walletCreationPeriod) +``` + +### WalletCreationMinBtcBalanceUpdateStarted + +```solidity +event WalletCreationMinBtcBalanceUpdateStarted(uint64 newWalletCreationMinBtcBalance, uint256 timestamp) +``` + +### WalletCreationMinBtcBalanceUpdated + +```solidity +event WalletCreationMinBtcBalanceUpdated(uint64 walletCreationMinBtcBalance) +``` + +### WalletCreationMaxBtcBalanceUpdateStarted + +```solidity +event WalletCreationMaxBtcBalanceUpdateStarted(uint64 newWalletCreationMaxBtcBalance, uint256 timestamp) +``` + +### WalletCreationMaxBtcBalanceUpdated + +```solidity +event WalletCreationMaxBtcBalanceUpdated(uint64 walletCreationMaxBtcBalance) +``` + +### WalletClosureMinBtcBalanceUpdateStarted + +```solidity +event WalletClosureMinBtcBalanceUpdateStarted(uint64 newWalletClosureMinBtcBalance, uint256 timestamp) +``` + +### WalletClosureMinBtcBalanceUpdated + +```solidity +event WalletClosureMinBtcBalanceUpdated(uint64 walletClosureMinBtcBalance) +``` + +### WalletMaxAgeUpdateStarted + +```solidity +event WalletMaxAgeUpdateStarted(uint32 newWalletMaxAge, uint256 timestamp) +``` + +### WalletMaxAgeUpdated + +```solidity +event WalletMaxAgeUpdated(uint32 walletMaxAge) +``` + +### WalletMaxBtcTransferUpdateStarted + +```solidity +event WalletMaxBtcTransferUpdateStarted(uint64 newWalletMaxBtcTransfer, uint256 timestamp) +``` + +### WalletMaxBtcTransferUpdated + +```solidity +event WalletMaxBtcTransferUpdated(uint64 walletMaxBtcTransfer) +``` + +### WalletClosingPeriodUpdateStarted + +```solidity +event WalletClosingPeriodUpdateStarted(uint32 newWalletClosingPeriod, uint256 timestamp) +``` + +### WalletClosingPeriodUpdated + +```solidity +event WalletClosingPeriodUpdated(uint32 walletClosingPeriod) +``` + +### FraudChallengeDepositAmountUpdateStarted + +```solidity +event FraudChallengeDepositAmountUpdateStarted(uint96 newFraudChallengeDepositAmount, uint256 timestamp) +``` + +### FraudChallengeDepositAmountUpdated + +```solidity +event FraudChallengeDepositAmountUpdated(uint96 fraudChallengeDepositAmount) +``` + +### FraudChallengeDefeatTimeoutUpdateStarted + +```solidity +event FraudChallengeDefeatTimeoutUpdateStarted(uint32 newFraudChallengeDefeatTimeout, uint256 timestamp) +``` + +### FraudChallengeDefeatTimeoutUpdated + +```solidity +event FraudChallengeDefeatTimeoutUpdated(uint32 fraudChallengeDefeatTimeout) +``` + +### FraudSlashingAmountUpdateStarted + +```solidity +event FraudSlashingAmountUpdateStarted(uint96 newFraudSlashingAmount, uint256 timestamp) +``` + +### FraudSlashingAmountUpdated + +```solidity +event FraudSlashingAmountUpdated(uint96 fraudSlashingAmount) +``` + +### FraudNotifierRewardMultiplierUpdateStarted + +```solidity +event FraudNotifierRewardMultiplierUpdateStarted(uint32 newFraudNotifierRewardMultiplier, uint256 timestamp) +``` + +### FraudNotifierRewardMultiplierUpdated + +```solidity +event FraudNotifierRewardMultiplierUpdated(uint32 fraudNotifierRewardMultiplier) +``` + +### TreasuryUpdateStarted + +```solidity +event TreasuryUpdateStarted(address newTreasury, uint256 timestamp) +``` + +### TreasuryUpdated + +```solidity +event TreasuryUpdated(address treasury) +``` + +### onlyAfterGovernanceDelay + +```solidity +modifier onlyAfterGovernanceDelay(uint256 changeInitiatedTimestamp, uint256 governanceDelay) +``` + +Reverts if called before the governance delay elapses. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| changeInitiatedTimestamp | uint256 | Timestamp indicating the beginning of the change. | +| governanceDelay | uint256 | | + +### beginDepositDustThresholdUpdate + +```solidity +function beginDepositDustThresholdUpdate(struct BridgeGovernanceParameters.DepositData self, uint64 _newDepositDustThreshold) external +``` + +Begins the deposit dust threshold amount update process. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| self | struct BridgeGovernanceParameters.DepositData | | +| _newDepositDustThreshold | uint64 | New deposit dust threshold amount. | + +### finalizeDepositDustThresholdUpdate + +```solidity +function finalizeDepositDustThresholdUpdate(struct BridgeGovernanceParameters.DepositData self, uint256 governanceDelay) external +``` + +Finalizes the deposit dust threshold amount update process. + +Can be called after the governance delay elapses. + +### beginDepositTreasuryFeeDivisorUpdate + +```solidity +function beginDepositTreasuryFeeDivisorUpdate(struct BridgeGovernanceParameters.DepositData self, uint64 _newDepositTreasuryFeeDivisor) external +``` + +Begins the deposit treasury fee divisor amount update process. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| self | struct BridgeGovernanceParameters.DepositData | | +| _newDepositTreasuryFeeDivisor | uint64 | New deposit treasury fee divisor amount. | + +### finalizeDepositTreasuryFeeDivisorUpdate + +```solidity +function finalizeDepositTreasuryFeeDivisorUpdate(struct BridgeGovernanceParameters.DepositData self, uint256 governanceDelay) external +``` + +Finalizes the deposit treasury fee divisor amount update process. + +Can be called after the governance delay elapses. + +### beginDepositTxMaxFeeUpdate + +```solidity +function beginDepositTxMaxFeeUpdate(struct BridgeGovernanceParameters.DepositData self, uint64 _newDepositTxMaxFee) external +``` + +Begins the deposit tx max fee amount update process. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| self | struct BridgeGovernanceParameters.DepositData | | +| _newDepositTxMaxFee | uint64 | New deposit tx max fee amount. | + +### finalizeDepositTxMaxFeeUpdate + +```solidity +function finalizeDepositTxMaxFeeUpdate(struct BridgeGovernanceParameters.DepositData self, uint256 governanceDelay) external +``` + +Finalizes the deposit tx max fee amount update process. + +Can be called after the governance delay elapses. + +### beginDepositRevealAheadPeriodUpdate + +```solidity +function beginDepositRevealAheadPeriodUpdate(struct BridgeGovernanceParameters.DepositData self, uint32 _newDepositRevealAheadPeriod) external +``` + +Begins the deposit reveal ahead period update process. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| self | struct BridgeGovernanceParameters.DepositData | | +| _newDepositRevealAheadPeriod | uint32 | New deposit reveal ahead period. | + +### finalizeDepositRevealAheadPeriodUpdate + +```solidity +function finalizeDepositRevealAheadPeriodUpdate(struct BridgeGovernanceParameters.DepositData self, uint256 governanceDelay) external +``` + +Finalizes the deposit reveal ahead period update process. + +Can be called after the governance delay elapses. + +### beginRedemptionDustThresholdUpdate + +```solidity +function beginRedemptionDustThresholdUpdate(struct BridgeGovernanceParameters.RedemptionData self, uint64 _newRedemptionDustThreshold) external +``` + +Begins the redemption dust threshold amount update process. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| self | struct BridgeGovernanceParameters.RedemptionData | | +| _newRedemptionDustThreshold | uint64 | New redemption dust threshold amount. | + +### finalizeRedemptionDustThresholdUpdate + +```solidity +function finalizeRedemptionDustThresholdUpdate(struct BridgeGovernanceParameters.RedemptionData self, uint256 governanceDelay) external +``` + +Finalizes the redemption dust threshold amount update process. + +Can be called after the governance delay elapses. + +### beginRedemptionTreasuryFeeDivisorUpdate + +```solidity +function beginRedemptionTreasuryFeeDivisorUpdate(struct BridgeGovernanceParameters.RedemptionData self, uint64 _newRedemptionTreasuryFeeDivisor) external +``` + +Begins the redemption treasury fee divisor amount update process. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| self | struct BridgeGovernanceParameters.RedemptionData | | +| _newRedemptionTreasuryFeeDivisor | uint64 | New redemption treasury fee divisor amount. | + +### finalizeRedemptionTreasuryFeeDivisorUpdate + +```solidity +function finalizeRedemptionTreasuryFeeDivisorUpdate(struct BridgeGovernanceParameters.RedemptionData self, uint256 governanceDelay) external +``` + +Finalizes the redemption treasury fee divisor amount update process. + +Can be called after the governance delay elapses. + +### beginRedemptionTxMaxFeeUpdate + +```solidity +function beginRedemptionTxMaxFeeUpdate(struct BridgeGovernanceParameters.RedemptionData self, uint64 _newRedemptionTxMaxFee) external +``` + +Begins the redemption tx max fee amount update process. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| self | struct BridgeGovernanceParameters.RedemptionData | | +| _newRedemptionTxMaxFee | uint64 | New redemption tx max fee amount. | + +### finalizeRedemptionTxMaxFeeUpdate + +```solidity +function finalizeRedemptionTxMaxFeeUpdate(struct BridgeGovernanceParameters.RedemptionData self, uint256 governanceDelay) external +``` + +Finalizes the redemption tx max fee amount update process. + +Can be called after the governance delay elapses. + +### beginRedemptionTxMaxTotalFeeUpdate + +```solidity +function beginRedemptionTxMaxTotalFeeUpdate(struct BridgeGovernanceParameters.RedemptionData self, uint64 _newRedemptionTxMaxTotalFee) external +``` + +Begins the redemption tx max total fee amount update process. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| self | struct BridgeGovernanceParameters.RedemptionData | | +| _newRedemptionTxMaxTotalFee | uint64 | New redemption tx max total fee amount. | + +### finalizeRedemptionTxMaxTotalFeeUpdate + +```solidity +function finalizeRedemptionTxMaxTotalFeeUpdate(struct BridgeGovernanceParameters.RedemptionData self, uint256 governanceDelay) external +``` + +Finalizes the redemption tx max total fee amount update process. + +Can be called after the governance delay elapses. + +### beginRedemptionTimeoutUpdate + +```solidity +function beginRedemptionTimeoutUpdate(struct BridgeGovernanceParameters.RedemptionData self, uint32 _newRedemptionTimeout) external +``` + +Begins the redemption timeout amount update process. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| self | struct BridgeGovernanceParameters.RedemptionData | | +| _newRedemptionTimeout | uint32 | New redemption timeout amount. | + +### finalizeRedemptionTimeoutUpdate + +```solidity +function finalizeRedemptionTimeoutUpdate(struct BridgeGovernanceParameters.RedemptionData self, uint256 governanceDelay) external +``` + +Finalizes the redemption timeout amount update +process. + +Can be called after the governance delay elapses. + +### beginRedemptionTimeoutSlashingAmountUpdate + +```solidity +function beginRedemptionTimeoutSlashingAmountUpdate(struct BridgeGovernanceParameters.RedemptionData self, uint96 _newRedemptionTimeoutSlashingAmount) external +``` + +Begins the redemption timeout slashing amount update process. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| self | struct BridgeGovernanceParameters.RedemptionData | | +| _newRedemptionTimeoutSlashingAmount | uint96 | New redemption timeout slashing amount. | + +### finalizeRedemptionTimeoutSlashingAmountUpdate + +```solidity +function finalizeRedemptionTimeoutSlashingAmountUpdate(struct BridgeGovernanceParameters.RedemptionData self, uint256 governanceDelay) external +``` + +Finalizes the redemption timeout slashing amount update process. + +Can be called after the governance delay elapses. + +### beginRedemptionTimeoutNotifierRewardMultiplierUpdate + +```solidity +function beginRedemptionTimeoutNotifierRewardMultiplierUpdate(struct BridgeGovernanceParameters.RedemptionData self, uint32 _newRedemptionTimeoutNotifierRewardMultiplier) external +``` + +Begins the redemption timeout notifier reward multiplier amount +update process. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| self | struct BridgeGovernanceParameters.RedemptionData | | +| _newRedemptionTimeoutNotifierRewardMultiplier | uint32 | New redemption timeout notifier reward multiplier amount. | + +### finalizeRedemptionTimeoutNotifierRewardMultiplierUpdate + +```solidity +function finalizeRedemptionTimeoutNotifierRewardMultiplierUpdate(struct BridgeGovernanceParameters.RedemptionData self, uint256 governanceDelay) external +``` + +Finalizes the redemption timeout notifier reward multiplier amount update process. + +Can be called after the governance delay elapses. + +### beginMovingFundsTxMaxTotalFeeUpdate + +```solidity +function beginMovingFundsTxMaxTotalFeeUpdate(struct BridgeGovernanceParameters.MovingFundsData self, uint64 _newMovingFundsTxMaxTotalFee) external +``` + +Begins the moving funds tx max total fee amount update process. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| self | struct BridgeGovernanceParameters.MovingFundsData | | +| _newMovingFundsTxMaxTotalFee | uint64 | New moving funds tx max total fee amount. | + +### finalizeMovingFundsTxMaxTotalFeeUpdate + +```solidity +function finalizeMovingFundsTxMaxTotalFeeUpdate(struct BridgeGovernanceParameters.MovingFundsData self, uint256 governanceDelay) external +``` + +Finalizes the moving funds tx max total fee amount update process. + +Can be called after the governance delay elapses. + +### beginMovingFundsDustThresholdUpdate + +```solidity +function beginMovingFundsDustThresholdUpdate(struct BridgeGovernanceParameters.MovingFundsData self, uint64 _newMovingFundsDustThreshold) external +``` + +Begins the moving funds dust threshold amount update process. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| self | struct BridgeGovernanceParameters.MovingFundsData | | +| _newMovingFundsDustThreshold | uint64 | New moving funds dust threshold amount. | + +### finalizeMovingFundsDustThresholdUpdate + +```solidity +function finalizeMovingFundsDustThresholdUpdate(struct BridgeGovernanceParameters.MovingFundsData self, uint256 governanceDelay) external +``` + +Finalizes the moving funds dust threshold amount update process. + +Can be called after the governance delay elapses. + +### beginMovingFundsTimeoutResetDelayUpdate + +```solidity +function beginMovingFundsTimeoutResetDelayUpdate(struct BridgeGovernanceParameters.MovingFundsData self, uint32 _newMovingFundsTimeoutResetDelay) external +``` + +Begins the moving funds timeout reset delay amount update process. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| self | struct BridgeGovernanceParameters.MovingFundsData | | +| _newMovingFundsTimeoutResetDelay | uint32 | New moving funds timeout reset delay amount. | + +### finalizeMovingFundsTimeoutResetDelayUpdate + +```solidity +function finalizeMovingFundsTimeoutResetDelayUpdate(struct BridgeGovernanceParameters.MovingFundsData self, uint256 governanceDelay) external +``` + +Finalizes the moving funds timeout reset delay amount update process. + +Can be called after the governance delay elapses. + +### beginMovingFundsTimeoutUpdate + +```solidity +function beginMovingFundsTimeoutUpdate(struct BridgeGovernanceParameters.MovingFundsData self, uint32 _newMovingFundsTimeout) external +``` + +Begins the moving funds timeout amount update process. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| self | struct BridgeGovernanceParameters.MovingFundsData | | +| _newMovingFundsTimeout | uint32 | New moving funds timeout amount. | + +### finalizeMovingFundsTimeoutUpdate + +```solidity +function finalizeMovingFundsTimeoutUpdate(struct BridgeGovernanceParameters.MovingFundsData self, uint256 governanceDelay) external +``` + +Finalizes the moving funds timeout amount update process. + +Can be called after the governance delay elapses. + +### beginMovingFundsTimeoutSlashingAmountUpdate + +```solidity +function beginMovingFundsTimeoutSlashingAmountUpdate(struct BridgeGovernanceParameters.MovingFundsData self, uint96 _newMovingFundsTimeoutSlashingAmount) external +``` + +Begins the moving funds timeout slashing amount update process. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| self | struct BridgeGovernanceParameters.MovingFundsData | | +| _newMovingFundsTimeoutSlashingAmount | uint96 | New moving funds timeout slashing amount. | + +### finalizeMovingFundsTimeoutSlashingAmountUpdate + +```solidity +function finalizeMovingFundsTimeoutSlashingAmountUpdate(struct BridgeGovernanceParameters.MovingFundsData self, uint256 governanceDelay) external +``` + +Finalizes the moving funds timeout slashing amount update process. + +Can be called after the governance delay elapses. + +### beginMovingFundsTimeoutNotifierRewardMultiplierUpdate + +```solidity +function beginMovingFundsTimeoutNotifierRewardMultiplierUpdate(struct BridgeGovernanceParameters.MovingFundsData self, uint32 _newMovingFundsTimeoutNotifierRewardMultiplier) external +``` + +Begins the moving funds timeout notifier reward multiplier amount +update process. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| self | struct BridgeGovernanceParameters.MovingFundsData | | +| _newMovingFundsTimeoutNotifierRewardMultiplier | uint32 | New moving funds timeout notifier reward multiplier amount. | + +### finalizeMovingFundsTimeoutNotifierRewardMultiplierUpdate + +```solidity +function finalizeMovingFundsTimeoutNotifierRewardMultiplierUpdate(struct BridgeGovernanceParameters.MovingFundsData self, uint256 governanceDelay) external +``` + +Finalizes the moving funds timeout notifier reward multiplier +amount update process. + +Can be called after the governance delay elapses. + +### beginMovingFundsCommitmentGasOffsetUpdate + +```solidity +function beginMovingFundsCommitmentGasOffsetUpdate(struct BridgeGovernanceParameters.MovingFundsData self, uint16 _newMovingFundsCommitmentGasOffset) external +``` + +Begins the moving funds commitment gas offset update process. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| self | struct BridgeGovernanceParameters.MovingFundsData | | +| _newMovingFundsCommitmentGasOffset | uint16 | New moving funds commitment gas offset. | + +### finalizeMovingFundsCommitmentGasOffsetUpdate + +```solidity +function finalizeMovingFundsCommitmentGasOffsetUpdate(struct BridgeGovernanceParameters.MovingFundsData self, uint256 governanceDelay) external +``` + +Finalizes the moving funds commitment gas offset update process. + +Can be called after the governance delay elapses. + +### beginMovedFundsSweepTxMaxTotalFeeUpdate + +```solidity +function beginMovedFundsSweepTxMaxTotalFeeUpdate(struct BridgeGovernanceParameters.MovingFundsData self, uint64 _newMovedFundsSweepTxMaxTotalFee) external +``` + +Begins the moved funds sweep tx max total fee amount update process. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| self | struct BridgeGovernanceParameters.MovingFundsData | | +| _newMovedFundsSweepTxMaxTotalFee | uint64 | New moved funds sweep tx max total fee amount. | + +### finalizeMovedFundsSweepTxMaxTotalFeeUpdate + +```solidity +function finalizeMovedFundsSweepTxMaxTotalFeeUpdate(struct BridgeGovernanceParameters.MovingFundsData self, uint256 governanceDelay) external +``` + +Finalizes the moved funds sweep tx max total fee amount update +process. + +Can be called after the governance delay elapses. + +### beginMovedFundsSweepTimeoutUpdate + +```solidity +function beginMovedFundsSweepTimeoutUpdate(struct BridgeGovernanceParameters.MovingFundsData self, uint32 _newMovedFundsSweepTimeout) external +``` + +Begins the moved funds sweep timeout amount update process. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| self | struct BridgeGovernanceParameters.MovingFundsData | | +| _newMovedFundsSweepTimeout | uint32 | New moved funds sweep timeout amount. | + +### finalizeMovedFundsSweepTimeoutUpdate + +```solidity +function finalizeMovedFundsSweepTimeoutUpdate(struct BridgeGovernanceParameters.MovingFundsData self, uint256 governanceDelay) external +``` + +Finalizes the moved funds sweep timeout amount update process. + +Can be called after the governance delay elapses. + +### beginMovedFundsSweepTimeoutSlashingAmountUpdate + +```solidity +function beginMovedFundsSweepTimeoutSlashingAmountUpdate(struct BridgeGovernanceParameters.MovingFundsData self, uint96 _newMovedFundsSweepTimeoutSlashingAmount) external +``` + +Begins the moved funds sweep timeout slashing amount update +process. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| self | struct BridgeGovernanceParameters.MovingFundsData | | +| _newMovedFundsSweepTimeoutSlashingAmount | uint96 | New moved funds sweep timeout slashing amount. | + +### finalizeMovedFundsSweepTimeoutSlashingAmountUpdate + +```solidity +function finalizeMovedFundsSweepTimeoutSlashingAmountUpdate(struct BridgeGovernanceParameters.MovingFundsData self, uint256 governanceDelay) external +``` + +Finalizes the moved funds sweep timeout slashing amount +update process. + +Can be called after the governance delay elapses. + +### beginMovedFundsSweepTimeoutNotifierRewardMultiplierUpdate + +```solidity +function beginMovedFundsSweepTimeoutNotifierRewardMultiplierUpdate(struct BridgeGovernanceParameters.MovingFundsData self, uint32 _newMovedFundsSweepTimeoutNotifierRewardMultiplier) external +``` + +Begins the moved funds sweep timeout notifier reward multiplier +amount update process. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| self | struct BridgeGovernanceParameters.MovingFundsData | | +| _newMovedFundsSweepTimeoutNotifierRewardMultiplier | uint32 | New moved funds sweep timeout notifier reward multiplier amount. | + +### finalizeMovedFundsSweepTimeoutNotifierRewardMultiplierUpdate + +```solidity +function finalizeMovedFundsSweepTimeoutNotifierRewardMultiplierUpdate(struct BridgeGovernanceParameters.MovingFundsData self, uint256 governanceDelay) external +``` + +Finalizes the moved funds sweep timeout notifier reward multiplier +amount update process. + +Can be called after the governance delay elapses. + +### beginWalletCreationPeriodUpdate + +```solidity +function beginWalletCreationPeriodUpdate(struct BridgeGovernanceParameters.WalletData self, uint32 _newWalletCreationPeriod) external +``` + +Begins the wallet creation period amount update process. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| self | struct BridgeGovernanceParameters.WalletData | | +| _newWalletCreationPeriod | uint32 | New wallet creation period amount. | + +### finalizeWalletCreationPeriodUpdate + +```solidity +function finalizeWalletCreationPeriodUpdate(struct BridgeGovernanceParameters.WalletData self, uint256 governanceDelay) external +``` + +Finalizes the wallet creation period amount update process. + +Can be called after the governance delay elapses. + +### beginWalletCreationMinBtcBalanceUpdate + +```solidity +function beginWalletCreationMinBtcBalanceUpdate(struct BridgeGovernanceParameters.WalletData self, uint64 _newWalletCreationMinBtcBalance) external +``` + +Begins the wallet creation min btc balance amount update process. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| self | struct BridgeGovernanceParameters.WalletData | | +| _newWalletCreationMinBtcBalance | uint64 | New wallet creation min btc balance amount. | + +### finalizeWalletCreationMinBtcBalanceUpdate + +```solidity +function finalizeWalletCreationMinBtcBalanceUpdate(struct BridgeGovernanceParameters.WalletData self, uint256 governanceDelay) external +``` + +Finalizes the wallet creation min btc balance amount update process. + +Can be called after the governance delay elapses. + +### beginWalletCreationMaxBtcBalanceUpdate + +```solidity +function beginWalletCreationMaxBtcBalanceUpdate(struct BridgeGovernanceParameters.WalletData self, uint64 _newWalletCreationMaxBtcBalance) external +``` + +Begins the wallet creation max btc balance amount update process. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| self | struct BridgeGovernanceParameters.WalletData | | +| _newWalletCreationMaxBtcBalance | uint64 | New wallet creation max btc balance amount. | + +### finalizeWalletCreationMaxBtcBalanceUpdate + +```solidity +function finalizeWalletCreationMaxBtcBalanceUpdate(struct BridgeGovernanceParameters.WalletData self, uint256 governanceDelay) external +``` + +Finalizes the wallet creation max btc balance amount update process. + +Can be called after the governance delay elapses. + +### beginWalletClosureMinBtcBalanceUpdate + +```solidity +function beginWalletClosureMinBtcBalanceUpdate(struct BridgeGovernanceParameters.WalletData self, uint64 _newWalletClosureMinBtcBalance) external +``` + +Begins the wallet closure min btc balance amount update process. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| self | struct BridgeGovernanceParameters.WalletData | | +| _newWalletClosureMinBtcBalance | uint64 | New wallet closure min btc balance amount. | + +### finalizeWalletClosureMinBtcBalanceUpdate + +```solidity +function finalizeWalletClosureMinBtcBalanceUpdate(struct BridgeGovernanceParameters.WalletData self, uint256 governanceDelay) external +``` + +Finalizes the wallet closure min btc balance amount update process. + +Can be called after the governance delay elapses. + +### beginWalletMaxAgeUpdate + +```solidity +function beginWalletMaxAgeUpdate(struct BridgeGovernanceParameters.WalletData self, uint32 _newWalletMaxAge) external +``` + +Begins the wallet max age amount update process. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| self | struct BridgeGovernanceParameters.WalletData | | +| _newWalletMaxAge | uint32 | New wallet max age amount. | + +### finalizeWalletMaxAgeUpdate + +```solidity +function finalizeWalletMaxAgeUpdate(struct BridgeGovernanceParameters.WalletData self, uint256 governanceDelay) external +``` + +Finalizes the wallet max age amount update process. + +Can be called after the governance delay elapses. + +### beginWalletMaxBtcTransferUpdate + +```solidity +function beginWalletMaxBtcTransferUpdate(struct BridgeGovernanceParameters.WalletData self, uint64 _newWalletMaxBtcTransfer) external +``` + +Begins the wallet max btc transfer amount update process. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| self | struct BridgeGovernanceParameters.WalletData | | +| _newWalletMaxBtcTransfer | uint64 | New wallet max btc transfer amount. | + +### finalizeWalletMaxBtcTransferUpdate + +```solidity +function finalizeWalletMaxBtcTransferUpdate(struct BridgeGovernanceParameters.WalletData self, uint256 governanceDelay) external +``` + +Finalizes the wallet max btc transfer amount update process. + +Can be called after the governance delay elapses. + +### beginWalletClosingPeriodUpdate + +```solidity +function beginWalletClosingPeriodUpdate(struct BridgeGovernanceParameters.WalletData self, uint32 _newWalletClosingPeriod) external +``` + +Begins the wallet closing period amount update process. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| self | struct BridgeGovernanceParameters.WalletData | | +| _newWalletClosingPeriod | uint32 | New wallet closing period amount. | + +### finalizeWalletClosingPeriodUpdate + +```solidity +function finalizeWalletClosingPeriodUpdate(struct BridgeGovernanceParameters.WalletData self, uint256 governanceDelay) external +``` + +Finalizes the wallet closing period amount update process. + +Can be called after the governance delay elapses. + +### beginFraudChallengeDepositAmountUpdate + +```solidity +function beginFraudChallengeDepositAmountUpdate(struct BridgeGovernanceParameters.FraudData self, uint96 _newFraudChallengeDepositAmount) external +``` + +Begins the fraud challenge deposit amount update process. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| self | struct BridgeGovernanceParameters.FraudData | | +| _newFraudChallengeDepositAmount | uint96 | New fraud challenge deposit amount. | + +### finalizeFraudChallengeDepositAmountUpdate + +```solidity +function finalizeFraudChallengeDepositAmountUpdate(struct BridgeGovernanceParameters.FraudData self, uint256 governanceDelay) external +``` + +Finalizes the fraud challenge deposit amount update process. + +Can be called after the governance delay elapses. + +### beginFraudChallengeDefeatTimeoutUpdate + +```solidity +function beginFraudChallengeDefeatTimeoutUpdate(struct BridgeGovernanceParameters.FraudData self, uint32 _newFraudChallengeDefeatTimeout) external +``` + +Begins the fraud challenge defeat timeout amount update process. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| self | struct BridgeGovernanceParameters.FraudData | | +| _newFraudChallengeDefeatTimeout | uint32 | New fraud challenge defeat timeout amount. | + +### finalizeFraudChallengeDefeatTimeoutUpdate + +```solidity +function finalizeFraudChallengeDefeatTimeoutUpdate(struct BridgeGovernanceParameters.FraudData self, uint256 governanceDelay) external +``` + +Finalizes the fraud challenge defeat timeout amount update process. + +Can be called after the governance delay elapses. + +### beginFraudSlashingAmountUpdate + +```solidity +function beginFraudSlashingAmountUpdate(struct BridgeGovernanceParameters.FraudData self, uint96 _newFraudSlashingAmount) external +``` + +Begins the fraud slashing amount update process. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| self | struct BridgeGovernanceParameters.FraudData | | +| _newFraudSlashingAmount | uint96 | New fraud slashing amount. | + +### finalizeFraudSlashingAmountUpdate + +```solidity +function finalizeFraudSlashingAmountUpdate(struct BridgeGovernanceParameters.FraudData self, uint256 governanceDelay) external +``` + +Finalizes the fraud slashing amount update process. + +Can be called after the governance delay elapses. + +### beginFraudNotifierRewardMultiplierUpdate + +```solidity +function beginFraudNotifierRewardMultiplierUpdate(struct BridgeGovernanceParameters.FraudData self, uint32 _newFraudNotifierRewardMultiplier) external +``` + +Begins the fraud notifier reward multiplier amount update process. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| self | struct BridgeGovernanceParameters.FraudData | | +| _newFraudNotifierRewardMultiplier | uint32 | New fraud notifier reward multiplier amount. | + +### finalizeFraudNotifierRewardMultiplierUpdate + +```solidity +function finalizeFraudNotifierRewardMultiplierUpdate(struct BridgeGovernanceParameters.FraudData self, uint256 governanceDelay) external +``` + +Finalizes the fraud notifier reward multiplier amount update process. + +Can be called after the governance delay elapses. + +### beginTreasuryUpdate + +```solidity +function beginTreasuryUpdate(struct BridgeGovernanceParameters.TreasuryData self, address _newTreasury) external +``` + +Begins the treasury address update process. + +It does not perform any parameter validation. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| self | struct BridgeGovernanceParameters.TreasuryData | | +| _newTreasury | address | New treasury address. | + +### finalizeTreasuryUpdate + +```solidity +function finalizeTreasuryUpdate(struct BridgeGovernanceParameters.TreasuryData self, uint256 governanceDelay) external +``` + +Finalizes the treasury address update process. + +Can be called after the governance delay elapses. + diff --git a/docs/app-development/tbtc-v2/tbtc-v2-api/generated-docs/bridge/BridgeState.md b/docs/app-development/tbtc-v2/tbtc-v2-api/generated-docs/bridge/BridgeState.md new file mode 100644 index 0000000..4ec9090 --- /dev/null +++ b/docs/app-development/tbtc-v2/tbtc-v2-api/generated-docs/bridge/BridgeState.md @@ -0,0 +1,250 @@ +# Solidity API + +## BridgeState + +### Storage + +```solidity +struct Storage { + contract Bank bank; + contract IRelay relay; + uint96 txProofDifficultyFactor; + contract IWalletRegistry ecdsaWalletRegistry; + contract ReimbursementPool reimbursementPool; + address treasury; + bytes32 __treasuryAlignmentGap; + uint64 depositDustThreshold; + uint64 depositTreasuryFeeDivisor; + uint64 depositTxMaxFee; + uint32 depositRevealAheadPeriod; + bytes32 __depositAlignmentGap; + uint64 movingFundsTxMaxTotalFee; + uint64 movingFundsDustThreshold; + uint32 movingFundsTimeoutResetDelay; + uint32 movingFundsTimeout; + uint96 movingFundsTimeoutSlashingAmount; + uint32 movingFundsTimeoutNotifierRewardMultiplier; + uint16 movingFundsCommitmentGasOffset; + bytes32 __movingFundsAlignmentGap; + uint64 movedFundsSweepTxMaxTotalFee; + uint32 movedFundsSweepTimeout; + uint96 movedFundsSweepTimeoutSlashingAmount; + uint32 movedFundsSweepTimeoutNotifierRewardMultiplier; + uint64 redemptionDustThreshold; + uint64 redemptionTreasuryFeeDivisor; + uint64 redemptionTxMaxFee; + uint64 redemptionTxMaxTotalFee; + bytes32 __redemptionAlignmentGap; + uint32 redemptionTimeout; + uint96 redemptionTimeoutSlashingAmount; + uint32 redemptionTimeoutNotifierRewardMultiplier; + uint96 fraudChallengeDepositAmount; + uint32 fraudChallengeDefeatTimeout; + uint96 fraudSlashingAmount; + uint32 fraudNotifierRewardMultiplier; + uint32 walletCreationPeriod; + uint64 walletCreationMinBtcBalance; + uint64 walletCreationMaxBtcBalance; + uint64 walletClosureMinBtcBalance; + uint32 walletMaxAge; + bytes20 activeWalletPubKeyHash; + uint32 liveWalletsCount; + uint64 walletMaxBtcTransfer; + uint32 walletClosingPeriod; + mapping(uint256 => struct Deposit.DepositRequest) deposits; + mapping(address => bool) isVaultTrusted; + mapping(address => bool) isSpvMaintainer; + mapping(uint256 => struct MovingFunds.MovedFundsSweepRequest) movedFundsSweepRequests; + mapping(uint256 => struct Redemption.RedemptionRequest) pendingRedemptions; + mapping(uint256 => struct Redemption.RedemptionRequest) timedOutRedemptions; + mapping(uint256 => struct Fraud.FraudChallenge) fraudChallenges; + mapping(uint256 => bool) spentMainUTXOs; + mapping(bytes20 => struct Wallets.Wallet) registeredWallets; + uint256[50] __gap; +} +``` + +### DepositParametersUpdated + +```solidity +event DepositParametersUpdated(uint64 depositDustThreshold, uint64 depositTreasuryFeeDivisor, uint64 depositTxMaxFee, uint32 depositRevealAheadPeriod) +``` + +### RedemptionParametersUpdated + +```solidity +event RedemptionParametersUpdated(uint64 redemptionDustThreshold, uint64 redemptionTreasuryFeeDivisor, uint64 redemptionTxMaxFee, uint64 redemptionTxMaxTotalFee, uint32 redemptionTimeout, uint96 redemptionTimeoutSlashingAmount, uint32 redemptionTimeoutNotifierRewardMultiplier) +``` + +### MovingFundsParametersUpdated + +```solidity +event MovingFundsParametersUpdated(uint64 movingFundsTxMaxTotalFee, uint64 movingFundsDustThreshold, uint32 movingFundsTimeoutResetDelay, uint32 movingFundsTimeout, uint96 movingFundsTimeoutSlashingAmount, uint32 movingFundsTimeoutNotifierRewardMultiplier, uint16 movingFundsCommitmentGasOffset, uint64 movedFundsSweepTxMaxTotalFee, uint32 movedFundsSweepTimeout, uint96 movedFundsSweepTimeoutSlashingAmount, uint32 movedFundsSweepTimeoutNotifierRewardMultiplier) +``` + +### WalletParametersUpdated + +```solidity +event WalletParametersUpdated(uint32 walletCreationPeriod, uint64 walletCreationMinBtcBalance, uint64 walletCreationMaxBtcBalance, uint64 walletClosureMinBtcBalance, uint32 walletMaxAge, uint64 walletMaxBtcTransfer, uint32 walletClosingPeriod) +``` + +### FraudParametersUpdated + +```solidity +event FraudParametersUpdated(uint96 fraudChallengeDepositAmount, uint32 fraudChallengeDefeatTimeout, uint96 fraudSlashingAmount, uint32 fraudNotifierRewardMultiplier) +``` + +### TreasuryUpdated + +```solidity +event TreasuryUpdated(address treasury) +``` + +### updateDepositParameters + +```solidity +function updateDepositParameters(struct BridgeState.Storage self, uint64 _depositDustThreshold, uint64 _depositTreasuryFeeDivisor, uint64 _depositTxMaxFee, uint32 _depositRevealAheadPeriod) internal +``` + +of `depositTreasuryFeeDivisor` and `depositTxMaxFee` parameters +in order to make requests that can incur the treasury and +transaction fee and still satisfy the depositor. + +Requirements: +- Deposit dust threshold must be greater than zero, +- Deposit dust threshold must be greater than deposit TX max fee, +- Deposit transaction max fee must be greater than zero. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| self | struct BridgeState.Storage | | +| _depositDustThreshold | uint64 | | +| _depositTreasuryFeeDivisor | uint64 | New value of the treasury fee divisor. It is the divisor used to compute the treasury fee taken from each deposit and transferred to the treasury upon sweep proof submission. That fee is computed as follows: `treasuryFee = depositedAmount / depositTreasuryFeeDivisor` For example, if the treasury fee needs to be 2% of each deposit, the `depositTreasuryFeeDivisor` should be set to `50` because `1/50 = 0.02 = 2%`. | +| _depositTxMaxFee | uint64 | New value of the deposit tx max fee in satoshis. It is the maximum amount of BTC transaction fee that can be incurred by each swept deposit being part of the given sweep transaction. If the maximum BTC transaction fee is exceeded, such transaction is considered a fraud. | +| _depositRevealAheadPeriod | uint32 | New value of the deposit reveal ahead period parameter in seconds. It defines the length of the period that must be preserved between the deposit reveal time and the deposit refund locktime. | + +### updateRedemptionParameters + +```solidity +function updateRedemptionParameters(struct BridgeState.Storage self, uint64 _redemptionDustThreshold, uint64 _redemptionTreasuryFeeDivisor, uint64 _redemptionTxMaxFee, uint64 _redemptionTxMaxTotalFee, uint32 _redemptionTimeout, uint96 _redemptionTimeoutSlashingAmount, uint32 _redemptionTimeoutNotifierRewardMultiplier) internal +``` + +Updates parameters of redemptions. + +Requirements: +- Redemption dust threshold must be greater than moving funds dust +threshold, +- Redemption dust threshold must be greater than the redemption TX +max fee, +- Redemption transaction max fee must be greater than zero, +- Redemption transaction max total fee must be greater than or +equal to the redemption transaction per-request max fee, +- Redemption timeout must be greater than zero, +- Redemption timeout notifier reward multiplier must be in the +range [0, 100]. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| self | struct BridgeState.Storage | | +| _redemptionDustThreshold | uint64 | New value of the redemption dust threshold in satoshis. It is the minimal amount that can be requested for redemption. Value of this parameter must take into account the value of `redemptionTreasuryFeeDivisor` and `redemptionTxMaxFee` parameters in order to make requests that can incur the treasury and transaction fee and still satisfy the redeemer. | +| _redemptionTreasuryFeeDivisor | uint64 | New value of the redemption treasury fee divisor. It is the divisor used to compute the treasury fee taken from each redemption request and transferred to the treasury upon successful request finalization. That fee is computed as follows: `treasuryFee = requestedAmount / redemptionTreasuryFeeDivisor` For example, if the treasury fee needs to be 2% of each redemption request, the `redemptionTreasuryFeeDivisor` should be set to `50` because `1/50 = 0.02 = 2%`. | +| _redemptionTxMaxFee | uint64 | New value of the redemption transaction max fee in satoshis. It is the maximum amount of BTC transaction fee that can be incurred by each redemption request being part of the given redemption transaction. If the maximum BTC transaction fee is exceeded, such transaction is considered a fraud. This is a per-redemption output max fee for the redemption transaction. | +| _redemptionTxMaxTotalFee | uint64 | New value of the redemption transaction max total fee in satoshis. It is the maximum amount of the total BTC transaction fee that is acceptable in a single redemption transaction. This is a _total_ max fee for the entire redemption transaction. | +| _redemptionTimeout | uint32 | New value of the redemption timeout in seconds. It is the time after which the redemption request can be reported as timed out. It is counted from the moment when the redemption request was created via `requestRedemption` call. Reported timed out requests are cancelled and locked TBTC is returned to the redeemer in full amount. | +| _redemptionTimeoutSlashingAmount | uint96 | New value of the redemption timeout slashing amount in T, it is the amount slashed from each wallet member for redemption timeout. | +| _redemptionTimeoutNotifierRewardMultiplier | uint32 | New value of the redemption timeout notifier reward multiplier as percentage, it determines the percentage of the notifier reward from the staking contact the notifier of a redemption timeout receives. The value must be in the range [0, 100]. | + +### updateMovingFundsParameters + +```solidity +function updateMovingFundsParameters(struct BridgeState.Storage self, uint64 _movingFundsTxMaxTotalFee, uint64 _movingFundsDustThreshold, uint32 _movingFundsTimeoutResetDelay, uint32 _movingFundsTimeout, uint96 _movingFundsTimeoutSlashingAmount, uint32 _movingFundsTimeoutNotifierRewardMultiplier, uint16 _movingFundsCommitmentGasOffset, uint64 _movedFundsSweepTxMaxTotalFee, uint32 _movedFundsSweepTimeout, uint96 _movedFundsSweepTimeoutSlashingAmount, uint32 _movedFundsSweepTimeoutNotifierRewardMultiplier) internal +``` + +Updates parameters of moving funds. + +Requirements: +- Moving funds transaction max total fee must be greater than zero, +- Moving funds dust threshold must be greater than zero and lower +than the redemption dust threshold, +- Moving funds timeout reset delay must be greater than zero, +- Moving funds timeout must be greater than the moving funds +timeout reset delay, +- Moving funds timeout notifier reward multiplier must be in the +range [0, 100], +- Moved funds sweep transaction max total fee must be greater than zero, +- Moved funds sweep timeout must be greater than zero, +- Moved funds sweep timeout notifier reward multiplier must be in the +range [0, 100]. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| self | struct BridgeState.Storage | | +| _movingFundsTxMaxTotalFee | uint64 | New value of the moving funds transaction max total fee in satoshis. It is the maximum amount of the total BTC transaction fee that is acceptable in a single moving funds transaction. This is a _total_ max fee for the entire moving funds transaction. | +| _movingFundsDustThreshold | uint64 | New value of the moving funds dust threshold. It is the minimal satoshi amount that makes sense to be transferred during the moving funds process. Moving funds wallets having their BTC balance below that value can begin closing immediately as transferring such a low value may not be possible due to BTC network fees. | +| _movingFundsTimeoutResetDelay | uint32 | New value of the moving funds timeout reset delay in seconds. It is the time after which the moving funds timeout can be reset in case the target wallet commitment cannot be submitted due to a lack of live wallets in the system. It is counted from the moment when the wallet was requested to move their funds and switched to the MovingFunds state or from the moment the timeout was reset the last time. | +| _movingFundsTimeout | uint32 | New value of the moving funds timeout in seconds. It is the time after which the moving funds process can be reported as timed out. It is counted from the moment when the wallet was requested to move their funds and switched to the MovingFunds state. | +| _movingFundsTimeoutSlashingAmount | uint96 | New value of the moving funds timeout slashing amount in T, it is the amount slashed from each wallet member for moving funds timeout. | +| _movingFundsTimeoutNotifierRewardMultiplier | uint32 | New value of the moving funds timeout notifier reward multiplier as percentage, it determines the percentage of the notifier reward from the staking contact the notifier of a moving funds timeout receives. The value must be in the range [0, 100]. | +| _movingFundsCommitmentGasOffset | uint16 | New value of the gas offset for moving funds target wallet commitment transaction gas costs reimbursement. | +| _movedFundsSweepTxMaxTotalFee | uint64 | New value of the moved funds sweep transaction max total fee in satoshis. It is the maximum amount of the total BTC transaction fee that is acceptable in a single moved funds sweep transaction. This is a _total_ max fee for the entire moved funds sweep transaction. | +| _movedFundsSweepTimeout | uint32 | New value of the moved funds sweep timeout in seconds. It is the time after which the moved funds sweep process can be reported as timed out. It is counted from the moment when the wallet was requested to sweep the received funds. | +| _movedFundsSweepTimeoutSlashingAmount | uint96 | New value of the moved funds sweep timeout slashing amount in T, it is the amount slashed from each wallet member for moved funds sweep timeout. | +| _movedFundsSweepTimeoutNotifierRewardMultiplier | uint32 | New value of the moved funds sweep timeout notifier reward multiplier as percentage, it determines the percentage of the notifier reward from the staking contact the notifier of a moved funds sweep timeout receives. The value must be in the range [0, 100]. | + +### updateWalletParameters + +```solidity +function updateWalletParameters(struct BridgeState.Storage self, uint32 _walletCreationPeriod, uint64 _walletCreationMinBtcBalance, uint64 _walletCreationMaxBtcBalance, uint64 _walletClosureMinBtcBalance, uint32 _walletMaxAge, uint64 _walletMaxBtcTransfer, uint32 _walletClosingPeriod) internal +``` + +Requirements: +- Wallet maximum BTC balance must be greater than the wallet +minimum BTC balance, +- Wallet maximum BTC transfer must be greater than zero, +- Wallet closing period must be greater than zero. + +### updateFraudParameters + +```solidity +function updateFraudParameters(struct BridgeState.Storage self, uint96 _fraudChallengeDepositAmount, uint32 _fraudChallengeDefeatTimeout, uint96 _fraudSlashingAmount, uint32 _fraudNotifierRewardMultiplier) internal +``` + +Updates parameters related to frauds. + +Requirements: +- Fraud challenge defeat timeout must be greater than 0, +- Fraud notifier reward multiplier must be in the range [0, 100]. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| self | struct BridgeState.Storage | | +| _fraudChallengeDepositAmount | uint96 | New value of the fraud challenge deposit amount in wei, it is the amount of ETH the party challenging the wallet for fraud needs to deposit. | +| _fraudChallengeDefeatTimeout | uint32 | New value of the challenge defeat timeout in seconds, it is the amount of time the wallet has to defeat a fraud challenge. The value must be greater than zero. | +| _fraudSlashingAmount | uint96 | New value of the fraud slashing amount in T, it is the amount slashed from each wallet member for committing a fraud. | +| _fraudNotifierRewardMultiplier | uint32 | New value of the fraud notifier reward multiplier as percentage, it determines the percentage of the notifier reward from the staking contact the notifier of a fraud receives. The value must be in the range [0, 100]. | + +### updateTreasury + +```solidity +function updateTreasury(struct BridgeState.Storage self, address _treasury) internal +``` + +Updates treasury address. The treasury receives the system fees. + +The treasury address must not be 0x0. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| self | struct BridgeState.Storage | | +| _treasury | address | New value of the treasury address. | + diff --git a/docs/app-development/tbtc-v2/tbtc-v2-api/generated-docs/bridge/Deposit.md b/docs/app-development/tbtc-v2/tbtc-v2-api/generated-docs/bridge/Deposit.md new file mode 100644 index 0000000..d555be0 --- /dev/null +++ b/docs/app-development/tbtc-v2/tbtc-v2-api/generated-docs/bridge/Deposit.md @@ -0,0 +1,131 @@ +# Solidity API + +## Deposit + +The library handles the logic for revealing Bitcoin deposits to +the Bridge. + +The depositor puts together a P2SH or P2WSH address to deposit the +funds. This script is unique to each depositor and looks like this: + +``` + DROP + DROP +DUP HASH160 EQUAL +IF +CHECKSIG +ELSE +DUP HASH160 EQUALVERIFY + CHECKLOCKTIMEVERIFY DROP +CHECKSIG +ENDIF +``` + +Since each depositor has their own Ethereum address and their own +blinding factor, each depositor’s script is unique, and the hash +of each depositor’s script is unique. + +### DepositRevealInfo + +```solidity +struct DepositRevealInfo { + uint32 fundingOutputIndex; + bytes8 blindingFactor; + bytes20 walletPubKeyHash; + bytes20 refundPubKeyHash; + bytes4 refundLocktime; + address vault; +} +``` + +### DepositRequest + +```solidity +struct DepositRequest { + address depositor; + uint64 amount; + uint32 revealedAt; + address vault; + uint64 treasuryFee; + uint32 sweptAt; +} +``` + +### DepositRevealed + +```solidity +event DepositRevealed(bytes32 fundingTxHash, uint32 fundingOutputIndex, address depositor, uint64 amount, bytes8 blindingFactor, bytes20 walletPubKeyHash, bytes20 refundPubKeyHash, bytes4 refundLocktime, address vault) +``` + +### revealDeposit + +```solidity +function revealDeposit(struct BridgeState.Storage self, struct BitcoinTx.Info fundingTx, struct Deposit.DepositRevealInfo reveal) external +``` + +Used by the depositor to reveal information about their P2(W)SH +Bitcoin deposit to the Bridge on Ethereum chain. The off-chain +wallet listens for revealed deposit events and may decide to +include the revealed deposit in the next executed sweep. +Information about the Bitcoin deposit can be revealed before or +after the Bitcoin transaction with P2(W)SH deposit is mined on +the Bitcoin chain. Worth noting, the gas cost of this function +scales with the number of P2(W)SH transaction inputs and +outputs. The deposit may be routed to one of the trusted vaults. +When a deposit is routed to a vault, vault gets notified when +the deposit gets swept and it may execute the appropriate action. + +Requirements: +- This function must be called by the same Ethereum address as the +one used in the P2(W)SH BTC deposit transaction as a depositor, +- `reveal.walletPubKeyHash` must identify a `Live` wallet, +- `reveal.vault` must be 0x0 or point to a trusted vault, +- `reveal.fundingOutputIndex` must point to the actual P2(W)SH +output of the BTC deposit transaction, +- `reveal.blindingFactor` must be the blinding factor used in the +P2(W)SH BTC deposit transaction, +- `reveal.walletPubKeyHash` must be the wallet pub key hash used in +the P2(W)SH BTC deposit transaction, +- `reveal.refundPubKeyHash` must be the refund pub key hash used in +the P2(W)SH BTC deposit transaction, +- `reveal.refundLocktime` must be the refund locktime used in the +P2(W)SH BTC deposit transaction, +- BTC deposit for the given `fundingTxHash`, `fundingOutputIndex` +can be revealed only one time. + +If any of these requirements is not met, the wallet _must_ refuse +to sweep the deposit and the depositor has to wait until the +deposit script unlocks to receive their BTC back. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| self | struct BridgeState.Storage | | +| fundingTx | struct BitcoinTx.Info | Bitcoin funding transaction data, see `BitcoinTx.Info`. | +| reveal | struct Deposit.DepositRevealInfo | Deposit reveal data, see `RevealInfo struct. | + +### validateDepositRefundLocktime + +```solidity +function validateDepositRefundLocktime(struct BridgeState.Storage self, bytes4 refundLocktime) internal view +``` + +Validates the deposit refund locktime. The validation passes +successfully only if the deposit reveal is done respectively +earlier than the moment when the deposit refund locktime is +reached, i.e. the deposit become refundable. Reverts otherwise. + +Requirements: +- `refundLocktime` as integer must be >= 500M +- `refundLocktime` must denote a timestamp that is at least +`depositRevealAheadPeriod` seconds later than the moment +of `block.timestamp` + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| self | struct BridgeState.Storage | | +| refundLocktime | bytes4 | The deposit refund locktime as 4-byte LE. | + diff --git a/docs/app-development/tbtc-v2/tbtc-v2-api/generated-docs/bridge/DepositSweep.md b/docs/app-development/tbtc-v2/tbtc-v2-api/generated-docs/bridge/DepositSweep.md new file mode 100644 index 0000000..4c3f0e8 --- /dev/null +++ b/docs/app-development/tbtc-v2/tbtc-v2-api/generated-docs/bridge/DepositSweep.md @@ -0,0 +1,222 @@ +# Solidity API + +## DepositSweep + +The library handles the logic for sweeping transactions revealed to +the Bridge + +Bridge active wallet periodically signs a transaction that unlocks all +of the valid, revealed deposits above the dust threshold, combines them +into a single UTXO with the existing main wallet UTXO, and relocks +those transactions without a 30-day refund clause to the same wallet. +This has two main effects: it consolidates the UTXO set and it disables +the refund. Balances of depositors in the Bank are increased when the +SPV sweep proof is submitted to the Bridge. + +### DepositSweepTxInputsProcessingInfo + +```solidity +struct DepositSweepTxInputsProcessingInfo { + bytes sweepTxInputVector; + struct BitcoinTx.UTXO mainUtxo; + address vault; +} +``` + +### DepositSweepTxInputsInfo + +```solidity +struct DepositSweepTxInputsInfo { + uint256 inputsTotalValue; + address[] depositors; + uint256[] depositedAmounts; + uint256[] treasuryFees; +} +``` + +### DepositsSwept + +```solidity +event DepositsSwept(bytes20 walletPubKeyHash, bytes32 sweepTxHash) +``` + +### submitDepositSweepProof + +```solidity +function submitDepositSweepProof(struct BridgeState.Storage self, struct BitcoinTx.Info sweepTx, struct BitcoinTx.Proof sweepProof, struct BitcoinTx.UTXO mainUtxo, address vault) external +``` + +Used by the wallet to prove the BTC deposit sweep transaction +and to update Bank balances accordingly. Sweep is only accepted +if it satisfies SPV proof. + +The function is performing Bank balance updates by first +computing the Bitcoin fee for the sweep transaction. The fee is +divided evenly between all swept deposits. Each depositor +receives a balance in the bank equal to the amount inferred +during the reveal transaction, minus their fee share. + +It is possible to prove the given sweep only one time. + +Requirements: +- `sweepTx` components must match the expected structure. See +`BitcoinTx.Info` docs for reference. Their values must exactly +correspond to appropriate Bitcoin transaction fields to produce +a provable transaction hash, +- The `sweepTx` should represent a Bitcoin transaction with 1..n +inputs. If the wallet has no main UTXO, all n inputs should +correspond to P2(W)SH revealed deposits UTXOs. If the wallet has +an existing main UTXO, one of the n inputs must point to that +main UTXO and remaining n-1 inputs should correspond to P2(W)SH +revealed deposits UTXOs. That transaction must have only +one P2(W)PKH output locking funds on the 20-byte wallet public +key hash, +- All revealed deposits that are swept by `sweepTx` must have +their `vault` parameters set to the same address as the address +passed in the `vault` function parameter, +- `sweepProof` components must match the expected structure. See +`BitcoinTx.Proof` docs for reference. The `bitcoinHeaders` +field must contain a valid number of block headers, not less +than the `txProofDifficultyFactor` contract constant, +- `mainUtxo` components must point to the recent main UTXO +of the given wallet, as currently known on the Ethereum chain. +If there is no main UTXO, this parameter is ignored. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| self | struct BridgeState.Storage | | +| sweepTx | struct BitcoinTx.Info | Bitcoin sweep transaction data. | +| sweepProof | struct BitcoinTx.Proof | Bitcoin sweep proof data. | +| mainUtxo | struct BitcoinTx.UTXO | Data of the wallet's main UTXO, as currently known on the Ethereum chain. If no main UTXO exists for the given wallet, this parameter is ignored. | +| vault | address | Optional address of the vault where all swept deposits should be routed to. All deposits swept as part of the transaction must have their `vault` parameters set to the same address. If this parameter is set to an address of a trusted vault, swept deposits are routed to that vault. If this parameter is set to the zero address or to an address of a non-trusted vault, swept deposits are not routed to a vault but depositors' balances are increased in the Bank individually. | + +### resolveDepositSweepingWallet + +```solidity +function resolveDepositSweepingWallet(struct BridgeState.Storage self, bytes20 walletPubKeyHash, struct BitcoinTx.UTXO mainUtxo) internal view returns (struct Wallets.Wallet wallet, struct BitcoinTx.UTXO resolvedMainUtxo) +``` + +Resolves sweeping wallet based on the provided wallet public key +hash. Validates the wallet state and current main UTXO, as +currently known on the Ethereum chain. + +Requirements: +- Sweeping wallet must be either in Live or MovingFunds state, +- If the main UTXO of the sweeping wallet exists in the storage, +the passed `mainUTXO` parameter must be equal to the stored one. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| self | struct BridgeState.Storage | | +| walletPubKeyHash | bytes20 | public key hash of the wallet proving the sweep Bitcoin transaction. | +| mainUtxo | struct BitcoinTx.UTXO | Data of the wallet's main UTXO, as currently known on the Ethereum chain. If no main UTXO exists for the given wallet, this parameter is ignored. | + +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +| wallet | struct Wallets.Wallet | Data of the sweeping wallet. | +| resolvedMainUtxo | struct BitcoinTx.UTXO | The actual main UTXO of the sweeping wallet resolved by cross-checking the `mainUtxo` parameter with the chain state. If the validation went well, this is the plain-text main UTXO corresponding to the `wallet.mainUtxoHash`. | + +### processDepositSweepTxOutput + +```solidity +function processDepositSweepTxOutput(struct BridgeState.Storage self, bytes sweepTxOutputVector) internal view returns (bytes20 walletPubKeyHash, uint64 value) +``` + +Processes the Bitcoin sweep transaction output vector by +extracting the single output and using it to gain additional +information required for further processing (e.g. value and +wallet public key hash). + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| self | struct BridgeState.Storage | | +| sweepTxOutputVector | bytes | Bitcoin sweep transaction output vector. This function assumes vector's structure is valid so it must be validated using e.g. `BTCUtils.validateVout` function before it is passed here. | + +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +| walletPubKeyHash | bytes20 | 20-byte wallet public key hash. | +| value | uint64 | 8-byte sweep transaction output value. | + +### processDepositSweepTxInputs + +```solidity +function processDepositSweepTxInputs(struct BridgeState.Storage self, struct DepositSweep.DepositSweepTxInputsProcessingInfo processInfo) internal returns (struct DepositSweep.DepositSweepTxInputsInfo resultInfo) +``` + +Processes the Bitcoin sweep transaction input vector. It +extracts each input and tries to obtain associated deposit or +main UTXO data, depending on the input type. Reverts +if one of the inputs cannot be recognized as a pointer to a +revealed deposit or expected main UTXO. +This function also marks each processed deposit as swept. + +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +| resultInfo | struct DepositSweep.DepositSweepTxInputsInfo | Outcomes of the processing. | + +### parseDepositSweepTxInputAt + +```solidity +function parseDepositSweepTxInputAt(bytes inputVector, uint256 inputStartingIndex) internal pure returns (bytes32 outpointTxHash, uint32 outpointIndex, uint256 inputLength) +``` + +Parses a Bitcoin transaction input starting at the given index. + +This function assumes vector's structure is valid so it must be +validated using e.g. `BTCUtils.validateVin` function before it +is passed here. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| inputVector | bytes | Bitcoin transaction input vector. | +| inputStartingIndex | uint256 | Index the given input starts at. | + +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +| outpointTxHash | bytes32 | 32-byte hash of the Bitcoin transaction which is pointed in the given input's outpoint. | +| outpointIndex | uint32 | 4-byte index of the Bitcoin transaction output which is pointed in the given input's outpoint. | +| inputLength | uint256 | Byte length of the given input. | + +### depositSweepTxFeeDistribution + +```solidity +function depositSweepTxFeeDistribution(uint256 sweepTxInputsTotalValue, uint256 sweepTxOutputValue, uint256 depositsCount) internal pure returns (uint256 depositTxFee, uint256 depositTxFeeRemainder) +``` + +Determines the distribution of the sweep transaction fee +over swept deposits. + +It is up to the caller to decide how the remainder should be +counted in. This function only computes its value. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| sweepTxInputsTotalValue | uint256 | Total value of all sweep transaction inputs. | +| sweepTxOutputValue | uint256 | Value of the sweep transaction output. | +| depositsCount | uint256 | Count of the deposits swept by the sweep transaction. | + +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +| depositTxFee | uint256 | Transaction fee per deposit determined by evenly spreading the divisible part of the sweep transaction fee over all deposits. | +| depositTxFeeRemainder | uint256 | The indivisible part of the sweep transaction fee than cannot be distributed over all deposits. | + diff --git a/docs/app-development/tbtc-v2/tbtc-v2-api/generated-docs/bridge/EcdsaLib.md b/docs/app-development/tbtc-v2/tbtc-v2-api/generated-docs/bridge/EcdsaLib.md new file mode 100644 index 0000000..65d5d89 --- /dev/null +++ b/docs/app-development/tbtc-v2/tbtc-v2-api/generated-docs/bridge/EcdsaLib.md @@ -0,0 +1,29 @@ +# Solidity API + +## EcdsaLib + +### compressPublicKey + +```solidity +function compressPublicKey(bytes32 x, bytes32 y) internal pure returns (bytes) +``` + +Converts public key X and Y coordinates (32-byte each) to a +compressed public key (33-byte). Compressed public key is X +coordinate prefixed with `02` or `03` based on the Y coordinate parity. +It is expected that the uncompressed public key is stripped +(i.e. it is not prefixed with `04`). + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| x | bytes32 | Wallet's public key's X coordinate. | +| y | bytes32 | Wallet's public key's Y coordinate. | + +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +| [0] | bytes | Compressed public key (33-byte), prefixed with `02` or `03`. | + diff --git a/docs/app-development/tbtc-v2/tbtc-v2-api/generated-docs/bridge/Fraud.md b/docs/app-development/tbtc-v2/tbtc-v2-api/generated-docs/bridge/Fraud.md new file mode 100644 index 0000000..e95cde5 --- /dev/null +++ b/docs/app-development/tbtc-v2/tbtc-v2-api/generated-docs/bridge/Fraud.md @@ -0,0 +1,286 @@ +# Solidity API + +## Fraud + +The library handles the logic for challenging Bridge wallets that +committed fraud. + +Anyone can submit a fraud challenge indicating that a UTXO being under +the wallet control was unlocked by the wallet but was not used +according to the protocol rules. That means the wallet signed +a transaction input pointing to that UTXO and there is a unique +sighash and signature pair associated with that input. + +In order to defeat the challenge, the same wallet public key and +signature must be provided as were used to calculate the sighash during +the challenge. The wallet provides the preimage which produces sighash +used to generate the ECDSA signature that is the subject of the fraud +claim. + +The fraud challenge defeat attempt will succeed if the inputs in the +preimage are considered honestly spent by the wallet. Therefore the +transaction spending the UTXO must be proven in the Bridge before +a challenge defeat is called. + +Another option is when a malicious wallet member used a signed heartbeat +message periodically produced by the wallet off-chain to challenge the +wallet for a fraud. Anyone from the wallet can defeat the challenge by +proving the sighash and signature were produced for a heartbeat message +following a strict format. + +### FraudChallenge + +```solidity +struct FraudChallenge { + address challenger; + uint256 depositAmount; + uint32 reportedAt; + bool resolved; +} +``` + +### FraudChallengeSubmitted + +```solidity +event FraudChallengeSubmitted(bytes20 walletPubKeyHash, bytes32 sighash, uint8 v, bytes32 r, bytes32 s) +``` + +### FraudChallengeDefeated + +```solidity +event FraudChallengeDefeated(bytes20 walletPubKeyHash, bytes32 sighash) +``` + +### FraudChallengeDefeatTimedOut + +```solidity +event FraudChallengeDefeatTimedOut(bytes20 walletPubKeyHash, bytes32 sighash) +``` + +### submitFraudChallenge + +```solidity +function submitFraudChallenge(struct BridgeState.Storage self, bytes walletPublicKey, bytes preimageSha256, struct BitcoinTx.RSVSignature signature) external +``` + +Submits a fraud challenge indicating that a UTXO being under +wallet control was unlocked by the wallet but was not used +according to the protocol rules. That means the wallet signed +a transaction input pointing to that UTXO and there is a unique +sighash and signature pair associated with that input. This +function uses those parameters to create a fraud accusation that +proves a given transaction input unlocking the given UTXO was +actually signed by the wallet. This function cannot determine +whether the transaction was actually broadcast and the input was +consumed in a fraudulent way so it just opens a challenge period +during which the wallet can defeat the challenge by submitting +proof of a transaction that consumes the given input according +to protocol rules. To prevent spurious allegations, the caller +must deposit ETH that is returned back upon justified fraud +challenge or confiscated otherwise. + +Requirements: +- Wallet behind `walletPublicKey` must be in Live or MovingFunds +or Closing state, +- The challenger must send appropriate amount of ETH used as +fraud challenge deposit, +- The signature (represented by r, s and v) must be generated by +the wallet behind `walletPubKey` during signing of `sighash` +which was calculated from `preimageSha256`, +- Wallet can be challenged for the given signature only once. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| self | struct BridgeState.Storage | | +| walletPublicKey | bytes | The public key of the wallet in the uncompressed and unprefixed format (64 bytes). | +| preimageSha256 | bytes | The hash that was generated by applying SHA-256 one time over the preimage used during input signing. The preimage is a serialized subset of the transaction and its structure depends on the transaction input (see BIP-143 for reference). Notice that applying SHA-256 over the `preimageSha256` results in `sighash`. The path from `preimage` to `sighash` looks like this: preimage -> (SHA-256) -> preimageSha256 -> (SHA-256) -> sighash. | +| signature | struct BitcoinTx.RSVSignature | Bitcoin signature in the R/S/V format | + +### defeatFraudChallenge + +```solidity +function defeatFraudChallenge(struct BridgeState.Storage self, bytes walletPublicKey, bytes preimage, bool witness) external +``` + +Allows to defeat a pending fraud challenge against a wallet if +the transaction that spends the UTXO follows the protocol rules. +In order to defeat the challenge the same `walletPublicKey` and +signature (represented by `r`, `s` and `v`) must be provided as +were used to calculate the sighash during input signing. +The fraud challenge defeat attempt will only succeed if the +inputs in the preimage are considered honestly spent by the +wallet. Therefore the transaction spending the UTXO must be +proven in the Bridge before a challenge defeat is called. +If successfully defeated, the fraud challenge is marked as +resolved and the amount of ether deposited by the challenger is +sent to the treasury. + +Requirements: +- `walletPublicKey` and `sighash` calculated as `hash256(preimage)` +must identify an open fraud challenge, +- the preimage must be a valid preimage of a transaction generated +according to the protocol rules and already proved in the Bridge, +- before a defeat attempt is made the transaction that spends the +given UTXO must be proven in the Bridge. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| self | struct BridgeState.Storage | | +| walletPublicKey | bytes | The public key of the wallet in the uncompressed and unprefixed format (64 bytes). | +| preimage | bytes | The preimage which produces sighash used to generate the ECDSA signature that is the subject of the fraud claim. It is a serialized subset of the transaction. The exact subset used as the preimage depends on the transaction input the signature is produced for. See BIP-143 for reference. | +| witness | bool | Flag indicating whether the preimage was produced for a witness input. True for witness, false for non-witness input. | + +### defeatFraudChallengeWithHeartbeat + +```solidity +function defeatFraudChallengeWithHeartbeat(struct BridgeState.Storage self, bytes walletPublicKey, bytes heartbeatMessage) external +``` + +Allows to defeat a pending fraud challenge against a wallet by +proving the sighash and signature were produced for an off-chain +wallet heartbeat message following a strict format. +In order to defeat the challenge the same `walletPublicKey` and +signature (represented by `r`, `s` and `v`) must be provided as +were used to calculate the sighash during heartbeat message +signing. The fraud challenge defeat attempt will only succeed if +the signed message follows a strict format required for +heartbeat messages. If successfully defeated, the fraud +challenge is marked as resolved and the amount of ether +deposited by the challenger is sent to the treasury. + +Requirements: +- `walletPublicKey` and `sighash` calculated as +`hash256(heartbeatMessage)` must identify an open fraud challenge, +- `heartbeatMessage` must follow a strict format of heartbeat +messages. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| self | struct BridgeState.Storage | | +| walletPublicKey | bytes | The public key of the wallet in the uncompressed and unprefixed format (64 bytes), | +| heartbeatMessage | bytes | Off-chain heartbeat message meeting the heartbeat message format requirements which produces sighash used to generate the ECDSA signature that is the subject of the fraud claim. | + +### resolveFraudChallenge + +```solidity +function resolveFraudChallenge(struct BridgeState.Storage self, bytes walletPublicKey, struct Fraud.FraudChallenge challenge, bytes32 sighash) internal +``` + +Called only for successfully defeated fraud challenges. +The fraud challenge is marked as resolved and the amount of +ether deposited by the challenger is sent to the treasury. + +Requirements: +- Must be called only for successfully defeated fraud challenges. + +### notifyFraudChallengeDefeatTimeout + +```solidity +function notifyFraudChallengeDefeatTimeout(struct BridgeState.Storage self, bytes walletPublicKey, uint32[] walletMembersIDs, bytes preimageSha256) external +``` + +Notifies about defeat timeout for the given fraud challenge. +Can be called only if there was a fraud challenge identified by +the provided `walletPublicKey` and `sighash` and it was not +defeated on time. The amount of time that needs to pass after +a fraud challenge is reported is indicated by the +`challengeDefeatTimeout`. After a successful fraud challenge +defeat timeout notification the fraud challenge is marked as +resolved, the stake of each operator is slashed, the ether +deposited is returned to the challenger and the challenger is +rewarded. + +Requirements: +- The wallet must be in the Live or MovingFunds or Closing or +Terminated state, +- The `walletPublicKey` and `sighash` calculated from +`preimageSha256` must identify an open fraud challenge, +- 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 of the `WalletRegistry` contract, +- The amount of time indicated by `challengeDefeatTimeout` must pass +after the challenge was reported. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| self | struct BridgeState.Storage | | +| walletPublicKey | bytes | The public key of the wallet in the uncompressed and unprefixed format (64 bytes). | +| walletMembersIDs | uint32[] | Identifiers of the wallet signing group members. | +| preimageSha256 | bytes | The hash that was generated by applying SHA-256 one time over the preimage used during input signing. The preimage is a serialized subset of the transaction and its structure depends on the transaction input (see BIP-143 for reference). Notice that applying SHA-256 over the `preimageSha256` results in `sighash`. The path from `preimage` to `sighash` looks like this: preimage -> (SHA-256) -> preimageSha256 -> (SHA-256) -> sighash. | + +### extractUtxoKeyFromWitnessPreimage + +```solidity +function extractUtxoKeyFromWitnessPreimage(bytes preimage) internal pure returns (uint256 utxoKey) +``` + +Extracts the UTXO keys from the given preimage used during +signing of a witness input. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| preimage | bytes | The preimage which produces sighash used to generate the ECDSA signature that is the subject of the fraud claim. It is a serialized subset of the transaction. The exact subset used as the preimage depends on the transaction input the signature is produced for. See BIP-143 for reference | + +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +| utxoKey | uint256 | UTXO key that identifies spent input. | + +### extractUtxoKeyFromNonWitnessPreimage + +```solidity +function extractUtxoKeyFromNonWitnessPreimage(bytes preimage) internal pure returns (uint256 utxoKey) +``` + +Extracts the UTXO key from the given preimage used during +signing of a non-witness input. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| preimage | bytes | The preimage which produces sighash used to generate the ECDSA signature that is the subject of the fraud claim. It is a serialized subset of the transaction. The exact subset used as the preimage depends on the transaction input the signature is produced for. See BIP-143 for reference. | + +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +| utxoKey | uint256 | UTXO key that identifies spent input. | + +### extractSighashType + +```solidity +function extractSighashType(bytes preimage) internal pure returns (uint32 sighashType) +``` + +Extracts the sighash type from the given preimage. + +Sighash type is stored as the last 4 bytes in the preimage (little +endian). + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| preimage | bytes | Serialized subset of the transaction. See BIP-143 for reference. | + +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +| sighashType | uint32 | Sighash type as a 32-bit integer. | + diff --git a/docs/app-development/tbtc-v2/tbtc-v2-api/generated-docs/bridge/Heartbeat.md b/docs/app-development/tbtc-v2/tbtc-v2-api/generated-docs/bridge/Heartbeat.md new file mode 100644 index 0000000..8dd8d0b --- /dev/null +++ b/docs/app-development/tbtc-v2/tbtc-v2-api/generated-docs/bridge/Heartbeat.md @@ -0,0 +1,93 @@ +# Solidity API + +## Heartbeat + +The library establishes expected format for heartbeat messages +signed by wallet ECDSA signing group. Heartbeat messages are +constructed in such a way that they can not be used as a Bitcoin +transaction preimages. + +The smallest Bitcoin non-coinbase transaction is a one spending an +OP_TRUE anyonecanspend output and creating 1 OP_TRUE anyonecanspend +output. Such a transaction has 61 bytes (see `BitcoinTx` documentation): +4 bytes for version +1 byte for tx_in_count +36 bytes for tx_in.previous_output +1 byte for tx_in.script_bytes (value: 0) +0 bytes for tx_in.signature_script +4 bytes for tx_in.sequence +1 byte for tx_out_count +8 bytes for tx_out.value +1 byte for tx_out.pk_script_bytes +1 byte for tx_out.pk_script +4 bytes for lock_time + +The smallest Bitcoin coinbase transaction is a one creating +1 OP_TRUE anyonecanspend output and having an empty coinbase script. +Such a transaction has 65 bytes: +4 bytes for version +1 byte for tx_in_count +32 bytes for tx_in.hash (all 0x00) +4 bytes for tx_in.index (all 0xff) +1 byte for tx_in.script_bytes (value: 0) +4 bytes for tx_in.height +0 byte for tx_in.coinbase_script +4 bytes for tx_in.sequence +1 byte for tx_out_count +8 bytes for tx_out.value +1 byte for tx_out.pk_script_bytes +1 byte for tx_out.pk_script +4 bytes for lock_time + +A SIGHASH flag is used to indicate which part of the transaction is +signed by the ECDSA signature. There are currently 3 flags: +SIGHASH_ALL, SIGHASH_NONE, SIGHASH_SINGLE, and different combinations +of these flags. + +No matter the SIGHASH flag and no matter the combination, the following +fields from the transaction are always included in the constructed +preimage: +4 bytes for version +36 bytes for tx_in.previous_output (or tx_in.hash + tx_in.index for coinbase) +4 bytes for lock_time + +Additionally, the last 4 bytes of the preimage determines the SIGHASH +flag. + +This is enough to say there is no way the preimage could be shorter +than 4 + 36 + 4 + 4 = 48 bytes. + +For this reason, we construct the heartbeat message, as a 16-byte +message. The first 8 bytes are 0xffffffffffffffff. The last 8 bytes +are for an arbitrary uint64, being a signed heartbeat nonce (for +example, the last Ethereum block hash). + +The message being signed by the wallet when executing the heartbeat +protocol should be Bitcoin's hash256 (double SHA-256) of the heartbeat +message: +heartbeat_sighash = hash256(heartbeat_message) + +### isValidHeartbeatMessage + +```solidity +function isValidHeartbeatMessage(bytes message) internal pure returns (bool) +``` + +Determines if the signed byte array is a valid, non-fraudulent +heartbeat message. + +Wallet heartbeat message must be exactly 16 bytes long with the first +8 bytes set to 0xffffffffffffffff. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| message | bytes | Message signed by the wallet. It is a potential heartbeat message, Bitcoin transaction preimage, or an arbitrary signed bytes. | + +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +| [0] | bool | True if valid heartbeat message, false otherwise. | + diff --git a/docs/app-development/tbtc-v2/tbtc-v2-api/generated-docs/bridge/IRelay.md b/docs/app-development/tbtc-v2/tbtc-v2-api/generated-docs/bridge/IRelay.md new file mode 100644 index 0000000..6345314 --- /dev/null +++ b/docs/app-development/tbtc-v2/tbtc-v2-api/generated-docs/bridge/IRelay.md @@ -0,0 +1,24 @@ +# Solidity API + +## IRelay + +Contains only the methods needed by tBTC v2. The Bitcoin relay +provides the difficulty of the previous and current epoch. One +difficulty epoch spans 2016 blocks. + +### getCurrentEpochDifficulty + +```solidity +function getCurrentEpochDifficulty() external view returns (uint256) +``` + +Returns the difficulty of the current epoch. + +### getPrevEpochDifficulty + +```solidity +function getPrevEpochDifficulty() external view returns (uint256) +``` + +Returns the difficulty of the previous epoch. + diff --git a/docs/app-development/tbtc-v2/tbtc-v2-api/generated-docs/bridge/MovingFunds.md b/docs/app-development/tbtc-v2/tbtc-v2-api/generated-docs/bridge/MovingFunds.md new file mode 100644 index 0000000..8370eb7 --- /dev/null +++ b/docs/app-development/tbtc-v2/tbtc-v2-api/generated-docs/bridge/MovingFunds.md @@ -0,0 +1,513 @@ +# Solidity API + +## MovingFunds + +The library handles the logic for moving Bitcoin between Bridge +wallets. + +A wallet that failed a heartbeat, did not process requested redemption +on time, or qualifies to be closed, begins the procedure of moving +funds to other wallets in the Bridge. The wallet needs to commit to +which other Live wallets it is moving the funds to and then, provide an +SPV proof of moving funds to the previously committed wallets. +Once the proof is submitted, all target wallets are supposed to +sweep the received UTXOs with their own main UTXOs in order to +update their BTC balances. + +### MovingFundsTxOutputsProcessingInfo + +```solidity +struct MovingFundsTxOutputsProcessingInfo { + bytes32 movingFundsTxHash; + bytes movingFundsTxOutputVector; +} +``` + +### MovedFundsSweepRequestState + +```solidity +enum MovedFundsSweepRequestState { + Unknown, + Pending, + Processed, + TimedOut +} +``` + +### MovedFundsSweepRequest + +```solidity +struct MovedFundsSweepRequest { + bytes20 walletPubKeyHash; + uint64 value; + uint32 createdAt; + enum MovingFunds.MovedFundsSweepRequestState state; +} +``` + +### MovingFundsCommitmentSubmitted + +```solidity +event MovingFundsCommitmentSubmitted(bytes20 walletPubKeyHash, bytes20[] targetWallets, address submitter) +``` + +### MovingFundsTimeoutReset + +```solidity +event MovingFundsTimeoutReset(bytes20 walletPubKeyHash) +``` + +### MovingFundsCompleted + +```solidity +event MovingFundsCompleted(bytes20 walletPubKeyHash, bytes32 movingFundsTxHash) +``` + +### MovingFundsTimedOut + +```solidity +event MovingFundsTimedOut(bytes20 walletPubKeyHash) +``` + +### MovingFundsBelowDustReported + +```solidity +event MovingFundsBelowDustReported(bytes20 walletPubKeyHash) +``` + +### MovedFundsSwept + +```solidity +event MovedFundsSwept(bytes20 walletPubKeyHash, bytes32 sweepTxHash) +``` + +### MovedFundsSweepTimedOut + +```solidity +event MovedFundsSweepTimedOut(bytes20 walletPubKeyHash, bytes32 movingFundsTxHash, uint32 movingFundsTxOutputIndex) +``` + +### submitMovingFundsCommitment + +```solidity +function submitMovingFundsCommitment(struct BridgeState.Storage self, bytes20 walletPubKeyHash, struct BitcoinTx.UTXO walletMainUtxo, uint32[] walletMembersIDs, uint256 walletMemberIndex, bytes20[] targetWallets) external +``` + +Submits the moving funds target wallets commitment. +Once all requirements are met, that function registers the +target wallets commitment and opens the way for moving funds +proof submission. + +Requirements: +- The source wallet must be in the MovingFunds state, +- The source wallet must not have pending redemption requests, +- The source wallet must not have pending moved funds sweep requests, +- The source wallet must not have submitted its commitment already, +- The expression `keccak256(abi.encode(walletMembersIDs))` must +be exactly the same as the hash stored under `membersIdsHash` +for the given source wallet in the ECDSA registry. 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], +- The caller must be the member of the source wallet signing group +at the position indicated by `walletMemberIndex` parameter, +- The `walletMainUtxo` components must point to the recent main +UTXO of the source wallet, as currently known on the Ethereum +chain, +- Source wallet BTC balance must be greater than zero, +- At least one Live wallet must exist in the system, +- Submitted target wallets count must match the expected count +`N = min(liveWalletsCount, ceil(walletBtcBalance / walletMaxBtcTransfer))` +where `N > 0`, +- Each target wallet must be not equal to the source wallet, +- Each target wallet must follow the expected order i.e. all +target wallets 20-byte public key hashes represented as numbers +must form a strictly increasing sequence without duplicates, +- Each target wallet must be in Live state. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| self | struct BridgeState.Storage | | +| walletPubKeyHash | bytes20 | 20-byte public key hash of the source wallet. | +| walletMainUtxo | struct BitcoinTx.UTXO | Data of the source wallet's main UTXO, as currently known on the Ethereum chain. | +| walletMembersIDs | uint32[] | Identifiers of the source wallet signing group members. | +| walletMemberIndex | uint256 | Position of the caller in the source wallet signing group members list. | +| targetWallets | bytes20[] | List of 20-byte public key hashes of the target wallets that the source wallet commits to move the funds to. | + +### resetMovingFundsTimeout + +```solidity +function resetMovingFundsTimeout(struct BridgeState.Storage self, bytes20 walletPubKeyHash) external +``` + +Resets the moving funds timeout for the given wallet if the +target wallet commitment cannot be submitted due to a lack +of live wallets in the system. + +Requirements: +- The wallet must be in the MovingFunds state, +- The target wallets commitment must not be already submitted for +the given moving funds wallet, +- Live wallets count must be zero, +- The moving funds timeout reset delay must be elapsed. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| self | struct BridgeState.Storage | | +| walletPubKeyHash | bytes20 | 20-byte public key hash of the moving funds wallet | + +### submitMovingFundsProof + +```solidity +function submitMovingFundsProof(struct BridgeState.Storage self, struct BitcoinTx.Info movingFundsTx, struct BitcoinTx.Proof movingFundsProof, struct BitcoinTx.UTXO mainUtxo, bytes20 walletPubKeyHash) external +``` + +Used by the wallet to prove the BTC moving funds transaction +and to make the necessary state changes. Moving funds is only +accepted if it satisfies SPV proof. + +The function validates the moving funds transaction structure +by checking if it actually spends the main UTXO of the declared +wallet and locks the value on the pre-committed target wallets +using a reasonable transaction fee. If all preconditions are +met, this functions closes the source wallet. + +It is possible to prove the given moving funds transaction only +one time. + +Requirements: +- `movingFundsTx` components must match the expected structure. See +`BitcoinTx.Info` docs for reference. Their values must exactly +correspond to appropriate Bitcoin transaction fields to produce +a provable transaction hash, +- The `movingFundsTx` should represent a Bitcoin transaction with +exactly 1 input that refers to the wallet's main UTXO. That +transaction should have 1..n outputs corresponding to the +pre-committed target wallets. Outputs must be ordered in the +same way as their corresponding target wallets are ordered +within the target wallets commitment, +- `movingFundsProof` components must match the expected structure. +See `BitcoinTx.Proof` docs for reference. The `bitcoinHeaders` +field must contain a valid number of block headers, not less +than the `txProofDifficultyFactor` contract constant, +- `mainUtxo` components must point to the recent main UTXO +of the given wallet, as currently known on the Ethereum chain. +Additionally, the recent main UTXO on Ethereum must be set, +- `walletPubKeyHash` must be connected with the main UTXO used +as transaction single input, +- The wallet that `walletPubKeyHash` points to must be in the +MovingFunds state, +- The target wallets commitment must be submitted by the wallet +that `walletPubKeyHash` points to, +- The total Bitcoin transaction fee must be lesser or equal +to `movingFundsTxMaxTotalFee` governable parameter. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| self | struct BridgeState.Storage | | +| movingFundsTx | struct BitcoinTx.Info | Bitcoin moving funds transaction data. | +| movingFundsProof | struct BitcoinTx.Proof | Bitcoin moving funds proof data. | +| mainUtxo | struct BitcoinTx.UTXO | Data of the wallet's main UTXO, as currently known on the Ethereum chain. | +| walletPubKeyHash | bytes20 | 20-byte public key hash (computed using Bitcoin HASH160 over the compressed ECDSA public key) of the wallet which performed the moving funds transaction. | + +### processMovingFundsTxOutputs + +```solidity +function processMovingFundsTxOutputs(struct BridgeState.Storage self, struct MovingFunds.MovingFundsTxOutputsProcessingInfo processInfo) internal returns (bytes32 targetWalletsHash, uint256 outputsTotalValue) +``` + +Processes the moving funds Bitcoin transaction output vector +and extracts information required for further processing. + +Requirements: +- The `movingFundsTxOutputVector` must be parseable, i.e. must +be validated by the caller as stated in their parameter doc, +- Each output must refer to a 20-byte public key hash, +- The total outputs value must be evenly divided over all outputs. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| self | struct BridgeState.Storage | | +| processInfo | struct MovingFunds.MovingFundsTxOutputsProcessingInfo | Processing info containing the moving funds tx hash and output vector. | + +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +| targetWalletsHash | bytes32 | keccak256 hash over the list of actual target wallets used in the transaction. | +| outputsTotalValue | uint256 | Sum of all outputs values. | + +### notifyMovingFundsTimeout + +```solidity +function notifyMovingFundsTimeout(struct BridgeState.Storage self, bytes20 walletPubKeyHash, uint32[] walletMembersIDs) external +``` + +Notifies about a timed out moving funds process. Terminates +the wallet and slashes signing group members as a result. + +Requirements: +- The wallet must be in the MovingFunds state, +- The moving funds timeout must be actually exceeded, +- 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 of the `WalletRegistry` contract. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| self | struct BridgeState.Storage | | +| walletPubKeyHash | bytes20 | 20-byte public key hash of the wallet. | +| walletMembersIDs | uint32[] | Identifiers of the wallet signing group members. | + +### notifyMovingFundsBelowDust + +```solidity +function notifyMovingFundsBelowDust(struct BridgeState.Storage self, bytes20 walletPubKeyHash, struct BitcoinTx.UTXO mainUtxo) external +``` + +Notifies about a moving funds wallet whose BTC balance is +below the moving funds dust threshold. Ends the moving funds +process and begins wallet closing immediately. + +Requirements: +- The wallet must be in the MovingFunds state, +- The `mainUtxo` components must point to the recent main UTXO +of the given wallet, as currently known on the Ethereum chain. +If the wallet has no main UTXO, this parameter can be empty as it +is ignored, +- The wallet BTC balance must be below the moving funds threshold. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| self | struct BridgeState.Storage | | +| walletPubKeyHash | bytes20 | 20-byte public key hash of the wallet. | +| mainUtxo | struct BitcoinTx.UTXO | Data of the wallet's main UTXO, as currently known on the Ethereum chain. | + +### submitMovedFundsSweepProof + +```solidity +function submitMovedFundsSweepProof(struct BridgeState.Storage self, struct BitcoinTx.Info sweepTx, struct BitcoinTx.Proof sweepProof, struct BitcoinTx.UTXO mainUtxo) external +``` + +Used by the wallet to prove the BTC moved funds sweep +transaction and to make the necessary state changes. Moved +funds sweep is only accepted if it satisfies SPV proof. + +The function validates the sweep transaction structure by +checking if it actually spends the moved funds UTXO and the +sweeping wallet's main UTXO (optionally), and if it locks the +value on the sweeping wallet's 20-byte public key hash using a +reasonable transaction fee. If all preconditions are +met, this function updates the sweeping wallet main UTXO, thus +their BTC balance. + +It is possible to prove the given sweep transaction only +one time. + +Requirements: +- `sweepTx` components must match the expected structure. See +`BitcoinTx.Info` docs for reference. Their values must exactly +correspond to appropriate Bitcoin transaction fields to produce +a provable transaction hash, +- The `sweepTx` should represent a Bitcoin transaction with +the first input pointing to a wallet's sweep Pending request and, +optionally, the second input pointing to the wallet's main UTXO, +if the sweeping wallet has a main UTXO set. There should be only +one output locking funds on the sweeping wallet 20-byte public +key hash, +- `sweepProof` components must match the expected structure. +See `BitcoinTx.Proof` docs for reference. The `bitcoinHeaders` +field must contain a valid number of block headers, not less +than the `txProofDifficultyFactor` contract constant, +- `mainUtxo` components must point to the recent main UTXO +of the sweeping wallet, as currently known on the Ethereum chain. +If there is no main UTXO, this parameter is ignored, +- The sweeping wallet must be in the Live or MovingFunds state, +- The total Bitcoin transaction fee must be lesser or equal +to `movedFundsSweepTxMaxTotalFee` governable parameter. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| self | struct BridgeState.Storage | | +| sweepTx | struct BitcoinTx.Info | Bitcoin sweep funds transaction data. | +| sweepProof | struct BitcoinTx.Proof | Bitcoin sweep funds proof data. | +| mainUtxo | struct BitcoinTx.UTXO | Data of the sweeping wallet's main UTXO, as currently known on the Ethereum chain. | + +### processMovedFundsSweepTxOutput + +```solidity +function processMovedFundsSweepTxOutput(struct BridgeState.Storage self, bytes sweepTxOutputVector) internal view returns (bytes20 walletPubKeyHash, uint64 value) +``` + +Processes the Bitcoin moved funds sweep transaction output vector +by extracting the single output and using it to gain additional +information required for further processing (e.g. value and +wallet public key hash). + +Requirements: +- Output vector must contain only one output, +- The single output must be of P2PKH or P2WPKH type and lock the +funds on a 20-byte public key hash. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| self | struct BridgeState.Storage | | +| sweepTxOutputVector | bytes | Bitcoin moved funds sweep transaction output vector. This function assumes vector's structure is valid so it must be validated using e.g. `BTCUtils.validateVout` function before it is passed here. | + +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +| walletPubKeyHash | bytes20 | 20-byte wallet public key hash. | +| value | uint64 | 8-byte moved funds sweep transaction output value. | + +### resolveMovedFundsSweepingWallet + +```solidity +function resolveMovedFundsSweepingWallet(struct BridgeState.Storage self, bytes20 walletPubKeyHash, struct BitcoinTx.UTXO mainUtxo) internal view returns (struct Wallets.Wallet wallet, struct BitcoinTx.UTXO resolvedMainUtxo) +``` + +Resolves sweeping wallet based on the provided wallet public key +hash. Validates the wallet state and current main UTXO, as +currently known on the Ethereum chain. + +Requirements: +- Sweeping wallet must be either in Live or MovingFunds state, +- If the main UTXO of the sweeping wallet exists in the storage, +the passed `mainUTXO` parameter must be equal to the stored one. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| self | struct BridgeState.Storage | | +| walletPubKeyHash | bytes20 | public key hash of the wallet proving the sweep Bitcoin transaction. | +| mainUtxo | struct BitcoinTx.UTXO | Data of the wallet's main UTXO, as currently known on the Ethereum chain. If no main UTXO exists for the given wallet, this parameter is ignored. | + +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +| wallet | struct Wallets.Wallet | Data of the sweeping wallet. | +| resolvedMainUtxo | struct BitcoinTx.UTXO | The actual main UTXO of the sweeping wallet resolved by cross-checking the `mainUtxo` parameter with the chain state. If the validation went well, this is the plain-text main UTXO corresponding to the `wallet.mainUtxoHash`. | + +### processMovedFundsSweepTxInputs + +```solidity +function processMovedFundsSweepTxInputs(struct BridgeState.Storage self, bytes sweepTxInputVector, struct BitcoinTx.UTXO mainUtxo, bytes20 walletPubKeyHash) internal returns (uint256 inputsTotalValue) +``` + +Processes the Bitcoin moved funds sweep transaction input vector. +It extracts the first input and tries to match it with one of +the moved funds sweep requests targeting the sweeping wallet. +If the sweep request is an existing Pending request, this +function marks it as Processed. If the sweeping wallet has a +main UTXO, this function extracts the second input, makes sure +it refers to the wallet main UTXO, and marks that main UTXO as +correctly spent. + +Requirements: +- The input vector must consist of one mandatory and one optional +input, +- The mandatory input must be the first input in the vector, +- The mandatory input must point to a Pending moved funds sweep +request that is targeted to the sweeping wallet, +- The optional output must be the second input in the vector, +- The optional input is required if the sweeping wallet has a +main UTXO (i.e. the `mainUtxo` is not zeroed). In that case, +that input must point the the sweeping wallet main UTXO. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| self | struct BridgeState.Storage | | +| sweepTxInputVector | bytes | Bitcoin moved funds sweep transaction input vector. This function assumes vector's structure is valid so it must be validated using e.g. `BTCUtils.validateVin` function before it is passed here. | +| mainUtxo | struct BitcoinTx.UTXO | Data of the sweeping wallet's main UTXO. If no main UTXO exists for the given the wallet, this parameter's fields should be zeroed to bypass the main UTXO validation. | +| walletPubKeyHash | bytes20 | 20-byte public key hash of the sweeping wallet. | + +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +| inputsTotalValue | uint256 | Total inputs value sum. | + +### parseMovedFundsSweepTxInputAt + +```solidity +function parseMovedFundsSweepTxInputAt(bytes inputVector, uint256 inputStartingIndex) internal pure returns (bytes32 outpointTxHash, uint32 outpointIndex, uint256 inputLength) +``` + +Parses a Bitcoin transaction input starting at the given index. + +This function assumes vector's structure is valid so it must be +validated using e.g. `BTCUtils.validateVin` function before it +is passed here. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| inputVector | bytes | Bitcoin transaction input vector. | +| inputStartingIndex | uint256 | Index the given input starts at. | + +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +| outpointTxHash | bytes32 | 32-byte hash of the Bitcoin transaction which is pointed in the given input's outpoint. | +| outpointIndex | uint32 | 4-byte index of the Bitcoin transaction output which is pointed in the given input's outpoint. | +| inputLength | uint256 | Byte length of the given input. | + +### notifyMovedFundsSweepTimeout + +```solidity +function notifyMovedFundsSweepTimeout(struct BridgeState.Storage self, bytes32 movingFundsTxHash, uint32 movingFundsTxOutputIndex, uint32[] walletMembersIDs) external +``` + +Notifies about a timed out moved funds sweep process. If the +wallet is not terminated yet, that function terminates +the wallet and slashes signing group members as a result. +Marks the given sweep request as TimedOut. + +Requirements: +- The moved funds sweep request must be in the Pending state, +- The moved funds sweep timeout must be actually exceeded, +- The wallet must be either in the Live or MovingFunds or +Terminated state,, +- 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 of the `WalletRegistry` contract. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| self | struct BridgeState.Storage | | +| movingFundsTxHash | bytes32 | 32-byte hash of the moving funds transaction that caused the sweep request to be created. | +| movingFundsTxOutputIndex | uint32 | Index of the moving funds transaction output that is subject of the sweep request. | +| walletMembersIDs | uint32[] | Identifiers of the wallet signing group members. | + diff --git a/docs/app-development/tbtc-v2/tbtc-v2-api/generated-docs/bridge/Redemption.md b/docs/app-development/tbtc-v2/tbtc-v2-api/generated-docs/bridge/Redemption.md new file mode 100644 index 0000000..4d4f9d3 --- /dev/null +++ b/docs/app-development/tbtc-v2/tbtc-v2-api/generated-docs/bridge/Redemption.md @@ -0,0 +1,478 @@ +# Solidity API + +## OutboundTx + +Aggregates functions common to the redemption transaction proof +validation and to the moving funds transaction proof validation. + +### processWalletOutboundTxInput + +```solidity +function processWalletOutboundTxInput(struct BridgeState.Storage self, bytes walletOutboundTxInputVector, struct BitcoinTx.UTXO mainUtxo) internal +``` + +Checks whether an outbound Bitcoin transaction performed from +the given wallet has an input vector that contains a single +input referring to the wallet's main UTXO. Marks that main UTXO +as correctly spent if the validation succeeds. Reverts otherwise. +There are two outbound transactions from a wallet possible: a +redemption transaction or a moving funds to another wallet +transaction. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| self | struct BridgeState.Storage | | +| walletOutboundTxInputVector | bytes | Bitcoin outbound transaction's input vector. This function assumes vector's structure is valid so it must be validated using e.g. `BTCUtils.validateVin` function before it is passed here. | +| mainUtxo | struct BitcoinTx.UTXO | Data of the wallet's main UTXO, as currently known on the Ethereum chain. | + +### parseWalletOutboundTxInput + +```solidity +function parseWalletOutboundTxInput(bytes walletOutboundTxInputVector) internal pure returns (bytes32 outpointTxHash, uint32 outpointIndex) +``` + +Parses the input vector of an outbound Bitcoin transaction +performed from the given wallet. It extracts the single input +then the transaction hash and output index from its outpoint. +There are two outbound transactions from a wallet possible: a +redemption transaction or a moving funds to another wallet +transaction. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| walletOutboundTxInputVector | bytes | Bitcoin outbound transaction input vector. This function assumes vector's structure is valid so it must be validated using e.g. `BTCUtils.validateVin` function before it is passed here. | + +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +| outpointTxHash | bytes32 | 32-byte hash of the Bitcoin transaction which is pointed in the input's outpoint. | +| outpointIndex | uint32 | 4-byte index of the Bitcoin transaction output which is pointed in the input's outpoint. | + +## Redemption + +The library handles the logic for redeeming Bitcoin balances from +the Bridge. + +To initiate a redemption, a user with a Bank balance supplies +a Bitcoin address. Then, the system calculates the redemption fee, and +releases balance to the provided Bitcoin address. Just like in case of +sweeps of revealed deposits, redemption requests are processed in +batches and require SPV proof to be submitted to the Bridge. + +### RedemptionRequest + +```solidity +struct RedemptionRequest { + address redeemer; + uint64 requestedAmount; + uint64 treasuryFee; + uint64 txMaxFee; + uint32 requestedAt; +} +``` + +### RedemptionTxOutputsInfo + +```solidity +struct RedemptionTxOutputsInfo { + uint256 outputsTotalValue; + uint64 totalBurnableValue; + uint64 totalTreasuryFee; + uint32 changeIndex; + uint64 changeValue; +} +``` + +### RedemptionTxOutputsProcessingInfo + +```solidity +struct RedemptionTxOutputsProcessingInfo { + uint256 outputStartingIndex; + uint256 outputsCount; + bytes32 walletP2PKHScriptKeccak; + bytes32 walletP2WPKHScriptKeccak; +} +``` + +### RedemptionRequested + +```solidity +event RedemptionRequested(bytes20 walletPubKeyHash, bytes redeemerOutputScript, address redeemer, uint64 requestedAmount, uint64 treasuryFee, uint64 txMaxFee) +``` + +### RedemptionsCompleted + +```solidity +event RedemptionsCompleted(bytes20 walletPubKeyHash, bytes32 redemptionTxHash) +``` + +### RedemptionTimedOut + +```solidity +event RedemptionTimedOut(bytes20 walletPubKeyHash, bytes redeemerOutputScript) +``` + +### requestRedemption + +```solidity +function requestRedemption(struct BridgeState.Storage self, bytes20 walletPubKeyHash, struct BitcoinTx.UTXO mainUtxo, address balanceOwner, bytes redeemerOutputScript, uint64 amount) external +``` + +Requests redemption of the given amount from the specified +wallet to the redeemer Bitcoin output script. +This function handles the simplest case, where balance owner is +the redeemer. + +Requirements: +- Wallet behind `walletPubKeyHash` must be live, +- `mainUtxo` components must point to the recent main UTXO +of the given wallet, as currently known on the Ethereum chain, +- `redeemerOutputScript` must be a proper Bitcoin script, +- `redeemerOutputScript` cannot have wallet PKH as payload, +- `amount` must be above or equal the `redemptionDustThreshold`, +- Given `walletPubKeyHash` and `redeemerOutputScript` pair can be +used for only one pending request at the same time, +- Wallet must have enough Bitcoin balance to proceed the request, +- Balance owner must make an allowance in the Bank that the Bridge +contract can spend the given `amount`. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| self | struct BridgeState.Storage | | +| walletPubKeyHash | bytes20 | The 20-byte wallet public key hash (computed using Bitcoin HASH160 over the compressed ECDSA public key). | +| mainUtxo | struct BitcoinTx.UTXO | Data of the wallet's main UTXO, as currently known on the Ethereum chain. | +| balanceOwner | address | The address of the Bank balance owner whose balance is getting redeemed. Balance owner address is stored as a redeemer address who will be able co claim back the Bank balance if anything goes wrong during the redemption. | +| redeemerOutputScript | bytes | The redeemer's length-prefixed output script (P2PKH, P2WPKH, P2SH or P2WSH) that will be used to lock redeemed BTC. | +| amount | uint64 | Requested amount in satoshi. This is also the Bank balance that is taken from the `balanceOwner` upon request. Once the request is handled, the actual amount of BTC locked on the redeemer output script will be always lower than this value since the treasury and Bitcoin transaction fees must be incurred. The minimal amount satisfying the request can be computed as: `amount - (amount / redemptionTreasuryFeeDivisor) - redemptionTxMaxFee`. Fees values are taken at the moment of request creation. | + +### requestRedemption + +```solidity +function requestRedemption(struct BridgeState.Storage self, address balanceOwner, uint64 amount, bytes redemptionData) external +``` + +Requests redemption of the given amount from the specified +wallet to the redeemer Bitcoin output script. Used by +`Bridge.receiveBalanceApproval`. Can handle more complex cases +where balance owner may be someone else than the redeemer. + +Requirements: +- Wallet behind `walletPubKeyHash` must be live, +- `mainUtxo*` components must point to the recent main UTXO +of the given wallet, as currently known on the Ethereum chain, +- `redeemerOutputScript` must be a proper Bitcoin script, +- `redeemerOutputScript` cannot have wallet PKH as payload, +- `amount` must be above or equal the `redemptionDustThreshold`, +- Given `walletPubKeyHash` and `redeemerOutputScript` pair can be +used for only one pending request at the same time, +- Wallet must have enough Bitcoin balance to proceed the request, +- Balance owner must make an allowance in the Bank that the Bridge +contract can spend the given `amount`. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| self | struct BridgeState.Storage | | +| balanceOwner | address | The address of the Bank balance owner whose balance is getting redeemed. | +| amount | uint64 | Requested amount in satoshi. This is also the Bank balance that is taken from the `balanceOwner` upon request. Once the request is handled, the actual amount of BTC locked on the redeemer output script will be always lower than this value since the treasury and Bitcoin transaction fees must be incurred. The minimal amount satisfying the request can be computed as: `amount - (amount / redemptionTreasuryFeeDivisor) - redemptionTxMaxFee`. Fees values are taken at the moment of request creation. | +| redemptionData | bytes | ABI-encoded redemption data: [ address redeemer, bytes20 walletPubKeyHash, bytes32 mainUtxoTxHash, uint32 mainUtxoTxOutputIndex, uint64 mainUtxoTxOutputValue, bytes redeemerOutputScript ] - redeemer: The Ethereum address of the redeemer who will be able to claim Bank balance if anything goes wrong during the redemption. In the most basic case, when someone redeems their Bitcoin balance from the Bank, `balanceOwner` is the same as `redeemer`. However, when a Vault is redeeming part of its balance for some redeemer address (for example, someone who has earlier deposited into that Vault), `balanceOwner` is the Vault, and `redeemer` is the address for which the vault is redeeming its balance to, - walletPubKeyHash: The 20-byte wallet public key hash (computed using Bitcoin HASH160 over the compressed ECDSA public key), - mainUtxoTxHash: Data of the wallet's main UTXO TX hash, as currently known on the Ethereum chain, - mainUtxoTxOutputIndex: Data of the wallet's main UTXO output index, as currently known on Ethereum chain, - mainUtxoTxOutputValue: Data of the wallet's main UTXO output value, as currently known on Ethereum chain, - redeemerOutputScript The redeemer's length-prefixed output script (P2PKH, P2WPKH, P2SH or P2WSH) that will be used to lock redeemed BTC. | + +### requestRedemption + +```solidity +function requestRedemption(struct BridgeState.Storage self, bytes20 walletPubKeyHash, struct BitcoinTx.UTXO mainUtxo, address balanceOwner, address redeemer, bytes redeemerOutputScript, uint64 amount) internal +``` + +Requests redemption of the given amount from the specified +wallet to the redeemer Bitcoin output script. + +Requirements: +- Wallet behind `walletPubKeyHash` must be live, +- `mainUtxo` components must point to the recent main UTXO +of the given wallet, as currently known on the Ethereum chain, +- `redeemerOutputScript` must be a proper Bitcoin script, +- `redeemerOutputScript` cannot have wallet PKH as payload, +- `amount` must be above or equal the `redemptionDustThreshold`, +- Given `walletPubKeyHash` and `redeemerOutputScript` pair can be +used for only one pending request at the same time, +- Wallet must have enough Bitcoin balance to proceed the request, +- Balance owner must make an allowance in the Bank that the Bridge +contract can spend the given `amount`. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| self | struct BridgeState.Storage | | +| walletPubKeyHash | bytes20 | The 20-byte wallet public key hash (computed using Bitcoin HASH160 over the compressed ECDSA public key). | +| mainUtxo | struct BitcoinTx.UTXO | Data of the wallet's main UTXO, as currently known on the Ethereum chain. | +| balanceOwner | address | The address of the Bank balance owner whose balance is getting redeemed. | +| redeemer | address | The Ethereum address of the redeemer who will be able to claim Bank balance if anything goes wrong during the redemption. In the most basic case, when someone redeems their Bitcoin balance from the Bank, `balanceOwner` is the same as `redeemer`. However, when a Vault is redeeming part of its balance for some redeemer address (for example, someone who has earlier deposited into that Vault), `balanceOwner` is the Vault, and `redeemer` is the address for which the vault is redeeming its balance to. | +| redeemerOutputScript | bytes | The redeemer's length-prefixed output script (P2PKH, P2WPKH, P2SH or P2WSH) that will be used to lock redeemed BTC. | +| amount | uint64 | Requested amount in satoshi. This is also the Bank balance that is taken from the `balanceOwner` upon request. Once the request is handled, the actual amount of BTC locked on the redeemer output script will be always lower than this value since the treasury and Bitcoin transaction fees must be incurred. The minimal amount satisfying the request can be computed as: `amount - (amount / redemptionTreasuryFeeDivisor) - redemptionTxMaxFee`. Fees values are taken at the moment of request creation. | + +### submitRedemptionProof + +```solidity +function submitRedemptionProof(struct BridgeState.Storage self, struct BitcoinTx.Info redemptionTx, struct BitcoinTx.Proof redemptionProof, struct BitcoinTx.UTXO mainUtxo, bytes20 walletPubKeyHash) external +``` + +Used by the wallet to prove the BTC redemption transaction +and to make the necessary bookkeeping. Redemption is only +accepted if it satisfies SPV proof. + +The function is performing Bank balance updates by burning +the total redeemed Bitcoin amount from Bridge balance and +transferring the treasury fee sum to the treasury address. + +It is possible to prove the given redemption only one time. + +Requirements: +- `redemptionTx` components must match the expected structure. See +`BitcoinTx.Info` docs for reference. Their values must exactly +correspond to appropriate Bitcoin transaction fields to produce +a provable transaction hash, +- The `redemptionTx` should represent a Bitcoin transaction with +exactly 1 input that refers to the wallet's main UTXO. That +transaction should have 1..n outputs handling existing pending +redemption requests or pointing to reported timed out requests. +There can be also 1 optional output representing the +change and pointing back to the 20-byte wallet public key hash. +The change should be always present if the redeemed value sum +is lower than the total wallet's BTC balance, +- `redemptionProof` components must match the expected structure. +See `BitcoinTx.Proof` docs for reference. The `bitcoinHeaders` +field must contain a valid number of block headers, not less +than the `txProofDifficultyFactor` contract constant, +- `mainUtxo` components must point to the recent main UTXO +of the given wallet, as currently known on the Ethereum chain. +Additionally, the recent main UTXO on Ethereum must be set, +- `walletPubKeyHash` must be connected with the main UTXO used +as transaction single input. +Other remarks: +- Putting the change output as the first transaction output can +save some gas because the output processing loop begins each +iteration by checking whether the given output is the change +thus uses some gas for making the comparison. Once the change +is identified, that check is omitted in further iterations. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| self | struct BridgeState.Storage | | +| redemptionTx | struct BitcoinTx.Info | Bitcoin redemption transaction data. | +| redemptionProof | struct BitcoinTx.Proof | Bitcoin redemption proof data. | +| mainUtxo | struct BitcoinTx.UTXO | Data of the wallet's main UTXO, as currently known on the Ethereum chain. | +| walletPubKeyHash | bytes20 | 20-byte public key hash (computed using Bitcoin HASH160 over the compressed ECDSA public key) of the wallet which performed the redemption transaction. | + +### resolveRedeemingWallet + +```solidity +function resolveRedeemingWallet(struct BridgeState.Storage self, bytes20 walletPubKeyHash, struct BitcoinTx.UTXO mainUtxo) internal view returns (struct Wallets.Wallet wallet) +``` + +Resolves redeeming wallet based on the provided wallet public +key hash. Validates the wallet state and current main UTXO, as +currently known on the Ethereum chain. + +Requirements: +- Sweeping wallet must be either in Live or MovingFunds state, +- Main UTXO of the redeeming wallet must exists in the storage, +- The passed `mainUTXO` parameter must be equal to the stored one. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| self | struct BridgeState.Storage | | +| walletPubKeyHash | bytes20 | public key hash of the wallet proving the sweep Bitcoin transaction. | +| mainUtxo | struct BitcoinTx.UTXO | Data of the wallet's main UTXO, as currently known on the Ethereum chain. | + +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +| wallet | struct Wallets.Wallet | Data of the sweeping wallet. | + +### processRedemptionTxOutputs + +```solidity +function processRedemptionTxOutputs(struct BridgeState.Storage self, bytes redemptionTxOutputVector, bytes20 walletPubKeyHash) internal returns (struct Redemption.RedemptionTxOutputsInfo info) +``` + +Processes the Bitcoin redemption transaction output vector. +It extracts each output and tries to identify it as a pending +redemption request, reported timed out request, or change. +Reverts if one of the outputs cannot be recognized properly. +This function also marks each request as processed by removing +them from `pendingRedemptions` mapping. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| self | struct BridgeState.Storage | | +| redemptionTxOutputVector | bytes | Bitcoin redemption transaction output vector. This function assumes vector's structure is valid so it must be validated using e.g. `BTCUtils.validateVout` function before it is passed here. | +| walletPubKeyHash | bytes20 | 20-byte public key hash (computed using Bitcoin HASH160 over the compressed ECDSA public key) of the wallet which performed the redemption transaction. | + +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +| info | struct Redemption.RedemptionTxOutputsInfo | Outcomes of the processing. | + +### processRedemptionTxOutputs + +```solidity +function processRedemptionTxOutputs(struct BridgeState.Storage self, bytes redemptionTxOutputVector, bytes20 walletPubKeyHash, struct Redemption.RedemptionTxOutputsProcessingInfo processInfo) internal returns (struct Redemption.RedemptionTxOutputsInfo resultInfo) +``` + +Processes all outputs from the redemption transaction. Tries to +identify output as a change output, pending redemption request +or reported redemption. Reverts if one of the outputs cannot be +recognized properly. Marks each request as processed by removing +them from `pendingRedemptions` mapping. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| self | struct BridgeState.Storage | | +| redemptionTxOutputVector | bytes | Bitcoin redemption transaction output vector. This function assumes vector's structure is valid so it must be validated using e.g. `BTCUtils.validateVout` function before it is passed here. | +| walletPubKeyHash | bytes20 | 20-byte public key hash (computed using Bitcoin HASH160 over the compressed ECDSA public key) of the wallet which performed the redemption transaction. | +| processInfo | struct Redemption.RedemptionTxOutputsProcessingInfo | RedemptionTxOutputsProcessingInfo identifying output starting index, the number of outputs and possible wallet change P2PKH and P2WPKH scripts. | + +### processNonChangeRedemptionTxOutput + +```solidity +function processNonChangeRedemptionTxOutput(struct BridgeState.Storage self, uint256 redemptionKey, uint64 outputValue) internal returns (uint64 burnableValue, uint64 treasuryFee) +``` + +Processes a single redemption transaction output. Tries to +identify output as a pending redemption request or reported +redemption timeout. Output script passed to this function must +not be the change output. Such output needs to be identified +separately before calling this function. +Reverts if output is neither requested pending redemption nor +requested and reported timed-out redemption. +This function also marks each pending request as processed by +removing them from `pendingRedemptions` mapping. + +Requirements: +- This function should be called only if the given output +represents redemption. It must not be the change output. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| self | struct BridgeState.Storage | | +| redemptionKey | uint256 | Redemption key of the output being processed. | +| outputValue | uint64 | Value of the output being processed. | + +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +| burnableValue | uint64 | The value burnable as a result of processing this single redemption output. This value needs to be summed up with burnable values of all other outputs to evaluate total burnable value for the entire redemption transaction. This value is 0 for a timed-out redemption request. | +| treasuryFee | uint64 | The treasury fee from this single redemption output. This value needs to be summed up with treasury fees of all other outputs to evaluate the total treasury fee for the entire redemption transaction. This value is 0 for a timed-out redemption request. | + +### notifyRedemptionTimeout + +```solidity +function notifyRedemptionTimeout(struct BridgeState.Storage self, bytes20 walletPubKeyHash, uint32[] walletMembersIDs, bytes redeemerOutputScript) external +``` + +Notifies that there is a pending redemption request associated +with the given wallet, that has timed out. The redemption +request is identified by the key built as +`keccak256(keccak256(redeemerOutputScript) | walletPubKeyHash)`. +The results of calling this function: +- the pending redemptions value for the wallet will be decreased +by the requested amount (minus treasury fee), +- the tokens taken from the redeemer on redemption request will +be returned to the redeemer, +- the request will be moved from pending redemptions to +timed-out redemptions, +- if the state of the wallet is `Live` or `MovingFunds`, the +wallet operators will be slashed and the notifier will be +rewarded, +- if the state of wallet is `Live`, the wallet will be closed or +marked as `MovingFunds` (depending on the presence or absence +of the wallet's main UTXO) and the wallet will no longer be +marked as the active wallet (if it was marked as such). + +Requirements: +- The wallet must be in the Live or MovingFunds or Terminated state, +- The redemption request identified by `walletPubKeyHash` and +`redeemerOutputScript` must exist, +- 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 of the `WalletRegistry` contract, +- The amount of time defined by `redemptionTimeout` must have +passed since the redemption was requested (the request must be +timed-out). + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| self | struct BridgeState.Storage | | +| walletPubKeyHash | bytes20 | 20-byte public key hash of the wallet. | +| walletMembersIDs | uint32[] | Identifiers of the wallet signing group members. | +| redeemerOutputScript | bytes | The redeemer's length-prefixed output script (P2PKH, P2WPKH, P2SH or P2WSH). | + +### getRedemptionKey + +```solidity +function getRedemptionKey(bytes20 walletPubKeyHash, bytes script) internal pure returns (uint256) +``` + +Calculate redemption key without allocations. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| walletPubKeyHash | bytes20 | the pubkey hash of the wallet. | +| script | bytes | the output script of the redemption. | + +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +| [0] | uint256 | The key = keccak256(keccak256(script) | walletPubKeyHash). | + +### _getRedemptionKey + +```solidity +function _getRedemptionKey(bytes20 walletPubKeyHash, bytes32 scriptHash) internal pure returns (uint256) +``` + +Finish calculating redemption key without allocations. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| walletPubKeyHash | bytes20 | the pubkey hash of the wallet. | +| scriptHash | bytes32 | the output script hash of the redemption. | + +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +| [0] | uint256 | The key = keccak256(scriptHash | walletPubKeyHash). | + diff --git a/docs/app-development/tbtc-v2/tbtc-v2-api/generated-docs/bridge/VendingMachine.md b/docs/app-development/tbtc-v2/tbtc-v2-api/generated-docs/bridge/VendingMachine.md new file mode 100644 index 0000000..03e7418 --- /dev/null +++ b/docs/app-development/tbtc-v2/tbtc-v2-api/generated-docs/bridge/VendingMachine.md @@ -0,0 +1,368 @@ +# Solidity API + +## VendingMachine + +The Vending Machine is the owner of TBTC v2 token and can mint +TBTC v2 tokens in 1:1 ratio from TBTC v1 tokens with TBTC v1 +deposited in the contract as collateral. TBTC v2 can be +unminted back to TBTC v1 with or without a fee - fee parameter is +controlled by the Governance. This implementation acts as a bridge +between TBTC v1 and TBTC v2 token, allowing to mint TBTC v2 before +the system is ready and fully operational without sacrificing any +security guarantees and decentralization of the project. +Vending Machine can be upgraded in a two-step, governance-controlled +process. The new version of the Vending Machine will receive the +ownership of TBTC v2 token and entire TBTC v1 balance stored as +collateral. It is expected that this process will be executed before +the v2 system launch. There is an optional unmint fee with a value +that can be updated in a two-step, governance-controlled process. +All governable parameters are controlled by two roles: update +initiator and finalizer. There is a separate initiator role for +unmint fee update and vending machine upgrade. The initiator +proposes the change by initiating the update and the finalizer +(contract owner) may approve it by finalizing the change after the +governance delay passes. + +### GOVERNANCE_DELAY + +```solidity +uint256 GOVERNANCE_DELAY +``` + +The time delay that needs to pass between initializing and +finalizing update of any governable parameter in this contract. + +### FLOATING_POINT_DIVISOR + +```solidity +uint256 FLOATING_POINT_DIVISOR +``` + +Divisor for precision purposes. Used to represent fractions +in parameter values. + +### tbtcV1 + +```solidity +contract IERC20 tbtcV1 +``` + +### tbtcV2 + +```solidity +contract TBTC tbtcV2 +``` + +### unmintFee + +```solidity +uint256 unmintFee +``` + +The fee for unminting TBTC v2 back into TBTC v1 represented as +1e18 precision fraction. The fee is proportional to the amount +being unminted and added on the top of the amount being unminted. +To calculate the fee value, the amount being unminted needs +to be multiplied by `unmintFee` and divided by 1e18. +For example, `unmintFee` set to 1000000000000000 +means that 0.001 of the amount being unminted needs to be paid +to the `VendingMachine` as an unminting fee on the top of the +amount being unminted. + +### newUnmintFee + +```solidity +uint256 newUnmintFee +``` + +### unmintFeeUpdateInitiatedTimestamp + +```solidity +uint256 unmintFeeUpdateInitiatedTimestamp +``` + +### unmintFeeUpdateInitiator + +```solidity +address unmintFeeUpdateInitiator +``` + +### newVendingMachine + +```solidity +address newVendingMachine +``` + +The address of a new vending machine. Set only when the upgrade +process is pending. Once the upgrade gets finalized, the new +vending machine will become an owner of TBTC v2 token. + +### vendingMachineUpgradeInitiatedTimestamp + +```solidity +uint256 vendingMachineUpgradeInitiatedTimestamp +``` + +### vendingMachineUpgradeInitiator + +```solidity +address vendingMachineUpgradeInitiator +``` + +### UnmintFeeUpdateInitiated + +```solidity +event UnmintFeeUpdateInitiated(uint256 newUnmintFee, uint256 timestamp) +``` + +### UnmintFeeUpdated + +```solidity +event UnmintFeeUpdated(uint256 newUnmintFee) +``` + +### VendingMachineUpgradeInitiated + +```solidity +event VendingMachineUpgradeInitiated(address newVendingMachine, uint256 timestamp) +``` + +### VendingMachineUpgraded + +```solidity +event VendingMachineUpgraded(address newVendingMachine) +``` + +### Minted + +```solidity +event Minted(address recipient, uint256 amount) +``` + +### Unminted + +```solidity +event Unminted(address recipient, uint256 amount, uint256 fee) +``` + +### only + +```solidity +modifier only(address authorizedCaller) +``` + +### onlyAfterGovernanceDelay + +```solidity +modifier onlyAfterGovernanceDelay(uint256 changeInitiatedTimestamp) +``` + +### constructor + +```solidity +constructor(contract IERC20 _tbtcV1, contract TBTC _tbtcV2, uint256 _unmintFee) public +``` + +### mint + +```solidity +function mint(uint256 amount) external +``` + +Mints TBTC v2 to the caller from TBTC v1 with 1:1 ratio. +The caller needs to have at least `amount` of TBTC v1 balance +approved for transfer to the `VendingMachine` before calling +this function. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| amount | uint256 | The amount of TBTC v2 to mint from TBTC v1 | + +### receiveApproval + +```solidity +function receiveApproval(address from, uint256 amount, address token, bytes) external +``` + +Mints TBTC v2 to `from` address from TBTC v1 with 1:1 ratio. +`from` address needs to have at least `amount` of TBTC v1 +balance approved for transfer to the `VendingMachine` before +calling this function. + +This function is a shortcut for approve + mint. Only TBTC v1 +caller is allowed and only TBTC v1 is allowed as a token to +transfer. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| from | address | TBTC v1 token holder minting TBTC v2 tokens | +| amount | uint256 | The amount of TBTC v2 to mint from TBTC v1 | +| token | address | TBTC v1 token address | +| | bytes | | + +### unmint + +```solidity +function unmint(uint256 amount) external +``` + +Unmints TBTC v2 from the caller into TBTC v1. Depending on +`unmintFee` value, may require paying an additional unmint fee +in TBTC v2 in addition to the amount being unminted. To see +what is the value of the fee, please call `unmintFeeFor(amount)` +function. The caller needs to have at least +`amount + unmintFeeFor(amount)` of TBTC v2 balance approved for +transfer to the `VendingMachine` before calling this function. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| amount | uint256 | The amount of TBTC v2 to unmint to TBTC v1 | + +### withdrawFees + +```solidity +function withdrawFees(address recipient, uint256 amount) external +``` + +Allows the Governance to withdraw unmint fees accumulated by +`VendingMachine`. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| recipient | address | The address receiving the fees | +| amount | uint256 | The amount of fees in TBTC v2 to withdraw | + +### initiateUnmintFeeUpdate + +```solidity +function initiateUnmintFeeUpdate(uint256 _newUnmintFee) external +``` + +Initiates unmint fee update process. The update process needs to +be finalized with a call to `finalizeUnmintFeeUpdate` function +after the `GOVERNANCE_DELAY` passes. Only unmint fee update +initiator role can initiate the update. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| _newUnmintFee | uint256 | The new unmint fee | + +### finalizeUnmintFeeUpdate + +```solidity +function finalizeUnmintFeeUpdate() external +``` + +Allows the contract owner to finalize unmint fee update process. +The update process needs to be first initiated with a call to +`initiateUnmintFeeUpdate` and the `GOVERNANCE_DELAY` needs to +pass. + +### initiateVendingMachineUpgrade + +```solidity +function initiateVendingMachineUpgrade(address _newVendingMachine) external +``` + +Initiates vending machine upgrade process. The upgrade process +needs to be finalized with a call to +`finalizeVendingMachineUpgrade` function after the +`GOVERNANCE_DELAY` passes. Only vending machine upgrade +initiator role can initiate the upgrade. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| _newVendingMachine | address | The new vending machine address | + +### finalizeVendingMachineUpgrade + +```solidity +function finalizeVendingMachineUpgrade() external +``` + +Allows the contract owner to finalize vending machine upgrade +process. The upgrade process needs to be first initiated with a +call to `initiateVendingMachineUpgrade` and the `GOVERNANCE_DELAY` +needs to pass. Once the upgrade is finalized, the new vending +machine will become an owner of TBTC v2 token and all TBTC v1 +held by this contract will be transferred to the new vending +machine. + +### transferUnmintFeeUpdateInitiatorRole + +```solidity +function transferUnmintFeeUpdateInitiatorRole(address newInitiator) external +``` + +Transfers unmint fee update initiator role to another address. +Can be called only by the current unmint fee update initiator. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| newInitiator | address | The new unmint fee update initiator | + +### transferVendingMachineUpgradeInitiatorRole + +```solidity +function transferVendingMachineUpgradeInitiatorRole(address newInitiator) external +``` + +Transfers vending machine upgrade initiator role to another +address. Can be called only by the current vending machine +upgrade initiator. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| newInitiator | address | The new vending machine upgrade initiator | + +### getRemainingUnmintFeeUpdateTime + +```solidity +function getRemainingUnmintFeeUpdateTime() external view returns (uint256) +``` + +Get the remaining time that needs to pass until unmint fee +update can be finalized by the Governance. If the update has +not been initiated, the function reverts. + +### getRemainingVendingMachineUpgradeTime + +```solidity +function getRemainingVendingMachineUpgradeTime() external view returns (uint256) +``` + +Get the remaining time that needs to pass until vending machine +upgrade can be finalized by the Governance. If the upgrade has +not been initiated, the function reverts. + +### unmintFeeFor + +```solidity +function unmintFeeFor(uint256 amount) public view returns (uint256) +``` + +Calculates the fee that needs to be paid to the `VendingMachine` +to unmint the given amount of TBTC v2 back into TBTC v1. + +### _mint + +```solidity +function _mint(address tokenOwner, uint256 amount) internal +``` + diff --git a/docs/app-development/tbtc-v2/tbtc-v2-api/generated-docs/bridge/VendingMachineV2.md b/docs/app-development/tbtc-v2/tbtc-v2-api/generated-docs/bridge/VendingMachineV2.md new file mode 100644 index 0000000..b12f9f3 --- /dev/null +++ b/docs/app-development/tbtc-v2/tbtc-v2-api/generated-docs/bridge/VendingMachineV2.md @@ -0,0 +1,145 @@ +# Solidity API + +## VendingMachineV2 + +VendingMachineV2 is used to exchange tBTC v1 to tBTC v2 in a 1:1 +ratio during the process of tBTC v1 bridge sunsetting. The redeemer +selected by the DAO based on the "TIP-027b tBTC v1: The Sunsetting" +proposal will deposit tBTC v2 tokens into VendingMachineV2 so that +outstanding tBTC v1 token owners can upgrade to tBTC v2 tokens. +The redeemer will withdraw the tBTC v1 tokens deposited into the +contract to perform tBTC v1 redemptions. +The redeemer may decide to withdraw their deposited tBTC v2 at any +moment in time. The amount withdrawable is lower than the amount +deposited in case tBTC v1 was exchanged for tBTC v2. +This contract is owned by the redeemer. + +### tbtcV1 + +```solidity +contract IERC20 tbtcV1 +``` + +### tbtcV2 + +```solidity +contract TBTC tbtcV2 +``` + +### Exchanged + +```solidity +event Exchanged(address to, uint256 amount) +``` + +### Deposited + +```solidity +event Deposited(address from, uint256 amount) +``` + +### Withdrawn + +```solidity +event Withdrawn(address token, address to, uint256 amount) +``` + +### constructor + +```solidity +constructor(contract IERC20 _tbtcV1, contract TBTC _tbtcV2) public +``` + +### exchange + +```solidity +function exchange(uint256 amount) external +``` + +Exchange tBTC v1 for tBTC v2 in a 1:1 ratio. +The caller needs to have at least `amount` of tBTC v1 balance +approved for transfer to the `VendingMachineV2` before calling +this function. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| amount | uint256 | The amount of tBTC v1 to exchange for tBTC v2. | + +### receiveApproval + +```solidity +function receiveApproval(address from, uint256 amount, address token, bytes) external +``` + +Exchange tBTC v1 for tBTC v2 in a 1:1 ratio. +The caller needs to have at least `amount` of tBTC v1 balance +approved for transfer to the `VendingMachineV2` before calling +this function. + +This function is a shortcut for `approve` + `exchange`. Only tBTC +v1 token caller is allowed and only tBTC v1 is allowed as a token +to transfer. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| from | address | tBTC v1 token holder exchanging tBTC v1 to tBTC v2. | +| amount | uint256 | The amount of tBTC v1 to exchange for tBTC v2. | +| token | address | tBTC v1 token address. | +| | bytes | | + +### depositTbtcV2 + +```solidity +function depositTbtcV2(uint256 amount) external +``` + +Allows to deposit tBTC v2 tokens to the contract. +VendingMachineV2 can not mint tBTC v2 tokens so tBTC v2 needs +to be deposited into the contract so that tBTC v1 to tBTC v2 +exchange can happen. +The caller needs to have at least `amount` of tBTC v2 balance +approved for transfer to the `VendingMachineV2` before calling +this function. + +This function is for the redeemer and tBTC v1 operators. This is +NOT a function for tBTC v1 token holders. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| amount | uint256 | The amount of tBTC v2 to deposit into the contract. | + +### withdrawFunds + +```solidity +function withdrawFunds(contract IERC20 token, address recipient, uint256 amount) external +``` + +Allows the contract owner to withdraw tokens. This function is +used in two cases: 1) when the redeemer wants to redeem tBTC v1 +tokens to perform tBTC v2 redemptions; 2) when the deadline for +tBTC v1 -> tBTC v2 exchange passed and the redeemer wants their +tBTC v2 back. + +This function is for the redeemer. This is NOT a function for +tBTC v1 token holders. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| token | contract IERC20 | The address of a token to withdraw. | +| recipient | address | The address which should receive withdrawn tokens. | +| amount | uint256 | The amount to withdraw. | + +### _exchange + +```solidity +function _exchange(address tokenOwner, uint256 amount) internal +``` + diff --git a/docs/app-development/tbtc-v2/tbtc-v2-api/generated-docs/bridge/VendingMachineV3.md b/docs/app-development/tbtc-v2/tbtc-v2-api/generated-docs/bridge/VendingMachineV3.md new file mode 100644 index 0000000..337ab19 --- /dev/null +++ b/docs/app-development/tbtc-v2/tbtc-v2-api/generated-docs/bridge/VendingMachineV3.md @@ -0,0 +1,163 @@ +# Solidity API + +## VendingMachineV3 + +VendingMachineV3 is used to exchange tBTC v1 to tBTC v2 in a 1:1 +ratio after the tBTC v1 bridge sunsetting is completed. Since +tBTC v1 bridge is no longer working, tBTC v1 tokens can not be used +to perform BTC redemptions. This contract allows tBTC v1 owners to +upgrade to tBTC v2 without any deadline. This way, tBTC v1 tokens +left on the market are always backed by Bitcoin. The governance will +deposit tBTC v2 into the contract in the amount equal to tBTC v1 +supply. The governance is allowed to withdraw tBTC v2 only if tBTC +v2 left in this contract is enough to cover the upgrade of all tBTC +v1 left on the market. This contract is owned by the governance. + +### tbtcV1 + +```solidity +contract IERC20 tbtcV1 +``` + +### tbtcV2 + +```solidity +contract TBTC tbtcV2 +``` + +### Exchanged + +```solidity +event Exchanged(address to, uint256 amount) +``` + +### Deposited + +```solidity +event Deposited(address from, uint256 amount) +``` + +### TbtcV2Withdrawn + +```solidity +event TbtcV2Withdrawn(address to, uint256 amount) +``` + +### FundsRecovered + +```solidity +event FundsRecovered(address token, address to, uint256 amount) +``` + +### constructor + +```solidity +constructor(contract IERC20 _tbtcV1, contract TBTC _tbtcV2) public +``` + +### exchange + +```solidity +function exchange(uint256 amount) external +``` + +Exchange tBTC v1 for tBTC v2 in a 1:1 ratio. +The caller needs to have at least `amount` of tBTC v1 balance +approved for transfer to the `VendingMachineV3` before calling +this function. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| amount | uint256 | The amount of tBTC v1 to exchange for tBTC v2. | + +### receiveApproval + +```solidity +function receiveApproval(address from, uint256 amount, address token, bytes) external +``` + +Exchange tBTC v1 for tBTC v2 in a 1:1 ratio. +The caller needs to have at least `amount` of tBTC v1 balance +approved for transfer to the `VendingMachineV3` before calling +this function. + +This function is a shortcut for `approve` + `exchange`. Only tBTC +v1 caller is allowed and only tBTC v1 is allowed as a token to +transfer. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| from | address | tBTC v1 token holder exchanging tBTC v1 to tBTC v2. | +| amount | uint256 | The amount of tBTC v1 to exchange for tBTC v2. | +| token | address | tBTC v1 token address. | +| | bytes | | + +### depositTbtcV2 + +```solidity +function depositTbtcV2(uint256 amount) external +``` + +Allows to deposit tBTC v2 tokens to the contract. +`VendingMachineV3` can not mint tBTC v2 tokens so tBTC v2 needs +to be deposited into the contract so that tBTC v1 to tBTC v2 +exchange can happen. +The caller needs to have at least `amount` of tBTC v2 balance +approved for transfer to the `VendingMachineV3` before calling +this function. + +This function is for the redeemer and tBTC v1 operators. This is +NOT a function for tBTC v1 token holders. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| amount | uint256 | The amount of tBTC v2 to deposit into the contract. | + +### withdrawTbtcV2 + +```solidity +function withdrawTbtcV2(address recipient, uint256 amount) external +``` + +Allows the governance to withdraw tBTC v2 deposited into this +contract. The governance is allowed to withdraw tBTC v2 +only if tBTC v2 left in this contract is enough to cover the +upgrade of all tBTC v1 left on the market. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| recipient | address | The address which should receive withdrawn tokens. | +| amount | uint256 | The amount to withdraw. | + +### recoverFunds + +```solidity +function recoverFunds(contract IERC20 token, address recipient, uint256 amount) external +``` + +Allows the governance to recover ERC20 sent to this contract +by mistake or tBTC v1 locked in the contract to exchange to +tBTC v2. No tBTC v2 can be withdrawn using this function. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| token | contract IERC20 | The address of a token to recover. | +| recipient | address | The address which should receive recovered tokens. | +| amount | uint256 | The amount to recover. | + +### _exchange + +```solidity +function _exchange(address tokenOwner, uint256 amount) internal +``` + diff --git a/docs/app-development/tbtc-v2/tbtc-v2-api/generated-docs/bridge/WalletCoordinator.md b/docs/app-development/tbtc-v2/tbtc-v2-api/generated-docs/bridge/WalletCoordinator.md new file mode 100644 index 0000000..04dd39c --- /dev/null +++ b/docs/app-development/tbtc-v2/tbtc-v2-api/generated-docs/bridge/WalletCoordinator.md @@ -0,0 +1,724 @@ +# Solidity API + +## WalletCoordinator + +The wallet coordinator contract aims to facilitate the coordination +of the off-chain wallet members during complex multi-chain wallet +operations like deposit sweeping, redemptions, or moving funds. +Such processes involve various moving parts and many steps that each +individual wallet member must do. Given the distributed nature of +the off-chain wallet software, full off-chain implementation is +challenging and prone to errors, especially byzantine faults. +This contract provides a single and trusted on-chain coordination +point thus taking the riskiest part out of the off-chain software. +The off-chain wallet members can focus on the core tasks and do not +bother about electing a trusted coordinator or aligning internal +states using complex consensus algorithms. + +### WalletAction + +```solidity +enum WalletAction { + Idle, + Heartbeat, + DepositSweep, + Redemption, + MovingFunds, + MovedFundsSweep +} +``` + +### WalletLock + +```solidity +struct WalletLock { + uint32 expiresAt; + enum WalletCoordinator.WalletAction cause; +} +``` + +### DepositSweepProposal + +```solidity +struct DepositSweepProposal { + bytes20 walletPubKeyHash; + struct WalletCoordinator.DepositKey[] depositsKeys; + uint256 sweepTxFee; + uint256[] depositsRevealBlocks; +} +``` + +### DepositKey + +```solidity +struct DepositKey { + bytes32 fundingTxHash; + uint32 fundingOutputIndex; +} +``` + +### DepositExtraInfo + +```solidity +struct DepositExtraInfo { + struct BitcoinTx.Info fundingTx; + bytes8 blindingFactor; + bytes20 walletPubKeyHash; + bytes20 refundPubKeyHash; + bytes4 refundLocktime; +} +``` + +### RedemptionProposal + +```solidity +struct RedemptionProposal { + bytes20 walletPubKeyHash; + bytes[] redeemersOutputScripts; + uint256 redemptionTxFee; +} +``` + +### isCoordinator + +```solidity +mapping(address => bool) isCoordinator +``` + +Mapping that holds addresses allowed to submit proposals and +request heartbeats. + +### walletLock + +```solidity +mapping(bytes20 => struct WalletCoordinator.WalletLock) walletLock +``` + +Mapping that holds wallet time locks. The key is a 20-byte +wallet public key hash. + +### bridge + +```solidity +contract Bridge bridge +``` + +Handle to the Bridge contract. + +### heartbeatRequestValidity + +```solidity +uint32 heartbeatRequestValidity +``` + +Determines the wallet heartbeat request validity time. In other +words, this is the worst-case time for a wallet heartbeat +during which the wallet is busy and canot take other actions. +This is also the duration of the time lock applied to the wallet +once a new heartbeat request is submitted. + +For example, if a deposit sweep proposal was submitted at +2 pm and heartbeatRequestValidity is 1 hour, the next request or +proposal (of any type) can be submitted after 3 pm. + +### heartbeatRequestGasOffset + +```solidity +uint32 heartbeatRequestGasOffset +``` + +Gas that is meant to balance the heartbeat request overall cost. +Can be updated by the owner based on the current conditions. + +### depositSweepProposalValidity + +```solidity +uint32 depositSweepProposalValidity +``` + +Determines the deposit sweep proposal validity time. In other +words, this is the worst-case time for a deposit sweep during +which the wallet is busy and cannot take another actions. This +is also the duration of the time lock applied to the wallet +once a new deposit sweep proposal is submitted. + +For example, if a deposit sweep proposal was submitted at +2 pm and depositSweepProposalValidity is 4 hours, the next +proposal (of any type) can be submitted after 6 pm. + +### depositMinAge + +```solidity +uint32 depositMinAge +``` + +The minimum time that must elapse since the deposit reveal +before a deposit becomes eligible for a deposit sweep. + +For example, if a deposit was revealed at 9 am and depositMinAge +is 2 hours, the deposit is eligible for sweep after 11 am. + +Forcing deposit minimum age ensures block finality for Ethereum. +In the happy path case, i.e. where the deposit is revealed immediately +after being broadcast on the Bitcoin network, the minimum age +check also ensures block finality for Bitcoin. + +### depositRefundSafetyMargin + +```solidity +uint32 depositRefundSafetyMargin +``` + +Each deposit can be technically swept until it reaches its +refund timestamp after which it can be taken back by the depositor. +However, allowing the wallet to sweep deposits that are close +to their refund timestamp may cause a race between the wallet +and the depositor. In result, the wallet may sign an invalid +sweep transaction that aims to sweep an already refunded deposit. +Such tx signature may be used to create an undefeatable fraud +challenge against the wallet. In order to mitigate that problem, +this parameter determines a safety margin that puts the latest +moment a deposit can be swept far before the point after which +the deposit becomes refundable. + +For example, if a deposit becomes refundable after 8 pm and +depositRefundSafetyMargin is 6 hours, the deposit is valid for +for a sweep only before 2 pm. + +### depositSweepMaxSize + +```solidity +uint16 depositSweepMaxSize +``` + +The maximum count of deposits that can be swept within a +single sweep. + +### depositSweepProposalSubmissionGasOffset + +```solidity +uint32 depositSweepProposalSubmissionGasOffset +``` + +Gas that is meant to balance the deposit sweep proposal +submission overall cost. Can be updated by the owner based on +the current conditions. + +### redemptionProposalValidity + +```solidity +uint32 redemptionProposalValidity +``` + +Determines the redemption proposal validity time. In other +words, this is the worst-case time for a redemption during +which the wallet is busy and cannot take another actions. This +is also the duration of the time lock applied to the wallet +once a new redemption proposal is submitted. + +For example, if a redemption proposal was submitted at +2 pm and redemptionProposalValidity is 2 hours, the next +proposal (of any type) can be submitted after 4 pm. + +### redemptionRequestMinAge + +```solidity +uint32 redemptionRequestMinAge +``` + +The minimum time that must elapse since the redemption request +creation before a request becomes eligible for a processing. + +For example, if a request was created at 9 am and +redemptionRequestMinAge is 2 hours, the request is eligible for +processing after 11 am. + +Forcing request minimum age ensures block finality for Ethereum. + +### redemptionRequestTimeoutSafetyMargin + +```solidity +uint32 redemptionRequestTimeoutSafetyMargin +``` + +Each redemption request can be technically handled until it +reaches its timeout timestamp after which it can be reported +as timed out. However, allowing the wallet to handle requests +that are close to their timeout timestamp may cause a race +between the wallet and the redeemer. In result, the wallet may +redeem the requested funds even though the redeemer already +received back their tBTC (locked during redemption request) upon +reporting the request timeout. In effect, the redeemer may end +out with both tBTC and redeemed BTC in their hands which has +a negative impact on the tBTC <-> BTC peg. In order to mitigate +that problem, this parameter determines a safety margin that +puts the latest moment a request can be handled far before the +point after which the request can be reported as timed out. + +For example, if a request times out after 8 pm and +redemptionRequestTimeoutSafetyMargin is 2 hours, the request is +valid for processing only before 6 pm. + +### redemptionMaxSize + +```solidity +uint16 redemptionMaxSize +``` + +The maximum count of redemption requests that can be processed +within a single redemption. + +### redemptionProposalSubmissionGasOffset + +```solidity +uint32 redemptionProposalSubmissionGasOffset +``` + +Gas that is meant to balance the redemption proposal +submission overall cost. Can be updated by the owner based on +the current conditions. + +### CoordinatorAdded + +```solidity +event CoordinatorAdded(address coordinator) +``` + +### CoordinatorRemoved + +```solidity +event CoordinatorRemoved(address coordinator) +``` + +### WalletManuallyUnlocked + +```solidity +event WalletManuallyUnlocked(bytes20 walletPubKeyHash) +``` + +### HeartbeatRequestParametersUpdated + +```solidity +event HeartbeatRequestParametersUpdated(uint32 heartbeatRequestValidity, uint32 heartbeatRequestGasOffset) +``` + +### HeartbeatRequestSubmitted + +```solidity +event HeartbeatRequestSubmitted(bytes20 walletPubKeyHash, bytes message, address coordinator) +``` + +### DepositSweepProposalParametersUpdated + +```solidity +event DepositSweepProposalParametersUpdated(uint32 depositSweepProposalValidity, uint32 depositMinAge, uint32 depositRefundSafetyMargin, uint16 depositSweepMaxSize, uint32 depositSweepProposalSubmissionGasOffset) +``` + +### DepositSweepProposalSubmitted + +```solidity +event DepositSweepProposalSubmitted(struct WalletCoordinator.DepositSweepProposal proposal, address coordinator) +``` + +### RedemptionProposalParametersUpdated + +```solidity +event RedemptionProposalParametersUpdated(uint32 redemptionProposalValidity, uint32 redemptionRequestMinAge, uint32 redemptionRequestTimeoutSafetyMargin, uint16 redemptionMaxSize, uint32 redemptionProposalSubmissionGasOffset) +``` + +### RedemptionProposalSubmitted + +```solidity +event RedemptionProposalSubmitted(struct WalletCoordinator.RedemptionProposal proposal, address coordinator) +``` + +### onlyCoordinator + +```solidity +modifier onlyCoordinator() +``` + +### onlyAfterWalletLock + +```solidity +modifier onlyAfterWalletLock(bytes20 walletPubKeyHash) +``` + +### onlyReimbursableAdmin + +```solidity +modifier onlyReimbursableAdmin() +``` + +### initialize + +```solidity +function initialize(contract Bridge _bridge) external +``` + +### addCoordinator + +```solidity +function addCoordinator(address coordinator) external +``` + +Adds the given address to the set of coordinator addresses. + +Requirements: +- The caller must be the owner, +- The `coordinator` must not be an existing coordinator. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| coordinator | address | Address of the new coordinator. | + +### removeCoordinator + +```solidity +function removeCoordinator(address coordinator) external +``` + +Removes the given address from the set of coordinator addresses. + +Requirements: +- The caller must be the owner, +- The `coordinator` must be an existing coordinator. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| coordinator | address | Address of the existing coordinator. | + +### unlockWallet + +```solidity +function unlockWallet(bytes20 walletPubKeyHash) external +``` + +Allows to unlock the given wallet before their time lock expires. +This function should be used in exceptional cases where +something went wrong and there is a need to unlock the wallet +without waiting. + +Requirements: +- The caller must be the owner. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| walletPubKeyHash | bytes20 | 20-byte public key hash of the wallet | + +### updateHeartbeatRequestParameters + +```solidity +function updateHeartbeatRequestParameters(uint32 _heartbeatRequestValidity, uint32 _heartbeatRequestGasOffset) external +``` + +Updates parameters related to heartbeat request. + +Requirements: +- The caller must be the owner. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| _heartbeatRequestValidity | uint32 | The new value of `heartbeatRequestValidity`. | +| _heartbeatRequestGasOffset | uint32 | The new value of `heartbeatRequestGasOffset`. | + +### updateDepositSweepProposalParameters + +```solidity +function updateDepositSweepProposalParameters(uint32 _depositSweepProposalValidity, uint32 _depositMinAge, uint32 _depositRefundSafetyMargin, uint16 _depositSweepMaxSize, uint32 _depositSweepProposalSubmissionGasOffset) external +``` + +Updates parameters related to deposit sweep proposal. + +Requirements: +- The caller must be the owner. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| _depositSweepProposalValidity | uint32 | The new value of `depositSweepProposalValidity`. | +| _depositMinAge | uint32 | The new value of `depositMinAge`. | +| _depositRefundSafetyMargin | uint32 | The new value of `depositRefundSafetyMargin`. | +| _depositSweepMaxSize | uint16 | The new value of `depositSweepMaxSize`. | +| _depositSweepProposalSubmissionGasOffset | uint32 | | + +### requestHeartbeat + +```solidity +function requestHeartbeat(bytes20 walletPubKeyHash, bytes message) public +``` + +Submits a heartbeat request from the wallet. Locks the wallet +for a specific time, equal to the request validity period. +This function validates the proposed heartbeat messge to see +if it matches the heartbeat format expected by the Bridge. + +Requirements: +- The caller is a coordinator, +- The wallet is not time-locked, +- The message to sign is a valid heartbeat message. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| walletPubKeyHash | bytes20 | 20-byte public key hash of the wallet that is supposed to execute the heartbeat. | +| message | bytes | The proposed heartbeat message for the wallet to sign. | + +### requestHeartbeatWithReimbursement + +```solidity +function requestHeartbeatWithReimbursement(bytes20 walletPubKeyHash, bytes message) external +``` + +Wraps `requestHeartbeat` call and reimburses the caller's +transaction cost. + +See `requestHeartbeat` function documentation. + +### submitDepositSweepProposal + +```solidity +function submitDepositSweepProposal(struct WalletCoordinator.DepositSweepProposal proposal) public +``` + +Submits a deposit sweep proposal. Locks the target wallet +for a specific time, equal to the proposal validity period. +This function does not store the proposal in the state but +just emits an event that serves as a guiding light for wallet +off-chain members. Wallet members are supposed to validate +the proposal on their own, before taking any action. + +Requirements: +- The caller is a coordinator, +- The wallet is not time-locked. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| proposal | struct WalletCoordinator.DepositSweepProposal | The deposit sweep proposal | + +### submitDepositSweepProposalWithReimbursement + +```solidity +function submitDepositSweepProposalWithReimbursement(struct WalletCoordinator.DepositSweepProposal proposal) external +``` + +Wraps `submitDepositSweepProposal` call and reimburses the +caller's transaction cost. + +See `submitDepositSweepProposal` function documentation. + +### validateDepositSweepProposal + +```solidity +function validateDepositSweepProposal(struct WalletCoordinator.DepositSweepProposal proposal, struct WalletCoordinator.DepositExtraInfo[] depositsExtraInfo) external view returns (bool) +``` + +View function encapsulating the main rules of a valid deposit +sweep proposal. This function is meant to facilitate the off-chain +validation of the incoming proposals. Thanks to it, most +of the work can be done using a single readonly contract call. +Worth noting, the validation done here is not exhaustive as some +conditions may not be verifiable within the on-chain function or +checking them may be easier on the off-chain side. For example, +this function does not check the SPV proofs and confirmations of +the deposit funding transactions as this would require an +integration with the difficulty relay that greatly increases +complexity. Instead of that, each off-chain wallet member is +supposed to do that check on their own. + +Requirements: +- The target wallet must be in the Live state, +- The number of deposits included in the sweep must be in +the range [1, `depositSweepMaxSize`], +- The length of `depositsExtraInfo` array must be equal to the +length of `proposal.depositsKeys`, i.e. each deposit must +have exactly one set of corresponding extra data, +- The proposed sweep tx fee must be grater than zero, +- The proposed maximum per-deposit sweep tx fee must be lesser than +or equal the maximum fee allowed by the Bridge (`Bridge.depositTxMaxFee`), +- Each deposit must be revealed to the Bridge, +- Each deposit must be old enough, i.e. at least `depositMinAge` +elapsed since their reveal time, +- Each deposit must not be swept yet, +- Each deposit must have valid extra data (see `validateDepositExtraInfo`), +- Each deposit must have the refund safety margin preserved, +- Each deposit must be controlled by the same wallet, +- Each deposit must target the same vault, +- Each deposit must be unique. + +The following off-chain validation must be performed as a bare minimum: +- Inputs used for the sweep transaction have enough Bitcoin confirmations, +- Deposits revealed to the Bridge have enough Ethereum confirmations. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| proposal | struct WalletCoordinator.DepositSweepProposal | The sweeping proposal to validate. | +| depositsExtraInfo | struct WalletCoordinator.DepositExtraInfo[] | Deposits extra data required to perform the validation. | + +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +| [0] | bool | True if the proposal is valid. Reverts otherwise. | + +### validateSweepTxFee + +```solidity +function validateSweepTxFee(uint256 sweepTxFee, uint256 depositsCount) internal view +``` + +Validates the sweep tx fee by checking if the part of the fee +incurred by each deposit does not exceed the maximum value +allowed by the Bridge. This function is heavily based on +`DepositSweep.depositSweepTxFeeDistribution` function. + +Requirements: +- The sweep tx fee must be grater than zero, +- The maximum per-deposit sweep tx fee must be lesser than or equal +the maximum fee allowed by the Bridge (`Bridge.depositTxMaxFee`). + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| sweepTxFee | uint256 | The sweep transaction fee. | +| depositsCount | uint256 | Count of the deposits swept by the sweep transaction. | + +### validateDepositExtraInfo + +```solidity +function validateDepositExtraInfo(struct WalletCoordinator.DepositKey depositKey, address depositor, struct WalletCoordinator.DepositExtraInfo depositExtraInfo) internal view +``` + +Validates the extra data for the given deposit. This function +is heavily based on `Deposit.revealDeposit` function. + +Requirements: +- The transaction hash computed using `depositExtraInfo.fundingTx` +must match the `depositKey.fundingTxHash`. This requirement +ensures the funding transaction data provided in the extra +data container actually represent the funding transaction of +the given deposit. +- The P2(W)SH script inferred from `depositExtraInfo` is actually +used to lock funds by the `depositKey.fundingOutputIndex` output +of the `depositExtraInfo.fundingTx` transaction. This requirement +ensures the reveal data provided in the extra data container +actually matches the given deposit. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| depositKey | struct WalletCoordinator.DepositKey | Key of the given deposit. | +| depositor | address | Depositor that revealed the deposit. | +| depositExtraInfo | struct WalletCoordinator.DepositExtraInfo | Extra data being subject of the validation. | + +### updateRedemptionProposalParameters + +```solidity +function updateRedemptionProposalParameters(uint32 _redemptionProposalValidity, uint32 _redemptionRequestMinAge, uint32 _redemptionRequestTimeoutSafetyMargin, uint16 _redemptionMaxSize, uint32 _redemptionProposalSubmissionGasOffset) external +``` + +Updates parameters related to redemption proposal. + +Requirements: +- The caller must be the owner. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| _redemptionProposalValidity | uint32 | The new value of `redemptionProposalValidity`. | +| _redemptionRequestMinAge | uint32 | The new value of `redemptionRequestMinAge`. | +| _redemptionRequestTimeoutSafetyMargin | uint32 | The new value of `redemptionRequestTimeoutSafetyMargin`. | +| _redemptionMaxSize | uint16 | The new value of `redemptionMaxSize`. | +| _redemptionProposalSubmissionGasOffset | uint32 | The new value of `redemptionProposalSubmissionGasOffset`. | + +### submitRedemptionProposal + +```solidity +function submitRedemptionProposal(struct WalletCoordinator.RedemptionProposal proposal) public +``` + +Submits a redemption proposal. Locks the target wallet +for a specific time, equal to the proposal validity period. +This function does not store the proposal in the state but +just emits an event that serves as a guiding light for wallet +off-chain members. Wallet members are supposed to validate +the proposal on their own, before taking any action. + +Requirements: +- The caller is a coordinator, +- The wallet is not time-locked. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| proposal | struct WalletCoordinator.RedemptionProposal | The redemption proposal | + +### submitRedemptionProposalWithReimbursement + +```solidity +function submitRedemptionProposalWithReimbursement(struct WalletCoordinator.RedemptionProposal proposal) external +``` + +Wraps `submitRedemptionProposal` call and reimburses the +caller's transaction cost. + +See `submitRedemptionProposal` function documentation. + +### validateRedemptionProposal + +```solidity +function validateRedemptionProposal(struct WalletCoordinator.RedemptionProposal proposal) external view returns (bool) +``` + +View function encapsulating the main rules of a valid redemption +proposal. This function is meant to facilitate the off-chain +validation of the incoming proposals. Thanks to it, most +of the work can be done using a single readonly contract call. + +Requirements: +- The target wallet must be in the Live state, +- The number of redemption requests included in the redemption +proposal must be in the range [1, `redemptionMaxSize`], +- The proposed redemption tx fee must be grater than zero, +- The proposed redemption tx fee must be lesser than or equal to +the maximum total fee allowed by the Bridge +(`Bridge.redemptionTxMaxTotalFee`), +- The proposed maximum per-request redemption tx fee share must be +lesser than or equal to the maximum fee share allowed by the +given request (`RedemptionRequest.txMaxFee`), +- Each request must be a pending request registered in the Bridge, +- Each request must be old enough, i.e. at least `redemptionRequestMinAge` +elapsed since their creation time, +- Each request must have the timeout safety margin preserved, +- Each request must be unique. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| proposal | struct WalletCoordinator.RedemptionProposal | The redemption proposal to validate. | + +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +| [0] | bool | True if the proposal is valid. Reverts otherwise. | + diff --git a/docs/app-development/tbtc-v2/tbtc-v2-api/generated-docs/bridge/Wallets.md b/docs/app-development/tbtc-v2/tbtc-v2-api/generated-docs/bridge/Wallets.md new file mode 100644 index 0000000..55231d5 --- /dev/null +++ b/docs/app-development/tbtc-v2/tbtc-v2-api/generated-docs/bridge/Wallets.md @@ -0,0 +1,448 @@ +# Solidity API + +## Wallets + +Library responsible for handling integration between Bridge +contract and ECDSA wallets. + +### WalletState + +```solidity +enum WalletState { + Unknown, + Live, + MovingFunds, + Closing, + Closed, + Terminated +} +``` + +### Wallet + +```solidity +struct Wallet { + bytes32 ecdsaWalletID; + bytes32 mainUtxoHash; + uint64 pendingRedemptionsValue; + uint32 createdAt; + uint32 movingFundsRequestedAt; + uint32 closingStartedAt; + uint32 pendingMovedFundsSweepRequestsCount; + enum Wallets.WalletState state; + bytes32 movingFundsTargetWalletsCommitmentHash; +} +``` + +### NewWalletRequested + +```solidity +event NewWalletRequested() +``` + +### NewWalletRegistered + +```solidity +event NewWalletRegistered(bytes32 ecdsaWalletID, bytes20 walletPubKeyHash) +``` + +### WalletMovingFunds + +```solidity +event WalletMovingFunds(bytes32 ecdsaWalletID, bytes20 walletPubKeyHash) +``` + +### WalletClosing + +```solidity +event WalletClosing(bytes32 ecdsaWalletID, bytes20 walletPubKeyHash) +``` + +### WalletClosed + +```solidity +event WalletClosed(bytes32 ecdsaWalletID, bytes20 walletPubKeyHash) +``` + +### WalletTerminated + +```solidity +event WalletTerminated(bytes32 ecdsaWalletID, bytes20 walletPubKeyHash) +``` + +### requestNewWallet + +```solidity +function requestNewWallet(struct BridgeState.Storage self, struct BitcoinTx.UTXO activeWalletMainUtxo) external +``` + +Requests creation of a new wallet. This function just +forms a request and the creation process is performed +asynchronously. Outcome of that process should be delivered +using `registerNewWallet` function. + +Requirements: +- `activeWalletMainUtxo` components must point to the recent main +UTXO of the given active wallet, as currently known on the +Ethereum chain. If there is no active wallet at the moment, or +the active wallet has no main UTXO, this parameter can be +empty as it is ignored, +- Wallet creation must not be in progress, +- If the active wallet is set, one of the following +conditions must be true: +- The active wallet BTC balance is above the minimum threshold +and the active wallet is old enough, i.e. the creation period +was elapsed since its creation time, +- The active wallet BTC balance is above the maximum threshold. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| self | struct BridgeState.Storage | | +| activeWalletMainUtxo | struct BitcoinTx.UTXO | Data of the active wallet's main UTXO, as currently known on the Ethereum chain. | + +### registerNewWallet + +```solidity +function registerNewWallet(struct BridgeState.Storage self, bytes32 ecdsaWalletID, bytes32 publicKeyX, bytes32 publicKeyY) external +``` + +Registers a new wallet. This function should be called +after the wallet creation process initiated using +`requestNewWallet` completes and brings the outcomes. + +Requirements: +- The only caller authorized to call this function is `registry`, +- Given wallet data must not belong to an already registered wallet. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| self | struct BridgeState.Storage | | +| ecdsaWalletID | bytes32 | Wallet's unique identifier. | +| publicKeyX | bytes32 | Wallet's public key's X coordinate. | +| publicKeyY | bytes32 | Wallet's public key's Y coordinate. | + +### notifyWalletRedemptionTimeout + +```solidity +function notifyWalletRedemptionTimeout(struct BridgeState.Storage self, bytes20 walletPubKeyHash, uint32[] walletMembersIDs) internal +``` + +Handles a notification about a wallet redemption timeout. +Triggers the wallet moving funds process only if the wallet is +still in the Live state. That means multiple action timeouts can +be reported for the same wallet but only the first report +requests the wallet to move their funds. Executes slashing if +the wallet is in Live or MovingFunds state. Allows to notify +redemption timeout also for a Terminated wallet in case the +redemption was requested before the wallet got terminated. + +Requirements: +- The wallet must be in the `Live`, `MovingFunds`, +or `Terminated` state. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| self | struct BridgeState.Storage | | +| walletPubKeyHash | bytes20 | 20-byte public key hash of the wallet. | +| walletMembersIDs | uint32[] | Identifiers of the wallet signing group members. | + +### notifyWalletHeartbeatFailed + +```solidity +function notifyWalletHeartbeatFailed(struct BridgeState.Storage self, bytes32 publicKeyX, bytes32 publicKeyY) external +``` + +Handles a notification about a wallet heartbeat failure and +triggers the wallet moving funds process. + +Requirements: +- The only caller authorized to call this function is `registry`, +- Wallet must be in Live state. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| self | struct BridgeState.Storage | | +| publicKeyX | bytes32 | Wallet's public key's X coordinate. | +| publicKeyY | bytes32 | Wallet's public key's Y coordinate. | + +### notifyWalletCloseable + +```solidity +function notifyWalletCloseable(struct BridgeState.Storage self, bytes20 walletPubKeyHash, struct BitcoinTx.UTXO walletMainUtxo) external +``` + +Notifies that the wallet is either old enough or has too few +satoshis left and qualifies to be closed. + +Requirements: +- Wallet must not be set as the current active wallet, +- Wallet must exceed the wallet maximum age OR the wallet BTC +balance must be lesser than the minimum threshold. If the latter +case is true, the `walletMainUtxo` components must point to the +recent main UTXO of the given wallet, as currently known on the +Ethereum chain. If the wallet has no main UTXO, this parameter +can be empty as it is ignored since the wallet balance is +assumed to be zero, +- Wallet must be in Live state. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| self | struct BridgeState.Storage | | +| walletPubKeyHash | bytes20 | 20-byte public key hash of the wallet. | +| walletMainUtxo | struct BitcoinTx.UTXO | Data of the wallet's main UTXO, as currently known on the Ethereum chain. | + +### notifyWalletClosingPeriodElapsed + +```solidity +function notifyWalletClosingPeriodElapsed(struct BridgeState.Storage self, bytes20 walletPubKeyHash) internal +``` + +Notifies about the end of the closing period for the given wallet. +Closes the wallet ultimately and notifies the ECDSA registry +about this fact. + +Requirements: +- The wallet must be in the Closing state, +- The wallet closing period must have elapsed. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| self | struct BridgeState.Storage | | +| walletPubKeyHash | bytes20 | 20-byte public key hash of the wallet. | + +### notifyWalletFundsMoved + +```solidity +function notifyWalletFundsMoved(struct BridgeState.Storage self, bytes20 walletPubKeyHash, bytes32 targetWalletsHash) internal +``` + +Notifies that the wallet completed the moving funds process +successfully. Checks if the funds were moved to the expected +target wallets. Closes the source wallet if everything went +good and reverts otherwise. + +Requirements: +- The caller must make sure the moving funds transaction actually +happened on Bitcoin chain and fits the protocol requirements, +- The source wallet must be in the MovingFunds state, +- The target wallets commitment must be submitted by the source +wallet, +- The actual target wallets used in the moving funds transaction +must be exactly the same as the target wallets commitment. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| self | struct BridgeState.Storage | | +| walletPubKeyHash | bytes20 | 20-byte public key hash of the wallet. | +| targetWalletsHash | bytes32 | 32-byte keccak256 hash over the list of 20-byte public key hashes of the target wallets actually used within the moving funds transactions. | + +### notifyWalletMovingFundsBelowDust + +```solidity +function notifyWalletMovingFundsBelowDust(struct BridgeState.Storage self, bytes20 walletPubKeyHash) internal +``` + +Called when a MovingFunds wallet has a balance below the dust +threshold. Begins the wallet closing. + +Requirements: +- The wallet must be in the MovingFunds state. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| self | struct BridgeState.Storage | | +| walletPubKeyHash | bytes20 | 20-byte public key hash of the wallet. | + +### notifyWalletMovingFundsTimeout + +```solidity +function notifyWalletMovingFundsTimeout(struct BridgeState.Storage self, bytes20 walletPubKeyHash, uint32[] walletMembersIDs) internal +``` + +Called when the timeout for MovingFunds for the wallet elapsed. +Slashes wallet members and terminates the wallet. + +Requirements: +- The wallet must be in the MovingFunds state. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| self | struct BridgeState.Storage | | +| walletPubKeyHash | bytes20 | 20-byte public key hash of the wallet. | +| walletMembersIDs | uint32[] | Identifiers of the wallet signing group members. | + +### notifyWalletMovedFundsSweepTimeout + +```solidity +function notifyWalletMovedFundsSweepTimeout(struct BridgeState.Storage self, bytes20 walletPubKeyHash, uint32[] walletMembersIDs) internal +``` + +Called when a wallet which was asked to sweep funds moved from +another wallet did not provide a sweeping proof before a timeout. +Slashes and terminates the wallet who failed to provide a proof. + +Requirements: +- The wallet must be in the `Live`, `MovingFunds`, +or `Terminated` state. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| self | struct BridgeState.Storage | | +| walletPubKeyHash | bytes20 | 20-byte public key hash of the wallet which was supposed to sweep funds. | +| walletMembersIDs | uint32[] | Identifiers of the wallet signing group members. | + +### notifyWalletFraudChallengeDefeatTimeout + +```solidity +function notifyWalletFraudChallengeDefeatTimeout(struct BridgeState.Storage self, bytes20 walletPubKeyHash, uint32[] walletMembersIDs, address challenger) internal +``` + +Called when a wallet which was challenged for a fraud did not +defeat the challenge before the timeout. Slashes and terminates +the wallet who failed to defeat the challenge. If the wallet is +already terminated, it does nothing. + +Requirements: +- The wallet must be in the `Live`, `MovingFunds`, `Closing` +or `Terminated` state. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| self | struct BridgeState.Storage | | +| walletPubKeyHash | bytes20 | 20-byte public key hash of the wallet which was supposed to sweep funds. | +| walletMembersIDs | uint32[] | Identifiers of the wallet signing group members. | +| challenger | address | Address of the party which submitted the fraud challenge. | + +### moveFunds + +```solidity +function moveFunds(struct BridgeState.Storage self, bytes20 walletPubKeyHash) internal +``` + +Requests a wallet to move their funds. If the wallet balance +is zero, the wallet closing begins immediately. If the move +funds request refers to the current active wallet, such a wallet +is no longer considered active and the active wallet slot +is unset allowing to trigger a new wallet creation immediately. + +Requirements: +- The caller must make sure that the wallet is in the Live state. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| self | struct BridgeState.Storage | | +| walletPubKeyHash | bytes20 | 20-byte public key hash of the wallet. | + +### beginWalletClosing + +```solidity +function beginWalletClosing(struct BridgeState.Storage self, bytes20 walletPubKeyHash) internal +``` + +Begins the closing period of the given wallet. + +Requirements: +- The caller must make sure that the wallet is in the +MovingFunds state. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| self | struct BridgeState.Storage | | +| walletPubKeyHash | bytes20 | 20-byte public key hash of the wallet. | + +### finalizeWalletClosing + +```solidity +function finalizeWalletClosing(struct BridgeState.Storage self, bytes20 walletPubKeyHash) internal +``` + +Finalizes the closing period of the given wallet and notifies +the ECDSA registry about this fact. + +Requirements: +- The caller must make sure that the wallet is in the Closing state. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| self | struct BridgeState.Storage | | +| walletPubKeyHash | bytes20 | 20-byte public key hash of the wallet. | + +### terminateWallet + +```solidity +function terminateWallet(struct BridgeState.Storage self, bytes20 walletPubKeyHash) internal +``` + +Terminates the given wallet and notifies the ECDSA registry +about this fact. If the wallet termination refers to the current +active wallet, such a wallet is no longer considered active and +the active wallet slot is unset allowing to trigger a new wallet +creation immediately. + +Requirements: +- The caller must make sure that the wallet is in the +Live or MovingFunds or Closing state. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| self | struct BridgeState.Storage | | +| walletPubKeyHash | bytes20 | 20-byte public key hash of the wallet. | + +### getWalletBtcBalance + +```solidity +function getWalletBtcBalance(struct BridgeState.Storage self, bytes20 walletPubKeyHash, struct BitcoinTx.UTXO walletMainUtxo) internal view returns (uint64 walletBtcBalance) +``` + +Gets BTC balance for given the wallet. + +Requirements: +- `walletMainUtxo` components must point to the recent main UTXO +of the given wallet, as currently known on the Ethereum chain. +If the wallet has no main UTXO, this parameter can be empty as it +is ignored. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| self | struct BridgeState.Storage | | +| walletPubKeyHash | bytes20 | 20-byte public key hash of the wallet. | +| walletMainUtxo | struct BitcoinTx.UTXO | Data of the wallet's main UTXO, as currently known on the Ethereum chain. | + +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +| walletBtcBalance | uint64 | Current BTC balance for the given wallet. | + diff --git a/docs/app-development/tbtc-v2/tbtc-v2-api/generated-docs/index.md b/docs/app-development/tbtc-v2/tbtc-v2-api/generated-docs/index.md deleted file mode 100644 index e61278b..0000000 --- a/docs/app-development/tbtc-v2/tbtc-v2-api/generated-docs/index.md +++ /dev/null @@ -1,11835 +0,0 @@ -# Solidity API -## Table Of Contents - - - -- [Bank](#bank) -- [IReceiveBalanceApproval](#ireceivebalanceapproval) -- [BitcoinTx](#bitcointx) -- [Bridge](#bridge) -- [BridgeGovernance](#bridgegovernance) -- [BridgeGovernanceParameters](#bridgegovernanceparameters) -- [BridgeState](#bridgestate) -- [Deposit](#deposit) -- [DepositSweep](#depositsweep) -- [EcdsaLib](#ecdsalib) -- [Fraud](#fraud) -- [Heartbeat](#heartbeat) -- [IRelay](#irelay) -- [MovingFunds](#movingfunds) -- [OutboundTx](#outboundtx) -- [Redemption](#redemption) -- [Wallets](#wallets) -- [IVault](#ivault) -- [GovernanceUtils](#governanceutils) -- [VendingMachine](#vendingmachine) -- [VendingMachineV2](#vendingmachinev2) -- [VendingMachineV3](#vendingmachinev3) -- [WalletCoordinator](#walletcoordinator) -- [L2TBTC](#l2tbtc) -- [IWormholeTokenBridge](#iwormholetokenbridge) -- [L2WormholeGateway](#l2wormholegateway) -- [MaintainerProxy](#maintainerproxy) -- [Epoch](#epoch) -- [ILightRelay](#ilightrelay) -- [RelayUtils](#relayutils) -- [LightRelay](#lightrelay) -- [LightRelayMaintainerProxy](#lightrelaymaintainerproxy) -- [TBTC](#tbtc) -- [DonationVault](#donationvault) -- [TBTCOptimisticMinting](#tbtcoptimisticminting) -- [TBTCVault](#tbtcvault) - - - -## Bank - -Bank is a central component tracking Bitcoin balances. Balances can -be transferred between balance owners, and balance owners can -approve their balances to be spent by others. Balances in the Bank -are updated for depositors who deposited their Bitcoin into the -Bridge and only the Bridge can increase balances. - -Bank is a governable contract and the Governance can upgrade the Bridge -address. - -### bridge - -```solidity -address bridge -``` - -### balanceOf - -```solidity -mapping(address => uint256) balanceOf -``` - -The balance of the given account in the Bank. Zero by default. - -### allowance - -```solidity -mapping(address => mapping(address => uint256)) allowance -``` - -The remaining amount of balance a spender will be -allowed to transfer on behalf of an owner using -`transferBalanceFrom`. Zero by default. - -### nonces - -```solidity -mapping(address => uint256) nonces -``` - -Returns the current nonce for an EIP2612 permission for the -provided balance owner to protect against replay attacks. Used -to construct an EIP2612 signature provided to the `permit` -function. - -### cachedChainId - -```solidity -uint256 cachedChainId -``` - -### cachedDomainSeparator - -```solidity -bytes32 cachedDomainSeparator -``` - -### PERMIT_TYPEHASH - -```solidity -bytes32 PERMIT_TYPEHASH -``` - -Returns an EIP2612 Permit message hash. Used to construct -an EIP2612 signature provided to the `permit` function. - -### BalanceTransferred - -```solidity -event BalanceTransferred(address from, address to, uint256 amount) -``` - -### BalanceApproved - -```solidity -event BalanceApproved(address owner, address spender, uint256 amount) -``` - -### BalanceIncreased - -```solidity -event BalanceIncreased(address owner, uint256 amount) -``` - -### BalanceDecreased - -```solidity -event BalanceDecreased(address owner, uint256 amount) -``` - -### BridgeUpdated - -```solidity -event BridgeUpdated(address newBridge) -``` - -### onlyBridge - -```solidity -modifier onlyBridge() -``` - -### constructor - -```solidity -constructor() public -``` - -### updateBridge - -```solidity -function updateBridge(address _bridge) external -``` - -Allows the Governance to upgrade the Bridge address. - -The function does not implement any governance delay and does not -check the status of the Bridge. The Governance implementation needs -to ensure all requirements for the upgrade are satisfied before -executing this function. -Requirements: -- The new Bridge address must not be zero. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| _bridge | address | The new Bridge address. | - -### transferBalance - -```solidity -function transferBalance(address recipient, uint256 amount) external -``` - -Moves the given `amount` of balance from the caller to -`recipient`. - -Requirements: -- `recipient` cannot be the zero address, -- the caller must have a balance of at least `amount`. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| recipient | address | The recipient of the balance. | -| amount | uint256 | The amount of the balance transferred. | - -### approveBalance - -```solidity -function approveBalance(address spender, uint256 amount) external -``` - -Sets `amount` as the allowance of `spender` over the caller's -balance. Does not allow updating an existing allowance to -a value that is non-zero to avoid someone using both the old and -the new allowance by unfortunate transaction ordering. To update -an allowance to a non-zero value please set it to zero first or -use `increaseBalanceAllowance` or `decreaseBalanceAllowance` for -an atomic update. - -If the `amount` is set to `type(uint256).max`, -`transferBalanceFrom` will not reduce an allowance. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| spender | address | The address that will be allowed to spend the balance. | -| amount | uint256 | The amount the spender is allowed to spend. | - -### approveBalanceAndCall - -```solidity -function approveBalanceAndCall(address spender, uint256 amount, bytes extraData) external -``` - -Sets the `amount` as an allowance of a smart contract `spender` -over the caller's balance and calls the `spender` via -`receiveBalanceApproval`. - -If the `amount` is set to `type(uint256).max`, the potential -`transferBalanceFrom` executed in `receiveBalanceApproval` of -`spender` will not reduce an allowance. Beware that changing an -allowance with this function brings the risk that `spender` may use -both the old and the new allowance by unfortunate transaction -ordering. Please use `increaseBalanceAllowance` and -`decreaseBalanceAllowance` to eliminate the risk. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| spender | address | The smart contract that will be allowed to spend the balance. | -| amount | uint256 | The amount the spender contract is allowed to spend. | -| extraData | bytes | Extra data passed to the `spender` contract via `receiveBalanceApproval` call. | - -### increaseBalanceAllowance - -```solidity -function increaseBalanceAllowance(address spender, uint256 addedValue) external -``` - -Atomically increases the caller's balance allowance granted to -`spender` by the given `addedValue`. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| spender | address | The spender address for which the allowance is increased. | -| addedValue | uint256 | The amount by which the allowance is increased. | - -### decreaseBalanceAllowance - -```solidity -function decreaseBalanceAllowance(address spender, uint256 subtractedValue) external -``` - -Atomically decreases the caller's balance allowance granted to -`spender` by the given `subtractedValue`. - -Requirements: -- `spender` must not be the zero address, -- the current allowance for `spender` must not be lower than -the `subtractedValue`. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| spender | address | The spender address for which the allowance is decreased. | -| subtractedValue | uint256 | The amount by which the allowance is decreased. | - -### transferBalanceFrom - -```solidity -function transferBalanceFrom(address spender, address recipient, uint256 amount) external -``` - -Moves `amount` of balance from `spender` to `recipient` using the -allowance mechanism. `amount` is then deducted from the caller's -allowance unless the allowance was made for `type(uint256).max`. - -Requirements: -- `recipient` cannot be the zero address, -- `spender` must have a balance of at least `amount`, -- the caller must have an allowance for `spender`'s balance of at -least `amount`. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| spender | address | The address from which the balance is transferred. | -| recipient | address | The address to which the balance is transferred. | -| amount | uint256 | The amount of balance that is transferred. | - -### permit - -```solidity -function permit(address owner, address spender, uint256 amount, uint256 deadline, uint8 v, bytes32 r, bytes32 s) external -``` - -An EIP2612 approval made with secp256k1 signature. Users can -authorize a transfer of their balance with a signature -conforming to the EIP712 standard, rather than an on-chain -transaction from their address. Anyone can submit this signature -on the user's behalf by calling the `permit` function, paying -gas fees, and possibly performing other actions in the same -transaction. - -The deadline argument can be set to `type(uint256).max to create -permits that effectively never expire. If the `amount` is set -to `type(uint256).max` then `transferBalanceFrom` will not -reduce an allowance. Beware that changing an allowance with this -function brings the risk that someone may use both the old and the -new allowance by unfortunate transaction ordering. Please use -`increaseBalanceAllowance` and `decreaseBalanceAllowance` to -eliminate the risk. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| owner | address | The balance owner who signed the permission. | -| spender | address | The address that will be allowed to spend the balance. | -| amount | uint256 | The amount the spender is allowed to spend. | -| deadline | uint256 | The UNIX time until which the permit is valid. | -| v | uint8 | V part of the permit signature. | -| r | bytes32 | R part of the permit signature. | -| s | bytes32 | S part of the permit signature. | - -### increaseBalances - -```solidity -function increaseBalances(address[] recipients, uint256[] amounts) external -``` - -Increases balances of the provided `recipients` by the provided -`amounts`. Can only be called by the Bridge. - -Requirements: -- length of `recipients` and `amounts` must be the same, -- none of `recipients` addresses must point to the Bank. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| recipients | address[] | Balance increase recipients. | -| amounts | uint256[] | Amounts by which balances are increased. | - -### increaseBalance - -```solidity -function increaseBalance(address recipient, uint256 amount) external -``` - -Increases balance of the provided `recipient` by the provided -`amount`. Can only be called by the Bridge. - -Requirements: -- `recipient` address must not point to the Bank. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| recipient | address | Balance increase recipient. | -| amount | uint256 | Amount by which the balance is increased. | - -### increaseBalanceAndCall - -```solidity -function increaseBalanceAndCall(address vault, address[] recipients, uint256[] amounts) external -``` - -Increases the given smart contract `vault`'s balance and -notifies the `vault` contract about it. -Can be called only by the Bridge. - -Requirements: -- `vault` must implement `IVault` interface, -- length of `recipients` and `amounts` must be the same. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| vault | address | Address of `IVault` recipient contract. | -| recipients | address[] | Balance increase recipients. | -| amounts | uint256[] | Amounts by which balances are increased. | - -### decreaseBalance - -```solidity -function decreaseBalance(uint256 amount) external -``` - -Decreases caller's balance by the provided `amount`. There is no -way to restore the balance so do not call this function unless -you really know what you are doing! - -Requirements: -- The caller must have a balance of at least `amount`. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| amount | uint256 | The amount by which the balance is decreased. | - -### DOMAIN_SEPARATOR - -```solidity -function DOMAIN_SEPARATOR() public view returns (bytes32) -``` - -Returns hash of EIP712 Domain struct with `TBTC Bank` as -a signing domain and Bank contract as a verifying contract. -Used to construct an EIP2612 signature provided to the `permit` -function. - -### _increaseBalance - -```solidity -function _increaseBalance(address recipient, uint256 amount) internal -``` - -## IReceiveBalanceApproval - -`IReceiveBalanceApproval` is an interface for a smart contract -consuming Bank balances approved to them in the same transaction by -other contracts or externally owned accounts (EOA). - -### receiveBalanceApproval - -```solidity -function receiveBalanceApproval(address owner, uint256 amount, bytes extraData) external -``` - -Called by the Bank in `approveBalanceAndCall` function after -the balance `owner` approved `amount` of their balance in the -Bank for the contract. This way, the depositor can approve -balance and call the contract to use the approved balance in -a single transaction. - -The implementation must ensure this function can only be called -by the Bank. The Bank does _not_ guarantee that the `amount` -approved by the `owner` currently exists on their balance. That is, -the `owner` could approve more balance than they currently have. -This works the same as `Bank.approve` function. The contract must -ensure the actual balance is checked before performing any action -based on it. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| owner | address | Address of the Bank balance owner who approved their balance to be used by the contract. | -| amount | uint256 | The amount of the Bank balance approved by the owner to be used by the contract. | -| extraData | bytes | The `extraData` passed to `Bank.approveBalanceAndCall`. | - -## BitcoinTx - -Allows to reference Bitcoin raw transaction in Solidity. - -See https://developer.bitcoin.org/reference/transactions.html#raw-transaction-format - -Raw Bitcoin transaction data: - -| Bytes | Name | BTC type | Description | -|--------|--------------|------------------------|---------------------------| -| 4 | version | int32_t (LE) | TX version number | -| varies | tx_in_count | compactSize uint (LE) | Number of TX inputs | -| varies | tx_in | txIn[] | TX inputs | -| varies | tx_out_count | compactSize uint (LE) | Number of TX outputs | -| varies | tx_out | txOut[] | TX outputs | -| 4 | lock_time | uint32_t (LE) | Unix time or block number | - -Non-coinbase transaction input (txIn): - -| Bytes | Name | BTC type | Description | -|--------|------------------|------------------------|---------------------------------------------| -| 36 | previous_output | outpoint | The previous outpoint being spent | -| varies | script_bytes | compactSize uint (LE) | The number of bytes in the signature script | -| varies | signature_script | char[] | The signature script, empty for P2WSH | -| 4 | sequence | uint32_t (LE) | Sequence number | - -The reference to transaction being spent (outpoint): - -| Bytes | Name | BTC type | Description | -|-------|-------|---------------|------------------------------------------| -| 32 | hash | char[32] | Hash of the transaction to spend | -| 4 | index | uint32_t (LE) | Index of the specific output from the TX | - -Transaction output (txOut): - -| Bytes | Name | BTC type | Description | -|--------|-----------------|-----------------------|--------------------------------------| -| 8 | value | int64_t (LE) | Number of satoshis to spend | -| 1+ | pk_script_bytes | compactSize uint (LE) | Number of bytes in the pubkey script | -| varies | pk_script | char[] | Pubkey script | - -compactSize uint format: - -| Value | Bytes | Format | -|-----------------------------------------|-------|----------------------------------------------| -| >= 0 && <= 252 | 1 | uint8_t | -| >= 253 && <= 0xffff | 3 | 0xfd followed by the number as uint16_t (LE) | -| >= 0x10000 && <= 0xffffffff | 5 | 0xfe followed by the number as uint32_t (LE) | -| >= 0x100000000 && <= 0xffffffffffffffff | 9 | 0xff followed by the number as uint64_t (LE) | - -(*) compactSize uint is often references as VarInt) - -Coinbase transaction input (txIn): - -| Bytes | Name | BTC type | Description | -|--------|------------------|------------------------|---------------------------------------------| -| 32 | hash | char[32] | A 32-byte 0x0 null (no previous_outpoint) | -| 4 | index | uint32_t (LE) | 0xffffffff (no previous_outpoint) | -| varies | script_bytes | compactSize uint (LE) | The number of bytes in the coinbase script | -| varies | height | char[] | The block height of this block (BIP34) (*) | -| varies | coinbase_script | none | Arbitrary data, max 100 bytes | -| 4 | sequence | uint32_t (LE) | Sequence number - -(*) Uses script language: starts with a data-pushing opcode that indicates how many bytes to push to -the stack followed by the block height as a little-endian unsigned integer. This script must be as -short as possible, otherwise it may be rejected. The data-pushing opcode will be 0x03 and the total -size four bytes until block 16,777,216 about 300 years from now. - -### Info - -```solidity -struct Info { - bytes4 version; - bytes inputVector; - bytes outputVector; - bytes4 locktime; -} -``` - -### Proof - -```solidity -struct Proof { - bytes merkleProof; - uint256 txIndexInBlock; - bytes bitcoinHeaders; -} -``` - -### UTXO - -```solidity -struct UTXO { - bytes32 txHash; - uint32 txOutputIndex; - uint64 txOutputValue; -} -``` - -### RSVSignature - -```solidity -struct RSVSignature { - bytes32 r; - bytes32 s; - uint8 v; -} -``` - -### validateProof - -```solidity -function validateProof(struct BridgeState.Storage self, struct BitcoinTx.Info txInfo, struct BitcoinTx.Proof proof) internal view returns (bytes32 txHash) -``` - -Validates the SPV proof of the Bitcoin transaction. -Reverts in case the validation or proof verification fail. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| self | struct BridgeState.Storage | | -| txInfo | struct BitcoinTx.Info | Bitcoin transaction data. | -| proof | struct BitcoinTx.Proof | Bitcoin proof data. | - -#### Return Values - -| Name | Type | Description | -| ---- | ---- | ----------- | -| txHash | bytes32 | Proven 32-byte transaction hash. | - -### evaluateProofDifficulty - -```solidity -function evaluateProofDifficulty(struct BridgeState.Storage self, bytes bitcoinHeaders) internal view -``` - -Evaluates the given Bitcoin proof difficulty against the actual -Bitcoin chain difficulty provided by the relay oracle. -Reverts in case the evaluation fails. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| self | struct BridgeState.Storage | | -| bitcoinHeaders | bytes | Bitcoin headers chain being part of the SPV proof. Used to extract the observed proof difficulty. | - -### extractPubKeyHash - -```solidity -function extractPubKeyHash(struct BridgeState.Storage, bytes output) internal pure returns (bytes20 pubKeyHash) -``` - -Extracts public key hash from the provided P2PKH or P2WPKH output. -Reverts if the validation fails. - -Requirements: -- The output must be of P2PKH or P2WPKH type and lock the funds -on a 20-byte public key hash. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| | struct BridgeState.Storage | | -| output | bytes | The transaction output. | - -#### Return Values - -| Name | Type | Description | -| ---- | ---- | ----------- | -| pubKeyHash | bytes20 | 20-byte public key hash the output locks funds on. | - -### makeP2PKHScript - -```solidity -function makeP2PKHScript(bytes20 pubKeyHash) internal pure returns (bytes26) -``` - -Build the P2PKH script from the given public key hash. - -The P2PKH script has the following byte format: -<0x1976a914> <20-byte PKH> <0x88ac>. According to -https://en.bitcoin.it/wiki/Script#Opcodes this translates to: -- 0x19: Byte length of the entire script -- 0x76: OP_DUP -- 0xa9: OP_HASH160 -- 0x14: Byte length of the public key hash -- 0x88: OP_EQUALVERIFY -- 0xac: OP_CHECKSIG -which matches the P2PKH structure as per: -https://en.bitcoin.it/wiki/Transaction#Pay-to-PubkeyHash - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| pubKeyHash | bytes20 | The 20-byte public key hash. | - -#### Return Values - -| Name | Type | Description | -| ---- | ---- | ----------- | -| [0] | bytes26 | The P2PKH script. | - -### makeP2WPKHScript - -```solidity -function makeP2WPKHScript(bytes20 pubKeyHash) internal pure returns (bytes23) -``` - -Build the P2WPKH script from the given public key hash. - -The P2WPKH script has the following format: -<0x160014> <20-byte PKH>. According to -https://en.bitcoin.it/wiki/Script#Opcodes this translates to: -- 0x16: Byte length of the entire script -- 0x00: OP_0 -- 0x14: Byte length of the public key hash -which matches the P2WPKH structure as per: -https://github.com/bitcoin/bips/blob/master/bip-0141.mediawiki#P2WPKH - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| pubKeyHash | bytes20 | The 20-byte public key hash. | - -#### Return Values - -| Name | Type | Description | -| ---- | ---- | ----------- | -| [0] | bytes23 | The P2WPKH script. | - -## Bridge - -Bridge manages BTC deposit and redemption flow and is increasing and -decreasing balances in the Bank as a result of BTC deposit and -redemption operations performed by depositors and redeemers. - -Depositors send BTC funds to the most recently created off-chain -ECDSA wallet of the bridge using pay-to-script-hash (P2SH) or -pay-to-witness-script-hash (P2WSH) containing hashed information -about the depositor’s Ethereum address. Then, the depositor reveals -their Ethereum address along with their deposit blinding factor, -refund public key hash and refund locktime to the Bridge on Ethereum -chain. The off-chain ECDSA wallet listens for these sorts of -messages and when it gets one, it checks the Bitcoin network to make -sure the deposit lines up. If it does, the off-chain ECDSA wallet -may decide to pick the deposit transaction for sweeping, and when -the sweep operation is confirmed on the Bitcoin network, the ECDSA -wallet informs the Bridge about the sweep increasing appropriate -balances in the Bank. - -Bridge is an upgradeable component of the Bank. The order of -functionalities in this contract is: deposit, sweep, redemption, -moving funds, wallet lifecycle, frauds, parameters. - -### self - -```solidity -struct BridgeState.Storage self -``` - -### DepositRevealed - -```solidity -event DepositRevealed(bytes32 fundingTxHash, uint32 fundingOutputIndex, address depositor, uint64 amount, bytes8 blindingFactor, bytes20 walletPubKeyHash, bytes20 refundPubKeyHash, bytes4 refundLocktime, address vault) -``` - -### DepositsSwept - -```solidity -event DepositsSwept(bytes20 walletPubKeyHash, bytes32 sweepTxHash) -``` - -### RedemptionRequested - -```solidity -event RedemptionRequested(bytes20 walletPubKeyHash, bytes redeemerOutputScript, address redeemer, uint64 requestedAmount, uint64 treasuryFee, uint64 txMaxFee) -``` - -### RedemptionsCompleted - -```solidity -event RedemptionsCompleted(bytes20 walletPubKeyHash, bytes32 redemptionTxHash) -``` - -### RedemptionTimedOut - -```solidity -event RedemptionTimedOut(bytes20 walletPubKeyHash, bytes redeemerOutputScript) -``` - -### WalletMovingFunds - -```solidity -event WalletMovingFunds(bytes32 ecdsaWalletID, bytes20 walletPubKeyHash) -``` - -### MovingFundsCommitmentSubmitted - -```solidity -event MovingFundsCommitmentSubmitted(bytes20 walletPubKeyHash, bytes20[] targetWallets, address submitter) -``` - -### MovingFundsTimeoutReset - -```solidity -event MovingFundsTimeoutReset(bytes20 walletPubKeyHash) -``` - -### MovingFundsCompleted - -```solidity -event MovingFundsCompleted(bytes20 walletPubKeyHash, bytes32 movingFundsTxHash) -``` - -### MovingFundsTimedOut - -```solidity -event MovingFundsTimedOut(bytes20 walletPubKeyHash) -``` - -### MovingFundsBelowDustReported - -```solidity -event MovingFundsBelowDustReported(bytes20 walletPubKeyHash) -``` - -### MovedFundsSwept - -```solidity -event MovedFundsSwept(bytes20 walletPubKeyHash, bytes32 sweepTxHash) -``` - -### MovedFundsSweepTimedOut - -```solidity -event MovedFundsSweepTimedOut(bytes20 walletPubKeyHash, bytes32 movingFundsTxHash, uint32 movingFundsTxOutputIndex) -``` - -### NewWalletRequested - -```solidity -event NewWalletRequested() -``` - -### NewWalletRegistered - -```solidity -event NewWalletRegistered(bytes32 ecdsaWalletID, bytes20 walletPubKeyHash) -``` - -### WalletClosing - -```solidity -event WalletClosing(bytes32 ecdsaWalletID, bytes20 walletPubKeyHash) -``` - -### WalletClosed - -```solidity -event WalletClosed(bytes32 ecdsaWalletID, bytes20 walletPubKeyHash) -``` - -### WalletTerminated - -```solidity -event WalletTerminated(bytes32 ecdsaWalletID, bytes20 walletPubKeyHash) -``` - -### FraudChallengeSubmitted - -```solidity -event FraudChallengeSubmitted(bytes20 walletPubKeyHash, bytes32 sighash, uint8 v, bytes32 r, bytes32 s) -``` - -### FraudChallengeDefeated - -```solidity -event FraudChallengeDefeated(bytes20 walletPubKeyHash, bytes32 sighash) -``` - -### FraudChallengeDefeatTimedOut - -```solidity -event FraudChallengeDefeatTimedOut(bytes20 walletPubKeyHash, bytes32 sighash) -``` - -### VaultStatusUpdated - -```solidity -event VaultStatusUpdated(address vault, bool isTrusted) -``` - -### SpvMaintainerStatusUpdated - -```solidity -event SpvMaintainerStatusUpdated(address spvMaintainer, bool isTrusted) -``` - -### DepositParametersUpdated - -```solidity -event DepositParametersUpdated(uint64 depositDustThreshold, uint64 depositTreasuryFeeDivisor, uint64 depositTxMaxFee, uint32 depositRevealAheadPeriod) -``` - -### RedemptionParametersUpdated - -```solidity -event RedemptionParametersUpdated(uint64 redemptionDustThreshold, uint64 redemptionTreasuryFeeDivisor, uint64 redemptionTxMaxFee, uint64 redemptionTxMaxTotalFee, uint32 redemptionTimeout, uint96 redemptionTimeoutSlashingAmount, uint32 redemptionTimeoutNotifierRewardMultiplier) -``` - -### MovingFundsParametersUpdated - -```solidity -event MovingFundsParametersUpdated(uint64 movingFundsTxMaxTotalFee, uint64 movingFundsDustThreshold, uint32 movingFundsTimeoutResetDelay, uint32 movingFundsTimeout, uint96 movingFundsTimeoutSlashingAmount, uint32 movingFundsTimeoutNotifierRewardMultiplier, uint16 movingFundsCommitmentGasOffset, uint64 movedFundsSweepTxMaxTotalFee, uint32 movedFundsSweepTimeout, uint96 movedFundsSweepTimeoutSlashingAmount, uint32 movedFundsSweepTimeoutNotifierRewardMultiplier) -``` - -### WalletParametersUpdated - -```solidity -event WalletParametersUpdated(uint32 walletCreationPeriod, uint64 walletCreationMinBtcBalance, uint64 walletCreationMaxBtcBalance, uint64 walletClosureMinBtcBalance, uint32 walletMaxAge, uint64 walletMaxBtcTransfer, uint32 walletClosingPeriod) -``` - -### FraudParametersUpdated - -```solidity -event FraudParametersUpdated(uint96 fraudChallengeDepositAmount, uint32 fraudChallengeDefeatTimeout, uint96 fraudSlashingAmount, uint32 fraudNotifierRewardMultiplier) -``` - -### TreasuryUpdated - -```solidity -event TreasuryUpdated(address treasury) -``` - -### onlySpvMaintainer - -```solidity -modifier onlySpvMaintainer() -``` - -### constructor - -```solidity -constructor() public -``` - -### initialize - -```solidity -function initialize(address _bank, address _relay, address _treasury, address _ecdsaWalletRegistry, address payable _reimbursementPool, uint96 _txProofDifficultyFactor) external -``` - -Initializes upgradable contract on deployment. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| _bank | address | Address of the Bank the Bridge belongs to. | -| _relay | address | Address of the Bitcoin relay providing the current Bitcoin network difficulty. | -| _treasury | address | Address where the deposit and redemption treasury fees will be sent to. | -| _ecdsaWalletRegistry | address | Address of the ECDSA Wallet Registry contract. | -| _reimbursementPool | address payable | Address of the Reimbursement Pool contract. | -| _txProofDifficultyFactor | uint96 | The number of confirmations on the Bitcoin chain required to successfully evaluate an SPV proof. | - -### revealDeposit - -```solidity -function revealDeposit(struct BitcoinTx.Info fundingTx, struct Deposit.DepositRevealInfo reveal) external -``` - -Used by the depositor to reveal information about their P2(W)SH -Bitcoin deposit to the Bridge on Ethereum chain. The off-chain -wallet listens for revealed deposit events and may decide to -include the revealed deposit in the next executed sweep. -Information about the Bitcoin deposit can be revealed before or -after the Bitcoin transaction with P2(W)SH deposit is mined on -the Bitcoin chain. Worth noting, the gas cost of this function -scales with the number of P2(W)SH transaction inputs and -outputs. The deposit may be routed to one of the trusted vaults. -When a deposit is routed to a vault, vault gets notified when -the deposit gets swept and it may execute the appropriate action. - -Requirements: -- This function must be called by the same Ethereum address as the -one used in the P2(W)SH BTC deposit transaction as a depositor, -- `reveal.walletPubKeyHash` must identify a `Live` wallet, -- `reveal.vault` must be 0x0 or point to a trusted vault, -- `reveal.fundingOutputIndex` must point to the actual P2(W)SH -output of the BTC deposit transaction, -- `reveal.blindingFactor` must be the blinding factor used in the -P2(W)SH BTC deposit transaction, -- `reveal.walletPubKeyHash` must be the wallet pub key hash used in -the P2(W)SH BTC deposit transaction, -- `reveal.refundPubKeyHash` must be the refund pub key hash used in -the P2(W)SH BTC deposit transaction, -- `reveal.refundLocktime` must be the refund locktime used in the -P2(W)SH BTC deposit transaction, -- BTC deposit for the given `fundingTxHash`, `fundingOutputIndex` -can be revealed only one time. - -If any of these requirements is not met, the wallet _must_ refuse -to sweep the deposit and the depositor has to wait until the -deposit script unlocks to receive their BTC back. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| fundingTx | struct BitcoinTx.Info | Bitcoin funding transaction data, see `BitcoinTx.Info`. | -| reveal | struct Deposit.DepositRevealInfo | Deposit reveal data, see `RevealInfo struct. | - -### submitDepositSweepProof - -```solidity -function submitDepositSweepProof(struct BitcoinTx.Info sweepTx, struct BitcoinTx.Proof sweepProof, struct BitcoinTx.UTXO mainUtxo, address vault) external -``` - -Used by the wallet to prove the BTC deposit sweep transaction -and to update Bank balances accordingly. Sweep is only accepted -if it satisfies SPV proof. - -The function is performing Bank balance updates by first -computing the Bitcoin fee for the sweep transaction. The fee is -divided evenly between all swept deposits. Each depositor -receives a balance in the bank equal to the amount inferred -during the reveal transaction, minus their fee share. - -It is possible to prove the given sweep only one time. - -Requirements: -- `sweepTx` components must match the expected structure. See -`BitcoinTx.Info` docs for reference. Their values must exactly -correspond to appropriate Bitcoin transaction fields to produce -a provable transaction hash, -- The `sweepTx` should represent a Bitcoin transaction with 1..n -inputs. If the wallet has no main UTXO, all n inputs should -correspond to P2(W)SH revealed deposits UTXOs. If the wallet has -an existing main UTXO, one of the n inputs must point to that -main UTXO and remaining n-1 inputs should correspond to P2(W)SH -revealed deposits UTXOs. That transaction must have only -one P2(W)PKH output locking funds on the 20-byte wallet public -key hash, -- All revealed deposits that are swept by `sweepTx` must have -their `vault` parameters set to the same address as the address -passed in the `vault` function parameter, -- `sweepProof` components must match the expected structure. See -`BitcoinTx.Proof` docs for reference. The `bitcoinHeaders` -field must contain a valid number of block headers, not less -than the `txProofDifficultyFactor` contract constant, -- `mainUtxo` components must point to the recent main UTXO -of the given wallet, as currently known on the Ethereum chain. -If there is no main UTXO, this parameter is ignored. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| sweepTx | struct BitcoinTx.Info | Bitcoin sweep transaction data. | -| sweepProof | struct BitcoinTx.Proof | Bitcoin sweep proof data. | -| mainUtxo | struct BitcoinTx.UTXO | Data of the wallet's main UTXO, as currently known on the Ethereum chain. If no main UTXO exists for the given wallet, this parameter is ignored. | -| vault | address | Optional address of the vault where all swept deposits should be routed to. All deposits swept as part of the transaction must have their `vault` parameters set to the same address. If this parameter is set to an address of a trusted vault, swept deposits are routed to that vault. If this parameter is set to the zero address or to an address of a non-trusted vault, swept deposits are not routed to a vault but depositors' balances are increased in the Bank individually. | - -### requestRedemption - -```solidity -function requestRedemption(bytes20 walletPubKeyHash, struct BitcoinTx.UTXO mainUtxo, bytes redeemerOutputScript, uint64 amount) external -``` - -Requests redemption of the given amount from the specified -wallet to the redeemer Bitcoin output script. Handles the -simplest case in which the redeemer's balance is decreased in -the Bank. - -Requirements: -- Wallet behind `walletPubKeyHash` must be live, -- `mainUtxo` components must point to the recent main UTXO -of the given wallet, as currently known on the Ethereum chain, -- `redeemerOutputScript` must be a proper Bitcoin script, -- `redeemerOutputScript` cannot have wallet PKH as payload, -- `amount` must be above or equal the `redemptionDustThreshold`, -- Given `walletPubKeyHash` and `redeemerOutputScript` pair can be -used for only one pending request at the same time, -- Wallet must have enough Bitcoin balance to process the request, -- Redeemer must make an allowance in the Bank that the Bridge -contract can spend the given `amount`. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| walletPubKeyHash | bytes20 | The 20-byte wallet public key hash (computed using Bitcoin HASH160 over the compressed ECDSA public key). | -| mainUtxo | struct BitcoinTx.UTXO | Data of the wallet's main UTXO, as currently known on the Ethereum chain. | -| redeemerOutputScript | bytes | The redeemer's length-prefixed output script (P2PKH, P2WPKH, P2SH or P2WSH) that will be used to lock redeemed BTC. | -| amount | uint64 | Requested amount in satoshi. This is also the Bank balance that is taken from the `balanceOwner` upon request. Once the request is handled, the actual amount of BTC locked on the redeemer output script will be always lower than this value since the treasury and Bitcoin transaction fees must be incurred. The minimal amount satisfying the request can be computed as: `amount - (amount / redemptionTreasuryFeeDivisor) - redemptionTxMaxFee`. Fees values are taken at the moment of request creation. | - -### receiveBalanceApproval - -```solidity -function receiveBalanceApproval(address balanceOwner, uint256 amount, bytes redemptionData) external -``` - -Requests redemption of the given amount from the specified -wallet to the redeemer Bitcoin output script. Used by -`Bank.approveBalanceAndCall`. Can handle more complex cases -where balance owner may be someone else than the redeemer. -For example, vault redeeming its balance for some depositor. - -Requirements: -- The caller must be the Bank, -- Wallet behind `walletPubKeyHash` must be live, -- `mainUtxo` components must point to the recent main UTXO -of the given wallet, as currently known on the Ethereum chain, -- `redeemerOutputScript` must be a proper Bitcoin script, -- `redeemerOutputScript` cannot have wallet PKH as payload, -- `amount` must be above or equal the `redemptionDustThreshold`, -- Given `walletPubKeyHash` and `redeemerOutputScript` pair can be -used for only one pending request at the same time, -- Wallet must have enough Bitcoin balance to process the request. - -Note on upgradeability: -Bridge is an upgradeable contract deployed behind -a TransparentUpgradeableProxy. Accepting redemption data as bytes -provides great flexibility. The Bridge is just like any other -contract with a balance approved in the Bank and can be upgraded -to another version without being bound to a particular interface -forever. This flexibility comes with the cost - developers -integrating their vaults and dApps with `Bridge` using -`approveBalanceAndCall` need to pay extra attention to -`redemptionData` and adjust the code in case the expected structure -of `redemptionData` changes. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| balanceOwner | address | The address of the Bank balance owner whose balance is getting redeemed. | -| amount | uint256 | Requested amount in satoshi. This is also the Bank balance that is taken from the `balanceOwner` upon request. Once the request is handled, the actual amount of BTC locked on the redeemer output script will be always lower than this value since the treasury and Bitcoin transaction fees must be incurred. The minimal amount satisfying the request can be computed as: `amount - (amount / redemptionTreasuryFeeDivisor) - redemptionTxMaxFee`. Fees values are taken at the moment of request creation. | -| redemptionData | bytes | ABI-encoded redemption data: [ address redeemer, bytes20 walletPubKeyHash, bytes32 mainUtxoTxHash, uint32 mainUtxoTxOutputIndex, uint64 mainUtxoTxOutputValue, bytes redeemerOutputScript ] - redeemer: The Ethereum address of the redeemer who will be able to claim Bank balance if anything goes wrong during the redemption. In the most basic case, when someone redeems their balance from the Bank, `balanceOwner` is the same as `redeemer`. However, when a Vault is redeeming part of its balance for some redeemer address (for example, someone who has earlier deposited into that Vault), `balanceOwner` is the Vault, and `redeemer` is the address for which the vault is redeeming its balance to, - walletPubKeyHash: The 20-byte wallet public key hash (computed using Bitcoin HASH160 over the compressed ECDSA public key), - mainUtxoTxHash: Data of the wallet's main UTXO TX hash, as currently known on the Ethereum chain, - mainUtxoTxOutputIndex: Data of the wallet's main UTXO output index, as currently known on Ethereum chain, - mainUtxoTxOutputValue: Data of the wallet's main UTXO output value, as currently known on Ethereum chain, - redeemerOutputScript The redeemer's length-prefixed output script (P2PKH, P2WPKH, P2SH or P2WSH) that will be used to lock redeemed BTC. | - -### submitRedemptionProof - -```solidity -function submitRedemptionProof(struct BitcoinTx.Info redemptionTx, struct BitcoinTx.Proof redemptionProof, struct BitcoinTx.UTXO mainUtxo, bytes20 walletPubKeyHash) external -``` - -Used by the wallet to prove the BTC redemption transaction -and to make the necessary bookkeeping. Redemption is only -accepted if it satisfies SPV proof. - -The function is performing Bank balance updates by burning -the total redeemed Bitcoin amount from Bridge balance and -transferring the treasury fee sum to the treasury address. - -It is possible to prove the given redemption only one time. - -Requirements: -- `redemptionTx` components must match the expected structure. See -`BitcoinTx.Info` docs for reference. Their values must exactly -correspond to appropriate Bitcoin transaction fields to produce -a provable transaction hash, -- The `redemptionTx` should represent a Bitcoin transaction with -exactly 1 input that refers to the wallet's main UTXO. That -transaction should have 1..n outputs handling existing pending -redemption requests or pointing to reported timed out requests. -There can be also 1 optional output representing the -change and pointing back to the 20-byte wallet public key hash. -The change should be always present if the redeemed value sum -is lower than the total wallet's BTC balance, -- `redemptionProof` components must match the expected structure. -See `BitcoinTx.Proof` docs for reference. The `bitcoinHeaders` -field must contain a valid number of block headers, not less -than the `txProofDifficultyFactor` contract constant, -- `mainUtxo` components must point to the recent main UTXO -of the given wallet, as currently known on the Ethereum chain. -Additionally, the recent main UTXO on Ethereum must be set, -- `walletPubKeyHash` must be connected with the main UTXO used -as transaction single input. -Other remarks: -- Putting the change output as the first transaction output can -save some gas because the output processing loop begins each -iteration by checking whether the given output is the change -thus uses some gas for making the comparison. Once the change -is identified, that check is omitted in further iterations. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| redemptionTx | struct BitcoinTx.Info | Bitcoin redemption transaction data. | -| redemptionProof | struct BitcoinTx.Proof | Bitcoin redemption proof data. | -| mainUtxo | struct BitcoinTx.UTXO | Data of the wallet's main UTXO, as currently known on the Ethereum chain. | -| walletPubKeyHash | bytes20 | 20-byte public key hash (computed using Bitcoin HASH160 over the compressed ECDSA public key) of the wallet which performed the redemption transaction. | - -### notifyRedemptionTimeout - -```solidity -function notifyRedemptionTimeout(bytes20 walletPubKeyHash, uint32[] walletMembersIDs, bytes redeemerOutputScript) external -``` - -Notifies that there is a pending redemption request associated -with the given wallet, that has timed out. The redemption -request is identified by the key built as -`keccak256(keccak256(redeemerOutputScript) | walletPubKeyHash)`. -The results of calling this function: -- The pending redemptions value for the wallet will be decreased -by the requested amount (minus treasury fee), -- The tokens taken from the redeemer on redemption request will -be returned to the redeemer, -- The request will be moved from pending redemptions to -timed-out redemptions, -- If the state of the wallet is `Live` or `MovingFunds`, the -wallet operators will be slashed and the notifier will be -rewarded, -- If the state of wallet is `Live`, the wallet will be closed or -marked as `MovingFunds` (depending on the presence or absence -of the wallet's main UTXO) and the wallet will no longer be -marked as the active wallet (if it was marked as such). - -Requirements: -- The wallet must be in the Live or MovingFunds or Terminated state, -- The redemption request identified by `walletPubKeyHash` and -`redeemerOutputScript` must exist, -- 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 of the `WalletRegistry` contract, -- The amount of time defined by `redemptionTimeout` must have -passed since the redemption was requested (the request must be -timed-out). - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| walletPubKeyHash | bytes20 | 20-byte public key hash of the wallet. | -| walletMembersIDs | uint32[] | Identifiers of the wallet signing group members. | -| redeemerOutputScript | bytes | The redeemer's length-prefixed output script (P2PKH, P2WPKH, P2SH or P2WSH). | - -### submitMovingFundsCommitment - -```solidity -function submitMovingFundsCommitment(bytes20 walletPubKeyHash, struct BitcoinTx.UTXO walletMainUtxo, uint32[] walletMembersIDs, uint256 walletMemberIndex, bytes20[] targetWallets) external -``` - -Submits the moving funds target wallets commitment. -Once all requirements are met, that function registers the -target wallets commitment and opens the way for moving funds -proof submission. -The caller is reimbursed for the transaction costs. - -Requirements: -- The source wallet must be in the MovingFunds state, -- The source wallet must not have pending redemption requests, -- The source wallet must not have pending moved funds sweep requests, -- The source wallet must not have submitted its commitment already, -- The expression `keccak256(abi.encode(walletMembersIDs))` must -be exactly the same as the hash stored under `membersIdsHash` -for the given source wallet in the ECDSA registry. 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], -- The caller must be the member of the source wallet signing group -at the position indicated by `walletMemberIndex` parameter, -- The `walletMainUtxo` components must point to the recent main -UTXO of the source wallet, as currently known on the Ethereum -chain, -- Source wallet BTC balance must be greater than zero, -- At least one Live wallet must exist in the system, -- Submitted target wallets count must match the expected count -`N = min(liveWalletsCount, ceil(walletBtcBalance / walletMaxBtcTransfer))` -where `N > 0`, -- Each target wallet must be not equal to the source wallet, -- Each target wallet must follow the expected order i.e. all -target wallets 20-byte public key hashes represented as numbers -must form a strictly increasing sequence without duplicates, -- Each target wallet must be in Live state. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| walletPubKeyHash | bytes20 | 20-byte public key hash of the source wallet. | -| walletMainUtxo | struct BitcoinTx.UTXO | Data of the source wallet's main UTXO, as currently known on the Ethereum chain. | -| walletMembersIDs | uint32[] | Identifiers of the source wallet signing group members. | -| walletMemberIndex | uint256 | Position of the caller in the source wallet signing group members list. | -| targetWallets | bytes20[] | List of 20-byte public key hashes of the target wallets that the source wallet commits to move the funds to. | - -### resetMovingFundsTimeout - -```solidity -function resetMovingFundsTimeout(bytes20 walletPubKeyHash) external -``` - -Resets the moving funds timeout for the given wallet if the -target wallet commitment cannot be submitted due to a lack -of live wallets in the system. - -Requirements: -- The wallet must be in the MovingFunds state, -- The target wallets commitment must not be already submitted for -the given moving funds wallet, -- Live wallets count must be zero, -- The moving funds timeout reset delay must be elapsed. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| walletPubKeyHash | bytes20 | 20-byte public key hash of the moving funds wallet. | - -### submitMovingFundsProof - -```solidity -function submitMovingFundsProof(struct BitcoinTx.Info movingFundsTx, struct BitcoinTx.Proof movingFundsProof, struct BitcoinTx.UTXO mainUtxo, bytes20 walletPubKeyHash) external -``` - -Used by the wallet to prove the BTC moving funds transaction -and to make the necessary state changes. Moving funds is only -accepted if it satisfies SPV proof. - -The function validates the moving funds transaction structure -by checking if it actually spends the main UTXO of the declared -wallet and locks the value on the pre-committed target wallets -using a reasonable transaction fee. If all preconditions are -met, this functions closes the source wallet. - -It is possible to prove the given moving funds transaction only -one time. - -Requirements: -- `movingFundsTx` components must match the expected structure. See -`BitcoinTx.Info` docs for reference. Their values must exactly -correspond to appropriate Bitcoin transaction fields to produce -a provable transaction hash, -- The `movingFundsTx` should represent a Bitcoin transaction with -exactly 1 input that refers to the wallet's main UTXO. That -transaction should have 1..n outputs corresponding to the -pre-committed target wallets. Outputs must be ordered in the -same way as their corresponding target wallets are ordered -within the target wallets commitment, -- `movingFundsProof` components must match the expected structure. -See `BitcoinTx.Proof` docs for reference. The `bitcoinHeaders` -field must contain a valid number of block headers, not less -than the `txProofDifficultyFactor` contract constant, -- `mainUtxo` components must point to the recent main UTXO -of the given wallet, as currently known on the Ethereum chain. -Additionally, the recent main UTXO on Ethereum must be set, -- `walletPubKeyHash` must be connected with the main UTXO used -as transaction single input, -- The wallet that `walletPubKeyHash` points to must be in the -MovingFunds state, -- The target wallets commitment must be submitted by the wallet -that `walletPubKeyHash` points to, -- The total Bitcoin transaction fee must be lesser or equal -to `movingFundsTxMaxTotalFee` governable parameter. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| movingFundsTx | struct BitcoinTx.Info | Bitcoin moving funds transaction data. | -| movingFundsProof | struct BitcoinTx.Proof | Bitcoin moving funds proof data. | -| mainUtxo | struct BitcoinTx.UTXO | Data of the wallet's main UTXO, as currently known on the Ethereum chain. | -| walletPubKeyHash | bytes20 | 20-byte public key hash (computed using Bitcoin HASH160 over the compressed ECDSA public key) of the wallet which performed the moving funds transaction. | - -### notifyMovingFundsTimeout - -```solidity -function notifyMovingFundsTimeout(bytes20 walletPubKeyHash, uint32[] walletMembersIDs) external -``` - -Notifies about a timed out moving funds process. Terminates -the wallet and slashes signing group members as a result. - -Requirements: -- The wallet must be in the MovingFunds state, -- The moving funds timeout must be actually exceeded, -- 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 of the `WalletRegistry` contract. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| walletPubKeyHash | bytes20 | 20-byte public key hash of the wallet. | -| walletMembersIDs | uint32[] | Identifiers of the wallet signing group members. | - -### notifyMovingFundsBelowDust - -```solidity -function notifyMovingFundsBelowDust(bytes20 walletPubKeyHash, struct BitcoinTx.UTXO mainUtxo) external -``` - -Notifies about a moving funds wallet whose BTC balance is -below the moving funds dust threshold. Ends the moving funds -process and begins wallet closing immediately. - -Requirements: -- The wallet must be in the MovingFunds state, -- The `mainUtxo` components must point to the recent main UTXO -of the given wallet, as currently known on the Ethereum chain. -If the wallet has no main UTXO, this parameter can be empty as it -is ignored, -- The wallet BTC balance must be below the moving funds threshold. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| walletPubKeyHash | bytes20 | 20-byte public key hash of the wallet | -| mainUtxo | struct BitcoinTx.UTXO | Data of the wallet's main UTXO, as currently known on the Ethereum chain. | - -### submitMovedFundsSweepProof - -```solidity -function submitMovedFundsSweepProof(struct BitcoinTx.Info sweepTx, struct BitcoinTx.Proof sweepProof, struct BitcoinTx.UTXO mainUtxo) external -``` - -Used by the wallet to prove the BTC moved funds sweep -transaction and to make the necessary state changes. Moved -funds sweep is only accepted if it satisfies SPV proof. - -The function validates the sweep transaction structure by -checking if it actually spends the moved funds UTXO and the -sweeping wallet's main UTXO (optionally), and if it locks the -value on the sweeping wallet's 20-byte public key hash using a -reasonable transaction fee. If all preconditions are -met, this function updates the sweeping wallet main UTXO, thus -their BTC balance. - -It is possible to prove the given sweep transaction only -one time. - -Requirements: -- `sweepTx` components must match the expected structure. See -`BitcoinTx.Info` docs for reference. Their values must exactly -correspond to appropriate Bitcoin transaction fields to produce -a provable transaction hash, -- The `sweepTx` should represent a Bitcoin transaction with -the first input pointing to a moved funds sweep request targeted -to the wallet, and optionally, the second input pointing to the -wallet's main UTXO, if the sweeping wallet has a main UTXO set. -There should be only one output locking funds on the sweeping -wallet 20-byte public key hash, -- `sweepProof` components must match the expected structure. -See `BitcoinTx.Proof` docs for reference. The `bitcoinHeaders` -field must contain a valid number of block headers, not less -than the `txProofDifficultyFactor` contract constant, -- `mainUtxo` components must point to the recent main UTXO -of the sweeping wallet, as currently known on the Ethereum chain. -If there is no main UTXO, this parameter is ignored, -- The sweeping wallet must be in the Live or MovingFunds state, -- The total Bitcoin transaction fee must be lesser or equal -to `movedFundsSweepTxMaxTotalFee` governable parameter. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| sweepTx | struct BitcoinTx.Info | Bitcoin sweep funds transaction data. | -| sweepProof | struct BitcoinTx.Proof | Bitcoin sweep funds proof data. | -| mainUtxo | struct BitcoinTx.UTXO | Data of the sweeping wallet's main UTXO, as currently known on the Ethereum chain. | - -### notifyMovedFundsSweepTimeout - -```solidity -function notifyMovedFundsSweepTimeout(bytes32 movingFundsTxHash, uint32 movingFundsTxOutputIndex, uint32[] walletMembersIDs) external -``` - -Notifies about a timed out moved funds sweep process. If the -wallet is not terminated yet, that function terminates -the wallet and slashes signing group members as a result. -Marks the given sweep request as TimedOut. - -Requirements: -- The moved funds sweep request must be in the Pending state, -- The moved funds sweep timeout must be actually exceeded, -- The wallet must be either in the Live or MovingFunds or -Terminated state, -- 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 of the `WalletRegistry` contract. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| movingFundsTxHash | bytes32 | 32-byte hash of the moving funds transaction that caused the sweep request to be created. | -| movingFundsTxOutputIndex | uint32 | Index of the moving funds transaction output that is subject of the sweep request. | -| walletMembersIDs | uint32[] | Identifiers of the wallet signing group members. | - -### requestNewWallet - -```solidity -function requestNewWallet(struct BitcoinTx.UTXO activeWalletMainUtxo) external -``` - -Requests creation of a new wallet. This function just -forms a request and the creation process is performed -asynchronously. Once a wallet is created, the ECDSA Wallet -Registry will notify this contract by calling the -`__ecdsaWalletCreatedCallback` function. - -Requirements: -- `activeWalletMainUtxo` components must point to the recent main -UTXO of the given active wallet, as currently known on the -Ethereum chain. If there is no active wallet at the moment, or -the active wallet has no main UTXO, this parameter can be -empty as it is ignored, -- Wallet creation must not be in progress, -- If the active wallet is set, one of the following -conditions must be true: -- The active wallet BTC balance is above the minimum threshold -and the active wallet is old enough, i.e. the creation period -was elapsed since its creation time, -- The active wallet BTC balance is above the maximum threshold. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| activeWalletMainUtxo | struct BitcoinTx.UTXO | Data of the active wallet's main UTXO, as currently known on the Ethereum chain. | - -### __ecdsaWalletCreatedCallback - -```solidity -function __ecdsaWalletCreatedCallback(bytes32 ecdsaWalletID, bytes32 publicKeyX, bytes32 publicKeyY) external -``` - -A callback function that is called by the ECDSA Wallet Registry -once a new ECDSA wallet is created. - -Requirements: -- The only caller authorized to call this function is `registry`, -- Given wallet data must not belong to an already registered wallet. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| ecdsaWalletID | bytes32 | Wallet's unique identifier. | -| publicKeyX | bytes32 | Wallet's public key's X coordinate. | -| publicKeyY | bytes32 | Wallet's public key's Y coordinate. | - -### __ecdsaWalletHeartbeatFailedCallback - -```solidity -function __ecdsaWalletHeartbeatFailedCallback(bytes32, bytes32 publicKeyX, bytes32 publicKeyY) external -``` - -A callback function that is called by the ECDSA Wallet Registry -once a wallet heartbeat failure is detected. - -Requirements: -- The only caller authorized to call this function is `registry`, -- Wallet must be in Live state. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| | bytes32 | | -| publicKeyX | bytes32 | Wallet's public key's X coordinate. | -| publicKeyY | bytes32 | Wallet's public key's Y coordinate. | - -### notifyWalletCloseable - -```solidity -function notifyWalletCloseable(bytes20 walletPubKeyHash, struct BitcoinTx.UTXO walletMainUtxo) external -``` - -Notifies that the wallet is either old enough or has too few -satoshi left and qualifies to be closed. - -Requirements: -- Wallet must not be set as the current active wallet, -- Wallet must exceed the wallet maximum age OR the wallet BTC -balance must be lesser than the minimum threshold. If the latter -case is true, the `walletMainUtxo` components must point to the -recent main UTXO of the given wallet, as currently known on the -Ethereum chain. If the wallet has no main UTXO, this parameter -can be empty as it is ignored since the wallet balance is -assumed to be zero, -- Wallet must be in Live state. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| walletPubKeyHash | bytes20 | 20-byte public key hash of the wallet. | -| walletMainUtxo | struct BitcoinTx.UTXO | Data of the wallet's main UTXO, as currently known on the Ethereum chain. | - -### notifyWalletClosingPeriodElapsed - -```solidity -function notifyWalletClosingPeriodElapsed(bytes20 walletPubKeyHash) external -``` - -Notifies about the end of the closing period for the given wallet. -Closes the wallet ultimately and notifies the ECDSA registry -about this fact. - -Requirements: -- The wallet must be in the Closing state, -- The wallet closing period must have elapsed. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| walletPubKeyHash | bytes20 | 20-byte public key hash of the wallet. | - -### submitFraudChallenge - -```solidity -function submitFraudChallenge(bytes walletPublicKey, bytes preimageSha256, struct BitcoinTx.RSVSignature signature) external payable -``` - -Submits a fraud challenge indicating that a UTXO being under -wallet control was unlocked by the wallet but was not used -according to the protocol rules. That means the wallet signed -a transaction input pointing to that UTXO and there is a unique -sighash and signature pair associated with that input. This -function uses those parameters to create a fraud accusation that -proves a given transaction input unlocking the given UTXO was -actually signed by the wallet. This function cannot determine -whether the transaction was actually broadcast and the input was -consumed in a fraudulent way so it just opens a challenge period -during which the wallet can defeat the challenge by submitting -proof of a transaction that consumes the given input according -to protocol rules. To prevent spurious allegations, the caller -must deposit ETH that is returned back upon justified fraud -challenge or confiscated otherwise. - -Requirements: -- Wallet behind `walletPublicKey` must be in Live or MovingFunds -or Closing state, -- The challenger must send appropriate amount of ETH used as -fraud challenge deposit, -- The signature (represented by r, s and v) must be generated by -the wallet behind `walletPubKey` during signing of `sighash` -which was calculated from `preimageSha256`, -- Wallet can be challenged for the given signature only once. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| walletPublicKey | bytes | The public key of the wallet in the uncompressed and unprefixed format (64 bytes). | -| preimageSha256 | bytes | The hash that was generated by applying SHA-256 one time over the preimage used during input signing. The preimage is a serialized subset of the transaction and its structure depends on the transaction input (see BIP-143 for reference). Notice that applying SHA-256 over the `preimageSha256` results in `sighash`. The path from `preimage` to `sighash` looks like this: preimage -> (SHA-256) -> preimageSha256 -> (SHA-256) -> sighash. | -| signature | struct BitcoinTx.RSVSignature | Bitcoin signature in the R/S/V format. | - -### defeatFraudChallenge - -```solidity -function defeatFraudChallenge(bytes walletPublicKey, bytes preimage, bool witness) external -``` - -Allows to defeat a pending fraud challenge against a wallet if -the transaction that spends the UTXO follows the protocol rules. -In order to defeat the challenge the same `walletPublicKey` and -signature (represented by `r`, `s` and `v`) must be provided as -were used to calculate the sighash during input signing. -The fraud challenge defeat attempt will only succeed if the -inputs in the preimage are considered honestly spent by the -wallet. Therefore the transaction spending the UTXO must be -proven in the Bridge before a challenge defeat is called. -If successfully defeated, the fraud challenge is marked as -resolved and the amount of ether deposited by the challenger is -sent to the treasury. - -Requirements: -- `walletPublicKey` and `sighash` calculated as `hash256(preimage)` -must identify an open fraud challenge, -- the preimage must be a valid preimage of a transaction generated -according to the protocol rules and already proved in the Bridge, -- before a defeat attempt is made the transaction that spends the -given UTXO must be proven in the Bridge. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| walletPublicKey | bytes | The public key of the wallet in the uncompressed and unprefixed format (64 bytes). | -| preimage | bytes | The preimage which produces sighash used to generate the ECDSA signature that is the subject of the fraud claim. It is a serialized subset of the transaction. The exact subset used as the preimage depends on the transaction input the signature is produced for. See BIP-143 for reference. | -| witness | bool | Flag indicating whether the preimage was produced for a witness input. True for witness, false for non-witness input. | - -### defeatFraudChallengeWithHeartbeat - -```solidity -function defeatFraudChallengeWithHeartbeat(bytes walletPublicKey, bytes heartbeatMessage) external -``` - -Allows to defeat a pending fraud challenge against a wallet by -proving the sighash and signature were produced for an off-chain -wallet heartbeat message following a strict format. -In order to defeat the challenge the same `walletPublicKey` and -signature (represented by `r`, `s` and `v`) must be provided as -were used to calculate the sighash during heartbeat message -signing. The fraud challenge defeat attempt will only succeed if -the signed message follows a strict format required for -heartbeat messages. If successfully defeated, the fraud -challenge is marked as resolved and the amount of ether -deposited by the challenger is sent to the treasury. - -Requirements: -- `walletPublicKey` and `sighash` calculated as -`hash256(heartbeatMessage)` must identify an open fraud challenge, -- `heartbeatMessage` must follow a strict format of heartbeat -messages. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| walletPublicKey | bytes | The public key of the wallet in the uncompressed and unprefixed format (64 bytes). | -| heartbeatMessage | bytes | Off-chain heartbeat message meeting the heartbeat message format requirements which produces sighash used to generate the ECDSA signature that is the subject of the fraud claim. | - -### notifyFraudChallengeDefeatTimeout - -```solidity -function notifyFraudChallengeDefeatTimeout(bytes walletPublicKey, uint32[] walletMembersIDs, bytes preimageSha256) external -``` - -Notifies about defeat timeout for the given fraud challenge. -Can be called only if there was a fraud challenge identified by -the provided `walletPublicKey` and `sighash` and it was not -defeated on time. The amount of time that needs to pass after -a fraud challenge is reported is indicated by the -`challengeDefeatTimeout`. After a successful fraud challenge -defeat timeout notification the fraud challenge is marked as -resolved, the stake of each operator is slashed, the ether -deposited is returned to the challenger and the challenger is -rewarded. - -Requirements: -- The wallet must be in the Live or MovingFunds or Closing or -Terminated state, -- The `walletPublicKey` and `sighash` calculated from -`preimageSha256` must identify an open fraud challenge, -- 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 of the `WalletRegistry` contract, -- The amount of time indicated by `challengeDefeatTimeout` must pass -after the challenge was reported. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| walletPublicKey | bytes | The public key of the wallet in the uncompressed and unprefixed format (64 bytes). | -| walletMembersIDs | uint32[] | Identifiers of the wallet signing group members. | -| preimageSha256 | bytes | The hash that was generated by applying SHA-256 one time over the preimage used during input signing. The preimage is a serialized subset of the transaction and its structure depends on the transaction input (see BIP-143 for reference). Notice that applying SHA-256 over the `preimageSha256` results in `sighash`. The path from `preimage` to `sighash` looks like this: preimage -> (SHA-256) -> preimageSha256 -> (SHA-256) -> sighash. | - -### setVaultStatus - -```solidity -function setVaultStatus(address vault, bool isTrusted) external -``` - -Allows the Governance to mark the given vault address as trusted -or no longer trusted. Vaults are not trusted by default. -Trusted vault must meet the following criteria: -- `IVault.receiveBalanceIncrease` must have a known, low gas -cost, -- `IVault.receiveBalanceIncrease` must never revert. - -Without restricting reveal only to trusted vaults, malicious -vaults not meeting the criteria would be able to nuke sweep proof -transactions executed by ECDSA wallet with deposits routed to -them. -Can only be called by the Governance. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| vault | address | The address of the vault. | -| isTrusted | bool | flag indicating whether the vault is trusted or not. | - -### setSpvMaintainerStatus - -```solidity -function setSpvMaintainerStatus(address spvMaintainer, bool isTrusted) external -``` - -Allows the Governance to mark the given address as trusted -or no longer trusted SPV maintainer. Addresses are not trusted -as SPV maintainers by default. - -The SPV proof does not check whether the transaction is a part of -the Bitcoin mainnet, it only checks whether the transaction has been -mined performing the required amount of work as on Bitcoin mainnet. -The possibility of submitting SPV proofs is limited to trusted SPV -maintainers. The system expects transaction confirmations with the -required work accumulated, so trusted SPV maintainers can not prove -the transaction without providing the required Bitcoin proof of work. -Trusted maintainers address the issue of an economic game between -tBTC and Bitcoin mainnet where large Bitcoin mining pools can decide -to use their hash power to mine fake Bitcoin blocks to prove them in -tBTC instead of receiving Bitcoin miner rewards. -Can only be called by the Governance. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| spvMaintainer | address | The address of the SPV maintainer. | -| isTrusted | bool | flag indicating whether the address is trusted or not. | - -### updateDepositParameters - -```solidity -function updateDepositParameters(uint64 depositDustThreshold, uint64 depositTreasuryFeeDivisor, uint64 depositTxMaxFee, uint32 depositRevealAheadPeriod) external -``` - -of `depositTreasuryFeeDivisor` and `depositTxMaxFee` parameters -in order to make requests that can incur the treasury and -transaction fee and still satisfy the depositor. - -Requirements: -- Deposit dust threshold must be greater than zero, -- Deposit dust threshold must be greater than deposit TX max fee, -- Deposit transaction max fee must be greater than zero. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| depositDustThreshold | uint64 | | -| depositTreasuryFeeDivisor | uint64 | New value of the treasury fee divisor. It is the divisor used to compute the treasury fee taken from each deposit and transferred to the treasury upon sweep proof submission. That fee is computed as follows: `treasuryFee = depositedAmount / depositTreasuryFeeDivisor` For example, if the treasury fee needs to be 2% of each deposit, the `depositTreasuryFeeDivisor` should be set to `50` because `1/50 = 0.02 = 2%`. | -| depositTxMaxFee | uint64 | New value of the deposit tx max fee in satoshis. It is the maximum amount of BTC transaction fee that can be incurred by each swept deposit being part of the given sweep transaction. If the maximum BTC transaction fee is exceeded, such transaction is considered a fraud. | -| depositRevealAheadPeriod | uint32 | New value of the deposit reveal ahead period parameter in seconds. It defines the length of the period that must be preserved between the deposit reveal time and the deposit refund locktime. | - -### updateRedemptionParameters - -```solidity -function updateRedemptionParameters(uint64 redemptionDustThreshold, uint64 redemptionTreasuryFeeDivisor, uint64 redemptionTxMaxFee, uint64 redemptionTxMaxTotalFee, uint32 redemptionTimeout, uint96 redemptionTimeoutSlashingAmount, uint32 redemptionTimeoutNotifierRewardMultiplier) external -``` - -Updates parameters of redemptions. - -Requirements: -- Redemption dust threshold must be greater than moving funds dust -threshold, -- Redemption dust threshold must be greater than the redemption TX -max fee, -- Redemption transaction max fee must be greater than zero, -- Redemption transaction max total fee must be greater than or -equal to the redemption transaction per-request max fee, -- Redemption timeout must be greater than zero, -- Redemption timeout notifier reward multiplier must be in the -range [0, 100]. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| redemptionDustThreshold | uint64 | New value of the redemption dust threshold in satoshis. It is the minimal amount that can be requested for redemption. Value of this parameter must take into account the value of `redemptionTreasuryFeeDivisor` and `redemptionTxMaxFee` parameters in order to make requests that can incur the treasury and transaction fee and still satisfy the redeemer. | -| redemptionTreasuryFeeDivisor | uint64 | New value of the redemption treasury fee divisor. It is the divisor used to compute the treasury fee taken from each redemption request and transferred to the treasury upon successful request finalization. That fee is computed as follows: `treasuryFee = requestedAmount / redemptionTreasuryFeeDivisor` For example, if the treasury fee needs to be 2% of each redemption request, the `redemptionTreasuryFeeDivisor` should be set to `50` because `1/50 = 0.02 = 2%`. | -| redemptionTxMaxFee | uint64 | New value of the redemption transaction max fee in satoshis. It is the maximum amount of BTC transaction fee that can be incurred by each redemption request being part of the given redemption transaction. If the maximum BTC transaction fee is exceeded, such transaction is considered a fraud. This is a per-redemption output max fee for the redemption transaction. | -| redemptionTxMaxTotalFee | uint64 | New value of the redemption transaction max total fee in satoshis. It is the maximum amount of the total BTC transaction fee that is acceptable in a single redemption transaction. This is a _total_ max fee for the entire redemption transaction. | -| redemptionTimeout | uint32 | New value of the redemption timeout in seconds. It is the time after which the redemption request can be reported as timed out. It is counted from the moment when the redemption request was created via `requestRedemption` call. Reported timed out requests are cancelled and locked balance is returned to the redeemer in full amount. | -| redemptionTimeoutSlashingAmount | uint96 | New value of the redemption timeout slashing amount in T, it is the amount slashed from each wallet member for redemption timeout. | -| redemptionTimeoutNotifierRewardMultiplier | uint32 | New value of the redemption timeout notifier reward multiplier as percentage, it determines the percentage of the notifier reward from the staking contact the notifier of a redemption timeout receives. The value must be in the range [0, 100]. | - -### updateMovingFundsParameters - -```solidity -function updateMovingFundsParameters(uint64 movingFundsTxMaxTotalFee, uint64 movingFundsDustThreshold, uint32 movingFundsTimeoutResetDelay, uint32 movingFundsTimeout, uint96 movingFundsTimeoutSlashingAmount, uint32 movingFundsTimeoutNotifierRewardMultiplier, uint16 movingFundsCommitmentGasOffset, uint64 movedFundsSweepTxMaxTotalFee, uint32 movedFundsSweepTimeout, uint96 movedFundsSweepTimeoutSlashingAmount, uint32 movedFundsSweepTimeoutNotifierRewardMultiplier) external -``` - -Updates parameters of moving funds. - -Requirements: -- Moving funds transaction max total fee must be greater than zero, -- Moving funds dust threshold must be greater than zero and lower -than the redemption dust threshold, -- Moving funds timeout reset delay must be greater than zero, -- Moving funds timeout must be greater than the moving funds -timeout reset delay, -- Moving funds timeout notifier reward multiplier must be in the -range [0, 100], -- Moved funds sweep transaction max total fee must be greater than zero, -- Moved funds sweep timeout must be greater than zero, -- Moved funds sweep timeout notifier reward multiplier must be in the -range [0, 100]. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| movingFundsTxMaxTotalFee | uint64 | New value of the moving funds transaction max total fee in satoshis. It is the maximum amount of the total BTC transaction fee that is acceptable in a single moving funds transaction. This is a _total_ max fee for the entire moving funds transaction. | -| movingFundsDustThreshold | uint64 | New value of the moving funds dust threshold. It is the minimal satoshi amount that makes sense to be transferred during the moving funds process. Moving funds wallets having their BTC balance below that value can begin closing immediately as transferring such a low value may not be possible due to BTC network fees. | -| movingFundsTimeoutResetDelay | uint32 | New value of the moving funds timeout reset delay in seconds. It is the time after which the moving funds timeout can be reset in case the target wallet commitment cannot be submitted due to a lack of live wallets in the system. It is counted from the moment when the wallet was requested to move their funds and switched to the MovingFunds state or from the moment the timeout was reset the last time. | -| movingFundsTimeout | uint32 | New value of the moving funds timeout in seconds. It is the time after which the moving funds process can be reported as timed out. It is counted from the moment when the wallet was requested to move their funds and switched to the MovingFunds state. | -| movingFundsTimeoutSlashingAmount | uint96 | New value of the moving funds timeout slashing amount in T, it is the amount slashed from each wallet member for moving funds timeout. | -| movingFundsTimeoutNotifierRewardMultiplier | uint32 | New value of the moving funds timeout notifier reward multiplier as percentage, it determines the percentage of the notifier reward from the staking contact the notifier of a moving funds timeout receives. The value must be in the range [0, 100]. | -| movingFundsCommitmentGasOffset | uint16 | New value of the gas offset for moving funds target wallet commitment transaction gas costs reimbursement. | -| movedFundsSweepTxMaxTotalFee | uint64 | New value of the moved funds sweep transaction max total fee in satoshis. It is the maximum amount of the total BTC transaction fee that is acceptable in a single moved funds sweep transaction. This is a _total_ max fee for the entire moved funds sweep transaction. | -| movedFundsSweepTimeout | uint32 | New value of the moved funds sweep timeout in seconds. It is the time after which the moved funds sweep process can be reported as timed out. It is counted from the moment when the wallet was requested to sweep the received funds. | -| movedFundsSweepTimeoutSlashingAmount | uint96 | New value of the moved funds sweep timeout slashing amount in T, it is the amount slashed from each wallet member for moved funds sweep timeout. | -| movedFundsSweepTimeoutNotifierRewardMultiplier | uint32 | New value of the moved funds sweep timeout notifier reward multiplier as percentage, it determines the percentage of the notifier reward from the staking contact the notifier of a moved funds sweep timeout receives. The value must be in the range [0, 100]. | - -### updateWalletParameters - -```solidity -function updateWalletParameters(uint32 walletCreationPeriod, uint64 walletCreationMinBtcBalance, uint64 walletCreationMaxBtcBalance, uint64 walletClosureMinBtcBalance, uint32 walletMaxAge, uint64 walletMaxBtcTransfer, uint32 walletClosingPeriod) external -``` - -Requirements: -- Wallet maximum BTC balance must be greater than the wallet -minimum BTC balance, -- Wallet maximum BTC transfer must be greater than zero, -- Wallet closing period must be greater than zero. - -### updateFraudParameters - -```solidity -function updateFraudParameters(uint96 fraudChallengeDepositAmount, uint32 fraudChallengeDefeatTimeout, uint96 fraudSlashingAmount, uint32 fraudNotifierRewardMultiplier) external -``` - -Updates parameters related to frauds. - -Requirements: -- Fraud challenge defeat timeout must be greater than 0, -- Fraud notifier reward multiplier must be in the range [0, 100]. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| fraudChallengeDepositAmount | uint96 | New value of the fraud challenge deposit amount in wei, it is the amount of ETH the party challenging the wallet for fraud needs to deposit. | -| fraudChallengeDefeatTimeout | uint32 | New value of the challenge defeat timeout in seconds, it is the amount of time the wallet has to defeat a fraud challenge. The value must be greater than zero. | -| fraudSlashingAmount | uint96 | New value of the fraud slashing amount in T, it is the amount slashed from each wallet member for committing a fraud. | -| fraudNotifierRewardMultiplier | uint32 | New value of the fraud notifier reward multiplier as percentage, it determines the percentage of the notifier reward from the staking contact the notifier of a fraud receives. The value must be in the range [0, 100]. | - -### updateTreasury - -```solidity -function updateTreasury(address treasury) external -``` - -Updates treasury address. The treasury receives the system fees. - -The treasury address must not be 0x0. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| treasury | address | New value of the treasury address. | - -### deposits - -```solidity -function deposits(uint256 depositKey) external view returns (struct Deposit.DepositRequest) -``` - -Collection of all revealed deposits indexed by -keccak256(fundingTxHash | fundingOutputIndex). -The fundingTxHash is bytes32 (ordered as in Bitcoin internally) -and fundingOutputIndex an uint32. This mapping may contain valid -and invalid deposits and the wallet is responsible for -validating them before attempting to execute a sweep. - -### pendingRedemptions - -```solidity -function pendingRedemptions(uint256 redemptionKey) external view returns (struct Redemption.RedemptionRequest) -``` - -Collection of all pending redemption requests indexed by -redemption key built as -`keccak256(keccak256(redeemerOutputScript) | walletPubKeyHash)`. -The walletPubKeyHash is the 20-byte wallet's public key hash -(computed using Bitcoin HASH160 over the compressed ECDSA -public key) and `redeemerOutputScript` is a Bitcoin script -(P2PKH, P2WPKH, P2SH or P2WSH) that will be used to lock -redeemed BTC as requested by the redeemer. Requests are added -to this mapping by the `requestRedemption` method (duplicates -not allowed) and are removed by one of the following methods: -- `submitRedemptionProof` in case the request was handled -successfully, -- `notifyRedemptionTimeout` in case the request was reported -to be timed out. - -### timedOutRedemptions - -```solidity -function timedOutRedemptions(uint256 redemptionKey) external view returns (struct Redemption.RedemptionRequest) -``` - -Collection of all timed out redemptions requests indexed by -redemption key built as -`keccak256(keccak256(redeemerOutputScript) | walletPubKeyHash)`. -The walletPubKeyHash is the 20-byte wallet's public key hash -(computed using Bitcoin HASH160 over the compressed ECDSA -public key) and `redeemerOutputScript` is the Bitcoin script -(P2PKH, P2WPKH, P2SH or P2WSH) that is involved in the timed -out request. -Only one method can add to this mapping: -- `notifyRedemptionTimeout` which puts the redemption key -to this mapping based on a timed out request stored -previously in `pendingRedemptions` mapping. -Only one method can remove entries from this mapping: -- `submitRedemptionProof` in case the timed out redemption -request was a part of the proven transaction. - -### spentMainUTXOs - -```solidity -function spentMainUTXOs(uint256 utxoKey) external view returns (bool) -``` - -Collection of main UTXOs that are honestly spent indexed by -keccak256(fundingTxHash | fundingOutputIndex). The fundingTxHash -is bytes32 (ordered as in Bitcoin internally) and -fundingOutputIndex an uint32. A main UTXO is considered honestly -spent if it was used as an input of a transaction that have been -proven in the Bridge. - -### wallets - -```solidity -function wallets(bytes20 walletPubKeyHash) external view returns (struct Wallets.Wallet) -``` - -Gets details about a registered wallet. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| walletPubKeyHash | bytes20 | The 20-byte wallet public key hash (computed using Bitcoin HASH160 over the compressed ECDSA public key). | - -#### Return Values - -| Name | Type | Description | -| ---- | ---- | ----------- | -| [0] | struct Wallets.Wallet | Wallet details. | - -### activeWalletPubKeyHash - -```solidity -function activeWalletPubKeyHash() external view returns (bytes20) -``` - -Gets the public key hash of the active wallet. - -#### Return Values - -| Name | Type | Description | -| ---- | ---- | ----------- | -| [0] | bytes20 | The 20-byte public key hash (computed using Bitcoin HASH160 over the compressed ECDSA public key) of the active wallet. Returns bytes20(0) if there is no active wallet at the moment. | - -### liveWalletsCount - -```solidity -function liveWalletsCount() external view returns (uint32) -``` - -Gets the live wallets count. - -#### Return Values - -| Name | Type | Description | -| ---- | ---- | ----------- | -| [0] | uint32 | The current count of wallets being in the Live state. | - -### fraudChallenges - -```solidity -function fraudChallenges(uint256 challengeKey) external view returns (struct Fraud.FraudChallenge) -``` - -Returns the fraud challenge identified by the given key built -as keccak256(walletPublicKey|sighash). - -### movedFundsSweepRequests - -```solidity -function movedFundsSweepRequests(uint256 requestKey) external view returns (struct MovingFunds.MovedFundsSweepRequest) -``` - -Collection of all moved funds sweep requests indexed by -`keccak256(movingFundsTxHash | movingFundsOutputIndex)`. -The `movingFundsTxHash` is `bytes32` (ordered as in Bitcoin -internally) and `movingFundsOutputIndex` an `uint32`. Each entry -is actually an UTXO representing the moved funds and is supposed -to be swept with the current main UTXO of the recipient wallet. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| requestKey | uint256 | Request key built as `keccak256(movingFundsTxHash | movingFundsOutputIndex)`. | - -#### Return Values - -| Name | Type | Description | -| ---- | ---- | ----------- | -| [0] | struct MovingFunds.MovedFundsSweepRequest | Details of the moved funds sweep request. | - -### isVaultTrusted - -```solidity -function isVaultTrusted(address vault) external view returns (bool) -``` - -Indicates if the vault with the given address is trusted or not. -Depositors can route their revealed deposits only to trusted -vaults and have trusted vaults notified about new deposits as -soon as these deposits get swept. Vaults not trusted by the -Bridge can still be used by Bank balance owners on their own -responsibility - anyone can approve their Bank balance to any -address. - -### depositParameters - -```solidity -function depositParameters() external view returns (uint64 depositDustThreshold, uint64 depositTreasuryFeeDivisor, uint64 depositTxMaxFee, uint32 depositRevealAheadPeriod) -``` - -Returns the current values of Bridge deposit parameters. - -#### Return Values - -| Name | Type | Description | -| ---- | ---- | ----------- | -| depositDustThreshold | uint64 | The minimal amount that can be requested to deposit. Value of this parameter must take into account the value of `depositTreasuryFeeDivisor` and `depositTxMaxFee` parameters in order to make requests that can incur the treasury and transaction fee and still satisfy the depositor. | -| depositTreasuryFeeDivisor | uint64 | Divisor used to compute the treasury fee taken from each deposit and transferred to the treasury upon sweep proof submission. That fee is computed as follows: `treasuryFee = depositedAmount / depositTreasuryFeeDivisor` For example, if the treasury fee needs to be 2% of each deposit, the `depositTreasuryFeeDivisor` should be set to `50` because `1/50 = 0.02 = 2%`. | -| depositTxMaxFee | uint64 | Maximum amount of BTC transaction fee that can be incurred by each swept deposit being part of the given sweep transaction. If the maximum BTC transaction fee is exceeded, such transaction is considered a fraud. | -| depositRevealAheadPeriod | uint32 | Defines the length of the period that must be preserved between the deposit reveal time and the deposit refund locktime. For example, if the deposit become refundable on August 1st, and the ahead period is 7 days, the latest moment for deposit reveal is July 25th. Value in seconds. | - -### redemptionParameters - -```solidity -function redemptionParameters() external view returns (uint64 redemptionDustThreshold, uint64 redemptionTreasuryFeeDivisor, uint64 redemptionTxMaxFee, uint64 redemptionTxMaxTotalFee, uint32 redemptionTimeout, uint96 redemptionTimeoutSlashingAmount, uint32 redemptionTimeoutNotifierRewardMultiplier) -``` - -Returns the current values of Bridge redemption parameters. - -#### Return Values - -| Name | Type | Description | -| ---- | ---- | ----------- | -| redemptionDustThreshold | uint64 | The minimal amount that can be requested for redemption. Value of this parameter must take into account the value of `redemptionTreasuryFeeDivisor` and `redemptionTxMaxFee` parameters in order to make requests that can incur the treasury and transaction fee and still satisfy the redeemer. | -| redemptionTreasuryFeeDivisor | uint64 | Divisor used to compute the treasury fee taken from each redemption request and transferred to the treasury upon successful request finalization. That fee is computed as follows: `treasuryFee = requestedAmount / redemptionTreasuryFeeDivisor` For example, if the treasury fee needs to be 2% of each redemption request, the `redemptionTreasuryFeeDivisor` should be set to `50` because `1/50 = 0.02 = 2%`. | -| redemptionTxMaxFee | uint64 | Maximum amount of BTC transaction fee that can be incurred by each redemption request being part of the given redemption transaction. If the maximum BTC transaction fee is exceeded, such transaction is considered a fraud. This is a per-redemption output max fee for the redemption transaction. | -| redemptionTxMaxTotalFee | uint64 | Maximum amount of the total BTC transaction fee that is acceptable in a single redemption transaction. This is a _total_ max fee for the entire redemption transaction. | -| redemptionTimeout | uint32 | Time after which the redemption request can be reported as timed out. It is counted from the moment when the redemption request was created via `requestRedemption` call. Reported timed out requests are cancelled and locked balance is returned to the redeemer in full amount. | -| redemptionTimeoutSlashingAmount | uint96 | The amount of stake slashed from each member of a wallet for a redemption timeout. | -| redemptionTimeoutNotifierRewardMultiplier | uint32 | The percentage of the notifier reward from the staking contract the notifier of a redemption timeout receives. The value is in the range [0, 100]. | - -### movingFundsParameters - -```solidity -function movingFundsParameters() external view returns (uint64 movingFundsTxMaxTotalFee, uint64 movingFundsDustThreshold, uint32 movingFundsTimeoutResetDelay, uint32 movingFundsTimeout, uint96 movingFundsTimeoutSlashingAmount, uint32 movingFundsTimeoutNotifierRewardMultiplier, uint16 movingFundsCommitmentGasOffset, uint64 movedFundsSweepTxMaxTotalFee, uint32 movedFundsSweepTimeout, uint96 movedFundsSweepTimeoutSlashingAmount, uint32 movedFundsSweepTimeoutNotifierRewardMultiplier) -``` - -Returns the current values of Bridge moving funds between -wallets parameters. - -#### Return Values - -| Name | Type | Description | -| ---- | ---- | ----------- | -| movingFundsTxMaxTotalFee | uint64 | Maximum amount of the total BTC transaction fee that is acceptable in a single moving funds transaction. This is a _total_ max fee for the entire moving funds transaction. | -| movingFundsDustThreshold | uint64 | The minimal satoshi amount that makes sense to be transferred during the moving funds process. Moving funds wallets having their BTC balance below that value can begin closing immediately as transferring such a low value may not be possible due to BTC network fees. | -| movingFundsTimeoutResetDelay | uint32 | Time after which the moving funds timeout can be reset in case the target wallet commitment cannot be submitted due to a lack of live wallets in the system. It is counted from the moment when the wallet was requested to move their funds and switched to the MovingFunds state or from the moment the timeout was reset the last time. Value in seconds This value should be lower than the value of the `movingFundsTimeout`. | -| movingFundsTimeout | uint32 | Time after which the moving funds process can be reported as timed out. It is counted from the moment when the wallet was requested to move their funds and switched to the MovingFunds state. Value in seconds. | -| movingFundsTimeoutSlashingAmount | uint96 | The amount of stake slashed from each member of a wallet for a moving funds timeout. | -| movingFundsTimeoutNotifierRewardMultiplier | uint32 | The percentage of the notifier reward from the staking contract the notifier of a moving funds timeout receives. The value is in the range [0, 100]. | -| movingFundsCommitmentGasOffset | uint16 | The gas offset used for the moving funds target wallet commitment transaction cost reimbursement. | -| movedFundsSweepTxMaxTotalFee | uint64 | Maximum amount of the total BTC transaction fee that is acceptable in a single moved funds sweep transaction. This is a _total_ max fee for the entire moved funds sweep transaction. | -| movedFundsSweepTimeout | uint32 | Time after which the moved funds sweep process can be reported as timed out. It is counted from the moment when the wallet was requested to sweep the received funds. Value in seconds. | -| movedFundsSweepTimeoutSlashingAmount | uint96 | The amount of stake slashed from each member of a wallet for a moved funds sweep timeout. | -| movedFundsSweepTimeoutNotifierRewardMultiplier | uint32 | The percentage of the notifier reward from the staking contract the notifier of a moved funds sweep timeout receives. The value is in the range [0, 100]. | - -### walletParameters - -```solidity -function walletParameters() external view returns (uint32 walletCreationPeriod, uint64 walletCreationMinBtcBalance, uint64 walletCreationMaxBtcBalance, uint64 walletClosureMinBtcBalance, uint32 walletMaxAge, uint64 walletMaxBtcTransfer, uint32 walletClosingPeriod) -``` - -#### Return Values - -| Name | Type | Description | -| ---- | ---- | ----------- | -| walletCreationPeriod | uint32 | Determines how frequently a new wallet creation can be requested. Value in seconds. | -| walletCreationMinBtcBalance | uint64 | The minimum BTC threshold in satoshi that is used to decide about wallet creation. | -| walletCreationMaxBtcBalance | uint64 | The maximum BTC threshold in satoshi that is used to decide about wallet creation. | -| walletClosureMinBtcBalance | uint64 | The minimum BTC threshold in satoshi that is used to decide about wallet closure. | -| walletMaxAge | uint32 | The maximum age of a wallet in seconds, after which the wallet moving funds process can be requested. | -| walletMaxBtcTransfer | uint64 | The maximum BTC amount in satoshi than can be transferred to a single target wallet during the moving funds process. | -| walletClosingPeriod | uint32 | Determines the length of the wallet closing period, i.e. the period when the wallet remains in the Closing state and can be subject of deposit fraud challenges. Value in seconds. | - -### fraudParameters - -```solidity -function fraudParameters() external view returns (uint96 fraudChallengeDepositAmount, uint32 fraudChallengeDefeatTimeout, uint96 fraudSlashingAmount, uint32 fraudNotifierRewardMultiplier) -``` - -Returns the current values of Bridge fraud parameters. - -#### Return Values - -| Name | Type | Description | -| ---- | ---- | ----------- | -| fraudChallengeDepositAmount | uint96 | The amount of ETH in wei the party challenging the wallet for fraud needs to deposit. | -| fraudChallengeDefeatTimeout | uint32 | The amount of time the wallet has to defeat a fraud challenge. | -| fraudSlashingAmount | uint96 | The amount slashed from each wallet member for committing a fraud. | -| fraudNotifierRewardMultiplier | uint32 | The percentage of the notifier reward from the staking contract the notifier of a fraud receives. The value is in the range [0, 100]. | - -### contractReferences - -```solidity -function contractReferences() external view returns (contract Bank bank, contract IRelay relay, contract IWalletRegistry ecdsaWalletRegistry, contract ReimbursementPool reimbursementPool) -``` - -Returns the addresses of contracts Bridge is interacting with. - -#### Return Values - -| Name | Type | Description | -| ---- | ---- | ----------- | -| bank | contract Bank | Address of the Bank the Bridge belongs to. | -| relay | contract IRelay | Address of the Bitcoin relay providing the current Bitcoin network difficulty. | -| ecdsaWalletRegistry | contract IWalletRegistry | Address of the ECDSA Wallet Registry. | -| reimbursementPool | contract ReimbursementPool | Address of the Reimbursement Pool. | - -### treasury - -```solidity -function treasury() external view returns (address) -``` - -Address where the deposit treasury fees will be sent to. -Treasury takes part in the operators rewarding process. - -### txProofDifficultyFactor - -```solidity -function txProofDifficultyFactor() external view returns (uint256) -``` - -The number of confirmations on the Bitcoin chain required to -successfully evaluate an SPV proof. - -## BridgeGovernance - -Owns the `Bridge` contract and is responsible for updating -its governable parameters in respect to governance delay individual -for each parameter. The other responsibility is marking a vault -address as trusted or no longer trusted. - -### depositData - -```solidity -struct BridgeGovernanceParameters.DepositData depositData -``` - -### redemptionData - -```solidity -struct BridgeGovernanceParameters.RedemptionData redemptionData -``` - -### movingFundsData - -```solidity -struct BridgeGovernanceParameters.MovingFundsData movingFundsData -``` - -### walletData - -```solidity -struct BridgeGovernanceParameters.WalletData walletData -``` - -### fraudData - -```solidity -struct BridgeGovernanceParameters.FraudData fraudData -``` - -### treasuryData - -```solidity -struct BridgeGovernanceParameters.TreasuryData treasuryData -``` - -### bridge - -```solidity -contract Bridge bridge -``` - -### governanceDelays - -```solidity -uint256[3] governanceDelays -``` - -### bridgeGovernanceTransferChangeInitiated - -```solidity -uint256 bridgeGovernanceTransferChangeInitiated -``` - -### newBridgeGovernance - -```solidity -address newBridgeGovernance -``` - -### BridgeGovernanceTransferStarted - -```solidity -event BridgeGovernanceTransferStarted(address newBridgeGovernance, uint256 timestamp) -``` - -### DepositDustThresholdUpdateStarted - -```solidity -event DepositDustThresholdUpdateStarted(uint64 newDepositDustThreshold, uint256 timestamp) -``` - -### DepositDustThresholdUpdated - -```solidity -event DepositDustThresholdUpdated(uint64 depositDustThreshold) -``` - -### DepositTreasuryFeeDivisorUpdateStarted - -```solidity -event DepositTreasuryFeeDivisorUpdateStarted(uint64 depositTreasuryFeeDivisor, uint256 timestamp) -``` - -### DepositTreasuryFeeDivisorUpdated - -```solidity -event DepositTreasuryFeeDivisorUpdated(uint64 depositTreasuryFeeDivisor) -``` - -### DepositTxMaxFeeUpdateStarted - -```solidity -event DepositTxMaxFeeUpdateStarted(uint64 newDepositTxMaxFee, uint256 timestamp) -``` - -### DepositTxMaxFeeUpdated - -```solidity -event DepositTxMaxFeeUpdated(uint64 depositTxMaxFee) -``` - -### DepositRevealAheadPeriodUpdateStarted - -```solidity -event DepositRevealAheadPeriodUpdateStarted(uint32 newDepositRevealAheadPeriod, uint256 timestamp) -``` - -### DepositRevealAheadPeriodUpdated - -```solidity -event DepositRevealAheadPeriodUpdated(uint32 depositRevealAheadPeriod) -``` - -### RedemptionDustThresholdUpdateStarted - -```solidity -event RedemptionDustThresholdUpdateStarted(uint64 newRedemptionDustThreshold, uint256 timestamp) -``` - -### RedemptionDustThresholdUpdated - -```solidity -event RedemptionDustThresholdUpdated(uint64 redemptionDustThreshold) -``` - -### RedemptionTreasuryFeeDivisorUpdateStarted - -```solidity -event RedemptionTreasuryFeeDivisorUpdateStarted(uint64 newRedemptionTreasuryFeeDivisor, uint256 timestamp) -``` - -### RedemptionTreasuryFeeDivisorUpdated - -```solidity -event RedemptionTreasuryFeeDivisorUpdated(uint64 redemptionTreasuryFeeDivisor) -``` - -### RedemptionTxMaxFeeUpdateStarted - -```solidity -event RedemptionTxMaxFeeUpdateStarted(uint64 newRedemptionTxMaxFee, uint256 timestamp) -``` - -### RedemptionTxMaxFeeUpdated - -```solidity -event RedemptionTxMaxFeeUpdated(uint64 redemptionTxMaxFee) -``` - -### RedemptionTxMaxTotalFeeUpdateStarted - -```solidity -event RedemptionTxMaxTotalFeeUpdateStarted(uint64 newRedemptionTxMaxTotalFee, uint256 timestamp) -``` - -### RedemptionTxMaxTotalFeeUpdated - -```solidity -event RedemptionTxMaxTotalFeeUpdated(uint64 redemptionTxMaxTotalFee) -``` - -### RedemptionTimeoutUpdateStarted - -```solidity -event RedemptionTimeoutUpdateStarted(uint32 newRedemptionTimeout, uint256 timestamp) -``` - -### RedemptionTimeoutUpdated - -```solidity -event RedemptionTimeoutUpdated(uint32 redemptionTimeout) -``` - -### RedemptionTimeoutSlashingAmountUpdateStarted - -```solidity -event RedemptionTimeoutSlashingAmountUpdateStarted(uint96 newRedemptionTimeoutSlashingAmount, uint256 timestamp) -``` - -### RedemptionTimeoutSlashingAmountUpdated - -```solidity -event RedemptionTimeoutSlashingAmountUpdated(uint96 redemptionTimeoutSlashingAmount) -``` - -### RedemptionTimeoutNotifierRewardMultiplierUpdateStarted - -```solidity -event RedemptionTimeoutNotifierRewardMultiplierUpdateStarted(uint32 newRedemptionTimeoutNotifierRewardMultiplier, uint256 timestamp) -``` - -### RedemptionTimeoutNotifierRewardMultiplierUpdated - -```solidity -event RedemptionTimeoutNotifierRewardMultiplierUpdated(uint32 redemptionTimeoutNotifierRewardMultiplier) -``` - -### MovingFundsTxMaxTotalFeeUpdateStarted - -```solidity -event MovingFundsTxMaxTotalFeeUpdateStarted(uint64 newMovingFundsTxMaxTotalFee, uint256 timestamp) -``` - -### MovingFundsTxMaxTotalFeeUpdated - -```solidity -event MovingFundsTxMaxTotalFeeUpdated(uint64 movingFundsTxMaxTotalFee) -``` - -### MovingFundsDustThresholdUpdateStarted - -```solidity -event MovingFundsDustThresholdUpdateStarted(uint64 newMovingFundsDustThreshold, uint256 timestamp) -``` - -### MovingFundsDustThresholdUpdated - -```solidity -event MovingFundsDustThresholdUpdated(uint64 movingFundsDustThreshold) -``` - -### MovingFundsTimeoutResetDelayUpdateStarted - -```solidity -event MovingFundsTimeoutResetDelayUpdateStarted(uint32 newMovingFundsTimeoutResetDelay, uint256 timestamp) -``` - -### MovingFundsTimeoutResetDelayUpdated - -```solidity -event MovingFundsTimeoutResetDelayUpdated(uint32 movingFundsTimeoutResetDelay) -``` - -### MovingFundsTimeoutUpdateStarted - -```solidity -event MovingFundsTimeoutUpdateStarted(uint32 newMovingFundsTimeout, uint256 timestamp) -``` - -### MovingFundsTimeoutUpdated - -```solidity -event MovingFundsTimeoutUpdated(uint32 movingFundsTimeout) -``` - -### MovingFundsTimeoutSlashingAmountUpdateStarted - -```solidity -event MovingFundsTimeoutSlashingAmountUpdateStarted(uint96 newMovingFundsTimeoutSlashingAmount, uint256 timestamp) -``` - -### MovingFundsTimeoutSlashingAmountUpdated - -```solidity -event MovingFundsTimeoutSlashingAmountUpdated(uint96 movingFundsTimeoutSlashingAmount) -``` - -### MovingFundsTimeoutNotifierRewardMultiplierUpdateStarted - -```solidity -event MovingFundsTimeoutNotifierRewardMultiplierUpdateStarted(uint32 newMovingFundsTimeoutNotifierRewardMultiplier, uint256 timestamp) -``` - -### MovingFundsTimeoutNotifierRewardMultiplierUpdated - -```solidity -event MovingFundsTimeoutNotifierRewardMultiplierUpdated(uint32 movingFundsTimeoutNotifierRewardMultiplier) -``` - -### MovingFundsCommitmentGasOffsetUpdateStarted - -```solidity -event MovingFundsCommitmentGasOffsetUpdateStarted(uint16 newMovingFundsCommitmentGasOffset, uint256 timestamp) -``` - -### MovingFundsCommitmentGasOffsetUpdated - -```solidity -event MovingFundsCommitmentGasOffsetUpdated(uint16 movingFundsCommitmentGasOffset) -``` - -### MovedFundsSweepTxMaxTotalFeeUpdateStarted - -```solidity -event MovedFundsSweepTxMaxTotalFeeUpdateStarted(uint64 newMovedFundsSweepTxMaxTotalFee, uint256 timestamp) -``` - -### MovedFundsSweepTxMaxTotalFeeUpdated - -```solidity -event MovedFundsSweepTxMaxTotalFeeUpdated(uint64 movedFundsSweepTxMaxTotalFee) -``` - -### MovedFundsSweepTimeoutUpdateStarted - -```solidity -event MovedFundsSweepTimeoutUpdateStarted(uint32 newMovedFundsSweepTimeout, uint256 timestamp) -``` - -### MovedFundsSweepTimeoutUpdated - -```solidity -event MovedFundsSweepTimeoutUpdated(uint32 movedFundsSweepTimeout) -``` - -### MovedFundsSweepTimeoutSlashingAmountUpdateStarted - -```solidity -event MovedFundsSweepTimeoutSlashingAmountUpdateStarted(uint96 newMovedFundsSweepTimeoutSlashingAmount, uint256 timestamp) -``` - -### MovedFundsSweepTimeoutSlashingAmountUpdated - -```solidity -event MovedFundsSweepTimeoutSlashingAmountUpdated(uint96 movedFundsSweepTimeoutSlashingAmount) -``` - -### MovedFundsSweepTimeoutNotifierRewardMultiplierUpdateStarted - -```solidity -event MovedFundsSweepTimeoutNotifierRewardMultiplierUpdateStarted(uint32 newMovedFundsSweepTimeoutNotifierRewardMultiplier, uint256 timestamp) -``` - -### MovedFundsSweepTimeoutNotifierRewardMultiplierUpdated - -```solidity -event MovedFundsSweepTimeoutNotifierRewardMultiplierUpdated(uint32 movedFundsSweepTimeoutNotifierRewardMultiplier) -``` - -### WalletCreationPeriodUpdateStarted - -```solidity -event WalletCreationPeriodUpdateStarted(uint32 newWalletCreationPeriod, uint256 timestamp) -``` - -### WalletCreationPeriodUpdated - -```solidity -event WalletCreationPeriodUpdated(uint32 walletCreationPeriod) -``` - -### WalletCreationMinBtcBalanceUpdateStarted - -```solidity -event WalletCreationMinBtcBalanceUpdateStarted(uint64 newWalletCreationMinBtcBalance, uint256 timestamp) -``` - -### WalletCreationMinBtcBalanceUpdated - -```solidity -event WalletCreationMinBtcBalanceUpdated(uint64 walletCreationMinBtcBalance) -``` - -### WalletCreationMaxBtcBalanceUpdateStarted - -```solidity -event WalletCreationMaxBtcBalanceUpdateStarted(uint64 newWalletCreationMaxBtcBalance, uint256 timestamp) -``` - -### WalletCreationMaxBtcBalanceUpdated - -```solidity -event WalletCreationMaxBtcBalanceUpdated(uint64 walletCreationMaxBtcBalance) -``` - -### WalletClosureMinBtcBalanceUpdateStarted - -```solidity -event WalletClosureMinBtcBalanceUpdateStarted(uint64 newWalletClosureMinBtcBalance, uint256 timestamp) -``` - -### WalletClosureMinBtcBalanceUpdated - -```solidity -event WalletClosureMinBtcBalanceUpdated(uint64 walletClosureMinBtcBalance) -``` - -### WalletMaxAgeUpdateStarted - -```solidity -event WalletMaxAgeUpdateStarted(uint32 newWalletMaxAge, uint256 timestamp) -``` - -### WalletMaxAgeUpdated - -```solidity -event WalletMaxAgeUpdated(uint32 walletMaxAge) -``` - -### WalletMaxBtcTransferUpdateStarted - -```solidity -event WalletMaxBtcTransferUpdateStarted(uint64 newWalletMaxBtcTransfer, uint256 timestamp) -``` - -### WalletMaxBtcTransferUpdated - -```solidity -event WalletMaxBtcTransferUpdated(uint64 walletMaxBtcTransfer) -``` - -### WalletClosingPeriodUpdateStarted - -```solidity -event WalletClosingPeriodUpdateStarted(uint32 newWalletClosingPeriod, uint256 timestamp) -``` - -### WalletClosingPeriodUpdated - -```solidity -event WalletClosingPeriodUpdated(uint32 walletClosingPeriod) -``` - -### FraudChallengeDepositAmountUpdateStarted - -```solidity -event FraudChallengeDepositAmountUpdateStarted(uint96 newFraudChallengeDepositAmount, uint256 timestamp) -``` - -### FraudChallengeDepositAmountUpdated - -```solidity -event FraudChallengeDepositAmountUpdated(uint96 fraudChallengeDepositAmount) -``` - -### FraudChallengeDefeatTimeoutUpdateStarted - -```solidity -event FraudChallengeDefeatTimeoutUpdateStarted(uint32 newFraudChallengeDefeatTimeout, uint256 timestamp) -``` - -### FraudChallengeDefeatTimeoutUpdated - -```solidity -event FraudChallengeDefeatTimeoutUpdated(uint32 fraudChallengeDefeatTimeout) -``` - -### FraudSlashingAmountUpdateStarted - -```solidity -event FraudSlashingAmountUpdateStarted(uint96 newFraudSlashingAmount, uint256 timestamp) -``` - -### FraudSlashingAmountUpdated - -```solidity -event FraudSlashingAmountUpdated(uint96 fraudSlashingAmount) -``` - -### FraudNotifierRewardMultiplierUpdateStarted - -```solidity -event FraudNotifierRewardMultiplierUpdateStarted(uint32 newFraudNotifierRewardMultiplier, uint256 timestamp) -``` - -### FraudNotifierRewardMultiplierUpdated - -```solidity -event FraudNotifierRewardMultiplierUpdated(uint32 fraudNotifierRewardMultiplier) -``` - -### TreasuryUpdateStarted - -```solidity -event TreasuryUpdateStarted(address newTreasury, uint256 timestamp) -``` - -### TreasuryUpdated - -```solidity -event TreasuryUpdated(address treasury) -``` - -### constructor - -```solidity -constructor(contract Bridge _bridge, uint256 _governanceDelay) public -``` - -### setVaultStatus - -```solidity -function setVaultStatus(address vault, bool isTrusted) external -``` - -Allows the Governance to mark the given vault address as trusted -or no longer trusted. Vaults are not trusted by default. -Trusted vault must meet the following criteria: -- `IVault.receiveBalanceIncrease` must have a known, low gas -cost, -- `IVault.receiveBalanceIncrease` must never revert. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| vault | address | The address of the vault. | -| isTrusted | bool | flag indicating whether the vault is trusted or not. | - -### setSpvMaintainerStatus - -```solidity -function setSpvMaintainerStatus(address spvMaintainer, bool isTrusted) external -``` - -Allows the Governance to mark the given address as trusted -or no longer trusted SPV maintainer. Addresses are not trusted -as SPV maintainers by default. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| spvMaintainer | address | The address of the SPV maintainer. | -| isTrusted | bool | flag indicating whether the address is trusted or not. | - -### beginGovernanceDelayUpdate - -```solidity -function beginGovernanceDelayUpdate(uint256 _newGovernanceDelay) external -``` - -Begins the governance delay update process. - -Can be called only by the contract owner. The event that informs about -the start of the governance delay was skipped on purpose to trim -the contract size. All the params inside of the `governanceDelays` -array are public and can be easily fetched. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| _newGovernanceDelay | uint256 | New governance delay | - -### finalizeGovernanceDelayUpdate - -```solidity -function finalizeGovernanceDelayUpdate() external -``` - -Finalizes the governance delay update process. - -Can be called only by the contract owner, after the governance -delay elapses. Updated event was skipped on purpose to trim the -contract size. All the params inside of the `governanceDelays` -array are public and can be easily fetched. - -### beginBridgeGovernanceTransfer - -```solidity -function beginBridgeGovernanceTransfer(address _newBridgeGovernance) external -``` - -Begins the Bridge governance transfer process. - -Can be called only by the contract owner. It is the governance -responsibility to validate the correctness of the new Bridge -Governance contract. The other reason for not adding this check is -to go down with the contract size and leaving only the essential code. - -### finalizeBridgeGovernanceTransfer - -```solidity -function finalizeBridgeGovernanceTransfer() external -``` - -Finalizes the bridge governance transfer process. - -Can be called only by the contract owner, after the governance -delay elapses. Bridge governance transferred event can be read -from the Governable bridge contract 'GovernanceTransferred(old, new)'. -Event that informs about the transfer in this function is skipped on -purpose to go down with the contract size. - -### beginDepositDustThresholdUpdate - -```solidity -function beginDepositDustThresholdUpdate(uint64 _newDepositDustThreshold) external -``` - -Begins the deposit dust threshold amount update process. - -Can be called only by the contract owner. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| _newDepositDustThreshold | uint64 | New deposit dust threshold amount. | - -### finalizeDepositDustThresholdUpdate - -```solidity -function finalizeDepositDustThresholdUpdate() external -``` - -Finalizes the deposit dust threshold amount update process. - -Can be called only by the contract owner, after the governance -delay elapses. - -### beginDepositTreasuryFeeDivisorUpdate - -```solidity -function beginDepositTreasuryFeeDivisorUpdate(uint64 _newDepositTreasuryFeeDivisor) external -``` - -Begins the deposit treasury fee divisor amount update process. - -Can be called only by the contract owner. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| _newDepositTreasuryFeeDivisor | uint64 | New deposit treasury fee divisor. | - -### finalizeDepositTreasuryFeeDivisorUpdate - -```solidity -function finalizeDepositTreasuryFeeDivisorUpdate() external -``` - -Finalizes the deposit treasury fee divisor amount update process. - -Can be called only by the contract owner, after the governance -delay elapses. - -### beginDepositTxMaxFeeUpdate - -```solidity -function beginDepositTxMaxFeeUpdate(uint64 _newDepositTxMaxFee) external -``` - -Begins the deposit tx max fee amount update process. - -Can be called only by the contract owner. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| _newDepositTxMaxFee | uint64 | New deposit tx max fee. | - -### finalizeDepositTxMaxFeeUpdate - -```solidity -function finalizeDepositTxMaxFeeUpdate() external -``` - -Finalizes the deposit tx max fee amount update process. - -Can be called only by the contract owner, after the governance -delay elapses. - -### beginDepositRevealAheadPeriodUpdate - -```solidity -function beginDepositRevealAheadPeriodUpdate(uint32 _newDepositRevealAheadPeriod) external -``` - -Begins the deposit reveal ahead period update process. - -Can be called only by the contract owner. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| _newDepositRevealAheadPeriod | uint32 | New deposit reveal ahead period. | - -### finalizeDepositRevealAheadPeriodUpdate - -```solidity -function finalizeDepositRevealAheadPeriodUpdate() external -``` - -Finalizes the deposit reveal ahead period update process. - -Can be called only by the contract owner, after the governance -delay elapses. - -### beginRedemptionDustThresholdUpdate - -```solidity -function beginRedemptionDustThresholdUpdate(uint64 _newRedemptionDustThreshold) external -``` - -Begins the redemption dust threshold amount update process. - -Can be called only by the contract owner. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| _newRedemptionDustThreshold | uint64 | New redemption dust threshold. | - -### finalizeRedemptionDustThresholdUpdate - -```solidity -function finalizeRedemptionDustThresholdUpdate() external -``` - -Finalizes the dust threshold amount update process. - -Can be called only by the contract owner, after the governance -delay elapses. - -### beginRedemptionTreasuryFeeDivisorUpdate - -```solidity -function beginRedemptionTreasuryFeeDivisorUpdate(uint64 _newRedemptionTreasuryFeeDivisor) external -``` - -Begins the redemption treasury fee divisor amount update process. - -Can be called only by the contract owner. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| _newRedemptionTreasuryFeeDivisor | uint64 | New redemption treasury fee divisor. | - -### finalizeRedemptionTreasuryFeeDivisorUpdate - -```solidity -function finalizeRedemptionTreasuryFeeDivisorUpdate() external -``` - -Finalizes the redemption treasury fee divisor amount update process. - -Can be called only by the contract owner, after the governance -delay elapses. - -### beginRedemptionTxMaxFeeUpdate - -```solidity -function beginRedemptionTxMaxFeeUpdate(uint64 _newRedemptionTxMaxFee) external -``` - -Begins the redemption tx max fee amount update process. - -Can be called only by the contract owner. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| _newRedemptionTxMaxFee | uint64 | New redemption tx max fee. | - -### finalizeRedemptionTxMaxFeeUpdate - -```solidity -function finalizeRedemptionTxMaxFeeUpdate() external -``` - -Finalizes the redemption tx max fee amount update process. - -Can be called only by the contract owner, after the governance -delay elapses. - -### beginRedemptionTxMaxTotalFeeUpdate - -```solidity -function beginRedemptionTxMaxTotalFeeUpdate(uint64 _newRedemptionTxMaxTotalFee) external -``` - -Begins the redemption tx max total fee amount update process. - -Can be called only by the contract owner. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| _newRedemptionTxMaxTotalFee | uint64 | New redemption tx max total fee. | - -### finalizeRedemptionTxMaxTotalFeeUpdate - -```solidity -function finalizeRedemptionTxMaxTotalFeeUpdate() external -``` - -Finalizes the redemption tx max total fee amount update process. - -Can be called only by the contract owner, after the governance -delay elapses. - -### beginRedemptionTimeoutUpdate - -```solidity -function beginRedemptionTimeoutUpdate(uint32 _newRedemptionTimeout) external -``` - -Begins the redemption timeout amount update process. - -Can be called only by the contract owner. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| _newRedemptionTimeout | uint32 | New redemption timeout. | - -### finalizeRedemptionTimeoutUpdate - -```solidity -function finalizeRedemptionTimeoutUpdate() external -``` - -Finalizes the redemption timeout amount update process. - -Can be called only by the contract owner, after the governance -delay elapses. - -### beginRedemptionTimeoutSlashingAmountUpdate - -```solidity -function beginRedemptionTimeoutSlashingAmountUpdate(uint96 _newRedemptionTimeoutSlashingAmount) external -``` - -Begins the redemption timeout slashing amount update process. - -Can be called only by the contract owner. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| _newRedemptionTimeoutSlashingAmount | uint96 | New redemption timeout slashing amount. | - -### finalizeRedemptionTimeoutSlashingAmountUpdate - -```solidity -function finalizeRedemptionTimeoutSlashingAmountUpdate() external -``` - -Finalizes the redemption timeout slashing amount update process. - -Can be called only by the contract owner, after the governance -delay elapses. - -### beginRedemptionTimeoutNotifierRewardMultiplierUpdate - -```solidity -function beginRedemptionTimeoutNotifierRewardMultiplierUpdate(uint32 _newRedemptionTimeoutNotifierRewardMultiplier) external -``` - -Begins the redemption timeout notifier reward multiplier amount -update process. - -Can be called only by the contract owner. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| _newRedemptionTimeoutNotifierRewardMultiplier | uint32 | New redemption timeout notifier reward multiplier. | - -### finalizeRedemptionTimeoutNotifierRewardMultiplierUpdate - -```solidity -function finalizeRedemptionTimeoutNotifierRewardMultiplierUpdate() external -``` - -Finalizes the redemption timeout notifier reward multiplier amount -update process. - -Can be called only by the contract owner, after the governance -delay elapses. - -### beginMovingFundsTxMaxTotalFeeUpdate - -```solidity -function beginMovingFundsTxMaxTotalFeeUpdate(uint64 _newMovingFundsTxMaxTotalFee) external -``` - -Begins the moving funds tx max total fee update process. - -Can be called only by the contract owner. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| _newMovingFundsTxMaxTotalFee | uint64 | New moving funds tx max total fee. | - -### finalizeMovingFundsTxMaxTotalFeeUpdate - -```solidity -function finalizeMovingFundsTxMaxTotalFeeUpdate() external -``` - -Finalizes the moving funds tx max total fee update process. - -Can be called only by the contract owner, after the governance -delay elapses. - -### beginMovingFundsDustThresholdUpdate - -```solidity -function beginMovingFundsDustThresholdUpdate(uint64 _newMovingFundsDustThreshold) external -``` - -Begins the moving funds dust threshold update process. - -Can be called only by the contract owner. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| _newMovingFundsDustThreshold | uint64 | New moving funds dust threshold. | - -### finalizeMovingFundsDustThresholdUpdate - -```solidity -function finalizeMovingFundsDustThresholdUpdate() external -``` - -Finalizes the moving funds dust threshold update process. - -Can be called only by the contract owner, after the governance -delay elapses. - -### beginMovingFundsTimeoutResetDelayUpdate - -```solidity -function beginMovingFundsTimeoutResetDelayUpdate(uint32 _newMovingFundsTimeoutResetDelay) external -``` - -Begins the moving funds timeout reset delay update process. - -Can be called only by the contract owner. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| _newMovingFundsTimeoutResetDelay | uint32 | New moving funds timeout reset delay. | - -### finalizeMovingFundsTimeoutResetDelayUpdate - -```solidity -function finalizeMovingFundsTimeoutResetDelayUpdate() external -``` - -Finalizes the moving funds timeout reset delay update process. - -Can be called only by the contract owner, after the governance -delay elapses. - -### beginMovingFundsTimeoutUpdate - -```solidity -function beginMovingFundsTimeoutUpdate(uint32 _newMovingFundsTimeout) external -``` - -Begins the moving funds timeout update process. - -Can be called only by the contract owner. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| _newMovingFundsTimeout | uint32 | New moving funds timeout. | - -### finalizeMovingFundsTimeoutUpdate - -```solidity -function finalizeMovingFundsTimeoutUpdate() external -``` - -Finalizes the moving funds timeout update process. - -Can be called only by the contract owner, after the governance -delay elapses. - -### beginMovingFundsTimeoutSlashingAmountUpdate - -```solidity -function beginMovingFundsTimeoutSlashingAmountUpdate(uint96 _newMovingFundsTimeoutSlashingAmount) external -``` - -Begins the moving funds timeout slashing amount update process. - -Can be called only by the contract owner. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| _newMovingFundsTimeoutSlashingAmount | uint96 | New moving funds timeout slashing amount. | - -### finalizeMovingFundsTimeoutSlashingAmountUpdate - -```solidity -function finalizeMovingFundsTimeoutSlashingAmountUpdate() external -``` - -Finalizes the moving funds timeout slashing amount update process. - -Can be called only by the contract owner, after the governance -delay elapses. - -### beginMovingFundsTimeoutNotifierRewardMultiplierUpdate - -```solidity -function beginMovingFundsTimeoutNotifierRewardMultiplierUpdate(uint32 _newMovingFundsTimeoutNotifierRewardMultiplier) external -``` - -Begins the moving funds timeout notifier reward multiplier update -process. - -Can be called only by the contract owner. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| _newMovingFundsTimeoutNotifierRewardMultiplier | uint32 | New moving funds timeout notifier reward multiplier. | - -### finalizeMovingFundsTimeoutNotifierRewardMultiplierUpdate - -```solidity -function finalizeMovingFundsTimeoutNotifierRewardMultiplierUpdate() external -``` - -Finalizes the moving funds timeout notifier reward multiplier -update process. - -Can be called only by the contract owner, after the governance -delay elapses. - -### beginMovingFundsCommitmentGasOffsetUpdate - -```solidity -function beginMovingFundsCommitmentGasOffsetUpdate(uint16 _newMovingFundsCommitmentGasOffset) external -``` - -Begins the moving funds commitment gas offset update process. - -Can be called only by the contract owner. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| _newMovingFundsCommitmentGasOffset | uint16 | New moving funds commitment gas offset. | - -### finalizeMovingFundsCommitmentGasOffsetUpdate - -```solidity -function finalizeMovingFundsCommitmentGasOffsetUpdate() external -``` - -Finalizes the moving funds commitment gas offset update process. - -Can be called only by the contract owner, after the governance -delay elapses. - -### beginMovedFundsSweepTxMaxTotalFeeUpdate - -```solidity -function beginMovedFundsSweepTxMaxTotalFeeUpdate(uint64 _newMovedFundsSweepTxMaxTotalFee) external -``` - -Begins the moved funds sweep tx max total fee update process. - -Can be called only by the contract owner. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| _newMovedFundsSweepTxMaxTotalFee | uint64 | New moved funds sweep tx max total fee. | - -### finalizeMovedFundsSweepTxMaxTotalFeeUpdate - -```solidity -function finalizeMovedFundsSweepTxMaxTotalFeeUpdate() external -``` - -Finalizes the moved funds sweep tx max total fee update process. - -Can be called only by the contract owner, after the governance -delay elapses. - -### beginMovedFundsSweepTimeoutUpdate - -```solidity -function beginMovedFundsSweepTimeoutUpdate(uint32 _newMovedFundsSweepTimeout) external -``` - -Begins the moved funds sweep timeout update process. - -Can be called only by the contract owner. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| _newMovedFundsSweepTimeout | uint32 | New moved funds sweep timeout. | - -### finalizeMovedFundsSweepTimeoutUpdate - -```solidity -function finalizeMovedFundsSweepTimeoutUpdate() external -``` - -Finalizes the moved funds sweep timeout update process. - -Can be called only by the contract owner, after the governance -delay elapses. - -### beginMovedFundsSweepTimeoutSlashingAmountUpdate - -```solidity -function beginMovedFundsSweepTimeoutSlashingAmountUpdate(uint96 _newMovedFundsSweepTimeoutSlashingAmount) external -``` - -Begins the moved funds sweep timeout slashing amount update process. - -Can be called only by the contract owner. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| _newMovedFundsSweepTimeoutSlashingAmount | uint96 | New moved funds sweep timeout slashing amount. | - -### finalizeMovedFundsSweepTimeoutSlashingAmountUpdate - -```solidity -function finalizeMovedFundsSweepTimeoutSlashingAmountUpdate() external -``` - -Finalizes the moved funds sweep timeout slashing amount update -process. - -Can be called only by the contract owner, after the governance -delay elapses. - -### beginMovedFundsSweepTimeoutNotifierRewardMultiplierUpdate - -```solidity -function beginMovedFundsSweepTimeoutNotifierRewardMultiplierUpdate(uint32 _newMovedFundsSweepTimeoutNotifierRewardMultiplier) external -``` - -Begins the moved funds sweep timeout notifier reward multiplier -update process. - -Can be called only by the contract owner. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| _newMovedFundsSweepTimeoutNotifierRewardMultiplier | uint32 | New moved funds sweep timeout notifier reward multiplier. | - -### finalizeMovedFundsSweepTimeoutNotifierRewardMultiplierUpdate - -```solidity -function finalizeMovedFundsSweepTimeoutNotifierRewardMultiplierUpdate() external -``` - -Finalizes the moved funds sweep timeout notifier reward multiplier -update process. - -Can be called only by the contract owner, after the governance -delay elapses. - -### beginWalletCreationPeriodUpdate - -```solidity -function beginWalletCreationPeriodUpdate(uint32 _newWalletCreationPeriod) external -``` - -Begins the wallet creation period update process. - -Can be called only by the contract owner. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| _newWalletCreationPeriod | uint32 | New wallet creation period. | - -### finalizeWalletCreationPeriodUpdate - -```solidity -function finalizeWalletCreationPeriodUpdate() external -``` - -Finalizes the wallet creation period update process. - -Can be called only by the contract owner, after the governance -delay elapses. - -### beginWalletCreationMinBtcBalanceUpdate - -```solidity -function beginWalletCreationMinBtcBalanceUpdate(uint64 _newWalletCreationMinBtcBalance) external -``` - -Begins the wallet creation min btc balance update process. - -Can be called only by the contract owner. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| _newWalletCreationMinBtcBalance | uint64 | New wallet creation min btc balance. | - -### finalizeWalletCreationMinBtcBalanceUpdate - -```solidity -function finalizeWalletCreationMinBtcBalanceUpdate() external -``` - -Finalizes the wallet creation min btc balance update process. - -Can be called only by the contract owner, after the governance -delay elapses. - -### beginWalletCreationMaxBtcBalanceUpdate - -```solidity -function beginWalletCreationMaxBtcBalanceUpdate(uint64 _newWalletCreationMaxBtcBalance) external -``` - -Begins the wallet creation max btc balance update process. - -Can be called only by the contract owner. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| _newWalletCreationMaxBtcBalance | uint64 | New wallet creation max btc balance. | - -### finalizeWalletCreationMaxBtcBalanceUpdate - -```solidity -function finalizeWalletCreationMaxBtcBalanceUpdate() external -``` - -Finalizes the wallet creation max btc balance update process. - -Can be called only by the contract owner, after the governance -delay elapses. - -### beginWalletClosureMinBtcBalanceUpdate - -```solidity -function beginWalletClosureMinBtcBalanceUpdate(uint64 _newWalletClosureMinBtcBalance) external -``` - -Begins the wallet closure min btc balance update process. - -Can be called only by the contract owner. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| _newWalletClosureMinBtcBalance | uint64 | New wallet closure min btc balance. | - -### finalizeWalletClosureMinBtcBalanceUpdate - -```solidity -function finalizeWalletClosureMinBtcBalanceUpdate() external -``` - -Finalizes the wallet closure min btc balance update process. - -Can be called only by the contract owner, after the governance -delay elapses. - -### beginWalletMaxAgeUpdate - -```solidity -function beginWalletMaxAgeUpdate(uint32 _newWalletMaxAge) external -``` - -Begins the wallet max age update process. - -Can be called only by the contract owner. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| _newWalletMaxAge | uint32 | New wallet max age. | - -### finalizeWalletMaxAgeUpdate - -```solidity -function finalizeWalletMaxAgeUpdate() external -``` - -Finalizes the wallet max age update process. - -Can be called only by the contract owner, after the governance -delay elapses. - -### beginWalletMaxBtcTransferUpdate - -```solidity -function beginWalletMaxBtcTransferUpdate(uint64 _newWalletMaxBtcTransfer) external -``` - -Begins the wallet max btc transfer amount update process. - -Can be called only by the contract owner. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| _newWalletMaxBtcTransfer | uint64 | New wallet max btc transfer. | - -### finalizeWalletMaxBtcTransferUpdate - -```solidity -function finalizeWalletMaxBtcTransferUpdate() external -``` - -Finalizes the wallet max btc transfer amount update process. - -Can be called only by the contract owner, after the governance -delay elapses. - -### beginWalletClosingPeriodUpdate - -```solidity -function beginWalletClosingPeriodUpdate(uint32 _newWalletClosingPeriod) external -``` - -Begins the wallet closing period update process. - -Can be called only by the contract owner. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| _newWalletClosingPeriod | uint32 | New wallet closing period. | - -### finalizeWalletClosingPeriodUpdate - -```solidity -function finalizeWalletClosingPeriodUpdate() external -``` - -Finalizes the wallet closing period update process. - -Can be called only by the contract owner, after the governance -delay elapses. - -### beginFraudChallengeDepositAmountUpdate - -```solidity -function beginFraudChallengeDepositAmountUpdate(uint96 _newFraudChallengeDepositAmount) external -``` - -Begins the fraud challenge deposit amount update process. - -Can be called only by the contract owner. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| _newFraudChallengeDepositAmount | uint96 | New fraud challenge deposit amount. | - -### finalizeFraudChallengeDepositAmountUpdate - -```solidity -function finalizeFraudChallengeDepositAmountUpdate() external -``` - -Finalizes the fraud challenge deposit amount update process. - -Can be called only by the contract owner, after the governance -delay elapses. - -### beginFraudChallengeDefeatTimeoutUpdate - -```solidity -function beginFraudChallengeDefeatTimeoutUpdate(uint32 _newFraudChallengeDefeatTimeout) external -``` - -Begins the fraud challenge defeat timeout update process. - -Can be called only by the contract owner. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| _newFraudChallengeDefeatTimeout | uint32 | New fraud challenge defeat timeout. | - -### finalizeFraudChallengeDefeatTimeoutUpdate - -```solidity -function finalizeFraudChallengeDefeatTimeoutUpdate() external -``` - -Finalizes the fraud challenge defeat timeout update process. - -Can be called only by the contract owner, after the governance -delay elapses. - -### beginFraudSlashingAmountUpdate - -```solidity -function beginFraudSlashingAmountUpdate(uint96 _newFraudSlashingAmount) external -``` - -Begins the fraud slashing amount update process. - -Can be called only by the contract owner. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| _newFraudSlashingAmount | uint96 | New fraud slashing amount. | - -### finalizeFraudSlashingAmountUpdate - -```solidity -function finalizeFraudSlashingAmountUpdate() external -``` - -Finalizes the fraud slashing amount update process. - -Can be called only by the contract owner, after the governance -delay elapses. - -### beginFraudNotifierRewardMultiplierUpdate - -```solidity -function beginFraudNotifierRewardMultiplierUpdate(uint32 _newFraudNotifierRewardMultiplier) external -``` - -Begins the fraud notifier reward multiplier update process. - -Can be called only by the contract owner. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| _newFraudNotifierRewardMultiplier | uint32 | New fraud notifier reward multiplier. | - -### finalizeFraudNotifierRewardMultiplierUpdate - -```solidity -function finalizeFraudNotifierRewardMultiplierUpdate() external -``` - -Finalizes the fraud notifier reward multiplier update process. - -Can be called only by the contract owner, after the governance -delay elapses. - -### beginTreasuryUpdate - -```solidity -function beginTreasuryUpdate(address _newTreasury) external -``` - -Begins the treasury address update process. - -Can be called only by the contract owner. It does not perform -any parameter validation. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| _newTreasury | address | New treasury address. | - -### finalizeTreasuryUpdate - -```solidity -function finalizeTreasuryUpdate() external -``` - -Finalizes the treasury address update process. - -Can be called only by the contract owner, after the governance -delay elapses. - -### governanceDelay - -```solidity -function governanceDelay() internal view returns (uint256) -``` - -Gets the governance delay parameter. - -## BridgeGovernanceParameters - -### TreasuryData - -```solidity -struct TreasuryData { - address newTreasury; - uint256 treasuryChangeInitiated; -} -``` - -### DepositData - -```solidity -struct DepositData { - uint64 newDepositDustThreshold; - uint256 depositDustThresholdChangeInitiated; - uint64 newDepositTreasuryFeeDivisor; - uint256 depositTreasuryFeeDivisorChangeInitiated; - uint64 newDepositTxMaxFee; - uint256 depositTxMaxFeeChangeInitiated; - uint32 newDepositRevealAheadPeriod; - uint256 depositRevealAheadPeriodChangeInitiated; -} -``` - -### RedemptionData - -```solidity -struct RedemptionData { - uint64 newRedemptionDustThreshold; - uint256 redemptionDustThresholdChangeInitiated; - uint64 newRedemptionTreasuryFeeDivisor; - uint256 redemptionTreasuryFeeDivisorChangeInitiated; - uint64 newRedemptionTxMaxFee; - uint256 redemptionTxMaxFeeChangeInitiated; - uint64 newRedemptionTxMaxTotalFee; - uint256 redemptionTxMaxTotalFeeChangeInitiated; - uint32 newRedemptionTimeout; - uint256 redemptionTimeoutChangeInitiated; - uint96 newRedemptionTimeoutSlashingAmount; - uint256 redemptionTimeoutSlashingAmountChangeInitiated; - uint32 newRedemptionTimeoutNotifierRewardMultiplier; - uint256 redemptionTimeoutNotifierRewardMultiplierChangeInitiated; -} -``` - -### MovingFundsData - -```solidity -struct MovingFundsData { - uint64 newMovingFundsTxMaxTotalFee; - uint256 movingFundsTxMaxTotalFeeChangeInitiated; - uint64 newMovingFundsDustThreshold; - uint256 movingFundsDustThresholdChangeInitiated; - uint32 newMovingFundsTimeoutResetDelay; - uint256 movingFundsTimeoutResetDelayChangeInitiated; - uint32 newMovingFundsTimeout; - uint256 movingFundsTimeoutChangeInitiated; - uint96 newMovingFundsTimeoutSlashingAmount; - uint256 movingFundsTimeoutSlashingAmountChangeInitiated; - uint32 newMovingFundsTimeoutNotifierRewardMultiplier; - uint256 movingFundsTimeoutNotifierRewardMultiplierChangeInitiated; - uint16 newMovingFundsCommitmentGasOffset; - uint256 movingFundsCommitmentGasOffsetChangeInitiated; - uint64 newMovedFundsSweepTxMaxTotalFee; - uint256 movedFundsSweepTxMaxTotalFeeChangeInitiated; - uint32 newMovedFundsSweepTimeout; - uint256 movedFundsSweepTimeoutChangeInitiated; - uint96 newMovedFundsSweepTimeoutSlashingAmount; - uint256 movedFundsSweepTimeoutSlashingAmountChangeInitiated; - uint32 newMovedFundsSweepTimeoutNotifierRewardMultiplier; - uint256 movedFundsSweepTimeoutNotifierRewardMultiplierChangeInitiated; -} -``` - -### WalletData - -```solidity -struct WalletData { - uint32 newWalletCreationPeriod; - uint256 walletCreationPeriodChangeInitiated; - uint64 newWalletCreationMinBtcBalance; - uint256 walletCreationMinBtcBalanceChangeInitiated; - uint64 newWalletCreationMaxBtcBalance; - uint256 walletCreationMaxBtcBalanceChangeInitiated; - uint64 newWalletClosureMinBtcBalance; - uint256 walletClosureMinBtcBalanceChangeInitiated; - uint32 newWalletMaxAge; - uint256 walletMaxAgeChangeInitiated; - uint64 newWalletMaxBtcTransfer; - uint256 walletMaxBtcTransferChangeInitiated; - uint32 newWalletClosingPeriod; - uint256 walletClosingPeriodChangeInitiated; -} -``` - -### FraudData - -```solidity -struct FraudData { - uint96 newFraudChallengeDepositAmount; - uint256 fraudChallengeDepositAmountChangeInitiated; - uint32 newFraudChallengeDefeatTimeout; - uint256 fraudChallengeDefeatTimeoutChangeInitiated; - uint96 newFraudSlashingAmount; - uint256 fraudSlashingAmountChangeInitiated; - uint32 newFraudNotifierRewardMultiplier; - uint256 fraudNotifierRewardMultiplierChangeInitiated; -} -``` - -### DepositDustThresholdUpdateStarted - -```solidity -event DepositDustThresholdUpdateStarted(uint64 newDepositDustThreshold, uint256 timestamp) -``` - -### DepositDustThresholdUpdated - -```solidity -event DepositDustThresholdUpdated(uint64 depositDustThreshold) -``` - -### DepositTreasuryFeeDivisorUpdateStarted - -```solidity -event DepositTreasuryFeeDivisorUpdateStarted(uint64 depositTreasuryFeeDivisor, uint256 timestamp) -``` - -### DepositTreasuryFeeDivisorUpdated - -```solidity -event DepositTreasuryFeeDivisorUpdated(uint64 depositTreasuryFeeDivisor) -``` - -### DepositTxMaxFeeUpdateStarted - -```solidity -event DepositTxMaxFeeUpdateStarted(uint64 newDepositTxMaxFee, uint256 timestamp) -``` - -### DepositTxMaxFeeUpdated - -```solidity -event DepositTxMaxFeeUpdated(uint64 depositTxMaxFee) -``` - -### DepositRevealAheadPeriodUpdateStarted - -```solidity -event DepositRevealAheadPeriodUpdateStarted(uint32 newDepositRevealAheadPeriod, uint256 timestamp) -``` - -### DepositRevealAheadPeriodUpdated - -```solidity -event DepositRevealAheadPeriodUpdated(uint32 depositRevealAheadPeriod) -``` - -### RedemptionDustThresholdUpdateStarted - -```solidity -event RedemptionDustThresholdUpdateStarted(uint64 newRedemptionDustThreshold, uint256 timestamp) -``` - -### RedemptionDustThresholdUpdated - -```solidity -event RedemptionDustThresholdUpdated(uint64 redemptionDustThreshold) -``` - -### RedemptionTreasuryFeeDivisorUpdateStarted - -```solidity -event RedemptionTreasuryFeeDivisorUpdateStarted(uint64 newRedemptionTreasuryFeeDivisor, uint256 timestamp) -``` - -### RedemptionTreasuryFeeDivisorUpdated - -```solidity -event RedemptionTreasuryFeeDivisorUpdated(uint64 redemptionTreasuryFeeDivisor) -``` - -### RedemptionTxMaxFeeUpdateStarted - -```solidity -event RedemptionTxMaxFeeUpdateStarted(uint64 newRedemptionTxMaxFee, uint256 timestamp) -``` - -### RedemptionTxMaxFeeUpdated - -```solidity -event RedemptionTxMaxFeeUpdated(uint64 redemptionTxMaxFee) -``` - -### RedemptionTxMaxTotalFeeUpdateStarted - -```solidity -event RedemptionTxMaxTotalFeeUpdateStarted(uint64 newRedemptionTxMaxTotalFee, uint256 timestamp) -``` - -### RedemptionTxMaxTotalFeeUpdated - -```solidity -event RedemptionTxMaxTotalFeeUpdated(uint64 redemptionTxMaxTotalFee) -``` - -### RedemptionTimeoutUpdateStarted - -```solidity -event RedemptionTimeoutUpdateStarted(uint32 newRedemptionTimeout, uint256 timestamp) -``` - -### RedemptionTimeoutUpdated - -```solidity -event RedemptionTimeoutUpdated(uint32 redemptionTimeout) -``` - -### RedemptionTimeoutSlashingAmountUpdateStarted - -```solidity -event RedemptionTimeoutSlashingAmountUpdateStarted(uint96 newRedemptionTimeoutSlashingAmount, uint256 timestamp) -``` - -### RedemptionTimeoutSlashingAmountUpdated - -```solidity -event RedemptionTimeoutSlashingAmountUpdated(uint96 redemptionTimeoutSlashingAmount) -``` - -### RedemptionTimeoutNotifierRewardMultiplierUpdateStarted - -```solidity -event RedemptionTimeoutNotifierRewardMultiplierUpdateStarted(uint32 newRedemptionTimeoutNotifierRewardMultiplier, uint256 timestamp) -``` - -### RedemptionTimeoutNotifierRewardMultiplierUpdated - -```solidity -event RedemptionTimeoutNotifierRewardMultiplierUpdated(uint32 redemptionTimeoutNotifierRewardMultiplier) -``` - -### MovingFundsTxMaxTotalFeeUpdateStarted - -```solidity -event MovingFundsTxMaxTotalFeeUpdateStarted(uint64 newMovingFundsTxMaxTotalFee, uint256 timestamp) -``` - -### MovingFundsTxMaxTotalFeeUpdated - -```solidity -event MovingFundsTxMaxTotalFeeUpdated(uint64 movingFundsTxMaxTotalFee) -``` - -### MovingFundsDustThresholdUpdateStarted - -```solidity -event MovingFundsDustThresholdUpdateStarted(uint64 newMovingFundsDustThreshold, uint256 timestamp) -``` - -### MovingFundsDustThresholdUpdated - -```solidity -event MovingFundsDustThresholdUpdated(uint64 movingFundsDustThreshold) -``` - -### MovingFundsTimeoutResetDelayUpdateStarted - -```solidity -event MovingFundsTimeoutResetDelayUpdateStarted(uint32 newMovingFundsTimeoutResetDelay, uint256 timestamp) -``` - -### MovingFundsTimeoutResetDelayUpdated - -```solidity -event MovingFundsTimeoutResetDelayUpdated(uint32 movingFundsTimeoutResetDelay) -``` - -### MovingFundsTimeoutUpdateStarted - -```solidity -event MovingFundsTimeoutUpdateStarted(uint32 newMovingFundsTimeout, uint256 timestamp) -``` - -### MovingFundsTimeoutUpdated - -```solidity -event MovingFundsTimeoutUpdated(uint32 movingFundsTimeout) -``` - -### MovingFundsTimeoutSlashingAmountUpdateStarted - -```solidity -event MovingFundsTimeoutSlashingAmountUpdateStarted(uint96 newMovingFundsTimeoutSlashingAmount, uint256 timestamp) -``` - -### MovingFundsTimeoutSlashingAmountUpdated - -```solidity -event MovingFundsTimeoutSlashingAmountUpdated(uint96 movingFundsTimeoutSlashingAmount) -``` - -### MovingFundsTimeoutNotifierRewardMultiplierUpdateStarted - -```solidity -event MovingFundsTimeoutNotifierRewardMultiplierUpdateStarted(uint32 newMovingFundsTimeoutNotifierRewardMultiplier, uint256 timestamp) -``` - -### MovingFundsTimeoutNotifierRewardMultiplierUpdated - -```solidity -event MovingFundsTimeoutNotifierRewardMultiplierUpdated(uint32 movingFundsTimeoutNotifierRewardMultiplier) -``` - -### MovingFundsCommitmentGasOffsetUpdateStarted - -```solidity -event MovingFundsCommitmentGasOffsetUpdateStarted(uint16 newMovingFundsCommitmentGasOffset, uint256 timestamp) -``` - -### MovingFundsCommitmentGasOffsetUpdated - -```solidity -event MovingFundsCommitmentGasOffsetUpdated(uint16 movingFundsCommitmentGasOffset) -``` - -### MovedFundsSweepTxMaxTotalFeeUpdateStarted - -```solidity -event MovedFundsSweepTxMaxTotalFeeUpdateStarted(uint64 newMovedFundsSweepTxMaxTotalFee, uint256 timestamp) -``` - -### MovedFundsSweepTxMaxTotalFeeUpdated - -```solidity -event MovedFundsSweepTxMaxTotalFeeUpdated(uint64 movedFundsSweepTxMaxTotalFee) -``` - -### MovedFundsSweepTimeoutUpdateStarted - -```solidity -event MovedFundsSweepTimeoutUpdateStarted(uint32 newMovedFundsSweepTimeout, uint256 timestamp) -``` - -### MovedFundsSweepTimeoutUpdated - -```solidity -event MovedFundsSweepTimeoutUpdated(uint32 movedFundsSweepTimeout) -``` - -### MovedFundsSweepTimeoutSlashingAmountUpdateStarted - -```solidity -event MovedFundsSweepTimeoutSlashingAmountUpdateStarted(uint96 newMovedFundsSweepTimeoutSlashingAmount, uint256 timestamp) -``` - -### MovedFundsSweepTimeoutSlashingAmountUpdated - -```solidity -event MovedFundsSweepTimeoutSlashingAmountUpdated(uint96 movedFundsSweepTimeoutSlashingAmount) -``` - -### MovedFundsSweepTimeoutNotifierRewardMultiplierUpdateStarted - -```solidity -event MovedFundsSweepTimeoutNotifierRewardMultiplierUpdateStarted(uint32 newMovedFundsSweepTimeoutNotifierRewardMultiplier, uint256 timestamp) -``` - -### MovedFundsSweepTimeoutNotifierRewardMultiplierUpdated - -```solidity -event MovedFundsSweepTimeoutNotifierRewardMultiplierUpdated(uint32 movedFundsSweepTimeoutNotifierRewardMultiplier) -``` - -### WalletCreationPeriodUpdateStarted - -```solidity -event WalletCreationPeriodUpdateStarted(uint32 newWalletCreationPeriod, uint256 timestamp) -``` - -### WalletCreationPeriodUpdated - -```solidity -event WalletCreationPeriodUpdated(uint32 walletCreationPeriod) -``` - -### WalletCreationMinBtcBalanceUpdateStarted - -```solidity -event WalletCreationMinBtcBalanceUpdateStarted(uint64 newWalletCreationMinBtcBalance, uint256 timestamp) -``` - -### WalletCreationMinBtcBalanceUpdated - -```solidity -event WalletCreationMinBtcBalanceUpdated(uint64 walletCreationMinBtcBalance) -``` - -### WalletCreationMaxBtcBalanceUpdateStarted - -```solidity -event WalletCreationMaxBtcBalanceUpdateStarted(uint64 newWalletCreationMaxBtcBalance, uint256 timestamp) -``` - -### WalletCreationMaxBtcBalanceUpdated - -```solidity -event WalletCreationMaxBtcBalanceUpdated(uint64 walletCreationMaxBtcBalance) -``` - -### WalletClosureMinBtcBalanceUpdateStarted - -```solidity -event WalletClosureMinBtcBalanceUpdateStarted(uint64 newWalletClosureMinBtcBalance, uint256 timestamp) -``` - -### WalletClosureMinBtcBalanceUpdated - -```solidity -event WalletClosureMinBtcBalanceUpdated(uint64 walletClosureMinBtcBalance) -``` - -### WalletMaxAgeUpdateStarted - -```solidity -event WalletMaxAgeUpdateStarted(uint32 newWalletMaxAge, uint256 timestamp) -``` - -### WalletMaxAgeUpdated - -```solidity -event WalletMaxAgeUpdated(uint32 walletMaxAge) -``` - -### WalletMaxBtcTransferUpdateStarted - -```solidity -event WalletMaxBtcTransferUpdateStarted(uint64 newWalletMaxBtcTransfer, uint256 timestamp) -``` - -### WalletMaxBtcTransferUpdated - -```solidity -event WalletMaxBtcTransferUpdated(uint64 walletMaxBtcTransfer) -``` - -### WalletClosingPeriodUpdateStarted - -```solidity -event WalletClosingPeriodUpdateStarted(uint32 newWalletClosingPeriod, uint256 timestamp) -``` - -### WalletClosingPeriodUpdated - -```solidity -event WalletClosingPeriodUpdated(uint32 walletClosingPeriod) -``` - -### FraudChallengeDepositAmountUpdateStarted - -```solidity -event FraudChallengeDepositAmountUpdateStarted(uint96 newFraudChallengeDepositAmount, uint256 timestamp) -``` - -### FraudChallengeDepositAmountUpdated - -```solidity -event FraudChallengeDepositAmountUpdated(uint96 fraudChallengeDepositAmount) -``` - -### FraudChallengeDefeatTimeoutUpdateStarted - -```solidity -event FraudChallengeDefeatTimeoutUpdateStarted(uint32 newFraudChallengeDefeatTimeout, uint256 timestamp) -``` - -### FraudChallengeDefeatTimeoutUpdated - -```solidity -event FraudChallengeDefeatTimeoutUpdated(uint32 fraudChallengeDefeatTimeout) -``` - -### FraudSlashingAmountUpdateStarted - -```solidity -event FraudSlashingAmountUpdateStarted(uint96 newFraudSlashingAmount, uint256 timestamp) -``` - -### FraudSlashingAmountUpdated - -```solidity -event FraudSlashingAmountUpdated(uint96 fraudSlashingAmount) -``` - -### FraudNotifierRewardMultiplierUpdateStarted - -```solidity -event FraudNotifierRewardMultiplierUpdateStarted(uint32 newFraudNotifierRewardMultiplier, uint256 timestamp) -``` - -### FraudNotifierRewardMultiplierUpdated - -```solidity -event FraudNotifierRewardMultiplierUpdated(uint32 fraudNotifierRewardMultiplier) -``` - -### TreasuryUpdateStarted - -```solidity -event TreasuryUpdateStarted(address newTreasury, uint256 timestamp) -``` - -### TreasuryUpdated - -```solidity -event TreasuryUpdated(address treasury) -``` - -### onlyAfterGovernanceDelay - -```solidity -modifier onlyAfterGovernanceDelay(uint256 changeInitiatedTimestamp, uint256 governanceDelay) -``` - -Reverts if called before the governance delay elapses. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| changeInitiatedTimestamp | uint256 | Timestamp indicating the beginning of the change. | -| governanceDelay | uint256 | | - -### beginDepositDustThresholdUpdate - -```solidity -function beginDepositDustThresholdUpdate(struct BridgeGovernanceParameters.DepositData self, uint64 _newDepositDustThreshold) external -``` - -Begins the deposit dust threshold amount update process. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| self | struct BridgeGovernanceParameters.DepositData | | -| _newDepositDustThreshold | uint64 | New deposit dust threshold amount. | - -### finalizeDepositDustThresholdUpdate - -```solidity -function finalizeDepositDustThresholdUpdate(struct BridgeGovernanceParameters.DepositData self, uint256 governanceDelay) external -``` - -Finalizes the deposit dust threshold amount update process. - -Can be called after the governance delay elapses. - -### beginDepositTreasuryFeeDivisorUpdate - -```solidity -function beginDepositTreasuryFeeDivisorUpdate(struct BridgeGovernanceParameters.DepositData self, uint64 _newDepositTreasuryFeeDivisor) external -``` - -Begins the deposit treasury fee divisor amount update process. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| self | struct BridgeGovernanceParameters.DepositData | | -| _newDepositTreasuryFeeDivisor | uint64 | New deposit treasury fee divisor amount. | - -### finalizeDepositTreasuryFeeDivisorUpdate - -```solidity -function finalizeDepositTreasuryFeeDivisorUpdate(struct BridgeGovernanceParameters.DepositData self, uint256 governanceDelay) external -``` - -Finalizes the deposit treasury fee divisor amount update process. - -Can be called after the governance delay elapses. - -### beginDepositTxMaxFeeUpdate - -```solidity -function beginDepositTxMaxFeeUpdate(struct BridgeGovernanceParameters.DepositData self, uint64 _newDepositTxMaxFee) external -``` - -Begins the deposit tx max fee amount update process. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| self | struct BridgeGovernanceParameters.DepositData | | -| _newDepositTxMaxFee | uint64 | New deposit tx max fee amount. | - -### finalizeDepositTxMaxFeeUpdate - -```solidity -function finalizeDepositTxMaxFeeUpdate(struct BridgeGovernanceParameters.DepositData self, uint256 governanceDelay) external -``` - -Finalizes the deposit tx max fee amount update process. - -Can be called after the governance delay elapses. - -### beginDepositRevealAheadPeriodUpdate - -```solidity -function beginDepositRevealAheadPeriodUpdate(struct BridgeGovernanceParameters.DepositData self, uint32 _newDepositRevealAheadPeriod) external -``` - -Begins the deposit reveal ahead period update process. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| self | struct BridgeGovernanceParameters.DepositData | | -| _newDepositRevealAheadPeriod | uint32 | New deposit reveal ahead period. | - -### finalizeDepositRevealAheadPeriodUpdate - -```solidity -function finalizeDepositRevealAheadPeriodUpdate(struct BridgeGovernanceParameters.DepositData self, uint256 governanceDelay) external -``` - -Finalizes the deposit reveal ahead period update process. - -Can be called after the governance delay elapses. - -### beginRedemptionDustThresholdUpdate - -```solidity -function beginRedemptionDustThresholdUpdate(struct BridgeGovernanceParameters.RedemptionData self, uint64 _newRedemptionDustThreshold) external -``` - -Begins the redemption dust threshold amount update process. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| self | struct BridgeGovernanceParameters.RedemptionData | | -| _newRedemptionDustThreshold | uint64 | New redemption dust threshold amount. | - -### finalizeRedemptionDustThresholdUpdate - -```solidity -function finalizeRedemptionDustThresholdUpdate(struct BridgeGovernanceParameters.RedemptionData self, uint256 governanceDelay) external -``` - -Finalizes the redemption dust threshold amount update process. - -Can be called after the governance delay elapses. - -### beginRedemptionTreasuryFeeDivisorUpdate - -```solidity -function beginRedemptionTreasuryFeeDivisorUpdate(struct BridgeGovernanceParameters.RedemptionData self, uint64 _newRedemptionTreasuryFeeDivisor) external -``` - -Begins the redemption treasury fee divisor amount update process. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| self | struct BridgeGovernanceParameters.RedemptionData | | -| _newRedemptionTreasuryFeeDivisor | uint64 | New redemption treasury fee divisor amount. | - -### finalizeRedemptionTreasuryFeeDivisorUpdate - -```solidity -function finalizeRedemptionTreasuryFeeDivisorUpdate(struct BridgeGovernanceParameters.RedemptionData self, uint256 governanceDelay) external -``` - -Finalizes the redemption treasury fee divisor amount update process. - -Can be called after the governance delay elapses. - -### beginRedemptionTxMaxFeeUpdate - -```solidity -function beginRedemptionTxMaxFeeUpdate(struct BridgeGovernanceParameters.RedemptionData self, uint64 _newRedemptionTxMaxFee) external -``` - -Begins the redemption tx max fee amount update process. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| self | struct BridgeGovernanceParameters.RedemptionData | | -| _newRedemptionTxMaxFee | uint64 | New redemption tx max fee amount. | - -### finalizeRedemptionTxMaxFeeUpdate - -```solidity -function finalizeRedemptionTxMaxFeeUpdate(struct BridgeGovernanceParameters.RedemptionData self, uint256 governanceDelay) external -``` - -Finalizes the redemption tx max fee amount update process. - -Can be called after the governance delay elapses. - -### beginRedemptionTxMaxTotalFeeUpdate - -```solidity -function beginRedemptionTxMaxTotalFeeUpdate(struct BridgeGovernanceParameters.RedemptionData self, uint64 _newRedemptionTxMaxTotalFee) external -``` - -Begins the redemption tx max total fee amount update process. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| self | struct BridgeGovernanceParameters.RedemptionData | | -| _newRedemptionTxMaxTotalFee | uint64 | New redemption tx max total fee amount. | - -### finalizeRedemptionTxMaxTotalFeeUpdate - -```solidity -function finalizeRedemptionTxMaxTotalFeeUpdate(struct BridgeGovernanceParameters.RedemptionData self, uint256 governanceDelay) external -``` - -Finalizes the redemption tx max total fee amount update process. - -Can be called after the governance delay elapses. - -### beginRedemptionTimeoutUpdate - -```solidity -function beginRedemptionTimeoutUpdate(struct BridgeGovernanceParameters.RedemptionData self, uint32 _newRedemptionTimeout) external -``` - -Begins the redemption timeout amount update process. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| self | struct BridgeGovernanceParameters.RedemptionData | | -| _newRedemptionTimeout | uint32 | New redemption timeout amount. | - -### finalizeRedemptionTimeoutUpdate - -```solidity -function finalizeRedemptionTimeoutUpdate(struct BridgeGovernanceParameters.RedemptionData self, uint256 governanceDelay) external -``` - -Finalizes the redemption timeout amount update -process. - -Can be called after the governance delay elapses. - -### beginRedemptionTimeoutSlashingAmountUpdate - -```solidity -function beginRedemptionTimeoutSlashingAmountUpdate(struct BridgeGovernanceParameters.RedemptionData self, uint96 _newRedemptionTimeoutSlashingAmount) external -``` - -Begins the redemption timeout slashing amount update process. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| self | struct BridgeGovernanceParameters.RedemptionData | | -| _newRedemptionTimeoutSlashingAmount | uint96 | New redemption timeout slashing amount. | - -### finalizeRedemptionTimeoutSlashingAmountUpdate - -```solidity -function finalizeRedemptionTimeoutSlashingAmountUpdate(struct BridgeGovernanceParameters.RedemptionData self, uint256 governanceDelay) external -``` - -Finalizes the redemption timeout slashing amount update process. - -Can be called after the governance delay elapses. - -### beginRedemptionTimeoutNotifierRewardMultiplierUpdate - -```solidity -function beginRedemptionTimeoutNotifierRewardMultiplierUpdate(struct BridgeGovernanceParameters.RedemptionData self, uint32 _newRedemptionTimeoutNotifierRewardMultiplier) external -``` - -Begins the redemption timeout notifier reward multiplier amount -update process. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| self | struct BridgeGovernanceParameters.RedemptionData | | -| _newRedemptionTimeoutNotifierRewardMultiplier | uint32 | New redemption timeout notifier reward multiplier amount. | - -### finalizeRedemptionTimeoutNotifierRewardMultiplierUpdate - -```solidity -function finalizeRedemptionTimeoutNotifierRewardMultiplierUpdate(struct BridgeGovernanceParameters.RedemptionData self, uint256 governanceDelay) external -``` - -Finalizes the redemption timeout notifier reward multiplier amount update process. - -Can be called after the governance delay elapses. - -### beginMovingFundsTxMaxTotalFeeUpdate - -```solidity -function beginMovingFundsTxMaxTotalFeeUpdate(struct BridgeGovernanceParameters.MovingFundsData self, uint64 _newMovingFundsTxMaxTotalFee) external -``` - -Begins the moving funds tx max total fee amount update process. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| self | struct BridgeGovernanceParameters.MovingFundsData | | -| _newMovingFundsTxMaxTotalFee | uint64 | New moving funds tx max total fee amount. | - -### finalizeMovingFundsTxMaxTotalFeeUpdate - -```solidity -function finalizeMovingFundsTxMaxTotalFeeUpdate(struct BridgeGovernanceParameters.MovingFundsData self, uint256 governanceDelay) external -``` - -Finalizes the moving funds tx max total fee amount update process. - -Can be called after the governance delay elapses. - -### beginMovingFundsDustThresholdUpdate - -```solidity -function beginMovingFundsDustThresholdUpdate(struct BridgeGovernanceParameters.MovingFundsData self, uint64 _newMovingFundsDustThreshold) external -``` - -Begins the moving funds dust threshold amount update process. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| self | struct BridgeGovernanceParameters.MovingFundsData | | -| _newMovingFundsDustThreshold | uint64 | New moving funds dust threshold amount. | - -### finalizeMovingFundsDustThresholdUpdate - -```solidity -function finalizeMovingFundsDustThresholdUpdate(struct BridgeGovernanceParameters.MovingFundsData self, uint256 governanceDelay) external -``` - -Finalizes the moving funds dust threshold amount update process. - -Can be called after the governance delay elapses. - -### beginMovingFundsTimeoutResetDelayUpdate - -```solidity -function beginMovingFundsTimeoutResetDelayUpdate(struct BridgeGovernanceParameters.MovingFundsData self, uint32 _newMovingFundsTimeoutResetDelay) external -``` - -Begins the moving funds timeout reset delay amount update process. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| self | struct BridgeGovernanceParameters.MovingFundsData | | -| _newMovingFundsTimeoutResetDelay | uint32 | New moving funds timeout reset delay amount. | - -### finalizeMovingFundsTimeoutResetDelayUpdate - -```solidity -function finalizeMovingFundsTimeoutResetDelayUpdate(struct BridgeGovernanceParameters.MovingFundsData self, uint256 governanceDelay) external -``` - -Finalizes the moving funds timeout reset delay amount update process. - -Can be called after the governance delay elapses. - -### beginMovingFundsTimeoutUpdate - -```solidity -function beginMovingFundsTimeoutUpdate(struct BridgeGovernanceParameters.MovingFundsData self, uint32 _newMovingFundsTimeout) external -``` - -Begins the moving funds timeout amount update process. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| self | struct BridgeGovernanceParameters.MovingFundsData | | -| _newMovingFundsTimeout | uint32 | New moving funds timeout amount. | - -### finalizeMovingFundsTimeoutUpdate - -```solidity -function finalizeMovingFundsTimeoutUpdate(struct BridgeGovernanceParameters.MovingFundsData self, uint256 governanceDelay) external -``` - -Finalizes the moving funds timeout amount update process. - -Can be called after the governance delay elapses. - -### beginMovingFundsTimeoutSlashingAmountUpdate - -```solidity -function beginMovingFundsTimeoutSlashingAmountUpdate(struct BridgeGovernanceParameters.MovingFundsData self, uint96 _newMovingFundsTimeoutSlashingAmount) external -``` - -Begins the moving funds timeout slashing amount update process. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| self | struct BridgeGovernanceParameters.MovingFundsData | | -| _newMovingFundsTimeoutSlashingAmount | uint96 | New moving funds timeout slashing amount. | - -### finalizeMovingFundsTimeoutSlashingAmountUpdate - -```solidity -function finalizeMovingFundsTimeoutSlashingAmountUpdate(struct BridgeGovernanceParameters.MovingFundsData self, uint256 governanceDelay) external -``` - -Finalizes the moving funds timeout slashing amount update process. - -Can be called after the governance delay elapses. - -### beginMovingFundsTimeoutNotifierRewardMultiplierUpdate - -```solidity -function beginMovingFundsTimeoutNotifierRewardMultiplierUpdate(struct BridgeGovernanceParameters.MovingFundsData self, uint32 _newMovingFundsTimeoutNotifierRewardMultiplier) external -``` - -Begins the moving funds timeout notifier reward multiplier amount -update process. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| self | struct BridgeGovernanceParameters.MovingFundsData | | -| _newMovingFundsTimeoutNotifierRewardMultiplier | uint32 | New moving funds timeout notifier reward multiplier amount. | - -### finalizeMovingFundsTimeoutNotifierRewardMultiplierUpdate - -```solidity -function finalizeMovingFundsTimeoutNotifierRewardMultiplierUpdate(struct BridgeGovernanceParameters.MovingFundsData self, uint256 governanceDelay) external -``` - -Finalizes the moving funds timeout notifier reward multiplier -amount update process. - -Can be called after the governance delay elapses. - -### beginMovingFundsCommitmentGasOffsetUpdate - -```solidity -function beginMovingFundsCommitmentGasOffsetUpdate(struct BridgeGovernanceParameters.MovingFundsData self, uint16 _newMovingFundsCommitmentGasOffset) external -``` - -Begins the moving funds commitment gas offset update process. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| self | struct BridgeGovernanceParameters.MovingFundsData | | -| _newMovingFundsCommitmentGasOffset | uint16 | New moving funds commitment gas offset. | - -### finalizeMovingFundsCommitmentGasOffsetUpdate - -```solidity -function finalizeMovingFundsCommitmentGasOffsetUpdate(struct BridgeGovernanceParameters.MovingFundsData self, uint256 governanceDelay) external -``` - -Finalizes the moving funds commitment gas offset update process. - -Can be called after the governance delay elapses. - -### beginMovedFundsSweepTxMaxTotalFeeUpdate - -```solidity -function beginMovedFundsSweepTxMaxTotalFeeUpdate(struct BridgeGovernanceParameters.MovingFundsData self, uint64 _newMovedFundsSweepTxMaxTotalFee) external -``` - -Begins the moved funds sweep tx max total fee amount update process. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| self | struct BridgeGovernanceParameters.MovingFundsData | | -| _newMovedFundsSweepTxMaxTotalFee | uint64 | New moved funds sweep tx max total fee amount. | - -### finalizeMovedFundsSweepTxMaxTotalFeeUpdate - -```solidity -function finalizeMovedFundsSweepTxMaxTotalFeeUpdate(struct BridgeGovernanceParameters.MovingFundsData self, uint256 governanceDelay) external -``` - -Finalizes the moved funds sweep tx max total fee amount update -process. - -Can be called after the governance delay elapses. - -### beginMovedFundsSweepTimeoutUpdate - -```solidity -function beginMovedFundsSweepTimeoutUpdate(struct BridgeGovernanceParameters.MovingFundsData self, uint32 _newMovedFundsSweepTimeout) external -``` - -Begins the moved funds sweep timeout amount update process. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| self | struct BridgeGovernanceParameters.MovingFundsData | | -| _newMovedFundsSweepTimeout | uint32 | New moved funds sweep timeout amount. | - -### finalizeMovedFundsSweepTimeoutUpdate - -```solidity -function finalizeMovedFundsSweepTimeoutUpdate(struct BridgeGovernanceParameters.MovingFundsData self, uint256 governanceDelay) external -``` - -Finalizes the moved funds sweep timeout amount update process. - -Can be called after the governance delay elapses. - -### beginMovedFundsSweepTimeoutSlashingAmountUpdate - -```solidity -function beginMovedFundsSweepTimeoutSlashingAmountUpdate(struct BridgeGovernanceParameters.MovingFundsData self, uint96 _newMovedFundsSweepTimeoutSlashingAmount) external -``` - -Begins the moved funds sweep timeout slashing amount update -process. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| self | struct BridgeGovernanceParameters.MovingFundsData | | -| _newMovedFundsSweepTimeoutSlashingAmount | uint96 | New moved funds sweep timeout slashing amount. | - -### finalizeMovedFundsSweepTimeoutSlashingAmountUpdate - -```solidity -function finalizeMovedFundsSweepTimeoutSlashingAmountUpdate(struct BridgeGovernanceParameters.MovingFundsData self, uint256 governanceDelay) external -``` - -Finalizes the moved funds sweep timeout slashing amount -update process. - -Can be called after the governance delay elapses. - -### beginMovedFundsSweepTimeoutNotifierRewardMultiplierUpdate - -```solidity -function beginMovedFundsSweepTimeoutNotifierRewardMultiplierUpdate(struct BridgeGovernanceParameters.MovingFundsData self, uint32 _newMovedFundsSweepTimeoutNotifierRewardMultiplier) external -``` - -Begins the moved funds sweep timeout notifier reward multiplier -amount update process. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| self | struct BridgeGovernanceParameters.MovingFundsData | | -| _newMovedFundsSweepTimeoutNotifierRewardMultiplier | uint32 | New moved funds sweep timeout notifier reward multiplier amount. | - -### finalizeMovedFundsSweepTimeoutNotifierRewardMultiplierUpdate - -```solidity -function finalizeMovedFundsSweepTimeoutNotifierRewardMultiplierUpdate(struct BridgeGovernanceParameters.MovingFundsData self, uint256 governanceDelay) external -``` - -Finalizes the moved funds sweep timeout notifier reward multiplier -amount update process. - -Can be called after the governance delay elapses. - -### beginWalletCreationPeriodUpdate - -```solidity -function beginWalletCreationPeriodUpdate(struct BridgeGovernanceParameters.WalletData self, uint32 _newWalletCreationPeriod) external -``` - -Begins the wallet creation period amount update process. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| self | struct BridgeGovernanceParameters.WalletData | | -| _newWalletCreationPeriod | uint32 | New wallet creation period amount. | - -### finalizeWalletCreationPeriodUpdate - -```solidity -function finalizeWalletCreationPeriodUpdate(struct BridgeGovernanceParameters.WalletData self, uint256 governanceDelay) external -``` - -Finalizes the wallet creation period amount update process. - -Can be called after the governance delay elapses. - -### beginWalletCreationMinBtcBalanceUpdate - -```solidity -function beginWalletCreationMinBtcBalanceUpdate(struct BridgeGovernanceParameters.WalletData self, uint64 _newWalletCreationMinBtcBalance) external -``` - -Begins the wallet creation min btc balance amount update process. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| self | struct BridgeGovernanceParameters.WalletData | | -| _newWalletCreationMinBtcBalance | uint64 | New wallet creation min btc balance amount. | - -### finalizeWalletCreationMinBtcBalanceUpdate - -```solidity -function finalizeWalletCreationMinBtcBalanceUpdate(struct BridgeGovernanceParameters.WalletData self, uint256 governanceDelay) external -``` - -Finalizes the wallet creation min btc balance amount update process. - -Can be called after the governance delay elapses. - -### beginWalletCreationMaxBtcBalanceUpdate - -```solidity -function beginWalletCreationMaxBtcBalanceUpdate(struct BridgeGovernanceParameters.WalletData self, uint64 _newWalletCreationMaxBtcBalance) external -``` - -Begins the wallet creation max btc balance amount update process. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| self | struct BridgeGovernanceParameters.WalletData | | -| _newWalletCreationMaxBtcBalance | uint64 | New wallet creation max btc balance amount. | - -### finalizeWalletCreationMaxBtcBalanceUpdate - -```solidity -function finalizeWalletCreationMaxBtcBalanceUpdate(struct BridgeGovernanceParameters.WalletData self, uint256 governanceDelay) external -``` - -Finalizes the wallet creation max btc balance amount update process. - -Can be called after the governance delay elapses. - -### beginWalletClosureMinBtcBalanceUpdate - -```solidity -function beginWalletClosureMinBtcBalanceUpdate(struct BridgeGovernanceParameters.WalletData self, uint64 _newWalletClosureMinBtcBalance) external -``` - -Begins the wallet closure min btc balance amount update process. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| self | struct BridgeGovernanceParameters.WalletData | | -| _newWalletClosureMinBtcBalance | uint64 | New wallet closure min btc balance amount. | - -### finalizeWalletClosureMinBtcBalanceUpdate - -```solidity -function finalizeWalletClosureMinBtcBalanceUpdate(struct BridgeGovernanceParameters.WalletData self, uint256 governanceDelay) external -``` - -Finalizes the wallet closure min btc balance amount update process. - -Can be called after the governance delay elapses. - -### beginWalletMaxAgeUpdate - -```solidity -function beginWalletMaxAgeUpdate(struct BridgeGovernanceParameters.WalletData self, uint32 _newWalletMaxAge) external -``` - -Begins the wallet max age amount update process. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| self | struct BridgeGovernanceParameters.WalletData | | -| _newWalletMaxAge | uint32 | New wallet max age amount. | - -### finalizeWalletMaxAgeUpdate - -```solidity -function finalizeWalletMaxAgeUpdate(struct BridgeGovernanceParameters.WalletData self, uint256 governanceDelay) external -``` - -Finalizes the wallet max age amount update process. - -Can be called after the governance delay elapses. - -### beginWalletMaxBtcTransferUpdate - -```solidity -function beginWalletMaxBtcTransferUpdate(struct BridgeGovernanceParameters.WalletData self, uint64 _newWalletMaxBtcTransfer) external -``` - -Begins the wallet max btc transfer amount update process. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| self | struct BridgeGovernanceParameters.WalletData | | -| _newWalletMaxBtcTransfer | uint64 | New wallet max btc transfer amount. | - -### finalizeWalletMaxBtcTransferUpdate - -```solidity -function finalizeWalletMaxBtcTransferUpdate(struct BridgeGovernanceParameters.WalletData self, uint256 governanceDelay) external -``` - -Finalizes the wallet max btc transfer amount update process. - -Can be called after the governance delay elapses. - -### beginWalletClosingPeriodUpdate - -```solidity -function beginWalletClosingPeriodUpdate(struct BridgeGovernanceParameters.WalletData self, uint32 _newWalletClosingPeriod) external -``` - -Begins the wallet closing period amount update process. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| self | struct BridgeGovernanceParameters.WalletData | | -| _newWalletClosingPeriod | uint32 | New wallet closing period amount. | - -### finalizeWalletClosingPeriodUpdate - -```solidity -function finalizeWalletClosingPeriodUpdate(struct BridgeGovernanceParameters.WalletData self, uint256 governanceDelay) external -``` - -Finalizes the wallet closing period amount update process. - -Can be called after the governance delay elapses. - -### beginFraudChallengeDepositAmountUpdate - -```solidity -function beginFraudChallengeDepositAmountUpdate(struct BridgeGovernanceParameters.FraudData self, uint96 _newFraudChallengeDepositAmount) external -``` - -Begins the fraud challenge deposit amount update process. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| self | struct BridgeGovernanceParameters.FraudData | | -| _newFraudChallengeDepositAmount | uint96 | New fraud challenge deposit amount. | - -### finalizeFraudChallengeDepositAmountUpdate - -```solidity -function finalizeFraudChallengeDepositAmountUpdate(struct BridgeGovernanceParameters.FraudData self, uint256 governanceDelay) external -``` - -Finalizes the fraud challenge deposit amount update process. - -Can be called after the governance delay elapses. - -### beginFraudChallengeDefeatTimeoutUpdate - -```solidity -function beginFraudChallengeDefeatTimeoutUpdate(struct BridgeGovernanceParameters.FraudData self, uint32 _newFraudChallengeDefeatTimeout) external -``` - -Begins the fraud challenge defeat timeout amount update process. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| self | struct BridgeGovernanceParameters.FraudData | | -| _newFraudChallengeDefeatTimeout | uint32 | New fraud challenge defeat timeout amount. | - -### finalizeFraudChallengeDefeatTimeoutUpdate - -```solidity -function finalizeFraudChallengeDefeatTimeoutUpdate(struct BridgeGovernanceParameters.FraudData self, uint256 governanceDelay) external -``` - -Finalizes the fraud challenge defeat timeout amount update process. - -Can be called after the governance delay elapses. - -### beginFraudSlashingAmountUpdate - -```solidity -function beginFraudSlashingAmountUpdate(struct BridgeGovernanceParameters.FraudData self, uint96 _newFraudSlashingAmount) external -``` - -Begins the fraud slashing amount update process. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| self | struct BridgeGovernanceParameters.FraudData | | -| _newFraudSlashingAmount | uint96 | New fraud slashing amount. | - -### finalizeFraudSlashingAmountUpdate - -```solidity -function finalizeFraudSlashingAmountUpdate(struct BridgeGovernanceParameters.FraudData self, uint256 governanceDelay) external -``` - -Finalizes the fraud slashing amount update process. - -Can be called after the governance delay elapses. - -### beginFraudNotifierRewardMultiplierUpdate - -```solidity -function beginFraudNotifierRewardMultiplierUpdate(struct BridgeGovernanceParameters.FraudData self, uint32 _newFraudNotifierRewardMultiplier) external -``` - -Begins the fraud notifier reward multiplier amount update process. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| self | struct BridgeGovernanceParameters.FraudData | | -| _newFraudNotifierRewardMultiplier | uint32 | New fraud notifier reward multiplier amount. | - -### finalizeFraudNotifierRewardMultiplierUpdate - -```solidity -function finalizeFraudNotifierRewardMultiplierUpdate(struct BridgeGovernanceParameters.FraudData self, uint256 governanceDelay) external -``` - -Finalizes the fraud notifier reward multiplier amount update process. - -Can be called after the governance delay elapses. - -### beginTreasuryUpdate - -```solidity -function beginTreasuryUpdate(struct BridgeGovernanceParameters.TreasuryData self, address _newTreasury) external -``` - -Begins the treasury address update process. - -It does not perform any parameter validation. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| self | struct BridgeGovernanceParameters.TreasuryData | | -| _newTreasury | address | New treasury address. | - -### finalizeTreasuryUpdate - -```solidity -function finalizeTreasuryUpdate(struct BridgeGovernanceParameters.TreasuryData self, uint256 governanceDelay) external -``` - -Finalizes the treasury address update process. - -Can be called after the governance delay elapses. - -## BridgeState - -### Storage - -```solidity -struct Storage { - contract Bank bank; - contract IRelay relay; - uint96 txProofDifficultyFactor; - contract IWalletRegistry ecdsaWalletRegistry; - contract ReimbursementPool reimbursementPool; - address treasury; - bytes32 __treasuryAlignmentGap; - uint64 depositDustThreshold; - uint64 depositTreasuryFeeDivisor; - uint64 depositTxMaxFee; - uint32 depositRevealAheadPeriod; - bytes32 __depositAlignmentGap; - uint64 movingFundsTxMaxTotalFee; - uint64 movingFundsDustThreshold; - uint32 movingFundsTimeoutResetDelay; - uint32 movingFundsTimeout; - uint96 movingFundsTimeoutSlashingAmount; - uint32 movingFundsTimeoutNotifierRewardMultiplier; - uint16 movingFundsCommitmentGasOffset; - bytes32 __movingFundsAlignmentGap; - uint64 movedFundsSweepTxMaxTotalFee; - uint32 movedFundsSweepTimeout; - uint96 movedFundsSweepTimeoutSlashingAmount; - uint32 movedFundsSweepTimeoutNotifierRewardMultiplier; - uint64 redemptionDustThreshold; - uint64 redemptionTreasuryFeeDivisor; - uint64 redemptionTxMaxFee; - uint64 redemptionTxMaxTotalFee; - bytes32 __redemptionAlignmentGap; - uint32 redemptionTimeout; - uint96 redemptionTimeoutSlashingAmount; - uint32 redemptionTimeoutNotifierRewardMultiplier; - uint96 fraudChallengeDepositAmount; - uint32 fraudChallengeDefeatTimeout; - uint96 fraudSlashingAmount; - uint32 fraudNotifierRewardMultiplier; - uint32 walletCreationPeriod; - uint64 walletCreationMinBtcBalance; - uint64 walletCreationMaxBtcBalance; - uint64 walletClosureMinBtcBalance; - uint32 walletMaxAge; - bytes20 activeWalletPubKeyHash; - uint32 liveWalletsCount; - uint64 walletMaxBtcTransfer; - uint32 walletClosingPeriod; - mapping(uint256 => struct Deposit.DepositRequest) deposits; - mapping(address => bool) isVaultTrusted; - mapping(address => bool) isSpvMaintainer; - mapping(uint256 => struct MovingFunds.MovedFundsSweepRequest) movedFundsSweepRequests; - mapping(uint256 => struct Redemption.RedemptionRequest) pendingRedemptions; - mapping(uint256 => struct Redemption.RedemptionRequest) timedOutRedemptions; - mapping(uint256 => struct Fraud.FraudChallenge) fraudChallenges; - mapping(uint256 => bool) spentMainUTXOs; - mapping(bytes20 => struct Wallets.Wallet) registeredWallets; - uint256[50] __gap; -} -``` - -### DepositParametersUpdated - -```solidity -event DepositParametersUpdated(uint64 depositDustThreshold, uint64 depositTreasuryFeeDivisor, uint64 depositTxMaxFee, uint32 depositRevealAheadPeriod) -``` - -### RedemptionParametersUpdated - -```solidity -event RedemptionParametersUpdated(uint64 redemptionDustThreshold, uint64 redemptionTreasuryFeeDivisor, uint64 redemptionTxMaxFee, uint64 redemptionTxMaxTotalFee, uint32 redemptionTimeout, uint96 redemptionTimeoutSlashingAmount, uint32 redemptionTimeoutNotifierRewardMultiplier) -``` - -### MovingFundsParametersUpdated - -```solidity -event MovingFundsParametersUpdated(uint64 movingFundsTxMaxTotalFee, uint64 movingFundsDustThreshold, uint32 movingFundsTimeoutResetDelay, uint32 movingFundsTimeout, uint96 movingFundsTimeoutSlashingAmount, uint32 movingFundsTimeoutNotifierRewardMultiplier, uint16 movingFundsCommitmentGasOffset, uint64 movedFundsSweepTxMaxTotalFee, uint32 movedFundsSweepTimeout, uint96 movedFundsSweepTimeoutSlashingAmount, uint32 movedFundsSweepTimeoutNotifierRewardMultiplier) -``` - -### WalletParametersUpdated - -```solidity -event WalletParametersUpdated(uint32 walletCreationPeriod, uint64 walletCreationMinBtcBalance, uint64 walletCreationMaxBtcBalance, uint64 walletClosureMinBtcBalance, uint32 walletMaxAge, uint64 walletMaxBtcTransfer, uint32 walletClosingPeriod) -``` - -### FraudParametersUpdated - -```solidity -event FraudParametersUpdated(uint96 fraudChallengeDepositAmount, uint32 fraudChallengeDefeatTimeout, uint96 fraudSlashingAmount, uint32 fraudNotifierRewardMultiplier) -``` - -### TreasuryUpdated - -```solidity -event TreasuryUpdated(address treasury) -``` - -### updateDepositParameters - -```solidity -function updateDepositParameters(struct BridgeState.Storage self, uint64 _depositDustThreshold, uint64 _depositTreasuryFeeDivisor, uint64 _depositTxMaxFee, uint32 _depositRevealAheadPeriod) internal -``` - -of `depositTreasuryFeeDivisor` and `depositTxMaxFee` parameters -in order to make requests that can incur the treasury and -transaction fee and still satisfy the depositor. - -Requirements: -- Deposit dust threshold must be greater than zero, -- Deposit dust threshold must be greater than deposit TX max fee, -- Deposit transaction max fee must be greater than zero. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| self | struct BridgeState.Storage | | -| _depositDustThreshold | uint64 | | -| _depositTreasuryFeeDivisor | uint64 | New value of the treasury fee divisor. It is the divisor used to compute the treasury fee taken from each deposit and transferred to the treasury upon sweep proof submission. That fee is computed as follows: `treasuryFee = depositedAmount / depositTreasuryFeeDivisor` For example, if the treasury fee needs to be 2% of each deposit, the `depositTreasuryFeeDivisor` should be set to `50` because `1/50 = 0.02 = 2%`. | -| _depositTxMaxFee | uint64 | New value of the deposit tx max fee in satoshis. It is the maximum amount of BTC transaction fee that can be incurred by each swept deposit being part of the given sweep transaction. If the maximum BTC transaction fee is exceeded, such transaction is considered a fraud. | -| _depositRevealAheadPeriod | uint32 | New value of the deposit reveal ahead period parameter in seconds. It defines the length of the period that must be preserved between the deposit reveal time and the deposit refund locktime. | - -### updateRedemptionParameters - -```solidity -function updateRedemptionParameters(struct BridgeState.Storage self, uint64 _redemptionDustThreshold, uint64 _redemptionTreasuryFeeDivisor, uint64 _redemptionTxMaxFee, uint64 _redemptionTxMaxTotalFee, uint32 _redemptionTimeout, uint96 _redemptionTimeoutSlashingAmount, uint32 _redemptionTimeoutNotifierRewardMultiplier) internal -``` - -Updates parameters of redemptions. - -Requirements: -- Redemption dust threshold must be greater than moving funds dust -threshold, -- Redemption dust threshold must be greater than the redemption TX -max fee, -- Redemption transaction max fee must be greater than zero, -- Redemption transaction max total fee must be greater than or -equal to the redemption transaction per-request max fee, -- Redemption timeout must be greater than zero, -- Redemption timeout notifier reward multiplier must be in the -range [0, 100]. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| self | struct BridgeState.Storage | | -| _redemptionDustThreshold | uint64 | New value of the redemption dust threshold in satoshis. It is the minimal amount that can be requested for redemption. Value of this parameter must take into account the value of `redemptionTreasuryFeeDivisor` and `redemptionTxMaxFee` parameters in order to make requests that can incur the treasury and transaction fee and still satisfy the redeemer. | -| _redemptionTreasuryFeeDivisor | uint64 | New value of the redemption treasury fee divisor. It is the divisor used to compute the treasury fee taken from each redemption request and transferred to the treasury upon successful request finalization. That fee is computed as follows: `treasuryFee = requestedAmount / redemptionTreasuryFeeDivisor` For example, if the treasury fee needs to be 2% of each redemption request, the `redemptionTreasuryFeeDivisor` should be set to `50` because `1/50 = 0.02 = 2%`. | -| _redemptionTxMaxFee | uint64 | New value of the redemption transaction max fee in satoshis. It is the maximum amount of BTC transaction fee that can be incurred by each redemption request being part of the given redemption transaction. If the maximum BTC transaction fee is exceeded, such transaction is considered a fraud. This is a per-redemption output max fee for the redemption transaction. | -| _redemptionTxMaxTotalFee | uint64 | New value of the redemption transaction max total fee in satoshis. It is the maximum amount of the total BTC transaction fee that is acceptable in a single redemption transaction. This is a _total_ max fee for the entire redemption transaction. | -| _redemptionTimeout | uint32 | New value of the redemption timeout in seconds. It is the time after which the redemption request can be reported as timed out. It is counted from the moment when the redemption request was created via `requestRedemption` call. Reported timed out requests are cancelled and locked TBTC is returned to the redeemer in full amount. | -| _redemptionTimeoutSlashingAmount | uint96 | New value of the redemption timeout slashing amount in T, it is the amount slashed from each wallet member for redemption timeout. | -| _redemptionTimeoutNotifierRewardMultiplier | uint32 | New value of the redemption timeout notifier reward multiplier as percentage, it determines the percentage of the notifier reward from the staking contact the notifier of a redemption timeout receives. The value must be in the range [0, 100]. | - -### updateMovingFundsParameters - -```solidity -function updateMovingFundsParameters(struct BridgeState.Storage self, uint64 _movingFundsTxMaxTotalFee, uint64 _movingFundsDustThreshold, uint32 _movingFundsTimeoutResetDelay, uint32 _movingFundsTimeout, uint96 _movingFundsTimeoutSlashingAmount, uint32 _movingFundsTimeoutNotifierRewardMultiplier, uint16 _movingFundsCommitmentGasOffset, uint64 _movedFundsSweepTxMaxTotalFee, uint32 _movedFundsSweepTimeout, uint96 _movedFundsSweepTimeoutSlashingAmount, uint32 _movedFundsSweepTimeoutNotifierRewardMultiplier) internal -``` - -Updates parameters of moving funds. - -Requirements: -- Moving funds transaction max total fee must be greater than zero, -- Moving funds dust threshold must be greater than zero and lower -than the redemption dust threshold, -- Moving funds timeout reset delay must be greater than zero, -- Moving funds timeout must be greater than the moving funds -timeout reset delay, -- Moving funds timeout notifier reward multiplier must be in the -range [0, 100], -- Moved funds sweep transaction max total fee must be greater than zero, -- Moved funds sweep timeout must be greater than zero, -- Moved funds sweep timeout notifier reward multiplier must be in the -range [0, 100]. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| self | struct BridgeState.Storage | | -| _movingFundsTxMaxTotalFee | uint64 | New value of the moving funds transaction max total fee in satoshis. It is the maximum amount of the total BTC transaction fee that is acceptable in a single moving funds transaction. This is a _total_ max fee for the entire moving funds transaction. | -| _movingFundsDustThreshold | uint64 | New value of the moving funds dust threshold. It is the minimal satoshi amount that makes sense to be transferred during the moving funds process. Moving funds wallets having their BTC balance below that value can begin closing immediately as transferring such a low value may not be possible due to BTC network fees. | -| _movingFundsTimeoutResetDelay | uint32 | New value of the moving funds timeout reset delay in seconds. It is the time after which the moving funds timeout can be reset in case the target wallet commitment cannot be submitted due to a lack of live wallets in the system. It is counted from the moment when the wallet was requested to move their funds and switched to the MovingFunds state or from the moment the timeout was reset the last time. | -| _movingFundsTimeout | uint32 | New value of the moving funds timeout in seconds. It is the time after which the moving funds process can be reported as timed out. It is counted from the moment when the wallet was requested to move their funds and switched to the MovingFunds state. | -| _movingFundsTimeoutSlashingAmount | uint96 | New value of the moving funds timeout slashing amount in T, it is the amount slashed from each wallet member for moving funds timeout. | -| _movingFundsTimeoutNotifierRewardMultiplier | uint32 | New value of the moving funds timeout notifier reward multiplier as percentage, it determines the percentage of the notifier reward from the staking contact the notifier of a moving funds timeout receives. The value must be in the range [0, 100]. | -| _movingFundsCommitmentGasOffset | uint16 | New value of the gas offset for moving funds target wallet commitment transaction gas costs reimbursement. | -| _movedFundsSweepTxMaxTotalFee | uint64 | New value of the moved funds sweep transaction max total fee in satoshis. It is the maximum amount of the total BTC transaction fee that is acceptable in a single moved funds sweep transaction. This is a _total_ max fee for the entire moved funds sweep transaction. | -| _movedFundsSweepTimeout | uint32 | New value of the moved funds sweep timeout in seconds. It is the time after which the moved funds sweep process can be reported as timed out. It is counted from the moment when the wallet was requested to sweep the received funds. | -| _movedFundsSweepTimeoutSlashingAmount | uint96 | New value of the moved funds sweep timeout slashing amount in T, it is the amount slashed from each wallet member for moved funds sweep timeout. | -| _movedFundsSweepTimeoutNotifierRewardMultiplier | uint32 | New value of the moved funds sweep timeout notifier reward multiplier as percentage, it determines the percentage of the notifier reward from the staking contact the notifier of a moved funds sweep timeout receives. The value must be in the range [0, 100]. | - -### updateWalletParameters - -```solidity -function updateWalletParameters(struct BridgeState.Storage self, uint32 _walletCreationPeriod, uint64 _walletCreationMinBtcBalance, uint64 _walletCreationMaxBtcBalance, uint64 _walletClosureMinBtcBalance, uint32 _walletMaxAge, uint64 _walletMaxBtcTransfer, uint32 _walletClosingPeriod) internal -``` - -Requirements: -- Wallet maximum BTC balance must be greater than the wallet -minimum BTC balance, -- Wallet maximum BTC transfer must be greater than zero, -- Wallet closing period must be greater than zero. - -### updateFraudParameters - -```solidity -function updateFraudParameters(struct BridgeState.Storage self, uint96 _fraudChallengeDepositAmount, uint32 _fraudChallengeDefeatTimeout, uint96 _fraudSlashingAmount, uint32 _fraudNotifierRewardMultiplier) internal -``` - -Updates parameters related to frauds. - -Requirements: -- Fraud challenge defeat timeout must be greater than 0, -- Fraud notifier reward multiplier must be in the range [0, 100]. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| self | struct BridgeState.Storage | | -| _fraudChallengeDepositAmount | uint96 | New value of the fraud challenge deposit amount in wei, it is the amount of ETH the party challenging the wallet for fraud needs to deposit. | -| _fraudChallengeDefeatTimeout | uint32 | New value of the challenge defeat timeout in seconds, it is the amount of time the wallet has to defeat a fraud challenge. The value must be greater than zero. | -| _fraudSlashingAmount | uint96 | New value of the fraud slashing amount in T, it is the amount slashed from each wallet member for committing a fraud. | -| _fraudNotifierRewardMultiplier | uint32 | New value of the fraud notifier reward multiplier as percentage, it determines the percentage of the notifier reward from the staking contact the notifier of a fraud receives. The value must be in the range [0, 100]. | - -### updateTreasury - -```solidity -function updateTreasury(struct BridgeState.Storage self, address _treasury) internal -``` - -Updates treasury address. The treasury receives the system fees. - -The treasury address must not be 0x0. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| self | struct BridgeState.Storage | | -| _treasury | address | New value of the treasury address. | - -## Deposit - -The library handles the logic for revealing Bitcoin deposits to -the Bridge. - -The depositor puts together a P2SH or P2WSH address to deposit the -funds. This script is unique to each depositor and looks like this: - -``` - DROP - DROP -DUP HASH160 EQUAL -IF -CHECKSIG -ELSE -DUP HASH160 EQUALVERIFY - CHECKLOCKTIMEVERIFY DROP -CHECKSIG -ENDIF -``` - -Since each depositor has their own Ethereum address and their own -blinding factor, each depositor’s script is unique, and the hash -of each depositor’s script is unique. - -### DepositRevealInfo - -```solidity -struct DepositRevealInfo { - uint32 fundingOutputIndex; - bytes8 blindingFactor; - bytes20 walletPubKeyHash; - bytes20 refundPubKeyHash; - bytes4 refundLocktime; - address vault; -} -``` - -### DepositRequest - -```solidity -struct DepositRequest { - address depositor; - uint64 amount; - uint32 revealedAt; - address vault; - uint64 treasuryFee; - uint32 sweptAt; -} -``` - -### DepositRevealed - -```solidity -event DepositRevealed(bytes32 fundingTxHash, uint32 fundingOutputIndex, address depositor, uint64 amount, bytes8 blindingFactor, bytes20 walletPubKeyHash, bytes20 refundPubKeyHash, bytes4 refundLocktime, address vault) -``` - -### revealDeposit - -```solidity -function revealDeposit(struct BridgeState.Storage self, struct BitcoinTx.Info fundingTx, struct Deposit.DepositRevealInfo reveal) external -``` - -Used by the depositor to reveal information about their P2(W)SH -Bitcoin deposit to the Bridge on Ethereum chain. The off-chain -wallet listens for revealed deposit events and may decide to -include the revealed deposit in the next executed sweep. -Information about the Bitcoin deposit can be revealed before or -after the Bitcoin transaction with P2(W)SH deposit is mined on -the Bitcoin chain. Worth noting, the gas cost of this function -scales with the number of P2(W)SH transaction inputs and -outputs. The deposit may be routed to one of the trusted vaults. -When a deposit is routed to a vault, vault gets notified when -the deposit gets swept and it may execute the appropriate action. - -Requirements: -- This function must be called by the same Ethereum address as the -one used in the P2(W)SH BTC deposit transaction as a depositor, -- `reveal.walletPubKeyHash` must identify a `Live` wallet, -- `reveal.vault` must be 0x0 or point to a trusted vault, -- `reveal.fundingOutputIndex` must point to the actual P2(W)SH -output of the BTC deposit transaction, -- `reveal.blindingFactor` must be the blinding factor used in the -P2(W)SH BTC deposit transaction, -- `reveal.walletPubKeyHash` must be the wallet pub key hash used in -the P2(W)SH BTC deposit transaction, -- `reveal.refundPubKeyHash` must be the refund pub key hash used in -the P2(W)SH BTC deposit transaction, -- `reveal.refundLocktime` must be the refund locktime used in the -P2(W)SH BTC deposit transaction, -- BTC deposit for the given `fundingTxHash`, `fundingOutputIndex` -can be revealed only one time. - -If any of these requirements is not met, the wallet _must_ refuse -to sweep the deposit and the depositor has to wait until the -deposit script unlocks to receive their BTC back. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| self | struct BridgeState.Storage | | -| fundingTx | struct BitcoinTx.Info | Bitcoin funding transaction data, see `BitcoinTx.Info`. | -| reveal | struct Deposit.DepositRevealInfo | Deposit reveal data, see `RevealInfo struct. | - -### validateDepositRefundLocktime - -```solidity -function validateDepositRefundLocktime(struct BridgeState.Storage self, bytes4 refundLocktime) internal view -``` - -Validates the deposit refund locktime. The validation passes -successfully only if the deposit reveal is done respectively -earlier than the moment when the deposit refund locktime is -reached, i.e. the deposit become refundable. Reverts otherwise. - -Requirements: -- `refundLocktime` as integer must be >= 500M -- `refundLocktime` must denote a timestamp that is at least -`depositRevealAheadPeriod` seconds later than the moment -of `block.timestamp` - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| self | struct BridgeState.Storage | | -| refundLocktime | bytes4 | The deposit refund locktime as 4-byte LE. | - -## DepositSweep - -The library handles the logic for sweeping transactions revealed to -the Bridge - -Bridge active wallet periodically signs a transaction that unlocks all -of the valid, revealed deposits above the dust threshold, combines them -into a single UTXO with the existing main wallet UTXO, and relocks -those transactions without a 30-day refund clause to the same wallet. -This has two main effects: it consolidates the UTXO set and it disables -the refund. Balances of depositors in the Bank are increased when the -SPV sweep proof is submitted to the Bridge. - -### DepositSweepTxInputsProcessingInfo - -```solidity -struct DepositSweepTxInputsProcessingInfo { - bytes sweepTxInputVector; - struct BitcoinTx.UTXO mainUtxo; - address vault; -} -``` - -### DepositSweepTxInputsInfo - -```solidity -struct DepositSweepTxInputsInfo { - uint256 inputsTotalValue; - address[] depositors; - uint256[] depositedAmounts; - uint256[] treasuryFees; -} -``` - -### DepositsSwept - -```solidity -event DepositsSwept(bytes20 walletPubKeyHash, bytes32 sweepTxHash) -``` - -### submitDepositSweepProof - -```solidity -function submitDepositSweepProof(struct BridgeState.Storage self, struct BitcoinTx.Info sweepTx, struct BitcoinTx.Proof sweepProof, struct BitcoinTx.UTXO mainUtxo, address vault) external -``` - -Used by the wallet to prove the BTC deposit sweep transaction -and to update Bank balances accordingly. Sweep is only accepted -if it satisfies SPV proof. - -The function is performing Bank balance updates by first -computing the Bitcoin fee for the sweep transaction. The fee is -divided evenly between all swept deposits. Each depositor -receives a balance in the bank equal to the amount inferred -during the reveal transaction, minus their fee share. - -It is possible to prove the given sweep only one time. - -Requirements: -- `sweepTx` components must match the expected structure. See -`BitcoinTx.Info` docs for reference. Their values must exactly -correspond to appropriate Bitcoin transaction fields to produce -a provable transaction hash, -- The `sweepTx` should represent a Bitcoin transaction with 1..n -inputs. If the wallet has no main UTXO, all n inputs should -correspond to P2(W)SH revealed deposits UTXOs. If the wallet has -an existing main UTXO, one of the n inputs must point to that -main UTXO and remaining n-1 inputs should correspond to P2(W)SH -revealed deposits UTXOs. That transaction must have only -one P2(W)PKH output locking funds on the 20-byte wallet public -key hash, -- All revealed deposits that are swept by `sweepTx` must have -their `vault` parameters set to the same address as the address -passed in the `vault` function parameter, -- `sweepProof` components must match the expected structure. See -`BitcoinTx.Proof` docs for reference. The `bitcoinHeaders` -field must contain a valid number of block headers, not less -than the `txProofDifficultyFactor` contract constant, -- `mainUtxo` components must point to the recent main UTXO -of the given wallet, as currently known on the Ethereum chain. -If there is no main UTXO, this parameter is ignored. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| self | struct BridgeState.Storage | | -| sweepTx | struct BitcoinTx.Info | Bitcoin sweep transaction data. | -| sweepProof | struct BitcoinTx.Proof | Bitcoin sweep proof data. | -| mainUtxo | struct BitcoinTx.UTXO | Data of the wallet's main UTXO, as currently known on the Ethereum chain. If no main UTXO exists for the given wallet, this parameter is ignored. | -| vault | address | Optional address of the vault where all swept deposits should be routed to. All deposits swept as part of the transaction must have their `vault` parameters set to the same address. If this parameter is set to an address of a trusted vault, swept deposits are routed to that vault. If this parameter is set to the zero address or to an address of a non-trusted vault, swept deposits are not routed to a vault but depositors' balances are increased in the Bank individually. | - -### resolveDepositSweepingWallet - -```solidity -function resolveDepositSweepingWallet(struct BridgeState.Storage self, bytes20 walletPubKeyHash, struct BitcoinTx.UTXO mainUtxo) internal view returns (struct Wallets.Wallet wallet, struct BitcoinTx.UTXO resolvedMainUtxo) -``` - -Resolves sweeping wallet based on the provided wallet public key -hash. Validates the wallet state and current main UTXO, as -currently known on the Ethereum chain. - -Requirements: -- Sweeping wallet must be either in Live or MovingFunds state, -- If the main UTXO of the sweeping wallet exists in the storage, -the passed `mainUTXO` parameter must be equal to the stored one. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| self | struct BridgeState.Storage | | -| walletPubKeyHash | bytes20 | public key hash of the wallet proving the sweep Bitcoin transaction. | -| mainUtxo | struct BitcoinTx.UTXO | Data of the wallet's main UTXO, as currently known on the Ethereum chain. If no main UTXO exists for the given wallet, this parameter is ignored. | - -#### Return Values - -| Name | Type | Description | -| ---- | ---- | ----------- | -| wallet | struct Wallets.Wallet | Data of the sweeping wallet. | -| resolvedMainUtxo | struct BitcoinTx.UTXO | The actual main UTXO of the sweeping wallet resolved by cross-checking the `mainUtxo` parameter with the chain state. If the validation went well, this is the plain-text main UTXO corresponding to the `wallet.mainUtxoHash`. | - -### processDepositSweepTxOutput - -```solidity -function processDepositSweepTxOutput(struct BridgeState.Storage self, bytes sweepTxOutputVector) internal view returns (bytes20 walletPubKeyHash, uint64 value) -``` - -Processes the Bitcoin sweep transaction output vector by -extracting the single output and using it to gain additional -information required for further processing (e.g. value and -wallet public key hash). - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| self | struct BridgeState.Storage | | -| sweepTxOutputVector | bytes | Bitcoin sweep transaction output vector. This function assumes vector's structure is valid so it must be validated using e.g. `BTCUtils.validateVout` function before it is passed here. | - -#### Return Values - -| Name | Type | Description | -| ---- | ---- | ----------- | -| walletPubKeyHash | bytes20 | 20-byte wallet public key hash. | -| value | uint64 | 8-byte sweep transaction output value. | - -### processDepositSweepTxInputs - -```solidity -function processDepositSweepTxInputs(struct BridgeState.Storage self, struct DepositSweep.DepositSweepTxInputsProcessingInfo processInfo) internal returns (struct DepositSweep.DepositSweepTxInputsInfo resultInfo) -``` - -Processes the Bitcoin sweep transaction input vector. It -extracts each input and tries to obtain associated deposit or -main UTXO data, depending on the input type. Reverts -if one of the inputs cannot be recognized as a pointer to a -revealed deposit or expected main UTXO. -This function also marks each processed deposit as swept. - -#### Return Values - -| Name | Type | Description | -| ---- | ---- | ----------- | -| resultInfo | struct DepositSweep.DepositSweepTxInputsInfo | Outcomes of the processing. | - -### parseDepositSweepTxInputAt - -```solidity -function parseDepositSweepTxInputAt(bytes inputVector, uint256 inputStartingIndex) internal pure returns (bytes32 outpointTxHash, uint32 outpointIndex, uint256 inputLength) -``` - -Parses a Bitcoin transaction input starting at the given index. - -This function assumes vector's structure is valid so it must be -validated using e.g. `BTCUtils.validateVin` function before it -is passed here. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| inputVector | bytes | Bitcoin transaction input vector. | -| inputStartingIndex | uint256 | Index the given input starts at. | - -#### Return Values - -| Name | Type | Description | -| ---- | ---- | ----------- | -| outpointTxHash | bytes32 | 32-byte hash of the Bitcoin transaction which is pointed in the given input's outpoint. | -| outpointIndex | uint32 | 4-byte index of the Bitcoin transaction output which is pointed in the given input's outpoint. | -| inputLength | uint256 | Byte length of the given input. | - -### depositSweepTxFeeDistribution - -```solidity -function depositSweepTxFeeDistribution(uint256 sweepTxInputsTotalValue, uint256 sweepTxOutputValue, uint256 depositsCount) internal pure returns (uint256 depositTxFee, uint256 depositTxFeeRemainder) -``` - -Determines the distribution of the sweep transaction fee -over swept deposits. - -It is up to the caller to decide how the remainder should be -counted in. This function only computes its value. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| sweepTxInputsTotalValue | uint256 | Total value of all sweep transaction inputs. | -| sweepTxOutputValue | uint256 | Value of the sweep transaction output. | -| depositsCount | uint256 | Count of the deposits swept by the sweep transaction. | - -#### Return Values - -| Name | Type | Description | -| ---- | ---- | ----------- | -| depositTxFee | uint256 | Transaction fee per deposit determined by evenly spreading the divisible part of the sweep transaction fee over all deposits. | -| depositTxFeeRemainder | uint256 | The indivisible part of the sweep transaction fee than cannot be distributed over all deposits. | - -## EcdsaLib - -### compressPublicKey - -```solidity -function compressPublicKey(bytes32 x, bytes32 y) internal pure returns (bytes) -``` - -Converts public key X and Y coordinates (32-byte each) to a -compressed public key (33-byte). Compressed public key is X -coordinate prefixed with `02` or `03` based on the Y coordinate parity. -It is expected that the uncompressed public key is stripped -(i.e. it is not prefixed with `04`). - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| x | bytes32 | Wallet's public key's X coordinate. | -| y | bytes32 | Wallet's public key's Y coordinate. | - -#### Return Values - -| Name | Type | Description | -| ---- | ---- | ----------- | -| [0] | bytes | Compressed public key (33-byte), prefixed with `02` or `03`. | - -## Fraud - -The library handles the logic for challenging Bridge wallets that -committed fraud. - -Anyone can submit a fraud challenge indicating that a UTXO being under -the wallet control was unlocked by the wallet but was not used -according to the protocol rules. That means the wallet signed -a transaction input pointing to that UTXO and there is a unique -sighash and signature pair associated with that input. - -In order to defeat the challenge, the same wallet public key and -signature must be provided as were used to calculate the sighash during -the challenge. The wallet provides the preimage which produces sighash -used to generate the ECDSA signature that is the subject of the fraud -claim. - -The fraud challenge defeat attempt will succeed if the inputs in the -preimage are considered honestly spent by the wallet. Therefore the -transaction spending the UTXO must be proven in the Bridge before -a challenge defeat is called. - -Another option is when a malicious wallet member used a signed heartbeat -message periodically produced by the wallet off-chain to challenge the -wallet for a fraud. Anyone from the wallet can defeat the challenge by -proving the sighash and signature were produced for a heartbeat message -following a strict format. - -### FraudChallenge - -```solidity -struct FraudChallenge { - address challenger; - uint256 depositAmount; - uint32 reportedAt; - bool resolved; -} -``` - -### FraudChallengeSubmitted - -```solidity -event FraudChallengeSubmitted(bytes20 walletPubKeyHash, bytes32 sighash, uint8 v, bytes32 r, bytes32 s) -``` - -### FraudChallengeDefeated - -```solidity -event FraudChallengeDefeated(bytes20 walletPubKeyHash, bytes32 sighash) -``` - -### FraudChallengeDefeatTimedOut - -```solidity -event FraudChallengeDefeatTimedOut(bytes20 walletPubKeyHash, bytes32 sighash) -``` - -### submitFraudChallenge - -```solidity -function submitFraudChallenge(struct BridgeState.Storage self, bytes walletPublicKey, bytes preimageSha256, struct BitcoinTx.RSVSignature signature) external -``` - -Submits a fraud challenge indicating that a UTXO being under -wallet control was unlocked by the wallet but was not used -according to the protocol rules. That means the wallet signed -a transaction input pointing to that UTXO and there is a unique -sighash and signature pair associated with that input. This -function uses those parameters to create a fraud accusation that -proves a given transaction input unlocking the given UTXO was -actually signed by the wallet. This function cannot determine -whether the transaction was actually broadcast and the input was -consumed in a fraudulent way so it just opens a challenge period -during which the wallet can defeat the challenge by submitting -proof of a transaction that consumes the given input according -to protocol rules. To prevent spurious allegations, the caller -must deposit ETH that is returned back upon justified fraud -challenge or confiscated otherwise. - -Requirements: -- Wallet behind `walletPublicKey` must be in Live or MovingFunds -or Closing state, -- The challenger must send appropriate amount of ETH used as -fraud challenge deposit, -- The signature (represented by r, s and v) must be generated by -the wallet behind `walletPubKey` during signing of `sighash` -which was calculated from `preimageSha256`, -- Wallet can be challenged for the given signature only once. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| self | struct BridgeState.Storage | | -| walletPublicKey | bytes | The public key of the wallet in the uncompressed and unprefixed format (64 bytes). | -| preimageSha256 | bytes | The hash that was generated by applying SHA-256 one time over the preimage used during input signing. The preimage is a serialized subset of the transaction and its structure depends on the transaction input (see BIP-143 for reference). Notice that applying SHA-256 over the `preimageSha256` results in `sighash`. The path from `preimage` to `sighash` looks like this: preimage -> (SHA-256) -> preimageSha256 -> (SHA-256) -> sighash. | -| signature | struct BitcoinTx.RSVSignature | Bitcoin signature in the R/S/V format | - -### defeatFraudChallenge - -```solidity -function defeatFraudChallenge(struct BridgeState.Storage self, bytes walletPublicKey, bytes preimage, bool witness) external -``` - -Allows to defeat a pending fraud challenge against a wallet if -the transaction that spends the UTXO follows the protocol rules. -In order to defeat the challenge the same `walletPublicKey` and -signature (represented by `r`, `s` and `v`) must be provided as -were used to calculate the sighash during input signing. -The fraud challenge defeat attempt will only succeed if the -inputs in the preimage are considered honestly spent by the -wallet. Therefore the transaction spending the UTXO must be -proven in the Bridge before a challenge defeat is called. -If successfully defeated, the fraud challenge is marked as -resolved and the amount of ether deposited by the challenger is -sent to the treasury. - -Requirements: -- `walletPublicKey` and `sighash` calculated as `hash256(preimage)` -must identify an open fraud challenge, -- the preimage must be a valid preimage of a transaction generated -according to the protocol rules and already proved in the Bridge, -- before a defeat attempt is made the transaction that spends the -given UTXO must be proven in the Bridge. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| self | struct BridgeState.Storage | | -| walletPublicKey | bytes | The public key of the wallet in the uncompressed and unprefixed format (64 bytes). | -| preimage | bytes | The preimage which produces sighash used to generate the ECDSA signature that is the subject of the fraud claim. It is a serialized subset of the transaction. The exact subset used as the preimage depends on the transaction input the signature is produced for. See BIP-143 for reference. | -| witness | bool | Flag indicating whether the preimage was produced for a witness input. True for witness, false for non-witness input. | - -### defeatFraudChallengeWithHeartbeat - -```solidity -function defeatFraudChallengeWithHeartbeat(struct BridgeState.Storage self, bytes walletPublicKey, bytes heartbeatMessage) external -``` - -Allows to defeat a pending fraud challenge against a wallet by -proving the sighash and signature were produced for an off-chain -wallet heartbeat message following a strict format. -In order to defeat the challenge the same `walletPublicKey` and -signature (represented by `r`, `s` and `v`) must be provided as -were used to calculate the sighash during heartbeat message -signing. The fraud challenge defeat attempt will only succeed if -the signed message follows a strict format required for -heartbeat messages. If successfully defeated, the fraud -challenge is marked as resolved and the amount of ether -deposited by the challenger is sent to the treasury. - -Requirements: -- `walletPublicKey` and `sighash` calculated as -`hash256(heartbeatMessage)` must identify an open fraud challenge, -- `heartbeatMessage` must follow a strict format of heartbeat -messages. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| self | struct BridgeState.Storage | | -| walletPublicKey | bytes | The public key of the wallet in the uncompressed and unprefixed format (64 bytes), | -| heartbeatMessage | bytes | Off-chain heartbeat message meeting the heartbeat message format requirements which produces sighash used to generate the ECDSA signature that is the subject of the fraud claim. | - -### resolveFraudChallenge - -```solidity -function resolveFraudChallenge(struct BridgeState.Storage self, bytes walletPublicKey, struct Fraud.FraudChallenge challenge, bytes32 sighash) internal -``` - -Called only for successfully defeated fraud challenges. -The fraud challenge is marked as resolved and the amount of -ether deposited by the challenger is sent to the treasury. - -Requirements: -- Must be called only for successfully defeated fraud challenges. - -### notifyFraudChallengeDefeatTimeout - -```solidity -function notifyFraudChallengeDefeatTimeout(struct BridgeState.Storage self, bytes walletPublicKey, uint32[] walletMembersIDs, bytes preimageSha256) external -``` - -Notifies about defeat timeout for the given fraud challenge. -Can be called only if there was a fraud challenge identified by -the provided `walletPublicKey` and `sighash` and it was not -defeated on time. The amount of time that needs to pass after -a fraud challenge is reported is indicated by the -`challengeDefeatTimeout`. After a successful fraud challenge -defeat timeout notification the fraud challenge is marked as -resolved, the stake of each operator is slashed, the ether -deposited is returned to the challenger and the challenger is -rewarded. - -Requirements: -- The wallet must be in the Live or MovingFunds or Closing or -Terminated state, -- The `walletPublicKey` and `sighash` calculated from -`preimageSha256` must identify an open fraud challenge, -- 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 of the `WalletRegistry` contract, -- The amount of time indicated by `challengeDefeatTimeout` must pass -after the challenge was reported. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| self | struct BridgeState.Storage | | -| walletPublicKey | bytes | The public key of the wallet in the uncompressed and unprefixed format (64 bytes). | -| walletMembersIDs | uint32[] | Identifiers of the wallet signing group members. | -| preimageSha256 | bytes | The hash that was generated by applying SHA-256 one time over the preimage used during input signing. The preimage is a serialized subset of the transaction and its structure depends on the transaction input (see BIP-143 for reference). Notice that applying SHA-256 over the `preimageSha256` results in `sighash`. The path from `preimage` to `sighash` looks like this: preimage -> (SHA-256) -> preimageSha256 -> (SHA-256) -> sighash. | - -### extractUtxoKeyFromWitnessPreimage - -```solidity -function extractUtxoKeyFromWitnessPreimage(bytes preimage) internal pure returns (uint256 utxoKey) -``` - -Extracts the UTXO keys from the given preimage used during -signing of a witness input. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| preimage | bytes | The preimage which produces sighash used to generate the ECDSA signature that is the subject of the fraud claim. It is a serialized subset of the transaction. The exact subset used as the preimage depends on the transaction input the signature is produced for. See BIP-143 for reference | - -#### Return Values - -| Name | Type | Description | -| ---- | ---- | ----------- | -| utxoKey | uint256 | UTXO key that identifies spent input. | - -### extractUtxoKeyFromNonWitnessPreimage - -```solidity -function extractUtxoKeyFromNonWitnessPreimage(bytes preimage) internal pure returns (uint256 utxoKey) -``` - -Extracts the UTXO key from the given preimage used during -signing of a non-witness input. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| preimage | bytes | The preimage which produces sighash used to generate the ECDSA signature that is the subject of the fraud claim. It is a serialized subset of the transaction. The exact subset used as the preimage depends on the transaction input the signature is produced for. See BIP-143 for reference. | - -#### Return Values - -| Name | Type | Description | -| ---- | ---- | ----------- | -| utxoKey | uint256 | UTXO key that identifies spent input. | - -### extractSighashType - -```solidity -function extractSighashType(bytes preimage) internal pure returns (uint32 sighashType) -``` - -Extracts the sighash type from the given preimage. - -Sighash type is stored as the last 4 bytes in the preimage (little -endian). - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| preimage | bytes | Serialized subset of the transaction. See BIP-143 for reference. | - -#### Return Values - -| Name | Type | Description | -| ---- | ---- | ----------- | -| sighashType | uint32 | Sighash type as a 32-bit integer. | - -## Heartbeat - -The library establishes expected format for heartbeat messages -signed by wallet ECDSA signing group. Heartbeat messages are -constructed in such a way that they can not be used as a Bitcoin -transaction preimages. - -The smallest Bitcoin non-coinbase transaction is a one spending an -OP_TRUE anyonecanspend output and creating 1 OP_TRUE anyonecanspend -output. Such a transaction has 61 bytes (see `BitcoinTx` documentation): -4 bytes for version -1 byte for tx_in_count -36 bytes for tx_in.previous_output -1 byte for tx_in.script_bytes (value: 0) -0 bytes for tx_in.signature_script -4 bytes for tx_in.sequence -1 byte for tx_out_count -8 bytes for tx_out.value -1 byte for tx_out.pk_script_bytes -1 byte for tx_out.pk_script -4 bytes for lock_time - -The smallest Bitcoin coinbase transaction is a one creating -1 OP_TRUE anyonecanspend output and having an empty coinbase script. -Such a transaction has 65 bytes: -4 bytes for version -1 byte for tx_in_count -32 bytes for tx_in.hash (all 0x00) -4 bytes for tx_in.index (all 0xff) -1 byte for tx_in.script_bytes (value: 0) -4 bytes for tx_in.height -0 byte for tx_in.coinbase_script -4 bytes for tx_in.sequence -1 byte for tx_out_count -8 bytes for tx_out.value -1 byte for tx_out.pk_script_bytes -1 byte for tx_out.pk_script -4 bytes for lock_time - -A SIGHASH flag is used to indicate which part of the transaction is -signed by the ECDSA signature. There are currently 3 flags: -SIGHASH_ALL, SIGHASH_NONE, SIGHASH_SINGLE, and different combinations -of these flags. - -No matter the SIGHASH flag and no matter the combination, the following -fields from the transaction are always included in the constructed -preimage: -4 bytes for version -36 bytes for tx_in.previous_output (or tx_in.hash + tx_in.index for coinbase) -4 bytes for lock_time - -Additionally, the last 4 bytes of the preimage determines the SIGHASH -flag. - -This is enough to say there is no way the preimage could be shorter -than 4 + 36 + 4 + 4 = 48 bytes. - -For this reason, we construct the heartbeat message, as a 16-byte -message. The first 8 bytes are 0xffffffffffffffff. The last 8 bytes -are for an arbitrary uint64, being a signed heartbeat nonce (for -example, the last Ethereum block hash). - -The message being signed by the wallet when executing the heartbeat -protocol should be Bitcoin's hash256 (double SHA-256) of the heartbeat -message: -heartbeat_sighash = hash256(heartbeat_message) - -### isValidHeartbeatMessage - -```solidity -function isValidHeartbeatMessage(bytes message) internal pure returns (bool) -``` - -Determines if the signed byte array is a valid, non-fraudulent -heartbeat message. - -Wallet heartbeat message must be exactly 16 bytes long with the first -8 bytes set to 0xffffffffffffffff. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| message | bytes | Message signed by the wallet. It is a potential heartbeat message, Bitcoin transaction preimage, or an arbitrary signed bytes. | - -#### Return Values - -| Name | Type | Description | -| ---- | ---- | ----------- | -| [0] | bool | True if valid heartbeat message, false otherwise. | - -## IRelay - -Contains only the methods needed by tBTC v2. The Bitcoin relay -provides the difficulty of the previous and current epoch. One -difficulty epoch spans 2016 blocks. - -### getCurrentEpochDifficulty - -```solidity -function getCurrentEpochDifficulty() external view returns (uint256) -``` - -Returns the difficulty of the current epoch. - -### getPrevEpochDifficulty - -```solidity -function getPrevEpochDifficulty() external view returns (uint256) -``` - -Returns the difficulty of the previous epoch. - -## MovingFunds - -The library handles the logic for moving Bitcoin between Bridge -wallets. - -A wallet that failed a heartbeat, did not process requested redemption -on time, or qualifies to be closed, begins the procedure of moving -funds to other wallets in the Bridge. The wallet needs to commit to -which other Live wallets it is moving the funds to and then, provide an -SPV proof of moving funds to the previously committed wallets. -Once the proof is submitted, all target wallets are supposed to -sweep the received UTXOs with their own main UTXOs in order to -update their BTC balances. - -### MovingFundsTxOutputsProcessingInfo - -```solidity -struct MovingFundsTxOutputsProcessingInfo { - bytes32 movingFundsTxHash; - bytes movingFundsTxOutputVector; -} -``` - -### MovedFundsSweepRequestState - -```solidity -enum MovedFundsSweepRequestState { - Unknown, - Pending, - Processed, - TimedOut -} -``` - -### MovedFundsSweepRequest - -```solidity -struct MovedFundsSweepRequest { - bytes20 walletPubKeyHash; - uint64 value; - uint32 createdAt; - enum MovingFunds.MovedFundsSweepRequestState state; -} -``` - -### MovingFundsCommitmentSubmitted - -```solidity -event MovingFundsCommitmentSubmitted(bytes20 walletPubKeyHash, bytes20[] targetWallets, address submitter) -``` - -### MovingFundsTimeoutReset - -```solidity -event MovingFundsTimeoutReset(bytes20 walletPubKeyHash) -``` - -### MovingFundsCompleted - -```solidity -event MovingFundsCompleted(bytes20 walletPubKeyHash, bytes32 movingFundsTxHash) -``` - -### MovingFundsTimedOut - -```solidity -event MovingFundsTimedOut(bytes20 walletPubKeyHash) -``` - -### MovingFundsBelowDustReported - -```solidity -event MovingFundsBelowDustReported(bytes20 walletPubKeyHash) -``` - -### MovedFundsSwept - -```solidity -event MovedFundsSwept(bytes20 walletPubKeyHash, bytes32 sweepTxHash) -``` - -### MovedFundsSweepTimedOut - -```solidity -event MovedFundsSweepTimedOut(bytes20 walletPubKeyHash, bytes32 movingFundsTxHash, uint32 movingFundsTxOutputIndex) -``` - -### submitMovingFundsCommitment - -```solidity -function submitMovingFundsCommitment(struct BridgeState.Storage self, bytes20 walletPubKeyHash, struct BitcoinTx.UTXO walletMainUtxo, uint32[] walletMembersIDs, uint256 walletMemberIndex, bytes20[] targetWallets) external -``` - -Submits the moving funds target wallets commitment. -Once all requirements are met, that function registers the -target wallets commitment and opens the way for moving funds -proof submission. - -Requirements: -- The source wallet must be in the MovingFunds state, -- The source wallet must not have pending redemption requests, -- The source wallet must not have pending moved funds sweep requests, -- The source wallet must not have submitted its commitment already, -- The expression `keccak256(abi.encode(walletMembersIDs))` must -be exactly the same as the hash stored under `membersIdsHash` -for the given source wallet in the ECDSA registry. 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], -- The caller must be the member of the source wallet signing group -at the position indicated by `walletMemberIndex` parameter, -- The `walletMainUtxo` components must point to the recent main -UTXO of the source wallet, as currently known on the Ethereum -chain, -- Source wallet BTC balance must be greater than zero, -- At least one Live wallet must exist in the system, -- Submitted target wallets count must match the expected count -`N = min(liveWalletsCount, ceil(walletBtcBalance / walletMaxBtcTransfer))` -where `N > 0`, -- Each target wallet must be not equal to the source wallet, -- Each target wallet must follow the expected order i.e. all -target wallets 20-byte public key hashes represented as numbers -must form a strictly increasing sequence without duplicates, -- Each target wallet must be in Live state. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| self | struct BridgeState.Storage | | -| walletPubKeyHash | bytes20 | 20-byte public key hash of the source wallet. | -| walletMainUtxo | struct BitcoinTx.UTXO | Data of the source wallet's main UTXO, as currently known on the Ethereum chain. | -| walletMembersIDs | uint32[] | Identifiers of the source wallet signing group members. | -| walletMemberIndex | uint256 | Position of the caller in the source wallet signing group members list. | -| targetWallets | bytes20[] | List of 20-byte public key hashes of the target wallets that the source wallet commits to move the funds to. | - -### resetMovingFundsTimeout - -```solidity -function resetMovingFundsTimeout(struct BridgeState.Storage self, bytes20 walletPubKeyHash) external -``` - -Resets the moving funds timeout for the given wallet if the -target wallet commitment cannot be submitted due to a lack -of live wallets in the system. - -Requirements: -- The wallet must be in the MovingFunds state, -- The target wallets commitment must not be already submitted for -the given moving funds wallet, -- Live wallets count must be zero, -- The moving funds timeout reset delay must be elapsed. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| self | struct BridgeState.Storage | | -| walletPubKeyHash | bytes20 | 20-byte public key hash of the moving funds wallet | - -### submitMovingFundsProof - -```solidity -function submitMovingFundsProof(struct BridgeState.Storage self, struct BitcoinTx.Info movingFundsTx, struct BitcoinTx.Proof movingFundsProof, struct BitcoinTx.UTXO mainUtxo, bytes20 walletPubKeyHash) external -``` - -Used by the wallet to prove the BTC moving funds transaction -and to make the necessary state changes. Moving funds is only -accepted if it satisfies SPV proof. - -The function validates the moving funds transaction structure -by checking if it actually spends the main UTXO of the declared -wallet and locks the value on the pre-committed target wallets -using a reasonable transaction fee. If all preconditions are -met, this functions closes the source wallet. - -It is possible to prove the given moving funds transaction only -one time. - -Requirements: -- `movingFundsTx` components must match the expected structure. See -`BitcoinTx.Info` docs for reference. Their values must exactly -correspond to appropriate Bitcoin transaction fields to produce -a provable transaction hash, -- The `movingFundsTx` should represent a Bitcoin transaction with -exactly 1 input that refers to the wallet's main UTXO. That -transaction should have 1..n outputs corresponding to the -pre-committed target wallets. Outputs must be ordered in the -same way as their corresponding target wallets are ordered -within the target wallets commitment, -- `movingFundsProof` components must match the expected structure. -See `BitcoinTx.Proof` docs for reference. The `bitcoinHeaders` -field must contain a valid number of block headers, not less -than the `txProofDifficultyFactor` contract constant, -- `mainUtxo` components must point to the recent main UTXO -of the given wallet, as currently known on the Ethereum chain. -Additionally, the recent main UTXO on Ethereum must be set, -- `walletPubKeyHash` must be connected with the main UTXO used -as transaction single input, -- The wallet that `walletPubKeyHash` points to must be in the -MovingFunds state, -- The target wallets commitment must be submitted by the wallet -that `walletPubKeyHash` points to, -- The total Bitcoin transaction fee must be lesser or equal -to `movingFundsTxMaxTotalFee` governable parameter. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| self | struct BridgeState.Storage | | -| movingFundsTx | struct BitcoinTx.Info | Bitcoin moving funds transaction data. | -| movingFundsProof | struct BitcoinTx.Proof | Bitcoin moving funds proof data. | -| mainUtxo | struct BitcoinTx.UTXO | Data of the wallet's main UTXO, as currently known on the Ethereum chain. | -| walletPubKeyHash | bytes20 | 20-byte public key hash (computed using Bitcoin HASH160 over the compressed ECDSA public key) of the wallet which performed the moving funds transaction. | - -### processMovingFundsTxOutputs - -```solidity -function processMovingFundsTxOutputs(struct BridgeState.Storage self, struct MovingFunds.MovingFundsTxOutputsProcessingInfo processInfo) internal returns (bytes32 targetWalletsHash, uint256 outputsTotalValue) -``` - -Processes the moving funds Bitcoin transaction output vector -and extracts information required for further processing. - -Requirements: -- The `movingFundsTxOutputVector` must be parseable, i.e. must -be validated by the caller as stated in their parameter doc, -- Each output must refer to a 20-byte public key hash, -- The total outputs value must be evenly divided over all outputs. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| self | struct BridgeState.Storage | | -| processInfo | struct MovingFunds.MovingFundsTxOutputsProcessingInfo | Processing info containing the moving funds tx hash and output vector. | - -#### Return Values - -| Name | Type | Description | -| ---- | ---- | ----------- | -| targetWalletsHash | bytes32 | keccak256 hash over the list of actual target wallets used in the transaction. | -| outputsTotalValue | uint256 | Sum of all outputs values. | - -### notifyMovingFundsTimeout - -```solidity -function notifyMovingFundsTimeout(struct BridgeState.Storage self, bytes20 walletPubKeyHash, uint32[] walletMembersIDs) external -``` - -Notifies about a timed out moving funds process. Terminates -the wallet and slashes signing group members as a result. - -Requirements: -- The wallet must be in the MovingFunds state, -- The moving funds timeout must be actually exceeded, -- 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 of the `WalletRegistry` contract. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| self | struct BridgeState.Storage | | -| walletPubKeyHash | bytes20 | 20-byte public key hash of the wallet. | -| walletMembersIDs | uint32[] | Identifiers of the wallet signing group members. | - -### notifyMovingFundsBelowDust - -```solidity -function notifyMovingFundsBelowDust(struct BridgeState.Storage self, bytes20 walletPubKeyHash, struct BitcoinTx.UTXO mainUtxo) external -``` - -Notifies about a moving funds wallet whose BTC balance is -below the moving funds dust threshold. Ends the moving funds -process and begins wallet closing immediately. - -Requirements: -- The wallet must be in the MovingFunds state, -- The `mainUtxo` components must point to the recent main UTXO -of the given wallet, as currently known on the Ethereum chain. -If the wallet has no main UTXO, this parameter can be empty as it -is ignored, -- The wallet BTC balance must be below the moving funds threshold. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| self | struct BridgeState.Storage | | -| walletPubKeyHash | bytes20 | 20-byte public key hash of the wallet. | -| mainUtxo | struct BitcoinTx.UTXO | Data of the wallet's main UTXO, as currently known on the Ethereum chain. | - -### submitMovedFundsSweepProof - -```solidity -function submitMovedFundsSweepProof(struct BridgeState.Storage self, struct BitcoinTx.Info sweepTx, struct BitcoinTx.Proof sweepProof, struct BitcoinTx.UTXO mainUtxo) external -``` - -Used by the wallet to prove the BTC moved funds sweep -transaction and to make the necessary state changes. Moved -funds sweep is only accepted if it satisfies SPV proof. - -The function validates the sweep transaction structure by -checking if it actually spends the moved funds UTXO and the -sweeping wallet's main UTXO (optionally), and if it locks the -value on the sweeping wallet's 20-byte public key hash using a -reasonable transaction fee. If all preconditions are -met, this function updates the sweeping wallet main UTXO, thus -their BTC balance. - -It is possible to prove the given sweep transaction only -one time. - -Requirements: -- `sweepTx` components must match the expected structure. See -`BitcoinTx.Info` docs for reference. Their values must exactly -correspond to appropriate Bitcoin transaction fields to produce -a provable transaction hash, -- The `sweepTx` should represent a Bitcoin transaction with -the first input pointing to a wallet's sweep Pending request and, -optionally, the second input pointing to the wallet's main UTXO, -if the sweeping wallet has a main UTXO set. There should be only -one output locking funds on the sweeping wallet 20-byte public -key hash, -- `sweepProof` components must match the expected structure. -See `BitcoinTx.Proof` docs for reference. The `bitcoinHeaders` -field must contain a valid number of block headers, not less -than the `txProofDifficultyFactor` contract constant, -- `mainUtxo` components must point to the recent main UTXO -of the sweeping wallet, as currently known on the Ethereum chain. -If there is no main UTXO, this parameter is ignored, -- The sweeping wallet must be in the Live or MovingFunds state, -- The total Bitcoin transaction fee must be lesser or equal -to `movedFundsSweepTxMaxTotalFee` governable parameter. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| self | struct BridgeState.Storage | | -| sweepTx | struct BitcoinTx.Info | Bitcoin sweep funds transaction data. | -| sweepProof | struct BitcoinTx.Proof | Bitcoin sweep funds proof data. | -| mainUtxo | struct BitcoinTx.UTXO | Data of the sweeping wallet's main UTXO, as currently known on the Ethereum chain. | - -### processMovedFundsSweepTxOutput - -```solidity -function processMovedFundsSweepTxOutput(struct BridgeState.Storage self, bytes sweepTxOutputVector) internal view returns (bytes20 walletPubKeyHash, uint64 value) -``` - -Processes the Bitcoin moved funds sweep transaction output vector -by extracting the single output and using it to gain additional -information required for further processing (e.g. value and -wallet public key hash). - -Requirements: -- Output vector must contain only one output, -- The single output must be of P2PKH or P2WPKH type and lock the -funds on a 20-byte public key hash. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| self | struct BridgeState.Storage | | -| sweepTxOutputVector | bytes | Bitcoin moved funds sweep transaction output vector. This function assumes vector's structure is valid so it must be validated using e.g. `BTCUtils.validateVout` function before it is passed here. | - -#### Return Values - -| Name | Type | Description | -| ---- | ---- | ----------- | -| walletPubKeyHash | bytes20 | 20-byte wallet public key hash. | -| value | uint64 | 8-byte moved funds sweep transaction output value. | - -### resolveMovedFundsSweepingWallet - -```solidity -function resolveMovedFundsSweepingWallet(struct BridgeState.Storage self, bytes20 walletPubKeyHash, struct BitcoinTx.UTXO mainUtxo) internal view returns (struct Wallets.Wallet wallet, struct BitcoinTx.UTXO resolvedMainUtxo) -``` - -Resolves sweeping wallet based on the provided wallet public key -hash. Validates the wallet state and current main UTXO, as -currently known on the Ethereum chain. - -Requirements: -- Sweeping wallet must be either in Live or MovingFunds state, -- If the main UTXO of the sweeping wallet exists in the storage, -the passed `mainUTXO` parameter must be equal to the stored one. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| self | struct BridgeState.Storage | | -| walletPubKeyHash | bytes20 | public key hash of the wallet proving the sweep Bitcoin transaction. | -| mainUtxo | struct BitcoinTx.UTXO | Data of the wallet's main UTXO, as currently known on the Ethereum chain. If no main UTXO exists for the given wallet, this parameter is ignored. | - -#### Return Values - -| Name | Type | Description | -| ---- | ---- | ----------- | -| wallet | struct Wallets.Wallet | Data of the sweeping wallet. | -| resolvedMainUtxo | struct BitcoinTx.UTXO | The actual main UTXO of the sweeping wallet resolved by cross-checking the `mainUtxo` parameter with the chain state. If the validation went well, this is the plain-text main UTXO corresponding to the `wallet.mainUtxoHash`. | - -### processMovedFundsSweepTxInputs - -```solidity -function processMovedFundsSweepTxInputs(struct BridgeState.Storage self, bytes sweepTxInputVector, struct BitcoinTx.UTXO mainUtxo, bytes20 walletPubKeyHash) internal returns (uint256 inputsTotalValue) -``` - -Processes the Bitcoin moved funds sweep transaction input vector. -It extracts the first input and tries to match it with one of -the moved funds sweep requests targeting the sweeping wallet. -If the sweep request is an existing Pending request, this -function marks it as Processed. If the sweeping wallet has a -main UTXO, this function extracts the second input, makes sure -it refers to the wallet main UTXO, and marks that main UTXO as -correctly spent. - -Requirements: -- The input vector must consist of one mandatory and one optional -input, -- The mandatory input must be the first input in the vector, -- The mandatory input must point to a Pending moved funds sweep -request that is targeted to the sweeping wallet, -- The optional output must be the second input in the vector, -- The optional input is required if the sweeping wallet has a -main UTXO (i.e. the `mainUtxo` is not zeroed). In that case, -that input must point the the sweeping wallet main UTXO. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| self | struct BridgeState.Storage | | -| sweepTxInputVector | bytes | Bitcoin moved funds sweep transaction input vector. This function assumes vector's structure is valid so it must be validated using e.g. `BTCUtils.validateVin` function before it is passed here. | -| mainUtxo | struct BitcoinTx.UTXO | Data of the sweeping wallet's main UTXO. If no main UTXO exists for the given the wallet, this parameter's fields should be zeroed to bypass the main UTXO validation. | -| walletPubKeyHash | bytes20 | 20-byte public key hash of the sweeping wallet. | - -#### Return Values - -| Name | Type | Description | -| ---- | ---- | ----------- | -| inputsTotalValue | uint256 | Total inputs value sum. | - -### parseMovedFundsSweepTxInputAt - -```solidity -function parseMovedFundsSweepTxInputAt(bytes inputVector, uint256 inputStartingIndex) internal pure returns (bytes32 outpointTxHash, uint32 outpointIndex, uint256 inputLength) -``` - -Parses a Bitcoin transaction input starting at the given index. - -This function assumes vector's structure is valid so it must be -validated using e.g. `BTCUtils.validateVin` function before it -is passed here. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| inputVector | bytes | Bitcoin transaction input vector. | -| inputStartingIndex | uint256 | Index the given input starts at. | - -#### Return Values - -| Name | Type | Description | -| ---- | ---- | ----------- | -| outpointTxHash | bytes32 | 32-byte hash of the Bitcoin transaction which is pointed in the given input's outpoint. | -| outpointIndex | uint32 | 4-byte index of the Bitcoin transaction output which is pointed in the given input's outpoint. | -| inputLength | uint256 | Byte length of the given input. | - -### notifyMovedFundsSweepTimeout - -```solidity -function notifyMovedFundsSweepTimeout(struct BridgeState.Storage self, bytes32 movingFundsTxHash, uint32 movingFundsTxOutputIndex, uint32[] walletMembersIDs) external -``` - -Notifies about a timed out moved funds sweep process. If the -wallet is not terminated yet, that function terminates -the wallet and slashes signing group members as a result. -Marks the given sweep request as TimedOut. - -Requirements: -- The moved funds sweep request must be in the Pending state, -- The moved funds sweep timeout must be actually exceeded, -- The wallet must be either in the Live or MovingFunds or -Terminated state,, -- 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 of the `WalletRegistry` contract. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| self | struct BridgeState.Storage | | -| movingFundsTxHash | bytes32 | 32-byte hash of the moving funds transaction that caused the sweep request to be created. | -| movingFundsTxOutputIndex | uint32 | Index of the moving funds transaction output that is subject of the sweep request. | -| walletMembersIDs | uint32[] | Identifiers of the wallet signing group members. | - -## OutboundTx - -Aggregates functions common to the redemption transaction proof -validation and to the moving funds transaction proof validation. - -### processWalletOutboundTxInput - -```solidity -function processWalletOutboundTxInput(struct BridgeState.Storage self, bytes walletOutboundTxInputVector, struct BitcoinTx.UTXO mainUtxo) internal -``` - -Checks whether an outbound Bitcoin transaction performed from -the given wallet has an input vector that contains a single -input referring to the wallet's main UTXO. Marks that main UTXO -as correctly spent if the validation succeeds. Reverts otherwise. -There are two outbound transactions from a wallet possible: a -redemption transaction or a moving funds to another wallet -transaction. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| self | struct BridgeState.Storage | | -| walletOutboundTxInputVector | bytes | Bitcoin outbound transaction's input vector. This function assumes vector's structure is valid so it must be validated using e.g. `BTCUtils.validateVin` function before it is passed here. | -| mainUtxo | struct BitcoinTx.UTXO | Data of the wallet's main UTXO, as currently known on the Ethereum chain. | - -### parseWalletOutboundTxInput - -```solidity -function parseWalletOutboundTxInput(bytes walletOutboundTxInputVector) internal pure returns (bytes32 outpointTxHash, uint32 outpointIndex) -``` - -Parses the input vector of an outbound Bitcoin transaction -performed from the given wallet. It extracts the single input -then the transaction hash and output index from its outpoint. -There are two outbound transactions from a wallet possible: a -redemption transaction or a moving funds to another wallet -transaction. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| walletOutboundTxInputVector | bytes | Bitcoin outbound transaction input vector. This function assumes vector's structure is valid so it must be validated using e.g. `BTCUtils.validateVin` function before it is passed here. | - -#### Return Values - -| Name | Type | Description | -| ---- | ---- | ----------- | -| outpointTxHash | bytes32 | 32-byte hash of the Bitcoin transaction which is pointed in the input's outpoint. | -| outpointIndex | uint32 | 4-byte index of the Bitcoin transaction output which is pointed in the input's outpoint. | - -## Redemption - -The library handles the logic for redeeming Bitcoin balances from -the Bridge. - -To initiate a redemption, a user with a Bank balance supplies -a Bitcoin address. Then, the system calculates the redemption fee, and -releases balance to the provided Bitcoin address. Just like in case of -sweeps of revealed deposits, redemption requests are processed in -batches and require SPV proof to be submitted to the Bridge. - -### RedemptionRequest - -```solidity -struct RedemptionRequest { - address redeemer; - uint64 requestedAmount; - uint64 treasuryFee; - uint64 txMaxFee; - uint32 requestedAt; -} -``` - -### RedemptionTxOutputsInfo - -```solidity -struct RedemptionTxOutputsInfo { - uint256 outputsTotalValue; - uint64 totalBurnableValue; - uint64 totalTreasuryFee; - uint32 changeIndex; - uint64 changeValue; -} -``` - -### RedemptionTxOutputsProcessingInfo - -```solidity -struct RedemptionTxOutputsProcessingInfo { - uint256 outputStartingIndex; - uint256 outputsCount; - bytes32 walletP2PKHScriptKeccak; - bytes32 walletP2WPKHScriptKeccak; -} -``` - -### RedemptionRequested - -```solidity -event RedemptionRequested(bytes20 walletPubKeyHash, bytes redeemerOutputScript, address redeemer, uint64 requestedAmount, uint64 treasuryFee, uint64 txMaxFee) -``` - -### RedemptionsCompleted - -```solidity -event RedemptionsCompleted(bytes20 walletPubKeyHash, bytes32 redemptionTxHash) -``` - -### RedemptionTimedOut - -```solidity -event RedemptionTimedOut(bytes20 walletPubKeyHash, bytes redeemerOutputScript) -``` - -### requestRedemption - -```solidity -function requestRedemption(struct BridgeState.Storage self, bytes20 walletPubKeyHash, struct BitcoinTx.UTXO mainUtxo, address balanceOwner, bytes redeemerOutputScript, uint64 amount) external -``` - -Requests redemption of the given amount from the specified -wallet to the redeemer Bitcoin output script. -This function handles the simplest case, where balance owner is -the redeemer. - -Requirements: -- Wallet behind `walletPubKeyHash` must be live, -- `mainUtxo` components must point to the recent main UTXO -of the given wallet, as currently known on the Ethereum chain, -- `redeemerOutputScript` must be a proper Bitcoin script, -- `redeemerOutputScript` cannot have wallet PKH as payload, -- `amount` must be above or equal the `redemptionDustThreshold`, -- Given `walletPubKeyHash` and `redeemerOutputScript` pair can be -used for only one pending request at the same time, -- Wallet must have enough Bitcoin balance to proceed the request, -- Balance owner must make an allowance in the Bank that the Bridge -contract can spend the given `amount`. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| self | struct BridgeState.Storage | | -| walletPubKeyHash | bytes20 | The 20-byte wallet public key hash (computed using Bitcoin HASH160 over the compressed ECDSA public key). | -| mainUtxo | struct BitcoinTx.UTXO | Data of the wallet's main UTXO, as currently known on the Ethereum chain. | -| balanceOwner | address | The address of the Bank balance owner whose balance is getting redeemed. Balance owner address is stored as a redeemer address who will be able co claim back the Bank balance if anything goes wrong during the redemption. | -| redeemerOutputScript | bytes | The redeemer's length-prefixed output script (P2PKH, P2WPKH, P2SH or P2WSH) that will be used to lock redeemed BTC. | -| amount | uint64 | Requested amount in satoshi. This is also the Bank balance that is taken from the `balanceOwner` upon request. Once the request is handled, the actual amount of BTC locked on the redeemer output script will be always lower than this value since the treasury and Bitcoin transaction fees must be incurred. The minimal amount satisfying the request can be computed as: `amount - (amount / redemptionTreasuryFeeDivisor) - redemptionTxMaxFee`. Fees values are taken at the moment of request creation. | - -### requestRedemption - -```solidity -function requestRedemption(struct BridgeState.Storage self, address balanceOwner, uint64 amount, bytes redemptionData) external -``` - -Requests redemption of the given amount from the specified -wallet to the redeemer Bitcoin output script. Used by -`Bridge.receiveBalanceApproval`. Can handle more complex cases -where balance owner may be someone else than the redeemer. - -Requirements: -- Wallet behind `walletPubKeyHash` must be live, -- `mainUtxo*` components must point to the recent main UTXO -of the given wallet, as currently known on the Ethereum chain, -- `redeemerOutputScript` must be a proper Bitcoin script, -- `redeemerOutputScript` cannot have wallet PKH as payload, -- `amount` must be above or equal the `redemptionDustThreshold`, -- Given `walletPubKeyHash` and `redeemerOutputScript` pair can be -used for only one pending request at the same time, -- Wallet must have enough Bitcoin balance to proceed the request, -- Balance owner must make an allowance in the Bank that the Bridge -contract can spend the given `amount`. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| self | struct BridgeState.Storage | | -| balanceOwner | address | The address of the Bank balance owner whose balance is getting redeemed. | -| amount | uint64 | Requested amount in satoshi. This is also the Bank balance that is taken from the `balanceOwner` upon request. Once the request is handled, the actual amount of BTC locked on the redeemer output script will be always lower than this value since the treasury and Bitcoin transaction fees must be incurred. The minimal amount satisfying the request can be computed as: `amount - (amount / redemptionTreasuryFeeDivisor) - redemptionTxMaxFee`. Fees values are taken at the moment of request creation. | -| redemptionData | bytes | ABI-encoded redemption data: [ address redeemer, bytes20 walletPubKeyHash, bytes32 mainUtxoTxHash, uint32 mainUtxoTxOutputIndex, uint64 mainUtxoTxOutputValue, bytes redeemerOutputScript ] - redeemer: The Ethereum address of the redeemer who will be able to claim Bank balance if anything goes wrong during the redemption. In the most basic case, when someone redeems their Bitcoin balance from the Bank, `balanceOwner` is the same as `redeemer`. However, when a Vault is redeeming part of its balance for some redeemer address (for example, someone who has earlier deposited into that Vault), `balanceOwner` is the Vault, and `redeemer` is the address for which the vault is redeeming its balance to, - walletPubKeyHash: The 20-byte wallet public key hash (computed using Bitcoin HASH160 over the compressed ECDSA public key), - mainUtxoTxHash: Data of the wallet's main UTXO TX hash, as currently known on the Ethereum chain, - mainUtxoTxOutputIndex: Data of the wallet's main UTXO output index, as currently known on Ethereum chain, - mainUtxoTxOutputValue: Data of the wallet's main UTXO output value, as currently known on Ethereum chain, - redeemerOutputScript The redeemer's length-prefixed output script (P2PKH, P2WPKH, P2SH or P2WSH) that will be used to lock redeemed BTC. | - -### requestRedemption - -```solidity -function requestRedemption(struct BridgeState.Storage self, bytes20 walletPubKeyHash, struct BitcoinTx.UTXO mainUtxo, address balanceOwner, address redeemer, bytes redeemerOutputScript, uint64 amount) internal -``` - -Requests redemption of the given amount from the specified -wallet to the redeemer Bitcoin output script. - -Requirements: -- Wallet behind `walletPubKeyHash` must be live, -- `mainUtxo` components must point to the recent main UTXO -of the given wallet, as currently known on the Ethereum chain, -- `redeemerOutputScript` must be a proper Bitcoin script, -- `redeemerOutputScript` cannot have wallet PKH as payload, -- `amount` must be above or equal the `redemptionDustThreshold`, -- Given `walletPubKeyHash` and `redeemerOutputScript` pair can be -used for only one pending request at the same time, -- Wallet must have enough Bitcoin balance to proceed the request, -- Balance owner must make an allowance in the Bank that the Bridge -contract can spend the given `amount`. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| self | struct BridgeState.Storage | | -| walletPubKeyHash | bytes20 | The 20-byte wallet public key hash (computed using Bitcoin HASH160 over the compressed ECDSA public key). | -| mainUtxo | struct BitcoinTx.UTXO | Data of the wallet's main UTXO, as currently known on the Ethereum chain. | -| balanceOwner | address | The address of the Bank balance owner whose balance is getting redeemed. | -| redeemer | address | The Ethereum address of the redeemer who will be able to claim Bank balance if anything goes wrong during the redemption. In the most basic case, when someone redeems their Bitcoin balance from the Bank, `balanceOwner` is the same as `redeemer`. However, when a Vault is redeeming part of its balance for some redeemer address (for example, someone who has earlier deposited into that Vault), `balanceOwner` is the Vault, and `redeemer` is the address for which the vault is redeeming its balance to. | -| redeemerOutputScript | bytes | The redeemer's length-prefixed output script (P2PKH, P2WPKH, P2SH or P2WSH) that will be used to lock redeemed BTC. | -| amount | uint64 | Requested amount in satoshi. This is also the Bank balance that is taken from the `balanceOwner` upon request. Once the request is handled, the actual amount of BTC locked on the redeemer output script will be always lower than this value since the treasury and Bitcoin transaction fees must be incurred. The minimal amount satisfying the request can be computed as: `amount - (amount / redemptionTreasuryFeeDivisor) - redemptionTxMaxFee`. Fees values are taken at the moment of request creation. | - -### submitRedemptionProof - -```solidity -function submitRedemptionProof(struct BridgeState.Storage self, struct BitcoinTx.Info redemptionTx, struct BitcoinTx.Proof redemptionProof, struct BitcoinTx.UTXO mainUtxo, bytes20 walletPubKeyHash) external -``` - -Used by the wallet to prove the BTC redemption transaction -and to make the necessary bookkeeping. Redemption is only -accepted if it satisfies SPV proof. - -The function is performing Bank balance updates by burning -the total redeemed Bitcoin amount from Bridge balance and -transferring the treasury fee sum to the treasury address. - -It is possible to prove the given redemption only one time. - -Requirements: -- `redemptionTx` components must match the expected structure. See -`BitcoinTx.Info` docs for reference. Their values must exactly -correspond to appropriate Bitcoin transaction fields to produce -a provable transaction hash, -- The `redemptionTx` should represent a Bitcoin transaction with -exactly 1 input that refers to the wallet's main UTXO. That -transaction should have 1..n outputs handling existing pending -redemption requests or pointing to reported timed out requests. -There can be also 1 optional output representing the -change and pointing back to the 20-byte wallet public key hash. -The change should be always present if the redeemed value sum -is lower than the total wallet's BTC balance, -- `redemptionProof` components must match the expected structure. -See `BitcoinTx.Proof` docs for reference. The `bitcoinHeaders` -field must contain a valid number of block headers, not less -than the `txProofDifficultyFactor` contract constant, -- `mainUtxo` components must point to the recent main UTXO -of the given wallet, as currently known on the Ethereum chain. -Additionally, the recent main UTXO on Ethereum must be set, -- `walletPubKeyHash` must be connected with the main UTXO used -as transaction single input. -Other remarks: -- Putting the change output as the first transaction output can -save some gas because the output processing loop begins each -iteration by checking whether the given output is the change -thus uses some gas for making the comparison. Once the change -is identified, that check is omitted in further iterations. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| self | struct BridgeState.Storage | | -| redemptionTx | struct BitcoinTx.Info | Bitcoin redemption transaction data. | -| redemptionProof | struct BitcoinTx.Proof | Bitcoin redemption proof data. | -| mainUtxo | struct BitcoinTx.UTXO | Data of the wallet's main UTXO, as currently known on the Ethereum chain. | -| walletPubKeyHash | bytes20 | 20-byte public key hash (computed using Bitcoin HASH160 over the compressed ECDSA public key) of the wallet which performed the redemption transaction. | - -### resolveRedeemingWallet - -```solidity -function resolveRedeemingWallet(struct BridgeState.Storage self, bytes20 walletPubKeyHash, struct BitcoinTx.UTXO mainUtxo) internal view returns (struct Wallets.Wallet wallet) -``` - -Resolves redeeming wallet based on the provided wallet public -key hash. Validates the wallet state and current main UTXO, as -currently known on the Ethereum chain. - -Requirements: -- Sweeping wallet must be either in Live or MovingFunds state, -- Main UTXO of the redeeming wallet must exists in the storage, -- The passed `mainUTXO` parameter must be equal to the stored one. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| self | struct BridgeState.Storage | | -| walletPubKeyHash | bytes20 | public key hash of the wallet proving the sweep Bitcoin transaction. | -| mainUtxo | struct BitcoinTx.UTXO | Data of the wallet's main UTXO, as currently known on the Ethereum chain. | - -#### Return Values - -| Name | Type | Description | -| ---- | ---- | ----------- | -| wallet | struct Wallets.Wallet | Data of the sweeping wallet. | - -### processRedemptionTxOutputs - -```solidity -function processRedemptionTxOutputs(struct BridgeState.Storage self, bytes redemptionTxOutputVector, bytes20 walletPubKeyHash) internal returns (struct Redemption.RedemptionTxOutputsInfo info) -``` - -Processes the Bitcoin redemption transaction output vector. -It extracts each output and tries to identify it as a pending -redemption request, reported timed out request, or change. -Reverts if one of the outputs cannot be recognized properly. -This function also marks each request as processed by removing -them from `pendingRedemptions` mapping. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| self | struct BridgeState.Storage | | -| redemptionTxOutputVector | bytes | Bitcoin redemption transaction output vector. This function assumes vector's structure is valid so it must be validated using e.g. `BTCUtils.validateVout` function before it is passed here. | -| walletPubKeyHash | bytes20 | 20-byte public key hash (computed using Bitcoin HASH160 over the compressed ECDSA public key) of the wallet which performed the redemption transaction. | - -#### Return Values - -| Name | Type | Description | -| ---- | ---- | ----------- | -| info | struct Redemption.RedemptionTxOutputsInfo | Outcomes of the processing. | - -### processRedemptionTxOutputs - -```solidity -function processRedemptionTxOutputs(struct BridgeState.Storage self, bytes redemptionTxOutputVector, bytes20 walletPubKeyHash, struct Redemption.RedemptionTxOutputsProcessingInfo processInfo) internal returns (struct Redemption.RedemptionTxOutputsInfo resultInfo) -``` - -Processes all outputs from the redemption transaction. Tries to -identify output as a change output, pending redemption request -or reported redemption. Reverts if one of the outputs cannot be -recognized properly. Marks each request as processed by removing -them from `pendingRedemptions` mapping. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| self | struct BridgeState.Storage | | -| redemptionTxOutputVector | bytes | Bitcoin redemption transaction output vector. This function assumes vector's structure is valid so it must be validated using e.g. `BTCUtils.validateVout` function before it is passed here. | -| walletPubKeyHash | bytes20 | 20-byte public key hash (computed using Bitcoin HASH160 over the compressed ECDSA public key) of the wallet which performed the redemption transaction. | -| processInfo | struct Redemption.RedemptionTxOutputsProcessingInfo | RedemptionTxOutputsProcessingInfo identifying output starting index, the number of outputs and possible wallet change P2PKH and P2WPKH scripts. | - -### processNonChangeRedemptionTxOutput - -```solidity -function processNonChangeRedemptionTxOutput(struct BridgeState.Storage self, uint256 redemptionKey, uint64 outputValue) internal returns (uint64 burnableValue, uint64 treasuryFee) -``` - -Processes a single redemption transaction output. Tries to -identify output as a pending redemption request or reported -redemption timeout. Output script passed to this function must -not be the change output. Such output needs to be identified -separately before calling this function. -Reverts if output is neither requested pending redemption nor -requested and reported timed-out redemption. -This function also marks each pending request as processed by -removing them from `pendingRedemptions` mapping. - -Requirements: -- This function should be called only if the given output -represents redemption. It must not be the change output. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| self | struct BridgeState.Storage | | -| redemptionKey | uint256 | Redemption key of the output being processed. | -| outputValue | uint64 | Value of the output being processed. | - -#### Return Values - -| Name | Type | Description | -| ---- | ---- | ----------- | -| burnableValue | uint64 | The value burnable as a result of processing this single redemption output. This value needs to be summed up with burnable values of all other outputs to evaluate total burnable value for the entire redemption transaction. This value is 0 for a timed-out redemption request. | -| treasuryFee | uint64 | The treasury fee from this single redemption output. This value needs to be summed up with treasury fees of all other outputs to evaluate the total treasury fee for the entire redemption transaction. This value is 0 for a timed-out redemption request. | - -### notifyRedemptionTimeout - -```solidity -function notifyRedemptionTimeout(struct BridgeState.Storage self, bytes20 walletPubKeyHash, uint32[] walletMembersIDs, bytes redeemerOutputScript) external -``` - -Notifies that there is a pending redemption request associated -with the given wallet, that has timed out. The redemption -request is identified by the key built as -`keccak256(keccak256(redeemerOutputScript) | walletPubKeyHash)`. -The results of calling this function: -- the pending redemptions value for the wallet will be decreased -by the requested amount (minus treasury fee), -- the tokens taken from the redeemer on redemption request will -be returned to the redeemer, -- the request will be moved from pending redemptions to -timed-out redemptions, -- if the state of the wallet is `Live` or `MovingFunds`, the -wallet operators will be slashed and the notifier will be -rewarded, -- if the state of wallet is `Live`, the wallet will be closed or -marked as `MovingFunds` (depending on the presence or absence -of the wallet's main UTXO) and the wallet will no longer be -marked as the active wallet (if it was marked as such). - -Requirements: -- The wallet must be in the Live or MovingFunds or Terminated state, -- The redemption request identified by `walletPubKeyHash` and -`redeemerOutputScript` must exist, -- 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 of the `WalletRegistry` contract, -- The amount of time defined by `redemptionTimeout` must have -passed since the redemption was requested (the request must be -timed-out). - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| self | struct BridgeState.Storage | | -| walletPubKeyHash | bytes20 | 20-byte public key hash of the wallet. | -| walletMembersIDs | uint32[] | Identifiers of the wallet signing group members. | -| redeemerOutputScript | bytes | The redeemer's length-prefixed output script (P2PKH, P2WPKH, P2SH or P2WSH). | - -### getRedemptionKey - -```solidity -function getRedemptionKey(bytes20 walletPubKeyHash, bytes script) internal pure returns (uint256) -``` - -Calculate redemption key without allocations. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| walletPubKeyHash | bytes20 | the pubkey hash of the wallet. | -| script | bytes | the output script of the redemption. | - -#### Return Values - -| Name | Type | Description | -| ---- | ---- | ----------- | -| [0] | uint256 | The key = keccak256(keccak256(script) | walletPubKeyHash). | - -### _getRedemptionKey - -```solidity -function _getRedemptionKey(bytes20 walletPubKeyHash, bytes32 scriptHash) internal pure returns (uint256) -``` - -Finish calculating redemption key without allocations. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| walletPubKeyHash | bytes20 | the pubkey hash of the wallet. | -| scriptHash | bytes32 | the output script hash of the redemption. | - -#### Return Values - -| Name | Type | Description | -| ---- | ---- | ----------- | -| [0] | uint256 | The key = keccak256(scriptHash | walletPubKeyHash). | - -## Wallets - -Library responsible for handling integration between Bridge -contract and ECDSA wallets. - -### WalletState - -```solidity -enum WalletState { - Unknown, - Live, - MovingFunds, - Closing, - Closed, - Terminated -} -``` - -### Wallet - -```solidity -struct Wallet { - bytes32 ecdsaWalletID; - bytes32 mainUtxoHash; - uint64 pendingRedemptionsValue; - uint32 createdAt; - uint32 movingFundsRequestedAt; - uint32 closingStartedAt; - uint32 pendingMovedFundsSweepRequestsCount; - enum Wallets.WalletState state; - bytes32 movingFundsTargetWalletsCommitmentHash; -} -``` - -### NewWalletRequested - -```solidity -event NewWalletRequested() -``` - -### NewWalletRegistered - -```solidity -event NewWalletRegistered(bytes32 ecdsaWalletID, bytes20 walletPubKeyHash) -``` - -### WalletMovingFunds - -```solidity -event WalletMovingFunds(bytes32 ecdsaWalletID, bytes20 walletPubKeyHash) -``` - -### WalletClosing - -```solidity -event WalletClosing(bytes32 ecdsaWalletID, bytes20 walletPubKeyHash) -``` - -### WalletClosed - -```solidity -event WalletClosed(bytes32 ecdsaWalletID, bytes20 walletPubKeyHash) -``` - -### WalletTerminated - -```solidity -event WalletTerminated(bytes32 ecdsaWalletID, bytes20 walletPubKeyHash) -``` - -### requestNewWallet - -```solidity -function requestNewWallet(struct BridgeState.Storage self, struct BitcoinTx.UTXO activeWalletMainUtxo) external -``` - -Requests creation of a new wallet. This function just -forms a request and the creation process is performed -asynchronously. Outcome of that process should be delivered -using `registerNewWallet` function. - -Requirements: -- `activeWalletMainUtxo` components must point to the recent main -UTXO of the given active wallet, as currently known on the -Ethereum chain. If there is no active wallet at the moment, or -the active wallet has no main UTXO, this parameter can be -empty as it is ignored, -- Wallet creation must not be in progress, -- If the active wallet is set, one of the following -conditions must be true: -- The active wallet BTC balance is above the minimum threshold -and the active wallet is old enough, i.e. the creation period -was elapsed since its creation time, -- The active wallet BTC balance is above the maximum threshold. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| self | struct BridgeState.Storage | | -| activeWalletMainUtxo | struct BitcoinTx.UTXO | Data of the active wallet's main UTXO, as currently known on the Ethereum chain. | - -### registerNewWallet - -```solidity -function registerNewWallet(struct BridgeState.Storage self, bytes32 ecdsaWalletID, bytes32 publicKeyX, bytes32 publicKeyY) external -``` - -Registers a new wallet. This function should be called -after the wallet creation process initiated using -`requestNewWallet` completes and brings the outcomes. - -Requirements: -- The only caller authorized to call this function is `registry`, -- Given wallet data must not belong to an already registered wallet. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| self | struct BridgeState.Storage | | -| ecdsaWalletID | bytes32 | Wallet's unique identifier. | -| publicKeyX | bytes32 | Wallet's public key's X coordinate. | -| publicKeyY | bytes32 | Wallet's public key's Y coordinate. | - -### notifyWalletRedemptionTimeout - -```solidity -function notifyWalletRedemptionTimeout(struct BridgeState.Storage self, bytes20 walletPubKeyHash, uint32[] walletMembersIDs) internal -``` - -Handles a notification about a wallet redemption timeout. -Triggers the wallet moving funds process only if the wallet is -still in the Live state. That means multiple action timeouts can -be reported for the same wallet but only the first report -requests the wallet to move their funds. Executes slashing if -the wallet is in Live or MovingFunds state. Allows to notify -redemption timeout also for a Terminated wallet in case the -redemption was requested before the wallet got terminated. - -Requirements: -- The wallet must be in the `Live`, `MovingFunds`, -or `Terminated` state. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| self | struct BridgeState.Storage | | -| walletPubKeyHash | bytes20 | 20-byte public key hash of the wallet. | -| walletMembersIDs | uint32[] | Identifiers of the wallet signing group members. | - -### notifyWalletHeartbeatFailed - -```solidity -function notifyWalletHeartbeatFailed(struct BridgeState.Storage self, bytes32 publicKeyX, bytes32 publicKeyY) external -``` - -Handles a notification about a wallet heartbeat failure and -triggers the wallet moving funds process. - -Requirements: -- The only caller authorized to call this function is `registry`, -- Wallet must be in Live state. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| self | struct BridgeState.Storage | | -| publicKeyX | bytes32 | Wallet's public key's X coordinate. | -| publicKeyY | bytes32 | Wallet's public key's Y coordinate. | - -### notifyWalletCloseable - -```solidity -function notifyWalletCloseable(struct BridgeState.Storage self, bytes20 walletPubKeyHash, struct BitcoinTx.UTXO walletMainUtxo) external -``` - -Notifies that the wallet is either old enough or has too few -satoshis left and qualifies to be closed. - -Requirements: -- Wallet must not be set as the current active wallet, -- Wallet must exceed the wallet maximum age OR the wallet BTC -balance must be lesser than the minimum threshold. If the latter -case is true, the `walletMainUtxo` components must point to the -recent main UTXO of the given wallet, as currently known on the -Ethereum chain. If the wallet has no main UTXO, this parameter -can be empty as it is ignored since the wallet balance is -assumed to be zero, -- Wallet must be in Live state. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| self | struct BridgeState.Storage | | -| walletPubKeyHash | bytes20 | 20-byte public key hash of the wallet. | -| walletMainUtxo | struct BitcoinTx.UTXO | Data of the wallet's main UTXO, as currently known on the Ethereum chain. | - -### notifyWalletClosingPeriodElapsed - -```solidity -function notifyWalletClosingPeriodElapsed(struct BridgeState.Storage self, bytes20 walletPubKeyHash) internal -``` - -Notifies about the end of the closing period for the given wallet. -Closes the wallet ultimately and notifies the ECDSA registry -about this fact. - -Requirements: -- The wallet must be in the Closing state, -- The wallet closing period must have elapsed. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| self | struct BridgeState.Storage | | -| walletPubKeyHash | bytes20 | 20-byte public key hash of the wallet. | - -### notifyWalletFundsMoved - -```solidity -function notifyWalletFundsMoved(struct BridgeState.Storage self, bytes20 walletPubKeyHash, bytes32 targetWalletsHash) internal -``` - -Notifies that the wallet completed the moving funds process -successfully. Checks if the funds were moved to the expected -target wallets. Closes the source wallet if everything went -good and reverts otherwise. - -Requirements: -- The caller must make sure the moving funds transaction actually -happened on Bitcoin chain and fits the protocol requirements, -- The source wallet must be in the MovingFunds state, -- The target wallets commitment must be submitted by the source -wallet, -- The actual target wallets used in the moving funds transaction -must be exactly the same as the target wallets commitment. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| self | struct BridgeState.Storage | | -| walletPubKeyHash | bytes20 | 20-byte public key hash of the wallet. | -| targetWalletsHash | bytes32 | 32-byte keccak256 hash over the list of 20-byte public key hashes of the target wallets actually used within the moving funds transactions. | - -### notifyWalletMovingFundsBelowDust - -```solidity -function notifyWalletMovingFundsBelowDust(struct BridgeState.Storage self, bytes20 walletPubKeyHash) internal -``` - -Called when a MovingFunds wallet has a balance below the dust -threshold. Begins the wallet closing. - -Requirements: -- The wallet must be in the MovingFunds state. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| self | struct BridgeState.Storage | | -| walletPubKeyHash | bytes20 | 20-byte public key hash of the wallet. | - -### notifyWalletMovingFundsTimeout - -```solidity -function notifyWalletMovingFundsTimeout(struct BridgeState.Storage self, bytes20 walletPubKeyHash, uint32[] walletMembersIDs) internal -``` - -Called when the timeout for MovingFunds for the wallet elapsed. -Slashes wallet members and terminates the wallet. - -Requirements: -- The wallet must be in the MovingFunds state. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| self | struct BridgeState.Storage | | -| walletPubKeyHash | bytes20 | 20-byte public key hash of the wallet. | -| walletMembersIDs | uint32[] | Identifiers of the wallet signing group members. | - -### notifyWalletMovedFundsSweepTimeout - -```solidity -function notifyWalletMovedFundsSweepTimeout(struct BridgeState.Storage self, bytes20 walletPubKeyHash, uint32[] walletMembersIDs) internal -``` - -Called when a wallet which was asked to sweep funds moved from -another wallet did not provide a sweeping proof before a timeout. -Slashes and terminates the wallet who failed to provide a proof. - -Requirements: -- The wallet must be in the `Live`, `MovingFunds`, -or `Terminated` state. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| self | struct BridgeState.Storage | | -| walletPubKeyHash | bytes20 | 20-byte public key hash of the wallet which was supposed to sweep funds. | -| walletMembersIDs | uint32[] | Identifiers of the wallet signing group members. | - -### notifyWalletFraudChallengeDefeatTimeout - -```solidity -function notifyWalletFraudChallengeDefeatTimeout(struct BridgeState.Storage self, bytes20 walletPubKeyHash, uint32[] walletMembersIDs, address challenger) internal -``` - -Called when a wallet which was challenged for a fraud did not -defeat the challenge before the timeout. Slashes and terminates -the wallet who failed to defeat the challenge. If the wallet is -already terminated, it does nothing. - -Requirements: -- The wallet must be in the `Live`, `MovingFunds`, `Closing` -or `Terminated` state. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| self | struct BridgeState.Storage | | -| walletPubKeyHash | bytes20 | 20-byte public key hash of the wallet which was supposed to sweep funds. | -| walletMembersIDs | uint32[] | Identifiers of the wallet signing group members. | -| challenger | address | Address of the party which submitted the fraud challenge. | - -### moveFunds - -```solidity -function moveFunds(struct BridgeState.Storage self, bytes20 walletPubKeyHash) internal -``` - -Requests a wallet to move their funds. If the wallet balance -is zero, the wallet closing begins immediately. If the move -funds request refers to the current active wallet, such a wallet -is no longer considered active and the active wallet slot -is unset allowing to trigger a new wallet creation immediately. - -Requirements: -- The caller must make sure that the wallet is in the Live state. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| self | struct BridgeState.Storage | | -| walletPubKeyHash | bytes20 | 20-byte public key hash of the wallet. | - -### beginWalletClosing - -```solidity -function beginWalletClosing(struct BridgeState.Storage self, bytes20 walletPubKeyHash) internal -``` - -Begins the closing period of the given wallet. - -Requirements: -- The caller must make sure that the wallet is in the -MovingFunds state. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| self | struct BridgeState.Storage | | -| walletPubKeyHash | bytes20 | 20-byte public key hash of the wallet. | - -### finalizeWalletClosing - -```solidity -function finalizeWalletClosing(struct BridgeState.Storage self, bytes20 walletPubKeyHash) internal -``` - -Finalizes the closing period of the given wallet and notifies -the ECDSA registry about this fact. - -Requirements: -- The caller must make sure that the wallet is in the Closing state. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| self | struct BridgeState.Storage | | -| walletPubKeyHash | bytes20 | 20-byte public key hash of the wallet. | - -### terminateWallet - -```solidity -function terminateWallet(struct BridgeState.Storage self, bytes20 walletPubKeyHash) internal -``` - -Terminates the given wallet and notifies the ECDSA registry -about this fact. If the wallet termination refers to the current -active wallet, such a wallet is no longer considered active and -the active wallet slot is unset allowing to trigger a new wallet -creation immediately. - -Requirements: -- The caller must make sure that the wallet is in the -Live or MovingFunds or Closing state. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| self | struct BridgeState.Storage | | -| walletPubKeyHash | bytes20 | 20-byte public key hash of the wallet. | - -### getWalletBtcBalance - -```solidity -function getWalletBtcBalance(struct BridgeState.Storage self, bytes20 walletPubKeyHash, struct BitcoinTx.UTXO walletMainUtxo) internal view returns (uint64 walletBtcBalance) -``` - -Gets BTC balance for given the wallet. - -Requirements: -- `walletMainUtxo` components must point to the recent main UTXO -of the given wallet, as currently known on the Ethereum chain. -If the wallet has no main UTXO, this parameter can be empty as it -is ignored. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| self | struct BridgeState.Storage | | -| walletPubKeyHash | bytes20 | 20-byte public key hash of the wallet. | -| walletMainUtxo | struct BitcoinTx.UTXO | Data of the wallet's main UTXO, as currently known on the Ethereum chain. | - -#### Return Values - -| Name | Type | Description | -| ---- | ---- | ----------- | -| walletBtcBalance | uint64 | Current BTC balance for the given wallet. | - -## IVault - -`IVault` is an interface for a smart contract consuming Bank -balances of other contracts or externally owned accounts (EOA). - -### receiveBalanceIncrease - -```solidity -function receiveBalanceIncrease(address[] depositors, uint256[] depositedAmounts) external -``` - -Called by the Bank in `increaseBalanceAndCall` function after -increasing the balance in the Bank for the vault. It happens in -the same transaction in which deposits were swept by the Bridge. -This allows the depositor to route their deposit revealed to the -Bridge to the particular smart contract (vault) in the same -transaction in which the deposit is revealed. This way, the -depositor does not have to execute additional transaction after -the deposit gets swept by the Bridge to approve and transfer -their balance to the vault. - -The implementation must ensure this function can only be called -by the Bank. The Bank guarantees that the vault's balance was -increased by the sum of all deposited amounts before this function -is called, in the same transaction. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| depositors | address[] | Addresses of depositors whose deposits have been swept. | -| depositedAmounts | uint256[] | Amounts deposited by individual depositors and swept. | - -## GovernanceUtils - -### onlyAfterGovernanceDelay - -```solidity -function onlyAfterGovernanceDelay(uint256 changeInitiatedTimestamp, uint256 delay) internal view -``` - -Reverts if the governance delay has not passed since -the change initiated time or if the change has not been -initiated. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| changeInitiatedTimestamp | uint256 | The timestamp at which the change has been initiated. | -| delay | uint256 | Governance delay. | - -### getRemainingGovernanceDelay - -```solidity -function getRemainingGovernanceDelay(uint256 changeInitiatedTimestamp, uint256 delay) internal view returns (uint256) -``` - -Gets the time remaining until the governable parameter update -can be committed. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| changeInitiatedTimestamp | uint256 | Timestamp indicating the beginning of the change. | -| delay | uint256 | Governance delay. | - -#### Return Values - -| Name | Type | Description | -| ---- | ---- | ----------- | -| [0] | uint256 | Remaining time in seconds. | - -## VendingMachine - -The Vending Machine is the owner of TBTC v2 token and can mint -TBTC v2 tokens in 1:1 ratio from TBTC v1 tokens with TBTC v1 -deposited in the contract as collateral. TBTC v2 can be -unminted back to TBTC v1 with or without a fee - fee parameter is -controlled by the Governance. This implementation acts as a bridge -between TBTC v1 and TBTC v2 token, allowing to mint TBTC v2 before -the system is ready and fully operational without sacrificing any -security guarantees and decentralization of the project. -Vending Machine can be upgraded in a two-step, governance-controlled -process. The new version of the Vending Machine will receive the -ownership of TBTC v2 token and entire TBTC v1 balance stored as -collateral. It is expected that this process will be executed before -the v2 system launch. There is an optional unmint fee with a value -that can be updated in a two-step, governance-controlled process. -All governable parameters are controlled by two roles: update -initiator and finalizer. There is a separate initiator role for -unmint fee update and vending machine upgrade. The initiator -proposes the change by initiating the update and the finalizer -(contract owner) may approve it by finalizing the change after the -governance delay passes. - -### GOVERNANCE_DELAY - -```solidity -uint256 GOVERNANCE_DELAY -``` - -The time delay that needs to pass between initializing and -finalizing update of any governable parameter in this contract. - -### FLOATING_POINT_DIVISOR - -```solidity -uint256 FLOATING_POINT_DIVISOR -``` - -Divisor for precision purposes. Used to represent fractions -in parameter values. - -### tbtcV1 - -```solidity -contract IERC20 tbtcV1 -``` - -### tbtcV2 - -```solidity -contract TBTC tbtcV2 -``` - -### unmintFee - -```solidity -uint256 unmintFee -``` - -The fee for unminting TBTC v2 back into TBTC v1 represented as -1e18 precision fraction. The fee is proportional to the amount -being unminted and added on the top of the amount being unminted. -To calculate the fee value, the amount being unminted needs -to be multiplied by `unmintFee` and divided by 1e18. -For example, `unmintFee` set to 1000000000000000 -means that 0.001 of the amount being unminted needs to be paid -to the `VendingMachine` as an unminting fee on the top of the -amount being unminted. - -### newUnmintFee - -```solidity -uint256 newUnmintFee -``` - -### unmintFeeUpdateInitiatedTimestamp - -```solidity -uint256 unmintFeeUpdateInitiatedTimestamp -``` - -### unmintFeeUpdateInitiator - -```solidity -address unmintFeeUpdateInitiator -``` - -### newVendingMachine - -```solidity -address newVendingMachine -``` - -The address of a new vending machine. Set only when the upgrade -process is pending. Once the upgrade gets finalized, the new -vending machine will become an owner of TBTC v2 token. - -### vendingMachineUpgradeInitiatedTimestamp - -```solidity -uint256 vendingMachineUpgradeInitiatedTimestamp -``` - -### vendingMachineUpgradeInitiator - -```solidity -address vendingMachineUpgradeInitiator -``` - -### UnmintFeeUpdateInitiated - -```solidity -event UnmintFeeUpdateInitiated(uint256 newUnmintFee, uint256 timestamp) -``` - -### UnmintFeeUpdated - -```solidity -event UnmintFeeUpdated(uint256 newUnmintFee) -``` - -### VendingMachineUpgradeInitiated - -```solidity -event VendingMachineUpgradeInitiated(address newVendingMachine, uint256 timestamp) -``` - -### VendingMachineUpgraded - -```solidity -event VendingMachineUpgraded(address newVendingMachine) -``` - -### Minted - -```solidity -event Minted(address recipient, uint256 amount) -``` - -### Unminted - -```solidity -event Unminted(address recipient, uint256 amount, uint256 fee) -``` - -### only - -```solidity -modifier only(address authorizedCaller) -``` - -### onlyAfterGovernanceDelay - -```solidity -modifier onlyAfterGovernanceDelay(uint256 changeInitiatedTimestamp) -``` - -### constructor - -```solidity -constructor(contract IERC20 _tbtcV1, contract TBTC _tbtcV2, uint256 _unmintFee) public -``` - -### mint - -```solidity -function mint(uint256 amount) external -``` - -Mints TBTC v2 to the caller from TBTC v1 with 1:1 ratio. -The caller needs to have at least `amount` of TBTC v1 balance -approved for transfer to the `VendingMachine` before calling -this function. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| amount | uint256 | The amount of TBTC v2 to mint from TBTC v1 | - -### receiveApproval - -```solidity -function receiveApproval(address from, uint256 amount, address token, bytes) external -``` - -Mints TBTC v2 to `from` address from TBTC v1 with 1:1 ratio. -`from` address needs to have at least `amount` of TBTC v1 -balance approved for transfer to the `VendingMachine` before -calling this function. - -This function is a shortcut for approve + mint. Only TBTC v1 -caller is allowed and only TBTC v1 is allowed as a token to -transfer. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| from | address | TBTC v1 token holder minting TBTC v2 tokens | -| amount | uint256 | The amount of TBTC v2 to mint from TBTC v1 | -| token | address | TBTC v1 token address | -| | bytes | | - -### unmint - -```solidity -function unmint(uint256 amount) external -``` - -Unmints TBTC v2 from the caller into TBTC v1. Depending on -`unmintFee` value, may require paying an additional unmint fee -in TBTC v2 in addition to the amount being unminted. To see -what is the value of the fee, please call `unmintFeeFor(amount)` -function. The caller needs to have at least -`amount + unmintFeeFor(amount)` of TBTC v2 balance approved for -transfer to the `VendingMachine` before calling this function. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| amount | uint256 | The amount of TBTC v2 to unmint to TBTC v1 | - -### withdrawFees - -```solidity -function withdrawFees(address recipient, uint256 amount) external -``` - -Allows the Governance to withdraw unmint fees accumulated by -`VendingMachine`. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| recipient | address | The address receiving the fees | -| amount | uint256 | The amount of fees in TBTC v2 to withdraw | - -### initiateUnmintFeeUpdate - -```solidity -function initiateUnmintFeeUpdate(uint256 _newUnmintFee) external -``` - -Initiates unmint fee update process. The update process needs to -be finalized with a call to `finalizeUnmintFeeUpdate` function -after the `GOVERNANCE_DELAY` passes. Only unmint fee update -initiator role can initiate the update. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| _newUnmintFee | uint256 | The new unmint fee | - -### finalizeUnmintFeeUpdate - -```solidity -function finalizeUnmintFeeUpdate() external -``` - -Allows the contract owner to finalize unmint fee update process. -The update process needs to be first initiated with a call to -`initiateUnmintFeeUpdate` and the `GOVERNANCE_DELAY` needs to -pass. - -### initiateVendingMachineUpgrade - -```solidity -function initiateVendingMachineUpgrade(address _newVendingMachine) external -``` - -Initiates vending machine upgrade process. The upgrade process -needs to be finalized with a call to -`finalizeVendingMachineUpgrade` function after the -`GOVERNANCE_DELAY` passes. Only vending machine upgrade -initiator role can initiate the upgrade. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| _newVendingMachine | address | The new vending machine address | - -### finalizeVendingMachineUpgrade - -```solidity -function finalizeVendingMachineUpgrade() external -``` - -Allows the contract owner to finalize vending machine upgrade -process. The upgrade process needs to be first initiated with a -call to `initiateVendingMachineUpgrade` and the `GOVERNANCE_DELAY` -needs to pass. Once the upgrade is finalized, the new vending -machine will become an owner of TBTC v2 token and all TBTC v1 -held by this contract will be transferred to the new vending -machine. - -### transferUnmintFeeUpdateInitiatorRole - -```solidity -function transferUnmintFeeUpdateInitiatorRole(address newInitiator) external -``` - -Transfers unmint fee update initiator role to another address. -Can be called only by the current unmint fee update initiator. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| newInitiator | address | The new unmint fee update initiator | - -### transferVendingMachineUpgradeInitiatorRole - -```solidity -function transferVendingMachineUpgradeInitiatorRole(address newInitiator) external -``` - -Transfers vending machine upgrade initiator role to another -address. Can be called only by the current vending machine -upgrade initiator. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| newInitiator | address | The new vending machine upgrade initiator | - -### getRemainingUnmintFeeUpdateTime - -```solidity -function getRemainingUnmintFeeUpdateTime() external view returns (uint256) -``` - -Get the remaining time that needs to pass until unmint fee -update can be finalized by the Governance. If the update has -not been initiated, the function reverts. - -### getRemainingVendingMachineUpgradeTime - -```solidity -function getRemainingVendingMachineUpgradeTime() external view returns (uint256) -``` - -Get the remaining time that needs to pass until vending machine -upgrade can be finalized by the Governance. If the upgrade has -not been initiated, the function reverts. - -### unmintFeeFor - -```solidity -function unmintFeeFor(uint256 amount) public view returns (uint256) -``` - -Calculates the fee that needs to be paid to the `VendingMachine` -to unmint the given amount of TBTC v2 back into TBTC v1. - -### _mint - -```solidity -function _mint(address tokenOwner, uint256 amount) internal -``` - -## VendingMachineV2 - -VendingMachineV2 is used to exchange tBTC v1 to tBTC v2 in a 1:1 -ratio during the process of tBTC v1 bridge sunsetting. The redeemer -selected by the DAO based on the "TIP-027b tBTC v1: The Sunsetting" -proposal will deposit tBTC v2 tokens into VendingMachineV2 so that -outstanding tBTC v1 token owners can upgrade to tBTC v2 tokens. -The redeemer will withdraw the tBTC v1 tokens deposited into the -contract to perform tBTC v1 redemptions. -The redeemer may decide to withdraw their deposited tBTC v2 at any -moment in time. The amount withdrawable is lower than the amount -deposited in case tBTC v1 was exchanged for tBTC v2. -This contract is owned by the redeemer. - -### tbtcV1 - -```solidity -contract IERC20 tbtcV1 -``` - -### tbtcV2 - -```solidity -contract TBTC tbtcV2 -``` - -### Exchanged - -```solidity -event Exchanged(address to, uint256 amount) -``` - -### Deposited - -```solidity -event Deposited(address from, uint256 amount) -``` - -### Withdrawn - -```solidity -event Withdrawn(address token, address to, uint256 amount) -``` - -### constructor - -```solidity -constructor(contract IERC20 _tbtcV1, contract TBTC _tbtcV2) public -``` - -### exchange - -```solidity -function exchange(uint256 amount) external -``` - -Exchange tBTC v1 for tBTC v2 in a 1:1 ratio. -The caller needs to have at least `amount` of tBTC v1 balance -approved for transfer to the `VendingMachineV2` before calling -this function. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| amount | uint256 | The amount of tBTC v1 to exchange for tBTC v2. | - -### receiveApproval - -```solidity -function receiveApproval(address from, uint256 amount, address token, bytes) external -``` - -Exchange tBTC v1 for tBTC v2 in a 1:1 ratio. -The caller needs to have at least `amount` of tBTC v1 balance -approved for transfer to the `VendingMachineV2` before calling -this function. - -This function is a shortcut for `approve` + `exchange`. Only tBTC -v1 token caller is allowed and only tBTC v1 is allowed as a token -to transfer. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| from | address | tBTC v1 token holder exchanging tBTC v1 to tBTC v2. | -| amount | uint256 | The amount of tBTC v1 to exchange for tBTC v2. | -| token | address | tBTC v1 token address. | -| | bytes | | - -### depositTbtcV2 - -```solidity -function depositTbtcV2(uint256 amount) external -``` - -Allows to deposit tBTC v2 tokens to the contract. -VendingMachineV2 can not mint tBTC v2 tokens so tBTC v2 needs -to be deposited into the contract so that tBTC v1 to tBTC v2 -exchange can happen. -The caller needs to have at least `amount` of tBTC v2 balance -approved for transfer to the `VendingMachineV2` before calling -this function. - -This function is for the redeemer and tBTC v1 operators. This is -NOT a function for tBTC v1 token holders. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| amount | uint256 | The amount of tBTC v2 to deposit into the contract. | - -### withdrawFunds - -```solidity -function withdrawFunds(contract IERC20 token, address recipient, uint256 amount) external -``` - -Allows the contract owner to withdraw tokens. This function is -used in two cases: 1) when the redeemer wants to redeem tBTC v1 -tokens to perform tBTC v2 redemptions; 2) when the deadline for -tBTC v1 -> tBTC v2 exchange passed and the redeemer wants their -tBTC v2 back. - -This function is for the redeemer. This is NOT a function for -tBTC v1 token holders. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| token | contract IERC20 | The address of a token to withdraw. | -| recipient | address | The address which should receive withdrawn tokens. | -| amount | uint256 | The amount to withdraw. | - -### _exchange - -```solidity -function _exchange(address tokenOwner, uint256 amount) internal -``` - -## VendingMachineV3 - -VendingMachineV3 is used to exchange tBTC v1 to tBTC v2 in a 1:1 -ratio after the tBTC v1 bridge sunsetting is completed. Since -tBTC v1 bridge is no longer working, tBTC v1 tokens can not be used -to perform BTC redemptions. This contract allows tBTC v1 owners to -upgrade to tBTC v2 without any deadline. This way, tBTC v1 tokens -left on the market are always backed by Bitcoin. The governance will -deposit tBTC v2 into the contract in the amount equal to tBTC v1 -supply. The governance is allowed to withdraw tBTC v2 only if tBTC -v2 left in this contract is enough to cover the upgrade of all tBTC -v1 left on the market. This contract is owned by the governance. - -### tbtcV1 - -```solidity -contract IERC20 tbtcV1 -``` - -### tbtcV2 - -```solidity -contract TBTC tbtcV2 -``` - -### Exchanged - -```solidity -event Exchanged(address to, uint256 amount) -``` - -### Deposited - -```solidity -event Deposited(address from, uint256 amount) -``` - -### TbtcV2Withdrawn - -```solidity -event TbtcV2Withdrawn(address to, uint256 amount) -``` - -### FundsRecovered - -```solidity -event FundsRecovered(address token, address to, uint256 amount) -``` - -### constructor - -```solidity -constructor(contract IERC20 _tbtcV1, contract TBTC _tbtcV2) public -``` - -### exchange - -```solidity -function exchange(uint256 amount) external -``` - -Exchange tBTC v1 for tBTC v2 in a 1:1 ratio. -The caller needs to have at least `amount` of tBTC v1 balance -approved for transfer to the `VendingMachineV3` before calling -this function. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| amount | uint256 | The amount of tBTC v1 to exchange for tBTC v2. | - -### receiveApproval - -```solidity -function receiveApproval(address from, uint256 amount, address token, bytes) external -``` - -Exchange tBTC v1 for tBTC v2 in a 1:1 ratio. -The caller needs to have at least `amount` of tBTC v1 balance -approved for transfer to the `VendingMachineV3` before calling -this function. - -This function is a shortcut for `approve` + `exchange`. Only tBTC -v1 caller is allowed and only tBTC v1 is allowed as a token to -transfer. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| from | address | tBTC v1 token holder exchanging tBTC v1 to tBTC v2. | -| amount | uint256 | The amount of tBTC v1 to exchange for tBTC v2. | -| token | address | tBTC v1 token address. | -| | bytes | | - -### depositTbtcV2 - -```solidity -function depositTbtcV2(uint256 amount) external -``` - -Allows to deposit tBTC v2 tokens to the contract. -`VendingMachineV3` can not mint tBTC v2 tokens so tBTC v2 needs -to be deposited into the contract so that tBTC v1 to tBTC v2 -exchange can happen. -The caller needs to have at least `amount` of tBTC v2 balance -approved for transfer to the `VendingMachineV3` before calling -this function. - -This function is for the redeemer and tBTC v1 operators. This is -NOT a function for tBTC v1 token holders. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| amount | uint256 | The amount of tBTC v2 to deposit into the contract. | - -### withdrawTbtcV2 - -```solidity -function withdrawTbtcV2(address recipient, uint256 amount) external -``` - -Allows the governance to withdraw tBTC v2 deposited into this -contract. The governance is allowed to withdraw tBTC v2 -only if tBTC v2 left in this contract is enough to cover the -upgrade of all tBTC v1 left on the market. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| recipient | address | The address which should receive withdrawn tokens. | -| amount | uint256 | The amount to withdraw. | - -### recoverFunds - -```solidity -function recoverFunds(contract IERC20 token, address recipient, uint256 amount) external -``` - -Allows the governance to recover ERC20 sent to this contract -by mistake or tBTC v1 locked in the contract to exchange to -tBTC v2. No tBTC v2 can be withdrawn using this function. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| token | contract IERC20 | The address of a token to recover. | -| recipient | address | The address which should receive recovered tokens. | -| amount | uint256 | The amount to recover. | - -### _exchange - -```solidity -function _exchange(address tokenOwner, uint256 amount) internal -``` - -## WalletCoordinator - -The wallet coordinator contract aims to facilitate the coordination -of the off-chain wallet members during complex multi-chain wallet -operations like deposit sweeping, redemptions, or moving funds. -Such processes involve various moving parts and many steps that each -individual wallet member must do. Given the distributed nature of -the off-chain wallet software, full off-chain implementation is -challenging and prone to errors, especially byzantine faults. -This contract provides a single and trusted on-chain coordination -point thus taking the riskiest part out of the off-chain software. -The off-chain wallet members can focus on the core tasks and do not -bother about electing a trusted coordinator or aligning internal -states using complex consensus algorithms. - -### WalletAction - -```solidity -enum WalletAction { - Idle, - Heartbeat, - DepositSweep, - Redemption, - MovingFunds, - MovedFundsSweep -} -``` - -### WalletLock - -```solidity -struct WalletLock { - uint32 expiresAt; - enum WalletCoordinator.WalletAction cause; -} -``` - -### DepositSweepProposal - -```solidity -struct DepositSweepProposal { - bytes20 walletPubKeyHash; - struct WalletCoordinator.DepositKey[] depositsKeys; - uint256 sweepTxFee; - uint256[] depositsRevealBlocks; -} -``` - -### DepositKey - -```solidity -struct DepositKey { - bytes32 fundingTxHash; - uint32 fundingOutputIndex; -} -``` - -### DepositExtraInfo - -```solidity -struct DepositExtraInfo { - struct BitcoinTx.Info fundingTx; - bytes8 blindingFactor; - bytes20 walletPubKeyHash; - bytes20 refundPubKeyHash; - bytes4 refundLocktime; -} -``` - -### RedemptionProposal - -```solidity -struct RedemptionProposal { - bytes20 walletPubKeyHash; - bytes[] redeemersOutputScripts; - uint256 redemptionTxFee; -} -``` - -### isCoordinator - -```solidity -mapping(address => bool) isCoordinator -``` - -Mapping that holds addresses allowed to submit proposals and -request heartbeats. - -### walletLock - -```solidity -mapping(bytes20 => struct WalletCoordinator.WalletLock) walletLock -``` - -Mapping that holds wallet time locks. The key is a 20-byte -wallet public key hash. - -### bridge - -```solidity -contract Bridge bridge -``` - -Handle to the Bridge contract. - -### heartbeatRequestValidity - -```solidity -uint32 heartbeatRequestValidity -``` - -Determines the wallet heartbeat request validity time. In other -words, this is the worst-case time for a wallet heartbeat -during which the wallet is busy and canot take other actions. -This is also the duration of the time lock applied to the wallet -once a new heartbeat request is submitted. - -For example, if a deposit sweep proposal was submitted at -2 pm and heartbeatRequestValidity is 1 hour, the next request or -proposal (of any type) can be submitted after 3 pm. - -### heartbeatRequestGasOffset - -```solidity -uint32 heartbeatRequestGasOffset -``` - -Gas that is meant to balance the heartbeat request overall cost. -Can be updated by the owner based on the current conditions. - -### depositSweepProposalValidity - -```solidity -uint32 depositSweepProposalValidity -``` - -Determines the deposit sweep proposal validity time. In other -words, this is the worst-case time for a deposit sweep during -which the wallet is busy and cannot take another actions. This -is also the duration of the time lock applied to the wallet -once a new deposit sweep proposal is submitted. - -For example, if a deposit sweep proposal was submitted at -2 pm and depositSweepProposalValidity is 4 hours, the next -proposal (of any type) can be submitted after 6 pm. - -### depositMinAge - -```solidity -uint32 depositMinAge -``` - -The minimum time that must elapse since the deposit reveal -before a deposit becomes eligible for a deposit sweep. - -For example, if a deposit was revealed at 9 am and depositMinAge -is 2 hours, the deposit is eligible for sweep after 11 am. - -Forcing deposit minimum age ensures block finality for Ethereum. -In the happy path case, i.e. where the deposit is revealed immediately -after being broadcast on the Bitcoin network, the minimum age -check also ensures block finality for Bitcoin. - -### depositRefundSafetyMargin - -```solidity -uint32 depositRefundSafetyMargin -``` - -Each deposit can be technically swept until it reaches its -refund timestamp after which it can be taken back by the depositor. -However, allowing the wallet to sweep deposits that are close -to their refund timestamp may cause a race between the wallet -and the depositor. In result, the wallet may sign an invalid -sweep transaction that aims to sweep an already refunded deposit. -Such tx signature may be used to create an undefeatable fraud -challenge against the wallet. In order to mitigate that problem, -this parameter determines a safety margin that puts the latest -moment a deposit can be swept far before the point after which -the deposit becomes refundable. - -For example, if a deposit becomes refundable after 8 pm and -depositRefundSafetyMargin is 6 hours, the deposit is valid for -for a sweep only before 2 pm. - -### depositSweepMaxSize - -```solidity -uint16 depositSweepMaxSize -``` - -The maximum count of deposits that can be swept within a -single sweep. - -### depositSweepProposalSubmissionGasOffset - -```solidity -uint32 depositSweepProposalSubmissionGasOffset -``` - -Gas that is meant to balance the deposit sweep proposal -submission overall cost. Can be updated by the owner based on -the current conditions. - -### redemptionProposalValidity - -```solidity -uint32 redemptionProposalValidity -``` - -Determines the redemption proposal validity time. In other -words, this is the worst-case time for a redemption during -which the wallet is busy and cannot take another actions. This -is also the duration of the time lock applied to the wallet -once a new redemption proposal is submitted. - -For example, if a redemption proposal was submitted at -2 pm and redemptionProposalValidity is 2 hours, the next -proposal (of any type) can be submitted after 4 pm. - -### redemptionRequestMinAge - -```solidity -uint32 redemptionRequestMinAge -``` - -The minimum time that must elapse since the redemption request -creation before a request becomes eligible for a processing. - -For example, if a request was created at 9 am and -redemptionRequestMinAge is 2 hours, the request is eligible for -processing after 11 am. - -Forcing request minimum age ensures block finality for Ethereum. - -### redemptionRequestTimeoutSafetyMargin - -```solidity -uint32 redemptionRequestTimeoutSafetyMargin -``` - -Each redemption request can be technically handled until it -reaches its timeout timestamp after which it can be reported -as timed out. However, allowing the wallet to handle requests -that are close to their timeout timestamp may cause a race -between the wallet and the redeemer. In result, the wallet may -redeem the requested funds even though the redeemer already -received back their tBTC (locked during redemption request) upon -reporting the request timeout. In effect, the redeemer may end -out with both tBTC and redeemed BTC in their hands which has -a negative impact on the tBTC <-> BTC peg. In order to mitigate -that problem, this parameter determines a safety margin that -puts the latest moment a request can be handled far before the -point after which the request can be reported as timed out. - -For example, if a request times out after 8 pm and -redemptionRequestTimeoutSafetyMargin is 2 hours, the request is -valid for processing only before 6 pm. - -### redemptionMaxSize - -```solidity -uint16 redemptionMaxSize -``` - -The maximum count of redemption requests that can be processed -within a single redemption. - -### redemptionProposalSubmissionGasOffset - -```solidity -uint32 redemptionProposalSubmissionGasOffset -``` - -Gas that is meant to balance the redemption proposal -submission overall cost. Can be updated by the owner based on -the current conditions. - -### CoordinatorAdded - -```solidity -event CoordinatorAdded(address coordinator) -``` - -### CoordinatorRemoved - -```solidity -event CoordinatorRemoved(address coordinator) -``` - -### WalletManuallyUnlocked - -```solidity -event WalletManuallyUnlocked(bytes20 walletPubKeyHash) -``` - -### HeartbeatRequestParametersUpdated - -```solidity -event HeartbeatRequestParametersUpdated(uint32 heartbeatRequestValidity, uint32 heartbeatRequestGasOffset) -``` - -### HeartbeatRequestSubmitted - -```solidity -event HeartbeatRequestSubmitted(bytes20 walletPubKeyHash, bytes message, address coordinator) -``` - -### DepositSweepProposalParametersUpdated - -```solidity -event DepositSweepProposalParametersUpdated(uint32 depositSweepProposalValidity, uint32 depositMinAge, uint32 depositRefundSafetyMargin, uint16 depositSweepMaxSize, uint32 depositSweepProposalSubmissionGasOffset) -``` - -### DepositSweepProposalSubmitted - -```solidity -event DepositSweepProposalSubmitted(struct WalletCoordinator.DepositSweepProposal proposal, address coordinator) -``` - -### RedemptionProposalParametersUpdated - -```solidity -event RedemptionProposalParametersUpdated(uint32 redemptionProposalValidity, uint32 redemptionRequestMinAge, uint32 redemptionRequestTimeoutSafetyMargin, uint16 redemptionMaxSize, uint32 redemptionProposalSubmissionGasOffset) -``` - -### RedemptionProposalSubmitted - -```solidity -event RedemptionProposalSubmitted(struct WalletCoordinator.RedemptionProposal proposal, address coordinator) -``` - -### onlyCoordinator - -```solidity -modifier onlyCoordinator() -``` - -### onlyAfterWalletLock - -```solidity -modifier onlyAfterWalletLock(bytes20 walletPubKeyHash) -``` - -### onlyReimbursableAdmin - -```solidity -modifier onlyReimbursableAdmin() -``` - -### initialize - -```solidity -function initialize(contract Bridge _bridge) external -``` - -### addCoordinator - -```solidity -function addCoordinator(address coordinator) external -``` - -Adds the given address to the set of coordinator addresses. - -Requirements: -- The caller must be the owner, -- The `coordinator` must not be an existing coordinator. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| coordinator | address | Address of the new coordinator. | - -### removeCoordinator - -```solidity -function removeCoordinator(address coordinator) external -``` - -Removes the given address from the set of coordinator addresses. - -Requirements: -- The caller must be the owner, -- The `coordinator` must be an existing coordinator. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| coordinator | address | Address of the existing coordinator. | - -### unlockWallet - -```solidity -function unlockWallet(bytes20 walletPubKeyHash) external -``` - -Allows to unlock the given wallet before their time lock expires. -This function should be used in exceptional cases where -something went wrong and there is a need to unlock the wallet -without waiting. - -Requirements: -- The caller must be the owner. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| walletPubKeyHash | bytes20 | 20-byte public key hash of the wallet | - -### updateHeartbeatRequestParameters - -```solidity -function updateHeartbeatRequestParameters(uint32 _heartbeatRequestValidity, uint32 _heartbeatRequestGasOffset) external -``` - -Updates parameters related to heartbeat request. - -Requirements: -- The caller must be the owner. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| _heartbeatRequestValidity | uint32 | The new value of `heartbeatRequestValidity`. | -| _heartbeatRequestGasOffset | uint32 | The new value of `heartbeatRequestGasOffset`. | - -### updateDepositSweepProposalParameters - -```solidity -function updateDepositSweepProposalParameters(uint32 _depositSweepProposalValidity, uint32 _depositMinAge, uint32 _depositRefundSafetyMargin, uint16 _depositSweepMaxSize, uint32 _depositSweepProposalSubmissionGasOffset) external -``` - -Updates parameters related to deposit sweep proposal. - -Requirements: -- The caller must be the owner. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| _depositSweepProposalValidity | uint32 | The new value of `depositSweepProposalValidity`. | -| _depositMinAge | uint32 | The new value of `depositMinAge`. | -| _depositRefundSafetyMargin | uint32 | The new value of `depositRefundSafetyMargin`. | -| _depositSweepMaxSize | uint16 | The new value of `depositSweepMaxSize`. | -| _depositSweepProposalSubmissionGasOffset | uint32 | | - -### requestHeartbeat - -```solidity -function requestHeartbeat(bytes20 walletPubKeyHash, bytes message) public -``` - -Submits a heartbeat request from the wallet. Locks the wallet -for a specific time, equal to the request validity period. -This function validates the proposed heartbeat messge to see -if it matches the heartbeat format expected by the Bridge. - -Requirements: -- The caller is a coordinator, -- The wallet is not time-locked, -- The message to sign is a valid heartbeat message. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| walletPubKeyHash | bytes20 | 20-byte public key hash of the wallet that is supposed to execute the heartbeat. | -| message | bytes | The proposed heartbeat message for the wallet to sign. | - -### requestHeartbeatWithReimbursement - -```solidity -function requestHeartbeatWithReimbursement(bytes20 walletPubKeyHash, bytes message) external -``` - -Wraps `requestHeartbeat` call and reimburses the caller's -transaction cost. - -See `requestHeartbeat` function documentation. - -### submitDepositSweepProposal - -```solidity -function submitDepositSweepProposal(struct WalletCoordinator.DepositSweepProposal proposal) public -``` - -Submits a deposit sweep proposal. Locks the target wallet -for a specific time, equal to the proposal validity period. -This function does not store the proposal in the state but -just emits an event that serves as a guiding light for wallet -off-chain members. Wallet members are supposed to validate -the proposal on their own, before taking any action. - -Requirements: -- The caller is a coordinator, -- The wallet is not time-locked. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| proposal | struct WalletCoordinator.DepositSweepProposal | The deposit sweep proposal | - -### submitDepositSweepProposalWithReimbursement - -```solidity -function submitDepositSweepProposalWithReimbursement(struct WalletCoordinator.DepositSweepProposal proposal) external -``` - -Wraps `submitDepositSweepProposal` call and reimburses the -caller's transaction cost. - -See `submitDepositSweepProposal` function documentation. - -### validateDepositSweepProposal - -```solidity -function validateDepositSweepProposal(struct WalletCoordinator.DepositSweepProposal proposal, struct WalletCoordinator.DepositExtraInfo[] depositsExtraInfo) external view returns (bool) -``` - -View function encapsulating the main rules of a valid deposit -sweep proposal. This function is meant to facilitate the off-chain -validation of the incoming proposals. Thanks to it, most -of the work can be done using a single readonly contract call. -Worth noting, the validation done here is not exhaustive as some -conditions may not be verifiable within the on-chain function or -checking them may be easier on the off-chain side. For example, -this function does not check the SPV proofs and confirmations of -the deposit funding transactions as this would require an -integration with the difficulty relay that greatly increases -complexity. Instead of that, each off-chain wallet member is -supposed to do that check on their own. - -Requirements: -- The target wallet must be in the Live state, -- The number of deposits included in the sweep must be in -the range [1, `depositSweepMaxSize`], -- The length of `depositsExtraInfo` array must be equal to the -length of `proposal.depositsKeys`, i.e. each deposit must -have exactly one set of corresponding extra data, -- The proposed sweep tx fee must be grater than zero, -- The proposed maximum per-deposit sweep tx fee must be lesser than -or equal the maximum fee allowed by the Bridge (`Bridge.depositTxMaxFee`), -- Each deposit must be revealed to the Bridge, -- Each deposit must be old enough, i.e. at least `depositMinAge` -elapsed since their reveal time, -- Each deposit must not be swept yet, -- Each deposit must have valid extra data (see `validateDepositExtraInfo`), -- Each deposit must have the refund safety margin preserved, -- Each deposit must be controlled by the same wallet, -- Each deposit must target the same vault, -- Each deposit must be unique. - -The following off-chain validation must be performed as a bare minimum: -- Inputs used for the sweep transaction have enough Bitcoin confirmations, -- Deposits revealed to the Bridge have enough Ethereum confirmations. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| proposal | struct WalletCoordinator.DepositSweepProposal | The sweeping proposal to validate. | -| depositsExtraInfo | struct WalletCoordinator.DepositExtraInfo[] | Deposits extra data required to perform the validation. | - -#### Return Values - -| Name | Type | Description | -| ---- | ---- | ----------- | -| [0] | bool | True if the proposal is valid. Reverts otherwise. | - -### validateSweepTxFee - -```solidity -function validateSweepTxFee(uint256 sweepTxFee, uint256 depositsCount) internal view -``` - -Validates the sweep tx fee by checking if the part of the fee -incurred by each deposit does not exceed the maximum value -allowed by the Bridge. This function is heavily based on -`DepositSweep.depositSweepTxFeeDistribution` function. - -Requirements: -- The sweep tx fee must be grater than zero, -- The maximum per-deposit sweep tx fee must be lesser than or equal -the maximum fee allowed by the Bridge (`Bridge.depositTxMaxFee`). - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| sweepTxFee | uint256 | The sweep transaction fee. | -| depositsCount | uint256 | Count of the deposits swept by the sweep transaction. | - -### validateDepositExtraInfo - -```solidity -function validateDepositExtraInfo(struct WalletCoordinator.DepositKey depositKey, address depositor, struct WalletCoordinator.DepositExtraInfo depositExtraInfo) internal view -``` - -Validates the extra data for the given deposit. This function -is heavily based on `Deposit.revealDeposit` function. - -Requirements: -- The transaction hash computed using `depositExtraInfo.fundingTx` -must match the `depositKey.fundingTxHash`. This requirement -ensures the funding transaction data provided in the extra -data container actually represent the funding transaction of -the given deposit. -- The P2(W)SH script inferred from `depositExtraInfo` is actually -used to lock funds by the `depositKey.fundingOutputIndex` output -of the `depositExtraInfo.fundingTx` transaction. This requirement -ensures the reveal data provided in the extra data container -actually matches the given deposit. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| depositKey | struct WalletCoordinator.DepositKey | Key of the given deposit. | -| depositor | address | Depositor that revealed the deposit. | -| depositExtraInfo | struct WalletCoordinator.DepositExtraInfo | Extra data being subject of the validation. | - -### updateRedemptionProposalParameters - -```solidity -function updateRedemptionProposalParameters(uint32 _redemptionProposalValidity, uint32 _redemptionRequestMinAge, uint32 _redemptionRequestTimeoutSafetyMargin, uint16 _redemptionMaxSize, uint32 _redemptionProposalSubmissionGasOffset) external -``` - -Updates parameters related to redemption proposal. - -Requirements: -- The caller must be the owner. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| _redemptionProposalValidity | uint32 | The new value of `redemptionProposalValidity`. | -| _redemptionRequestMinAge | uint32 | The new value of `redemptionRequestMinAge`. | -| _redemptionRequestTimeoutSafetyMargin | uint32 | The new value of `redemptionRequestTimeoutSafetyMargin`. | -| _redemptionMaxSize | uint16 | The new value of `redemptionMaxSize`. | -| _redemptionProposalSubmissionGasOffset | uint32 | The new value of `redemptionProposalSubmissionGasOffset`. | - -### submitRedemptionProposal - -```solidity -function submitRedemptionProposal(struct WalletCoordinator.RedemptionProposal proposal) public -``` - -Submits a redemption proposal. Locks the target wallet -for a specific time, equal to the proposal validity period. -This function does not store the proposal in the state but -just emits an event that serves as a guiding light for wallet -off-chain members. Wallet members are supposed to validate -the proposal on their own, before taking any action. - -Requirements: -- The caller is a coordinator, -- The wallet is not time-locked. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| proposal | struct WalletCoordinator.RedemptionProposal | The redemption proposal | - -### submitRedemptionProposalWithReimbursement - -```solidity -function submitRedemptionProposalWithReimbursement(struct WalletCoordinator.RedemptionProposal proposal) external -``` - -Wraps `submitRedemptionProposal` call and reimburses the -caller's transaction cost. - -See `submitRedemptionProposal` function documentation. - -### validateRedemptionProposal - -```solidity -function validateRedemptionProposal(struct WalletCoordinator.RedemptionProposal proposal) external view returns (bool) -``` - -View function encapsulating the main rules of a valid redemption -proposal. This function is meant to facilitate the off-chain -validation of the incoming proposals. Thanks to it, most -of the work can be done using a single readonly contract call. - -Requirements: -- The target wallet must be in the Live state, -- The number of redemption requests included in the redemption -proposal must be in the range [1, `redemptionMaxSize`], -- The proposed redemption tx fee must be grater than zero, -- The proposed redemption tx fee must be lesser than or equal to -the maximum total fee allowed by the Bridge -(`Bridge.redemptionTxMaxTotalFee`), -- The proposed maximum per-request redemption tx fee share must be -lesser than or equal to the maximum fee share allowed by the -given request (`RedemptionRequest.txMaxFee`), -- Each request must be a pending request registered in the Bridge, -- Each request must be old enough, i.e. at least `redemptionRequestMinAge` -elapsed since their creation time, -- Each request must have the timeout safety margin preserved, -- Each request must be unique. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| proposal | struct WalletCoordinator.RedemptionProposal | The redemption proposal to validate. | - -#### Return Values - -| Name | Type | Description | -| ---- | ---- | ----------- | -| [0] | bool | True if the proposal is valid. Reverts otherwise. | - -## L2TBTC - -Canonical L2/sidechain token implementation. tBTC token is minted on -L1 and locked there to be moved to L2/sidechain. By deploying -a canonical token on each L2/sidechain, we can ensure the supply of -tBTC remains sacrosanct, while enabling quick, interoperable -cross-chain bridges and localizing ecosystem risk. - -This contract is flexible enough to: -- Delegate minting authority to a native bridge on the chain, if -present. -- Delegate minting authority to a short list of ecosystem bridges. -- Have mints and burns paused by any one of n guardians, allowing -avoidance of contagion in case of a chain- or bridge-specific -incident. -- Be governed and upgradeable. - -The token is burnable by the token holder and supports EIP2612 -permits. Token holder can authorize a transfer of their token with -a signature conforming EIP712 standard instead of an on-chain -transaction from their address. Anyone can submit this signature on -the user's behalf by calling the permit function, paying gas fees, -and possibly performing other actions in the same transaction. -The governance can recover ERC20 and ERC721 tokens sent mistakenly -to L2TBTC token contract. - -### isMinter - -```solidity -mapping(address => bool) isMinter -``` - -Indicates if the given address is a minter. Only minters can -mint the token. - -### minters - -```solidity -address[] minters -``` - -List of all minters. - -### isGuardian - -```solidity -mapping(address => bool) isGuardian -``` - -Indicates if the given address is a guardian. Only guardians can -pause token mints and burns. - -### guardians - -```solidity -address[] guardians -``` - -List of all guardians. - -### MinterAdded - -```solidity -event MinterAdded(address minter) -``` - -### MinterRemoved - -```solidity -event MinterRemoved(address minter) -``` - -### GuardianAdded - -```solidity -event GuardianAdded(address guardian) -``` - -### GuardianRemoved - -```solidity -event GuardianRemoved(address guardian) -``` - -### onlyMinter - -```solidity -modifier onlyMinter() -``` - -### onlyGuardian - -```solidity -modifier onlyGuardian() -``` - -### initialize - -```solidity -function initialize(string _name, string _symbol) external -``` - -Initializes the token contract. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| _name | string | The name of the token. | -| _symbol | string | The symbol of the token, usually a shorter version of the name. | - -### addMinter - -```solidity -function addMinter(address minter) external -``` - -Adds the address to the minters list. - -Requirements: -- The caller must be the contract owner. -- `minter` must not be a minter address already. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| minter | address | The address to be added as a minter. | - -### removeMinter - -```solidity -function removeMinter(address minter) external -``` - -Removes the address from the minters list. - -Requirements: -- The caller must be the contract owner. -- `minter` must be a minter address. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| minter | address | The address to be removed from the minters list. | - -### addGuardian - -```solidity -function addGuardian(address guardian) external -``` - -Adds the address to the guardians list. - -Requirements: -- The caller must be the contract owner. -- `guardian` must not be a guardian address already. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| guardian | address | The address to be added as a guardian. | - -### removeGuardian - -```solidity -function removeGuardian(address guardian) external -``` - -Removes the address from the guardians list. - -Requirements: -- The caller must be the contract owner. -- `guardian` must be a guardian address. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| guardian | address | The address to be removed from the guardians list. | - -### recoverERC20 - -```solidity -function recoverERC20(contract IERC20Upgradeable token, address recipient, uint256 amount) external -``` - -Allows the governance of the token contract to recover any ERC20 -sent mistakenly to the token contract address. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| token | contract IERC20Upgradeable | The address of the token to be recovered. | -| recipient | address | The token recipient address that will receive recovered tokens. | -| amount | uint256 | The amount to be recovered. | - -### recoverERC721 - -```solidity -function recoverERC721(contract IERC721Upgradeable token, address recipient, uint256 tokenId, bytes data) external -``` - -Allows the governance of the token contract to recover any -ERC721 sent mistakenly to the token contract address. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| token | contract IERC721Upgradeable | The address of the token to be recovered. | -| recipient | address | The token recipient address that will receive the recovered token. | -| tokenId | uint256 | The ID of the ERC721 token to be recovered. | -| data | bytes | | - -### pause - -```solidity -function pause() external -``` - -Allows one of the guardians to pause mints and burns allowing -avoidance of contagion in case of a chain- or bridge-specific -incident. - -Requirements: -- The caller must be a guardian. -- The contract must not be already paused. - -### unpause - -```solidity -function unpause() external -``` - -Allows the governance to unpause mints and burns previously -paused by one of the guardians. - -Requirements: -- The caller must be the contract owner. -- The contract must be paused. - -### mint - -```solidity -function mint(address account, uint256 amount) external -``` - -Allows one of the minters to mint `amount` tokens and assign -them to `account`, increasing the total supply. Emits -a `Transfer` event with `from` set to the zero address. - -Requirements: -- The caller must be a minter. -- `account` must not be the zero address. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| account | address | The address to receive tokens. | -| amount | uint256 | The amount of token to be minted. | - -### burn - -```solidity -function burn(uint256 amount) public -``` - -Destroys `amount` tokens from the caller. Emits a `Transfer` -event with `to` set to the zero address. - -Requirements: -- The caller must have at least `amount` tokens. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| amount | uint256 | The amount of token to be burned. | - -### burnFrom - -```solidity -function burnFrom(address account, uint256 amount) public -``` - -Destroys `amount` tokens from `account`, deducting from the -caller's allowance. Emits a `Transfer` event with `to` set to -the zero address. - -Requirements: -- The che caller must have allowance for `accounts`'s tokens of at -least `amount`. -- `account` must not be the zero address. -- `account` must have at least `amount` tokens. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| account | address | The address owning tokens to be burned. | -| amount | uint256 | The amount of token to be burned. | - -### getMinters - -```solidity -function getMinters() external view returns (address[]) -``` - -Allows to fetch a list of all minters. - -### getGuardians - -```solidity -function getGuardians() external view returns (address[]) -``` - -Allows to fetch a list of all guardians. - -## IWormholeTokenBridge - -Wormhole Token Bridge interface. Contains only selected functions -used by L2WormholeGateway. - -### completeTransferWithPayload - -```solidity -function completeTransferWithPayload(bytes encodedVm) external returns (bytes) -``` - -### parseTransferWithPayload - -```solidity -function parseTransferWithPayload(bytes encoded) external pure returns (struct IWormholeTokenBridge.TransferWithPayload transfer) -``` - -### transferTokens - -```solidity -function transferTokens(address token, uint256 amount, uint16 recipientChain, bytes32 recipient, uint256 arbiterFee, uint32 nonce) external payable returns (uint64 sequence) -``` - -### transferTokensWithPayload - -```solidity -function transferTokensWithPayload(address token, uint256 amount, uint16 recipientChain, bytes32 recipient, uint32 nonce, bytes payload) external payable returns (uint64 sequence) -``` - -### TransferWithPayload - -```solidity -struct TransferWithPayload { - uint8 payloadID; - uint256 amount; - bytes32 tokenAddress; - uint16 tokenChain; - bytes32 to; - uint16 toChain; - bytes32 fromAddress; - bytes payload; -} -``` - -## L2WormholeGateway - -Selected cross-ecosystem bridges are given the minting authority for -tBTC token on L2 and sidechains. This contract gives a minting -authority to the Wormhole Bridge. - -The process of bridging from L1 to L2 (or sidechain) looks as -follows: -1. There is a tBTC holder on L1. The holder goes to the Wormhole -Portal and selects the chain they want to bridge to. -2. The holder submits one transaction to L1 locking their tBTC -tokens in the bridge’s smart contract. After the transaction is -mined, they wait about 15 minutes for the Ethereum block -finality. -3. The holder submits one transaction to L2 that is minting tokens. -After that transaction is mined, they have their tBTC on L2. - -The process of bridging from L2 (or sidechain) to L1 looks as -follows: -1. There is a tBTC holder on L2. That holder goes to the Wormhole -Portal and selects one of the L2 chains they want to bridge from. -2. The holder submits one transaction to L2 that is burning the -token. After the transaction is mined, they wait about 15 minutes -for the L2 block finality. -3. The holder submits one transaction to L1 unlocking their tBTC -tokens from the bridge’s smart contract. After that transaction -is mined, they have their tBTC on L1. - -This smart contract is integrated with step 3 of L1->L2 bridging and -step 1 of L2->L1 or L2->L2 bridging. When the user redeems token on -L2, this contract receives the Wormhole tBTC representation and -mints the canonical tBTC in an equal amount. When user sends their -token from L1, this contract burns the canonical tBTC and sends -Wormhole tBTC representation through the bridge in an equal amount. - -This contract is supposed to be deployed behind a transparent -upgradeable proxy. - -### bridge - -```solidity -contract IWormholeTokenBridge bridge -``` - -Reference to the Wormhole Token Bridge contract. - -### bridgeToken - -```solidity -contract IERC20Upgradeable bridgeToken -``` - -Wormhole tBTC token representation. - -### tbtc - -```solidity -contract L2TBTC tbtc -``` - -Canonical tBTC token. - -### gateways - -```solidity -mapping(uint16 => bytes32) gateways -``` - -Maps Wormhole chain ID to the Wormhole tBTC gateway address on -that chain. For example, this chain's ID should be mapped to -this contract's address. If there is no Wormhole tBTC gateway -address on the given chain, there is no entry in this mapping. -The mapping holds addresses in a Wormhole-specific format, where -Ethereum address is left-padded with zeros. - -### mintingLimit - -```solidity -uint256 mintingLimit -``` - -Minting limit for this gateway. Useful for early days of testing -the system. The gateway can not mint more canonical tBTC than -this limit. - -### mintedAmount - -```solidity -uint256 mintedAmount -``` - -The amount of tBTC minted by this contract. tBTC burned by this -contract decreases this amount. - -### WormholeTbtcReceived - -```solidity -event WormholeTbtcReceived(address receiver, uint256 amount) -``` - -### WormholeTbtcSent - -```solidity -event WormholeTbtcSent(uint256 amount, uint16 recipientChain, bytes32 gateway, bytes32 recipient, uint256 arbiterFee, uint32 nonce) -``` - -### WormholeTbtcDeposited - -```solidity -event WormholeTbtcDeposited(address depositor, uint256 amount) -``` - -### GatewayAddressUpdated - -```solidity -event GatewayAddressUpdated(uint16 chainId, bytes32 gateway) -``` - -### MintingLimitUpdated - -```solidity -event MintingLimitUpdated(uint256 mintingLimit) -``` - -### initialize - -```solidity -function initialize(contract IWormholeTokenBridge _bridge, contract IERC20Upgradeable _bridgeToken, contract L2TBTC _tbtc) external -``` - -### sendTbtc - -```solidity -function sendTbtc(uint256 amount, uint16 recipientChain, bytes32 recipient, uint256 arbiterFee, uint32 nonce) external payable returns (uint64) -``` - -This function is called when the user sends their token from L2. -The contract burns the canonical tBTC from the user and sends -wormhole tBTC representation over the bridge. -Keep in mind that when multiple bridges receive a minting -authority on the canonical tBTC, this function may not be able -to send all amounts of tBTC through the Wormhole bridge. The -capability of Wormhole Bridge to send tBTC from the chain is -limited to the amount of tBTC bridged through Wormhole to that -chain. - -Requirements: -- The sender must have at least `amount` of the canonical tBTC and -it has to be approved for L2WormholeGateway. -- The L2WormholeGateway must have at least `amount` of the wormhole -tBTC. -- The recipient must not be 0x0. -- The amount to transfer must not be 0, -- The amount to transfer must be >= 10^10 (1e18 precision). -Depending if Wormhole tBTC gateway is registered on the target -chain, this function uses transfer or transfer with payload over -the Wormhole bridge. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| amount | uint256 | The amount of tBTC to be sent. | -| recipientChain | uint16 | The Wormhole recipient chain ID. | -| recipient | bytes32 | The address of the recipient in the Wormhole format. | -| arbiterFee | uint256 | The Wormhole arbiter fee. Ignored if sending tBTC to chain with Wormhole tBTC gateway. | -| nonce | uint32 | The Wormhole nonce used to batch messages together. | - -#### Return Values - -| Name | Type | Description | -| ---- | ---- | ----------- | -| [0] | uint64 | The Wormhole sequence number. | - -### receiveTbtc - -```solidity -function receiveTbtc(bytes encodedVm) external -``` - -This function is called when the user redeems their token on L2. -The contract receives Wormhole tBTC representation and mints the -canonical tBTC for the user. -If the tBTC minting limit has been reached by this contract, -instead of minting tBTC the receiver address receives Wormhole -tBTC representation. - -Requirements: -- The receiver of Wormhole tBTC should be the L2WormholeGateway -contract. -- The receiver of the canonical tBTC should be abi-encoded in the -payload. -- The receiver of the canonical tBTC must not be the zero address. -The Wormhole Token Bridge contract has protection against redeeming -the same VAA again. When a Token Bridge VAA is redeemed, its -message body hash is stored in a map. This map is used to check -whether the hash has already been set in this map. For this reason, -this function does not have to be nonReentrant. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| encodedVm | bytes | A byte array containing a Wormhole VAA signed by the guardians. | - -### depositWormholeTbtc - -```solidity -function depositWormholeTbtc(uint256 amount) external -``` - -Allows to deposit Wormhole tBTC token in exchange for canonical -tBTC. Useful in a situation when user received wormhole tBTC -instead of canonical tBTC. One example of such situation is -when the minting limit was exceeded but the user minted anyway. - -Requirements: -- The sender must have at least `amount` of the Wormhole tBTC and -it has to be approved for L2WormholeGateway. -- The minting limit must allow for minting the given amount. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| amount | uint256 | The amount of Wormhole tBTC to deposit. | - -### updateGatewayAddress - -```solidity -function updateGatewayAddress(uint16 chainId, bytes32 gateway) external -``` - -Lets the governance to update the tBTC gateway address on the -chain with the given Wormhole ID. - -Use toWormholeAddress function to convert between Ethereum and -Wormhole address formats. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| chainId | uint16 | Wormhole ID of the chain. | -| gateway | bytes32 | Address of tBTC gateway on the given chain in a Wormhole format. | - -### updateMintingLimit - -```solidity -function updateMintingLimit(uint256 _mintingLimit) external -``` - -Lets the governance to update the tBTC minting limit for this -contract. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| _mintingLimit | uint256 | The new minting limit. | - -### toWormholeAddress - -```solidity -function toWormholeAddress(address _address) external pure returns (bytes32) -``` - -Converts Ethereum address into Wormhole format. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| _address | address | The address to convert. | - -### fromWormholeAddress - -```solidity -function fromWormholeAddress(bytes32 _address) public pure returns (address) -``` - -Converts Wormhole address into Ethereum format. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| _address | bytes32 | The address to convert. | - -### normalize - -```solidity -function normalize(uint256 amount) internal pure returns (uint256) -``` - -Eliminates the dust that cannot be bridged with Wormhole -due to the decimal shift in the Wormhole Bridge contract. -See https://github.com/wormhole-foundation/wormhole/blob/96682bdbeb7c87bfa110eade0554b3d8cbf788d2/ethereum/contracts/bridge/Bridge.sol#L276-L288 - -## MaintainerProxy - -Maintainers are the willing off-chain clients approved by the governance. -Maintainers proxy calls to the `Bridge` contract via 'MaintainerProxy' -and are refunded for the spent gas from the `ReimbursementPool`. -There are two types of maintainers: wallet maintainers and SPV -maintainers. - -### bridge - -```solidity -contract Bridge bridge -``` - -### isWalletMaintainer - -```solidity -mapping(address => uint256) isWalletMaintainer -``` - -Authorized wallet maintainers that can interact with the set of -functions for wallet maintainers only. Authorization can be -granted and removed by the governance. - -'Key' is the address of the maintainer. 'Value' represents an index+1 -in the 'maintainers' array. 1 was added so the maintainer index can -never be 0 which is a reserved index for a non-existent maintainer -in this map. - -### walletMaintainers - -```solidity -address[] walletMaintainers -``` - -This list of wallet maintainers keeps the order of which wallet -maintainer should be submitting a next transaction. It does not -enforce the order but only tracks who should be next in line. - -### isSpvMaintainer - -```solidity -mapping(address => uint256) isSpvMaintainer -``` - -Authorized SPV maintainers that can interact with the set of -functions for SPV maintainers only. Authorization can be -granted and removed by the governance. - -'Key' is the address of the maintainer. 'Value' represents an index+1 -in the 'maintainers' array. 1 was added so the maintainer index can -never be 0 which is a reserved index for a non-existent maintainer -in this map. - -### spvMaintainers - -```solidity -address[] spvMaintainers -``` - -This list of SPV maintainers keeps the order of which SPV -maintainer should be submitting a next transaction. It does not -enforce the order but only tracks who should be next in line. - -### submitDepositSweepProofGasOffset - -```solidity -uint256 submitDepositSweepProofGasOffset -``` - -Gas that is meant to balance the submission of deposit sweep proof -overall cost. Can be updated by the governance based on the current -market conditions. - -### submitRedemptionProofGasOffset - -```solidity -uint256 submitRedemptionProofGasOffset -``` - -Gas that is meant to balance the submission of redemption proof -overall cost. Can be updated by the governance based on the current -market conditions. - -### resetMovingFundsTimeoutGasOffset - -```solidity -uint256 resetMovingFundsTimeoutGasOffset -``` - -Gas that is meant to balance the reset of moving funds timeout -overall cost. Can be updated by the governance based on the current -market conditions. - -### submitMovingFundsProofGasOffset - -```solidity -uint256 submitMovingFundsProofGasOffset -``` - -Gas that is meant to balance the submission of moving funds proof -overall cost. Can be updated by the governance based on the current -market conditions. - -### notifyMovingFundsBelowDustGasOffset - -```solidity -uint256 notifyMovingFundsBelowDustGasOffset -``` - -Gas that is meant to balance the notification of moving funds below -dust overall cost. Can be updated by the governance based on the -current market conditions. - -### submitMovedFundsSweepProofGasOffset - -```solidity -uint256 submitMovedFundsSweepProofGasOffset -``` - -Gas that is meant to balance the submission of moved funds sweep -proof overall cost. Can be updated by the governance based on the -current market conditions. - -### requestNewWalletGasOffset - -```solidity -uint256 requestNewWalletGasOffset -``` - -Gas that is meant to balance the request of a new wallet overall -cost. Can be updated by the governance based on the current -market conditions. - -### notifyWalletCloseableGasOffset - -```solidity -uint256 notifyWalletCloseableGasOffset -``` - -Gas that is meant to balance the notification of closeable wallet -overall cost. Can be updated by the governance based on the current -market conditions. - -### notifyWalletClosingPeriodElapsedGasOffset - -```solidity -uint256 notifyWalletClosingPeriodElapsedGasOffset -``` - -Gas that is meant to balance the notification of wallet closing -period elapsed overall cost. Can be updated by the governance -based on the current market conditions. - -### defeatFraudChallengeGasOffset - -```solidity -uint256 defeatFraudChallengeGasOffset -``` - -Gas that is meant to balance the defeat fraud challenge -overall cost. Can be updated by the governance based on the current -market conditions. - -### defeatFraudChallengeWithHeartbeatGasOffset - -```solidity -uint256 defeatFraudChallengeWithHeartbeatGasOffset -``` - -Gas that is meant to balance the defeat fraud challenge with heartbeat -overall cost. Can be updated by the governance based on the current -market conditions. - -### WalletMaintainerAuthorized - -```solidity -event WalletMaintainerAuthorized(address maintainer) -``` - -### WalletMaintainerUnauthorized - -```solidity -event WalletMaintainerUnauthorized(address maintainer) -``` - -### SpvMaintainerAuthorized - -```solidity -event SpvMaintainerAuthorized(address maintainer) -``` - -### SpvMaintainerUnauthorized - -```solidity -event SpvMaintainerUnauthorized(address maintainer) -``` - -### BridgeUpdated - -```solidity -event BridgeUpdated(address newBridge) -``` - -### GasOffsetParametersUpdated - -```solidity -event GasOffsetParametersUpdated(uint256 submitDepositSweepProofGasOffset, uint256 submitRedemptionProofGasOffset, uint256 resetMovingFundsTimeoutGasOffset, uint256 submitMovingFundsProofGasOffset, uint256 notifyMovingFundsBelowDustGasOffset, uint256 submitMovedFundsSweepProofGasOffset, uint256 requestNewWalletGasOffset, uint256 notifyWalletCloseableGasOffset, uint256 notifyWalletClosingPeriodElapsedGasOffset, uint256 defeatFraudChallengeGasOffset, uint256 defeatFraudChallengeWithHeartbeatGasOffset) -``` - -### onlyWalletMaintainer - -```solidity -modifier onlyWalletMaintainer() -``` - -### onlySpvMaintainer - -```solidity -modifier onlySpvMaintainer() -``` - -### onlyReimbursableAdmin - -```solidity -modifier onlyReimbursableAdmin() -``` - -### constructor - -```solidity -constructor(contract Bridge _bridge, contract ReimbursementPool _reimbursementPool) public -``` - -### submitDepositSweepProof - -```solidity -function submitDepositSweepProof(struct BitcoinTx.Info sweepTx, struct BitcoinTx.Proof sweepProof, struct BitcoinTx.UTXO mainUtxo, address vault) external -``` - -Wraps `Bridge.submitDepositSweepProof` call and reimburses the -caller's transaction cost. - -See `Bridge.submitDepositSweepProof` function documentation. - -### submitRedemptionProof - -```solidity -function submitRedemptionProof(struct BitcoinTx.Info redemptionTx, struct BitcoinTx.Proof redemptionProof, struct BitcoinTx.UTXO mainUtxo, bytes20 walletPubKeyHash) external -``` - -Wraps `Bridge.submitRedemptionProof` call and reimburses the -caller's transaction cost. - -See `Bridge.submitRedemptionProof` function documentation. - -### resetMovingFundsTimeout - -```solidity -function resetMovingFundsTimeout(bytes20 walletPubKeyHash) external -``` - -Wraps `Bridge.resetMovingFundsTimeout` call and reimburses the -caller's transaction cost. - -See `Bridge.resetMovingFundsTimeout` function documentation. - -### submitMovingFundsProof - -```solidity -function submitMovingFundsProof(struct BitcoinTx.Info movingFundsTx, struct BitcoinTx.Proof movingFundsProof, struct BitcoinTx.UTXO mainUtxo, bytes20 walletPubKeyHash) external -``` - -Wraps `Bridge.submitMovingFundsProof` call and reimburses the -caller's transaction cost. - -See `Bridge.submitMovingFundsProof` function documentation. - -### notifyMovingFundsBelowDust - -```solidity -function notifyMovingFundsBelowDust(bytes20 walletPubKeyHash, struct BitcoinTx.UTXO mainUtxo) external -``` - -Wraps `Bridge.notifyMovingFundsBelowDust` call and reimburses the -caller's transaction cost. - -See `Bridge.notifyMovingFundsBelowDust` function documentation. - -### submitMovedFundsSweepProof - -```solidity -function submitMovedFundsSweepProof(struct BitcoinTx.Info sweepTx, struct BitcoinTx.Proof sweepProof, struct BitcoinTx.UTXO mainUtxo) external -``` - -Wraps `Bridge.submitMovedFundsSweepProof` call and reimburses the -caller's transaction cost. - -See `Bridge.submitMovedFundsSweepProof` function documentation. - -### requestNewWallet - -```solidity -function requestNewWallet(struct BitcoinTx.UTXO activeWalletMainUtxo) external -``` - -Wraps `Bridge.requestNewWallet` call and reimburses the -caller's transaction cost. - -See `Bridge.requestNewWallet` function documentation. - -### notifyWalletCloseable - -```solidity -function notifyWalletCloseable(bytes20 walletPubKeyHash, struct BitcoinTx.UTXO walletMainUtxo) external -``` - -Wraps `Bridge.notifyWalletCloseable` call and reimburses the -caller's transaction cost. - -See `Bridge.notifyWalletCloseable` function documentation. - -### notifyWalletClosingPeriodElapsed - -```solidity -function notifyWalletClosingPeriodElapsed(bytes20 walletPubKeyHash) external -``` - -Wraps `Bridge.notifyWalletClosingPeriodElapsed` call and reimburses -the caller's transaction cost. - -See `Bridge.notifyWalletClosingPeriodElapsed` function documentation. - -### defeatFraudChallenge - -```solidity -function defeatFraudChallenge(bytes walletPublicKey, bytes preimage, bool witness) external -``` - -Wraps `Bridge.defeatFraudChallenge` call and reimburses the -caller's transaction cost. - -See `Bridge.defeatFraudChallenge` function documentation. - -### defeatFraudChallengeWithHeartbeat - -```solidity -function defeatFraudChallengeWithHeartbeat(bytes walletPublicKey, bytes heartbeatMessage) external -``` - -Wraps `Bridge.defeatFraudChallengeWithHeartbeat` call and -reimburses the caller's transaction cost. - -See `Bridge.defeatFraudChallengeWithHeartbeat` function documentation. - -### authorizeWalletMaintainer - -```solidity -function authorizeWalletMaintainer(address maintainer) external -``` - -Authorize a wallet maintainer that can interact with this -reimbursement pool. Can be authorized by the owner only. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| maintainer | address | Wallet maintainer to authorize. | - -### authorizeSpvMaintainer - -```solidity -function authorizeSpvMaintainer(address maintainer) external -``` - -Authorize an SPV maintainer that can interact with this -reimbursement pool. Can be authorized by the owner only. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| maintainer | address | SPV maintainer to authorize. | - -### unauthorizeWalletMaintainer - -```solidity -function unauthorizeWalletMaintainer(address maintainerToUnauthorize) external -``` - -Unauthorize a wallet maintainer that was previously authorized to -interact with the Maintainer Proxy contract. Can be unauthorized -by the owner only. - -The last maintainer is swapped with the one to be unauthorized. -The unauthorized maintainer is then removed from the list. An index -of the last maintainer is changed with the removed maintainer. -Ex. -'walletMaintainers' list: [0x1, 0x2, 0x3, 0x4, 0x5] -'isWalletMaintainer' map: [0x1 -> 1, 0x2 -> 2, 0x3 -> 3, 0x4 -> 4, 0x5 -> 5] -unauthorize: 0x3 -new 'walletMaintainers' list: [0x1, 0x2, 0x5, 0x4] -new 'isWalletMaintainer' map: [0x1 -> 1, 0x2 -> 2, 0x4 -> 4, 0x5 -> 3] - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| maintainerToUnauthorize | address | Maintainer to unauthorize. | - -### unauthorizeSpvMaintainer - -```solidity -function unauthorizeSpvMaintainer(address maintainerToUnauthorize) external -``` - -Unauthorize an SPV maintainer that was previously authorized to -interact with the Maintainer Proxy contract. Can be unauthorized -by the owner only. - -The last maintainer is swapped with the one to be unauthorized. -The unauthorized maintainer is then removed from the list. An index -of the last maintainer is changed with the removed maintainer. -Ex. -'spvMaintainers' list: [0x1, 0x2, 0x3, 0x4, 0x5] -'isSpvMaintainer' map: [0x1 -> 1, 0x2 -> 2, 0x3 -> 3, 0x4 -> 4, 0x5 -> 5] -unauthorize: 0x3 -new 'spvMaintainers' list: [0x1, 0x2, 0x5, 0x4] -new 'isSpvMaintainer' map: [0x1 -> 1, 0x2 -> 2, 0x4 -> 4, 0x5 -> 3] - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| maintainerToUnauthorize | address | Maintainer to unauthorize. | - -### updateBridge - -```solidity -function updateBridge(contract Bridge _bridge) external -``` - -Allows the Governance to upgrade the Bridge address. - -The function does not implement any governance delay and does not -check the status of the Bridge. The Governance implementation needs -to ensure all requirements for the upgrade are satisfied before -executing this function. - -### updateGasOffsetParameters - -```solidity -function updateGasOffsetParameters(uint256 newSubmitDepositSweepProofGasOffset, uint256 newSubmitRedemptionProofGasOffset, uint256 newResetMovingFundsTimeoutGasOffset, uint256 newSubmitMovingFundsProofGasOffset, uint256 newNotifyMovingFundsBelowDustGasOffset, uint256 newSubmitMovedFundsSweepProofGasOffset, uint256 newRequestNewWalletGasOffset, uint256 newNotifyWalletCloseableGasOffset, uint256 newNotifyWalletClosingPeriodElapsedGasOffset, uint256 newDefeatFraudChallengeGasOffset, uint256 newDefeatFraudChallengeWithHeartbeatGasOffset) external -``` - -Updates the values of gas offset parameters. - -Can be called only by the contract owner. The caller is responsible -for validating parameters. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| newSubmitDepositSweepProofGasOffset | uint256 | New submit deposit sweep proof gas offset. | -| newSubmitRedemptionProofGasOffset | uint256 | New submit redemption proof gas offset. | -| newResetMovingFundsTimeoutGasOffset | uint256 | New reset moving funds timeout gas offset. | -| newSubmitMovingFundsProofGasOffset | uint256 | New submit moving funds proof gas offset. | -| newNotifyMovingFundsBelowDustGasOffset | uint256 | New notify moving funds below dust gas offset. | -| newSubmitMovedFundsSweepProofGasOffset | uint256 | New submit moved funds sweep proof gas offset. | -| newRequestNewWalletGasOffset | uint256 | New request new wallet gas offset. | -| newNotifyWalletCloseableGasOffset | uint256 | New notify closeable wallet gas offset. | -| newNotifyWalletClosingPeriodElapsedGasOffset | uint256 | New notify wallet closing period elapsed gas offset. | -| newDefeatFraudChallengeGasOffset | uint256 | New defeat fraud challenge gas offset. | -| newDefeatFraudChallengeWithHeartbeatGasOffset | uint256 | New defeat fraud challenge with heartbeat gas offset. | - -### allWalletMaintainers - -```solidity -function allWalletMaintainers() external view returns (address[]) -``` - -Gets an entire array of wallet maintainer addresses. - -### allSpvMaintainers - -```solidity -function allSpvMaintainers() external view returns (address[]) -``` - -Gets an entire array of SPV maintainer addresses. - -## Epoch - -```solidity -struct Epoch { - uint32 timestamp; - uint224 target; -} -``` - -## ILightRelay - -### Genesis - -```solidity -event Genesis(uint256 blockHeight) -``` - -### Retarget - -```solidity -event Retarget(uint256 oldDifficulty, uint256 newDifficulty) -``` - -### ProofLengthChanged - -```solidity -event ProofLengthChanged(uint256 newLength) -``` - -### AuthorizationRequirementChanged - -```solidity -event AuthorizationRequirementChanged(bool newStatus) -``` - -### SubmitterAuthorized - -```solidity -event SubmitterAuthorized(address submitter) -``` - -### SubmitterDeauthorized - -```solidity -event SubmitterDeauthorized(address submitter) -``` - -### retarget - -```solidity -function retarget(bytes headers) external -``` - -### validateChain - -```solidity -function validateChain(bytes headers) external view returns (uint256 startingHeaderTimestamp, uint256 headerCount) -``` - -### getBlockDifficulty - -```solidity -function getBlockDifficulty(uint256 blockNumber) external view returns (uint256) -``` - -### getEpochDifficulty - -```solidity -function getEpochDifficulty(uint256 epochNumber) external view returns (uint256) -``` - -### getRelayRange - -```solidity -function getRelayRange() external view returns (uint256 relayGenesis, uint256 currentEpochEnd) -``` - -## RelayUtils - -### extractTimestampAt - -```solidity -function extractTimestampAt(bytes headers, uint256 at) internal pure returns (uint32) -``` - -Extract the timestamp of the header at the given position. - -Assumes that the specified position contains a valid header. -Performs no validation whatsoever. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| headers | bytes | Byte array containing the header of interest. | -| at | uint256 | The start of the header in the array. | - -#### Return Values - -| Name | Type | Description | -| ---- | ---- | ----------- | -| [0] | uint32 | The timestamp of the header. | - -## LightRelay - -THE RELAY MUST NOT BE USED BEFORE GENESIS AND AT LEAST ONE RETARGET. - -### ready - -```solidity -bool ready -``` - -### authorizationRequired - -```solidity -bool authorizationRequired -``` - -### proofLength - -```solidity -uint64 proofLength -``` - -### genesisEpoch - -```solidity -uint64 genesisEpoch -``` - -### currentEpoch - -```solidity -uint64 currentEpoch -``` - -### currentEpochDifficulty - -```solidity -uint256 currentEpochDifficulty -``` - -### prevEpochDifficulty - -```solidity -uint256 prevEpochDifficulty -``` - -### epochs - -```solidity -mapping(uint256 => struct Epoch) epochs -``` - -### isAuthorized - -```solidity -mapping(address => bool) isAuthorized -``` - -### relayActive - -```solidity -modifier relayActive() -``` - -### genesis - -```solidity -function genesis(bytes genesisHeader, uint256 genesisHeight, uint64 genesisProofLength) external -``` - -Establish a starting point for the relay by providing the -target, timestamp and blockheight of the first block of the relay -genesis epoch. - -If the relay is used by querying the current and previous epoch -difficulty, at least one retarget needs to be provided after genesis; -otherwise the prevEpochDifficulty will be uninitialised and zero. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| genesisHeader | bytes | The first block header of the genesis epoch. | -| genesisHeight | uint256 | The block number of the first block of the epoch. | -| genesisProofLength | uint64 | The number of blocks required to accept a proof. | - -### setProofLength - -```solidity -function setProofLength(uint64 newLength) external -``` - -Set the number of blocks required to accept a header chain. - -For production, a high number (e.g. 20-50) is recommended. -Small numbers are accepted but should only be used for testing. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| newLength | uint64 | The required number of blocks. Must be less than 2016. | - -### setAuthorizationStatus - -```solidity -function setAuthorizationStatus(bool status) external -``` - -Set whether the relay requires retarget submitters to be -pre-authorised by governance. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| status | bool | True if authorisation is to be required, false if not. | - -### authorize - -```solidity -function authorize(address submitter) external -``` - -Authorise the given address to submit retarget proofs. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| submitter | address | The address to be authorised. | - -### deauthorize - -```solidity -function deauthorize(address submitter) external -``` - -Rescind the authorisation of the submitter to retarget. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| submitter | address | The address to be deauthorised. | - -### retarget - -```solidity -function retarget(bytes headers) external -``` - -Add a new epoch to the relay by providing a proof -of the difficulty before and after the retarget. - -Checks that the first X blocks are valid in the most recent epoch, -that the difficulty of the new epoch is calculated correctly according -to the block timestamps, and that the next X blocks would be valid in -the new epoch. -We have no information of block heights, so we cannot enforce that -retargets only happen every 2016 blocks; instead, we assume that this -is the case if a valid proof of work is provided. -It is possible to cheat the relay by providing X blocks from earlier in -the most recent epoch, and then mining X new blocks after them. -However, each of these malicious blocks would have to be mined to a -higher difficulty than the legitimate ones. -Alternatively, if the retarget has not been performed yet, one could -first mine X blocks in the old difficulty with timestamps set far in -the future, and then another X blocks at a greatly reduced difficulty. -In either case, cheating the realy requires more work than mining X -legitimate blocks. -Only the most recent epoch is vulnerable to these attacks; once a -retarget has been proven to the relay, the epoch is immutable even if a -contradictory proof were to be presented later. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| headers | bytes | A chain of headers including the last X blocks before the retarget, followed by the first X blocks after the retarget, where X equals the current proof length. | - -### validateChain - -```solidity -function validateChain(bytes headers) external view returns (uint256 startingHeaderTimestamp, uint256 headerCount) -``` - -Check whether a given chain of headers should be accepted as -valid within the rules of the relay. -If the validation fails, this function throws an exception. - -A chain of headers is accepted as valid if: -- Its length is between 2 and 2015 headers. -- Headers in the chain are sequential and refer to previous digests. -- Each header is mined with the correct amount of work. -- The difficulty in each header matches an epoch of the relay, -as determined by the headers' timestamps. The headers must be between -the genesis epoch and the latest proven epoch (inclusive). -If the chain contains a retarget, it is accepted if the retarget has -already been proven to the relay. -If the chain contains blocks of an epoch that has not been proven to -the relay (after a retarget within the header chain, or when the entire -chain falls within an epoch that has not been proven yet), it will be -rejected. -One exception to this is when two subsequent epochs have exactly the -same difficulty; headers from the latter epoch will be accepted if the -previous epoch has been proven to the relay. -This is because it is not possible to distinguish such headers from -headers of the previous epoch. - -If the difficulty increases significantly between relay genesis and the -present, creating fraudulent proofs for earlier epochs becomes easier. -Users of the relay should check the timestamps of valid headers and -only accept appropriately recent ones. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| headers | bytes | A chain of 2 to 2015 bitcoin headers. | - -#### Return Values - -| Name | Type | Description | -| ---- | ---- | ----------- | -| startingHeaderTimestamp | uint256 | The timestamp of the first header. | -| headerCount | uint256 | The number of headers. | - -### getBlockDifficulty - -```solidity -function getBlockDifficulty(uint256 blockNumber) external view returns (uint256) -``` - -Get the difficulty of the specified block. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| blockNumber | uint256 | The number of the block. Must fall within the relay range (at or after the relay genesis, and at or before the end of the most recent epoch proven to the relay). | - -#### Return Values - -| Name | Type | Description | -| ---- | ---- | ----------- | -| [0] | uint256 | The difficulty of the epoch. | - -### getRelayRange - -```solidity -function getRelayRange() external view returns (uint256 relayGenesis, uint256 currentEpochEnd) -``` - -Get the range of blocks the relay can accept proofs for. - -Assumes that the genesis has been set correctly. -Additionally, if the next epoch after the current one has the exact -same difficulty, headers for it can be validated as well. -This function should be used for informative purposes, -e.g. to determine whether a retarget must be provided before submitting -a header chain for validation. - -#### Return Values - -| Name | Type | Description | -| ---- | ---- | ----------- | -| relayGenesis | uint256 | The height of the earliest block that can be included in header chains for the relay to validate. | -| currentEpochEnd | uint256 | The height of the last block that can be included in header chains for the relay to validate. | - -### getCurrentEpochDifficulty - -```solidity -function getCurrentEpochDifficulty() external view virtual returns (uint256) -``` - -Returns the difficulty of the current epoch. - -returns 0 if the relay is not ready. - -#### Return Values - -| Name | Type | Description | -| ---- | ---- | ----------- | -| [0] | uint256 | The difficulty of the current epoch. | - -### getPrevEpochDifficulty - -```solidity -function getPrevEpochDifficulty() external view virtual returns (uint256) -``` - -Returns the difficulty of the previous epoch. - -Returns 0 if the relay is not ready or has not had a retarget. - -#### Return Values - -| Name | Type | Description | -| ---- | ---- | ----------- | -| [0] | uint256 | The difficulty of the previous epoch. | - -### getCurrentAndPrevEpochDifficulty - -```solidity -function getCurrentAndPrevEpochDifficulty() external view returns (uint256 current, uint256 previous) -``` - -### getEpochDifficulty - -```solidity -function getEpochDifficulty(uint256 epochNumber) public view returns (uint256) -``` - -Get the difficulty of the specified epoch. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| epochNumber | uint256 | The number of the epoch (the height of the first block of the epoch, divided by 2016). Must fall within the relay range. | - -#### Return Values - -| Name | Type | Description | -| ---- | ---- | ----------- | -| [0] | uint256 | The difficulty of the epoch. | - -### validateHeader - -```solidity -function validateHeader(bytes headers, uint256 start, bytes32 prevDigest) internal view returns (bytes32 digest, uint256 target) -``` - -Check that the specified header forms a correct chain with the -digest of the previous header (if provided), and has sufficient work. - -Throws an exception if the header's chain or PoW are invalid. -Performs no other validation. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| headers | bytes | The byte array containing the header of interest. | -| start | uint256 | The start of the header in the array. | -| prevDigest | bytes32 | The digest of the previous header (optional; providing zeros for the digest skips the check). | - -#### Return Values - -| Name | Type | Description | -| ---- | ---- | ----------- | -| digest | bytes32 | The digest of the current header. | -| target | uint256 | The PoW target of the header. | - -## LightRelayMaintainerProxy - -The proxy contract that allows the relay maintainers to be refunded -for the spent gas from the `ReimbursementPool`. When proving the -next Bitcoin difficulty epoch, the maintainer calls the -`LightRelayMaintainerProxy` which in turn calls the actual `LightRelay` -contract. - -### lightRelay - -```solidity -contract ILightRelay lightRelay -``` - -### isAuthorized - -```solidity -mapping(address => bool) isAuthorized -``` - -Stores the addresses that can maintain the relay. Those -addresses are attested by the DAO. - -The goal is to prevent a griefing attack by frontrunning relay -maintainer which is responsible for retargetting the relay in the -given round. The maintainer's transaction would revert with no gas -refund. Having the ability to restrict maintainer addresses is also -important in case the underlying relay contract has authorization -requirements for callers. - -### retargetGasOffset - -```solidity -uint256 retargetGasOffset -``` - -Gas that is meant to balance the retarget overall cost. Can be - -### LightRelayUpdated - -```solidity -event LightRelayUpdated(address newRelay) -``` - -### MaintainerAuthorized - -```solidity -event MaintainerAuthorized(address maintainer) -``` - -### MaintainerDeauthorized - -```solidity -event MaintainerDeauthorized(address maintainer) -``` - -### RetargetGasOffsetUpdated - -```solidity -event RetargetGasOffsetUpdated(uint256 retargetGasOffset) -``` - -### onlyRelayMaintainer - -```solidity -modifier onlyRelayMaintainer() -``` - -### onlyReimbursableAdmin - -```solidity -modifier onlyReimbursableAdmin() -``` - -### constructor - -```solidity -constructor(contract ILightRelay _lightRelay, contract ReimbursementPool _reimbursementPool) public -``` - -### updateLightRelay - -```solidity -function updateLightRelay(contract ILightRelay _lightRelay) external -``` - -Allows the governance to upgrade the `LightRelay` address. - -The function does not implement any governance delay and does not -check the status of the `LightRelay`. The Governance implementation -needs to ensure all requirements for the upgrade are satisfied -before executing this function. - -### authorize - -```solidity -function authorize(address maintainer) external -``` - -Authorizes the given address as a maintainer. Can only be called -by the owner and the address of the maintainer must not be -already authorized. - -The function does not implement any governance delay. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| maintainer | address | The address of the maintainer to be authorized. | - -### deauthorize - -```solidity -function deauthorize(address maintainer) external -``` - -Deauthorizes the given address as a maintainer. Can only be -called by the owner and the address of the maintainer must be -authorized. - -The function does not implement any governance delay. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| maintainer | address | The address of the maintainer to be deauthorized. | - -### updateRetargetGasOffset - -```solidity -function updateRetargetGasOffset(uint256 newRetargetGasOffset) external -``` - -Updates the values of retarget gas offset. - -Can be called only by the contract owner. The caller is responsible -for validating the parameter. The function does not implement any -governance delay. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| newRetargetGasOffset | uint256 | New retarget gas offset. | - -### retarget - -```solidity -function retarget(bytes headers) external -``` - -Wraps `LightRelay.retarget` call and reimburses the caller's -transaction cost. Can only be called by an authorized relay -maintainer. - -See `LightRelay.retarget` function documentation. - -## TBTC - -### constructor - -```solidity -constructor() public -``` - -## DonationVault - -Vault that allows making BTC donations to the system. Upon deposit, -this vault does not increase depositors' balances and always -decreases its own balance in the same transaction. The vault also -allows making donations using existing Bank balances. - -BEWARE: ALL BTC DEPOSITS TARGETING THIS VAULT ARE NOT REDEEMABLE -AND THERE IS NO WAY TO RESTORE THE DONATED BALANCE. -USE THIS VAULT ONLY WHEN YOU REALLY KNOW WHAT YOU ARE DOING! - -### bank - -```solidity -contract Bank bank -``` - -### DonationReceived - -```solidity -event DonationReceived(address donor, uint256 donatedAmount) -``` - -### onlyBank - -```solidity -modifier onlyBank() -``` - -### constructor - -```solidity -constructor(contract Bank _bank) public -``` - -### donate - -```solidity -function donate(uint256 amount) external -``` - -Transfers the given `amount` of the Bank balance from the -caller to the Donation Vault and immediately decreases the -vault's balance in the Bank by the transferred `amount`. - -Requirements: -- The caller's balance in the Bank must be greater than or equal -to the `amount`, -- Donation Vault must have an allowance for caller's balance in -the Bank for at least `amount`. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| amount | uint256 | Amount of the Bank balance to donate. | - -### receiveBalanceApproval - -```solidity -function receiveBalanceApproval(address owner, uint256 amount, bytes) external -``` - -Transfers the given `amount` of the Bank balance from the -`owner` to the Donation Vault and immediately decreases the -vault's balance in the Bank by the transferred `amount`. - -Requirements: -- Can only be called by the Bank via `approveBalanceAndCall`, -- The `owner` balance in the Bank must be greater than or equal -to the `amount`. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| owner | address | Address of the Bank balance owner who approved their balance to be used by the vault. | -| amount | uint256 | The amount of the Bank balance approved by the owner to be used by the vault. | -| | bytes | | - -### receiveBalanceIncrease - -```solidity -function receiveBalanceIncrease(address[] depositors, uint256[] depositedAmounts) external -``` - -Ignores the deposited amounts and does not increase depositors' -individual balances. The vault decreases its own tBTC balance -in the Bank by the total deposited amount. - -Requirements: -- Can only be called by the Bank after the Bridge swept deposits -and Bank increased balance for the vault, -- The `depositors` array must not be empty, -- The `depositors` array length must be equal to the -`depositedAmounts` array length. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| depositors | address[] | Addresses of depositors whose deposits have been swept. | -| depositedAmounts | uint256[] | Amounts deposited by individual depositors and swept. | - -## TBTCOptimisticMinting - -The Optimistic Minting mechanism allows to mint TBTC before -`TBTCVault` receives the Bank balance. There are two permissioned -sets in the system: Minters and Guardians, both set up in 1-of-n -mode. Minters observe the revealed deposits and request minting TBTC. -Any single Minter can perform this action. There is an -`optimisticMintingDelay` between the time of the request from -a Minter to the time TBTC is minted. During the time of the delay, -any Guardian can cancel the minting. - -This functionality is a part of `TBTCVault`. It is implemented in -a separate abstract contract to achieve better separation of concerns -and easier-to-follow code. - -### OptimisticMintingRequest - -```solidity -struct OptimisticMintingRequest { - uint64 requestedAt; - uint64 finalizedAt; -} -``` - -### GOVERNANCE_DELAY - -```solidity -uint256 GOVERNANCE_DELAY -``` - -The time delay that needs to pass between initializing and -finalizing the upgrade of governable parameters. - -### SATOSHI_MULTIPLIER - -```solidity -uint256 SATOSHI_MULTIPLIER -``` - -Multiplier to convert satoshi to TBTC token units. - -### bridge - -```solidity -contract Bridge bridge -``` - -### isOptimisticMintingPaused - -```solidity -bool isOptimisticMintingPaused -``` - -Indicates if the optimistic minting has been paused. Only the -Governance can pause optimistic minting. Note that the pause of -the optimistic minting does not stop the standard minting flow -where wallets sweep deposits. - -### optimisticMintingFeeDivisor - -```solidity -uint32 optimisticMintingFeeDivisor -``` - -Divisor used to compute the treasury fee taken from each -optimistically minted deposit and transferred to the treasury -upon finalization of the optimistic mint. This fee is computed -as follows: `fee = amount / optimisticMintingFeeDivisor`. -For example, if the fee needs to be 2%, the -`optimisticMintingFeeDivisor` should be set to `50` because -`1/50 = 0.02 = 2%`. -The optimistic minting fee does not replace the deposit treasury -fee cut by the Bridge. The optimistic fee is a percentage AFTER -the treasury fee is cut: -`optimisticMintingFee = (depositAmount - treasuryFee) / optimisticMintingFeeDivisor` - -### optimisticMintingDelay - -```solidity -uint32 optimisticMintingDelay -``` - -The time that needs to pass between the moment the optimistic -minting is requested and the moment optimistic minting is -finalized with minting TBTC. - -### isMinter - -```solidity -mapping(address => bool) isMinter -``` - -Indicates if the given address is a Minter. Only Minters can -request optimistic minting. - -### minters - -```solidity -address[] minters -``` - -List of all Minters. - -May be used to establish an order in which the Minters should -request for an optimistic minting. - -### isGuardian - -```solidity -mapping(address => bool) isGuardian -``` - -Indicates if the given address is a Guardian. Only Guardians can -cancel requested optimistic minting. - -### optimisticMintingRequests - -```solidity -mapping(uint256 => struct TBTCOptimisticMinting.OptimisticMintingRequest) optimisticMintingRequests -``` - -Collection of all revealed deposits for which the optimistic -minting was requested. Indexed by a deposit key computed as -`keccak256(fundingTxHash | fundingOutputIndex)`. - -### optimisticMintingDebt - -```solidity -mapping(address => uint256) optimisticMintingDebt -``` - -Optimistic minting debt value per depositor's address. The debt -represents the total value of all depositor's deposits revealed -to the Bridge that has not been yet swept and led to the -optimistic minting of TBTC. When `TBTCVault` sweeps a deposit, -the debt is fully or partially paid off, no matter if that -particular swept deposit was used for the optimistic minting or -not. The values are in 1e18 Ethereum precision. - -### newOptimisticMintingFeeDivisor - -```solidity -uint32 newOptimisticMintingFeeDivisor -``` - -New optimistic minting fee divisor value. Set only when the -parameter update process is pending. Once the update gets - -### optimisticMintingFeeUpdateInitiatedTimestamp - -```solidity -uint256 optimisticMintingFeeUpdateInitiatedTimestamp -``` - -The timestamp at which the update of the optimistic minting fee -divisor started. Zero if update is not in progress. - -### newOptimisticMintingDelay - -```solidity -uint32 newOptimisticMintingDelay -``` - -New optimistic minting delay value. Set only when the parameter -update process is pending. Once the update gets finalized, this - -### optimisticMintingDelayUpdateInitiatedTimestamp - -```solidity -uint256 optimisticMintingDelayUpdateInitiatedTimestamp -``` - -The timestamp at which the update of the optimistic minting -delay started. Zero if update is not in progress. - -### OptimisticMintingRequested - -```solidity -event OptimisticMintingRequested(address minter, uint256 depositKey, address depositor, uint256 amount, bytes32 fundingTxHash, uint32 fundingOutputIndex) -``` - -### OptimisticMintingFinalized - -```solidity -event OptimisticMintingFinalized(address minter, uint256 depositKey, address depositor, uint256 optimisticMintingDebt) -``` - -### OptimisticMintingCancelled - -```solidity -event OptimisticMintingCancelled(address guardian, uint256 depositKey) -``` - -### OptimisticMintingDebtRepaid - -```solidity -event OptimisticMintingDebtRepaid(address depositor, uint256 optimisticMintingDebt) -``` - -### MinterAdded - -```solidity -event MinterAdded(address minter) -``` - -### MinterRemoved - -```solidity -event MinterRemoved(address minter) -``` - -### GuardianAdded - -```solidity -event GuardianAdded(address guardian) -``` - -### GuardianRemoved - -```solidity -event GuardianRemoved(address guardian) -``` - -### OptimisticMintingPaused - -```solidity -event OptimisticMintingPaused() -``` - -### OptimisticMintingUnpaused - -```solidity -event OptimisticMintingUnpaused() -``` - -### OptimisticMintingFeeUpdateStarted - -```solidity -event OptimisticMintingFeeUpdateStarted(uint32 newOptimisticMintingFeeDivisor) -``` - -### OptimisticMintingFeeUpdated - -```solidity -event OptimisticMintingFeeUpdated(uint32 newOptimisticMintingFeeDivisor) -``` - -### OptimisticMintingDelayUpdateStarted - -```solidity -event OptimisticMintingDelayUpdateStarted(uint32 newOptimisticMintingDelay) -``` - -### OptimisticMintingDelayUpdated - -```solidity -event OptimisticMintingDelayUpdated(uint32 newOptimisticMintingDelay) -``` - -### onlyMinter - -```solidity -modifier onlyMinter() -``` - -### onlyGuardian - -```solidity -modifier onlyGuardian() -``` - -### onlyOwnerOrGuardian - -```solidity -modifier onlyOwnerOrGuardian() -``` - -### whenOptimisticMintingNotPaused - -```solidity -modifier whenOptimisticMintingNotPaused() -``` - -### onlyAfterGovernanceDelay - -```solidity -modifier onlyAfterGovernanceDelay(uint256 updateInitiatedTimestamp) -``` - -### constructor - -```solidity -constructor(contract Bridge _bridge) internal -``` - -### _mint - -```solidity -function _mint(address minter, uint256 amount) internal virtual -``` - -Mints the given amount of TBTC to the given depositor's address. -Implemented by TBTCVault. - -### getMinters - -```solidity -function getMinters() external view returns (address[]) -``` - -Allows to fetch a list of all Minters. - -### requestOptimisticMint - -```solidity -function requestOptimisticMint(bytes32 fundingTxHash, uint32 fundingOutputIndex) external -``` - -Allows a Minter to request for an optimistic minting of TBTC. -The following conditions must be met: -- There is no optimistic minting request for the deposit, -finalized or not. -- The deposit with the given Bitcoin funding transaction hash -and output index has been revealed to the Bridge. -- The deposit has not been swept yet. -- The deposit is targeted into the TBTCVault. -- The optimistic minting is not paused. -After calling this function, the Minter has to wait for -`optimisticMintingDelay` before finalizing the mint with a call -to finalizeOptimisticMint. - -The deposit done on the Bitcoin side must be revealed early enough -to the Bridge on Ethereum to pass the Bridge's validation. The -validation passes successfully only if the deposit reveal is done -respectively earlier than the moment when the deposit refund -locktime is reached, i.e. the deposit becomes refundable. It may -happen that the wallet does not sweep a revealed deposit and one of -the Minters requests an optimistic mint for that deposit just -before the locktime is reached. Guardians must cancel optimistic -minting for this deposit because the wallet will not be able to -sweep it. The on-chain optimistic minting code does not perform any -validation for gas efficiency: it would have to perform the same -validation as `validateDepositRefundLocktime` and expect the entire -`DepositRevealInfo` to be passed to assemble the expected script -hash on-chain. Guardians must validate if the deposit happened on -Bitcoin, that the script hash has the expected format, and that the -wallet is an active one so they can also validate the time left for -the refund. - -### finalizeOptimisticMint - -```solidity -function finalizeOptimisticMint(bytes32 fundingTxHash, uint32 fundingOutputIndex) external -``` - -Allows a Minter to finalize previously requested optimistic -minting. The following conditions must be met: -- The optimistic minting has been requested for the given -deposit. -- The deposit has not been swept yet. -- At least `optimisticMintingDelay` passed since the optimistic -minting was requested for the given deposit. -- The optimistic minting has not been finalized earlier for the -given deposit. -- The optimistic minting request for the given deposit has not -been canceled by a Guardian. -- The optimistic minting is not paused. -This function mints TBTC and increases `optimisticMintingDebt` -for the given depositor. The optimistic minting request is -marked as finalized. - -### cancelOptimisticMint - -```solidity -function cancelOptimisticMint(bytes32 fundingTxHash, uint32 fundingOutputIndex) external -``` - -Allows a Guardian to cancel optimistic minting request. The -following conditions must be met: -- The optimistic minting request for the given deposit exists. -- The optimistic minting request for the given deposit has not -been finalized yet. -Optimistic minting request is removed. It is possible to request -optimistic minting again for the same deposit later. - -Guardians must validate the following conditions for every deposit -for which the optimistic minting was requested: -- The deposit happened on Bitcoin side and it has enough -confirmations. -- The optimistic minting has been requested early enough so that -the wallet has enough time to sweep the deposit. -- The wallet is an active one and it does perform sweeps or it will -perform sweeps once the sweeps are activated. - -### addMinter - -```solidity -function addMinter(address minter) external -``` - -Adds the address to the Minter list. - -### removeMinter - -```solidity -function removeMinter(address minter) external -``` - -Removes the address from the Minter list. - -### addGuardian - -```solidity -function addGuardian(address guardian) external -``` - -Adds the address to the Guardian set. - -### removeGuardian - -```solidity -function removeGuardian(address guardian) external -``` - -Removes the address from the Guardian set. - -### pauseOptimisticMinting - -```solidity -function pauseOptimisticMinting() external -``` - -Pauses the optimistic minting. Note that the pause of the -optimistic minting does not stop the standard minting flow -where wallets sweep deposits. - -### unpauseOptimisticMinting - -```solidity -function unpauseOptimisticMinting() external -``` - -Unpauses the optimistic minting. - -### beginOptimisticMintingFeeUpdate - -```solidity -function beginOptimisticMintingFeeUpdate(uint32 _newOptimisticMintingFeeDivisor) external -``` - -Begins the process of updating optimistic minting fee. -The fee is computed as follows: -`fee = amount / optimisticMintingFeeDivisor`. -For example, if the fee needs to be 2% of each deposit, -the `optimisticMintingFeeDivisor` should be set to `50` because -`1/50 = 0.02 = 2%`. - -See the documentation for optimisticMintingFeeDivisor. - -### finalizeOptimisticMintingFeeUpdate - -```solidity -function finalizeOptimisticMintingFeeUpdate() external -``` - -Finalizes the update process of the optimistic minting fee. - -### beginOptimisticMintingDelayUpdate - -```solidity -function beginOptimisticMintingDelayUpdate(uint32 _newOptimisticMintingDelay) external -``` - -Begins the process of updating optimistic minting delay. - -### finalizeOptimisticMintingDelayUpdate - -```solidity -function finalizeOptimisticMintingDelayUpdate() external -``` - -Finalizes the update process of the optimistic minting delay. - -### calculateDepositKey - -```solidity -function calculateDepositKey(bytes32 fundingTxHash, uint32 fundingOutputIndex) public pure returns (uint256) -``` - -Calculates deposit key the same way as the Bridge contract. -The deposit key is computed as -`keccak256(fundingTxHash | fundingOutputIndex)`. - -### repayOptimisticMintingDebt - -```solidity -function repayOptimisticMintingDebt(address depositor, uint256 amount) internal returns (uint256) -``` - -Used by `TBTCVault.receiveBalanceIncrease` to repay the optimistic -minting debt before TBTC is minted. When optimistic minting is -finalized, debt equal to the value of the deposit being -a subject of the optimistic minting is incurred. When `TBTCVault` -sweeps a deposit, the debt is fully or partially paid off, no -matter if that particular deposit was used for the optimistic -minting or not. - -See `TBTCVault.receiveBalanceIncrease` - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| depositor | address | The depositor whose balance increase is received. | -| amount | uint256 | The balance increase amount for the depositor received. | - -#### Return Values - -| Name | Type | Description | -| ---- | ---- | ----------- | -| [0] | uint256 | The TBTC amount that should be minted after paying off the optimistic minting debt. | - -## TBTCVault - -TBTC is a fully Bitcoin-backed ERC-20 token pegged to the price of -Bitcoin. It facilitates Bitcoin holders to act on the Ethereum -blockchain and access the decentralized finance (DeFi) ecosystem. -TBTC Vault mints and unmints TBTC based on Bitcoin balances in the -Bank. - -TBTC Vault is the owner of TBTC token contract and is the only contract -minting the token. - -### bank - -```solidity -contract Bank bank -``` - -### tbtcToken - -```solidity -contract TBTC tbtcToken -``` - -### newVault - -```solidity -address newVault -``` - -The address of a new TBTC vault. Set only when the upgrade -process is pending. Once the upgrade gets finalized, the new -TBTC vault will become an owner of TBTC token. - -### upgradeInitiatedTimestamp - -```solidity -uint256 upgradeInitiatedTimestamp -``` - -The timestamp at which an upgrade to a new TBTC vault was -initiated. Set only when the upgrade process is pending. - -### Minted - -```solidity -event Minted(address to, uint256 amount) -``` - -### Unminted - -```solidity -event Unminted(address from, uint256 amount) -``` - -### UpgradeInitiated - -```solidity -event UpgradeInitiated(address newVault, uint256 timestamp) -``` - -### UpgradeFinalized - -```solidity -event UpgradeFinalized(address newVault) -``` - -### onlyBank - -```solidity -modifier onlyBank() -``` - -### constructor - -```solidity -constructor(contract Bank _bank, contract TBTC _tbtcToken, contract Bridge _bridge) public -``` - -### mint - -```solidity -function mint(uint256 amount) external -``` - -Mints the given `amount` of TBTC to the caller previously -transferring `amount / SATOSHI_MULTIPLIER` of the Bank balance -from caller to TBTC Vault. If `amount` is not divisible by -SATOSHI_MULTIPLIER, the remainder is left on the caller's -Bank balance. - -TBTC Vault must have an allowance for caller's balance in the -Bank for at least `amount / SATOSHI_MULTIPLIER`. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| amount | uint256 | Amount of TBTC to mint. | - -### receiveBalanceApproval - -```solidity -function receiveBalanceApproval(address owner, uint256 satoshis, bytes) external -``` - -Transfers `satoshis` of the Bank balance from the caller -to TBTC Vault and mints `satoshis * SATOSHI_MULTIPLIER` of TBTC -to the caller. - -Can only be called by the Bank via `approveBalanceAndCall`. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| owner | address | The owner who approved their Bank balance. | -| satoshis | uint256 | Amount of satoshis used to mint TBTC. | -| | bytes | | - -### receiveBalanceIncrease - -```solidity -function receiveBalanceIncrease(address[] depositors, uint256[] depositedSatoshiAmounts) external -``` - -Mints the same amount of TBTC as the deposited satoshis amount -multiplied by SATOSHI_MULTIPLIER for each depositor in the array. -Can only be called by the Bank after the Bridge swept deposits -and Bank increased balance for the vault. - -Fails if `depositors` array is empty. Expects the length of -`depositors` and `depositedSatoshiAmounts` is the same. - -### unmint - -```solidity -function unmint(uint256 amount) external -``` - -Burns `amount` of TBTC from the caller's balance and transfers -`amount / SATOSHI_MULTIPLIER` back to the caller's balance in -the Bank. If `amount` is not divisible by SATOSHI_MULTIPLIER, -the remainder is left on the caller's account. - -Caller must have at least `amount` of TBTC approved to -TBTC Vault. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| amount | uint256 | Amount of TBTC to unmint. | - -### unmintAndRedeem - -```solidity -function unmintAndRedeem(uint256 amount, bytes redemptionData) external -``` - -Burns `amount` of TBTC from the caller's balance and transfers -`amount / SATOSHI_MULTIPLIER` of Bank balance to the Bridge -requesting redemption based on the provided `redemptionData`. -If `amount` is not divisible by SATOSHI_MULTIPLIER, the -remainder is left on the caller's account. - -Caller must have at least `amount` of TBTC approved to -TBTC Vault. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| amount | uint256 | Amount of TBTC to unmint and request to redeem in Bridge. | -| redemptionData | bytes | Redemption data in a format expected from `redemptionData` parameter of Bridge's `receiveBalanceApproval` function. | - -### receiveApproval - -```solidity -function receiveApproval(address from, uint256 amount, address token, bytes extraData) external -``` - -Burns `amount` of TBTC from the caller's balance. If `extraData` -is empty, transfers `amount` back to the caller's balance in the -Bank. If `extraData` is not empty, requests redemption in the -Bridge using the `extraData` as a `redemptionData` parameter to -Bridge's `receiveBalanceApproval` function. -If `amount` is not divisible by SATOSHI_MULTIPLIER, the -remainder is left on the caller's account. Note that it may -left a token approval equal to the remainder. - -This function is doing the same as `unmint` or `unmintAndRedeem` -(depending on `extraData` parameter) but it allows to execute -unminting without a separate approval transaction. The function can -be called only via `approveAndCall` of TBTC token. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| from | address | TBTC token holder executing unminting. | -| amount | uint256 | Amount of TBTC to unmint. | -| token | address | TBTC token address. | -| extraData | bytes | Redemption data in a format expected from `redemptionData` parameter of Bridge's `receiveBalanceApproval` function. If empty, `receiveApproval` is not requesting a redemption of Bank balance but is instead performing just TBTC unminting to a Bank balance. | - -### initiateUpgrade - -```solidity -function initiateUpgrade(address _newVault) external -``` - -Initiates vault upgrade process. The upgrade process needs to be -finalized with a call to `finalizeUpgrade` function after the -`UPGRADE_GOVERNANCE_DELAY` passes. Only the governance can -initiate the upgrade. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| _newVault | address | The new vault address. | - -### finalizeUpgrade - -```solidity -function finalizeUpgrade() external -``` - -Allows the governance to finalize vault upgrade process. The -upgrade process needs to be first initiated with a call to -`initiateUpgrade` and the `GOVERNANCE_DELAY` needs to pass. -Once the upgrade is finalized, the new vault becomes the owner -of the TBTC token and receives the whole Bank balance of this -vault. - -### recoverERC20FromToken - -```solidity -function recoverERC20FromToken(contract IERC20 token, address recipient, uint256 amount) external -``` - -Allows the governance of the TBTCVault to recover any ERC20 -token sent mistakenly to the TBTC token contract address. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| token | contract IERC20 | Address of the recovered ERC20 token contract. | -| recipient | address | Address the recovered token should be sent to. | -| amount | uint256 | Recovered amount. | - -### recoverERC721FromToken - -```solidity -function recoverERC721FromToken(contract IERC721 token, address recipient, uint256 tokenId, bytes data) external -``` - -Allows the governance of the TBTCVault to recover any ERC721 -token sent mistakenly to the TBTC token contract address. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| token | contract IERC721 | Address of the recovered ERC721 token contract. | -| recipient | address | Address the recovered token should be sent to. | -| tokenId | uint256 | Identifier of the recovered token. | -| data | bytes | Additional data. | - -### recoverERC20 - -```solidity -function recoverERC20(contract IERC20 token, address recipient, uint256 amount) external -``` - -Allows the governance of the TBTCVault to recover any ERC20 -token sent - mistakenly or not - to the vault address. This -function should be used to withdraw TBTC v1 tokens transferred -to TBTCVault as a result of VendingMachine > TBTCVault upgrade. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| token | contract IERC20 | Address of the recovered ERC20 token contract. | -| recipient | address | Address the recovered token should be sent to. | -| amount | uint256 | Recovered amount. | - -### recoverERC721 - -```solidity -function recoverERC721(contract IERC721 token, address recipient, uint256 tokenId, bytes data) external -``` - -Allows the governance of the TBTCVault to recover any ERC721 -token sent mistakenly to the vault address. - -#### Parameters - -| Name | Type | Description | -| ---- | ---- | ----------- | -| token | contract IERC721 | Address of the recovered ERC721 token contract. | -| recipient | address | Address the recovered token should be sent to. | -| tokenId | uint256 | Identifier of the recovered token. | -| data | bytes | Additional data. | - -### amountToSatoshis - -```solidity -function amountToSatoshis(uint256 amount) public view returns (uint256 convertibleAmount, uint256 remainder, uint256 satoshis) -``` - -Returns the amount of TBTC to be minted/unminted, the remainder, -and the Bank balance to be transferred for the given mint/unmint. -Note that if the `amount` is not divisible by SATOSHI_MULTIPLIER, -the remainder is left on the caller's account when minting or -unminting. - -#### Return Values - -| Name | Type | Description | -| ---- | ---- | ----------- | -| convertibleAmount | uint256 | Amount of TBTC to be minted/unminted. | -| remainder | uint256 | Not convertible remainder if amount is not divisible by SATOSHI_MULTIPLIER. | -| satoshis | uint256 | Amount in satoshis - the Bank balance to be transferred for the given mint/unmint | - -### _mint - -```solidity -function _mint(address minter, uint256 amount) internal -``` - -Mints the given amount of TBTC to the given depositor's address. -Implemented by TBTCVault. - -### _unmint - -```solidity -function _unmint(address unminter, uint256 amount) internal -``` - -`amount` MUST be divisible by SATOSHI_MULTIPLIER with no change. - -### _unmintAndRedeem - -```solidity -function _unmintAndRedeem(address redeemer, uint256 amount, bytes redemptionData) internal -``` - -`amount` MUST be divisible by SATOSHI_MULTIPLIER with no change. - diff --git a/docs/app-development/tbtc-v2/tbtc-v2-api/generated-docs/l2/L2TBTC.md b/docs/app-development/tbtc-v2/tbtc-v2-api/generated-docs/l2/L2TBTC.md new file mode 100644 index 0000000..22c8da9 --- /dev/null +++ b/docs/app-development/tbtc-v2/tbtc-v2-api/generated-docs/l2/L2TBTC.md @@ -0,0 +1,325 @@ +# Solidity API + +## L2TBTC + +Canonical L2/sidechain token implementation. tBTC token is minted on +L1 and locked there to be moved to L2/sidechain. By deploying +a canonical token on each L2/sidechain, we can ensure the supply of +tBTC remains sacrosanct, while enabling quick, interoperable +cross-chain bridges and localizing ecosystem risk. + +This contract is flexible enough to: +- Delegate minting authority to a native bridge on the chain, if +present. +- Delegate minting authority to a short list of ecosystem bridges. +- Have mints and burns paused by any one of n guardians, allowing +avoidance of contagion in case of a chain- or bridge-specific +incident. +- Be governed and upgradeable. + +The token is burnable by the token holder and supports EIP2612 +permits. Token holder can authorize a transfer of their token with +a signature conforming EIP712 standard instead of an on-chain +transaction from their address. Anyone can submit this signature on +the user's behalf by calling the permit function, paying gas fees, +and possibly performing other actions in the same transaction. +The governance can recover ERC20 and ERC721 tokens sent mistakenly +to L2TBTC token contract. + +### isMinter + +```solidity +mapping(address => bool) isMinter +``` + +Indicates if the given address is a minter. Only minters can +mint the token. + +### minters + +```solidity +address[] minters +``` + +List of all minters. + +### isGuardian + +```solidity +mapping(address => bool) isGuardian +``` + +Indicates if the given address is a guardian. Only guardians can +pause token mints and burns. + +### guardians + +```solidity +address[] guardians +``` + +List of all guardians. + +### MinterAdded + +```solidity +event MinterAdded(address minter) +``` + +### MinterRemoved + +```solidity +event MinterRemoved(address minter) +``` + +### GuardianAdded + +```solidity +event GuardianAdded(address guardian) +``` + +### GuardianRemoved + +```solidity +event GuardianRemoved(address guardian) +``` + +### onlyMinter + +```solidity +modifier onlyMinter() +``` + +### onlyGuardian + +```solidity +modifier onlyGuardian() +``` + +### initialize + +```solidity +function initialize(string _name, string _symbol) external +``` + +Initializes the token contract. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| _name | string | The name of the token. | +| _symbol | string | The symbol of the token, usually a shorter version of the name. | + +### addMinter + +```solidity +function addMinter(address minter) external +``` + +Adds the address to the minters list. + +Requirements: +- The caller must be the contract owner. +- `minter` must not be a minter address already. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| minter | address | The address to be added as a minter. | + +### removeMinter + +```solidity +function removeMinter(address minter) external +``` + +Removes the address from the minters list. + +Requirements: +- The caller must be the contract owner. +- `minter` must be a minter address. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| minter | address | The address to be removed from the minters list. | + +### addGuardian + +```solidity +function addGuardian(address guardian) external +``` + +Adds the address to the guardians list. + +Requirements: +- The caller must be the contract owner. +- `guardian` must not be a guardian address already. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| guardian | address | The address to be added as a guardian. | + +### removeGuardian + +```solidity +function removeGuardian(address guardian) external +``` + +Removes the address from the guardians list. + +Requirements: +- The caller must be the contract owner. +- `guardian` must be a guardian address. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| guardian | address | The address to be removed from the guardians list. | + +### recoverERC20 + +```solidity +function recoverERC20(contract IERC20Upgradeable token, address recipient, uint256 amount) external +``` + +Allows the governance of the token contract to recover any ERC20 +sent mistakenly to the token contract address. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| token | contract IERC20Upgradeable | The address of the token to be recovered. | +| recipient | address | The token recipient address that will receive recovered tokens. | +| amount | uint256 | The amount to be recovered. | + +### recoverERC721 + +```solidity +function recoverERC721(contract IERC721Upgradeable token, address recipient, uint256 tokenId, bytes data) external +``` + +Allows the governance of the token contract to recover any +ERC721 sent mistakenly to the token contract address. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| token | contract IERC721Upgradeable | The address of the token to be recovered. | +| recipient | address | The token recipient address that will receive the recovered token. | +| tokenId | uint256 | The ID of the ERC721 token to be recovered. | +| data | bytes | | + +### pause + +```solidity +function pause() external +``` + +Allows one of the guardians to pause mints and burns allowing +avoidance of contagion in case of a chain- or bridge-specific +incident. + +Requirements: +- The caller must be a guardian. +- The contract must not be already paused. + +### unpause + +```solidity +function unpause() external +``` + +Allows the governance to unpause mints and burns previously +paused by one of the guardians. + +Requirements: +- The caller must be the contract owner. +- The contract must be paused. + +### mint + +```solidity +function mint(address account, uint256 amount) external +``` + +Allows one of the minters to mint `amount` tokens and assign +them to `account`, increasing the total supply. Emits +a `Transfer` event with `from` set to the zero address. + +Requirements: +- The caller must be a minter. +- `account` must not be the zero address. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| account | address | The address to receive tokens. | +| amount | uint256 | The amount of token to be minted. | + +### burn + +```solidity +function burn(uint256 amount) public +``` + +Destroys `amount` tokens from the caller. Emits a `Transfer` +event with `to` set to the zero address. + +Requirements: +- The caller must have at least `amount` tokens. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| amount | uint256 | The amount of token to be burned. | + +### burnFrom + +```solidity +function burnFrom(address account, uint256 amount) public +``` + +Destroys `amount` tokens from `account`, deducting from the +caller's allowance. Emits a `Transfer` event with `to` set to +the zero address. + +Requirements: +- The che caller must have allowance for `accounts`'s tokens of at +least `amount`. +- `account` must not be the zero address. +- `account` must have at least `amount` tokens. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| account | address | The address owning tokens to be burned. | +| amount | uint256 | The amount of token to be burned. | + +### getMinters + +```solidity +function getMinters() external view returns (address[]) +``` + +Allows to fetch a list of all minters. + +### getGuardians + +```solidity +function getGuardians() external view returns (address[]) +``` + +Allows to fetch a list of all guardians. + diff --git a/docs/app-development/tbtc-v2/tbtc-v2-api/generated-docs/l2/L2WormholeGateway.md b/docs/app-development/tbtc-v2/tbtc-v2-api/generated-docs/l2/L2WormholeGateway.md new file mode 100644 index 0000000..44c05e4 --- /dev/null +++ b/docs/app-development/tbtc-v2/tbtc-v2-api/generated-docs/l2/L2WormholeGateway.md @@ -0,0 +1,345 @@ +# Solidity API + +## IWormholeTokenBridge + +Wormhole Token Bridge interface. Contains only selected functions +used by L2WormholeGateway. + +### completeTransferWithPayload + +```solidity +function completeTransferWithPayload(bytes encodedVm) external returns (bytes) +``` + +### parseTransferWithPayload + +```solidity +function parseTransferWithPayload(bytes encoded) external pure returns (struct IWormholeTokenBridge.TransferWithPayload transfer) +``` + +### transferTokens + +```solidity +function transferTokens(address token, uint256 amount, uint16 recipientChain, bytes32 recipient, uint256 arbiterFee, uint32 nonce) external payable returns (uint64 sequence) +``` + +### transferTokensWithPayload + +```solidity +function transferTokensWithPayload(address token, uint256 amount, uint16 recipientChain, bytes32 recipient, uint32 nonce, bytes payload) external payable returns (uint64 sequence) +``` + +### TransferWithPayload + +```solidity +struct TransferWithPayload { + uint8 payloadID; + uint256 amount; + bytes32 tokenAddress; + uint16 tokenChain; + bytes32 to; + uint16 toChain; + bytes32 fromAddress; + bytes payload; +} +``` + +## L2WormholeGateway + +Selected cross-ecosystem bridges are given the minting authority for +tBTC token on L2 and sidechains. This contract gives a minting +authority to the Wormhole Bridge. + +The process of bridging from L1 to L2 (or sidechain) looks as +follows: +1. There is a tBTC holder on L1. The holder goes to the Wormhole +Portal and selects the chain they want to bridge to. +2. The holder submits one transaction to L1 locking their tBTC +tokens in the bridge’s smart contract. After the transaction is +mined, they wait about 15 minutes for the Ethereum block +finality. +3. The holder submits one transaction to L2 that is minting tokens. +After that transaction is mined, they have their tBTC on L2. + +The process of bridging from L2 (or sidechain) to L1 looks as +follows: +1. There is a tBTC holder on L2. That holder goes to the Wormhole +Portal and selects one of the L2 chains they want to bridge from. +2. The holder submits one transaction to L2 that is burning the +token. After the transaction is mined, they wait about 15 minutes +for the L2 block finality. +3. The holder submits one transaction to L1 unlocking their tBTC +tokens from the bridge’s smart contract. After that transaction +is mined, they have their tBTC on L1. + +This smart contract is integrated with step 3 of L1->L2 bridging and +step 1 of L2->L1 or L2->L2 bridging. When the user redeems token on +L2, this contract receives the Wormhole tBTC representation and +mints the canonical tBTC in an equal amount. When user sends their +token from L1, this contract burns the canonical tBTC and sends +Wormhole tBTC representation through the bridge in an equal amount. + +This contract is supposed to be deployed behind a transparent +upgradeable proxy. + +### bridge + +```solidity +contract IWormholeTokenBridge bridge +``` + +Reference to the Wormhole Token Bridge contract. + +### bridgeToken + +```solidity +contract IERC20Upgradeable bridgeToken +``` + +Wormhole tBTC token representation. + +### tbtc + +```solidity +contract L2TBTC tbtc +``` + +Canonical tBTC token. + +### gateways + +```solidity +mapping(uint16 => bytes32) gateways +``` + +Maps Wormhole chain ID to the Wormhole tBTC gateway address on +that chain. For example, this chain's ID should be mapped to +this contract's address. If there is no Wormhole tBTC gateway +address on the given chain, there is no entry in this mapping. +The mapping holds addresses in a Wormhole-specific format, where +Ethereum address is left-padded with zeros. + +### mintingLimit + +```solidity +uint256 mintingLimit +``` + +Minting limit for this gateway. Useful for early days of testing +the system. The gateway can not mint more canonical tBTC than +this limit. + +### mintedAmount + +```solidity +uint256 mintedAmount +``` + +The amount of tBTC minted by this contract. tBTC burned by this +contract decreases this amount. + +### WormholeTbtcReceived + +```solidity +event WormholeTbtcReceived(address receiver, uint256 amount) +``` + +### WormholeTbtcSent + +```solidity +event WormholeTbtcSent(uint256 amount, uint16 recipientChain, bytes32 gateway, bytes32 recipient, uint256 arbiterFee, uint32 nonce) +``` + +### WormholeTbtcDeposited + +```solidity +event WormholeTbtcDeposited(address depositor, uint256 amount) +``` + +### GatewayAddressUpdated + +```solidity +event GatewayAddressUpdated(uint16 chainId, bytes32 gateway) +``` + +### MintingLimitUpdated + +```solidity +event MintingLimitUpdated(uint256 mintingLimit) +``` + +### initialize + +```solidity +function initialize(contract IWormholeTokenBridge _bridge, contract IERC20Upgradeable _bridgeToken, contract L2TBTC _tbtc) external +``` + +### sendTbtc + +```solidity +function sendTbtc(uint256 amount, uint16 recipientChain, bytes32 recipient, uint256 arbiterFee, uint32 nonce) external payable returns (uint64) +``` + +This function is called when the user sends their token from L2. +The contract burns the canonical tBTC from the user and sends +wormhole tBTC representation over the bridge. +Keep in mind that when multiple bridges receive a minting +authority on the canonical tBTC, this function may not be able +to send all amounts of tBTC through the Wormhole bridge. The +capability of Wormhole Bridge to send tBTC from the chain is +limited to the amount of tBTC bridged through Wormhole to that +chain. + +Requirements: +- The sender must have at least `amount` of the canonical tBTC and +it has to be approved for L2WormholeGateway. +- The L2WormholeGateway must have at least `amount` of the wormhole +tBTC. +- The recipient must not be 0x0. +- The amount to transfer must not be 0, +- The amount to transfer must be >= 10^10 (1e18 precision). +Depending if Wormhole tBTC gateway is registered on the target +chain, this function uses transfer or transfer with payload over +the Wormhole bridge. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| amount | uint256 | The amount of tBTC to be sent. | +| recipientChain | uint16 | The Wormhole recipient chain ID. | +| recipient | bytes32 | The address of the recipient in the Wormhole format. | +| arbiterFee | uint256 | The Wormhole arbiter fee. Ignored if sending tBTC to chain with Wormhole tBTC gateway. | +| nonce | uint32 | The Wormhole nonce used to batch messages together. | + +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +| [0] | uint64 | The Wormhole sequence number. | + +### receiveTbtc + +```solidity +function receiveTbtc(bytes encodedVm) external +``` + +This function is called when the user redeems their token on L2. +The contract receives Wormhole tBTC representation and mints the +canonical tBTC for the user. +If the tBTC minting limit has been reached by this contract, +instead of minting tBTC the receiver address receives Wormhole +tBTC representation. + +Requirements: +- The receiver of Wormhole tBTC should be the L2WormholeGateway +contract. +- The receiver of the canonical tBTC should be abi-encoded in the +payload. +- The receiver of the canonical tBTC must not be the zero address. +The Wormhole Token Bridge contract has protection against redeeming +the same VAA again. When a Token Bridge VAA is redeemed, its +message body hash is stored in a map. This map is used to check +whether the hash has already been set in this map. For this reason, +this function does not have to be nonReentrant. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| encodedVm | bytes | A byte array containing a Wormhole VAA signed by the guardians. | + +### depositWormholeTbtc + +```solidity +function depositWormholeTbtc(uint256 amount) external +``` + +Allows to deposit Wormhole tBTC token in exchange for canonical +tBTC. Useful in a situation when user received wormhole tBTC +instead of canonical tBTC. One example of such situation is +when the minting limit was exceeded but the user minted anyway. + +Requirements: +- The sender must have at least `amount` of the Wormhole tBTC and +it has to be approved for L2WormholeGateway. +- The minting limit must allow for minting the given amount. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| amount | uint256 | The amount of Wormhole tBTC to deposit. | + +### updateGatewayAddress + +```solidity +function updateGatewayAddress(uint16 chainId, bytes32 gateway) external +``` + +Lets the governance to update the tBTC gateway address on the +chain with the given Wormhole ID. + +Use toWormholeAddress function to convert between Ethereum and +Wormhole address formats. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| chainId | uint16 | Wormhole ID of the chain. | +| gateway | bytes32 | Address of tBTC gateway on the given chain in a Wormhole format. | + +### updateMintingLimit + +```solidity +function updateMintingLimit(uint256 _mintingLimit) external +``` + +Lets the governance to update the tBTC minting limit for this +contract. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| _mintingLimit | uint256 | The new minting limit. | + +### toWormholeAddress + +```solidity +function toWormholeAddress(address _address) external pure returns (bytes32) +``` + +Converts Ethereum address into Wormhole format. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| _address | address | The address to convert. | + +### fromWormholeAddress + +```solidity +function fromWormholeAddress(bytes32 _address) public pure returns (address) +``` + +Converts Wormhole address into Ethereum format. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| _address | bytes32 | The address to convert. | + +### normalize + +```solidity +function normalize(uint256 amount) internal pure returns (uint256) +``` + +Eliminates the dust that cannot be bridged with Wormhole +due to the decimal shift in the Wormhole Bridge contract. +See https://github.com/wormhole-foundation/wormhole/blob/96682bdbeb7c87bfa110eade0554b3d8cbf788d2/ethereum/contracts/bridge/Bridge.sol#L276-L288 + diff --git a/docs/app-development/tbtc-v2/tbtc-v2-api/generated-docs/maintainer/MaintainerProxy.md b/docs/app-development/tbtc-v2/tbtc-v2-api/generated-docs/maintainer/MaintainerProxy.md new file mode 100644 index 0000000..6cd6c6b --- /dev/null +++ b/docs/app-development/tbtc-v2/tbtc-v2-api/generated-docs/maintainer/MaintainerProxy.md @@ -0,0 +1,495 @@ +# Solidity API + +## MaintainerProxy + +Maintainers are the willing off-chain clients approved by the governance. +Maintainers proxy calls to the `Bridge` contract via 'MaintainerProxy' +and are refunded for the spent gas from the `ReimbursementPool`. +There are two types of maintainers: wallet maintainers and SPV +maintainers. + +### bridge + +```solidity +contract Bridge bridge +``` + +### isWalletMaintainer + +```solidity +mapping(address => uint256) isWalletMaintainer +``` + +Authorized wallet maintainers that can interact with the set of +functions for wallet maintainers only. Authorization can be +granted and removed by the governance. + +'Key' is the address of the maintainer. 'Value' represents an index+1 +in the 'maintainers' array. 1 was added so the maintainer index can +never be 0 which is a reserved index for a non-existent maintainer +in this map. + +### walletMaintainers + +```solidity +address[] walletMaintainers +``` + +This list of wallet maintainers keeps the order of which wallet +maintainer should be submitting a next transaction. It does not +enforce the order but only tracks who should be next in line. + +### isSpvMaintainer + +```solidity +mapping(address => uint256) isSpvMaintainer +``` + +Authorized SPV maintainers that can interact with the set of +functions for SPV maintainers only. Authorization can be +granted and removed by the governance. + +'Key' is the address of the maintainer. 'Value' represents an index+1 +in the 'maintainers' array. 1 was added so the maintainer index can +never be 0 which is a reserved index for a non-existent maintainer +in this map. + +### spvMaintainers + +```solidity +address[] spvMaintainers +``` + +This list of SPV maintainers keeps the order of which SPV +maintainer should be submitting a next transaction. It does not +enforce the order but only tracks who should be next in line. + +### submitDepositSweepProofGasOffset + +```solidity +uint256 submitDepositSweepProofGasOffset +``` + +Gas that is meant to balance the submission of deposit sweep proof +overall cost. Can be updated by the governance based on the current +market conditions. + +### submitRedemptionProofGasOffset + +```solidity +uint256 submitRedemptionProofGasOffset +``` + +Gas that is meant to balance the submission of redemption proof +overall cost. Can be updated by the governance based on the current +market conditions. + +### resetMovingFundsTimeoutGasOffset + +```solidity +uint256 resetMovingFundsTimeoutGasOffset +``` + +Gas that is meant to balance the reset of moving funds timeout +overall cost. Can be updated by the governance based on the current +market conditions. + +### submitMovingFundsProofGasOffset + +```solidity +uint256 submitMovingFundsProofGasOffset +``` + +Gas that is meant to balance the submission of moving funds proof +overall cost. Can be updated by the governance based on the current +market conditions. + +### notifyMovingFundsBelowDustGasOffset + +```solidity +uint256 notifyMovingFundsBelowDustGasOffset +``` + +Gas that is meant to balance the notification of moving funds below +dust overall cost. Can be updated by the governance based on the +current market conditions. + +### submitMovedFundsSweepProofGasOffset + +```solidity +uint256 submitMovedFundsSweepProofGasOffset +``` + +Gas that is meant to balance the submission of moved funds sweep +proof overall cost. Can be updated by the governance based on the +current market conditions. + +### requestNewWalletGasOffset + +```solidity +uint256 requestNewWalletGasOffset +``` + +Gas that is meant to balance the request of a new wallet overall +cost. Can be updated by the governance based on the current +market conditions. + +### notifyWalletCloseableGasOffset + +```solidity +uint256 notifyWalletCloseableGasOffset +``` + +Gas that is meant to balance the notification of closeable wallet +overall cost. Can be updated by the governance based on the current +market conditions. + +### notifyWalletClosingPeriodElapsedGasOffset + +```solidity +uint256 notifyWalletClosingPeriodElapsedGasOffset +``` + +Gas that is meant to balance the notification of wallet closing +period elapsed overall cost. Can be updated by the governance +based on the current market conditions. + +### defeatFraudChallengeGasOffset + +```solidity +uint256 defeatFraudChallengeGasOffset +``` + +Gas that is meant to balance the defeat fraud challenge +overall cost. Can be updated by the governance based on the current +market conditions. + +### defeatFraudChallengeWithHeartbeatGasOffset + +```solidity +uint256 defeatFraudChallengeWithHeartbeatGasOffset +``` + +Gas that is meant to balance the defeat fraud challenge with heartbeat +overall cost. Can be updated by the governance based on the current +market conditions. + +### WalletMaintainerAuthorized + +```solidity +event WalletMaintainerAuthorized(address maintainer) +``` + +### WalletMaintainerUnauthorized + +```solidity +event WalletMaintainerUnauthorized(address maintainer) +``` + +### SpvMaintainerAuthorized + +```solidity +event SpvMaintainerAuthorized(address maintainer) +``` + +### SpvMaintainerUnauthorized + +```solidity +event SpvMaintainerUnauthorized(address maintainer) +``` + +### BridgeUpdated + +```solidity +event BridgeUpdated(address newBridge) +``` + +### GasOffsetParametersUpdated + +```solidity +event GasOffsetParametersUpdated(uint256 submitDepositSweepProofGasOffset, uint256 submitRedemptionProofGasOffset, uint256 resetMovingFundsTimeoutGasOffset, uint256 submitMovingFundsProofGasOffset, uint256 notifyMovingFundsBelowDustGasOffset, uint256 submitMovedFundsSweepProofGasOffset, uint256 requestNewWalletGasOffset, uint256 notifyWalletCloseableGasOffset, uint256 notifyWalletClosingPeriodElapsedGasOffset, uint256 defeatFraudChallengeGasOffset, uint256 defeatFraudChallengeWithHeartbeatGasOffset) +``` + +### onlyWalletMaintainer + +```solidity +modifier onlyWalletMaintainer() +``` + +### onlySpvMaintainer + +```solidity +modifier onlySpvMaintainer() +``` + +### onlyReimbursableAdmin + +```solidity +modifier onlyReimbursableAdmin() +``` + +### constructor + +```solidity +constructor(contract Bridge _bridge, contract ReimbursementPool _reimbursementPool) public +``` + +### submitDepositSweepProof + +```solidity +function submitDepositSweepProof(struct BitcoinTx.Info sweepTx, struct BitcoinTx.Proof sweepProof, struct BitcoinTx.UTXO mainUtxo, address vault) external +``` + +Wraps `Bridge.submitDepositSweepProof` call and reimburses the +caller's transaction cost. + +See `Bridge.submitDepositSweepProof` function documentation. + +### submitRedemptionProof + +```solidity +function submitRedemptionProof(struct BitcoinTx.Info redemptionTx, struct BitcoinTx.Proof redemptionProof, struct BitcoinTx.UTXO mainUtxo, bytes20 walletPubKeyHash) external +``` + +Wraps `Bridge.submitRedemptionProof` call and reimburses the +caller's transaction cost. + +See `Bridge.submitRedemptionProof` function documentation. + +### resetMovingFundsTimeout + +```solidity +function resetMovingFundsTimeout(bytes20 walletPubKeyHash) external +``` + +Wraps `Bridge.resetMovingFundsTimeout` call and reimburses the +caller's transaction cost. + +See `Bridge.resetMovingFundsTimeout` function documentation. + +### submitMovingFundsProof + +```solidity +function submitMovingFundsProof(struct BitcoinTx.Info movingFundsTx, struct BitcoinTx.Proof movingFundsProof, struct BitcoinTx.UTXO mainUtxo, bytes20 walletPubKeyHash) external +``` + +Wraps `Bridge.submitMovingFundsProof` call and reimburses the +caller's transaction cost. + +See `Bridge.submitMovingFundsProof` function documentation. + +### notifyMovingFundsBelowDust + +```solidity +function notifyMovingFundsBelowDust(bytes20 walletPubKeyHash, struct BitcoinTx.UTXO mainUtxo) external +``` + +Wraps `Bridge.notifyMovingFundsBelowDust` call and reimburses the +caller's transaction cost. + +See `Bridge.notifyMovingFundsBelowDust` function documentation. + +### submitMovedFundsSweepProof + +```solidity +function submitMovedFundsSweepProof(struct BitcoinTx.Info sweepTx, struct BitcoinTx.Proof sweepProof, struct BitcoinTx.UTXO mainUtxo) external +``` + +Wraps `Bridge.submitMovedFundsSweepProof` call and reimburses the +caller's transaction cost. + +See `Bridge.submitMovedFundsSweepProof` function documentation. + +### requestNewWallet + +```solidity +function requestNewWallet(struct BitcoinTx.UTXO activeWalletMainUtxo) external +``` + +Wraps `Bridge.requestNewWallet` call and reimburses the +caller's transaction cost. + +See `Bridge.requestNewWallet` function documentation. + +### notifyWalletCloseable + +```solidity +function notifyWalletCloseable(bytes20 walletPubKeyHash, struct BitcoinTx.UTXO walletMainUtxo) external +``` + +Wraps `Bridge.notifyWalletCloseable` call and reimburses the +caller's transaction cost. + +See `Bridge.notifyWalletCloseable` function documentation. + +### notifyWalletClosingPeriodElapsed + +```solidity +function notifyWalletClosingPeriodElapsed(bytes20 walletPubKeyHash) external +``` + +Wraps `Bridge.notifyWalletClosingPeriodElapsed` call and reimburses +the caller's transaction cost. + +See `Bridge.notifyWalletClosingPeriodElapsed` function documentation. + +### defeatFraudChallenge + +```solidity +function defeatFraudChallenge(bytes walletPublicKey, bytes preimage, bool witness) external +``` + +Wraps `Bridge.defeatFraudChallenge` call and reimburses the +caller's transaction cost. + +See `Bridge.defeatFraudChallenge` function documentation. + +### defeatFraudChallengeWithHeartbeat + +```solidity +function defeatFraudChallengeWithHeartbeat(bytes walletPublicKey, bytes heartbeatMessage) external +``` + +Wraps `Bridge.defeatFraudChallengeWithHeartbeat` call and +reimburses the caller's transaction cost. + +See `Bridge.defeatFraudChallengeWithHeartbeat` function documentation. + +### authorizeWalletMaintainer + +```solidity +function authorizeWalletMaintainer(address maintainer) external +``` + +Authorize a wallet maintainer that can interact with this +reimbursement pool. Can be authorized by the owner only. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| maintainer | address | Wallet maintainer to authorize. | + +### authorizeSpvMaintainer + +```solidity +function authorizeSpvMaintainer(address maintainer) external +``` + +Authorize an SPV maintainer that can interact with this +reimbursement pool. Can be authorized by the owner only. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| maintainer | address | SPV maintainer to authorize. | + +### unauthorizeWalletMaintainer + +```solidity +function unauthorizeWalletMaintainer(address maintainerToUnauthorize) external +``` + +Unauthorize a wallet maintainer that was previously authorized to +interact with the Maintainer Proxy contract. Can be unauthorized +by the owner only. + +The last maintainer is swapped with the one to be unauthorized. +The unauthorized maintainer is then removed from the list. An index +of the last maintainer is changed with the removed maintainer. +Ex. +'walletMaintainers' list: [0x1, 0x2, 0x3, 0x4, 0x5] +'isWalletMaintainer' map: [0x1 -> 1, 0x2 -> 2, 0x3 -> 3, 0x4 -> 4, 0x5 -> 5] +unauthorize: 0x3 +new 'walletMaintainers' list: [0x1, 0x2, 0x5, 0x4] +new 'isWalletMaintainer' map: [0x1 -> 1, 0x2 -> 2, 0x4 -> 4, 0x5 -> 3] + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| maintainerToUnauthorize | address | Maintainer to unauthorize. | + +### unauthorizeSpvMaintainer + +```solidity +function unauthorizeSpvMaintainer(address maintainerToUnauthorize) external +``` + +Unauthorize an SPV maintainer that was previously authorized to +interact with the Maintainer Proxy contract. Can be unauthorized +by the owner only. + +The last maintainer is swapped with the one to be unauthorized. +The unauthorized maintainer is then removed from the list. An index +of the last maintainer is changed with the removed maintainer. +Ex. +'spvMaintainers' list: [0x1, 0x2, 0x3, 0x4, 0x5] +'isSpvMaintainer' map: [0x1 -> 1, 0x2 -> 2, 0x3 -> 3, 0x4 -> 4, 0x5 -> 5] +unauthorize: 0x3 +new 'spvMaintainers' list: [0x1, 0x2, 0x5, 0x4] +new 'isSpvMaintainer' map: [0x1 -> 1, 0x2 -> 2, 0x4 -> 4, 0x5 -> 3] + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| maintainerToUnauthorize | address | Maintainer to unauthorize. | + +### updateBridge + +```solidity +function updateBridge(contract Bridge _bridge) external +``` + +Allows the Governance to upgrade the Bridge address. + +The function does not implement any governance delay and does not +check the status of the Bridge. The Governance implementation needs +to ensure all requirements for the upgrade are satisfied before +executing this function. + +### updateGasOffsetParameters + +```solidity +function updateGasOffsetParameters(uint256 newSubmitDepositSweepProofGasOffset, uint256 newSubmitRedemptionProofGasOffset, uint256 newResetMovingFundsTimeoutGasOffset, uint256 newSubmitMovingFundsProofGasOffset, uint256 newNotifyMovingFundsBelowDustGasOffset, uint256 newSubmitMovedFundsSweepProofGasOffset, uint256 newRequestNewWalletGasOffset, uint256 newNotifyWalletCloseableGasOffset, uint256 newNotifyWalletClosingPeriodElapsedGasOffset, uint256 newDefeatFraudChallengeGasOffset, uint256 newDefeatFraudChallengeWithHeartbeatGasOffset) external +``` + +Updates the values of gas offset parameters. + +Can be called only by the contract owner. The caller is responsible +for validating parameters. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| newSubmitDepositSweepProofGasOffset | uint256 | New submit deposit sweep proof gas offset. | +| newSubmitRedemptionProofGasOffset | uint256 | New submit redemption proof gas offset. | +| newResetMovingFundsTimeoutGasOffset | uint256 | New reset moving funds timeout gas offset. | +| newSubmitMovingFundsProofGasOffset | uint256 | New submit moving funds proof gas offset. | +| newNotifyMovingFundsBelowDustGasOffset | uint256 | New notify moving funds below dust gas offset. | +| newSubmitMovedFundsSweepProofGasOffset | uint256 | New submit moved funds sweep proof gas offset. | +| newRequestNewWalletGasOffset | uint256 | New request new wallet gas offset. | +| newNotifyWalletCloseableGasOffset | uint256 | New notify closeable wallet gas offset. | +| newNotifyWalletClosingPeriodElapsedGasOffset | uint256 | New notify wallet closing period elapsed gas offset. | +| newDefeatFraudChallengeGasOffset | uint256 | New defeat fraud challenge gas offset. | +| newDefeatFraudChallengeWithHeartbeatGasOffset | uint256 | New defeat fraud challenge with heartbeat gas offset. | + +### allWalletMaintainers + +```solidity +function allWalletMaintainers() external view returns (address[]) +``` + +Gets an entire array of wallet maintainer addresses. + +### allSpvMaintainers + +```solidity +function allSpvMaintainers() external view returns (address[]) +``` + +Gets an entire array of SPV maintainer addresses. + diff --git a/docs/app-development/tbtc-v2/tbtc-v2-api/generated-docs/relay/LightRelay.md b/docs/app-development/tbtc-v2/tbtc-v2-api/generated-docs/relay/LightRelay.md new file mode 100644 index 0000000..7571613 --- /dev/null +++ b/docs/app-development/tbtc-v2/tbtc-v2-api/generated-docs/relay/LightRelay.md @@ -0,0 +1,460 @@ +# Solidity API + +## Epoch + +```solidity +struct Epoch { + uint32 timestamp; + uint224 target; +} +``` + +## ILightRelay + +### Genesis + +```solidity +event Genesis(uint256 blockHeight) +``` + +### Retarget + +```solidity +event Retarget(uint256 oldDifficulty, uint256 newDifficulty) +``` + +### ProofLengthChanged + +```solidity +event ProofLengthChanged(uint256 newLength) +``` + +### AuthorizationRequirementChanged + +```solidity +event AuthorizationRequirementChanged(bool newStatus) +``` + +### SubmitterAuthorized + +```solidity +event SubmitterAuthorized(address submitter) +``` + +### SubmitterDeauthorized + +```solidity +event SubmitterDeauthorized(address submitter) +``` + +### retarget + +```solidity +function retarget(bytes headers) external +``` + +### validateChain + +```solidity +function validateChain(bytes headers) external view returns (uint256 startingHeaderTimestamp, uint256 headerCount) +``` + +### getBlockDifficulty + +```solidity +function getBlockDifficulty(uint256 blockNumber) external view returns (uint256) +``` + +### getEpochDifficulty + +```solidity +function getEpochDifficulty(uint256 epochNumber) external view returns (uint256) +``` + +### getRelayRange + +```solidity +function getRelayRange() external view returns (uint256 relayGenesis, uint256 currentEpochEnd) +``` + +## RelayUtils + +### extractTimestampAt + +```solidity +function extractTimestampAt(bytes headers, uint256 at) internal pure returns (uint32) +``` + +Extract the timestamp of the header at the given position. + +Assumes that the specified position contains a valid header. +Performs no validation whatsoever. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| headers | bytes | Byte array containing the header of interest. | +| at | uint256 | The start of the header in the array. | + +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +| [0] | uint32 | The timestamp of the header. | + +## LightRelay + +THE RELAY MUST NOT BE USED BEFORE GENESIS AND AT LEAST ONE RETARGET. + +### ready + +```solidity +bool ready +``` + +### authorizationRequired + +```solidity +bool authorizationRequired +``` + +### proofLength + +```solidity +uint64 proofLength +``` + +### genesisEpoch + +```solidity +uint64 genesisEpoch +``` + +### currentEpoch + +```solidity +uint64 currentEpoch +``` + +### currentEpochDifficulty + +```solidity +uint256 currentEpochDifficulty +``` + +### prevEpochDifficulty + +```solidity +uint256 prevEpochDifficulty +``` + +### epochs + +```solidity +mapping(uint256 => struct Epoch) epochs +``` + +### isAuthorized + +```solidity +mapping(address => bool) isAuthorized +``` + +### relayActive + +```solidity +modifier relayActive() +``` + +### genesis + +```solidity +function genesis(bytes genesisHeader, uint256 genesisHeight, uint64 genesisProofLength) external +``` + +Establish a starting point for the relay by providing the +target, timestamp and blockheight of the first block of the relay +genesis epoch. + +If the relay is used by querying the current and previous epoch +difficulty, at least one retarget needs to be provided after genesis; +otherwise the prevEpochDifficulty will be uninitialised and zero. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| genesisHeader | bytes | The first block header of the genesis epoch. | +| genesisHeight | uint256 | The block number of the first block of the epoch. | +| genesisProofLength | uint64 | The number of blocks required to accept a proof. | + +### setProofLength + +```solidity +function setProofLength(uint64 newLength) external +``` + +Set the number of blocks required to accept a header chain. + +For production, a high number (e.g. 20-50) is recommended. +Small numbers are accepted but should only be used for testing. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| newLength | uint64 | The required number of blocks. Must be less than 2016. | + +### setAuthorizationStatus + +```solidity +function setAuthorizationStatus(bool status) external +``` + +Set whether the relay requires retarget submitters to be +pre-authorised by governance. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| status | bool | True if authorisation is to be required, false if not. | + +### authorize + +```solidity +function authorize(address submitter) external +``` + +Authorise the given address to submit retarget proofs. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| submitter | address | The address to be authorised. | + +### deauthorize + +```solidity +function deauthorize(address submitter) external +``` + +Rescind the authorisation of the submitter to retarget. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| submitter | address | The address to be deauthorised. | + +### retarget + +```solidity +function retarget(bytes headers) external +``` + +Add a new epoch to the relay by providing a proof +of the difficulty before and after the retarget. + +Checks that the first X blocks are valid in the most recent epoch, +that the difficulty of the new epoch is calculated correctly according +to the block timestamps, and that the next X blocks would be valid in +the new epoch. +We have no information of block heights, so we cannot enforce that +retargets only happen every 2016 blocks; instead, we assume that this +is the case if a valid proof of work is provided. +It is possible to cheat the relay by providing X blocks from earlier in +the most recent epoch, and then mining X new blocks after them. +However, each of these malicious blocks would have to be mined to a +higher difficulty than the legitimate ones. +Alternatively, if the retarget has not been performed yet, one could +first mine X blocks in the old difficulty with timestamps set far in +the future, and then another X blocks at a greatly reduced difficulty. +In either case, cheating the realy requires more work than mining X +legitimate blocks. +Only the most recent epoch is vulnerable to these attacks; once a +retarget has been proven to the relay, the epoch is immutable even if a +contradictory proof were to be presented later. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| headers | bytes | A chain of headers including the last X blocks before the retarget, followed by the first X blocks after the retarget, where X equals the current proof length. | + +### validateChain + +```solidity +function validateChain(bytes headers) external view returns (uint256 startingHeaderTimestamp, uint256 headerCount) +``` + +Check whether a given chain of headers should be accepted as +valid within the rules of the relay. +If the validation fails, this function throws an exception. + +A chain of headers is accepted as valid if: +- Its length is between 2 and 2015 headers. +- Headers in the chain are sequential and refer to previous digests. +- Each header is mined with the correct amount of work. +- The difficulty in each header matches an epoch of the relay, +as determined by the headers' timestamps. The headers must be between +the genesis epoch and the latest proven epoch (inclusive). +If the chain contains a retarget, it is accepted if the retarget has +already been proven to the relay. +If the chain contains blocks of an epoch that has not been proven to +the relay (after a retarget within the header chain, or when the entire +chain falls within an epoch that has not been proven yet), it will be +rejected. +One exception to this is when two subsequent epochs have exactly the +same difficulty; headers from the latter epoch will be accepted if the +previous epoch has been proven to the relay. +This is because it is not possible to distinguish such headers from +headers of the previous epoch. + +If the difficulty increases significantly between relay genesis and the +present, creating fraudulent proofs for earlier epochs becomes easier. +Users of the relay should check the timestamps of valid headers and +only accept appropriately recent ones. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| headers | bytes | A chain of 2 to 2015 bitcoin headers. | + +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +| startingHeaderTimestamp | uint256 | The timestamp of the first header. | +| headerCount | uint256 | The number of headers. | + +### getBlockDifficulty + +```solidity +function getBlockDifficulty(uint256 blockNumber) external view returns (uint256) +``` + +Get the difficulty of the specified block. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| blockNumber | uint256 | The number of the block. Must fall within the relay range (at or after the relay genesis, and at or before the end of the most recent epoch proven to the relay). | + +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +| [0] | uint256 | The difficulty of the epoch. | + +### getRelayRange + +```solidity +function getRelayRange() external view returns (uint256 relayGenesis, uint256 currentEpochEnd) +``` + +Get the range of blocks the relay can accept proofs for. + +Assumes that the genesis has been set correctly. +Additionally, if the next epoch after the current one has the exact +same difficulty, headers for it can be validated as well. +This function should be used for informative purposes, +e.g. to determine whether a retarget must be provided before submitting +a header chain for validation. + +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +| relayGenesis | uint256 | The height of the earliest block that can be included in header chains for the relay to validate. | +| currentEpochEnd | uint256 | The height of the last block that can be included in header chains for the relay to validate. | + +### getCurrentEpochDifficulty + +```solidity +function getCurrentEpochDifficulty() external view virtual returns (uint256) +``` + +Returns the difficulty of the current epoch. + +returns 0 if the relay is not ready. + +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +| [0] | uint256 | The difficulty of the current epoch. | + +### getPrevEpochDifficulty + +```solidity +function getPrevEpochDifficulty() external view virtual returns (uint256) +``` + +Returns the difficulty of the previous epoch. + +Returns 0 if the relay is not ready or has not had a retarget. + +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +| [0] | uint256 | The difficulty of the previous epoch. | + +### getCurrentAndPrevEpochDifficulty + +```solidity +function getCurrentAndPrevEpochDifficulty() external view returns (uint256 current, uint256 previous) +``` + +### getEpochDifficulty + +```solidity +function getEpochDifficulty(uint256 epochNumber) public view returns (uint256) +``` + +Get the difficulty of the specified epoch. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| epochNumber | uint256 | The number of the epoch (the height of the first block of the epoch, divided by 2016). Must fall within the relay range. | + +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +| [0] | uint256 | The difficulty of the epoch. | + +### validateHeader + +```solidity +function validateHeader(bytes headers, uint256 start, bytes32 prevDigest) internal view returns (bytes32 digest, uint256 target) +``` + +Check that the specified header forms a correct chain with the +digest of the previous header (if provided), and has sufficient work. + +Throws an exception if the header's chain or PoW are invalid. +Performs no other validation. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| headers | bytes | The byte array containing the header of interest. | +| start | uint256 | The start of the header in the array. | +| prevDigest | bytes32 | The digest of the previous header (optional; providing zeros for the digest skips the check). | + +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +| digest | bytes32 | The digest of the current header. | +| target | uint256 | The PoW target of the header. | + diff --git a/docs/app-development/tbtc-v2/tbtc-v2-api/generated-docs/relay/LightRelayMaintainerProxy.md b/docs/app-development/tbtc-v2/tbtc-v2-api/generated-docs/relay/LightRelayMaintainerProxy.md new file mode 100644 index 0000000..b6452cd --- /dev/null +++ b/docs/app-development/tbtc-v2/tbtc-v2-api/generated-docs/relay/LightRelayMaintainerProxy.md @@ -0,0 +1,161 @@ +# Solidity API + +## LightRelayMaintainerProxy + +The proxy contract that allows the relay maintainers to be refunded +for the spent gas from the `ReimbursementPool`. When proving the +next Bitcoin difficulty epoch, the maintainer calls the +`LightRelayMaintainerProxy` which in turn calls the actual `LightRelay` +contract. + +### lightRelay + +```solidity +contract ILightRelay lightRelay +``` + +### isAuthorized + +```solidity +mapping(address => bool) isAuthorized +``` + +Stores the addresses that can maintain the relay. Those +addresses are attested by the DAO. + +The goal is to prevent a griefing attack by frontrunning relay +maintainer which is responsible for retargetting the relay in the +given round. The maintainer's transaction would revert with no gas +refund. Having the ability to restrict maintainer addresses is also +important in case the underlying relay contract has authorization +requirements for callers. + +### retargetGasOffset + +```solidity +uint256 retargetGasOffset +``` + +Gas that is meant to balance the retarget overall cost. Can be + +### LightRelayUpdated + +```solidity +event LightRelayUpdated(address newRelay) +``` + +### MaintainerAuthorized + +```solidity +event MaintainerAuthorized(address maintainer) +``` + +### MaintainerDeauthorized + +```solidity +event MaintainerDeauthorized(address maintainer) +``` + +### RetargetGasOffsetUpdated + +```solidity +event RetargetGasOffsetUpdated(uint256 retargetGasOffset) +``` + +### onlyRelayMaintainer + +```solidity +modifier onlyRelayMaintainer() +``` + +### onlyReimbursableAdmin + +```solidity +modifier onlyReimbursableAdmin() +``` + +### constructor + +```solidity +constructor(contract ILightRelay _lightRelay, contract ReimbursementPool _reimbursementPool) public +``` + +### updateLightRelay + +```solidity +function updateLightRelay(contract ILightRelay _lightRelay) external +``` + +Allows the governance to upgrade the `LightRelay` address. + +The function does not implement any governance delay and does not +check the status of the `LightRelay`. The Governance implementation +needs to ensure all requirements for the upgrade are satisfied +before executing this function. + +### authorize + +```solidity +function authorize(address maintainer) external +``` + +Authorizes the given address as a maintainer. Can only be called +by the owner and the address of the maintainer must not be +already authorized. + +The function does not implement any governance delay. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| maintainer | address | The address of the maintainer to be authorized. | + +### deauthorize + +```solidity +function deauthorize(address maintainer) external +``` + +Deauthorizes the given address as a maintainer. Can only be +called by the owner and the address of the maintainer must be +authorized. + +The function does not implement any governance delay. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| maintainer | address | The address of the maintainer to be deauthorized. | + +### updateRetargetGasOffset + +```solidity +function updateRetargetGasOffset(uint256 newRetargetGasOffset) external +``` + +Updates the values of retarget gas offset. + +Can be called only by the contract owner. The caller is responsible +for validating the parameter. The function does not implement any +governance delay. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| newRetargetGasOffset | uint256 | New retarget gas offset. | + +### retarget + +```solidity +function retarget(bytes headers) external +``` + +Wraps `LightRelay.retarget` call and reimburses the caller's +transaction cost. Can only be called by an authorized relay +maintainer. + +See `LightRelay.retarget` function documentation. + diff --git a/docs/app-development/tbtc-v2/tbtc-v2-api/generated-docs/token/TBTC.md b/docs/app-development/tbtc-v2/tbtc-v2-api/generated-docs/token/TBTC.md new file mode 100644 index 0000000..15aca0f --- /dev/null +++ b/docs/app-development/tbtc-v2/tbtc-v2-api/generated-docs/token/TBTC.md @@ -0,0 +1,10 @@ +# Solidity API + +## TBTC + +### constructor + +```solidity +constructor() public +``` + diff --git a/docs/app-development/tbtc-v2/tbtc-v2-api/generated-docs/vault/DonationVault.md b/docs/app-development/tbtc-v2/tbtc-v2-api/generated-docs/vault/DonationVault.md new file mode 100644 index 0000000..7499255 --- /dev/null +++ b/docs/app-development/tbtc-v2/tbtc-v2-api/generated-docs/vault/DonationVault.md @@ -0,0 +1,106 @@ +# Solidity API + +## DonationVault + +Vault that allows making BTC donations to the system. Upon deposit, +this vault does not increase depositors' balances and always +decreases its own balance in the same transaction. The vault also +allows making donations using existing Bank balances. + +BEWARE: ALL BTC DEPOSITS TARGETING THIS VAULT ARE NOT REDEEMABLE +AND THERE IS NO WAY TO RESTORE THE DONATED BALANCE. +USE THIS VAULT ONLY WHEN YOU REALLY KNOW WHAT YOU ARE DOING! + +### bank + +```solidity +contract Bank bank +``` + +### DonationReceived + +```solidity +event DonationReceived(address donor, uint256 donatedAmount) +``` + +### onlyBank + +```solidity +modifier onlyBank() +``` + +### constructor + +```solidity +constructor(contract Bank _bank) public +``` + +### donate + +```solidity +function donate(uint256 amount) external +``` + +Transfers the given `amount` of the Bank balance from the +caller to the Donation Vault and immediately decreases the +vault's balance in the Bank by the transferred `amount`. + +Requirements: +- The caller's balance in the Bank must be greater than or equal +to the `amount`, +- Donation Vault must have an allowance for caller's balance in +the Bank for at least `amount`. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| amount | uint256 | Amount of the Bank balance to donate. | + +### receiveBalanceApproval + +```solidity +function receiveBalanceApproval(address owner, uint256 amount, bytes) external +``` + +Transfers the given `amount` of the Bank balance from the +`owner` to the Donation Vault and immediately decreases the +vault's balance in the Bank by the transferred `amount`. + +Requirements: +- Can only be called by the Bank via `approveBalanceAndCall`, +- The `owner` balance in the Bank must be greater than or equal +to the `amount`. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| owner | address | Address of the Bank balance owner who approved their balance to be used by the vault. | +| amount | uint256 | The amount of the Bank balance approved by the owner to be used by the vault. | +| | bytes | | + +### receiveBalanceIncrease + +```solidity +function receiveBalanceIncrease(address[] depositors, uint256[] depositedAmounts) external +``` + +Ignores the deposited amounts and does not increase depositors' +individual balances. The vault decreases its own tBTC balance +in the Bank by the total deposited amount. + +Requirements: +- Can only be called by the Bank after the Bridge swept deposits +and Bank increased balance for the vault, +- The `depositors` array must not be empty, +- The `depositors` array length must be equal to the +`depositedAmounts` array length. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| depositors | address[] | Addresses of depositors whose deposits have been swept. | +| depositedAmounts | uint256[] | Amounts deposited by individual depositors and swept. | + diff --git a/docs/app-development/tbtc-v2/tbtc-v2-api/generated-docs/vault/IVault.md b/docs/app-development/tbtc-v2/tbtc-v2-api/generated-docs/vault/IVault.md new file mode 100644 index 0000000..b298044 --- /dev/null +++ b/docs/app-development/tbtc-v2/tbtc-v2-api/generated-docs/vault/IVault.md @@ -0,0 +1,35 @@ +# Solidity API + +## IVault + +`IVault` is an interface for a smart contract consuming Bank +balances of other contracts or externally owned accounts (EOA). + +### receiveBalanceIncrease + +```solidity +function receiveBalanceIncrease(address[] depositors, uint256[] depositedAmounts) external +``` + +Called by the Bank in `increaseBalanceAndCall` function after +increasing the balance in the Bank for the vault. It happens in +the same transaction in which deposits were swept by the Bridge. +This allows the depositor to route their deposit revealed to the +Bridge to the particular smart contract (vault) in the same +transaction in which the deposit is revealed. This way, the +depositor does not have to execute additional transaction after +the deposit gets swept by the Bridge to approve and transfer +their balance to the vault. + +The implementation must ensure this function can only be called +by the Bank. The Bank guarantees that the vault's balance was +increased by the sum of all deposited amounts before this function +is called, in the same transaction. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| depositors | address[] | Addresses of depositors whose deposits have been swept. | +| depositedAmounts | uint256[] | Amounts deposited by individual depositors and swept. | + diff --git a/docs/app-development/tbtc-v2/tbtc-v2-api/generated-docs/vault/TBTCOptimisticMinting.md b/docs/app-development/tbtc-v2/tbtc-v2-api/generated-docs/vault/TBTCOptimisticMinting.md new file mode 100644 index 0000000..802efd9 --- /dev/null +++ b/docs/app-development/tbtc-v2/tbtc-v2-api/generated-docs/vault/TBTCOptimisticMinting.md @@ -0,0 +1,524 @@ +# Solidity API + +## TBTCOptimisticMinting + +The Optimistic Minting mechanism allows to mint TBTC before +`TBTCVault` receives the Bank balance. There are two permissioned +sets in the system: Minters and Guardians, both set up in 1-of-n +mode. Minters observe the revealed deposits and request minting TBTC. +Any single Minter can perform this action. There is an +`optimisticMintingDelay` between the time of the request from +a Minter to the time TBTC is minted. During the time of the delay, +any Guardian can cancel the minting. + +This functionality is a part of `TBTCVault`. It is implemented in +a separate abstract contract to achieve better separation of concerns +and easier-to-follow code. + +### OptimisticMintingRequest + +```solidity +struct OptimisticMintingRequest { + uint64 requestedAt; + uint64 finalizedAt; +} +``` + +### GOVERNANCE_DELAY + +```solidity +uint256 GOVERNANCE_DELAY +``` + +The time delay that needs to pass between initializing and +finalizing the upgrade of governable parameters. + +### SATOSHI_MULTIPLIER + +```solidity +uint256 SATOSHI_MULTIPLIER +``` + +Multiplier to convert satoshi to TBTC token units. + +### bridge + +```solidity +contract Bridge bridge +``` + +### isOptimisticMintingPaused + +```solidity +bool isOptimisticMintingPaused +``` + +Indicates if the optimistic minting has been paused. Only the +Governance can pause optimistic minting. Note that the pause of +the optimistic minting does not stop the standard minting flow +where wallets sweep deposits. + +### optimisticMintingFeeDivisor + +```solidity +uint32 optimisticMintingFeeDivisor +``` + +Divisor used to compute the treasury fee taken from each +optimistically minted deposit and transferred to the treasury +upon finalization of the optimistic mint. This fee is computed +as follows: `fee = amount / optimisticMintingFeeDivisor`. +For example, if the fee needs to be 2%, the +`optimisticMintingFeeDivisor` should be set to `50` because +`1/50 = 0.02 = 2%`. +The optimistic minting fee does not replace the deposit treasury +fee cut by the Bridge. The optimistic fee is a percentage AFTER +the treasury fee is cut: +`optimisticMintingFee = (depositAmount - treasuryFee) / optimisticMintingFeeDivisor` + +### optimisticMintingDelay + +```solidity +uint32 optimisticMintingDelay +``` + +The time that needs to pass between the moment the optimistic +minting is requested and the moment optimistic minting is +finalized with minting TBTC. + +### isMinter + +```solidity +mapping(address => bool) isMinter +``` + +Indicates if the given address is a Minter. Only Minters can +request optimistic minting. + +### minters + +```solidity +address[] minters +``` + +List of all Minters. + +May be used to establish an order in which the Minters should +request for an optimistic minting. + +### isGuardian + +```solidity +mapping(address => bool) isGuardian +``` + +Indicates if the given address is a Guardian. Only Guardians can +cancel requested optimistic minting. + +### optimisticMintingRequests + +```solidity +mapping(uint256 => struct TBTCOptimisticMinting.OptimisticMintingRequest) optimisticMintingRequests +``` + +Collection of all revealed deposits for which the optimistic +minting was requested. Indexed by a deposit key computed as +`keccak256(fundingTxHash | fundingOutputIndex)`. + +### optimisticMintingDebt + +```solidity +mapping(address => uint256) optimisticMintingDebt +``` + +Optimistic minting debt value per depositor's address. The debt +represents the total value of all depositor's deposits revealed +to the Bridge that has not been yet swept and led to the +optimistic minting of TBTC. When `TBTCVault` sweeps a deposit, +the debt is fully or partially paid off, no matter if that +particular swept deposit was used for the optimistic minting or +not. The values are in 1e18 Ethereum precision. + +### newOptimisticMintingFeeDivisor + +```solidity +uint32 newOptimisticMintingFeeDivisor +``` + +New optimistic minting fee divisor value. Set only when the +parameter update process is pending. Once the update gets + +### optimisticMintingFeeUpdateInitiatedTimestamp + +```solidity +uint256 optimisticMintingFeeUpdateInitiatedTimestamp +``` + +The timestamp at which the update of the optimistic minting fee +divisor started. Zero if update is not in progress. + +### newOptimisticMintingDelay + +```solidity +uint32 newOptimisticMintingDelay +``` + +New optimistic minting delay value. Set only when the parameter +update process is pending. Once the update gets finalized, this + +### optimisticMintingDelayUpdateInitiatedTimestamp + +```solidity +uint256 optimisticMintingDelayUpdateInitiatedTimestamp +``` + +The timestamp at which the update of the optimistic minting +delay started. Zero if update is not in progress. + +### OptimisticMintingRequested + +```solidity +event OptimisticMintingRequested(address minter, uint256 depositKey, address depositor, uint256 amount, bytes32 fundingTxHash, uint32 fundingOutputIndex) +``` + +### OptimisticMintingFinalized + +```solidity +event OptimisticMintingFinalized(address minter, uint256 depositKey, address depositor, uint256 optimisticMintingDebt) +``` + +### OptimisticMintingCancelled + +```solidity +event OptimisticMintingCancelled(address guardian, uint256 depositKey) +``` + +### OptimisticMintingDebtRepaid + +```solidity +event OptimisticMintingDebtRepaid(address depositor, uint256 optimisticMintingDebt) +``` + +### MinterAdded + +```solidity +event MinterAdded(address minter) +``` + +### MinterRemoved + +```solidity +event MinterRemoved(address minter) +``` + +### GuardianAdded + +```solidity +event GuardianAdded(address guardian) +``` + +### GuardianRemoved + +```solidity +event GuardianRemoved(address guardian) +``` + +### OptimisticMintingPaused + +```solidity +event OptimisticMintingPaused() +``` + +### OptimisticMintingUnpaused + +```solidity +event OptimisticMintingUnpaused() +``` + +### OptimisticMintingFeeUpdateStarted + +```solidity +event OptimisticMintingFeeUpdateStarted(uint32 newOptimisticMintingFeeDivisor) +``` + +### OptimisticMintingFeeUpdated + +```solidity +event OptimisticMintingFeeUpdated(uint32 newOptimisticMintingFeeDivisor) +``` + +### OptimisticMintingDelayUpdateStarted + +```solidity +event OptimisticMintingDelayUpdateStarted(uint32 newOptimisticMintingDelay) +``` + +### OptimisticMintingDelayUpdated + +```solidity +event OptimisticMintingDelayUpdated(uint32 newOptimisticMintingDelay) +``` + +### onlyMinter + +```solidity +modifier onlyMinter() +``` + +### onlyGuardian + +```solidity +modifier onlyGuardian() +``` + +### onlyOwnerOrGuardian + +```solidity +modifier onlyOwnerOrGuardian() +``` + +### whenOptimisticMintingNotPaused + +```solidity +modifier whenOptimisticMintingNotPaused() +``` + +### onlyAfterGovernanceDelay + +```solidity +modifier onlyAfterGovernanceDelay(uint256 updateInitiatedTimestamp) +``` + +### constructor + +```solidity +constructor(contract Bridge _bridge) internal +``` + +### _mint + +```solidity +function _mint(address minter, uint256 amount) internal virtual +``` + +Mints the given amount of TBTC to the given depositor's address. +Implemented by TBTCVault. + +### getMinters + +```solidity +function getMinters() external view returns (address[]) +``` + +Allows to fetch a list of all Minters. + +### requestOptimisticMint + +```solidity +function requestOptimisticMint(bytes32 fundingTxHash, uint32 fundingOutputIndex) external +``` + +Allows a Minter to request for an optimistic minting of TBTC. +The following conditions must be met: +- There is no optimistic minting request for the deposit, +finalized or not. +- The deposit with the given Bitcoin funding transaction hash +and output index has been revealed to the Bridge. +- The deposit has not been swept yet. +- The deposit is targeted into the TBTCVault. +- The optimistic minting is not paused. +After calling this function, the Minter has to wait for +`optimisticMintingDelay` before finalizing the mint with a call +to finalizeOptimisticMint. + +The deposit done on the Bitcoin side must be revealed early enough +to the Bridge on Ethereum to pass the Bridge's validation. The +validation passes successfully only if the deposit reveal is done +respectively earlier than the moment when the deposit refund +locktime is reached, i.e. the deposit becomes refundable. It may +happen that the wallet does not sweep a revealed deposit and one of +the Minters requests an optimistic mint for that deposit just +before the locktime is reached. Guardians must cancel optimistic +minting for this deposit because the wallet will not be able to +sweep it. The on-chain optimistic minting code does not perform any +validation for gas efficiency: it would have to perform the same +validation as `validateDepositRefundLocktime` and expect the entire +`DepositRevealInfo` to be passed to assemble the expected script +hash on-chain. Guardians must validate if the deposit happened on +Bitcoin, that the script hash has the expected format, and that the +wallet is an active one so they can also validate the time left for +the refund. + +### finalizeOptimisticMint + +```solidity +function finalizeOptimisticMint(bytes32 fundingTxHash, uint32 fundingOutputIndex) external +``` + +Allows a Minter to finalize previously requested optimistic +minting. The following conditions must be met: +- The optimistic minting has been requested for the given +deposit. +- The deposit has not been swept yet. +- At least `optimisticMintingDelay` passed since the optimistic +minting was requested for the given deposit. +- The optimistic minting has not been finalized earlier for the +given deposit. +- The optimistic minting request for the given deposit has not +been canceled by a Guardian. +- The optimistic minting is not paused. +This function mints TBTC and increases `optimisticMintingDebt` +for the given depositor. The optimistic minting request is +marked as finalized. + +### cancelOptimisticMint + +```solidity +function cancelOptimisticMint(bytes32 fundingTxHash, uint32 fundingOutputIndex) external +``` + +Allows a Guardian to cancel optimistic minting request. The +following conditions must be met: +- The optimistic minting request for the given deposit exists. +- The optimistic minting request for the given deposit has not +been finalized yet. +Optimistic minting request is removed. It is possible to request +optimistic minting again for the same deposit later. + +Guardians must validate the following conditions for every deposit +for which the optimistic minting was requested: +- The deposit happened on Bitcoin side and it has enough +confirmations. +- The optimistic minting has been requested early enough so that +the wallet has enough time to sweep the deposit. +- The wallet is an active one and it does perform sweeps or it will +perform sweeps once the sweeps are activated. + +### addMinter + +```solidity +function addMinter(address minter) external +``` + +Adds the address to the Minter list. + +### removeMinter + +```solidity +function removeMinter(address minter) external +``` + +Removes the address from the Minter list. + +### addGuardian + +```solidity +function addGuardian(address guardian) external +``` + +Adds the address to the Guardian set. + +### removeGuardian + +```solidity +function removeGuardian(address guardian) external +``` + +Removes the address from the Guardian set. + +### pauseOptimisticMinting + +```solidity +function pauseOptimisticMinting() external +``` + +Pauses the optimistic minting. Note that the pause of the +optimistic minting does not stop the standard minting flow +where wallets sweep deposits. + +### unpauseOptimisticMinting + +```solidity +function unpauseOptimisticMinting() external +``` + +Unpauses the optimistic minting. + +### beginOptimisticMintingFeeUpdate + +```solidity +function beginOptimisticMintingFeeUpdate(uint32 _newOptimisticMintingFeeDivisor) external +``` + +Begins the process of updating optimistic minting fee. +The fee is computed as follows: +`fee = amount / optimisticMintingFeeDivisor`. +For example, if the fee needs to be 2% of each deposit, +the `optimisticMintingFeeDivisor` should be set to `50` because +`1/50 = 0.02 = 2%`. + +See the documentation for optimisticMintingFeeDivisor. + +### finalizeOptimisticMintingFeeUpdate + +```solidity +function finalizeOptimisticMintingFeeUpdate() external +``` + +Finalizes the update process of the optimistic minting fee. + +### beginOptimisticMintingDelayUpdate + +```solidity +function beginOptimisticMintingDelayUpdate(uint32 _newOptimisticMintingDelay) external +``` + +Begins the process of updating optimistic minting delay. + +### finalizeOptimisticMintingDelayUpdate + +```solidity +function finalizeOptimisticMintingDelayUpdate() external +``` + +Finalizes the update process of the optimistic minting delay. + +### calculateDepositKey + +```solidity +function calculateDepositKey(bytes32 fundingTxHash, uint32 fundingOutputIndex) public pure returns (uint256) +``` + +Calculates deposit key the same way as the Bridge contract. +The deposit key is computed as +`keccak256(fundingTxHash | fundingOutputIndex)`. + +### repayOptimisticMintingDebt + +```solidity +function repayOptimisticMintingDebt(address depositor, uint256 amount) internal returns (uint256) +``` + +Used by `TBTCVault.receiveBalanceIncrease` to repay the optimistic +minting debt before TBTC is minted. When optimistic minting is +finalized, debt equal to the value of the deposit being +a subject of the optimistic minting is incurred. When `TBTCVault` +sweeps a deposit, the debt is fully or partially paid off, no +matter if that particular deposit was used for the optimistic +minting or not. + +See `TBTCVault.receiveBalanceIncrease` + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| depositor | address | The depositor whose balance increase is received. | +| amount | uint256 | The balance increase amount for the depositor received. | + +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +| [0] | uint256 | The TBTC amount that should be minted after paying off the optimistic minting debt. | + diff --git a/docs/app-development/tbtc-v2/tbtc-v2-api/generated-docs/vault/TBTCVault.md b/docs/app-development/tbtc-v2/tbtc-v2-api/generated-docs/vault/TBTCVault.md new file mode 100644 index 0000000..0838f0d --- /dev/null +++ b/docs/app-development/tbtc-v2/tbtc-v2-api/generated-docs/vault/TBTCVault.md @@ -0,0 +1,353 @@ +# Solidity API + +## TBTCVault + +TBTC is a fully Bitcoin-backed ERC-20 token pegged to the price of +Bitcoin. It facilitates Bitcoin holders to act on the Ethereum +blockchain and access the decentralized finance (DeFi) ecosystem. +TBTC Vault mints and unmints TBTC based on Bitcoin balances in the +Bank. + +TBTC Vault is the owner of TBTC token contract and is the only contract +minting the token. + +### bank + +```solidity +contract Bank bank +``` + +### tbtcToken + +```solidity +contract TBTC tbtcToken +``` + +### newVault + +```solidity +address newVault +``` + +The address of a new TBTC vault. Set only when the upgrade +process is pending. Once the upgrade gets finalized, the new +TBTC vault will become an owner of TBTC token. + +### upgradeInitiatedTimestamp + +```solidity +uint256 upgradeInitiatedTimestamp +``` + +The timestamp at which an upgrade to a new TBTC vault was +initiated. Set only when the upgrade process is pending. + +### Minted + +```solidity +event Minted(address to, uint256 amount) +``` + +### Unminted + +```solidity +event Unminted(address from, uint256 amount) +``` + +### UpgradeInitiated + +```solidity +event UpgradeInitiated(address newVault, uint256 timestamp) +``` + +### UpgradeFinalized + +```solidity +event UpgradeFinalized(address newVault) +``` + +### onlyBank + +```solidity +modifier onlyBank() +``` + +### constructor + +```solidity +constructor(contract Bank _bank, contract TBTC _tbtcToken, contract Bridge _bridge) public +``` + +### mint + +```solidity +function mint(uint256 amount) external +``` + +Mints the given `amount` of TBTC to the caller previously +transferring `amount / SATOSHI_MULTIPLIER` of the Bank balance +from caller to TBTC Vault. If `amount` is not divisible by +SATOSHI_MULTIPLIER, the remainder is left on the caller's +Bank balance. + +TBTC Vault must have an allowance for caller's balance in the +Bank for at least `amount / SATOSHI_MULTIPLIER`. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| amount | uint256 | Amount of TBTC to mint. | + +### receiveBalanceApproval + +```solidity +function receiveBalanceApproval(address owner, uint256 satoshis, bytes) external +``` + +Transfers `satoshis` of the Bank balance from the caller +to TBTC Vault and mints `satoshis * SATOSHI_MULTIPLIER` of TBTC +to the caller. + +Can only be called by the Bank via `approveBalanceAndCall`. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| owner | address | The owner who approved their Bank balance. | +| satoshis | uint256 | Amount of satoshis used to mint TBTC. | +| | bytes | | + +### receiveBalanceIncrease + +```solidity +function receiveBalanceIncrease(address[] depositors, uint256[] depositedSatoshiAmounts) external +``` + +Mints the same amount of TBTC as the deposited satoshis amount +multiplied by SATOSHI_MULTIPLIER for each depositor in the array. +Can only be called by the Bank after the Bridge swept deposits +and Bank increased balance for the vault. + +Fails if `depositors` array is empty. Expects the length of +`depositors` and `depositedSatoshiAmounts` is the same. + +### unmint + +```solidity +function unmint(uint256 amount) external +``` + +Burns `amount` of TBTC from the caller's balance and transfers +`amount / SATOSHI_MULTIPLIER` back to the caller's balance in +the Bank. If `amount` is not divisible by SATOSHI_MULTIPLIER, +the remainder is left on the caller's account. + +Caller must have at least `amount` of TBTC approved to +TBTC Vault. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| amount | uint256 | Amount of TBTC to unmint. | + +### unmintAndRedeem + +```solidity +function unmintAndRedeem(uint256 amount, bytes redemptionData) external +``` + +Burns `amount` of TBTC from the caller's balance and transfers +`amount / SATOSHI_MULTIPLIER` of Bank balance to the Bridge +requesting redemption based on the provided `redemptionData`. +If `amount` is not divisible by SATOSHI_MULTIPLIER, the +remainder is left on the caller's account. + +Caller must have at least `amount` of TBTC approved to +TBTC Vault. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| amount | uint256 | Amount of TBTC to unmint and request to redeem in Bridge. | +| redemptionData | bytes | Redemption data in a format expected from `redemptionData` parameter of Bridge's `receiveBalanceApproval` function. | + +### receiveApproval + +```solidity +function receiveApproval(address from, uint256 amount, address token, bytes extraData) external +``` + +Burns `amount` of TBTC from the caller's balance. If `extraData` +is empty, transfers `amount` back to the caller's balance in the +Bank. If `extraData` is not empty, requests redemption in the +Bridge using the `extraData` as a `redemptionData` parameter to +Bridge's `receiveBalanceApproval` function. +If `amount` is not divisible by SATOSHI_MULTIPLIER, the +remainder is left on the caller's account. Note that it may +left a token approval equal to the remainder. + +This function is doing the same as `unmint` or `unmintAndRedeem` +(depending on `extraData` parameter) but it allows to execute +unminting without a separate approval transaction. The function can +be called only via `approveAndCall` of TBTC token. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| from | address | TBTC token holder executing unminting. | +| amount | uint256 | Amount of TBTC to unmint. | +| token | address | TBTC token address. | +| extraData | bytes | Redemption data in a format expected from `redemptionData` parameter of Bridge's `receiveBalanceApproval` function. If empty, `receiveApproval` is not requesting a redemption of Bank balance but is instead performing just TBTC unminting to a Bank balance. | + +### initiateUpgrade + +```solidity +function initiateUpgrade(address _newVault) external +``` + +Initiates vault upgrade process. The upgrade process needs to be +finalized with a call to `finalizeUpgrade` function after the +`UPGRADE_GOVERNANCE_DELAY` passes. Only the governance can +initiate the upgrade. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| _newVault | address | The new vault address. | + +### finalizeUpgrade + +```solidity +function finalizeUpgrade() external +``` + +Allows the governance to finalize vault upgrade process. The +upgrade process needs to be first initiated with a call to +`initiateUpgrade` and the `GOVERNANCE_DELAY` needs to pass. +Once the upgrade is finalized, the new vault becomes the owner +of the TBTC token and receives the whole Bank balance of this +vault. + +### recoverERC20FromToken + +```solidity +function recoverERC20FromToken(contract IERC20 token, address recipient, uint256 amount) external +``` + +Allows the governance of the TBTCVault to recover any ERC20 +token sent mistakenly to the TBTC token contract address. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| token | contract IERC20 | Address of the recovered ERC20 token contract. | +| recipient | address | Address the recovered token should be sent to. | +| amount | uint256 | Recovered amount. | + +### recoverERC721FromToken + +```solidity +function recoverERC721FromToken(contract IERC721 token, address recipient, uint256 tokenId, bytes data) external +``` + +Allows the governance of the TBTCVault to recover any ERC721 +token sent mistakenly to the TBTC token contract address. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| token | contract IERC721 | Address of the recovered ERC721 token contract. | +| recipient | address | Address the recovered token should be sent to. | +| tokenId | uint256 | Identifier of the recovered token. | +| data | bytes | Additional data. | + +### recoverERC20 + +```solidity +function recoverERC20(contract IERC20 token, address recipient, uint256 amount) external +``` + +Allows the governance of the TBTCVault to recover any ERC20 +token sent - mistakenly or not - to the vault address. This +function should be used to withdraw TBTC v1 tokens transferred +to TBTCVault as a result of VendingMachine > TBTCVault upgrade. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| token | contract IERC20 | Address of the recovered ERC20 token contract. | +| recipient | address | Address the recovered token should be sent to. | +| amount | uint256 | Recovered amount. | + +### recoverERC721 + +```solidity +function recoverERC721(contract IERC721 token, address recipient, uint256 tokenId, bytes data) external +``` + +Allows the governance of the TBTCVault to recover any ERC721 +token sent mistakenly to the vault address. + +#### Parameters + +| Name | Type | Description | +| ---- | ---- | ----------- | +| token | contract IERC721 | Address of the recovered ERC721 token contract. | +| recipient | address | Address the recovered token should be sent to. | +| tokenId | uint256 | Identifier of the recovered token. | +| data | bytes | Additional data. | + +### amountToSatoshis + +```solidity +function amountToSatoshis(uint256 amount) public view returns (uint256 convertibleAmount, uint256 remainder, uint256 satoshis) +``` + +Returns the amount of TBTC to be minted/unminted, the remainder, +and the Bank balance to be transferred for the given mint/unmint. +Note that if the `amount` is not divisible by SATOSHI_MULTIPLIER, +the remainder is left on the caller's account when minting or +unminting. + +#### Return Values + +| Name | Type | Description | +| ---- | ---- | ----------- | +| convertibleAmount | uint256 | Amount of TBTC to be minted/unminted. | +| remainder | uint256 | Not convertible remainder if amount is not divisible by SATOSHI_MULTIPLIER. | +| satoshis | uint256 | Amount in satoshis - the Bank balance to be transferred for the given mint/unmint | + +### _mint + +```solidity +function _mint(address minter, uint256 amount) internal +``` + +Mints the given amount of TBTC to the given depositor's address. +Implemented by TBTCVault. + +### _unmint + +```solidity +function _unmint(address unminter, uint256 amount) internal +``` + +`amount` MUST be divisible by SATOSHI_MULTIPLIER with no change. + +### _unmintAndRedeem + +```solidity +function _unmintAndRedeem(address redeemer, uint256 amount, bytes redemptionData) internal +``` + +`amount` MUST be divisible by SATOSHI_MULTIPLIER with no change. +