specs: Add deposit gas metering spec (#2679)

* Deposit Fee Spec

* Update guaranteed-gas-market.md

* Update guaranteed-gas-market.md

* Update guaranteed-gas-market.md

* PR Fixes

* PR Changes
Co-authored-by: mergify[bot] <37929162+mergify[bot]@users.noreply.github.com>

specs/deposits.md

@@ -50,9 +50,11 @@ transaction types:
 1. They are derived from Layer 1 blocks, and must be included as part of the protocol.
 2. They do not include signature validation (see [User-Deposited Transactions][user-deposited]
    for the rationale).
+3. They buy their L2 gas on L1 and, as such, the L2 gas is not refundable.
 
-We define a new [EIP-2718] compatible transaction type with the prefix `0x7E`, and the following
-fields (rlp encoded in the order they appear here):
+We define a new [EIP-2718] compatible transaction type with the prefix `0x7E`, and then a versioned
+byte sequence. The first version has `0x00` as the version byte and then as the following fields
+(rlp encoded in the order they appear here):
 
 [EIP-2718]: https://eips.ethereum.org/EIPS/eip-2718
 
@@ -75,6 +77,9 @@ Picking a high identifier minimizes the risk that the identifier will be used be
 transaction type on the L1 chain in the future. We don't pick `0x7F` itself in case it becomes used
 for a variable-length encoding scheme.
 
+We chose to add a version field to the deposit transaction to enable the protocol to upgrade the deposit
+transaction type without having to take another [EIP-2718] transaction type selector.
+
 ### Source hash computation
 
 The `sourceHash` of a deposit transaction is computed based on the origin:
@@ -138,6 +143,11 @@ follows:
 - `context.gas` set to `gasLimit`
 - `context.value` set to `sendValue`
 
+No gas is bought on L2 and no refund is provided. The gas used for the deposit is subtracted from
+the gas pool on L2. Gas usage exactly matches other transaction types (including intrinsic gas).
+If a deposit runs out of gas or has some other failure, the mint will succeed and the nonce of the
+account will be increased, but no other state transition will occur.
+
 #### Nonce Handling
 
 Despite the lack of signature validation, we still increment the nonce of the `from` account when a
@@ -163,7 +173,7 @@ This transaction MUST have the following values:
    contract][predeploy]).
 3. `mint` is `0`
 4. `value` is `0`
-5. `gasLimit` is set to the maximum available.
+5. `gasLimit` is set to 75,000.
 6. `data` is an [ABI] encoded call to the [L1 attributes predeployed contract][predeploy]'s
    `setL1BlockValues()` function with correct values associated with the corresponding L1 block (cf.
    [reference implementation][l1-attr-ref-implem]).
@@ -244,6 +254,10 @@ feed contract][deposit-feed-contract] on L1.
 The deposit contract is deployed to L1. Deposited transactions are derived from the values in
 the `TransactionDeposited` event(s) emitted by the deposit contract.
 
+The deposit contract is responsible for maintaing the [guaranteed gas market](./guaranteed-gas-market.md),
+charging deposits for gas to be used on L2, and ensuring that the total amount of guaranted
+gas in a single L1 block does not exceed the L2 block gas limit.
+
 The deposit contract handles two special cases:
 
 1. A contract creation deposit, which is indicated by setting the `isCreation` flag to `true`.

specs/glossary.md

@@ -15,6 +15,7 @@
   - [Receipt](#receipt)
   - [Transaction Type](#transaction-type)
   - [Fork Choice Rule](#fork-choice-rule)
+  - [Priority Gas Auction](#priority-gas-auction)
 - [Sequencing](#sequencing)
   - [Sequencing window](#sequencing-window)
   - [Sequencing epoch](#sequencing-epoch)
@@ -137,11 +138,20 @@ Different transaction types can contain different payloads, and be handled diffe
 The fork choice rule is the rule used to determined which block is to be considered as the head of a blockchain. On L1,
 this is determined by the proof of stake rules.
 
-L2 also has a fork choice rule, although the rules vary depending on wether we want the sequencer-confirmed head, the
+L2 also has a fork choice rule, although the rules vary depending on whether we want the sequencer-confirmed head, the
 on-chain-confirmed head, or the on-chain-finalized head.
 
 > TODO: define and link to those concepts
 
+## Priority Gas Auction
+
+Transactions in ethereum are ordered by the price that the transaction pays to the miner. Priority Gas Auctions
+(PGAs) occur when multiple parties are competing to be the first transaction in a block. Each party continuously
+updates the gas price of their transaction. PGAs occur when there is value in submitting a transaction before other
+parties (like being the first deposit or submitting a deposit before there is not more guaranteed gas remaining).
+PGAs tend to have negative externalities on the network due to a large amount of transactions being submitted in a
+very short amount of time.
+
 ------------------------------------------------------------------------------------------------------------------------
 
 # Sequencing

specs/guaranteed-gas-market.md

+# Guaranteed Gas Fee Market
+
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+**Table of Contents**
+
+- [Gas Stipend](#gas-stipend)
+- [Limiting Guaranteed Gas](#limiting-guaranteed-gas)
+- [Rationale for burning L1 Gas](#rationale-for-burning-l1-gas)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
+[Deposited transaction](./glossary.md#deposited-transaction) are transactions on L2 that are
+initiated on L1. The gas that they use on L2 is bought on L1 via a gas burn or a direct payment. We
+maintain a fee market and hard cap on the amount of gas provided to all deposits in a single L1
+block.
+
+The gas provided to deposited transactions is sometimes called "guaranteed gas". The gas provided to
+deposited transactions is unique in the regard that it is not refundable. It cannot be refunded as
+it is sometimes paid for with a gas burn and there may not be any ETH left to refund.
+
+The **guaranteed gas** is composed of a gas stipend, and of any guaranteed gas the user would like
+to purchase (on L1) on top of that.
+
+Guaranteed gas on L2 is bought in the following manner. An L2 gas price is calculated via an
+EIP-1559-style algorithm. The total amount of ETH required to buy that gas is then calculated as
+(`guaranteed gas * L2 deposit basefee`). The contract then accepts that amount of ETH (in a future
+upgrade) or (only method right now), burns an amount of L1 gas that corresponds to the L2 cost
+(`L2 cost / L1 Basefee`). The L2 gas price for guaranteed gas is not synchronized with the basefee
+on L2 and will likely be different.
+
+## Gas Stipend
+
+To offset the gas spent on the deposit event, we credit `gas spent * L1 basefee` ETH to the cost of
+the L2 gas, where `gas spent` is the amount of L1 gas spent processing the deposit. If the ETH value
+of this credit is greater than the ETH value of the requested guaranteed gas
+(`requested guaranteed gas * L2 gas price`), no L1 gas is burnt.
+
+## Limiting Guaranteed Gas
+
+The total amount of guaranteed gas that can be bought in a single L1 block must be limited to
+prevent a denial of service attack against L2 as well as ensure the total amount of guaranteed gas
+stays below the L2 block gas limit.
+
+We set a guaranteed gas limit of 8,000,000 gas per L1 block and a target of 2,000,000 gas per L1
+block. These numbers enabled occasional large transactions while staying within our target and
+maximum gas usage on L2.
+
+Because the amount of guaranteed L2 gas that can be purchased in a single block is now limited,
+we implement an EIP-1559-style fee market to reduce congestion on deposits. By setting the limit
+at a multiple of the target, we enable deposits to temporarily use more L2 gas at a greater cost.
+
+```python
+# Pseudocode to update the L2 Deposit Basefee and cap the amount of guaranteed gas
+# bought in a block. Calling code must handle the gas burn and validity checks on
+# the ability of the account to afford this gas.
+BASE_FEE_MAX_CHANGE_DENOMINATOR = 8
+ELASTICITY_MULTIPLIER = 4
+MAX_RESOURCE_LIMIT = 8,000,000
+TARGET_RESOURCE_LIMIT = MAX_RESOURCE_LIMIT / ELASTICITY_MULTIPLIER
+MINIMUM_BASEFEE=10000
+
+# prev_basefee is a u128, prev_bought_gas and prev_num are u64s
+prev_basefee, prev_bought_gas, prev_num = <values from previous update>
+now_num = block.number
+
+# Clamp the full basefee to a specific range. The minimum value in the range should be around 100-1000
+# to enable faster responses in the basefee. This replaces the `max` mechanism in the ethereum 1559
+# implementation (it also serves to enable the basefee to increase if it is very small).
+def clamp(v: i256, min: u128, max: u128) -> u128:
+    if v < i256(min):
+        return min
+    elif v > i256(max):
+        return max
+    else:
+        return u128(v)
+
+# If this is a new block, update the basefee and reset the total gas
+# If not, just update the total gas
+if prev_num == now_num:
+    now_basefee = prev_basefee
+    now_bought_gas = prev_bought_gas + requested_gas
+elif prev_num != now_num :
+    # Width extension and conversion to signed integer math
+    gas_used_delta = int128(prev_bought_gas) - int128(TARGET_RESOURCE_LIMIT)
+    # Use truncating (round to 0) division - solidity's default.
+    # Sign extend gas_used_delta & prev_basefee to 256 bits to avoid overflows here.
+    base_fee_per_gas_delta = prev_basefee * gas_used_delta / TARGET_RESOURCE_LIMIT / BASE_FEE_MAX_CHANGE_DENOMINATOR
+    now_basefee_wide = prev_basefee + base_fee_per_gas_delta
+
+    now_basefee = clamp(now_basefee_wide, min=MINIMUM_BASEFEE, max=UINT_64_MAX_VALUE)
+    now_bought_gas =  requested_gas
+
+# If we skipped multiple blocks between the previous block and now update the basefee again.
+# This is not exactly the same as iterating the above function, but quite close for reasonable
+# gas target values. It is also constant time wrt the number of missed blocks which is important
+# for keeping gas usage stable.
+if prev_num + 1 < now_num:
+    n = now_num - prev_num - 1
+    # Apply 7/8 reduction to prev_basefee for the n empty blocks in a row.
+    now_basefee_wide = prev_basefee * pow(1-(1/BASE_FEE_MAX_CHANGE_DENOMINATOR), n)
+    now_basefee = clamp(now_basefee_wide, min=MINIMUM_BASEFEE, max=UINT_64_MAX_VALUE)
+
+require(now_bought_gas < MAX_RESOURCE_LIMIT)
+
+store_values(now_basefee, now_bought_gas, now_num)
+```
+
+## Rationale for burning L1 Gas
+
+If we collect ETH directly to pay for L2 gas, every (indirect) caller of the deposit function will need
+to be marked with the payable selector. This won't be possible for many existing projects. Unfortunately
+this is quite wasteful. As such, we will provide two options to buy L2 gas:
+
+1. Burn L1 Gas
+2. Send ETH to the Optimism Portal (Not yet supported)
+
+The payable version (Option 2) will likely have discount applied to it (or conversely, #1 has a
+premium applied to it).
+
+For the initial release of bedrock, only #1 is supported.