@keep-network/tbtc-v2 0.1.1-dev.80 → 0.1.1-dev.83

package/contracts/bridge/Redemption.sol

@@ -233,15 +233,21 @@ library Redemption {
 
     /// @notice Requests redemption of the given amount from the specified
     ///         wallet to the redeemer Bitcoin output script.
+    ///         This function handles the simplest case, where balance owner is
+    ///         the redeemer.
     /// @param walletPubKeyHash The 20-byte wallet public key hash (computed
     ///        using Bitcoin HASH160 over the compressed ECDSA public key).
     /// @param mainUtxo Data of the wallet's main UTXO, as currently known on
     ///        the Ethereum chain.
+    /// @param balanceOwner The address of the Bank balance owner whose balance
+    ///        is getting redeemed. Balance owner address is stored as
+    ///        a redemeer address who will be able co claim back the Bank
+    ///        balance if anything goes wrong during the redemption.
     /// @param redeemerOutputScript The redeemer's length-prefixed output
     ///        script (P2PKH, P2WPKH, P2SH or P2WSH) that will be used to lock
     ///        redeemed BTC.
-    /// @param amount Requested amount in satoshi. This is also the TBTC amount
-    ///        that is taken from redeemer's balance in the Bank upon request.
+    /// @param amount Requested amount in satoshi. This is also the Bank balance
+    ///        that is taken from the `balanceOwner` upon request.
     ///        Once the request is handled, the actual amount of BTC locked
     ///        on the redeemer output script will be always lower than this value
     ///        since the treasury and Bitcoin transaction fees must be incurred.
@@ -258,15 +264,163 @@ library Redemption {
     ///      - Given `walletPubKeyHash` and `redeemerOutputScript` pair can be
     ///        used for only one pending request at the same time,
     ///      - Wallet must have enough Bitcoin balance to proceed the request,
-    ///      - Redeemer must make an allowance in the Bank that the Bridge
+    ///      - Balance owner must make an allowance in the Bank that the Bridge
     ///        contract can spend the given `amount`.
     function requestRedemption(
         BridgeState.Storage storage self,
         bytes20 walletPubKeyHash,
         BitcoinTx.UTXO calldata mainUtxo,
+        address balanceOwner,
         bytes calldata redeemerOutputScript,
         uint64 amount
     ) external {
+        requestRedemption(
+            self,
+            walletPubKeyHash,
+            mainUtxo,
+            balanceOwner,
+            balanceOwner,
+            redeemerOutputScript,
+            amount
+        );
+    }
+
+    /// @notice Requests redemption of the given amount from the specified
+    ///         wallet to the redeemer Bitcoin output script. Used by
+    ///         `Bridge.receiveBalanceApproval`. Can handle more complex cases
+    ///         where balance owner may be someone else than the redeemer.
+    /// @param balanceOwner The address of the Bank balance owner whose balance
+    ///        is getting redeemed.
+    /// @param amount Requested amount in satoshi. This is also the Bank balance
+    ///        that is taken from the `balanceOwner` upon request.
+    ///        Once the request is handled, the actual amount of BTC locked
+    ///        on the redeemer output script will be always lower than this value
+    ///        since the treasury and Bitcoin transaction fees must be incurred.
+    ///        The minimal amount satisfying the request can be computed as:
+    ///        `amount - (amount / redemptionTreasuryFeeDivisor) - redemptionTxMaxFee`.
+    ///        Fees values are taken at the moment of request creation.
+    /// @param redemptionData ABI-encoded redemption data:
+    ///        [
+    ///          address redeemer,
+    ///          bytes20 walletPubKeyHash,
+    ///          bytes32 mainUtxoTxHash,
+    ///          uint32 mainUtxoTxOutputIndex,
+    ///          uint64 mainUtxoTxOutputValue,
+    ///          bytes redeemerOutputScript
+    ///        ]
+    ///
+    ///        - redeemer: The Ethereum address of the redeemer who will be able
+    ///        to claim Bank balance if anything goes wrong during the redemption.
+    ///        In the most basic case, when someone redeems their Bitcoin
+    ///        balance from the Bank, `balanceOwner` is the same as `redemeer`.
+    ///        However, when a Vault is redeeming part of its balance for some
+    ///        redeemer address (for example, someone who has earlier deposited
+    ///        into that Vault), `balanceOwner` is the Vault, and `redemeer` is
+    ///        the address for which the vault is redeeming its balance to,
+    ///        - walletPubKeyHash: The 20-byte wallet public key hash (computed
+    ///        using Bitcoin HASH160 over the compressed ECDSA public key),
+    ///        - mainUtxoTxHash: Data of the wallet's main UTXO TX hash, as
+    ///        currently known on the Ethereum chain,
+    ///        - mainUtxoTxOutputIndex: Data of the wallet's main UTXO output
+    ///        index, as currently known on Ethereum chain,
+    ///        - mainUtxoTxOutputValue: Data of the wallet's main UTXO output
+    ///        value, as currently known on Ethereum chain,
+    ///        - redeemerOutputScript The redeemer's length-prefixed output
+    ///        script (P2PKH, P2WPKH, P2SH or P2WSH) that will be used to lock
+    ///        redeemed BTC.
+    /// @dev Requirements:
+    ///      - Wallet behind `walletPubKeyHash` must be live,
+    ///      - `mainUtxo*` components must point to the recent main UTXO
+    ///        of the given wallet, as currently known on the Ethereum chain,
+    ///      - `redeemerOutputScript` must be a proper Bitcoin script,
+    ///      - `redeemerOutputScript` cannot have wallet PKH as payload,
+    ///      - `amount` must be above or equal the `redemptionDustThreshold`,
+    ///      - Given `walletPubKeyHash` and `redeemerOutputScript` pair can be
+    ///        used for only one pending request at the same time,
+    ///      - Wallet must have enough Bitcoin balance to proceed the request,
+    ///      - Balance owner must make an allowance in the Bank that the Bridge
+    ///        contract can spend the given `amount`.
+    function requestRedemption(
+        BridgeState.Storage storage self,
+        address balanceOwner,
+        uint64 amount,
+        bytes calldata redemptionData
+    ) external {
+        (
+            address redeemer,
+            bytes20 walletPubKeyHash,
+            bytes32 mainUtxoTxHash,
+            uint32 mainUtxoTxOutputIndex,
+            uint64 mainUtxoTxOutputValue,
+            bytes memory redeemerOutputScript
+        ) = abi.decode(
+                redemptionData,
+                (address, bytes20, bytes32, uint32, uint64, bytes)
+            );
+
+        requestRedemption(
+            self,
+            walletPubKeyHash,
+            BitcoinTx.UTXO(
+                mainUtxoTxHash,
+                mainUtxoTxOutputIndex,
+                mainUtxoTxOutputValue
+            ),
+            balanceOwner,
+            redeemer,
+            redeemerOutputScript,
+            amount
+        );
+    }
+
+    /// @notice Requests redemption of the given amount from the specified
+    ///         wallet to the redeemer Bitcoin output script.
+    /// @param walletPubKeyHash The 20-byte wallet public key hash (computed
+    ///        using Bitcoin HASH160 over the compressed ECDSA public key).
+    /// @param mainUtxo Data of the wallet's main UTXO, as currently known on
+    ///        the Ethereum chain.
+    /// @param balanceOwner The address of the Bank balance owner whose balance
+    ///        is getting redeemed.
+    /// @param redeemer The Ethereum address of the redeemer who will be able to
+    ///        claim Bank balance if anything goes wrong during the redemption.
+    ///        In the most basic case, when someone redeems their Bitcoin
+    ///        balance from the Bank, `balanceOwner` is the same as `redemeer`.
+    ///        However, when a Vault is redeeming part of its balance for some
+    ///        redeemer address (for example, someone who has earlier deposited
+    ///        into that Vault), `balanceOwner` is the Vault, and `redemeer` is
+    ///        the address for which the vault is redeeming its balance to.
+    /// @param redeemerOutputScript The redeemer's length-prefixed output
+    ///        script (P2PKH, P2WPKH, P2SH or P2WSH) that will be used to lock
+    ///        redeemed BTC.
+    /// @param amount Requested amount in satoshi. This is also the Bank balance
+    ///        that is taken from the `balanceOwner` upon request.
+    ///        Once the request is handled, the actual amount of BTC locked
+    ///        on the redeemer output script will be always lower than this value
+    ///        since the treasury and Bitcoin transaction fees must be incurred.
+    ///        The minimal amount satisfying the request can be computed as:
+    ///        `amount - (amount / redemptionTreasuryFeeDivisor) - redemptionTxMaxFee`.
+    ///        Fees values are taken at the moment of request creation.
+    /// @dev Requirements:
+    ///      - Wallet behind `walletPubKeyHash` must be live,
+    ///      - `mainUtxo` components must point to the recent main UTXO
+    ///        of the given wallet, as currently known on the Ethereum chain,
+    ///      - `redeemerOutputScript` must be a proper Bitcoin script,
+    ///      - `redeemerOutputScript` cannot have wallet PKH as payload,
+    ///      - `amount` must be above or equal the `redemptionDustThreshold`,
+    ///      - Given `walletPubKeyHash` and `redeemerOutputScript` pair can be
+    ///        used for only one pending request at the same time,
+    ///      - Wallet must have enough Bitcoin balance to proceed the request,
+    ///      - Balance owner must make an allowance in the Bank that the Bridge
+    ///        contract can spend the given `amount`.
+    function requestRedemption(
+        BridgeState.Storage storage self,
+        bytes20 walletPubKeyHash,
+        BitcoinTx.UTXO memory mainUtxo,
+        address balanceOwner,
+        address redeemer,
+        bytes memory redeemerOutputScript,
+        uint64 amount
+    ) internal {
         Wallets.Wallet storage wallet = self.registeredWallets[
             walletPubKeyHash
         ];
@@ -358,7 +512,7 @@ library Redemption {
         );
 
         self.pendingRedemptions[redemptionKey] = RedemptionRequest(
-            msg.sender,
+            redeemer,
             amount,
             treasuryFee,
             txMaxFee,
@@ -369,13 +523,13 @@ library Redemption {
         emit RedemptionRequested(
             walletPubKeyHash,
             redeemerOutputScript,
-            msg.sender,
+            redeemer,
             amount,
             treasuryFee,
             txMaxFee
         );
 
-        self.bank.transferBalanceFrom(msg.sender, address(this), amount);
+        self.bank.transferBalanceFrom(balanceOwner, address(this), amount);
     }
 
     /// @notice Used by the wallet to prove the BTC redemption transaction

package/contracts/vault/TBTCVault.sol

@@ -25,7 +25,7 @@ import "../token/TBTC.sol";
 /// @notice TBTC is a fully Bitcoin-backed ERC-20 token pegged to the price of
 ///         Bitcoin. It facilitates Bitcoin holders to act on the Ethereum
 ///         blockchain and access the decentralized finance (DeFi) ecosystem.
-///         TBTC Vault mints and redeems TBTC based on Bitcoin balances in the
+///         TBTC Vault mints and unmints TBTC based on Bitcoin balances in the
 ///         Bank.
 /// @dev TBTC Vault is the owner of TBTC token contract and is the only contract
 ///      minting the token.
@@ -35,7 +35,7 @@ contract TBTCVault is IVault, Governable {
 
     event Minted(address indexed to, uint256 amount);
 
-    event Redeemed(address indexed from, uint256 amount);
+    event Unminted(address indexed from, uint256 amount);
 
     modifier onlyBank() {
         require(msg.sender == address(bank), "Caller is not the Bank");
@@ -140,18 +140,18 @@ contract TBTCVault is IVault, Governable {
     ///         `amount` back to the caller's balance in the Bank.
     /// @dev Caller must have at least `amount` of TBTC approved to
     ///       TBTC Vault.
-    /// @param amount Amount of TBTC to redeem.
-    function redeem(uint256 amount) external {
-        _redeem(msg.sender, amount);
+    /// @param amount Amount of TBTC to unmint.
+    function unmint(uint256 amount) external {
+        _unmint(msg.sender, amount);
     }
 
     /// @notice Burns `amount` of TBTC from the caller's account and transfers
     ///         `amount` back to the caller's balance in the Bank.
-    /// @dev This function is doing the same as `redeem` but it allows to
-    ///      execute redemption without an additional approval transaction.
+    /// @dev This function is doing the same as `unmint` but it allows to
+    ///      execute unminting without an additional approval transaction.
     ///      The function can be called only via `approveAndCall` of TBTC token.
-    /// @param from TBTC token holder executing redemption.
-    /// @param amount Amount of TBTC to redeem.
+    /// @param from TBTC token holder executing unminting.
+    /// @param amount Amount of TBTC to unmint.
     /// @param token TBTC token address.
     function receiveApproval(
         address from,
@@ -161,7 +161,7 @@ contract TBTCVault is IVault, Governable {
     ) external {
         require(token == address(tbtcToken), "Token is not TBTC");
         require(msg.sender == token, "Only TBTC caller allowed");
-        _redeem(from, amount);
+        _unmint(from, amount);
     }
 
     // slither-disable-next-line calls-loop
@@ -170,9 +170,9 @@ contract TBTCVault is IVault, Governable {
         tbtcToken.mint(minter, amount);
     }
 
-    function _redeem(address redeemer, uint256 amount) internal {
-        emit Redeemed(redeemer, amount);
-        tbtcToken.burnFrom(redeemer, amount);
-        bank.transferBalance(redeemer, amount);
+    function _unmint(address unminter, uint256 amount) internal {
+        emit Unminted(unminter, amount);
+        tbtcToken.burnFrom(unminter, amount);
+        bank.transferBalance(unminter, amount);
     }
 }

package/export.json

@@ -13523,12 +13523,12 @@
             },
             {
               "internalType": "address[]",
-              "name": "depositors",
+              "name": "recipients",
               "type": "address[]"
             },
             {
               "internalType": "uint256[]",
-              "name": "depositedAmounts",
+              "name": "amounts",
               "type": "uint256[]"
             }
           ],
@@ -15515,6 +15515,28 @@
           ],
           "outputs": []
         },
+        {
+          "type": "function",
+          "name": "receiveBalanceApproval",
+          "constant": false,
+          "payable": false,
+          "gas": 29000000,
+          "inputs": [
+            {
+              "type": "address",
+              "name": "balanceOwner"
+            },
+            {
+              "type": "uint256",
+              "name": "amount"
+            },
+            {
+              "type": "bytes",
+              "name": "redemptionData"
+            }
+          ],
+          "outputs": []
+        },
         {
           "type": "function",
           "name": "redemptionParameters",
@@ -16858,7 +16880,7 @@
               "type": "uint256"
             }
           ],
-          "name": "Redeemed",
+          "name": "Unminted",
           "type": "event"
         },
         {
@@ -17020,19 +17042,6 @@
           "stateMutability": "nonpayable",
           "type": "function"
         },
-        {
-          "inputs": [
-            {
-              "internalType": "uint256",
-              "name": "amount",
-              "type": "uint256"
-            }
-          ],
-          "name": "redeem",
-          "outputs": [],
-          "stateMutability": "nonpayable",
-          "type": "function"
-        },
         {
           "inputs": [],
           "name": "tbtcToken",
@@ -17058,6 +17067,19 @@
           "outputs": [],
           "stateMutability": "nonpayable",
           "type": "function"
+        },
+        {
+          "inputs": [
+            {
+              "internalType": "uint256",
+              "name": "amount",
+              "type": "uint256"
+            }
+          ],
+          "name": "unmint",
+          "outputs": [],
+          "stateMutability": "nonpayable",
+          "type": "function"
         }
       ]
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@keep-network/tbtc-v2",
-  "version": "0.1.1-dev.80+main.46e9cb6936fa4c5b474bd52fadb61ad74b908b14",
+  "version": "0.1.1-dev.83+main.c3c80fb5df859b160f905226f2c6fb7e3296b9ac",
   "license": "MIT",
   "files": [
     "artifacts/",