Skip to content

Latest commit

 

History

History
239 lines (166 loc) · 11.4 KB

README.md

File metadata and controls

239 lines (166 loc) · 11.4 KB
Raw

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 the following addresses:

  • Mainnet: 0x7dB8637A5fd20BbDab1176BdF49C943A96F2E9c6
  • Sepolia: 0x82c6c4940cE0066B9F8b500aBF8535810524890c

❗ L1OpUSDCBridgeAdapter.sol has been deployed to the following addresses:

  • Sepolia: 0x0429b5441c85EF7932B694f1998B778D89375b12

❗ L2OpUSDCBridgeAdapter.sol has been deployed to the following addresses:

  • Optimism Sepolia: 0xCe7bb486F2b17735a2ee7566Fe03cA77b1a1aa9d

❗ Bridged USDC contract has been deployed to the following addresses:

  • Optimism Sepolia: 0x7a30534619d60e4A610833F985bdF7892fD9bcD5

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

image

L1 → L2 USDC Canonical Bridging

image

For a user to make a deposit, the process is the following:

Deposits

  1. Users approve the L1OpUSDCBridgeAdapter to spend USDC.
  2. Users proceed to deposit USDC by calling the contract.
  3. The L1OpUSDCBridgeAdapter sends the message to the appointed CrossDomainMessenger.
  4. The message is digested and included by the sequencer.
  5. The L1OpUSDCBridgeAdapter mints the specified amount of bridgedUSDC to the user.

Similarly, for withdrawals:

Withdrawals

  1. Users send bridgedUSDC to the L2OpUSDCBridgeAdapter.
  2. The L2OpUSDCBridgeAdapter burns the token.
  3. The L2OpUSDCBridgeAdapter sends the message to the appointed CrossDomainMessenger.
  4. The message is eventually included and proven on L1.
  5. Wait for the challenge period (at least 7 days).
  6. The receiving user (or relayers) withdraws the message after the challenge period, which is then forwarded to the L1OpUSDCBridgeAdapter that releases the specified amount of USDC to the user.

You can test the bridging flows using Brid.gg in Sepolia.

Migrating from Bridged USDC to Native USDC

image

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 protocol 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=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
PRIVATE_KEY=
# Ethereum RPC URL
ETHEREUM_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

In addittion, the L1OpUSDCFactory deployment command is:

yarn deploy:mainnet:factory

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

yarn deploy:mainnet:factory:broadcast

Alternatively, you can run the deployment scripts over your desired testent by replacing mainnet with testnet in the commands above.

Tips For Verifying

  • Remember to set the EVM version to paris when verifying the contracts.

  • Remember to add the --via-ir version if you compiled the contracts with the optimized flag and you're verifying them through the CLI.

  • If you are verifying manually through a block explorer UI, you can choose a single Soldiity file option and use forge flatten <contract_name> > <flattened_contract_name> to get the flattened contract and avoid having to upload multiple Solidity files.

  • If you're facing issues with the L1OpUSDCFactory verification, you can resolve them by adding the CrossChainDeployments library address to the L1OpUSDCFactory.json file as shown below:

        "libraries": {
      "src/libraries/CrossChainDeployments.sol": {
          "CrossChainDeployments":"<CROSS_CHAIN_DEPLOYMENTS_ADDRESS>"
      }

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
L1_ADAPTER_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.