Bridged USDC Standard for the OP Stack

USDC is one of the most bridged assets across the crypto ecosystem, and USDC is often bridged to new chains prior to any action from Circle. This can create a challenge when bridged USDC achieves substantial marketshare, but native USDC (issued by Circle) is preferred by the ecosystem, leading to fragmentation between multiple representations of USDC. Circle introduced the Bridged USDC Standard to ensure that chains can easily deploy a form of USDC that is capable of being upgraded in-place by Circle to native USDC, if and when appropriate, and prevent the fragmentation problem.

Bridged USDC Standard for the OP Stack allows for an efficient and modular solution for expanding the Bridged USDC Standard across the Superchain ecosystem.

Chain operators can use the Bridged USDC Standard for the OP Stack to get bridged USDC on their OP Stack chain while also providing the optionality for Circle to seamlessly upgrade bridged USDC to native USDC and retain existing supply, holders, and app integrations.

Contracts

❗ L1OpUSDCFactory.sol has been deployed to 0x7dB8637A5fd20BbDab1176BdF49C943A96F2E9c6.

L1OpUSDCFactory.sol - Factory contract to deploy and setup the L1OpUSDCBridgeAdapter contract on L1. Precalculates the addresses of the L2 deployments and triggers their deployment, by sending a transaction to L2.

L2OpUSDCDeploy.sol - One time use deployer contract deployed from the L1 factory through a cross-chain deployment. Used as a utility contract for deploying the L2 USDC Proxy, and L2OpUSDCBridgeAdapter contract, all at once in its constructor.

L1OpUSDCBridgeAdapter - Contract that allows for the transfer of USDC from Ethereum Mainnet to a specific OP Stack chain. Locks USDC on Ethereum Mainnet and sends a message to the other chain to mint the equivalent amount of USDC. Receives messages from the other chain and unlocks USDC on the Ethereum Mainnet. Controls the message flow between layers. Supports the requirements for the Bridged USDC to be migrated to Native USDC should the chain operator and Circle want to.

L2OpUSDCBridgeAdapter - Contract that allows for the transfer of USDC from the specific OP Stack chain to Ethereum Mainnet. Burns USDC on the L2 and sends a message to Ethereum Mainnet to unlock the equivalent amount of USDC. Receives messages from Ethereum Mainnet and mints USDC. Allows chain operator to execute arbitrary functions on the Bridged USDC contract as if they were the owner of the contract.

L1 → L2 Deployment

L1 → L2 USDC Canonical Bridging

Migrating from Bridged USDC to Native USDC

Security

The referenced implementation for the OP Stack has undergone audits from Spearbit and is recommended for production use. The audit report is available here.

Setup

1. Install Foundry by following the instructions from their repository.
2. Copy the .env.example file to .env and fill in the variables.
3. Install the dependencies by running: yarn install. If there is an error with the commands, run foundryup and try them again.

Build

The default way to build the code is suboptimal but fast, you can run it via:

yarn build

In order to build a more optimized code (via IR), run:

yarn build:optimized

Running tests

Unit tests should be isolated from any externalities, while Integration tests usually run in a blockchain fork. In this boilerplate, you will find examples of both.

In order to run both unit and integration tests, run:

yarn test

In order to just run unit tests, run:

yarn test:unit

In order to run unit tests and run way more fuzzing than usual (5x), run:

yarn test:unit:deep

In order to just run integration tests, run:

yarn test:integration

In order to check your current code coverage, run:

yarn coverage

Deploying

❗ BRIDGED_USDC_IMPLEMENTATION needs to be deployed ahead of time onto the target L2 chain.

In order to deploy the opUSDC procotol for your OP Stack chain, you will need to fill out these variables in the .env file:

# The factory contract address on L1
L1_FACTORY_MAINNET=0x7dB8637A5fd20BbDab1176BdF49C943A96F2E9c6
# The bridged USDC implementation address on L2
BRIDGED_USDC_IMPLEMENTATION=
# The address of your CrossDomainMessenger on L1
L1_MESSENGER=
# The name of your chain
CHAIN_NAME=
# The private key that will sign the transactions on L1
MAINNET_PK=
# Ethereum RPC URL
MAINNET_RPC=

After all these variables are set, navigate to the script/mainnet/Deploy.s.sol file and edit the following lines with your desired configuration, we add a sanity check that will revert if you forget to change this value:

    // NOTE: We have these hardcoded to default values, if used in product you will need to change them

    bytes[] memory _usdcInitTxs = new bytes[](3);
    string memory _name = string.concat('Bridged USDC', ' ', '(', chainName, ')');
    
    _usdcInitTxs[0] = abi.encodeCall(IUSDC.initializeV2, (_name));
    _usdcInitTxs[1] = USDCInitTxs.INITIALIZEV2_1;
    _usdcInitTxs[2] = USDCInitTxs.INITIALIZEV2_2;

    // Sanity check to ensure the caller of this script changed this value to the proper naming
    assert(keccak256(_usdcInitTxs[0]) != keccak256(USDCInitTxs.INITIALIZEV2));

Then run this command to test:

yarn script:deploy

And when you are ready to deploy to mainnet, run:

yarn script:deploy:broadcast

Migrating to Native USDC

⚠️ Migrating to native USDC is a manual process that requires communication with Circle, this section assumes both parties are ready to migrate to native USDC. Please review Circle’s documentation to learn about the process around Circle obtaining ownership of the Bridged USDC Standard token contract.

In order to migrate to native USDC, you will need to fill out these variables in the .env file:

# The address of the L1 opUSDC bridge adapter
L1_ADAPTER=
# The private key of the transaction signer, should be the owner of the L1 Adapter
MAINNET_OWNER_PK=
# The address of the role caller, should be provided by circle
ROLE_CALLER=
# The address of the burn caller, should be provided by circle
BURN_CALLER

After all these variables are set, run this command to test:

yarn script:migrate

And when you are ready to migrate to native USDC, run:

yarn script:migrate:broadcast

What will Circle need at migration?

Circle will need the metadata from the original deployment of the USDC implementation that was used

To do this you will need to go back to the stablecoin-evm github repo that the implementation was deployed from in order to extract the raw metadata from the compiled files. The compiled files are usually found in the out/ or artifacts/ folders. To extract the raw metadata you can run a command like this:

cat out/example.sol/example.json | jq -jr '.rawMetadata' > example.metadata.json

You will need to do this for both the token contract and any external libraries that get deployed with it, at the time of writing this these are FiatTokenV2_2 and SignatureChecker but these are subject to change in the future.

Licensing

The primary license for the boilerplate is MIT, see LICENSE

Bridged USDC Standard Factory Disclaimer

This software is provided “as is,” without warranty of any kind, express or implied, including but not limited to the warranties of merchantability, fitness for a particular purpose, and noninfringement. In no event shall the authors or copyright holders be liable for any claim, damages, or other liability, whether in an action of contract, tort, or otherwise, arising from, out of, or in connection with the software or the use or other dealings in the software.

Please review Circle’s disclaimer for the limitations around Circle obtaining ownership of the Bridged USDC Standard token contract.