## Arbitrum Mint/Burn & ERC20MigrationOutbox (Nitro v3.7.4)

### What is the ERC20MigrationOutbox contract?

#### Purpose and how it works
- The `ERC20MigrationOutbox` is part of Offchain Labs’ mint/burn feature for custom gas tokens. When an Orbit chain uses an ERC‑20 token as its native gas token, the canonical bridge on Ethereum escrows that token and mints it on the child chain via `ERC20Bridge`. Once the chain owner decides to use a different bridge (e.g., an OFT/xERC20 external bridge) or to move the collateral away from the canonical bridge, they need a way to sweep the escrowed tokens out of the canonical bridge.
- The ERC20MigrationOutbox provides this “migration” functionality:
- It is a small [contract](https://github.com/OffchainLabs/nitro-contracts/blob/main/src/bridge/extra/ERC20MigrationOutbox.sol) with three immutable variables:
- a reference to the ERC20Bridge,
- the address of the native token being escrowed, and
- the destination address (usually an external bridge address)
- In the `migrate()` [function](https://github.com/OffchainLabs/nitro-contracts/blob/0b8c04e8f5f66fe6678a4f53aa15f23da417260e/src/bridge/extra/ERC20MigrationOutbox.sol#L33), it reads the balance of the native token held by the bridge. If there is no balance, it reverts with `NoBalanceToMigrate`. It then calls `bridge.executeCall(destination, bal, "")`, which transfers the entire token balance to the destination. If the call fails, it reverts with `MigrationFailed(returndata)`. On success, it emits a `CollateralMigrated` event.
- Because `migrate()` does not require any particular caller, anyone can trigger the migration once the contract is added as an outbox. This design avoids the need for multi‑sig coordination at the time of migration.

The contract is intentionally simple and has no assumptions about the external bridge. However, the official code [comments](https://github.com/OffchainLabs/nitro-contracts/blob/0b8c04e8f5f66fe6678a4f53aa15f23da417260e/src/bridge/extra/ERC20MigrationOutbox.sol#L13) note several important caveats:
- It should be enabled together with the vanilla outbox. In other words, the Bridge must allow both the standard outbox and the migration outbox.
- Value withdrawals via the native bridge (ArbSys) must be disabled on the child chain while the migration outbox is used. If a user tries to withdraw tokens via the native bridge while the migration outbox is allowed, the funds and messages would become “stuck,” because the native bridge would no longer hold the necessary collateral.
- The `destination` address must not be the zero address; the constructor will revert otherwise.

How it fits into the mint/burn workflow:
- Orbit chains that enable mint/burn do not rely solely on bridging deposits and withdrawals to manage the supply of their gas token. Instead, an on‑chain precompile [ArbNativeTokenManager](https://raw.githubusercontent.com/OffchainLabs/nitro-precompile-interfaces/main/ArbNativeTokenManager.sol#:~:text=,address%20indexed%20to%2C%20uint256%20amount) allows authorized owners to mint and burn the native token. The interface shows two functions, `mintNativeToken` and `burnNativeToken`, and events `NativeTokenMinted` and `NativeTokenBurned`. This precompile exists at address `0x73` and is available in `ArbOS≥41`.
- The canonical bridge still holds collateral equal to the circulating supply minted via deposits before mint/burn is enabled. When migrating to an external bridge (or another design), chain owners use the `ERC20MigrationOutbox` to sweep those escrowed tokens to the destination contract, where they can be burned or managed under the new bridge’s rules.

### Security review

Trail of Bits performed a dedicated audit of the mint/burn precompile and `ERC20MigrationOutbox`. Their summary [report](https://docs.arbitrum.io/assets/files/2025-06-offchain-arbitrum-mint-burn-precompile-securityreview-79ff8927ca1cd62424d286b0b30838ae.pdf#:~:text=Offchain%20Labs%20engaged%20Trail%20of,tokens%20from%20the%20native%20Arbitrum) notes that Offchain Labs added the migration outbox so “native tokens can be migrated from the native Arbitrum bridge to an external bridge on Orbit chains”. The auditors found three low or informational‑severity [findings](https://docs.arbitrum.io/assets/files/2025-06-offchain-arbitrum-mint-burn-precompile-securityreview-79ff8927ca1cd62424d286b0b30838ae.pdf#:~:text=Our%20review%20identified%20three%20issues%3A,the%20Code%20Quality%20Recommendations%20appendix) (improper timestamp validation, retroactive timestamp modification, and undefined behavior when the native token owner list is not updated). None of these findings relate to the migration outbox contract; they concern the `ArbOwner` and `ArbNativeTokenManager` precompiles. Offchain Labs deemed the observed behaviors intentional and did not modify the functionality. Trail of Bits recommended adding zero‑address checks in the migration outbox constructor and adding a migration event and better [NatSpec comments](https://docs.arbitrum.io/assets/files/2025-06-offchain-arbitrum-mint-burn-precompile-securityreview-79ff8927ca1cd62424d286b0b30838ae.pdf#:~:text=%E2%97%8F%20Add%20a%20specific%20migration,in%20the%20ERC20MigrationOutbox%20contract%E2%80%99s%20constructor), which were implemented in later PRs.

### Version dependency and compatibility

#### 1. Nitro version / ArbOS requirement:
Mint/burn and the migration outbox are not available in Nitro 2.1.0. They were introduced in the Nitro v3 family (around PR [#335]( https://github.com/OffchainLabs/nitro-contracts/pull/335) and [#339]( https://github.com/OffchainLabs/nitro-contracts/pull/339) in nitro-contracts) and require ArbOS ≥ 41. The [ArbNativeTokenManager](https://raw.githubusercontent.com/OffchainLabs/nitro-precompile-interfaces/main/ArbNativeTokenManager.sol#:~:text=,interface%20ArbNativeTokenManager) interface explicitly states that it is “available in ArbOS version 41 and above”. Mint/burn support is therefore absent in older versions; using ERC20MigrationOutbox with nitro-contracts v2.1.0 would be impossible because the precompile and the extended Bridge.executeCall() semantics are missing. Upgrading to Nitro v3.x (e.g., v3.7.4) is necessary to use custom gas tokens with mint/burn.
#### 2. BoLD (Bounded Liquidity Delay):
The Arbitrum [documentation](https://docs.arbitrum.io/launch-arbitrum-chain/configure-your-chain/common-configurations/use-a-custom-gas-token-rollup#:~:text=info) emphasises that custom gas tokens on Rollup mode currently require the chain to **post data to Ethereum and have BoLD enabled**. BoLD is only supported in the v3.x series of Nitro. If we're currently using v2.1.0, enabling mint/burn for a custom gas token will also require adopting BoLD.
#### 3. Native bridge configuration:
When the migration outbox is used, chain operators must disable value withdrawals via the native bridge (the ArbSys precompile) because the escrowed tokens are no longer in the native bridge contract after migration. In practice, this is done by calling SetNativeTokenEnabledFrom in ArbOwner to turn off native token withdrawal and by updating the outbox list to include the migration outbox.
#### 4. Destination bridge requirements:
The destination address must belong to a contract capable of receiving the entire collateral and, in most cases, burning it or managing it according to the new bridge’s logic. If the chain will use an OFT/xERC20 or other cross‑chain token standard, the destination should be an adapter contract that locks or burns tokens on the parent chain and emits a message for minting on the child chain. More [info](https://medium.com/@peterifreke/arbos-50-revolutionizing-gas-on-arbitrum-orbit-chains-with-crosschain-tokens-41268abaab94)

### 3. How to integrate ERC20MigrationOutbox into your fork

#### 1. Upgrade to Nitro 3.x and enable mint/burn:
Assuming the fork currently runs on nitro-contracts v2.1.0, we must upgrade to a version that supports mint/burn (≥ v3.3). This upgrade brings in the `ArbNativeTokenManager` precompile and the `ERC20MigrationOutbox` contract. It also enables BoLD, which is required for Rollup chains using a [custom gas token](https://docs.arbitrum.io/launch-arbitrum-chain/configure-your-chain/common-configurations/use-a-custom-gas-token-rollup#:~:text=info). Ensure that the upgrade is thoroughly tested because it includes other changes (e.g., new gas metering options, precompile updates, and bug fixes).
#### 2. Deploy and configure the migration outbox:

1. On the parent chain, deploy `ERC20MigrationOutbox`, passing the canonical ERC20Bridge address and the destination address (external bridge or adapter). The constructor ensures the destination is non‑zero.
2. Use Bridge.setOutbox (a function restricted to the rollup owner) to enable the migration outbox alongside the standard outbox. This step allows L2→L1 messages to target the migration outbox.
3. On the child chain, disable value withdrawal for the native token by calling `ArbOwner.SetNativeTokenEnabledFrom(0)` (or schedule a future time after which withdrawals are reenabled). This prevents users from using the old withdrawal mechanism after the collateral has been migrated.
4. Once the migration outbox is enabled, anyone can call migrate() to sweep the tokens from the canonical bridge into the new destination contract. The chain’s governance should coordinate this call to ensure it happens at the desired time.

#### 3. Post‑migration tasks:
After migration, update the chain’s gas‑token configuration to stop using the canonical bridge and instead rely on your deployed external bridge. You also need to update off‑chain relayers and UI components to reflect the new bridging path. If users still hold representation tokens on the child chain from the old bridge, provide a swap contract or a burn‑and‑mint mechanism to convert them to the new representation.

### 4. Recommendation for customers – use now or wait?

**Overall assessment:** The ERC20MigrationOutbox is a straightforward contract whose only purpose is to transfer the entire escrowed supply of the native gas token from the canonical ERC20Bridge to a specified destination. Its code is short, audited, and does not introduce complex logic. The _mint/burn_ feature and the migration mechanism were subject to a Trail of Bits security review, which did not find critical [vulnerabilities](https://docs.arbitrum.io/assets/files/2025-06-offchain-arbitrum-mint-burn-precompile-securityreview-79ff8927ca1cd62424d286b0b30838ae.pdf#:~:text=Our%20review%20identified%20three%20issues%3A,the%20Code%20Quality%20Recommendations%20appendix). Offchain Labs intentionally left certain behaviors (timestamp resets and owner permissions) unchanged, and these are unrelated to the migration outbox. Based on the available information, the feature appears safe to use when the operator understands the trust assumptions and properly configures their chain.

#### When it makes sense to use
- **Chain operators wanting to adopt external bridges:** If your Orbit chain plans to use OFT, xERC20, or another cross‑chain standard for its native gas token, you must sweep collateral out of the canonical bridge. In such cases, ERC20MigrationOutbox is necessary and should be used.
- **Operators comfortable with Nitro 3.x:** Because mint/burn and the migration outbox require Nitro 3.x and BoLD, you should only proceed if you are ready to upgrade your fork. For forks stuck on 2.x, the migration outbox cannot be used.
- **Audited external bridge:** Your destination bridge should be thoroughly audited. Using an unsafe bridge defeats the purpose of a secure migration. The Medium article on ArbOS 50 highlights the security trade‑offs of relying on external bridges; the 2022 Harmony Horizon bridge hack is cited as a [cautionary tale](https://medium.com/@peterifreke/arbos-50-revolutionizing-gas-on-arbitrum-orbit-chains-with-crosschain-tokens-41268abaab94).

#### When it might be better to wait
- **Chains without a clear external‑bridge strategy:** If you are still evaluating which cross‑chain protocol (LayerZero OFT, Wormhole, etc.) to use or if your customers rely on the canonical bridge, you may wait to upgrade. The canonical bridge remains fully supported for custom gas tokens; you can still use a mint/burn token while leaving collateral locked in the canonical bridge.
- **Chains on Nitro 2.x:** Upgrading a rollup stack is non‑trivial. If your customers prioritise stability over new features, it may be prudent to remain on v2.x until you have the resources to migrate to v3.x, test BoLD, and adopt the new precompiles.

### Final guidance

In summary, `ERC20MigrationOutbox` is a tool for safely migrating native gas‑token collateral off of the canonical bridge when adopting an external bridge. It does not introduce complicated logic and has been externally audited. To use it, you must upgrade your Nitro fork to a version supporting mint/burn (ArbOS ≥ 41, Nitro ≥ 3.x), enable BoLD, and configure both the outboxes and native‑token settings. Provided these steps are followed and the destination bridge is secure, using the migration outbox is recommended. For chains that are not ready to upgrade or that lack a clear bridging strategy, continue using the canonical bridge until the upgrade path is clear.