Merge pull request #820 from ethereum-optimism/qbzzt/230628-wallet-ba…

…sefee

feat(wallet-dev, wallet-upgrade): Explain base fee better

src/docs/developers/bedrock/wallet-upgrade.md

@@ -37,15 +37,43 @@ If not, use [`eth_getBlockByNumber`](https://docs.alchemy.com/reference/eth-getb
 
 ## Transaction fees
 
+In OP Mainnet (and most other OP Stack chain) transaction fees include both an [L1 data fee](../build/transaction-fees.md#estimating-the-l1-data-fee) and an [L2 execution fee](../build/transaction-fees.md#the-l2-execution-fee). 
+To display the entire estimated cost of a transaction to your users we recommend you [use the SDK](https://github.com/ethereum-optimism/optimism-tutorial/tree/main/sdk-estimate-gas). 
+
 In Bedrock we support [EIP 1559](https://eips.ethereum.org/EIPS/eip-1559).
 Therefore, the L2 execution fee is composed of two components: a fixed (per-block) base fee and a user selected priority fee.
 
-To enable your users to select a priority fee, you can [build a priority fee estimator]
-(https://docs.alchemy.com/docs/how-to-build-a-gas-fee-estimator-using-eip-1559).
+
+### Base fee
+
+[The EIP 1559 parameters](./differences.md#eip-1559) have different values in OP Mainnet (and most other OP Stack chain) than those on L1 Ethereum.
+As a result, in every block the base fee can be between 98% and 110% of the previous value. 
+As blocks are produced every two seconds, the base fee can be between 54% and 1,745% of the value a minute earlier.
+If it takes the user fourteen seconds to approve the transaction in the wallet, the base fee can almost double in that time.
+
+The base fee specified in the transaction is not necessarily the base fee that the user will pay, *it is merely an upper limit to that amount*.
+In most cases, it makes sense to specify a much higher base fee than the current value, to ensure acceptance. 
+
+For example, as I'm writing this, ETH is about $2000, and a cent is about 5000 gwei. 
+Assuming 20% of a cent is an acceptable base fee for a transaction, and that the transaction is a big 5,000,000 gas one (at the target block size), this gives us a base fee of 200,000 wei. 
+That would be the value to put in the transaction, even though the L2 base fee (as I'm writing this) is 2,420 wei. 
+
+::: info Up to date information
+
+You can get the current L2 base fee [in the gas tracker dashboard](https://optimism.io/gas-tracker).
+
+:::
+
+
+### Priority fee
+
+In contrast to the base fee, the priority fee in the transaction is the amount that the user pays, and therefore it makes sense to keep it as low as possible.
+To enable your users to select a priority fee, you can [build a priority fee estimator](https://docs.alchemy.com/docs/how-to-build-a-gas-fee-estimator-using-eip-1559).
 If you already have estimating code you use for L1 Ethereum, you can just use that.
 
 Note that on OP Mainnet the priority fee tends to be very low. 
-As I am writing this, a priority fee of 0.0002 gwei is sufficient ([see here](https://optimism.io/gas-tracker) to get the current values).
+As I am writing this, a priority fee of 500 wei is sufficient ([see here](https://optimism.io/gas-tracker) to get the current values).
+
+
 
-To display the entire estimated cost of a transaction we recommend you [use the SDK](https://github.com/ethereum-optimism/optimism-tutorial/tree/main/sdk-estimate-gas). 
 

src/docs/guides/wallet-dev.md

@@ -5,7 +5,7 @@ lang: en-US
 
 ## Overview
 
-This guide is intended for wallet developers who want to give their users the ability to send transactions on OP Mainnet.
+This guide is intended for wallet developers who want to give their users the ability to send transactions on OP Mainnet (most other OP Stack chains behave similarly).
 OP Mainnet generally behaves like any other EVM-based chain with the exception of minor discrepancies related to [transaction fees](#transaction-fees).
 These fee discrepancies are an inherent result of the fact that OP Mainnet is a Layer 2 blockchain network that must publish transaction data to Ethereum.
 
@@ -44,28 +44,50 @@ We're still working on the tooling to easily detect when a given transaction has
 For the moment, we recommend wallets consider transactions final after they are "Sequencer Confirmed".
 Transactions are considered "Sequencer Confirmed" as soon as their transaction receipt shows at least one confirmation.
 
-## Transaction Fees
 
-We aim to be [EVM equivalent](https://medium.com/ethereum-optimism/introducing-evm-equivalence-5c2021deb306), meaning we aim to minimize the differences between OP Mainnet and Ethereum.
-You can see a summary of the few differences between OP Mainnet and Ethereum [here](../developers/build/differences.md).
-One of the most important discrepancies can be found within OP Mainnet's fee model.
-As a wallet developer, you **must** be aware of this difference.
 
-### Estimating total fees
+## Transaction fees
 
-Most of the cost of a transaction on OP Mainnet comes from the cost of publishing the transaction to Ethereum.
-This publication step is what makes OP Mainnet a Layer 2 blockchain.
-Unlike with the standard execution gas fee, users cannot specify a particular gas price or gas limit for this portion of their transaction cost.
-Instead, this fee is automatically deducted from the user's ETH balance on OP Mainnet when the transaction is executed.
+In OP Mainnet transaction fees include both an [L1 data fee](../developers/build/transaction-fees.md#estimating-the-l1-data-fee) and an [L2 execution fee](../developers/build/transaction-fees.md#the-l2-execution-fee). 
+To display the entire estimated cost of a transaction to your users we recommend you [use the SDK](https://github.com/ethereum-optimism/optimism-tutorial/tree/main/sdk-estimate-gas).
+We **highly recommend** displaying fees on OP Mainnet (and any other OP Stack chain that uses the same mechanism) as one unified fee to minimize user confusion.
 
-[You can read more about this subject here](../developers/build/transaction-fees.md),
-or use [this tutorial](https://github.com/ethereum-optimism/optimism-tutorial/tree/main/sdk-estimate-gas).
-The total fee paid by a transaction will be a combination of the normal fee estimation formula (`gasPrice * gasLimit`) in addition to the estimated L1 fee.
 
-### Displaying fees
+In Bedrock we support [EIP 1559](https://eips.ethereum.org/EIPS/eip-1559).
+Therefore, the L2 execution fee is composed of two components: a fixed (per-block) base fee and a user selected priority fee.
+
+
+### Base fee
+
+[The EIP 1559 parameters](../developers/bedrock/differences.md#eip-1559) have different values in OP Mainnet (and many other OP Stack chains) than those on L1 Ethereum.
+As a result, in every block the base fee can be between 98% and 110% of the previous value. 
+As blocks are produced every two seconds, the base fee can be between 54% and 1,745% of the value a minute earlier.
+If it takes the user fourteen seconds to approve the transaction in the wallet, the base fee can almost double in that time.
+
+The base fee specified in the transaction is not necessarily the base fee that the user will pay, *it is merely an upper limit to that amount*.
+In most cases, it makes sense to specify a much higher base fee than the current value, to ensure acceptance. 
+
+For example, as I'm writing this, ETH is about $2000, and a cent is about 5000 gwei. 
+Assuming 20% of a cent is an acceptable base fee for a transaction, and that the transaction is a big 5,000,000 gas one (at the target block size), this gives us a base fee of 200,000 wei. 
+That would be the value to put in the transaction, even though the L2 base fee (as I'm writing this) is 2,420 wei. 
+
+::: info Up to date information
+
+You can get the current L2 base fee [in the gas tracker dashboard](https://optimism.io/gas-tracker).
+
+:::
+
+
+### Priority fee
+
+In contrast to the base fee, the priority fee in the transaction is the amount that the user pays, and therefore it makes sense to keep it as low as possible.
+To enable your users to select a priority fee, you can [build a priority fee estimator](https://docs.alchemy.com/docs/how-to-build-a-gas-fee-estimator-using-eip-1559).
+If you already have estimating code you use for L1 Ethereum, you can just use that.
+
+Note that on OP Mainnet the priority fee tends to be very low. 
+As I am writing this, a priority fee of 500 wei is sufficient ([see here](https://optimism.io/gas-tracker) to get the current values).
+
 
-We **highly recommend** displaying fees on OP Mainnet as one unified fee to minimize user confusion.
-You can do this by combining both portions of the fee (the L2 execution fee and the L1 data fee) into a single value presented to the end user.
 
 ### Sending "max" ETH
 
@@ -75,4 +97,4 @@ You **MUST** deduct both the L2 execution fee and the L1 data fee or the charged
 
 ### Displaying the gas prices
 
-If you want to display the current gas prices, you can use [`eth_gasPrice`](https://docs.alchemy.com/reference/eth-gasprice).
+If you want to display the current gas prices, you can use [`eth_gasPrice`](https://docs.alchemy.com/reference/eth-gasprice).