This project contains the implementations of the L2 ERC20 token bridges for Arbitrum and Optimism chains. The current solution allows transferring ERC20 tokens between L1 and L2 chains.
To retrieve more detailed info about the bridging process, see the specifications for certain chains:
- Clone the repo:
git clone [email protected]:lidofinance/lido-l2.git
cd ./lido-l2
- Install dependencies:
npm install
- Compile the contracts:
npm run compile
The simplest way to create .env
file is via cloning the .env.example
file:
cp .env.example .env
Fill the newly created .env
file with the required variables. See the Project Configuration section for the complete list of configuration options.
The configuration of the deployment scripts happens via the ENV variables. The following variables are required:
TOKEN
- address of the token to deploy a new bridge on the Ethereum chain.NETWORK
- name of the network environments used by deployment scripts. Allowed values:mainnet
,goerli
.FORKING
- run deployment in the forking network instead of real onesETH_DEPLOYER_PRIVATE_KEY
- The private key of the deployer account in the Ethereum network is used during the deployment process.ARB_DEPLOYER_PRIVATE_KEY
- The private key of the deployer account in the Arbitrum network is used during the deployment process.OPT_DEPLOYER_PRIVATE_KEY
- The private key of the deployer account in the Optimism network is used during the deployment process.L1_PROXY_ADMIN
- The address to grant admin rights of theOssifiableProxy
on the L1 bridgeL1_BRIDGE_ADMIN
- Address to grant theDEFAULT_ADMIN_ROLE
on the L1 bridgeL2_PROXY_ADMIN
- The address to grant admin rights of theOssifiableProxy
on the L2 bridgeL2_BRIDGE_ADMIN
- Address to grant theDEFAULT_ADMIN_ROLE
on the L2 bridge
The following ENV variables are optional and might be used to make an additional setup of the bridge after the deployment:
L1_DEPOSITS_ENABLED
- whether the deposits are enabled on the L1 after the deployment. By default, deposits are disabled.L1_WITHDRAWALS_ENABLED
- whether the withdrawals are enabled on the L1 after the deployment. By default, withdrawals are disabled.L1_DEPOSITS_ENABLERS
- array of addresses to grantDEPOSITS_ENABLER_ROLE
on the L1 bridge.L1_DEPOSITS_DISABLERS
- array of addresses to grantDEPOSITS_DISABLER_ROLE
on the L1 bridge.L1_WITHDRAWALS_ENABLERS
- array of addresses to grantWITHDRAWALS_ENABLER_ROLE
on the L1 bridge.L1_WITHDRAWALS_DISABLERS
- array of addresses to grantWITHDRAWALS_DISABLER_ROLE
on the L1 bridge.L2_DEPOSITS_ENABLED
- whether the deposits are enabled on the L2 after the deployment. By default, deposits are disabled.L2_WITHDRAWALS_ENABLED
- whether the withdrawals are enabled on the L2 after the deployment. By default, deposits are disabled.L2_DEPOSITS_ENABLERS
- array of addresses to grantDEPOSITS_ENABLER_ROLE
on the L2 bridge.L2_DEPOSITS_DISABLERS
- array of addresses to grantDEPOSITS_DISABLER_ROLE
on the L2 bridge.L2_WITHDRAWALS_ENABLERS
- array of addresses to grantWITHDRAWALS_ENABLER_ROLE
on the L2 bridge.L2_WITHDRAWALS_DISABLERS
- array of addresses to grantWITHDRAWALS_DISABLER_ROLE
on the L2 bridge.
To run the deployment of the ERC20 token gateway for the Ethereum <-> Arbitrum chains use the following command:
npm run arbitrum:deploy
To run the deployment of the ERC20 token gateway for the Ethereum <-> Optimism chains use the following command:
npm run optimism:deploy
To run unit tests use one of the following commands:
# Run tests for both Arbitrum and Optimism bridges
npm run test:unit
# Run tests only for Arbitrum gateway
npm run arbitrum:test:unit
# Run tests only for Optimism bridge
npm run optimism:test:unit
Before running integration tests, run the hardhat forked nodes in the standalone tabs corresponding to TESTING_ARB_NETWORK
\ TESTING_OPT_NETWORK
env variable or if it's not set use mainnet
network. Example of the commands for the mainnet
network:
# Required to run both Arbitrum and Optimism integraton tests
npm run fork:eth:mainnet
# Required to run Optimism integration tests
npm run fork:opt:mainnet
# Required to run Arbitrum integration tests
npm run fork:arb:mainnet
The integration tests might be run via the following commands:
# Run integration tests for both Arbitrum and Optimism bridges
npm run test:integration
# Run integration tests for Arbitrum bridge
npm run arbitrum:test:integration
# Run integration tests for Optimism bridge
npm run optimism:test:integration
Additionally, tests might be run on the deployed contracts. To do it, set the following variables values in the .env
file:
# Activates testing on already deployed contracts
TESTING_USE_DEPLOYED_CONTRACTS=true
# Address of the account which has tokens to test
TESTING_L1_TOKENS_HOLDER=
# Addresses of the Arbitrum gateway
TESTING_ARB_NETWORK=
TESTING_ARB_L1_TOKEN=
TESTING_ARB_L2_TOKEN=
TESTING_ARB_L1_ERC20_TOKEN_GATEWAY=
TESTING_ARB_L2_ERC20_TOKEN_GATEWAY=
# Below addresses are not required when the gateway uses the default Arbitrum router
TESTING_ARB_L1_GATEWAY_ROUTER=
TESTING_ARB_L2_GATEWAY_ROUTER=
# Addresses of the Optimism bridge
TESTING_OPT_NETWORK=
TESTING_OPT_L1_TOKEN=
TESTING_OPT_L2_TOKEN=
TESTING_OPT_L1_ERC20_TOKEN_BRIDGE=
TESTING_OPT_L2_ERC20_TOKEN_BRIDGE=
E2E tests run on the real contracts deployed on the testnet networks. To run such tests next env variables must be set in the .env
file.
TESTING_PRIVATE_KEY
TESTING_OPT_LDO_HOLDER_PRIVATE_KEY
TESTING_ARB_LDO_HOLDER_PRIVATE_KEY
To run E2E tests use the following commands:
# Run E2E tests for both Arbitrum and Optimism bridges
npm run test:e2e
# Run E2E tests for Arbitrum bridge
npm run arbitrum:test:e2e
# Run E2E tests for Optimism bridge
npm run optimism:test:e2e
Additionally, tests might be run on the deployed contracts. To do it, set the following variables values in the .env
file:
# private key of the tester. It must have tokens for testing
TESTING_PRIVATE_KEY=
# Addresses of the Arbitrum gateway
TESTING_ARB_NETWORK=
TESTING_ARB_L1_TOKEN=
TESTING_ARB_L2_TOKEN=
TESTING_ARB_L1_ERC20_TOKEN_GATEWAY=
TESTING_ARB_L2_ERC20_TOKEN_GATEWAY=
# Below addresses are not required when the gateway uses the default Arbitrum router
TESTING_ARB_L1_GATEWAY_ROUTER=
TESTING_ARB_L2_GATEWAY_ROUTER=
# Addresses of the Optimism bridge
TESTING_OPT_NETWORK=
TESTING_OPT_L1_TOKEN=
TESTING_OPT_L2_TOKEN=
TESTING_OPT_L1_ERC20_TOKEN_BRIDGE=
TESTING_OPT_L2_ERC20_TOKEN_BRIDGE=
The acceptance tests might be run after the deployment to validate that the bridge was deployed with the correct parameters.
The following ENV variables must be set before the tests running:
# Addresses of the Arbitrum gateway
TESTING_ARB_L1_TOKEN=
TESTING_ARB_L2_TOKEN=
TESTING_ARB_L1_ERC20_TOKEN_GATEWAY=
TESTING_ARB_L2_ERC20_TOKEN_GATEWAY=
# Below addresses are not required when the gateway uses the default Arbitrum router
TESTING_ARB_L1_GATEWAY_ROUTER=
TESTING_ARB_L2_GATEWAY_ROUTER=
# Addresses of the Optimism bridge
TESTING_OPT_L1_TOKEN=
TESTING_OPT_L2_TOKEN=
TESTING_OPT_L1_ERC20_TOKEN_BRIDGE=
TESTING_OPT_L2_ERC20_TOKEN_BRIDGE=
To run the acceptance tests, use the following commands:
# Optimism bridge
npm run optimism:test:acceptance
# Arbitrum bridge
npm run arbitrum:test:acceptance
To run coverage measurement for unit tests:
npm run coverage
The configuration of the project happens via set of ENV variables. The full list of the configured properties might be split in the following groups:
Address of the RPC node for Mainnet Ethereum network.
Address of the RPC node for Goerli Ethereum network.
Warning
Please, don't use the default value for production deployments! The default RPC node might not be available or fail suddenly during the request.
Address of the RPC node for Mainnet Arbitrum network.
Default value:
https://arb1.arbitrum.io/rpc
Address of the RPC node for Goerli Arbitrum network.
Default value:
https://goerli-rollup.arbitrum.io/rpc
Address of the RPC node for Goerli Optimism network.
Default value:
https://goerli-rollup.arbitrum.io/rpc
Warning
Please, don't use the default value for production deployments! The default RPC node might not be available or fail suddenly during the request.
Address of the RPC node for Mainnet Optimism network.
Default value:
https://mainnet.optimism.io
Below variables are required for successfull verification of the contracts on block explorer for certain networks.
API key from the Etherscan block explorer. See details here: https://info.etherscan.com/api-keys/
API key from the Arbiscan block explorer.
API key from the Optimistic Ethereum block explorer.
Below variables used in the Arbitrum/Optimism bridge deployment process.
Address of the token to deploy a new bridge on the Ethereum chain.
Default value:
mainnet
Name of the network environments used by deployment scripts. Might be one of: mainnet
, goerli
.
Run deployment in the forking network instead of public ones
Default value:
true
The private key of the deployer account in the Ethereum network is used during the deployment process.
The private key of the deployer account in the Arbitrum network is used during the deployment process.
The private key of the deployer account in the Optimism network is used during the deployment process.
The address assigned as admin of the OssifiableProxy
contract for L1ERC20Bridge
/ L1ERC20Gateway
.
The address granted the DEFAULT_ADMIN_ROLE
for L1ERC20Bridge
/ L1ERC20Gateway
.
Default value:
false
Whether the deposits enabled on the L1 after the deployment
Default value:
false
Whether the deposits enabled on the L1 after the deployment
Default value:
[]
The array of addresses to grant DEPOSITS_ENABLER_ROLE
on L1 bridge/gateway. The value must be in the form of JSON array of strings. For example:
["0x00000000219ab540356cbb839cbe05303d7705fa","0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2"]
Default value:
[]
The array of addresses to grant DEPOSITS_DISABLER_ROLE
on L1 bridge/gateway. The value must be in the form of JSON array of strings. For example:
["0x00000000219ab540356cbb839cbe05303d7705fa","0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2"]
Default value:
[]
The array of addresses to grant WITHDRAWALS_ENABLER_ROLE
on L1 bridge/gateway. The value must be in the form of JSON array of strings. For example:
["0x00000000219ab540356cbb839cbe05303d7705fa","0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2"]
Default value:
[]
The array of addresses to grant WITHDRAWALS_DISABLER_ROLE
. The value must be in the form of JSON array of strings. For example:
["0x00000000219ab540356cbb839cbe05303d7705fa","0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2"]
The address assigned as admin of the OssifiableProxy
contract for L2ERC20Bridge
/ L2ERC20Gateway
and ERC20Bridged.
The address granted the DEFAULT_ADMIN_ROLE
for L2ERC20Bridge
/ L2ERC20Gateway
.
Default value:
false
Whether the deposits enabled on the L2 after the deployment
Default value:
false
Whether the deposits enabled on the L2 after the deployment
Default value:
[]
The array of addresses to grant DEPOSITS_ENABLER_ROLE
on L2 bridge/gateway. The value must be in the form of JSON array of strings. For example:
["0x00000000219ab540356cbb839cbe05303d7705fa","0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2"]
Default value:
[]
The array of addresses to grant DEPOSITS_DISABLER_ROLE
on L2 bridge/gateway. The value must be in the form of JSON array of strings. For example:
["0x00000000219ab540356cbb839cbe05303d7705fa","0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2"]
Default value:
[]
The array of addresses to grant WITHDRAWALS_ENABLER_ROLE
on L2 bridge/gateway. The value must be in the form of JSON array of strings. For example:
["0x00000000219ab540356cbb839cbe05303d7705fa","0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2"]
Default value:
[]
The array of addresses to grant WITHDRAWALS_DISABLER_ROLE
on L2 bridge/gateway. The value must be in the form of JSON array of strings. For example:
["0x00000000219ab540356cbb839cbe05303d7705fa","0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2"]
The following variables are used in the process of the Integration & E2E testing.
Name of the network environments used for Arbitrum Integration & E2E testing. Might be one of: mainnet
, goerli
.
Address of the token to use in the Acceptance Integration & E2E (when TESTING_USE_DEPLOYED_CONTRACTS
is set to true) testing of the bridging between Ethereum and Arbitrum networks.
Default value:
0x7AEE39c46f20135114e85A03C02aB4FE73fB8127
Address of the token minted on L2 in the Acceptance Integration & E2E (when TESTING_USE_DEPLOYED_CONTRACTS
is set to true) testing of the bridging between Ethereum and Arbitrum networks.
Default value:
0x775ede8029C117effce283b3391E420EacF3c85F
Address of the L1 ERC20 token gateway used in the Acceptance Integration & E2E (when TESTING_USE_DEPLOYED_CONTRACTS
is set to true) testing of the bridging between Ethereum and Arbitrum networks.
Default value:
0x0A7e12b563Ba623646a31a09F0182e8aD45D6cfD
Address of the L2 ERC20 token gateway used in the Acceptance Integration & E2E (when TESTING_USE_DEPLOYED_CONTRACTS
is set to true) testing of the bridging between Ethereum and Arbitrum networks.
Default value:
0x8c269989D839eE9DaEe64D57C8c41404DF87F722
Address of the L1 gateway router used in the Acceptance Integration & E2E (when TESTING_USE_DEPLOYED_CONTRACTS
is set to true) testing of the bridging between Ethereum and Arbitrum networks. If not set, will be used default Arbitrum's L1 Gateway Router
Default value:
0xa2a8F940752aDc4A3278B63B96d56D72D2b075B1
Address of the L2 gateway router used in the Acceptance Integration & E2E (when TESTING_USE_DEPLOYED_CONTRACTS
is set to true) testing of the bridging between Ethereum and Arbitrum networks. If not set, will be used default Arbitrum's L2 Gateway Router
Default value:
0x57f54f87C44d816f60b92864e23b8c0897D4d81D
Name of the network environments used for Optimism Integration & E2E testing. Might be one of: mainnet
, goerli
.
Address of the token to use in the Acceptance Integration & E2E (when TESTING_USE_DEPLOYED_CONTRACTS
is set to true) testing of the bridging between Ethereum and Optimism networks.
Default value:
0xaF8a2F0aE374b03376155BF745A3421Dac711C12
Address of the token minted on L2 in the Acceptance Integration & E2E (when TESTING_USE_DEPLOYED_CONTRACTS
is set to true) testing of the bridging between Ethereum and Optimism networks.
Default value:
0xAED5F9aaF167923D34174b8E636aaF040A11f6F7
Address of the L1 ERC20 token bridge used in the Acceptance Integration & E2E (when TESTING_USE_DEPLOYED_CONTRACTS
is set to true) testing of the bridging between Ethereum and Optimism networks.
Default value:
0x243b661276670bD17399C488E7287ea4D416115b
Address of the L2 ERC20 token bridge used in the Acceptance Integration & E2E (when TESTING_USE_DEPLOYED_CONTRACTS
is set to true) testing of the bridging between Ethereum and Optimism networks.
Default value:
0x447CD1794d209Ac4E6B4097B34658bc00C4d0a51
When set to true
integration tests will use addresses of deployed contracts set in corresponding variables in the .env
file. In other cases, bridges will be deployed on fork nodes from scratch.
When TESTING_USE_DEPLOYED_CONTRACTS
is set to true, this address will be used as the holder of the tokens, bridged between L1 and L2.
Address of the deployed Governance Bridge Executor in the Arbitrum network. If set, this contract will be used for integration tests of Governance Bridge.
Address of the deployed Governance Bridge Executor in the Optimism network. If set, this contract will be used for integration tests of Governance Bridge.
The private key from the address which holds:
- Goerli and Arbitrum/Optimistic Goerli Ether to launch Arbitrum/Optimism E2E tests
The test Ether might be retrived via Paradigm Faucet.
The private key from the address which holds 50+% TLDO
The private key from the address which holds 50+% TLDO