@keep-network/tbtc-v2 0.1.1-dev.6 → 0.1.1-dev.60

package/contracts/bridge/VendingMachine.sol

@@ -1,6 +1,6 @@
 // SPDX-License-Identifier: MIT
 
-pragma solidity 0.8.4;
+pragma solidity ^0.8.9;
 
 import "@openzeppelin/contracts/access/Ownable.sol";
 import "@openzeppelin/contracts/token/ERC20/IERC20.sol";

package/contracts/bridge/Wallets.sol

@@ -0,0 +1,550 @@
+// SPDX-License-Identifier: MIT
+
+// ██████████████     ▐████▌     ██████████████
+// ██████████████     ▐████▌     ██████████████
+//               ▐████▌    ▐████▌
+//               ▐████▌    ▐████▌
+// ██████████████     ▐████▌     ██████████████
+// ██████████████     ▐████▌     ██████████████
+//               ▐████▌    ▐████▌
+//               ▐████▌    ▐████▌
+//               ▐████▌    ▐████▌
+//               ▐████▌    ▐████▌
+//               ▐████▌    ▐████▌
+//               ▐████▌    ▐████▌
+
+pragma solidity ^0.8.9;
+
+import {BTCUtils} from "@keep-network/bitcoin-spv-sol/contracts/BTCUtils.sol";
+import {EcdsaDkg} from "@keep-network/ecdsa/contracts/libraries/EcdsaDkg.sol";
+import {Math} from "@openzeppelin/contracts/utils/math/Math.sol";
+
+import "./BitcoinTx.sol";
+import "./EcdsaLib.sol";
+import "./BridgeState.sol";
+
+/// @title Wallet library
+/// @notice Library responsible for handling integration between Bridge
+///         contract and ECDSA wallets.
+library Wallets {
+    using BTCUtils for bytes;
+
+    /// @notice Represents wallet state:
+    enum WalletState {
+        /// @dev The wallet is unknown to the Bridge.
+        Unknown,
+        /// @dev The wallet can sweep deposits and accept redemption requests.
+        Live,
+        /// @dev The wallet was deemed unhealthy and is expected to move their
+        ///      outstanding funds to another wallet. The wallet can still
+        ///      fulfill their pending redemption requests although new
+        ///      redemption requests and new deposit reveals are not accepted.
+        MovingFunds,
+        /// @dev The wallet moved or redeemed all their funds and is in the
+        ///      closing period where they can be subject of fraud challenges
+        ///      and must defend against them. This state is needed to protect
+        ///      against deposit frauds on deposits revealed but not swept.
+        ///      The closing period must be greater that the deposit refund
+        ///      time plus some time margin.
+        Closing,
+        /// @dev The wallet finalized the closing period successfully and
+        ///      cannot perform any action in the Bridge.
+        Closed,
+        /// @dev The wallet committed a fraud that was reported. The wallet is
+        ///      blocked and can not perform any actions in the Bridge.
+        ///      Off-chain coordination with the wallet operators is needed to
+        ///      recover funds.
+        Terminated
+    }
+
+    /// @notice Holds information about a wallet.
+    struct Wallet {
+        // Identifier of a ECDSA Wallet registered in the ECDSA Wallet Registry.
+        bytes32 ecdsaWalletID;
+        // Latest wallet's main UTXO hash computed as
+        // keccak256(txHash | txOutputIndex | txOutputValue). The `tx` prefix
+        // refers to the transaction which created that main UTXO. The `txHash`
+        // is `bytes32` (ordered as in Bitcoin internally), `txOutputIndex`
+        // an `uint32`, and `txOutputValue` an `uint64` value.
+        bytes32 mainUtxoHash;
+        // The total redeemable value of pending redemption requests targeting
+        // that wallet.
+        uint64 pendingRedemptionsValue;
+        // UNIX timestamp the wallet was created at.
+        uint32 createdAt;
+        // UNIX timestamp indicating the moment the wallet was requested to
+        // move their funds.
+        uint32 movingFundsRequestedAt;
+        // UNIX timestamp indicating the moment the wallet's closing period
+        // started.
+        uint32 closingStartedAt;
+        // Total count of pending moved funds sweep requests targeting this wallet.
+        uint32 pendingMovedFundsSweepRequestsCount;
+        // Current state of the wallet.
+        WalletState state;
+        // Moving funds target wallet commitment submitted by the wallet. It
+        // is built by applying the keccak256 hash over the list of 20-byte
+        // public key hashes of the target wallets.
+        bytes32 movingFundsTargetWalletsCommitmentHash;
+    }
+
+    event NewWalletRequested();
+
+    event NewWalletRegistered(
+        bytes32 indexed ecdsaWalletID,
+        bytes20 indexed walletPubKeyHash
+    );
+
+    event WalletMovingFunds(
+        bytes32 indexed ecdsaWalletID,
+        bytes20 indexed walletPubKeyHash
+    );
+
+    event WalletClosing(
+        bytes32 indexed ecdsaWalletID,
+        bytes20 indexed walletPubKeyHash
+    );
+
+    event WalletClosed(
+        bytes32 indexed ecdsaWalletID,
+        bytes20 indexed walletPubKeyHash
+    );
+
+    event WalletTerminated(
+        bytes32 indexed ecdsaWalletID,
+        bytes20 indexed walletPubKeyHash
+    );
+
+    /// @notice Requests creation of a new wallet. This function just
+    ///         forms a request and the creation process is performed
+    ///         asynchronously. Outcome of that process should be delivered
+    ///         using `registerNewWallet` function.
+    /// @param activeWalletMainUtxo Data of the active wallet's main UTXO, as
+    ///        currently known on the Ethereum chain.
+    /// @dev Requirements:
+    ///      - `activeWalletMainUtxo` components must point to the recent main
+    ///        UTXO of the given active wallet, as currently known on the
+    ///        Ethereum chain. If there is no active wallet at the moment, or
+    ///        the active wallet has no main UTXO, this parameter can be
+    ///        empty as it is ignored.
+    ///      - Wallet creation must not be in progress
+    ///      - If the active wallet is set, one of the following
+    ///        conditions must be true:
+    ///        - The active wallet BTC balance is above the minimum threshold
+    ///          and the active wallet is old enough, i.e. the creation period
+    ///           was elapsed since its creation time
+    ///        - The active wallet BTC balance is above the maximum threshold
+    function requestNewWallet(
+        BridgeState.Storage storage self,
+        BitcoinTx.UTXO calldata activeWalletMainUtxo
+    ) external {
+        require(
+            self.ecdsaWalletRegistry.getWalletCreationState() ==
+                EcdsaDkg.State.IDLE,
+            "Wallet creation already in progress"
+        );
+
+        bytes20 activeWalletPubKeyHash = self.activeWalletPubKeyHash;
+
+        // If the active wallet is set, fetch this wallet's details from
+        // storage to perform conditions check. The `registerNewWallet`
+        // function guarantees an active wallet is always one of the
+        // registered ones.
+        if (activeWalletPubKeyHash != bytes20(0)) {
+            uint64 activeWalletBtcBalance = getWalletBtcBalance(
+                self,
+                activeWalletPubKeyHash,
+                activeWalletMainUtxo
+            );
+            uint32 activeWalletCreatedAt = self
+                .registeredWallets[activeWalletPubKeyHash]
+                .createdAt;
+            /* solhint-disable-next-line not-rely-on-time */
+            bool activeWalletOldEnough = block.timestamp >=
+                activeWalletCreatedAt + self.walletCreationPeriod;
+
+            require(
+                (activeWalletOldEnough &&
+                    activeWalletBtcBalance >=
+                    self.walletCreationMinBtcBalance) ||
+                    activeWalletBtcBalance >= self.walletCreationMaxBtcBalance,
+                "Wallet creation conditions are not met"
+            );
+        }
+
+        emit NewWalletRequested();
+
+        self.ecdsaWalletRegistry.requestNewWallet();
+    }
+
+    /// @notice Gets BTC balance for given the wallet.
+    /// @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.
+    /// @return walletBtcBalance Current BTC balance for the given wallet.
+    /// @dev Requirements:
+    ///      - `walletMainUtxo` 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.
+    function getWalletBtcBalance(
+        BridgeState.Storage storage self,
+        bytes20 walletPubKeyHash,
+        BitcoinTx.UTXO calldata walletMainUtxo
+    ) internal view returns (uint64 walletBtcBalance) {
+        bytes32 walletMainUtxoHash = self
+            .registeredWallets[walletPubKeyHash]
+            .mainUtxoHash;
+
+        // If the wallet has a main UTXO hash set, cross-check it with the
+        // provided plain-text parameter and get the transaction output value
+        // as BTC balance. Otherwise, the BTC balance is just zero.
+        if (walletMainUtxoHash != bytes32(0)) {
+            require(
+                keccak256(
+                    abi.encodePacked(
+                        walletMainUtxo.txHash,
+                        walletMainUtxo.txOutputIndex,
+                        walletMainUtxo.txOutputValue
+                    )
+                ) == walletMainUtxoHash,
+                "Invalid wallet main UTXO data"
+            );
+
+            walletBtcBalance = walletMainUtxo.txOutputValue;
+        }
+
+        return walletBtcBalance;
+    }
+
+    /// @notice Registers a new wallet. This function should be called
+    ///         after the wallet creation process initiated using
+    ///         `requestNewWallet` completes and brings the outcomes.
+    /// @param ecdsaWalletID Wallet's unique identifier.
+    /// @param publicKeyX Wallet's public key's X coordinate.
+    /// @param publicKeyY Wallet's public key's Y coordinate.
+    /// @dev Requirements:
+    ///      - The only caller authorized to call this function is `registry`
+    ///      - Given wallet data must not belong to an already registered wallet
+    function registerNewWallet(
+        BridgeState.Storage storage self,
+        bytes32 ecdsaWalletID,
+        bytes32 publicKeyX,
+        bytes32 publicKeyY
+    ) external {
+        require(
+            msg.sender == address(self.ecdsaWalletRegistry),
+            "Caller is not the ECDSA Wallet Registry"
+        );
+
+        // Compress wallet's public key and calculate Bitcoin's hash160 of it.
+        bytes20 walletPubKeyHash = bytes20(
+            EcdsaLib.compressPublicKey(publicKeyX, publicKeyY).hash160View()
+        );
+
+        Wallet storage wallet = self.registeredWallets[walletPubKeyHash];
+        require(
+            wallet.state == WalletState.Unknown,
+            "ECDSA wallet has been already registered"
+        );
+        wallet.ecdsaWalletID = ecdsaWalletID;
+        wallet.state = WalletState.Live;
+        /* solhint-disable-next-line not-rely-on-time */
+        wallet.createdAt = uint32(block.timestamp);
+
+        // Set the freshly created wallet as the new active wallet.
+        self.activeWalletPubKeyHash = walletPubKeyHash;
+
+        self.liveWalletsCount++;
+
+        emit NewWalletRegistered(ecdsaWalletID, walletPubKeyHash);
+    }
+
+    /// @notice Handles a notification about a wallet heartbeat failure and
+    ///         triggers the wallet moving funds process.
+    /// @param publicKeyX Wallet's public key's X coordinate.
+    /// @param publicKeyY Wallet's public key's Y coordinate.
+    /// @dev Requirements:
+    ///      - The only caller authorized to call this function is `registry`
+    ///      - Wallet must be in Live state
+    function notifyWalletHeartbeatFailed(
+        BridgeState.Storage storage self,
+        bytes32 publicKeyX,
+        bytes32 publicKeyY
+    ) external {
+        require(
+            msg.sender == address(self.ecdsaWalletRegistry),
+            "Caller is not the ECDSA Wallet Registry"
+        );
+
+        // Compress wallet's public key and calculate Bitcoin's hash160 of it.
+        bytes20 walletPubKeyHash = bytes20(
+            EcdsaLib.compressPublicKey(publicKeyX, publicKeyY).hash160View()
+        );
+
+        require(
+            self.registeredWallets[walletPubKeyHash].state == WalletState.Live,
+            "ECDSA wallet must be in Live state"
+        );
+
+        moveFunds(self, walletPubKeyHash);
+    }
+
+    /// @notice Handles a notification about a wallet redemption timeout.
+    ///         Triggers the wallet moving funds process only if the wallet is
+    ///         still in the Live state. That means multiple action timeouts can
+    ///         be reported for the same wallet but only the first report
+    ///         requests the wallet to move their funds.
+    /// @param walletPubKeyHash 20-byte public key hash of the wallet
+    /// @dev Requirements:
+    ///      - The wallet must be in the `Live` or `MovingFunds` state
+    function notifyWalletTimedOutRedemption(
+        BridgeState.Storage storage self,
+        bytes20 walletPubKeyHash
+    ) internal {
+        WalletState walletState = self
+            .registeredWallets[walletPubKeyHash]
+            .state;
+
+        require(
+            walletState == WalletState.Live ||
+                walletState == WalletState.MovingFunds,
+            "ECDSA wallet must be in Live or MovingFunds state"
+        );
+
+        if (walletState == WalletState.Live) {
+            moveFunds(self, walletPubKeyHash);
+        }
+    }
+
+    /// @notice Notifies that the wallet is either old enough or has too few
+    ///         satoshis 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.
+    /// @dev Requirements:
+    ///      - Wallet must not be set as the current active wallet
+    ///      - Wallet must exceed the wallet maximum age OR the wallet BTC
+    ///        balance must be lesser than the minimum threshold. If the latter
+    ///        case is true, the `walletMainUtxo` 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 since the wallet balance is
+    ///        assumed to be zero.
+    ///      - Wallet must be in Live state
+    function notifyCloseableWallet(
+        BridgeState.Storage storage self,
+        bytes20 walletPubKeyHash,
+        BitcoinTx.UTXO calldata walletMainUtxo
+    ) external {
+        require(
+            self.activeWalletPubKeyHash != walletPubKeyHash,
+            "Active wallet cannot be considered closeable"
+        );
+
+        Wallet storage wallet = self.registeredWallets[walletPubKeyHash];
+        require(
+            wallet.state == WalletState.Live,
+            "ECDSA wallet must be in Live state"
+        );
+
+        /* solhint-disable-next-line not-rely-on-time */
+        bool walletOldEnough = block.timestamp >=
+            wallet.createdAt + self.walletMaxAge;
+
+        require(
+            walletOldEnough ||
+                getWalletBtcBalance(self, walletPubKeyHash, walletMainUtxo) <
+                self.walletClosureMinBtcBalance,
+            "Wallet needs to be old enough or have too few satoshis"
+        );
+
+        moveFunds(self, walletPubKeyHash);
+    }
+
+    /// @notice Requests a wallet to move their funds. If the wallet balance
+    ///         is zero, the wallet closing begins immediately. If the move
+    ///         funds request refers to the current active wallet, such a wallet
+    ///         is no longer considered active and the active wallet slot
+    ///         is unset allowing to trigger a new wallet creation immediately.
+    /// @param walletPubKeyHash 20-byte public key hash of the wallet
+    /// @dev Requirements:
+    ///      - The caller must make sure that the wallet is in the Live state
+    function moveFunds(
+        BridgeState.Storage storage self,
+        bytes20 walletPubKeyHash
+    ) internal {
+        Wallet storage wallet = self.registeredWallets[walletPubKeyHash];
+
+        if (wallet.mainUtxoHash == bytes32(0)) {
+            // If the wallet has no main UTXO, that means its BTC balance
+            // is zero and the wallet closing should begin immediately.
+            beginWalletClosing(self, walletPubKeyHash);
+        } else {
+            // Otherwise, initialize the moving funds process.
+            wallet.state = WalletState.MovingFunds;
+            /* solhint-disable-next-line not-rely-on-time */
+            wallet.movingFundsRequestedAt = uint32(block.timestamp);
+
+            emit WalletMovingFunds(wallet.ecdsaWalletID, walletPubKeyHash);
+        }
+
+        if (self.activeWalletPubKeyHash == walletPubKeyHash) {
+            // If the move funds request refers to the current active wallet,
+            // unset the active wallet and make the wallet creation process
+            // possible in order to get a new healthy active wallet.
+            delete self.activeWalletPubKeyHash;
+        }
+
+        self.liveWalletsCount--;
+    }
+
+    /// @notice Begins the closing period of the given wallet.
+    /// @param walletPubKeyHash 20-byte public key hash of the wallet
+    /// @dev Requirements:
+    ///      - The caller must make sure that the wallet is in the
+    ///        MovingFunds state
+    function beginWalletClosing(
+        BridgeState.Storage storage self,
+        bytes20 walletPubKeyHash
+    ) internal {
+        Wallet storage wallet = self.registeredWallets[walletPubKeyHash];
+        // Initialize the closing period.
+        wallet.state = WalletState.Closing;
+        /* solhint-disable-next-line not-rely-on-time */
+        wallet.closingStartedAt = uint32(block.timestamp);
+
+        emit WalletClosing(wallet.ecdsaWalletID, walletPubKeyHash);
+    }
+
+    /// @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(
+        BridgeState.Storage storage self,
+        bytes20 walletPubKeyHash
+    ) internal {
+        Wallet storage wallet = self.registeredWallets[walletPubKeyHash];
+
+        require(
+            wallet.state == WalletState.Closing,
+            "ECDSA wallet must be in Closing state"
+        );
+
+        require(
+            /* solhint-disable-next-line not-rely-on-time */
+            block.timestamp >
+                wallet.closingStartedAt + self.walletClosingPeriod,
+            "Closing period has not elapsed yet"
+        );
+
+        finalizeWalletClosing(self, walletPubKeyHash);
+    }
+
+    /// @notice Finalizes the closing period of the given wallet and notifies
+    ///         the ECDSA registry about this fact.
+    /// @param walletPubKeyHash 20-byte public key hash of the wallet
+    /// @dev Requirements:
+    ///      - The caller must make sure that the wallet is in the Closing state
+    function finalizeWalletClosing(
+        BridgeState.Storage storage self,
+        bytes20 walletPubKeyHash
+    ) internal {
+        Wallet storage wallet = self.registeredWallets[walletPubKeyHash];
+
+        wallet.state = WalletState.Closed;
+
+        emit WalletClosed(wallet.ecdsaWalletID, walletPubKeyHash);
+
+        self.ecdsaWalletRegistry.closeWallet(wallet.ecdsaWalletID);
+    }
+
+    /// @notice Terminates the given wallet and notifies the ECDSA registry
+    ///         about this fact. If the wallet termination refers to the current
+    ///         active wallet, such a wallet is no longer considered active and
+    ///         the active wallet slot is unset allowing to trigger a new wallet
+    ///         creation immediately.
+    /// @param walletPubKeyHash 20-byte public key hash of the wallet
+    /// @dev Requirements:
+    ///      - The caller must make sure that the wallet is in the
+    ///        Live or MovingFunds or Closing state.
+    function terminateWallet(
+        BridgeState.Storage storage self,
+        bytes20 walletPubKeyHash
+    ) internal {
+        Wallet storage wallet = self.registeredWallets[walletPubKeyHash];
+
+        if (wallet.state == WalletState.Live) {
+            self.liveWalletsCount--;
+        }
+
+        wallet.state = WalletState.Terminated;
+
+        emit WalletTerminated(wallet.ecdsaWalletID, walletPubKeyHash);
+
+        if (self.activeWalletPubKeyHash == walletPubKeyHash) {
+            // If termination refers to the current active wallet,
+            // unset the active wallet and make the wallet creation process
+            // possible in order to get a new healthy active wallet.
+            delete self.activeWalletPubKeyHash;
+        }
+
+        self.ecdsaWalletRegistry.closeWallet(wallet.ecdsaWalletID);
+    }
+
+    /// @notice Notifies that the wallet completed the moving funds process
+    ///         successfully. Checks if the funds were moved to the expected
+    ///         target wallets. Closes the source wallet if everything went
+    ///         good and reverts otherwise.
+    /// @param walletPubKeyHash 20-byte public key hash of the wallet
+    /// @param targetWalletsHash 32-byte keccak256 hash over the list of
+    ///        20-byte public key hashes of the target wallets actually used
+    ///        within the moving funds transactions.
+    /// @dev Requirements:
+    ///      - The caller must make sure the moving funds transaction actually
+    ///        happened on Bitcoin chain and fits the protocol requirements.
+    ///      - The source wallet must be in the MovingFunds state
+    ///      - The target wallets commitment must be submitted by the source
+    ///        wallet.
+    ///      - The actual target wallets used in the moving funds transaction
+    ///        must be exactly the same as the target wallets commitment.
+    function notifyWalletFundsMoved(
+        BridgeState.Storage storage self,
+        bytes20 walletPubKeyHash,
+        bytes32 targetWalletsHash
+    ) internal {
+        Wallet storage wallet = self.registeredWallets[walletPubKeyHash];
+        // Check that the wallet is in the MovingFunds state but don't check
+        // if the moving funds timeout is exceeded. That should give a
+        // possibility to move funds in case when timeout was hit but was
+        // not reported yet.
+        require(
+            wallet.state == WalletState.MovingFunds,
+            "ECDSA wallet must be in MovingFunds state"
+        );
+
+        bytes32 targetWalletsCommitmentHash = wallet
+            .movingFundsTargetWalletsCommitmentHash;
+
+        require(
+            targetWalletsCommitmentHash != bytes32(0),
+            "Target wallets commitment not submitted yet"
+        );
+
+        // Make sure that the target wallets where funds were moved to are
+        // exactly the same as the ones the source wallet committed to.
+        require(
+            targetWalletsCommitmentHash == targetWalletsHash,
+            "Target wallets don't correspond to the commitment"
+        );
+
+        // If funds were moved, the wallet has no longer a main UTXO.
+        delete wallet.mainUtxoHash;
+
+        beginWalletClosing(self, walletPubKeyHash);
+    }
+}

package/contracts/token/TBTC.sol

@@ -1,6 +1,6 @@
 // SPDX-License-Identifier: MIT
 
-pragma solidity 0.8.4;
+pragma solidity ^0.8.9;
 
 import "@thesis/solidity-contracts/contracts/token/ERC20WithPermit.sol";
 import "@thesis/solidity-contracts/contracts/token/MisfundRecovery.sol";

package/contracts/vault/IVault.sol

@@ -13,25 +13,47 @@
 //               ▐████▌    ▐████▌
 //               ▐████▌    ▐████▌
 
-pragma solidity 0.8.4;
+pragma solidity ^0.8.9;
 
 /// @title Bank Vault interface
 /// @notice `IVault` is an interface for a smart contract consuming Bank
-///         balances allowing the smart contract to receive Bank balances right
-///         after sweeping the deposit by the Bridge. This method allows the
-///         depositor to route their deposit revealed to the Bridge to the
-///         particular smart contract in the same transaction the deposit is
-///         revealed. This way, the depositor does not have to execute
-///         additional transaction after the deposit gets swept by the Bridge.
+///         balances of other contracts or externally owned accounts (EOA).
 interface IVault {
+    /// @notice Called by the Bank in `approveBalanceAndCall` function after
+    ///         the balance `owner` approved `amount` of their balance in the
+    ///         Bank for the vault. This way, the depositor can approve balance
+    ///         and call the vault to use the approved balance in a single
+    ///         transaction.
+    /// @param owner Address of the Bank balance owner who approved their
+    ///        balance to be used by the vault
+    /// @param amount The amount of the Bank balance approved by the owner
+    ///        to be used by the vault
+    // @dev The implementation must ensure this function can only be called
+    ///      by the Bank. The Bank does _not_ guarantee that the `amount`
+    ///      approved by the `owner` currently exists on their balance. That is,
+    ///      the `owner` could approve more balance than they currently have.
+    ///      This works the same as `Bank.approve` function. The vault must
+    ///      ensure the actual balance is checked before performing any action
+    ///      based on it.
+    function receiveBalanceApproval(address owner, uint256 amount) external;
+
     /// @notice Called by the Bank in `increaseBalanceAndCall` function after
-    ///         increasing the balance in the Bank for the vault.
+    ///         increasing the balance in the Bank for the vault. It happens in
+    ///         the same transaction in which deposits were swept by the Bridge.
+    ///         This allows the depositor to route their deposit revealed to the
+    ///         Bridge to the particular smart contract (vault) in the same
+    ///         transaction in which the deposit is revealed. This way, the
+    ///         depositor does not have to execute additional transaction after
+    ///         the deposit gets swept by the Bridge to approve and transfer
+    ///         their balance to the vault.
     /// @param depositors Addresses of depositors whose deposits have been swept
     /// @param depositedAmounts Amounts deposited by individual depositors and
     ///        swept
     /// @dev The implementation must ensure this function can only be called
-    ///      by the Bank.
-    function onBalanceIncreased(
+    ///      by the Bank. The Bank guarantees that the vault's balance was
+    ///      increased by the sum of all deposited amounts before this function
+    ///      is called, in the same transaction.
+    function receiveBalanceIncrease(
         address[] calldata depositors,
         uint256[] calldata depositedAmounts
     ) external;

package/contracts/vault/TBTCVault.sol

@@ -13,7 +13,7 @@
 //               ▐████▌    ▐████▌
 //               ▐████▌    ▐████▌
 
-pragma solidity 0.8.4;
+pragma solidity ^0.8.9;
 
 import "./IVault.sol";
 import "../bank/Bank.sol";
@@ -70,13 +70,31 @@ contract TBTCVault is IVault {
         bank.transferBalanceFrom(minter, address(this), amount);
     }
 
+    /// @notice Transfers the given `amount` of the Bank balance from the caller
+    ///         to TBTC Vault and mints `amount` of TBTC to the caller.
+    /// @dev Can only be called by the Bank via `approveBalanceAndCall`.
+    /// @param owner The owner who approved their Bank balance
+    /// @param amount Amount of TBTC to mint
+    function receiveBalanceApproval(address owner, uint256 amount)
+        external
+        override
+        onlyBank
+    {
+        require(
+            bank.balanceOf(owner) >= amount,
+            "Amount exceeds balance in the bank"
+        );
+        _mint(owner, amount);
+        bank.transferBalanceFrom(owner, address(this), amount);
+    }
+
     /// @notice Mints the same amount of TBTC as the deposited amount for each
     ///         depositor in the array. Can only be called by the Bank after the
     ///         Bridge swept deposits and Bank increased balance for the
     ///         vault.
     /// @dev Fails if `depositors` array is empty. Expects the length of
     ///      `depositors` and `depositedAmounts` is the same.
-    function onBalanceIncreased(
+    function receiveBalanceIncrease(
         address[] calldata depositors,
         uint256[] calldata depositedAmounts
     ) external override onlyBank {