bitpro가 원문에서 글자만 모은 내용이에요. 표·그림·수식은 빠지거나 깨질 수 있어요. 전체 36쪽 중 24쪽
d 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. |
# Redemption
## 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*` compone프로젝트로 돌아가기
