release: v1.2.3

.github/workflows/build-test.yml

@@ -67,7 +67,7 @@ jobs:
         run: yarn test
 
   test-contracts:
-    name: Test storage layout and signatures
+    name: Test storage layout, signatures and look for unused errors
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v3
@@ -98,6 +98,12 @@ jobs:
       - name: Test function signatures
         run: yarn run test:signatures
 
+      - name: Run unused Solidity errors checker
+        uses: OffchainLabs/actions/check-unused-errors@main
+        with:
+          directory: './contracts'
+          exceptions_file: './test/unused-errors/exceptions.txt'
+
   test-e2e:
     name: Test e2e
     runs-on: ubuntu-latest
@@ -112,7 +118,6 @@ jobs:
           no-token-bridge: true
           no-l3-token-bridge: true
           token-bridge-branch: '${{ github.head_ref }}'
-          nitro-testnode-ref: node-18
 
       - name: Setup node/yarn
         uses: actions/setup-node@v3
@@ -136,6 +141,9 @@ jobs:
       - name: Verify creation code generation
         run: yarn test:creation-code
 
+      - name: Test e2e orbit token bridge actions
+        run: yarn hardhat test test-e2e/orbitTokenBridge.ts
+
   test-e2e-custom-fee-token:
     name: Test e2e on custom fee token chain
     runs-on: ubuntu-latest
@@ -151,7 +159,6 @@ jobs:
           no-token-bridge: true
           no-l3-token-bridge: true
           token-bridge-branch: '${{ github.head_ref }}'
-          nitro-testnode-ref: node-18
 
       - name: Setup node/yarn
         uses: actions/setup-node@v3
@@ -194,7 +201,6 @@ jobs:
           no-l3-token-bridge: true
           token-bridge-branch: '${{ github.head_ref }}'
           nitro-contracts-branch: 'develop'
-          nitro-testnode-ref: 'non18-decimal-token-node-18'
 
       - name: Setup node/yarn
         uses: actions/setup-node@v3

.gitignore

@@ -23,4 +23,7 @@ network.json
 
 # Gambit (mutation test) files
 gambit_out/
-test-mutation/mutant_test_env/
+test-mutation/mutant_test_env/
+
+# bridged usdc deployment script
+registerUsdcGatewayTx.json

contracts/tokenbridge/arbitrum/IArbToken.sol

@@ -19,6 +19,8 @@
 /**
  * @title Minimum expected interface for L2 token that interacts with the L2 token bridge (this is the interface necessary
  * for a custom token that interacts with the bridge, see TestArbCustomToken.sol for an example implementation).
+ * @dev For the token to be compatible out of the box with the tooling available (e.g., the Arbitrum bridge), it is
+ * recommended to keep the implementation of this interface as close as possible to the `TestArbCustomToken` example.
  */
 
 // solhint-disable-next-line compiler-version

contracts/tokenbridge/arbitrum/gateway/L2ArbitrumGateway.sol

@@ -137,7 +137,7 @@ abstract contract L2ArbitrumGateway is L2ArbitrumMessenger, TokenGateway {
         uint256, /* _maxGas */
         uint256, /* _gasPriceBid */
         bytes calldata _data
-    ) public payable override returns (bytes memory res) {
+    ) public payable virtual override returns (bytes memory res) {
         // This function is set as public and virtual so that subclasses can override
         // it and add custom validation for callers (ie only whitelisted users)
 
@@ -163,7 +163,7 @@ abstract contract L2ArbitrumGateway is L2ArbitrumMessenger, TokenGateway {
         {
             address l2Token = calculateL2TokenAddress(_l1Token);
             require(l2Token.isContract(), "TOKEN_NOT_DEPLOYED");
-            require(IArbToken(l2Token).l1Address() == _l1Token, "NOT_EXPECTED_L1_TOKEN");
+            require(_isValidTokenAddress(_l1Token, l2Token), "NOT_EXPECTED_L1_TOKEN");
 
             _amount = outboundEscrowTransfer(l2Token, _from, _amount);
             id = triggerWithdrawal(_l1Token, _from, _to, _amount, _extraData);
@@ -252,33 +252,14 @@ abstract contract L2ArbitrumGateway is L2ArbitrumMessenger, TokenGateway {
             );
             if (shouldHalt) return;
         }
-        // ignores gatewayData if token already deployed
 
-        {
-            // validate if L1 address supplied matches that of the expected L2 address
-            (bool success, bytes memory _l1AddressData) = expectedAddress.staticcall(
-                abi.encodeWithSelector(IArbToken.l1Address.selector)
-            );
-
-            bool shouldWithdraw;
-            if (!success || _l1AddressData.length < 32) {
-                shouldWithdraw = true;
-            } else {
-                // we do this in the else branch since we want to avoid reverts
-                // and `toAddress` reverts if _l1AddressData has a short length
-                // `_l1AddressData` should be 12 bytes of padding then 20 bytes for the address
-                address expectedL1Address = BytesLib.toAddress(_l1AddressData, 12);
-                if (expectedL1Address != _token) {
-                    shouldWithdraw = true;
-                }
-            }
-
-            if (shouldWithdraw) {
-                // we don't need the return value from triggerWithdrawal since this is forcing
-                // a withdrawal back to the L1 instead of composing with a L2 dapp
-                triggerWithdrawal(_token, address(this), _from, _amount, "");
-                return;
-            }
+        // validate if L1 address supplied matches that of the expected L2 address
+        bool shouldWithdraw = !_isValidTokenAddress(_token, expectedAddress);
+        if (shouldWithdraw) {
+            // we don't need the return value from triggerWithdrawal since this is forcing
+            // a withdrawal back to the L1 instead of composing with a L2 dapp
+            triggerWithdrawal(_token, address(this), _from, _amount, "");
+            return;
         }
 
         inboundEscrowTransfer(expectedAddress, _to, _amount);
@@ -296,4 +277,34 @@ abstract contract L2ArbitrumGateway is L2ArbitrumMessenger, TokenGateway {
         uint256 _amount,
         bytes memory gatewayData
     ) internal virtual returns (bool shouldHalt);
-}
+
+    /**
+     * @notice Check if expected token address matches the provided one
+     * @param _l1Address provided address of L1 token
+     * @param _expectedL2Address address of L2 gateway expects
+     * @return true if addresses match, false otherwise
+     */
+    function _isValidTokenAddress(address _l1Address, address _expectedL2Address)
+        internal
+        view
+        virtual
+        returns (bool)
+    {
+        (bool success, bytes memory _l1AddressData) =
+            _expectedL2Address.staticcall(abi.encodeWithSelector(IArbToken.l1Address.selector));
+
+        if (!success || _l1AddressData.length < 32) {
+            return false;
+        } else {
+            // we do this in the else branch since we want to avoid reverts
+            // and `toAddress` reverts if _l1AddressData has a short length
+            // `_l1AddressData` should be 12 bytes of padding then 20 bytes for the address
+            address expectedL1Address = BytesLib.toAddress(_l1AddressData, 12);
+            if (expectedL1Address != _l1Address) {
+                return false;
+            }
+        }
+
+        return true;
+    }
+}

contracts/tokenbridge/arbitrum/gateway/L2USDCGateway.sol

@@ -0,0 +1,216 @@
+// SPDX-License-Identifier: Apache-2.0
+pragma solidity ^0.8.4;
+
+import "./L2ArbitrumGateway.sol";
+import {IFiatToken, IFiatTokenProxy} from "../../ethereum/gateway/L1USDCGateway.sol";
+import "@openzeppelin/contracts/token/ERC20/utils/SafeERC20.sol";
+
+/**
+ * @title  Child chain custom gateway for USDC implementing Bridged USDC Standard.
+ * @notice Reference to the Circle's Bridged USDC Standard:
+ *         https://github.com/circlefin/stablecoin-evm/blob/master/doc/bridged_USDC_standard.md
+ *
+ * @dev    This contract can be used on new Orbit chains which want to provide USDC
+ *         bridging solution and keep the possibility to upgrade to native USDC at
+ *         some point later. This solution will NOT be used in existing Arbitrum chains.
+ *
+ *         Parent chain custom gateway to be used along this child chain custom gateway is
+ *         L1USDCGateway (when eth is used to pay fees) or L1OrbitUSDCGateway (when custom fee token is used).
+ *         This custom gateway differs from standard gateway in the following ways:
+ *         - it supports a single parent chain - child chain USDC token pair
+ *         - it is ownable
+ *         - withdrawals can be paused by the owner
+ *         - owner can set an "transferrer" account which will be able to transfer USDC ownership
+ *         - transferrer can transfer USDC owner and proxyAdmin
+ *
+ *         NOTE: before withdrawing funds, make sure that recipient address is not blacklisted on the parent chain.
+ *               Also, make sure that USDC token itself is not paused. Otherwise funds might get stuck.
+ */
+contract L2USDCGateway is L2ArbitrumGateway {
+    using SafeERC20 for IERC20;
+    using Address for address;
+
+    address public l1USDC;
+    address public l2USDC;
+    address public owner;
+    address public usdcOwnershipTransferrer;
+    bool public withdrawalsPaused;
+
+    event WithdrawalsPaused();
+    event WithdrawalsUnpaused();
+    event OwnerSet(address indexed owner);
+    event USDCOwnershipTransferrerSet(address indexed usdcOwnershipTransferrer);
+    event USDCOwnershipTransferred(address indexed newOwner, address indexed newProxyAdmin);
+
+    error L2USDCGateway_WithdrawalsAlreadyPaused();
+    error L2USDCGateway_WithdrawalsAlreadyUnpaused();
+    error L2USDCGateway_WithdrawalsPaused();
+    error L2USDCGateway_InvalidL1USDC();
+    error L2USDCGateway_InvalidL2USDC();
+    error L2USDCGateway_NotOwner();
+    error L2USDCGateway_InvalidOwner();
+    error L2USDCGateway_NotUSDCOwnershipTransferrer();
+
+    modifier onlyOwner() {
+        if (msg.sender != owner) {
+            revert L2USDCGateway_NotOwner();
+        }
+        _;
+    }
+
+    function initialize(
+        address _l1Counterpart,
+        address _router,
+        address _l1USDC,
+        address _l2USDC,
+        address _owner
+    ) public {
+        if (_l1USDC == address(0)) {
+            revert L2USDCGateway_InvalidL1USDC();
+        }
+        if (_l2USDC == address(0)) {
+            revert L2USDCGateway_InvalidL2USDC();
+        }
+        if (_owner == address(0)) {
+            revert L2USDCGateway_InvalidOwner();
+        }
+        L2ArbitrumGateway._initialize(_l1Counterpart, _router);
+        l1USDC = _l1USDC;
+        l2USDC = _l2USDC;
+        owner = _owner;
+    }
+
+    /**
+     * @notice Pause all withdrawals. This can only be called by the owner.
+     */
+    function pauseWithdrawals() external onlyOwner {
+        if (withdrawalsPaused) {
+            revert L2USDCGateway_WithdrawalsAlreadyPaused();
+        }
+        withdrawalsPaused = true;
+        emit WithdrawalsPaused();
+    }
+
+    /**
+     * @notice Unpause withdrawals. This can only be called by the owner.
+     */
+    function unpauseWithdrawals() external onlyOwner {
+        if (!withdrawalsPaused) {
+            revert L2USDCGateway_WithdrawalsAlreadyUnpaused();
+        }
+        withdrawalsPaused = false;
+        emit WithdrawalsUnpaused();
+    }
+
+    /**
+     * @notice Sets a new owner.
+     */
+    function setOwner(address newOwner) external onlyOwner {
+        if (newOwner == address(0)) {
+            revert L2USDCGateway_InvalidOwner();
+        }
+        owner = newOwner;
+        emit OwnerSet(newOwner);
+    }
+
+    /**
+     * @notice Sets the account which is able to transfer USDC role away from the gateway to some other account.
+     */
+    function setUsdcOwnershipTransferrer(address _usdcOwnershipTransferrer) external onlyOwner {
+        usdcOwnershipTransferrer = _usdcOwnershipTransferrer;
+        emit USDCOwnershipTransferrerSet(_usdcOwnershipTransferrer);
+    }
+
+    /**
+     * @notice In accordance with bridged USDC standard, the ownership of the USDC token contract is transferred
+     *         to the new owner, and the proxy admin is transferred to the caller (usdcOwnershipTransferrer).
+     * @dev    For transfer to be successful, this gateway should be both the owner and the proxy admin of L2 USDC token.
+     */
+    function transferUSDCRoles(address _owner) external {
+        if (msg.sender != usdcOwnershipTransferrer) {
+            revert L2USDCGateway_NotUSDCOwnershipTransferrer();
+        }
+
+        IFiatTokenProxy(l2USDC).changeAdmin(msg.sender);
+        IFiatToken(l2USDC).transferOwnership(_owner);
+
+        emit USDCOwnershipTransferred(_owner, msg.sender);
+    }
+
+    /**
+     * @notice Entrypoint for withdrawing USDC, can be used only if withdrawals are not paused.
+     */
+    function outboundTransfer(
+        address _l1Token,
+        address _to,
+        uint256 _amount,
+        uint256, /* _maxGas */
+        uint256, /* _gasPriceBid */
+        bytes calldata _data
+    ) public payable override returns (bytes memory res) {
+        if (withdrawalsPaused) {
+            revert L2USDCGateway_WithdrawalsPaused();
+        }
+        return super.outboundTransfer(_l1Token, _to, _amount, 0, 0, _data);
+    }
+
+    /**
+     * @notice Only parent chain - child chain USDC token pair is supported
+     */
+    function calculateL2TokenAddress(address l1ERC20) public view override returns (address) {
+        if (l1ERC20 != l1USDC) {
+            // invalid L1 usdc address
+            return address(0);
+        }
+        return l2USDC;
+    }
+
+    function inboundEscrowTransfer(address _l2Address, address _dest, uint256 _amount)
+        internal
+        override
+    {
+        IFiatToken(_l2Address).mint(_dest, _amount);
+    }
+
+    function outboundEscrowTransfer(address _l2Token, address _from, uint256 _amount)
+        internal
+        override
+        returns (uint256)
+    {
+        // fetch the USDC tokens from the user and then burn them
+        IERC20(_l2Token).safeTransferFrom(_from, address(this), _amount);
+        IFiatToken(_l2Token).burn(_amount);
+
+        return _amount;
+    }
+
+    /**
+     * @notice Withdraw back the USDC if child chain side is not set up properly
+     */
+    function handleNoContract(
+        address l1ERC20,
+        address, /* expectedL2Address */
+        address _from,
+        address, /* _to */
+        uint256 _amount,
+        bytes memory /* deployData */
+    ) internal override returns (bool shouldHalt) {
+        // it is assumed that the custom token is deployed to child chain before deposits are made
+        triggerWithdrawal(l1ERC20, address(this), _from, _amount, "");
+        return true;
+    }
+
+    /**
+     * @notice We need to override this function because base implementation assumes that L2 token implements
+     *         `l1Address()` function from IArbToken interface. In the case of USDC gateway IArbToken logic is
+     *         part of this contract, so we just check that addresses match the expected L1 and L2 USDC address.
+     */
+    function _isValidTokenAddress(address _l1Address, address _expectedL2Address)
+        internal
+        view
+        override
+        returns (bool)
+    {
+        return _l1Address == l1USDC && _expectedL2Address == l2USDC;
+    }
+}