Bridge
Overview
In the earlier sections, we provided some basic guides and tutorials with a setup involving:
- an L2 chain (i.e., the AltLayer network, or a deployed flash layer) acting as the execution layer,
- an L1 chain (e.g., Ethereum) acting as the settlement layer, and
- a rollup mechanism that allows state settlement on the L1 chain
This rolling up process is made possible through a bridge setup between contracts on the L1 and L2 chains. Such contracts include handlers and standard or AltLayer's token (and native) contracts.
info
AltLayer's bridge is based on the ChainBridge solution. For more information, please refer to their documentation website.
This section provides developers with more details on the common deployment configurations provided by AltLayer, namely:
- Native tokens (such as Ether)
- ERC20 tokens (for existing deployed contracts and using AltLayer's custom contracts)
- ERC721 tokens (for existing deployed contracts and using AltLayer's custom contracts)
Native
A native token is a token that is native to an L1 chain and not part of a smart contract. It lacks the standard interfaces present in token standards such as ERC20.
On L1, the contract address 0x0000000000000000000000000000000000000001 will be used to represent native ETH.
On L2, an ERC20 token contract will be deployed to represent ETH on the L2.
Currently, we only support the ETH native token. We will progressively support more chains and more native tokens.
Deployment and Configuration
The following steps are performed to deploy the ERC20 contract on L2 and configure the bridge for it.
| Operation | Actor |
|---|---|
Deploy ERC20Preset.sol on L2. This token will have the function required for rollup to L1. | Smart Contract Developer |
| Add 3 resource IDs on L1: - Resource ID #1: NativeTokenHandler map to a pre-defined address 0x0000000000000000000000000000000000000001- Resource ID #2: RollupHandler map to a pre-defined address 0x0000000000000000000000000000000000000001- Resource ID #3: RollupHandler map to NativeTokenHandler (for release of native token) | Bridge Contract Admin |
| Add 3 resource IDs on L2: - Resource ID #1: NativeTokenHandler map to the deployed ERC20Preset address- Resource ID #2: RollupHandler map to the deployed ERC20Preset address- Resource ID #3: RollupHandler map to NativeTokenHandler | Bridge Contract Admin |
Call grantRole function in the ERC20 contract on L2 to grant minter role to ERC20RollupHandler. This gives the handler on L2 the ability to mint an equivalent amount of tokens on L2. | Smart Contract Developer |
Call adminSetBurnable function in the bridge contract on L2 to set burner to both ERC20RollupHandler and RollupHandler. This gives the handlers the ability to burn the bridged ERC20 tokens on L2 before bridging/rolling up to L1. | Bridge Contract Admin |
Bridging to L2
To bridge the native tokens to L2, the token holder will need to call the deposit function on the bridge contract on L1.
| Parameter | Value |
|---|---|
| destinationDomainID | L2 Domain ID (e.g., 99) |
| resourceID | Resource ID #1 |
| data | DataHexString of tuple(uint256 amount, uint256 len_dest_addr, uint256 dest_addr) |
This contract call will transfer the native tokens to the NativeTokenHandler on L1. It will then lock up the native token and emit a Deposit event which the relayer will listen to. The relayer will then proceed to create and vote on the proposal. Once passed, the ERC20RollupHandler on L2 will mint out an equivalent amount of bridged ERC20 tokens on L2.
Bridging Back to L1
To transfer the native tokens back to L1, there are two options:
- Token holder manually bridges them back to L1
- ERC20 contract owner initiates the rollup process, burning tokens of all EOA and releasing the tokens to respective EOA on L1
Option 1: Bridging ERC20 tokens to L1
To bridge the tokens from L2 to L1, the token holder will need to call the deposit function on the bridge contract on L2.
| Parameter | Value |
|---|---|
| destinationDomainID | L1 Domain ID (e.g., 4) |
| resourceID | Resource ID #1 |
| data | DataHexString of tuple(uint256 amount, uint256 len_dest_addr, uint256 dest_addr) |
This contract call will transfer the ERC20 tokens to the ERC20RollupHandler on L2. The handler will then burn the tokens and emit a Deposit event, which the relayer will listen to. The relayer will then proceed to create and vote on the proposal. Once passed, the NativeTokenHandler on L1 will release an equivalent amount of native tokens to the token holders.
Option 2: Rolling Up to L1
To rollup all bridged tokens from EOA on L2, the rollup admin will need to call the rollup function on the ERC20 token contract on L2.
| Parameter | Value |
|---|---|
| targetDomainID | L1 Domain ID (e.g., 4) |
| resourceID | Resource ID #3 |
| batchSize | uint64 (e.g., 100) |
This contract call will transfer the ERC20 tokens to the RollupHandler on L2. The handler will then burn the tokens from the token holder and emit a ExecRollup event which the relayer will listen to. The relayer will then proceed to create and vote on the proposal. Once passed, the RollupHandler on L1 will call the NativeTokenHandler on L1 to release an equivalent amount of native tokens to all token holders involved in the rollup process.
ERC20
We support two different types of ERC20 tokens, namely:
- An existing deployed ERC20 standard contract (i.e., with no generic interface) on L1 (e.g., USDT)
- ERC20 contract with AltLayer's generic interface support
For the existing ERC20 contract, the rollup process can only transfer the token balance to the corresponding token holder. It will not be able to update any other arbitary contract state.
info
The generic interface is additional functionality specified by AltLayer that enables contracts to send state changes in batches from L2 to L1.
For the ERC20 contract with AltLayer's generic interface, it is possible to update any arbitary contract state as defined in the generic interface.
Type 1: Existing ERC20 Token on L1
A typical scenario will be that there is already an ERC20 token (e.g., USDT) already pre-deployed on L1, which the user wishes to bridge to L2.
Deployment and Configuration
The following steps are performed to deploy the ERC20 contract on L2 and configure the bridge for it.
| Operation | Actor |
|---|---|
Deploy ERC20Preset.sol on L2. This token will have the function required for rollup to L1. | Smart Contract Developer |
| Add 3 resource IDs on L1: - Resource ID #1: ERC20RollupHandler map to the existing ERC20 contract address on L1 - Resource ID #2: RollupHandler map to the existing ERC20 contract address on L1 - Resource ID #3: RollupHandler map to ERC20RollupHandler (for release of the existing ERC20 token) | Bridge Contract Admin |
| Add 3 resource IDs on L2: - Resource ID #1: ERC20RollupHandler map to the deployed ERC20Preset address- Resource ID #2: RollupHandler map to the deployed ERC20Preset address- Resource ID #3: RollupHandler map to ERC20RollupHandler | Bridge Contract Admin |
Call grantRole function on the ERC20 contract on L2 to grant minter role to ERC20RollupHandler. This contract call gives the ERC20RollupHandler the ability to mint an equivalent amount of ERC20 bridged tokens on L2. | Smart Contract Admin |
Call adminSetBurnable function on the Bridge contract on L2 to set burner to both ERC20RollupHandler and RollupHandler. This contract call gives the handlers the ability to burn the ERC20 token on L2 before rolling up to L1. Do note that this is a bridge admin operation. | Bridge Contract Admin |
Bridging to L2
To bridge an existing ERC20 token (with no generic interface) to L2, the token holder will need to:
- Ensure there is sufficient approval limit for the bridge to spend the token
- Call the
depositfunction on the bridge contract on L1
| Parameter | Value |
|---|---|
| destinationDomainID | L2 Domain ID (e.g., 99) |
| resourceID | Resource ID #1 |
| data | DataHexString of tuple(uint256 amount, uint256 len_dest_addr, uint256 dest_addr) |
This contract call will transfer the ERC20 tokens to the ERC20RollupHandler on L1. It will then lock up the ERC20 token and emit a Deposit event which the relayer will listen to. The relayer will then proceed to create and vote on the proposal. Once passed, the ERC20RollupHandler on L2 will mint out an equivalent amount of ERC20 bridged tokens on L2.
Bridging Back to L1
To transfer the ERC20 tokens back to L1, there are two options:
- Token holder manually bridges them back to L1
- ERC20 contract owner initiates the rollup process, burning tokens of all EOA and releasing the tokens to respective EOA on L1
Option 1: Bridging ERC20 tokens to L1
To bridge the tokens from L2 to L1, the token holder will need to call the deposit function on the bridge contract on L2.
| Parameter | Value |
|---|---|
| destinationDomainID | L1 Domain ID (e.g., 4) |
| resourceID | Resource ID #1 |
| data | DataHexString of tuple(uint256 amount, uint256 len_dest_addr, uint256 dest_addr) |
This contract call will transfer the ERC20 tokens to the ERC20RollupHandler on L2. The handler will then burn the tokens from the token holder and emit a Deposit event which the relayer will listen to. The relayer will then proceed to create and vote on the proposal. Once passed, the ERC20RollupHandler on L1 will release an equivalent amount of ERC20 tokens to the token holder.
Option 2: Rolling Up to L1
To rollup all tokens from EOA on L2, the rollup admin will need to call the rollup function on the ERC20 token contract on L2.
| Parameter | Value |
|---|---|
| targetDomainID | L1 Domain ID (e.g., 4) |
| resourceID | Resource ID #3 |
| batchSize | uint64 (e.g., 100) |
This contract call will transfer the ERC20 tokens to the RollupHandler on L2. The handler will then burn the tokens from the token holder and emit a ExecRollup event which the relayer will listen to. The relayer will then proceed to create and vote on the proposal. Once passed, the RollupHandler on L1 will call the ERC20RollupHandler on L1 to release an equivalent amount of ERC20 tokens to all token holders involved in the rollup process.
Type 2: New ERC20 Token with Generic Interface Support
For the case where no ERC20 contract has been deployed yet on L1, the developer can choose to deploy AltLayer's ERC20 token contract with generic interface support.
Deployment and Configuration
The following steps are performed to deploy the ERC20 contracts and configure the bridge for them.
| Operation | Actor |
|---|---|
Deploy ERC20Preset.sol on L1. This token will have the function required for receiving rollup settlement data from L2. | Smart Contract Developer |
Deploy ERC20Preset.sol on L2. This token will have the function required for rollup to L1. | Smart Contract Developer |
| Add 3 resource IDs on L1 - Resource ID #1: ERC20RollupHandler map to the deployed ERC20Preset contract address on L1- Resource ID #2: RollupHandler map to the deployed ERC20Preset contract address on L1 | Bridge Contract Admin |
| Add 3 resource IDs on L2 - Resource ID #1: ERC20RollupHandler map to the deployed ERC20Preset address on L2- Resource ID #2: RollupHandler map to the deployed ERC20Preset contract address on L2 | Bridge Contract Admin |
Call grantRole function on the ERC20 contract on L2 to grant minter role to ERC20RollupHandler. This contract call gives the ERC20RollupHandler the ability to mint an equivalent amount of ERC20 bridged tokens on L2. | Smart Contract Admin |
Call adminSetBurnable function on the bridge contract on L2 to set burner to both ERC20RollupHandler and RollupHandler. This contract call gives the handlers the ability to burn the ERC20 token on L2 before rolling up to L1. | Bridge Contract Admin |
Bridging to L2
To bridge the ERC20 token with the generic interface to L2, the token holder will need to:
- Ensure there is sufficient approval limit for the bridge to spend the token
- Call the
depositfunction on the bridge contract on L1
| Parameter | Value |
|---|---|
| destinationDomainID | L2 Domain ID (e.g., 99) |
| resourceID | Resource ID #1 |
| data | DataHexString of tuple(uint256 amount, uint256 len_dest_addr, uint256 dest_addr) |
This contract call will transfer the ERC20 tokens to the ERC20RollupHandler on L1. It will then lock up the ERC20 token and emit a Deposit event which the relayer will listen to. The relayer will then proceed to create and vote on the proposal. Once passed, the ERC20RollupHandler on L2 will mint an equivalent amount of ERC20 bridged tokens on L2.
Bridging Back to L1
To transfer the ERC20 tokens back to L1, there are two options:
- Token holder manually bridges them back to L1
- ERC20 contract owner initiates the rollup process, burning tokens of all EOA and releasing the tokens to respective EOA on L1
Option 1: Bridging ERC20 tokens to L1
To bridge the token from L2 to L1, the token holder will need to call the deposit function on the bridge contract on L2.
| Parameter | Value |
|---|---|
| destinationDomainID | L1 Domain ID (e.g., 4) |
| resourceID | Resource ID #1 |
| data | DataHexString of tuple(uint256 amount, uint256 len_dest_addr, uint256 dest_addr) |
This contract call will transfer the ERC20 tokens to the ERC20RollupHandler on L2. The handler will then burn the tokens from the token holder and emit a Deposit event which the relayer will listen to. The relayer will then proceed to create and vote on the proposal. Once passed, the ERC20RollupHandler on L1 will release an equivalent amount of ERC20 tokens to the token holder.
Option 2: Rolling Up to L1
To rollup all tokens from EOA on L2, the rollup admin will need to call the rollup function on the ERC20 token contract on L2.
| Parameter | Value |
|---|---|
| targetDomainID | L1 Domain ID (e.g., 4) |
| resourceID | Resource ID #2 |
| batchSize | uint64 (e.g., 100) |
This contract call will transfer the ERC20 tokens to the RollupHandler on L2. The handler will then burn the tokens from the token holder and emit a ExecRollup event which the relayer will listen to. The relayer will then proceed to create and vote on the proposal. Once passed, the RollupHandler on L1 will call the ERC20RollupHandler on L1 to release an equivalent amount of ERC20 tokens to all token holders involved in the rollup process.
ERC721
In the case of ERC721 tokens, we use AltLayer's ERC721 contract with generic interface support.
For NFT mints, we expect the project team will benefit the most from AltLayer during the minting phase. As such, the suggested process will be:
- Deploy the NFT contracts on L1 and L2
- Commence with minting on L2 (execution)
- Rollup contract states from L2 to L1 upon conclusion of minting (settlement)
- Disable future rollup on the NFT contract (once no further rollup is expected)
No regular bridging will be required in this process.
info
A hands-on demonstration on NFT minting using the process above is available in the tutorials section.
info
As the ERC721 contract has AltLayer's generic interface, it is possible to update any arbitary contract state as defined in the generic interface.
Deployment and Configuration
The following steps are performed to deploy the ERC721 contracts and configure the bridge for them.
| Operation | Actor |
|---|---|
Deploy ERC721PresetL1.sol on L1 | Smart Contract Developer |
Deploy ERC721PresetL2.sol on L2 | Smart Contract Developer |
| Add a resource ID on L1 that maps RollupHandler to the contract address of ERC721PresetL1 | Bridge Contract Admin |
| Add a resource ID on L2 that maps RollupHandler to the contract address of ERC721PresetL2 | Bridge Contract Admin |
Call the adminSetBurnable function on the bridge contract on L2 to set burner to RollupHandler. This enables RollupHandler to burn the ERC721 tokens on L2 before rolling up to L1. Do note that this is a bridge admin operation. | Bridge Contract Admin |
Rolling Up to L1
To rollup all NFT tokens from EOA on L2, the rollup admin will need to call the rollup function on the ERC721 token contract on L2.
| Parameter | Value |
|---|---|
| targetDomainID | L1 Domain ID (e.g., 4) |
| resourceID | Resource ID |
| batchSize | uint64 (e.g., 100) |
This contract call will transfer the ERC721 tokens to the RollupHandler on L2. The handler will then burn the tokens from the token holder and emit an ExecRollup event which the relayer will listen to. The relayer will then proceed to create and vote on the proposal. Once passed, the RollupHandler on L1 will call the ERC721 token contract on L1 to mint the same NFT on L1.
The contract developer can customize what kind of states they want to update on L1. They can do so via the generic interface.
info
It is possible to rollup multiple times.
The relayers submit transactions with a gas limit of 5,000,000 units of gas. It is recommended that the batch size be set conservatively, so as not to exceed the gas limit of the rollup transaction.
Disabling Future Rollups
Minting is typically a one-time event. As such, we recommend that the project team call the disableStateSettlement disable any further rollup. This will harden the contract security posture as any security compromise in the bridge infrastructure will not have any security impact on the ERC721 contract. This provides L1 security guarantee for the ERC721 contract.