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