Threshold Network 백서 전문

``` 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 | #### 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 ## 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 Redemp