specs: Add deposit gas metering spec

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)
@@ -139,11 +140,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 are 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

@@ -0,0 +1,137 @@
+# 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)
+- [1559 Fee Market](#1559-fee-market)
+  - [Exponent Based Fee Reduction](#exponent-based-fee-reduction)
+- [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 a 1559
+style gas market. The total amount of ETH required to buy that gas is then calculated
+(`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`).
+
+## Gas Stipend
+
+To offset the gas spent on the deposit event, we credit the amount of gas spent on the metering step
+times the current basefee to the cost of the L2 gas. The amount of gas is selected to represent the
+cost to the user. If the ETH price of the gas (gas times current L1 baseefee) is greater than the
+requested guaranteed gas times the 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 allow the total amount of guaranteed gas
+to be below the L2 block gas limit.
+
+We set a guaranteed gas limit of 2,500,000 gas per L1 block. This corresponds to the L2 gas target
+that we expect.
+
+## 1559 Fee Market
+
+To reduce [Priority Gas Auctions](./glossary.md#priority-gas-auction) and accurately price gas, we
+implement a 1559 style fee market on L1 with the following pseudocode. We also use this opporunity
+to place a hard limit on the amount of guaranteed gas that is provided.
+
+```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 = load_and_unpack_storage()
+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 :
+    # New formula
+    # 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.
+# TODO: Update this to a fixed point exponentiation for constant time results. This loop is currently
+# bounded to take no more than 12 iterations to exit.
+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)
+
+
+pack_and_store(now_basefee, now_bought_gas, now_num)
+```
+
+### Exponent Based Fee Reduction
+
+When there are stretches where no deposits are executed on L1, the basefee should be decaying, but
+is not. If there is the case that the basefee spiked, this mechanism is needed to enable a more
+accurate decay. It uses exponentiation to run in constant (relative to the number of missed blocks)
+gas.
+
+The current loop based approach will always converge in no more than 12 steps, however it is possible
+to go to a loopless form (with slightly more error), but adpoting a fixed point exponentiation
+algorithm.
+
+## Rationale for burning L1 Gas
+
+If we collect ETH directly we need to add the payable selector. Some projects are not able to do
+this. The alternative is to burn L1 gas. Unfortunately this is quite wastefull. As such, we provide
+two options to buy L2 gas:
+
+1. Burn L1 Gas 2. Send ETH to the Optimism Portal
+
+The payable version (Option 2) will likely have discout applied to it (or conversly, #1 has a
+premium applied to it).
+
+For the initial release of bedrock, only #1 is supported.