@keep-network/tbtc-v2 0.1.0 → 0.1.1-dev.3

package/contracts/bank/Bank.sol

@@ -0,0 +1,339 @@
+// SPDX-License-Identifier: MIT
+
+// ██████████████     ▐████▌     ██████████████
+// ██████████████     ▐████▌     ██████████████
+//               ▐████▌    ▐████▌
+//               ▐████▌    ▐████▌
+// ██████████████     ▐████▌     ██████████████
+// ██████████████     ▐████▌     ██████████████
+//               ▐████▌    ▐████▌
+//               ▐████▌    ▐████▌
+//               ▐████▌    ▐████▌
+//               ▐████▌    ▐████▌
+//               ▐████▌    ▐████▌
+//               ▐████▌    ▐████▌
+pragma solidity 0.8.4;
+
+import "@openzeppelin/contracts/access/Ownable.sol";
+
+/// @title Bitcoin Bank
+/// @notice Bank is a central component tracking Bitcoin balances. Balances can
+///         be transferred between holders and holders can approve their
+///         balances to be spent by others. Balances in the Bank are updated for
+///         depositors who deposit their Bitcoin into the Bridge and only the
+///         Bridge can increase balances.
+/// @dev Bank is a governable contract and the Governance can upgrade the Bridge
+///      address.
+contract Bank is Ownable {
+    address public bridge;
+
+    /// @notice The balance of a given account in the Bank. Zero by default.
+    mapping(address => uint256) public balanceOf;
+
+    /// @notice The remaining amount of balance a spender will be
+    ///         allowed to transfer on behalf of an owner using
+    ///         `transferBalanceFrom`. Zero by default.
+    mapping(address => mapping(address => uint256)) public allowance;
+
+    /// @notice Returns the current nonce for EIP2612 permission for the
+    ///         provided balance owner for a replay protection. Used to
+    ///         construct EIP2612 signature provided to `permit` function.
+    mapping(address => uint256) public nonce;
+
+    uint256 public immutable cachedChainId;
+    bytes32 public immutable cachedDomainSeparator;
+
+    /// @notice Returns EIP2612 Permit message hash. Used to construct EIP2612
+    ///         signature provided to `permit` function.
+    bytes32 public constant PERMIT_TYPEHASH =
+        keccak256(
+            "Permit(address owner,address spender,uint256 value,uint256 nonce,uint256 deadline)"
+        );
+
+    event BalanceTransferred(
+        address indexed from,
+        address indexed to,
+        uint256 amount
+    );
+
+    event BalanceApproved(
+        address indexed owner,
+        address indexed spender,
+        uint256 amount
+    );
+
+    event BalanceIncreased(address indexed owner, uint256 amount);
+
+    event BalanceDecreased(address indexed owner, uint256 amount);
+
+    event BridgeUpdated(address newBridge);
+
+    modifier onlyBridge() {
+        require(msg.sender == address(bridge), "Caller is not the bridge");
+        _;
+    }
+
+    constructor() {
+        cachedChainId = block.chainid;
+        cachedDomainSeparator = buildDomainSeparator();
+    }
+
+    /// @notice Allows the Governance to upgrade the Bridge address.
+    /// @dev The function does not implement any governance delay and does not
+    ///      check the status of the Bridge. The Governance implementation needs
+    ///      to ensure all requirements for the upgrade are satisfied before
+    ///      executing this function.
+    function updateBridge(address _bridge) external onlyOwner {
+        require(_bridge != address(0), "Bridge address must not be 0x0");
+        bridge = _bridge;
+        emit BridgeUpdated(_bridge);
+    }
+
+    /// @notice Moves the given `amount` of balance from the caller to
+    ///         `recipient`.
+    /// @dev Requirements:
+    ///       - `recipient` cannot be the zero address,
+    ///       - the caller must have a balance of at least `amount`.
+    function transferBalance(address recipient, uint256 amount) external {
+        _transferBalance(msg.sender, recipient, amount);
+    }
+
+    /// @notice Sets `amount` as the allowance of `spender` over the caller's
+    ///         balance.
+    /// @dev If the `amount` is set to `type(uint256).max` then
+    ///      `transferBalanceFrom` will not reduce an allowance.
+    ///      Beware that changing an allowance with this function brings the
+    ///      risk that someone may use both the old and the new allowance by
+    ///      unfortunate transaction ordering. Please use
+    ///      `increaseBalanceAllowance` and `decreaseBalanceAllowance` to
+    ///      eliminate the risk.
+    function approveBalance(address spender, uint256 amount) external {
+        _approveBalance(msg.sender, spender, amount);
+    }
+
+    /// @notice Atomically increases the balance allowance granted to `spender`
+    ///         by the caller by the given `addedValue`.
+    function increaseBalanceAllowance(address spender, uint256 addedValue)
+        external
+    {
+        _approveBalance(
+            msg.sender,
+            spender,
+            allowance[msg.sender][spender] + addedValue
+        );
+    }
+
+    /// @notice Atomically decreases the balance allowance granted to `spender`
+    ///         by the caller by the given `subtractedValue`.
+    function decreaseBalanceAllowance(address spender, uint256 subtractedValue)
+        external
+    {
+        uint256 currentAllowance = allowance[msg.sender][spender];
+        require(
+            currentAllowance >= subtractedValue,
+            "Can not decrease balance allowance below zero"
+        );
+        unchecked {
+            _approveBalance(
+                msg.sender,
+                spender,
+                currentAllowance - subtractedValue
+            );
+        }
+    }
+
+    /// @notice Moves `amount` of balance from `spender` to `recipient` using the
+    ///         allowance mechanism. `amount` is then deducted from the caller's
+    ///         allowance unless the allowance was made for `type(uint256).max`.
+    /// @dev Requirements:
+    ///      - `recipient` cannot be the zero address,
+    ///      - `spender` must have a balance of at least `amount`,
+    ///      - the caller must have allowance for `spender`'s balance of at
+    ///        least `amount`.
+    function transferBalanceFrom(
+        address spender,
+        address recipient,
+        uint256 amount
+    ) external {
+        uint256 currentAllowance = allowance[spender][msg.sender];
+        if (currentAllowance != type(uint256).max) {
+            require(
+                currentAllowance >= amount,
+                "Transfer amount exceeds allowance"
+            );
+            unchecked {
+                _approveBalance(spender, msg.sender, currentAllowance - amount);
+            }
+        }
+        _transferBalance(spender, recipient, amount);
+    }
+
+    /// @notice EIP2612 approval made with secp256k1 signature.
+    ///         Users can authorize a transfer of their balance with a signature
+    ///         conforming EIP712 standard, rather than an on-chain transaction
+    ///         from their address. Anyone can submit this signature on the
+    ///         user's behalf by calling the permit function, paying gas fees,
+    ///         and possibly performing other actions in the same transaction.
+    /// @dev The deadline argument can be set to `type(uint256).max to create
+    ///      permits that effectively never expire.  If the `amount` is set
+    ///      to `type(uint256).max` then `transferBalanceFrom` will not
+    ///      reduce an allowance. Beware that changing an allowance with this
+    ///      function brings the risk that someone may use both the old and the
+    ///      new allowance by unfortunate transaction ordering. Please use
+    ///      `increaseBalanceAllowance` and `decreaseBalanceAllowance` to
+    ///      eliminate the risk.
+    function permit(
+        address owner,
+        address spender,
+        uint256 amount,
+        uint256 deadline,
+        uint8 v,
+        bytes32 r,
+        bytes32 s
+    ) external {
+        /* solhint-disable-next-line not-rely-on-time */
+        require(deadline >= block.timestamp, "Permission expired");
+
+        // Validate `s` and `v` values for a malleability concern described in EIP2.
+        // Only signatures with `s` value in the lower half of the secp256k1
+        // curve's order and `v` value of 27 or 28 are considered valid.
+        require(
+            uint256(s) <=
+                0x7FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF5D576E7357A4501DDFE92F46681B20A0,
+            "Invalid signature 's' value"
+        );
+        require(v == 27 || v == 28, "Invalid signature 'v' value");
+
+        bytes32 digest =
+            keccak256(
+                abi.encodePacked(
+                    "\x19\x01",
+                    DOMAIN_SEPARATOR(),
+                    keccak256(
+                        abi.encode(
+                            PERMIT_TYPEHASH,
+                            owner,
+                            spender,
+                            amount,
+                            nonce[owner]++,
+                            deadline
+                        )
+                    )
+                )
+            );
+        address recoveredAddress = ecrecover(digest, v, r, s);
+        require(
+            recoveredAddress != address(0) && recoveredAddress == owner,
+            "Invalid signature"
+        );
+        _approveBalance(owner, spender, amount);
+    }
+
+    /// @notice Increases balances of the provided `recipients` by the provided
+    ///         `amounts`. Can only be called by the Bridge.
+    /// @dev This function fails if the lengths of the arrays are not the same.
+    function increaseBalances(
+        address[] calldata recipients,
+        uint256[] calldata amounts
+    ) external onlyBridge {
+        require(
+            recipients.length == amounts.length,
+            "Arrays must have the same length"
+        );
+        for (uint256 i = 0; i < recipients.length; i++) {
+            _increaseBalance(recipients[i], amounts[i]);
+        }
+    }
+
+    /// @notice Increases balance of the provided `recipient` by the provided
+    ///         `amount`. Can only be called by the Bridge.
+    function increaseBalance(address recipient, uint256 amount)
+        external
+        onlyBridge
+    {
+        _increaseBalance(recipient, amount);
+    }
+
+    /// @notice Decreases caller's balance by the provided `amount`. There is no
+    ///         way to restore the balance so do not call this function unless
+    ///         you really know what you are doing!
+    function decreaseBalance(uint256 amount) external {
+        balanceOf[msg.sender] -= amount;
+        emit BalanceDecreased(msg.sender, amount);
+    }
+
+    /// @notice Returns hash of EIP712 Domain struct with `TBTC Bank` as
+    ///         a signing domain and Bank contract as a verifying contract.
+    ///         Used to construct EIP2612 signature provided to `permit`
+    ///         function.
+    /* solhint-disable-next-line func-name-mixedcase */
+    function DOMAIN_SEPARATOR() public view returns (bytes32) {
+        // As explained in EIP-2612, if the DOMAIN_SEPARATOR contains the
+        // chainId and is defined at contract deployment instead of
+        // reconstructed for every signature, there is a risk of possible replay
+        // attacks between chains in the event of a future chain split.
+        // To address this issue, we check the cached chain ID against the
+        // current one and in case they are different, we build domain separator
+        // from scratch.
+        if (block.chainid == cachedChainId) {
+            return cachedDomainSeparator;
+        } else {
+            return buildDomainSeparator();
+        }
+    }
+
+    function _increaseBalance(address recipient, uint256 amount) internal {
+        require(
+            recipient != address(this),
+            "Can not increase balance for Bank"
+        );
+        balanceOf[recipient] += amount;
+        emit BalanceIncreased(recipient, amount);
+    }
+
+    function _transferBalance(
+        address spender,
+        address recipient,
+        uint256 amount
+    ) private {
+        require(
+            recipient != address(0),
+            "Can not transfer to the zero address"
+        );
+        require(
+            recipient != address(this),
+            "Can not transfer to the Bank address"
+        );
+
+        uint256 spenderBalance = balanceOf[spender];
+        require(spenderBalance >= amount, "Transfer amount exceeds balance");
+        unchecked {balanceOf[spender] = spenderBalance - amount;}
+        balanceOf[recipient] += amount;
+        emit BalanceTransferred(spender, recipient, amount);
+    }
+
+    function _approveBalance(
+        address owner,
+        address spender,
+        uint256 amount
+    ) private {
+        require(spender != address(0), "Can not approve to the zero address");
+        allowance[owner][spender] = amount;
+        emit BalanceApproved(owner, spender, amount);
+    }
+
+    function buildDomainSeparator() private view returns (bytes32) {
+        return
+            keccak256(
+                abi.encode(
+                    keccak256(
+                        "EIP712Domain(string name,string version,uint256 chainId,address verifyingContract)"
+                    ),
+                    keccak256(bytes("TBTC Bank")),
+                    keccak256(bytes("1")),
+                    block.chainid,
+                    address(this)
+                )
+            );
+    }
+}

package/contracts/bridge/Bridge.sol

@@ -0,0 +1,161 @@
+pragma solidity 0.8.4;
+
+/// @title BTC Bridge
+/// @notice Bridge manages BTC deposit and redemption and is increasing and
+///         decreasing balances in the Bank as a result of BTC deposit and
+///         redemption operations.
+///
+///         Depositors send BTC funds to the most-recently-created-wallet of the
+///         bridge using pay-to-script-hash (P2SH) which contains hashed
+///         information about the depositor’s minting Ethereum address. Then,
+///         the depositor reveals their desired Ethereum minting address to the
+///         Ethereum chain. The Bridge listens for these sorts of messages and
+///         when it gets one, it checks the Bitcoin network to make sure the
+///         funds line up. If they do, the off-chain wallet may decide to pick
+///         this transaction for sweeping, and when the sweep operation is
+///         confirmed on the Bitcoin network, the wallet informs the Bridge
+///         about the sweep increasing appropriate balances in the Bank.
+/// @dev Bridge is an upgradeable component of the Bank.
+contract Bridge {
+    struct DepositInfo {
+        uint64 amount;
+        address vault;
+        uint32 revealedAt;
+    }
+
+    /// @notice Collection of all unswept deposits indexed by
+    ///         keccak256(fundingTxHash | fundingOutputIndex | depositorAddress).
+    ///         This mapping may contain valid and invalid deposits and the
+    ///         wallet is responsible for validating them before attempting to
+    ///         execute a sweep.
+    mapping(uint256 => DepositInfo) public unswept;
+
+    event DepositRevealed(
+        uint256 depositId,
+        bytes32 fundingTxHash,
+        uint8 fundingOutputIndex,
+        address depositor,
+        uint64 blindingFactor,
+        bytes refundPubKey,
+        uint64 amount,
+        address vault
+    );
+
+    /// @notice Used by the depositor to reveal information about their P2SH
+    ///         Bitcoin deposit to the Bridge on Ethereum chain. The off-chain
+    ///         wallet listens for revealed deposit events and may decide to
+    ///         include the revealed deposit in the next executed sweep.
+    ///         Information about the Bitcoin deposit can be revealed before or
+    ///         after the Bitcoin transaction with P2SH deposit is mined on the
+    ///         Bitcoin chain.
+    /// @param fundingTxHash The BTC transaction hash containing BTC P2SH
+    ///        deposit funding transaction
+    /// @param fundingOutputIndex The index of the transaction output in the
+    ///        funding TX with P2SH deposit, max 256
+    /// @param blindingFactor The blinding factor used in the BTC P2SH deposit,
+    ///        max 2^64
+    /// @param refundPubKey The refund pub key used in the BTC P2SH deposit
+    /// @param amount The amount locked in the BTC P2SH deposit
+    /// @param vault Bank vault to which the swept deposit should be routed
+    /// @dev Requirements:
+    ///      - `msg.sender` must be the Ethereum address used in the P2SH BTC deposit,
+    ///      - `blindingFactor` must be the blinding factor used in the P2SH BTC deposit,
+    ///      - `refundPubKey` must be the refund pub key used in the P2SH BTC deposit,
+    ///      - `amount` must be the same as locked in the P2SH BTC deposit,
+    ///      - BTC deposit for the given `fundingTxHash`, `fundingOutputIndex`
+    ///        can be revealed by `msg.sender` only one time.
+    ///
+    ///      If any of these requirements is not met, the wallet _must_ refuse
+    ///      to sweep the deposit and the depositor has to wait until the
+    ///      deposit script unlocks to receive their BTC back.
+    function revealDeposit(
+        bytes32 fundingTxHash,
+        uint8 fundingOutputIndex,
+        uint64 blindingFactor,
+        bytes calldata refundPubKey,
+        uint64 amount,
+        address vault
+    ) external {
+        uint256 depositId =
+            uint256(
+                keccak256(
+                    abi.encode(fundingTxHash, fundingOutputIndex, msg.sender)
+                )
+            );
+
+        DepositInfo storage deposit = unswept[depositId];
+        require(deposit.revealedAt == 0, "Deposit already revealed");
+
+        deposit.amount = amount;
+        deposit.vault = vault;
+        /* solhint-disable-next-line not-rely-on-time */
+        deposit.revealedAt = uint32(block.timestamp);
+
+        emit DepositRevealed(
+            depositId,
+            fundingTxHash,
+            fundingOutputIndex,
+            msg.sender,
+            blindingFactor,
+            refundPubKey,
+            amount,
+            vault
+        );
+    }
+
+    /// @notice Used by the wallet to prove the BTC deposit sweep transaction
+    ///         and to update Bank balances accordingly. Sweep is only accepted
+    ///         if it satisfies SPV proof.
+    ///
+    ///         The function is performing Bank balance updates by first
+    ///         computing the Bitcoin fee for the sweep transaction. The fee is
+    ///         divided evenly between all swept deposits. Each depositor
+    ///         receives a balance in the bank equal to the amount they have
+    ///         declared during the reveal transaction, minus their fee share.
+    ///
+    ///         It is possible to prove the given sweep only one time.
+    /// @param txVersion Transaction version number (4-byte LE)
+    /// @param txInputVector All transaction inputs prepended by the number of
+    ///                      inputs encoded as a VarInt, max 0xFC(252) inputs
+    /// @param txOutput Single sweep transaction output
+    /// @param txLocktime Final 4 bytes of the transaction
+    /// @param merkleProof The merkle proof of transaction inclusion in a block
+    /// @param txIndexInBlock Transaction index in the block (0-indexed)
+    /// @param bitcoinHeaders Single bytestring of 80-byte bitcoin headers,
+    ///                       lowest height first
+    function sweep(
+        bytes4 txVersion,
+        bytes memory txInputVector,
+        bytes memory txOutput,
+        bytes4 txLocktime,
+        bytes memory merkleProof,
+        uint256 txIndexInBlock,
+        bytes memory bitcoinHeaders
+    ) external {
+        // TODO We need to read `fundingTxHash`, `fundingOutputIndex` and
+        //      P2SH script depositor address from `txInputVector`.
+        //      We then hash them to obtain deposit identifier and read
+        //      DepositInfo. From DepositInfo we know what amount was declared
+        //      by the depositor in their reveal transaction and we use that
+        //      amount to update their Bank balance, minus fee.
+        //
+        // TODO We need to validate if the sum in the output minus the
+        //      amount from the previous wallet balance input minus fees is
+        //      equal to the amount by which Bank balances were increased.
+        //
+        // TODO We need to validate txOutput to see if the balance was not
+        //      transferred away from the wallet before increasing balances in
+        //      the bank.
+        //
+        // TODO Delete deposit from unswept mapping or mark it as swept
+        //      depending on the gas costs. Alternativly, do not allow to
+        //      use the same TX input vector twice. Sweep should be provable
+        //      only one time.
+    }
+
+    // TODO It is possible a malicious wallet can sweep deposits that can not
+    //      be later proved on Ethereum. For example, a deposit with
+    //      an incorrect amount revealed. We need to provide a function for honest
+    //      depositors, next to sweep, to prove their swept balances on Ethereum
+    //      selectively, based on deposits they have earlier received.
+}

package/contracts/vault/TBTCVault.sol

@@ -0,0 +1,104 @@
+// SPDX-License-Identifier: MIT
+
+// ██████████████     ▐████▌     ██████████████
+// ██████████████     ▐████▌     ██████████████
+//               ▐████▌    ▐████▌
+//               ▐████▌    ▐████▌
+// ██████████████     ▐████▌     ██████████████
+// ██████████████     ▐████▌     ██████████████
+//               ▐████▌    ▐████▌
+//               ▐████▌    ▐████▌
+//               ▐████▌    ▐████▌
+//               ▐████▌    ▐████▌
+//               ▐████▌    ▐████▌
+//               ▐████▌    ▐████▌
+
+pragma solidity 0.8.4;
+
+import "../bank/Bank.sol";
+import "../token/TBTC.sol";
+
+/// @title TBTC application vault
+/// @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
+///         Bank.
+/// @dev TBTC Vault is the owner of TBTC token contract and is the only contract
+///      minting the token.
+contract TBTCVault {
+    Bank public bank;
+    TBTC public tbtcToken;
+
+    event Minted(address indexed to, uint256 amount);
+
+    event Redeemed(address indexed from, uint256 amount);
+
+    constructor(Bank _bank, TBTC _tbtcToken) {
+        require(
+            address(_bank) != address(0),
+            "Bank can not be the zero address"
+        );
+
+        require(
+            address(_tbtcToken) != address(0),
+            "TBTC token can not be the zero address"
+        );
+
+        bank = _bank;
+        tbtcToken = _tbtcToken;
+    }
+
+    /// @notice Transfers the given `amount` of the Bank balance from caller
+    ///         to TBTC Vault, and mints `amount` of TBTC to the caller.
+    /// @dev TBTC Vault must have an allowance for caller's balance in the Bank
+    ///      for at least `amount`.
+    /// @param amount Amount of TBTC to mint
+    function mint(uint256 amount) external {
+        _mint(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 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);
+    }
+
+    /// @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.
+    ///      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 token TBTC token address
+    function receiveApproval(
+        address from,
+        uint256 amount,
+        address token,
+        bytes calldata
+    ) external {
+        require(token == address(tbtcToken), "Token is not TBTC");
+        require(msg.sender == token, "Only TBTC caller allowed");
+        _redeem(from, amount);
+    }
+
+    function _mint(address minter, uint256 amount) internal {
+        require(
+            bank.balanceOf(minter) >= amount,
+            "Amount exceeds balance in the bank"
+        );
+        emit Minted(minter, amount);
+        bank.transferBalanceFrom(minter, address(this), amount);
+        tbtcToken.mint(minter, amount);
+    }
+
+    function _redeem(address redeemer, uint256 amount) internal {
+        emit Redeemed(redeemer, amount);
+        tbtcToken.burnFrom(redeemer, amount);
+        bank.transferBalance(redeemer, amount);
+    }
+}

package/deploy/00_resolve_tbtc_v1_token.ts

@@ -13,7 +13,7 @@ const func: DeployFunction = async function (hre: HardhatRuntimeEnvironment) {
   } else if (hre.network.name !== "hardhat") {
     throw new Error("deployed TBTCToken contract not found")
   } else {
-    log(`deploying TBTCToken stub`)
+    log("deploying TBTCToken stub")
 
     await deployments.deploy("TBTCToken", {
       contract: "TestERC20",

package/deploy/01_deploy_tbtc_v2_token.ts

@@ -6,10 +6,17 @@ const func: DeployFunction = async function (hre: HardhatRuntimeEnvironment) {
   const { deploy } = deployments
   const { deployer } = await getNamedAccounts()
 
-  await deploy("TBTC", {
+  const TBTC = await deploy("TBTC", {
     from: deployer,
     log: true,
   })
+
+  if (hre.network.tags.tenderly) {
+    await hre.tenderly.verify({
+      name: "TBTC",
+      address: TBTC.address,
+    })
+  }
 }
 
 export default func

package/deploy/02_deploy_vending_machine.ts

@@ -22,6 +22,13 @@ const func: DeployFunction = async function (hre: HardhatRuntimeEnvironment) {
     VendingMachine.address,
     deployer
   )
+
+  if (hre.network.tags.tenderly) {
+    await hre.tenderly.verify({
+      name: "VendingMachine",
+      address: VendingMachine.address,
+    })
+  }
 }
 
 export default func