Threshold Network 백서 전문

n. 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