@keep-network/tbtc-v2 0.1.1-dev.71 → 0.1.1-dev.74

package/contracts/bridge/BridgeState.sol

@@ -27,7 +27,6 @@ import "./MovingFunds.sol";
 import "../bank/Bank.sol";
 
 library BridgeState {
-    // TODO: Make parameters governable
     struct Storage {
         // Address of the Bank the Bridge belongs to.
         Bank bank;
@@ -179,9 +178,9 @@ library BridgeState {
         // 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
+        //    successfully,
         // - `notifyRedemptionTimeout` in case the request was reported
-        //    to be timed out
+        //    to be timed out.
         mapping(uint256 => Redemption.RedemptionRequest) pendingRedemptions;
         // Collection of all timed out redemptions requests indexed by
         // redemption key built as
@@ -316,7 +315,7 @@ library BridgeState {
     ////       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
+    ///        transaction fee and still satisfy the depositor.
     /// @param _depositTreasuryFeeDivisor 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
@@ -324,16 +323,16 @@ library BridgeState {
     ///        `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%`
+    ///        because `1/50 = 0.02 = 2%`.
     /// @param _depositTxMaxFee 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
+    ///        such transaction is considered a fraud.
     /// @dev Requirements:
-    ///      - Deposit dust threshold must be greater than zero
-    ///      - Deposit treasury fee divisor must be greater than zero
-    ///      - Deposit transaction max fee must be greater than zero
+    ///      - Deposit dust threshold must be greater than zero,
+    ///      - Deposit treasury fee divisor must be greater than zero,
+    ///      - Deposit transaction max fee must be greater than zero.
     function updateDepositParameters(
         Storage storage self,
         uint64 _depositDustThreshold,
@@ -398,20 +397,20 @@ library BridgeState {
     ///        redeemer in full amount.
     /// @param _redemptionTimeoutSlashingAmount New value of the redemption
     ///        timeout slashing amount in T, it is the amount slashed from each
-    ///        wallet member for redemption timeout
+    ///        wallet member for redemption timeout.
     /// @param _redemptionTimeoutNotifierRewardMultiplier 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]
+    ///        The value must be in the range [0, 100].
     /// @dev Requirements:
     ///      - Redemption dust threshold must be greater than moving funds dust
-    ///        threshold
-    ///      - Redemption treasury fee divisor must be greater than zero
-    ///      - Redemption transaction max fee must be greater than zero
-    ///      - Redemption timeout must be greater than zero
+    ///        threshold,
+    ///      - Redemption treasury fee divisor must be greater than zero,
+    ///      - Redemption transaction max fee must be greater than zero,
+    ///      - Redemption timeout must be greater than zero,
     ///      - Redemption timeout notifier reward multiplier must be in the
-    ///        range [0, 100]
+    ///        range [0, 100].
     function updateRedemptionParameters(
         Storage storage self,
         uint64 _redemptionDustThreshold,
@@ -483,12 +482,12 @@ library BridgeState {
     ///        MovingFunds state.
     /// @param _movingFundsTimeoutSlashingAmount New value of the moving funds
     ///        timeout slashing amount in T, it is the amount slashed from each
-    ///        wallet member for moving funds timeout
+    ///        wallet member for moving funds timeout.
     /// @param _movingFundsTimeoutNotifierRewardMultiplier 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]
+    ///        The value must be in the range [0, 100].
     /// @param _movedFundsSweepTxMaxTotalFee 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
@@ -501,23 +500,23 @@ library BridgeState {
     ///        funds.
     /// @param _movedFundsSweepTimeoutSlashingAmount 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
+    ///        slashed from each wallet member for moved funds sweep timeout.
     /// @param _movedFundsSweepTimeoutNotifierRewardMultiplier 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]
+    ///        timeout receives. The value must be in the range [0, 100].
     /// @dev Requirements:
-    ///      - Moving funds transaction max total fee must be greater than zero
+    ///      - 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 must be greater than zero
+    ///        than the redemption dust threshold,
+    ///      - Moving funds timeout must be greater than zero,
     ///      - 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
+    ///        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]
+    ///        range [0, 100].
     function updateMovingFundsParameters(
         Storage storage self,
         uint64 _movingFundsTxMaxTotalFee,
@@ -596,29 +595,29 @@ library BridgeState {
     /// @notice Updates parameters of wallets.
     /// @param _walletCreationPeriod New value of the wallet creation period in
     ///        seconds, determines how frequently a new wallet creation can be
-    ///        requested
+    ///        requested.
     /// @param _walletCreationMinBtcBalance New value of the wallet minimum BTC
-    ///        balance in satoshi, used to decide about wallet creation
+    ///        balance in satoshi, used to decide about wallet creation.
     /// @param _walletCreationMaxBtcBalance New value of the wallet maximum BTC
-    ///        balance in satoshi, used to decide about wallet creation
+    ///        balance in satoshi, used to decide about wallet creation.
     /// @param _walletClosureMinBtcBalance New value of the wallet minimum BTC
-    ///        balance in satoshi, used to decide about wallet closure
+    ///        balance in satoshi, used to decide about wallet closure.
     /// @param _walletMaxAge New value of the wallet maximum age in seconds,
     ///        indicates the maximum age of a wallet in seconds, after which
-    ///        the wallet moving funds process can be requested
+    ///        the wallet moving funds process can be requested.
     /// @param _walletMaxBtcTransfer New value of the wallet maximum BTC transfer
     ///        in satoshi, determines the maximum amount that can be transferred
-    ///        to a single target wallet during the moving funds process
+    ///        to a single target wallet during the moving funds process.
     /// @param _walletClosingPeriod New value of the wallet closing period in
     ///        seconds, 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
+    //         and can be subject of deposit fraud challenges.
     /// @dev Requirements:
-    ///      - Wallet minimum BTC balance must be greater than zero
+    ///      - Wallet minimum BTC balance must be greater than zero,
     ///      - 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
+    ///        minimum BTC balance,
+    ///      - Wallet maximum BTC transfer must be greater than zero,
+    ///      - Wallet closing period must be greater than zero.
     function updateWalletParameters(
         Storage storage self,
         uint32 _walletCreationPeriod,
@@ -668,20 +667,20 @@ library BridgeState {
     /// @notice Updates parameters related to frauds.
     /// @param _fraudChallengeDepositAmount 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
+    ///        challenging the wallet for fraud needs to deposit.
     /// @param _fraudChallengeDefeatTimeout 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
+    ///        defeat a fraud challenge. The value must be greater than zero.
     /// @param _fraudSlashingAmount New value of the fraud slashing amount in T,
     ///        it is the amount slashed from each wallet member for committing
-    ///        a fraud
+    ///        a fraud.
     /// @param _fraudNotifierRewardMultiplier 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]
+    ///        a fraud receives. The value must be in the range [0, 100].
     /// @dev Requirements:
-    ///      - Fraud challenge defeat timeout must be greater than 0
-    ///      - Fraud notifier reward multiplier must be in the range [0, 100]
+    ///      - Fraud challenge defeat timeout must be greater than 0,
+    ///      - Fraud notifier reward multiplier must be in the range [0, 100].
     function updateFraudParameters(
         Storage storage self,
         uint256 _fraudChallengeDepositAmount,

package/contracts/bridge/Deposit.sol

@@ -123,13 +123,13 @@ library Deposit {
     ///         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.
-    /// @param fundingTx Bitcoin funding transaction data, see `BitcoinTx.Info`
-    /// @param reveal Deposit reveal data, see `RevealInfo struct
+    /// @param fundingTx Bitcoin funding transaction data, see `BitcoinTx.Info`.
+    /// @param reveal Deposit reveal data, see `RevealInfo struct.
     /// @dev Requirements:
-    ///      - `reveal.walletPubKeyHash` must identify a `Live` wallet
-    ///      - `reveal.vault` must be 0x0 or point to a trusted vault
+    ///      - `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
+    ///        output of the BTC deposit transaction,
     ///      - `reveal.depositor` must be the Ethereum address used in the
     ///        P2(W)SH BTC deposit transaction,
     ///      - `reveal.blindingFactor` must be the blinding factor used in the
@@ -162,8 +162,6 @@ library Deposit {
             "Vault is not trusted"
         );
 
-        // TODO: Should we enforce a specific locktime at contract level?
-
         bytes memory expectedScript = abi.encodePacked(
             hex"14", // Byte length of depositor Ethereum address.
             reveal.depositor,

package/contracts/bridge/DepositSweep.sol

@@ -105,11 +105,11 @@ library DepositSweep {
     ///         during the reveal transaction, minus their fee share.
     ///
     ///         It is possible to prove the given sweep only one time.
-    /// @param sweepTx Bitcoin sweep transaction data
-    /// @param sweepProof Bitcoin sweep proof data
+    /// @param sweepTx Bitcoin sweep transaction data.
+    /// @param sweepProof Bitcoin sweep proof data.
     /// @param mainUtxo 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
+    ///        this parameter is ignored.
     /// @param vault 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.
@@ -123,7 +123,7 @@ library DepositSweep {
     ///      - `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.
+    ///        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
@@ -131,14 +131,14 @@ library DepositSweep {
     ///        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.
+    ///        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.
+    ///        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.
+    ///        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.
@@ -261,14 +261,14 @@ library DepositSweep {
     ///        Bitcoin transaction.
     /// @param mainUtxo 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
+    ///        this parameter is ignored.
     /// @return wallet Data of the sweeping wallet.
     /// @return resolvedMainUtxo 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`.
     /// @dev Requirements:
-    ///     - Sweeping wallet must be either in Live or MovingFunds state.
+    ///     - 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.
     function resolveDepositSweepingWallet(
@@ -319,7 +319,7 @@ library DepositSweep {
     /// @param sweepTxOutputVector 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
+    ///        it is passed here.
     /// @return walletPubKeyHash 20-byte wallet public key hash.
     /// @return value 8-byte sweep transaction output value.
     function processDepositSweepTxOutput(
@@ -502,8 +502,8 @@ library DepositSweep {
     }
 
     /// @notice Parses a Bitcoin transaction input starting at the given index.
-    /// @param inputVector Bitcoin transaction input vector
-    /// @param inputStartingIndex Index the given input starts at
+    /// @param inputVector Bitcoin transaction input vector.
+    /// @param inputStartingIndex Index the given input starts at.
     /// @return outpointTxHash 32-byte hash of the Bitcoin transaction which is
     ///         pointed in the given input's outpoint.
     /// @return outpointIndex 4-byte index of the Bitcoin transaction output

package/contracts/bridge/Fraud.sol

@@ -109,9 +109,9 @@ library Fraud {
     ///         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
+    ///         challenge or confiscated otherwise.
     /// @param walletPublicKey The public key of the wallet in the uncompressed
-    ///        and unprefixed format (64 bytes)
+    ///        and unprefixed format (64 bytes).
     /// @param preimageSha256 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
@@ -119,17 +119,17 @@ library Fraud {
     ///        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
+    ///        preimage -> (SHA-256) -> preimageSha256 -> (SHA-256) -> sighash.
     /// @param signature Bitcoin signature in the R/S/V format
     /// @dev Requirements:
     ///      - Wallet behind `walletPublicKey` must be in Live or MovingFunds
-    ///        or Closing state
+    ///        or Closing state,
     ///      - The challenger must send appropriate amount of ETH used as
-    ///        fraud challenge deposit
+    ///        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
+    ///        which was calculated from `preimageSha256`,
+    ///      - Wallet can be challenged for the given signature only once.
     function submitFraudChallenge(
         BridgeState.Storage storage self,
         bytes calldata walletPublicKey,
@@ -210,21 +210,21 @@ library Fraud {
     ///         resolved and the amount of ether deposited by the challenger is
     ///         sent to the treasury.
     /// @param walletPublicKey The public key of the wallet in the uncompressed
-    ///        and unprefixed format (64 bytes)
+    ///        and unprefixed format (64 bytes).
     /// @param preimage 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
+    ///        produced for. See BIP-143 for reference.
     /// @param witness Flag indicating whether the preimage was produced for a
     ///        witness input. True for witness, false for non-witness input.
     /// @dev Requirements:
     ///      - `walletPublicKey` and `sighash` calculated as `hash256(preimage)`
-    ///        must identify an open fraud challenge
+    ///        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
+    ///        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
+    ///        given UTXO must be proven in the Bridge.
     function defeatFraudChallenge(
         BridgeState.Storage storage self,
         bytes calldata walletPublicKey,
@@ -277,16 +277,16 @@ library Fraud {
     ///         challenge is marked as resolved and the amount of ether
     ///         deposited by the challenger is sent to the treasury.
     /// @param walletPublicKey The public key of the wallet in the uncompressed
-    ///        and unprefixed format (64 bytes)
+    ///        and unprefixed format (64 bytes),
     /// @param heartbeatMessage 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
+    ///        claim.
     /// @dev Requirements:
     ///      - `walletPublicKey` and `sighash` calculated as
-    ///        `hash256(heartbeatMessage)` must identify an open fraud challenge
+    ///        `hash256(heartbeatMessage)` must identify an open fraud challenge,
     ///      - `heartbeatMessage` must follow a strict format of heartbeat
-    ///        messages
+    ///        messages.
     function defeatFraudChallengeWithHeartbeat(
         BridgeState.Storage storage self,
         bytes calldata walletPublicKey,
@@ -355,8 +355,8 @@ library Fraud {
     ///         deposited is returned to the challenger and the challenger is
     ///         rewarded.
     /// @param walletPublicKey The public key of the wallet in the uncompressed
-    ///        and unprefixed format (64 bytes)
-    /// @param walletMembersIDs Identifiers of the wallet signing group members
+    ///        and unprefixed format (64 bytes).
+    /// @param walletMembersIDs Identifiers of the wallet signing group members.
     /// @param preimageSha256 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
@@ -364,20 +364,20 @@ library Fraud {
     ///        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
+    ///        preimage -> (SHA-256) -> preimageSha256 -> (SHA-256) -> sighash.
     /// @dev Requirements:
     ///      - The wallet must be in the Live or MovingFunds or Closing or
-    ///        Terminated state
+    ///        Terminated state,
     ///      - The `walletPublicKey` and `sighash` calculated from
-    ///        `preimageSha256` must identify an open fraud challenge
+    ///        `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
+    ///        events of the `WalletRegistry` contract,
     ///      - The amount of time indicated by `challengeDefeatTimeout` must pass
-    ///        after the challenge was reported
+    ///        after the challenge was reported.
     function notifyFraudChallengeDefeatTimeout(
         BridgeState.Storage storage self,
         bytes calldata walletPublicKey,
@@ -504,7 +504,7 @@ library Fraud {
     ///        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
+    ///        produced for. See BIP-143 for reference.
     /// @return utxoKey UTXO key that identifies spent input.
     function extractUtxoKeyFromNonWitnessPreimage(bytes calldata preimage)
         internal
@@ -588,7 +588,7 @@ library Fraud {
 
     /// @notice Extracts the sighash type from the given preimage.
     /// @param preimage Serialized subset of the transaction. See BIP-143 for
-    ///        reference
+    ///        reference.
     /// @dev Sighash type is stored as the last 4 bytes in the preimage (little
     ///      endian).
     /// @return sighashType Sighash type as a 32-bit integer.

package/contracts/bridge/Heartbeat.sol

@@ -90,7 +90,7 @@ library Heartbeat {
     ///         heartbeat message.
     /// @param message Message signed by the wallet. It is a potential heartbeat
     ///        message, Bitcoin transaction preimage, or an arbitrary signed
-    ///        bytes
+    ///        bytes.
     /// @dev Wallet heartbeat message must be exactly 16 bytes long with the first
     ///      8 bytes set to 0xffffffffffffffff.
     /// @return True if valid heartbeat message, false otherwise.