From de634553de670e959c06630b3eb626f200f6104b Mon Sep 17 00:00:00 2001 From: cpengilly <29023967+cpengilly@users.noreply.github.com> Date: Wed, 1 May 2024 20:17:51 -0700 Subject: [PATCH 1/6] custom-gas-token page for chain ops --- .../chain-operators/management/_meta.json | 1 + .../management/custom-gas-token.mdx | 120 ++++++++++++++++++ words.txt | 1 + 3 files changed, 122 insertions(+) create mode 100644 pages/builders/chain-operators/management/custom-gas-token.mdx diff --git a/pages/builders/chain-operators/management/_meta.json b/pages/builders/chain-operators/management/_meta.json index 04dc113af..d37c43c2b 100644 --- a/pages/builders/chain-operators/management/_meta.json +++ b/pages/builders/chain-operators/management/_meta.json @@ -2,6 +2,7 @@ "configuration": "Configuration", "blobs": "Using Blobs", "snap-sync": "Using Snap Sync", + "custom-gas-token": "Run a Custom Gas Token Chain", "operations": "Node Operations", "key-management": "Key Management", "troubleshooting": "Troubleshooting" diff --git a/pages/builders/chain-operators/management/custom-gas-token.mdx b/pages/builders/chain-operators/management/custom-gas-token.mdx new file mode 100644 index 000000000..50a98da07 --- /dev/null +++ b/pages/builders/chain-operators/management/custom-gas-token.mdx @@ -0,0 +1,120 @@ +--- +title: How to Run a Custom Gas Token Chain +lang: en-US +description: Learn how to run a custom gas token chain. +--- + +import { Callout, Steps } from 'nextra/components' + +# How to Run a Custom Gas Token Chain + + + We do not recommend running a Custom Gas Token chain in production mainnet yet. + This guide is for running testnet chains. The OP Labs team will flag when they have confidence in the security of the implementation code. + + +This guide provides a walkthrough for chain operators who want to run a custom gas token chain. +An OP Stack chain that uses the custom gas token feature enables an end user to deposit an L1 native ERC20 token into L2 where that asset is minted as the native L2 asset and can be used to pay for gas on L2. + + + ### Deploying Your Contracts + + * Checkout the [custom gas token branch](https://github.com/ethereum-optimism/optimism/pull/10143) and use the commit to deploy. This will be merged into the main branch after fault proofs are code complete. + + + Be sure to check out this branch or you will not deploy a chain that uses custom gas token! + + + * Update the deploy config in `contracts-bedrock/deploy-config` with new fields: `useCustomGasToken` and `customGasTokenAddress` + + * Set `useCustomGasToken` to `true` and the address of the L1 ERC20 token should be in `customGasTokenAddress`. The ERC20 should already be deployed before trying to spin up the custom gas token chain. + + If you set `useCustomGasToken` to `false` (it defaults this way), then it will use ETH as the gas paying token. + + * Set `customGasTokenAddress` to the contract address of an L1 ERC20 token you wish to use as the gas token on your L2. + + The custom gas token being set must meet the following criteria: + + * the number of decimals on the token MUST be exactly 18 + * the name of the token MUST be less than or equal to 32 bytes + * symbol MUST be less than or equal to 32 bytes. + + + You will NOT be able to change the address of the custom gas token if it is already set. + + + * Deploy the L1 contracts from `contracts-bedrock` using the following command: + + ```bash + DEPLOYMENT_OUTFILE=deployments/artifact.json \ + DEPLOY_CONFIG_PATH= \ + forge script scripts/Deploy.s.sol:Deploy \ + --broadcast --private-key $PRIVATE_KEY \ + --rpc-url $ETH_RPC_URL + ``` + + * `DEPLOYMENT_OUTFILE` is the path to the file at which the L1 contract deployment artifacts are written to after deployment. Foundry has filesystem restrictions for security, so make this file a child of the `deployments` directory. This file will contain key/value pairs of the names and addresses of the deployed contracts. + * `DEPLOY_CONFIG_PATH` is the path to the file for the deploy config used to deploy + + ### Generating L2 Allocs + + + Be sure to use the same branch that you used to deploy the L1 contracts. + + + A forge script is used to generate the L2 genesis. It is a requirement that the L1 contracts have been deployed before generating the L2 genesis, since some L1 contract addresses are embedded into the L2 genesis. + + ```bash + CONTRACT_ADDRESSES_PATH=deployments/artifact.json \ + DEPLOY_CONFIG_PATH= \ + STATE_DUMP_PATH= \ + forge script scripts/L2Genesis.s.sol:L2Genesis \ + --sig 'runWithStateDump()' --chain-id $L2_CHAIN_ID + ``` + + To generate L2 Allocs, it is assumed that: + + * You have the L1 contracts artifact, specified with `DEPLOYMENT_OUTFILE` + * `CONTRACT_ADDRESSES_PATH` is the path to the deployment artifact from deploying the L1 contracts in the first step, aka `DEPLOYMENT_OUTFILE` + * `DEPLOY_CONFIG_PATH` is the path to the file for the deploy config used to deploy + * `STATE_DUMP_PATH` is a path to the generated L2 allocs file, this is the genesis state and is required for the next step. + + ### Generating L2 Genesis + + The `op-node` is used to generate the final L2 genesis file. It takes the allocs created by the forge script as input for the `--l2-allocs` flag. + + ```bash + op-node genesis l2 \ + --l1-rpc $ETH_RPC_URL \ + --deploy-config \ + --l2-allocs \ + --l1-deployments \ + --outfile.l2 \ + --outfile.rollup + ``` + + ### Spinning Up Your Infrastructure + + Ensure that the end to end system is running. + + ### Depositing Your Custom Gas Token into Your Chain + + * To deposit your custom gas token into your chain, you must use the **`OptimismPortalProxy.depositERC20Transaction`** method + * Users MUST first `approve()` the `OptimismPortal` before they can deposit tokens using `depositERC20Transaction`. + + ``` + function depositERC20Transaction( + address _to, + uint256 _mint, + uint256 _value, + uint64 _gasLimit, + bool _isCreation, + bytes memory _data + ) public; + ``` + + +## Next Steps + +* For more detailed info on custom gas tokens, see the [specs](https://specs.optimism.io/experimental/custom-gas-token.html). +* If experience any problems, please reach out to [developer support](https://github.com/ethereum-optimism/developers/discussions). diff --git a/words.txt b/words.txt index d79126436..39bd5e4b5 100644 --- a/words.txt +++ b/words.txt @@ -5,6 +5,7 @@ accountslots ADDI ADDIU ADDU +Allocs allocs ANDI Ankr From ce6f702735636a9f7f291a67d3817edc618e1768 Mon Sep 17 00:00:00 2001 From: cpengilly <29023967+cpengilly@users.noreply.github.com> Date: Thu, 23 May 2024 23:53:17 -0700 Subject: [PATCH 2/6] add explainer and internal links --- .../management/custom-gas-token.mdx | 6 +- pages/stack/protocol/_meta.json | 1 + pages/stack/protocol/features/_meta.json | 3 + .../protocol/features/custom-gas-token.mdx | 66 +++++++++++++++++++ words.txt | 1 - 5 files changed, 73 insertions(+), 4 deletions(-) create mode 100644 pages/stack/protocol/features/_meta.json create mode 100644 pages/stack/protocol/features/custom-gas-token.mdx diff --git a/pages/builders/chain-operators/management/custom-gas-token.mdx b/pages/builders/chain-operators/management/custom-gas-token.mdx index 50a98da07..b38bdc48a 100644 --- a/pages/builders/chain-operators/management/custom-gas-token.mdx +++ b/pages/builders/chain-operators/management/custom-gas-token.mdx @@ -13,7 +13,7 @@ import { Callout, Steps } from 'nextra/components' This guide is for running testnet chains. The OP Labs team will flag when they have confidence in the security of the implementation code. -This guide provides a walkthrough for chain operators who want to run a custom gas token chain. +This guide provides a walkthrough for chain operators who want to run a custom gas token chain. See the [Custom Gas Token Explainer](/stack/protocol/features/custom-gas-token) for a general overview of this OP Stack feature. An OP Stack chain that uses the custom gas token feature enables an end user to deposit an L1 native ERC20 token into L2 where that asset is minted as the native L2 asset and can be used to pay for gas on L2. @@ -116,5 +116,5 @@ An OP Stack chain that uses the custom gas token feature enables an end user to ## Next Steps -* For more detailed info on custom gas tokens, see the [specs](https://specs.optimism.io/experimental/custom-gas-token.html). -* If experience any problems, please reach out to [developer support](https://github.com/ethereum-optimism/developers/discussions). +* For more detailed info on custom gas tokens, see the [specs](https://specs.optimism.io/protocol/granite/custom-gas-token.html). +* If you experience any problems, please reach out to [developer support](https://github.com/ethereum-optimism/developers/discussions). diff --git a/pages/stack/protocol/_meta.json b/pages/stack/protocol/_meta.json index a2ce154b7..5f67f7a27 100644 --- a/pages/stack/protocol/_meta.json +++ b/pages/stack/protocol/_meta.json @@ -1,5 +1,6 @@ { "rollup": "Rollup", "fault-proofs": "Fault Proofs", + "features": "Features", "outages": "Sequencer Outages" } \ No newline at end of file diff --git a/pages/stack/protocol/features/_meta.json b/pages/stack/protocol/features/_meta.json new file mode 100644 index 000000000..3871d9f9c --- /dev/null +++ b/pages/stack/protocol/features/_meta.json @@ -0,0 +1,3 @@ +{ + "custom-gas-token": "Custom Gas Token" +} \ No newline at end of file diff --git a/pages/stack/protocol/features/custom-gas-token.mdx b/pages/stack/protocol/features/custom-gas-token.mdx new file mode 100644 index 000000000..46ef71240 --- /dev/null +++ b/pages/stack/protocol/features/custom-gas-token.mdx @@ -0,0 +1,66 @@ +--- +title: Custom Gas Token +lang: en-US +description: Learn how to run a custom gas token chain. +--- + +import { Callout } from 'nextra/components' + +# Custom Gas Token Explainer + +The Custom Gas Token configuration lets OP Stack chain operators deploy their chain allowing a specific ERC-20 token to be deposited in as the native token to pay for gas fees. Chain operators can now customize their gas token to: + +* provide utility for their project's token +* make it easier to subsidize gas costs for their users directly via their token treasury +* facilitate in-game economies, allowing players to pay for gas with their in-game currency +* build alignment with the community of any token. + +## Native Gas Tokens + +By default, L2 OP Stack chains allow users to deposit ETH from L1 into the chain as the L2 ETH, the native token that can then be used to pay for gas fees. +Chain operators wanted to configure the stack to use a custom token to pay for gas, other than ETH. + +With custom gas tokens, chain operators can now set an L1 ERC-20 token address at the time of deploying the contracts of their chain. +When deposited, this L1 ERC-20 token will become the native gas token on the L2 and can be used to pay for gas fees. + + + **Caveats chain operators should be aware of:** + * You cannot switch from your custom gas token to another token after the chain is launched. + * You will need to manually modify your fee configuration values to properly charge fees for users. + * Understand the [constraints required for your chain to be able to join the Superchain](#considerations) when setting the custom gas token for your chain. + + +## How It Works + +This is the general flow of how custom gas tokens work on the OP Stack: + +* On deployment of an L2 chain, set the address of an L1 token to be used as the gas token. +* When depositing a custom gas token to L2, it mints the native L2 token. +* Withdrawing the native L2 token results in the unlocking of the custom token on L1. +* The native L2 token is used by default to pay for gas fees. + +## Benefits + +Chain operators get the following benefits by using custom gas tokens: + +* use an L1 ERC-20 token as the custom gas token for L2 OP Stack chain deployment +* use an ERC-20 token on an existing L2 OP Stack chain as as the custom gas token for an L3 OP Stack chain deployment +* use custom gas tokens with other configurations of the OP Stack, including Plasma Mode. + +## Considerations + +The custom token being used must adhere to the following constraints to be able to join the Superchain: + +* Must be a non-yield bearing token (This is a requirement from Legal) +* Must be a valid ERC-20 token +* Must have 18 decimals +* Can't be rebasing or have a transfer fee +* Must only be transferrable via a call to the token address itself +* Must only be able to set allowance via a call to the token address itself +* Must not have a callback on transfer, and more generally a user must not be able to make a transfer to themselves revert + +## Next Steps + +* Ready to get started? Read our guide on how to [deploy your custom gas token chain](/builders/chain-operators/management/custom-gas-token). +* For bridges or developers building on a custom gas token chain, read our guide on how to deposit custom gas tokens into a chain. +* For more info about how the custom gas token feature works under the hood, [check out the specs](https://specs.optimism.io/protocol/granite/custom-gas-token.html). diff --git a/words.txt b/words.txt index 5bfac88e0..109ea0578 100644 --- a/words.txt +++ b/words.txt @@ -135,7 +135,6 @@ journalremotes JSPATH jspath jwtsecret -leadup leveldb lightkdf logfile From d2f0f7727145bd5f9d8ec37df9998a5ea7669610 Mon Sep 17 00:00:00 2001 From: cpengilly <29023967+cpengilly@users.noreply.github.com> Date: Fri, 24 May 2024 01:25:01 -0700 Subject: [PATCH 3/6] content updates --- .../management/custom-gas-token.mdx | 3 +- .../protocol/features/custom-gas-token.mdx | 38 ++++++++++++++++--- 2 files changed, 34 insertions(+), 7 deletions(-) diff --git a/pages/builders/chain-operators/management/custom-gas-token.mdx b/pages/builders/chain-operators/management/custom-gas-token.mdx index b38bdc48a..c310d14b0 100644 --- a/pages/builders/chain-operators/management/custom-gas-token.mdx +++ b/pages/builders/chain-operators/management/custom-gas-token.mdx @@ -19,7 +19,7 @@ An OP Stack chain that uses the custom gas token feature enables an end user to ### Deploying Your Contracts - * Checkout the [custom gas token branch](https://github.com/ethereum-optimism/optimism/pull/10143) and use the commit to deploy. This will be merged into the main branch after fault proofs are code complete. + * Checkout the [custom gas token branch](https://github.com/ethereum-optimism/optimism/pull/10143) and use the commit to deploy. Be sure to check out this branch or you will not deploy a chain that uses custom gas token! @@ -116,5 +116,6 @@ An OP Stack chain that uses the custom gas token feature enables an end user to ## Next Steps +* Additional questions? See the FAQ section in the [Custom Gas Token Explainer](/stack/protocol/features/custom-gas-token#faqs). * For more detailed info on custom gas tokens, see the [specs](https://specs.optimism.io/protocol/granite/custom-gas-token.html). * If you experience any problems, please reach out to [developer support](https://github.com/ethereum-optimism/developers/discussions). diff --git a/pages/stack/protocol/features/custom-gas-token.mdx b/pages/stack/protocol/features/custom-gas-token.mdx index 46ef71240..294a0660c 100644 --- a/pages/stack/protocol/features/custom-gas-token.mdx +++ b/pages/stack/protocol/features/custom-gas-token.mdx @@ -1,7 +1,7 @@ --- -title: Custom Gas Token +title: Custom Gas Token Explainer lang: en-US -description: Learn how to run a custom gas token chain. +description: Learn the basic process, benefits, and considerations for running a custom gas token chain. --- import { Callout } from 'nextra/components' @@ -43,9 +43,9 @@ This is the general flow of how custom gas tokens work on the OP Stack: Chain operators get the following benefits by using custom gas tokens: -* use an L1 ERC-20 token as the custom gas token for L2 OP Stack chain deployment -* use an ERC-20 token on an existing L2 OP Stack chain as as the custom gas token for an L3 OP Stack chain deployment -* use custom gas tokens with other configurations of the OP Stack, including Plasma Mode. +* can use an L1 ERC-20 token as the custom gas token for L2 OP Stack chain deployment +* can use an ERC-20 token on an existing L2 OP Stack chain as as the custom gas token for an L3 OP Stack chain deployment +* can use custom gas tokens with other configurations of the OP Stack, including Plasma Mode. ## Considerations @@ -62,5 +62,31 @@ The custom token being used must adhere to the following constraints to be able ## Next Steps * Ready to get started? Read our guide on how to [deploy your custom gas token chain](/builders/chain-operators/management/custom-gas-token). -* For bridges or developers building on a custom gas token chain, read our guide on how to deposit custom gas tokens into a chain. +* For bridges or developers building on a custom gas token chain, read our tutorial on [depositing custom gas tokens into a chain](/builders/app-developers/tutorials/standard-bridge-custom-token). * For more info about how the custom gas token feature works under the hood, [check out the specs](https://specs.optimism.io/protocol/granite/custom-gas-token.html). + +## FAQs + +### What is the Wrapped (ERC-20) Gas Token? + +- The `WETH` predeploy at `0x4200000000000000000000000000000000000006` represents the wrapped custom gas token. If you wish to transact with your native gas token as an ERC-20, you can `deposit` and `withdraw` from this contract to wrap and unwrap your token. +- What this means is the asset at the `WETH` predeploy is not `ether` but instead is the wrapped version of your custom gas token. Its an ERC20 token, the `name()` will be `"Wrapped ..."` (whatever the name of your token is). + +### How do I charge fees as the chain operator? + +The initial release of custom gas token does not have special logic for taking into account the exchange rate between the custom gas token and ether. This logic is nice to have because it requires ether to purchase data availability for Ethereum. If the chain is earning in a custom gas token and spending in ether, then it must earn enough custom gas token such that it can be sold for ether. + +For the initial release of custom gas token, the chain operator will need to manage this either out of band or by manually tuning the fee parameters to ensure profitability. A future release may include [L1 Fee Abstraction](https://github.com/ethereum-optimism/specs/issues/73) where the L1 fee is calculated in a smart contract instead of native code. This would enable an on chain oracle to take into account the exchange rate of the custom gas token. This oracle could be something like Uniswap TWAP or Chainlink. + +### What's the best way to monitor my custom gas token chain? +It is important to monitor your custom gas token chain to see if your chain's bridge is undercollateralized by checking that the amount of ETH in the `OptimismPortal` is greater or equal to the amount of ETH on the L2. [Chain monitor](https://github.com/ethereum-optimism/optimism/tree/v1.7.4/packages/chain-mon) is one way to actively monitor your custom gas token chain. + +### Can I migrate my chain into being custom gas token? + +If you are already live using `ether` to pay for gas, you cannot become a custom gas token chain. It would require a large migration and chain downtime and it is not a service that we provide. + +Custom gas token hack to standard gas token is possible with architectural changes. L1 and L2 architectural changes are required, messengers and bridges on both sides, OptimismPortal (L1), and SystemConfig (L1). Additional information can be found in the [specs](https://specs.optimism.io/protocol/granite/custom-gas-token.html). + +### Do node operators need to do anything? + +There are no core changes to `op-geth` or `op-node` so the infrastructure that node operators run is exactly the same as any other OP Stack based chain. The differences are encapsulated in the smart contracts, so only the L1 contract deployments and L2 genesis generation need to be done in a particular way. From 29d7fc51db428eb5bf2948f7a89084a6823652e6 Mon Sep 17 00:00:00 2001 From: cpengilly <29023967+cpengilly@users.noreply.github.com> Date: Fri, 24 May 2024 01:27:42 -0700 Subject: [PATCH 4/6] fix linting --- pages/stack/protocol/features/custom-gas-token.mdx | 8 +++++--- words.txt | 2 ++ 2 files changed, 7 insertions(+), 3 deletions(-) diff --git a/pages/stack/protocol/features/custom-gas-token.mdx b/pages/stack/protocol/features/custom-gas-token.mdx index 294a0660c..797de3321 100644 --- a/pages/stack/protocol/features/custom-gas-token.mdx +++ b/pages/stack/protocol/features/custom-gas-token.mdx @@ -25,6 +25,7 @@ When deposited, this L1 ERC-20 token will become the native gas token on the L2 **Caveats chain operators should be aware of:** + * You cannot switch from your custom gas token to another token after the chain is launched. * You will need to manually modify your fee configuration values to properly charge fees for users. * Understand the [constraints required for your chain to be able to join the Superchain](#considerations) when setting the custom gas token for your chain. @@ -69,16 +70,17 @@ The custom token being used must adhere to the following constraints to be able ### What is the Wrapped (ERC-20) Gas Token? -- The `WETH` predeploy at `0x4200000000000000000000000000000000000006` represents the wrapped custom gas token. If you wish to transact with your native gas token as an ERC-20, you can `deposit` and `withdraw` from this contract to wrap and unwrap your token. -- What this means is the asset at the `WETH` predeploy is not `ether` but instead is the wrapped version of your custom gas token. Its an ERC20 token, the `name()` will be `"Wrapped ..."` (whatever the name of your token is). +* The `WETH` predeploy at `0x4200000000000000000000000000000000000006` represents the wrapped custom gas token. If you wish to transact with your native gas token as an ERC-20, you can `deposit` and `withdraw` from this contract to wrap and unwrap your token. +* What this means is the asset at the `WETH` predeploy is not `ether` but instead is the wrapped version of your custom gas token. Its an ERC20 token, the `name()` will be `"Wrapped ..."` (whatever the name of your token is). ### How do I charge fees as the chain operator? The initial release of custom gas token does not have special logic for taking into account the exchange rate between the custom gas token and ether. This logic is nice to have because it requires ether to purchase data availability for Ethereum. If the chain is earning in a custom gas token and spending in ether, then it must earn enough custom gas token such that it can be sold for ether. -For the initial release of custom gas token, the chain operator will need to manage this either out of band or by manually tuning the fee parameters to ensure profitability. A future release may include [L1 Fee Abstraction](https://github.com/ethereum-optimism/specs/issues/73) where the L1 fee is calculated in a smart contract instead of native code. This would enable an on chain oracle to take into account the exchange rate of the custom gas token. This oracle could be something like Uniswap TWAP or Chainlink. +For the initial release of custom gas token, the chain operator will need to manage this either out of band or by manually tuning the fee parameters to ensure profitability. A future release may include [L1 Fee Abstraction](https://github.com/ethereum-optimism/specs/issues/73) where the L1 fee is calculated in a smart contract instead of native code. This would enable an on chain oracle to take into account the exchange rate of the custom gas token. This oracle could be something like Uniswap TWAP or Chainlink. ### What's the best way to monitor my custom gas token chain? + It is important to monitor your custom gas token chain to see if your chain's bridge is undercollateralized by checking that the amount of ETH in the `OptimismPortal` is greater or equal to the amount of ETH on the L2. [Chain monitor](https://github.com/ethereum-optimism/optimism/tree/v1.7.4/packages/chain-mon) is one way to actively monitor your custom gas token chain. ### Can I migrate my chain into being custom gas token? diff --git a/words.txt b/words.txt index 109ea0578..bc2d9b6d4 100644 --- a/words.txt +++ b/words.txt @@ -299,9 +299,11 @@ tility timeseries trustlessly trustrpc +TWAP txfeecap TXPOOL txpool +undercollateralized Unprotect unsubmitted UPNP From b828112d269e7cd1d9a3603e55ba116fedbe7835 Mon Sep 17 00:00:00 2001 From: Kevin Ho Date: Tue, 28 May 2024 21:06:16 -0600 Subject: [PATCH 5/6] update custom gas token docs --- .../management/custom-gas-token.mdx | 39 +++++++++++++------ .../protocol/features/custom-gas-token.mdx | 36 ++++++++--------- 2 files changed, 44 insertions(+), 31 deletions(-) diff --git a/pages/builders/chain-operators/management/custom-gas-token.mdx b/pages/builders/chain-operators/management/custom-gas-token.mdx index c310d14b0..5a9746847 100644 --- a/pages/builders/chain-operators/management/custom-gas-token.mdx +++ b/pages/builders/chain-operators/management/custom-gas-token.mdx @@ -9,8 +9,7 @@ import { Callout, Steps } from 'nextra/components' # How to Run a Custom Gas Token Chain - We do not recommend running a Custom Gas Token chain in production mainnet yet. - This guide is for running testnet chains. The OP Labs team will flag when they have confidence in the security of the implementation code. +The Custom Gas Token feature is a Beta feature of the MIT licensed OP Stack. While it has received initial review from core contributors, it is still undergoing testing, and may have bugs or other issues. This guide provides a walkthrough for chain operators who want to run a custom gas token chain. See the [Custom Gas Token Explainer](/stack/protocol/features/custom-gas-token) for a general overview of this OP Stack feature. @@ -19,28 +18,32 @@ An OP Stack chain that uses the custom gas token feature enables an end user to ### Deploying Your Contracts - * Checkout the [custom gas token branch](https://github.com/ethereum-optimism/optimism/pull/10143) and use the commit to deploy. + * Checkout the [`v2.0.0-beta.1` of the contracts](https://github.com/ethereum-optimism/optimism/tree/op-contracts/v2.0.0-beta.1) and use the commit to deploy. - Be sure to check out this branch or you will not deploy a chain that uses custom gas token! + Be sure to check out this tag or you will not deploy a chain that uses custom gas token! * Update the deploy config in `contracts-bedrock/deploy-config` with new fields: `useCustomGasToken` and `customGasTokenAddress` - * Set `useCustomGasToken` to `true` and the address of the L1 ERC20 token should be in `customGasTokenAddress`. The ERC20 should already be deployed before trying to spin up the custom gas token chain. + * Set `useCustomGasToken` to `true`. If you set `useCustomGasToken` to `false` (it defaults this way), then it will use ETH as the gas paying token. - If you set `useCustomGasToken` to `false` (it defaults this way), then it will use ETH as the gas paying token. - - * Set `customGasTokenAddress` to the contract address of an L1 ERC20 token you wish to use as the gas token on your L2. + * Set `customGasTokenAddress` to the contract address of an L1 ERC20 token you wish to use as the gas token on your L2. The ERC20 should already be deployed before trying to spin up the custom gas token chain. The custom gas token being set must meet the following criteria: + * must be a valid ERC-20 token * the number of decimals on the token MUST be exactly 18 * the name of the token MUST be less than or equal to 32 bytes * symbol MUST be less than or equal to 32 bytes. + * must not be yield-bearing + * cannot be rebasing or have a transfer fee + * must be transferrable only via a call to the token address itself + * must only be able to set allowance via a call to the token address itself + * must not have a callback on transfer, and more generally a user must not be able to make a transfer to themselves revert - You will NOT be able to change the address of the custom gas token if it is already set. + You will NOT be able to change the address of the custom gas token after it is set during deployment. * Deploy the L1 contracts from `contracts-bedrock` using the following command: @@ -59,7 +62,7 @@ An OP Stack chain that uses the custom gas token feature enables an end user to ### Generating L2 Allocs - Be sure to use the same branch that you used to deploy the L1 contracts. + Be sure to use the same tag that you used to deploy the L1 contracts. A forge script is used to generate the L2 genesis. It is a requirement that the L1 contracts have been deployed before generating the L2 genesis, since some L1 contract addresses are embedded into the L2 genesis. @@ -97,9 +100,9 @@ An OP Stack chain that uses the custom gas token feature enables an end user to Ensure that the end to end system is running. - ### Depositing Your Custom Gas Token into Your Chain + ### Depositing Custom Gas Token into the Chain - * To deposit your custom gas token into your chain, you must use the **`OptimismPortalProxy.depositERC20Transaction`** method + * To deposit the custom gas token into the chain, users must use the **`OptimismPortalProxy.depositERC20Transaction`** method * Users MUST first `approve()` the `OptimismPortal` before they can deposit tokens using `depositERC20Transaction`. ``` @@ -112,6 +115,18 @@ An OP Stack chain that uses the custom gas token feature enables an end user to bytes memory _data ) public; ``` + + ### Withdrawing Custom Gas Tokens out of the Chain + + * To withdraw your native custom gas token from the chain, users must use the **`L2ToL1MessagePasser.initiateWithdrawal`** method. Proving and finalizing withdrawals is identical to the process on chains that use ETH as the native gas token. + + ``` + function initiateWithdrawal( + address _target, + uint256 _gasLimit, + bytes memory _data + ) public payable; + ``` ## Next Steps diff --git a/pages/stack/protocol/features/custom-gas-token.mdx b/pages/stack/protocol/features/custom-gas-token.mdx index 797de3321..343881383 100644 --- a/pages/stack/protocol/features/custom-gas-token.mdx +++ b/pages/stack/protocol/features/custom-gas-token.mdx @@ -17,16 +17,17 @@ The Custom Gas Token configuration lets OP Stack chain operators deploy their ch ## Native Gas Tokens -By default, L2 OP Stack chains allow users to deposit ETH from L1 into the chain as the L2 ETH, the native token that can then be used to pay for gas fees. +By default, L2 OP Stack chains allow users to deposit ETH from L1 into the L2 chain as native L2 token that can then be used to pay for gas fees. Chain operators wanted to configure the stack to use a custom token to pay for gas, other than ETH. -With custom gas tokens, chain operators can now set an L1 ERC-20 token address at the time of deploying the contracts of their chain. +With custom gas tokens, chain operators can now set an L1 ERC-20 token address at the time of deploying the contracts of their L2 chain. When deposited, this L1 ERC-20 token will become the native gas token on the L2 and can be used to pay for gas fees. **Caveats chain operators should be aware of:** * You cannot switch from your custom gas token to another token after the chain is launched. + * Existing chains cannot switch to use a custom gas token. A custom token must be configured at the time of chain deployment. * You will need to manually modify your fee configuration values to properly charge fees for users. * Understand the [constraints required for your chain to be able to join the Superchain](#considerations) when setting the custom gas token for your chain. @@ -36,7 +37,7 @@ When deposited, this L1 ERC-20 token will become the native gas token on the L2 This is the general flow of how custom gas tokens work on the OP Stack: * On deployment of an L2 chain, set the address of an L1 token to be used as the gas token. -* When depositing a custom gas token to L2, it mints the native L2 token. +* When depositing the custom gas token to L2, it mints the native L2 token. * Withdrawing the native L2 token results in the unlocking of the custom token on L1. * The native L2 token is used by default to pay for gas fees. @@ -52,13 +53,16 @@ Chain operators get the following benefits by using custom gas tokens: The custom token being used must adhere to the following constraints to be able to join the Superchain: -* Must be a non-yield bearing token (This is a requirement from Legal) -* Must be a valid ERC-20 token -* Must have 18 decimals -* Can't be rebasing or have a transfer fee -* Must only be transferrable via a call to the token address itself -* Must only be able to set allowance via a call to the token address itself -* Must not have a callback on transfer, and more generally a user must not be able to make a transfer to themselves revert +* must be a valid ERC-20 token +* the number of decimals on the token MUST be exactly 18 +* the name of the token MUST be less than or equal to 32 bytes +* symbol MUST be less than or equal to 32 bytes. +* must not be yield-bearing +* cannot be rebasing or have a transfer fee +* must be transferrable only via a call to the token address itself +* must only be able to set allowance via a call to the token address itself +* must not have a callback on transfer, and more generally a user must not be able to make a transfer to themselves revert + ## Next Steps @@ -75,19 +79,13 @@ The custom token being used must adhere to the following constraints to be able ### How do I charge fees as the chain operator? -The initial release of custom gas token does not have special logic for taking into account the exchange rate between the custom gas token and ether. This logic is nice to have because it requires ether to purchase data availability for Ethereum. If the chain is earning in a custom gas token and spending in ether, then it must earn enough custom gas token such that it can be sold for ether. - -For the initial release of custom gas token, the chain operator will need to manage this either out of band or by manually tuning the fee parameters to ensure profitability. A future release may include [L1 Fee Abstraction](https://github.com/ethereum-optimism/specs/issues/73) where the L1 fee is calculated in a smart contract instead of native code. This would enable an on chain oracle to take into account the exchange rate of the custom gas token. This oracle could be something like Uniswap TWAP or Chainlink. +The initial release of custom gas token does not have special logic for taking into account the exchange rate between the custom gas token and ether. Currently, the protocol charges fees for users with scalars on the L1 blob fee and L1 base fee in ETH. Chain operator will be taking user fees in the custom gas token and spending in ether. -### What's the best way to monitor my custom gas token chain? - -It is important to monitor your custom gas token chain to see if your chain's bridge is undercollateralized by checking that the amount of ETH in the `OptimismPortal` is greater or equal to the amount of ETH on the L2. [Chain monitor](https://github.com/ethereum-optimism/optimism/tree/v1.7.4/packages/chain-mon) is one way to actively monitor your custom gas token chain. +For the initial release of custom gas token, the chain operator will need to manage this either out of band or by manually tuning the fee scalar values to capture the exchange rate between ETH and the custom gas token to ensure profitability. A future release may include [L1 Fee Abstraction](https://github.com/ethereum-optimism/specs/issues/73) where the L1 fee is calculated in a smart contract instead of native code. This would enable an on chain oracle to take into account the exchange rate of the custom gas token. ### Can I migrate my chain into being custom gas token? -If you are already live using `ether` to pay for gas, you cannot become a custom gas token chain. It would require a large migration and chain downtime and it is not a service that we provide. - -Custom gas token hack to standard gas token is possible with architectural changes. L1 and L2 architectural changes are required, messengers and bridges on both sides, OptimismPortal (L1), and SystemConfig (L1). Additional information can be found in the [specs](https://specs.optimism.io/protocol/granite/custom-gas-token.html). +If you are already live using `ether` to pay for gas, you cannot become a custom gas token chain. This would likely require a risky, high lift state migration that we would not recommend. ### Do node operators need to do anything? From 872a5667d7e24747ff41540b1772994f687ea6d3 Mon Sep 17 00:00:00 2001 From: Kevin Ho Date: Wed, 29 May 2024 15:21:16 -0600 Subject: [PATCH 6/6] update custom gas token docs w PR feedback --- .../standard-bridge-custom-token.mdx | 2 +- .../management/custom-gas-token.mdx | 21 +++++++++++++++++++ .../protocol/features/custom-gas-token.mdx | 3 ++- 3 files changed, 24 insertions(+), 2 deletions(-) diff --git a/pages/builders/app-developers/tutorials/standard-bridge-custom-token.mdx b/pages/builders/app-developers/tutorials/standard-bridge-custom-token.mdx index 4936f91fe..89cf0a492 100644 --- a/pages/builders/app-developers/tutorials/standard-bridge-custom-token.mdx +++ b/pages/builders/app-developers/tutorials/standard-bridge-custom-token.mdx @@ -9,7 +9,7 @@ import { Callout, Steps } from 'nextra/components' # Bridging Your Custom ERC-20 Token Using the Standard Bridge -**This tutorial is for developers who want to bridge a new ERC-20 token to an OP Stack chain.** +**This tutorial is for developers who want to bridge a new ERC-20 token to an OP Stack chain. This is not related to the "Custom Gas Token" feature for new OP Stack chains** If you want to bridge existing tokens, you can skip to the tutorial on [Bridging ERC-20 tokens with the Optimism SDK](./cross-dom-bridge-erc20). diff --git a/pages/builders/chain-operators/management/custom-gas-token.mdx b/pages/builders/chain-operators/management/custom-gas-token.mdx index 5a9746847..92d80bde9 100644 --- a/pages/builders/chain-operators/management/custom-gas-token.mdx +++ b/pages/builders/chain-operators/management/custom-gas-token.mdx @@ -41,6 +41,7 @@ An OP Stack chain that uses the custom gas token feature enables an end user to * must be transferrable only via a call to the token address itself * must only be able to set allowance via a call to the token address itself * must not have a callback on transfer, and more generally a user must not be able to make a transfer to themselves revert + * a user must not be able to make a transfer have unexpected side effects You will NOT be able to change the address of the custom gas token after it is set during deployment. @@ -100,6 +101,26 @@ An OP Stack chain that uses the custom gas token feature enables an end user to Ensure that the end to end system is running. + ### Validating your deployment + + This calls the `WETH` predeploy which should be considered wrapped native asset in the context of custom gas token. It should return the name of the token prefixed by `"Wrapped "` + + ```bash + cast call --rpc-url $L2_ETH_RPC_URL 0x4200000000000000000000000000000000000006 'name()(string)' + ``` + + This calls the `L1Block` predeploy should return `true`. + + ```bash + cast call --rpc-url $L2_ETH_RPC_URL 0x4200000000000000000000000000000000000015 'isCustomGasToken()(bool) + ``` + + This calls the L1 `SystemConfig` contract and should return `true`. + + ```bash + cast call --rpc-url $L1_ETH_RPC_URL 'isCustomGasToken()(bool) + ``` + ### Depositing Custom Gas Token into the Chain * To deposit the custom gas token into the chain, users must use the **`OptimismPortalProxy.depositERC20Transaction`** method diff --git a/pages/stack/protocol/features/custom-gas-token.mdx b/pages/stack/protocol/features/custom-gas-token.mdx index 343881383..415e1cfa9 100644 --- a/pages/stack/protocol/features/custom-gas-token.mdx +++ b/pages/stack/protocol/features/custom-gas-token.mdx @@ -62,12 +62,13 @@ The custom token being used must adhere to the following constraints to be able * must be transferrable only via a call to the token address itself * must only be able to set allowance via a call to the token address itself * must not have a callback on transfer, and more generally a user must not be able to make a transfer to themselves revert +* a user must not be able to make a transfer have unexpected side effects + ## Next Steps * Ready to get started? Read our guide on how to [deploy your custom gas token chain](/builders/chain-operators/management/custom-gas-token). -* For bridges or developers building on a custom gas token chain, read our tutorial on [depositing custom gas tokens into a chain](/builders/app-developers/tutorials/standard-bridge-custom-token). * For more info about how the custom gas token feature works under the hood, [check out the specs](https://specs.optimism.io/protocol/granite/custom-gas-token.html). ## FAQs