From a27db2ae9abbaa2db5f37158dd0d68163232265c Mon Sep 17 00:00:00 2001 From: Joxes <91908708+Joxess@users.noreply.github.com> Date: Thu, 31 Jul 2025 21:42:56 -0300 Subject: [PATCH 01/10] feat: add-custom-gas-token-migration Signed-off-by: Joxes <91908708+Joxess@users.noreply.github.com> --- protocol/custom-gas-token-migration.md | 159 +++++++++++++++++++++++++ 1 file changed, 159 insertions(+) create mode 100644 protocol/custom-gas-token-migration.md diff --git a/protocol/custom-gas-token-migration.md b/protocol/custom-gas-token-migration.md new file mode 100644 index 00000000..5ebb8ba6 --- /dev/null +++ b/protocol/custom-gas-token-migration.md @@ -0,0 +1,159 @@ +# Custom Gas Token Migration: Design Doc + +| Author | *AgusDuha, Joxes, Skeletor* | +| --- | --- | +| Created at | *2025-07-31* | +| Initial Reviewers | *Mark Tyneway, TBD* | +| Need Approval From | *TBD* | +| Status | *In Review* | + +## Purpose + +Provide a repeatable, low-risk procedure for OP Stack chains that still run the legacy CGT implementation to migrate to the new proposed CGT design. The plan aims to keep full backward compatibility. + +## Summary + +The proposed Custom Gas Token upgrade lets any OP Stack chain introduce its native asset as the gas currency with almost no core-code intrusion: a single `isCustomGasToken()` flag turns off ETH transfer flows in all bridging methods, while two new pre-deploys, `NativeAssetLiquidity`, a contract with pre-minted assets, and `LiquidityController`, an owner-governed mint/burn router, hand supply control to chain governors or authorized “minter” contracts that can plug in anything from ERC-20 converters to third-party bridges or emission schedules. Wrapped-asset compatibility is preserved, and the entire system is initialized by seeding the native asset and allowing the governor to fully manage liquidity, such as integrating with the L2CGTBridge and burning any surplus. Lastly, we propose a method to address the issue of in-flight withdrawals when necessary. + +## Problem Statement + Context + +A new CGT implementation is being proposed to minimize the number of changes required to enable the custom gas token mode. In contrast, allow greater customizability for chain governors to define the native asset. However, chains already in production use the legacy CGT implementation. There should be a way to migrate the legacy implementation into the new one to make it possible for them to stay in a standard version for present and future compatibility in the OP Stack development. + +The goals for the migration must be: + +- Removes obsolete code from existing contracts and introduces the new changes. +- Avoid users from performing migration actions. +- Reduce the risk of breaking existing integrations. +- Requires as little client and infrastructure work as possible. +- One upgrade procedure in L2 should be enough to make it work. + +## Proposed Solution + +The solution consists of an upgrade procedure that performs two main changes: + +- Upgrade the chain +- Enable a new bridge for native asset minting, defined by the chain governor. + +### Chain’s Contracts Changes + +**L1 Contracts Upgrade** + +The following contracts are upgraded to the version that contains the new CGT implementation. The following main changes are expected: + +- In `SystemConfig`: + - Removal of the `GasPayingToken` library. + - This removes the `gasPayingToken`, `gasPayingTokenName`, and `gasPayingTokenSymbol`. + - `isCustomGasToken()` boolean is introduced at initialization, as a replacement for `setGasPayingToken`. +- In `OptimismPortal`: + - Removal of the `depositERC20Transaction` and `gasPayingToken` dependencies. + - Import `isCustomGasToken` to block `msg.value` > 0 during deposits, to block ETH sends. + - Migrate funds into a new bridge. + +**L2 Contracts Upgrade** + +The following contracts are upgraded to the version as well: + +- In `L1Block`: + - Removal of the `gasPayingToken`. + - Modifications of `gasPayingTokenName`, `gasPayingTokenSymbol` to query from `LiquidityController`. + - Retro-compatibility is guaranteed in the `WETH` predeploy contract, which contains old CGT code. + - Set `isCustomGasToken` at initialization. +- In `L2ToL1MessagePasser`: + - Import `isCustomGasToken` to block `msg.value` > 0 during withdrawals, to block native asset sends. +- `FeeVaults`: + - Upgraded to allow withdrawals into an L2 address and turn off L1 withdrawals. + +**New predeploys** + +Since the legacy L1-L2 native asset bridging is down, liquidity creation is replaced by introducing the following contracts during the upgrade: + +- `NativeAssetLiquidity`: This contains a large amount of native assets minted during the upgrade. +- `LiquidityController`: In charge of managing such liquidity. +- `L2CGTBridge`: predeploy addresses reserved for managing users’ requests to mint native assets, which the chain governor decides their implementation. + +**Consensus / Execution clients** + +Other than setting the new state containing the upgrade, no major changes are required. General configs might require being custom gas token aware. + +**Proofs** + +Other than setting the new state containing the upgrade, no major changes are required. + +### Native Asset Bridging + +Native asset bridging is outsourced from OP Stack core components, which means chain governors must implement their bridge set of contracts to migrate from the existing flow (through `OptimismPortal`) into a new one, which gets coupled into the `LiquidityController` and `L2CGTBridge` proxy. + +For example, a chain governor can implement a set of contracts that uses the reserved `L2CGTBridge` pre-deploy along with any set of L1 contracts to support bridging from L1. + +### Liquidity Migration on `OptimismPortal` + +The `OptimismPortal` would be required to be upgraded into an intermediate contract containing a function such as migrateLiquidity to move the ERC20 tokens into the new bridge. + +If the token is upgradable, the chain governor can also upgrade the token itself to swap the balances between the `OptimismPortal` and the new bridge. + +### Upgrade Overview Flow + +A chain using the CGT legacy implementation would need to pass through an upgrade process, which requires the following steps: + +1. Prepare and deploy the CGT Bridge. + +A chain governor would require deploying the desired bridge for native asset bridging in L1. This bridge will remain unusable (or paused) from deposits and withdrawals until the chain’s upgrade is completed. Deploying this contract in advance allows the chain governor to shorten the time the native asset bridging is disabled from the UX perspective. + +2. Upgrade all the contracts to the new CGT version via hard fork. + + Perform the upgrade for L1 and L2 contracts into the new implementations. + + Hardfork the L2 chain to add `NativeAssetLiquidity` (fund liquidity), add `LiquidityController`, reserve the `L2CGTBridge` address, and upgrade each predeploy contract. + + - For `NativeAssetLiquidity`, burn the amount of native asset that isn’t planned to be used. + - Relevant for chains that already run over pre-defined tokenomics. + - For `L2CGTBridge`, point to a desired implementation if the chain governor desires to give it to a user. + - For `OptimismPortal`, use an intermediate contract/implementation to move the funds into the new L1 CGT Bridge. +4. Update the chain state in Fault Proofs. +5. Activates `L1CGTBridge`. +6. Restore the rest of the OP Stack Chains related services. + +### In-Flight Withdrawals + +The upgrade may affect some initiated but not finalized withdrawals. One option that fits the migration flow is using the `L1CGTBridge` to support legacy withdrawals. This is done by porting `OptimismPortal`’s withdrawal logic and the latest valid state into the CGT Bridge and consulting the withdrawal mapping of `OptimismPortal` to ensure no completed withdrawals are replayed. + +The goal is for applications and users to consume the same APIs to prove and finalize into the new `L1CGTBridge`, which will contain the liquidity. + +### Resource Usage + +No usage changes. + +### Single Point of Failure and Multi Client Considerations + +Upgrades are a sensitive process and should be performed according to best practices. + +## Failure Mode Analysis + +TBD. + +## Impact on Developer Experience + +The following aspects should be taken into account: + +- Contracts that rely on `depositERC20Transaction` and `initiateWithdrawal` methods will revert when tried to call, so they need to upgrade their app to migrate to a new contract that uses the new bridging methods. + - It is recommended to track the `initiateWithdrawal` to understand the impact on them. +- Bridge UI interfaces must update the native asset bridging methods as well. +- Apps relying on `SystemConfig.gasPayingToken` methods must be aware and instead rely on the `L1Block` / `LiquidityController`. + +Please review the new CGT design doc for the impact of the latest proposed implementation. + +## Alternatives Considered + +**On Unfinalized Withdrawals** + +One of the main user-facing risks during the upgrade processes is that some unfinalized withdrawals that try to withdraw native assets will fail after the upgrade. Other alternatives were considered to satisfy each user to be able to get their assets during or after the upgrade: + +- **Pause or block msg.value > 0 in L2ToL1MessagePasser**: Upgrade the contract to block native asset withdrawals and let the users (or the chain governor) prove and finalize the withdrawals before fully upgrading the chain, cleaning the withdrawal queue. +- **OptimismPortal maintains the finalizeWithdrawal legacy code**: retain the withdrawal legacy code to maintain backward compatibility, at the cost of keeping old code just for this purpose and storing the exact portion of tokens there, which should be upgraded on a future date, since new CGT chains will not have this logic. +- **Inherit the CGT Bridge interface into OptimismPortal**: replicate the latest `OptimismPortal` logic (`ETHLockbox`), in this case, where the native assets are pulled from the CGT Bridge, at the cost of adding new code for this sole purpose. +- **Upgrade the Gas Token**: Only for chains that use an upgradable token can it simply mint tokens and reimburse the affected users due to the migration. + +## Risks & Uncertainties + +- Chains should ensure no critical dependencies on `depositERC20Transaction`, `initiateWithdrawal`, and related legacy CGT code being removed, and communicate with enough anticipation for proper migration. +- Chains with an enormous amount of native assets might cause an overflow in `NativeAssetLiquidity`. Currently, we set the liquidity to `type(uint248).max` wei, which should make such cases extremely rare. From e4c2f4ea5d77ea34dc8997f2c885f1b5d39ed479 Mon Sep 17 00:00:00 2001 From: Joxes <91908708+Joxess@users.noreply.github.com> Date: Thu, 31 Jul 2025 21:45:43 -0300 Subject: [PATCH 02/10] chore: fix format Signed-off-by: Joxes <91908708+Joxess@users.noreply.github.com> --- protocol/custom-gas-token-migration.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/protocol/custom-gas-token-migration.md b/protocol/custom-gas-token-migration.md index 5ebb8ba6..02c6170b 100644 --- a/protocol/custom-gas-token-migration.md +++ b/protocol/custom-gas-token-migration.md @@ -13,7 +13,7 @@ Provide a repeatable, low-risk procedure for OP Stack chains that still run the ## Summary -The proposed Custom Gas Token upgrade lets any OP Stack chain introduce its native asset as the gas currency with almost no core-code intrusion: a single `isCustomGasToken()` flag turns off ETH transfer flows in all bridging methods, while two new pre-deploys, `NativeAssetLiquidity`, a contract with pre-minted assets, and `LiquidityController`, an owner-governed mint/burn router, hand supply control to chain governors or authorized “minter” contracts that can plug in anything from ERC-20 converters to third-party bridges or emission schedules. Wrapped-asset compatibility is preserved, and the entire system is initialized by seeding the native asset and allowing the governor to fully manage liquidity, such as integrating with the L2CGTBridge and burning any surplus. Lastly, we propose a method to address the issue of in-flight withdrawals when necessary. +The proposed Custom Gas Token upgrade lets any OP Stack chain introduce its native asset as the gas currency with almost no core-code intrusion: a single `isCustomGasToken()` flag turns off ETH transfer flows in all bridging methods, while two new pre-deploys, `NativeAssetLiquidity`, a contract with pre-minted assets, and `LiquidityController`, an owner-governed mint/burn router, hand supply control to chain governors or authorized “minter” contracts that can plug in anything from ERC-20 converters to third-party bridges or emission schedules. Wrapped-asset compatibility is preserved, and the entire system is initialized by seeding the native asset and allowing the governor to fully manage liquidity, such as integrating with the `L2CGTBridge` and burning any surplus. Lastly, we propose a method to address the issue of in-flight withdrawals when necessary. ## Problem Statement + Context From 04dd40c915637222d211317726029524bbf51825 Mon Sep 17 00:00:00 2001 From: Joxes <91908708+Joxess@users.noreply.github.com> Date: Thu, 21 Aug 2025 01:33:33 -0300 Subject: [PATCH 03/10] docs: update L1 changes Signed-off-by: Joxes <91908708+Joxess@users.noreply.github.com> --- protocol/custom-gas-token-migration.md | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/protocol/custom-gas-token-migration.md b/protocol/custom-gas-token-migration.md index 02c6170b..b2b360ae 100644 --- a/protocol/custom-gas-token-migration.md +++ b/protocol/custom-gas-token-migration.md @@ -42,12 +42,13 @@ The following contracts are upgraded to the version that contains the new CGT im - In `SystemConfig`: - Removal of the `GasPayingToken` library. - - This removes the `gasPayingToken`, `gasPayingTokenName`, and `gasPayingTokenSymbol`. - - `isCustomGasToken()` boolean is introduced at initialization, as a replacement for `setGasPayingToken`. + - This removes the `gasPayingToken`, `gasPayingTokenName` and `gasPayingTokenSymbol`. + - Removal of the `GAS_PAYING_TOKEN_DECIMALS` constant. + - `isCustomGasToken()` boolean is read from `OptimismPortal`. - In `OptimismPortal`: - Removal of the `depositERC20Transaction` and `gasPayingToken` dependencies. - - Import `isCustomGasToken` to block `msg.value` > 0 during deposits, to block ETH sends. - - Migrate funds into a new bridge. + - Addition of the `isCustomGasToken` boolean to block `msg.value` > 0 during deposits, to block ETH sends. + - Migrate ERC20 balance into a new bridge. **L2 Contracts Upgrade** From de50734e9b3447d5abb15445e3a78f07469050bd Mon Sep 17 00:00:00 2001 From: Joxes <91908708+Joxess@users.noreply.github.com> Date: Thu, 21 Aug 2025 01:43:24 -0300 Subject: [PATCH 04/10] docs: improve summary Signed-off-by: Joxes <91908708+Joxess@users.noreply.github.com> --- protocol/custom-gas-token-migration.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/protocol/custom-gas-token-migration.md b/protocol/custom-gas-token-migration.md index b2b360ae..0bca5a49 100644 --- a/protocol/custom-gas-token-migration.md +++ b/protocol/custom-gas-token-migration.md @@ -13,7 +13,7 @@ Provide a repeatable, low-risk procedure for OP Stack chains that still run the ## Summary -The proposed Custom Gas Token upgrade lets any OP Stack chain introduce its native asset as the gas currency with almost no core-code intrusion: a single `isCustomGasToken()` flag turns off ETH transfer flows in all bridging methods, while two new pre-deploys, `NativeAssetLiquidity`, a contract with pre-minted assets, and `LiquidityController`, an owner-governed mint/burn router, hand supply control to chain governors or authorized “minter” contracts that can plug in anything from ERC-20 converters to third-party bridges or emission schedules. Wrapped-asset compatibility is preserved, and the entire system is initialized by seeding the native asset and allowing the governor to fully manage liquidity, such as integrating with the `L2CGTBridge` and burning any surplus. Lastly, we propose a method to address the issue of in-flight withdrawals when necessary. +The proposed Custom Gas Token (CGT) upgrade path enables any OP Stack chain running the legacy CGT implementation to migrate to the new design. The migration process assumes that the set of smart contracts either corresponds to an official release (e.g., v1.8.0) or complies with the legacy CGT specifications. Only a single upgrade procedure is expected to transition a valid old implementation into the new one. Finally, we propose a method to address the issue of in-flight withdrawals when necessary. ## Problem Statement + Context From bd49c6d96f57140c20af2d1433ec1eece53b30f2 Mon Sep 17 00:00:00 2001 From: Joxes <91908708+Joxess@users.noreply.github.com> Date: Thu, 21 Aug 2025 02:21:45 -0300 Subject: [PATCH 05/10] docs: update cgt features Signed-off-by: Joxes <91908708+Joxess@users.noreply.github.com> --- protocol/custom-gas-token-migration.md | 16 +++++++--------- 1 file changed, 7 insertions(+), 9 deletions(-) diff --git a/protocol/custom-gas-token-migration.md b/protocol/custom-gas-token-migration.md index 0bca5a49..19cbf7ee 100644 --- a/protocol/custom-gas-token-migration.md +++ b/protocol/custom-gas-token-migration.md @@ -32,7 +32,7 @@ The goals for the migration must be: The solution consists of an upgrade procedure that performs two main changes: - Upgrade the chain -- Enable a new bridge for native asset minting, defined by the chain governor. +- Enable a new L1-L2 bridge for native asset minting, defined by the chain governor. ### Chain’s Contracts Changes @@ -48,7 +48,7 @@ The following contracts are upgraded to the version that contains the new CGT im - In `OptimismPortal`: - Removal of the `depositERC20Transaction` and `gasPayingToken` dependencies. - Addition of the `isCustomGasToken` boolean to block `msg.value` > 0 during deposits, to block ETH sends. - - Migrate ERC20 balance into a new bridge. + - Migrate the ERC20 balance into a new bridge. **L2 Contracts Upgrade** @@ -70,7 +70,6 @@ Since the legacy L1-L2 native asset bridging is down, liquidity creation is repl - `NativeAssetLiquidity`: This contains a large amount of native assets minted during the upgrade. - `LiquidityController`: In charge of managing such liquidity. -- `L2CGTBridge`: predeploy addresses reserved for managing users’ requests to mint native assets, which the chain governor decides their implementation. **Consensus / Execution clients** @@ -82,13 +81,13 @@ Other than setting the new state containing the upgrade, no major changes are re ### Native Asset Bridging -Native asset bridging is outsourced from OP Stack core components, which means chain governors must implement their bridge set of contracts to migrate from the existing flow (through `OptimismPortal`) into a new one, which gets coupled into the `LiquidityController` and `L2CGTBridge` proxy. +Native asset bridging is outsourced from OP Stack core components, which means chain governors must implement their bridge set of contracts to migrate from the existing flow (through `OptimismPortal`) into a new one, which gets coupled into the `LiquidityController`. -For example, a chain governor can implement a set of contracts that uses the reserved `L2CGTBridge` pre-deploy along with any set of L1 contracts to support bridging from L1. +For example, a chain governor can implement a set of contracts that acts as minter of the `LiquidityController` along with any set of L1 contracts to support bridging from L1. ### Liquidity Migration on `OptimismPortal` -The `OptimismPortal` would be required to be upgraded into an intermediate contract containing a function such as migrateLiquidity to move the ERC20 tokens into the new bridge. +The `OptimismPortal` would be required to be upgraded into an intermediate contract containing a function such as `migrateLiquidity` to move the ERC20 balance into the new bridge. If the token is upgradable, the chain governor can also upgrade the token itself to swap the balances between the `OptimismPortal` and the new bridge. @@ -104,11 +103,10 @@ A chain governor would require deploying the desired bridge for native asset bri Perform the upgrade for L1 and L2 contracts into the new implementations. - Hardfork the L2 chain to add `NativeAssetLiquidity` (fund liquidity), add `LiquidityController`, reserve the `L2CGTBridge` address, and upgrade each predeploy contract. + Hardfork the L2 chain to add `NativeAssetLiquidity` (fund liquidity) and add `LiquidityController` and upgrade each existing predeploy contract. - For `NativeAssetLiquidity`, burn the amount of native asset that isn’t planned to be used. - - Relevant for chains that already run over pre-defined tokenomics. - - For `L2CGTBridge`, point to a desired implementation if the chain governor desires to give it to a user. + - Relevant for chains that already has a considerable amount of native asset supply scattered in the L2 state. - For `OptimismPortal`, use an intermediate contract/implementation to move the funds into the new L1 CGT Bridge. 4. Update the chain state in Fault Proofs. 5. Activates `L1CGTBridge`. From 4b32e045de71e3b7f42123afe5ac19a6bc2688b5 Mon Sep 17 00:00:00 2001 From: Joxes <91908708+Joxess@users.noreply.github.com> Date: Thu, 21 Aug 2025 11:16:28 -0300 Subject: [PATCH 06/10] docs: add CGT bridges deployment Signed-off-by: Joxes <91908708+Joxess@users.noreply.github.com> --- protocol/custom-gas-token-migration.md | 11 +++++++++-- 1 file changed, 9 insertions(+), 2 deletions(-) diff --git a/protocol/custom-gas-token-migration.md b/protocol/custom-gas-token-migration.md index 19cbf7ee..f4ae895a 100644 --- a/protocol/custom-gas-token-migration.md +++ b/protocol/custom-gas-token-migration.md @@ -91,6 +91,12 @@ The `OptimismPortal` would be required to be upgraded into an intermediate contr If the token is upgradable, the chain governor can also upgrade the token itself to swap the balances between the `OptimismPortal` and the new bridge. +### CGTBridge Deployment + +To automate the deployment process of the `L1CGTBridge` and `L2CGTBridge`, a Factory contract will be deployed on L1. This Factory is responsible for deploying the L1 and L2 bridge contracts (proxy + implementation) and ensuring that their addresses are deterministically derived. Since the addresses are precomputed, each bridge will already know the address of its counterpart at the time of deployment, eliminating the need for an additional step to manually set the bridge addresses. + +The `ProxyAdmin` owner must authorize the `L2CGTBridge` proxy address as a minter in the `LiquidityController`. + ### Upgrade Overview Flow A chain using the CGT legacy implementation would need to pass through an upgrade process, which requires the following steps: @@ -109,8 +115,9 @@ A chain governor would require deploying the desired bridge for native asset bri - Relevant for chains that already has a considerable amount of native asset supply scattered in the L2 state. - For `OptimismPortal`, use an intermediate contract/implementation to move the funds into the new L1 CGT Bridge. 4. Update the chain state in Fault Proofs. -5. Activates `L1CGTBridge`. -6. Restore the rest of the OP Stack Chains related services. +5. Grants the `authorizedMinter` role to the `L2CGTBridge`. +6. Activates `L1CGTBridge`. +7. Restore the rest of the OP Stack Chains related services. ### In-Flight Withdrawals From 48e8c10fd0c3ed38a92ce2435833e7a4ed9780db Mon Sep 17 00:00:00 2001 From: Joxes <91908708+Joxess@users.noreply.github.com> Date: Thu, 21 Aug 2025 11:39:44 -0300 Subject: [PATCH 07/10] docs: add contracts version considerations Signed-off-by: Joxes <91908708+Joxess@users.noreply.github.com> --- protocol/custom-gas-token-migration.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/protocol/custom-gas-token-migration.md b/protocol/custom-gas-token-migration.md index f4ae895a..5b7bb1e8 100644 --- a/protocol/custom-gas-token-migration.md +++ b/protocol/custom-gas-token-migration.md @@ -17,7 +17,7 @@ The proposed Custom Gas Token (CGT) upgrade path enables any OP Stack chain runn ## Problem Statement + Context -A new CGT implementation is being proposed to minimize the number of changes required to enable the custom gas token mode. In contrast, allow greater customizability for chain governors to define the native asset. However, chains already in production use the legacy CGT implementation. There should be a way to migrate the legacy implementation into the new one to make it possible for them to stay in a standard version for present and future compatibility in the OP Stack development. +A new CGT implementation is being proposed to minimize the number of changes required to enable the custom gas token mode. In contrast, allow greater customizability for chain governors to define the native asset. However, chains already in production use a legacy CGT implementation, for example, based in the op-contracts/v1.8.0 release. There should be a way to migrate the legacy implementation into the new one to make it possible for them to stay in a standard version for present and future compatibility in the OP Stack development. The goals for the migration must be: @@ -161,5 +161,6 @@ One of the main user-facing risks during the upgrade processes is that some unfi ## Risks & Uncertainties +- OP Stack chains might use contract versions that differ from v1.8.0 or even from the old CGT specs. A complete review of the core contracts is needed to ensure there are no inconsistencies with the proposed upgrade path that could introduce safety or liveness risks. - Chains should ensure no critical dependencies on `depositERC20Transaction`, `initiateWithdrawal`, and related legacy CGT code being removed, and communicate with enough anticipation for proper migration. - Chains with an enormous amount of native assets might cause an overflow in `NativeAssetLiquidity`. Currently, we set the liquidity to `type(uint248).max` wei, which should make such cases extremely rare. From b9979af1eb487c49b21ddadf9393263284e08a1e Mon Sep 17 00:00:00 2001 From: Joxes <91908708+Joxess@users.noreply.github.com> Date: Thu, 21 Aug 2025 11:46:30 -0300 Subject: [PATCH 08/10] docs: add reimburse solution as an alternative Signed-off-by: Joxes <91908708+Joxess@users.noreply.github.com> --- protocol/custom-gas-token-migration.md | 1 + 1 file changed, 1 insertion(+) diff --git a/protocol/custom-gas-token-migration.md b/protocol/custom-gas-token-migration.md index 5b7bb1e8..ff3067bd 100644 --- a/protocol/custom-gas-token-migration.md +++ b/protocol/custom-gas-token-migration.md @@ -158,6 +158,7 @@ One of the main user-facing risks during the upgrade processes is that some unfi - **OptimismPortal maintains the finalizeWithdrawal legacy code**: retain the withdrawal legacy code to maintain backward compatibility, at the cost of keeping old code just for this purpose and storing the exact portion of tokens there, which should be upgraded on a future date, since new CGT chains will not have this logic. - **Inherit the CGT Bridge interface into OptimismPortal**: replicate the latest `OptimismPortal` logic (`ETHLockbox`), in this case, where the native assets are pulled from the CGT Bridge, at the cost of adding new code for this sole purpose. - **Upgrade the Gas Token**: Only for chains that use an upgradable token can it simply mint tokens and reimburse the affected users due to the migration. +-** Return funds on L2 via a reimburse contract**: Deploy an reimburse contract as an authorized minter of the `LiquidityController`. The user initiates a request in L1, which verifies the unfinalized withdrawal status, sends a cross-chain message, and reimburses users directly on L2, effectively reversing unfinalized withdrawals. The contract can be retired once all reimbursements are completed. ## Risks & Uncertainties From aa78fe89eed5a22ffedb1dfa8385f9db3ddf78f9 Mon Sep 17 00:00:00 2001 From: Joxes <91908708+Joxess@users.noreply.github.com> Date: Thu, 21 Aug 2025 11:47:26 -0300 Subject: [PATCH 09/10] docs: fix format Signed-off-by: Joxes <91908708+Joxess@users.noreply.github.com> --- protocol/custom-gas-token-migration.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/protocol/custom-gas-token-migration.md b/protocol/custom-gas-token-migration.md index ff3067bd..3692d8d5 100644 --- a/protocol/custom-gas-token-migration.md +++ b/protocol/custom-gas-token-migration.md @@ -158,7 +158,7 @@ One of the main user-facing risks during the upgrade processes is that some unfi - **OptimismPortal maintains the finalizeWithdrawal legacy code**: retain the withdrawal legacy code to maintain backward compatibility, at the cost of keeping old code just for this purpose and storing the exact portion of tokens there, which should be upgraded on a future date, since new CGT chains will not have this logic. - **Inherit the CGT Bridge interface into OptimismPortal**: replicate the latest `OptimismPortal` logic (`ETHLockbox`), in this case, where the native assets are pulled from the CGT Bridge, at the cost of adding new code for this sole purpose. - **Upgrade the Gas Token**: Only for chains that use an upgradable token can it simply mint tokens and reimburse the affected users due to the migration. --** Return funds on L2 via a reimburse contract**: Deploy an reimburse contract as an authorized minter of the `LiquidityController`. The user initiates a request in L1, which verifies the unfinalized withdrawal status, sends a cross-chain message, and reimburses users directly on L2, effectively reversing unfinalized withdrawals. The contract can be retired once all reimbursements are completed. +- **Return funds on L2 via a reimburse contract**: Deploy an reimburse contract as an authorized minter of the `LiquidityController`. The user initiates a request in L1, which verifies the unfinalized withdrawal status, sends a cross-chain message, and reimburses users directly on L2, effectively reversing unfinalized withdrawals. The contract can be retired once all reimbursements are completed. ## Risks & Uncertainties From f68ec99249acd55098b3e9856c177b318a77cb0d Mon Sep 17 00:00:00 2001 From: Joxes <91908708+Joxess@users.noreply.github.com> Date: Thu, 21 Aug 2025 12:08:10 -0300 Subject: [PATCH 10/10] docs: list of contracts to be upgraded Signed-off-by: Joxes <91908708+Joxess@users.noreply.github.com> --- protocol/custom-gas-token-migration.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/protocol/custom-gas-token-migration.md b/protocol/custom-gas-token-migration.md index 3692d8d5..f50f6b83 100644 --- a/protocol/custom-gas-token-migration.md +++ b/protocol/custom-gas-token-migration.md @@ -107,9 +107,9 @@ A chain governor would require deploying the desired bridge for native asset bri 2. Upgrade all the contracts to the new CGT version via hard fork. - Perform the upgrade for L1 and L2 contracts into the new implementations. + Perform the upgrade for L1 and L2 contracts into the new implementations. The following L1 contracts needs to be upgraded: `SystemConfig`, `OptimismPortal`, `L1CrossDomainMessenger` and `L1StandardBridge`. - Hardfork the L2 chain to add `NativeAssetLiquidity` (fund liquidity) and add `LiquidityController` and upgrade each existing predeploy contract. + Hardfork the L2 chain through a NUT to add `NativeAssetLiquidity` (`fund` liquidity) and add `LiquidityController` and upgrade the `L1Block`, `L2StandardBridge`, `L2CrossDomainMessenger` and `L2ToL1MessagePasser` predeploy contracts. - For `NativeAssetLiquidity`, burn the amount of native asset that isn’t planned to be used. - Relevant for chains that already has a considerable amount of native asset supply scattered in the L2 state.