@keep-network/tbtc-v2 0.1.1-dev.43 → 0.1.1-dev.46

package/contracts/bridge/Bridge.sol

@@ -53,6 +53,10 @@ import "../bank/Bank.sol";
 /// @dev Bridge is an upgradeable component of the Bank. The order of
 ///      functionalities in this contract is: deposit, sweep, redemption,
 ///      moving funds, wallet lifecycle, frauds, parameters.
+///
+/// TODO: Revisit all events and look which parameters should be indexed.
+/// TODO: Align the convention around `param` and `dev` endings. They should
+///       not have a punctuation mark.
 contract Bridge is Ownable, EcdsaWalletOwner {
     using BridgeState for BridgeState.Storage;
     using Deposit for BridgeState.Storage;
@@ -102,11 +106,19 @@ contract Bridge is Ownable, EcdsaWalletOwner {
         bytes20 indexed walletPubKeyHash
     );
 
+    event MovingFundsCommitmentSubmitted(
+        bytes20 walletPubKeyHash,
+        bytes20[] targetWallets,
+        address submitter
+    );
+
     event MovingFundsCompleted(
         bytes20 walletPubKeyHash,
         bytes32 movingFundsTxHash
     );
 
+    event MovingFundsTimedOut(bytes20 walletPubKeyHash);
+
     event NewWalletRequested();
 
     event NewWalletRegistered(
@@ -114,6 +126,11 @@ contract Bridge is Ownable, EcdsaWalletOwner {
         bytes20 indexed walletPubKeyHash
     );
 
+    event WalletClosing(
+        bytes32 indexed ecdsaWalletID,
+        bytes20 indexed walletPubKeyHash
+    );
+
     event WalletClosed(
         bytes32 indexed ecdsaWalletID,
         bytes20 indexed walletPubKeyHash
@@ -125,27 +142,54 @@ contract Bridge is Ownable, EcdsaWalletOwner {
     );
 
     event FraudChallengeSubmitted(
-        bytes20 walletPublicKeyHash,
+        bytes20 walletPubKeyHash,
         bytes32 sighash,
         uint8 v,
         bytes32 r,
         bytes32 s
     );
 
-    event FraudChallengeDefeated(bytes20 walletPublicKeyHash, bytes32 sighash);
+    event FraudChallengeDefeated(bytes20 walletPubKeyHash, bytes32 sighash);
 
     event FraudChallengeDefeatTimedOut(
-        bytes20 walletPublicKeyHash,
+        bytes20 walletPubKeyHash,
         bytes32 sighash
     );
 
     event VaultStatusUpdated(address indexed vault, bool isTrusted);
 
+    event DepositParametersUpdated(
+        uint64 depositDustThreshold,
+        uint64 depositTreasuryFeeDivisor,
+        uint64 depositTxMaxFee
+    );
+
+    event RedemptionParametersUpdated(
+        uint64 redemptionDustThreshold,
+        uint64 redemptionTreasuryFeeDivisor,
+        uint64 redemptionTxMaxFee,
+        uint256 redemptionTimeout
+    );
+
+    event MovingFundsParametersUpdated(
+        uint64 movingFundsTxMaxTotalFee,
+        uint32 movingFundsTimeout
+    );
+
     event WalletParametersUpdated(
         uint32 walletCreationPeriod,
         uint64 walletMinBtcBalance,
         uint64 walletMaxBtcBalance,
-        uint32 walletMaxAge
+        uint32 walletMaxAge,
+        uint64 walletMaxBtcTransfer,
+        uint32 walletClosingPeriod
+    );
+
+    event FraudParametersUpdated(
+        uint256 fraudSlashingAmount,
+        uint256 fraudNotifierRewardMultiplier,
+        uint256 fraudChallengeDefeatTimeout,
+        uint256 fraudChallengeDepositAmount
     );
 
     constructor(
@@ -181,6 +225,7 @@ contract Bridge is Ownable, EcdsaWalletOwner {
         self.redemptionTxMaxFee = 10000; // 10000 satoshi
         self.redemptionTimeout = 172800; // 48 hours
         self.movingFundsTxMaxTotalFee = 10000; // 10000 satoshi
+        self.movingFundsTimeout = 7 days;
         self.fraudSlashingAmount = 10000 * 1e18; // 10000 T
         self.fraudNotifierRewardMultiplier = 100; // 100%
         self.fraudChallengeDefeatTimeout = 7 days;
@@ -189,6 +234,8 @@ contract Bridge is Ownable, EcdsaWalletOwner {
         self.walletMinBtcBalance = 1e8; // 1 BTC
         self.walletMaxBtcBalance = 10e8; // 10 BTC
         self.walletMaxAge = 26 weeks; // ~6 months
+        self.walletMaxBtcTransfer = 10e8; // 10 BTC
+        self.walletClosingPeriod = 40 days;
     }
 
     /// @notice Used by the depositor to reveal information about their P2(W)SH
@@ -408,6 +455,61 @@ contract Bridge is Ownable, EcdsaWalletOwner {
         self.notifyRedemptionTimeout(walletPubKeyHash, redeemerOutputScript);
     }
 
+    /// @notice 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.
+    /// @param walletPubKeyHash 20-byte public key hash of the source wallet
+    /// @param walletMainUtxo Data of the source wallet's main UTXO, as
+    ///        currently known on the Ethereum chain
+    /// @param walletMembersIDs Identifiers of the source wallet signing group
+    ///        members
+    /// @param walletMemberIndex Position of the caller in the source wallet
+    ///        signing group members list
+    /// @param targetWallets List of 20-byte public key hashes of the target
+    ///        wallets that the source wallet commits to move the funds to
+    /// @dev 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 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
+    function submitMovingFundsCommitment(
+        bytes20 walletPubKeyHash,
+        BitcoinTx.UTXO calldata walletMainUtxo,
+        uint32[] calldata walletMembersIDs,
+        uint256 walletMemberIndex,
+        bytes20[] calldata targetWallets
+    ) external {
+        self.submitMovingFundsCommitment(
+            walletPubKeyHash,
+            walletMainUtxo,
+            walletMembersIDs,
+            walletMemberIndex,
+            targetWallets
+        );
+    }
+
     /// @notice Used by the wallet to prove the BTC moving funds transaction
     ///         and to make the necessary state changes. Moving funds is only
     ///         accepted if it satisfies SPV proof.
@@ -467,6 +569,16 @@ contract Bridge is Ownable, EcdsaWalletOwner {
         );
     }
 
+    /// @notice Notifies about a timed out moving funds process. Terminates
+    ///         the wallet and slashes signing group members as a result.
+    /// @param walletPubKeyHash 20-byte public key hash of the wallet
+    /// @dev Requirements:
+    ///      - The wallet must be in the MovingFunds state
+    ///      - The moving funds timeout must be actually exceeded
+    function notifyMovingFundsTimeout(bytes20 walletPubKeyHash) external {
+        self.notifyMovingFundsTimeout(walletPubKeyHash);
+    }
+
     /// @notice Requests creation of a new wallet. This function just
     ///         forms a request and the creation process is performed
     ///         asynchronously. Once a wallet is created, the ECDSA Wallet
@@ -525,7 +637,7 @@ contract Bridge is Ownable, EcdsaWalletOwner {
     }
 
     /// @notice Notifies that the wallet is either old enough or has too few
-    ///         satoshis left and qualifies to be closed.
+    ///         satoshi left and qualifies to be closed.
     /// @param walletPubKeyHash 20-byte public key hash of the wallet
     /// @param walletMainUtxo Data of the wallet's main UTXO, as currently
     ///        known on the Ethereum chain.
@@ -546,6 +658,19 @@ contract Bridge is Ownable, EcdsaWalletOwner {
         self.notifyCloseableWallet(walletPubKeyHash, walletMainUtxo);
     }
 
+    /// @notice Notifies about the end of the closing period for the given wallet.
+    ///         Closes the wallet ultimately and notifies the ECDSA registry
+    ///         about this fact.
+    /// @param walletPubKeyHash 20-byte public key hash of the wallet
+    /// @dev Requirements:
+    ///      - The wallet must be in the Closing state
+    ///      - The wallet closing period must have elapsed
+    function notifyWalletClosingPeriodElapsed(bytes20 walletPubKeyHash)
+        external
+    {
+        self.notifyWalletClosingPeriodElapsed(walletPubKeyHash);
+    }
+
     /// @notice 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
@@ -571,8 +696,8 @@ contract Bridge is Ownable, EcdsaWalletOwner {
     ///        for reference
     /// @param signature Bitcoin signature in the R/S/V format
     /// @dev Requirements:
-    ///      - Wallet behind `walletPubKey` must be in `Live` or `MovingFunds`
-    ///        state
+    ///      - Wallet behind `walletPublicKey` must be in Live or MovingFunds
+    ///        or Closing state
     ///      - The challenger must send appropriate amount of ETH used as
     ///        fraud challenge deposit
     ///      - The signature (represented by r, s and v) must be generated by
@@ -670,40 +795,187 @@ contract Bridge is Ownable, EcdsaWalletOwner {
         emit VaultStatusUpdated(vault, isTrusted);
     }
 
-    // TODO: updateDepositParameters
-    // TODO: updateRedemptionParameters
-    // TODO: updateMovingFundsParameters
+    /// @notice Updates parameters of deposits.
+    /// @param depositDustThreshold New value of the deposit dust threshold in
+    ///        satoshis. It is 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
+    /// @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
+    ///        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%`
+    /// @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
+    /// @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
+    function updateDepositParameters(
+        uint64 depositDustThreshold,
+        uint64 depositTreasuryFeeDivisor,
+        uint64 depositTxMaxFee
+    ) external onlyOwner {
+        self.updateDepositParameters(
+            depositDustThreshold,
+            depositTreasuryFeeDivisor,
+            depositTxMaxFee
+        );
+    }
+
+    /// @notice Updates parameters of redemptions.
+    /// @param redemptionDustThreshold New value of the redemption dust
+    ///        threshold in satoshis. It is 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.
+    /// @param redemptionTreasuryFeeDivisor New value of the redemption
+    ///        treasury fee divisor. It is the 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%`.
+    /// @param redemptionTxMaxFee New value of the redemption transaction max
+    ///        fee in satoshis. It is the 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.
+    /// @param redemptionTimeout New value of the redemption timeout in seconds.
+    ///        It is the 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 TBTC is returned to the
+    ///        redeemer in full amount.
+    /// @dev Requirements:
+    ///      - Redemption dust threshold must be greater than zero
+    ///      - 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
+    function updateRedemptionParameters(
+        uint64 redemptionDustThreshold,
+        uint64 redemptionTreasuryFeeDivisor,
+        uint64 redemptionTxMaxFee,
+        uint256 redemptionTimeout
+    ) external onlyOwner {
+        self.updateRedemptionParameters(
+            redemptionDustThreshold,
+            redemptionTreasuryFeeDivisor,
+            redemptionTxMaxFee,
+            redemptionTimeout
+        );
+    }
+
+    /// @notice Updates parameters of moving funds.
+    /// @param movingFundsTxMaxTotalFee New value of the moving funds transaction
+    ///        max total fee in satoshis. It is the 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.
+    /// @param movingFundsTimeout New value of the moving funds timeout in
+    ///        seconds. It is the 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.
+    /// @dev Requirements:
+    ///      - Moving funds transaction max total fee must be greater than zero
+    ///      - Moving funds timeout must be greater than zero
+    function updateMovingFundsParameters(
+        uint64 movingFundsTxMaxTotalFee,
+        uint32 movingFundsTimeout
+    ) external onlyOwner {
+        self.updateMovingFundsParameters(
+            movingFundsTxMaxTotalFee,
+            movingFundsTimeout
+        );
+    }
 
     /// @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
     /// @param walletMinBtcBalance New value of the wallet minimum BTC balance
-    ///        in satoshis, used to decide about wallet creation or closing
+    ///        in satoshi, used to decide about wallet creation or closing
     /// @param walletMaxBtcBalance New value of the wallet maximum BTC balance
-    ///        in satoshis, used to decide about wallet creation
+    ///        in satoshi, used to decide about wallet creation
     /// @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
+    /// @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
+    /// @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
     /// @dev Requirements:
     ///      - 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
     function updateWalletParameters(
         uint32 walletCreationPeriod,
         uint64 walletMinBtcBalance,
         uint64 walletMaxBtcBalance,
-        uint32 walletMaxAge
+        uint32 walletMaxAge,
+        uint64 walletMaxBtcTransfer,
+        uint32 walletClosingPeriod
     ) external onlyOwner {
         self.updateWalletParameters(
             walletCreationPeriod,
             walletMinBtcBalance,
             walletMaxBtcBalance,
-            walletMaxAge
+            walletMaxAge,
+            walletMaxBtcTransfer,
+            walletClosingPeriod
         );
     }
 
-    // TODO: updateFraudParameters
+    /// @notice Updates parameters related to frauds.
+    /// @param fraudSlashingAmount New value of the fraud slashing amount in T,
+    ///        it is the amount slashed from each wallet member for committing
+    ///        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]
+    /// @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
+    /// @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
+    /// @dev Requirements:
+    ///      - Fraud notifier reward multiplier must be in the range [0, 100]
+    ///      - Fraud challenge defeat timeout must be greater than 0
+    function updateFraudParameters(
+        uint256 fraudSlashingAmount,
+        uint256 fraudNotifierRewardMultiplier,
+        uint256 fraudChallengeDefeatTimeout,
+        uint256 fraudChallengeDepositAmount
+    ) external onlyOwner {
+        self.updateFraudParameters(
+            fraudSlashingAmount,
+            fraudNotifierRewardMultiplier,
+            fraudChallengeDefeatTimeout,
+            fraudChallengeDepositAmount
+        );
+    }
 
     /// @notice Collection of all revealed deposits indexed by
     ///         keccak256(fundingTxHash | fundingOutputIndex).
@@ -792,6 +1064,12 @@ contract Bridge is Ownable, EcdsaWalletOwner {
         return self.activeWalletPubKeyHash;
     }
 
+    /// @notice Gets the live wallets count.
+    /// @return The current count of wallets being in the Live state.
+    function liveWalletsCount() external view returns (uint32) {
+        return self.liveWalletsCount;
+    }
+
     /// @notice Returns the fraud challenge identified by the given key built
     ///         as keccak256(walletPublicKey|sighash).
     function fraudChallenges(uint256 challengeKey)
@@ -862,6 +1140,8 @@ contract Bridge is Ownable, EcdsaWalletOwner {
     ///         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.
     /// @return redemptionTimeout 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.
@@ -889,13 +1169,17 @@ contract Bridge is Ownable, EcdsaWalletOwner {
     ///         transaction fee that is acceptable in a single moving funds
     ///         transaction. This is a _total_ max fee for the entire moving
     ///         funds transaction.
+    /// @return movingFundsTimeout 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.
     function movingFundsParameters()
         external
         view
-        returns (uint64 movingFundsTxMaxTotalFee)
+        returns (uint64 movingFundsTxMaxTotalFee, uint32 movingFundsTimeout)
     {
-        // TODO: we will have more parameters here, for example moving funds timeout
         movingFundsTxMaxTotalFee = self.movingFundsTxMaxTotalFee;
+        movingFundsTimeout = self.movingFundsTimeout;
     }
 
     /// @return walletCreationPeriod Determines how frequently a new wallet
@@ -906,6 +1190,13 @@ contract Bridge is Ownable, EcdsaWalletOwner {
     ///         used to decide about wallet creation.
     /// @return walletMaxAge The maximum age of a wallet in seconds, after which
     ///         the wallet moving funds process can be requested.
+    /// @return walletMaxBtcTransfer The maximum BTC amount in satoshi than
+    ///         can be transferred to a single target wallet during the moving
+    ///         funds process.
+    /// @return walletClosingPeriod 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.
     function walletParameters()
         external
         view
@@ -913,13 +1204,17 @@ contract Bridge is Ownable, EcdsaWalletOwner {
             uint32 walletCreationPeriod,
             uint64 walletMinBtcBalance,
             uint64 walletMaxBtcBalance,
-            uint32 walletMaxAge
+            uint32 walletMaxAge,
+            uint64 walletMaxBtcTransfer,
+            uint32 walletClosingPeriod
         )
     {
         walletCreationPeriod = self.walletCreationPeriod;
         walletMinBtcBalance = self.walletMinBtcBalance;
         walletMaxBtcBalance = self.walletMaxBtcBalance;
         walletMaxAge = self.walletMaxAge;
+        walletMaxBtcTransfer = self.walletMaxBtcTransfer;
+        walletClosingPeriod = self.walletClosingPeriod;
     }
 
     /// @notice Returns the current values of Bridge fraud parameters.