diff --git a/specs/SUMMARY.md b/specs/SUMMARY.md index 44dd04ecf..c8cc681f5 100644 --- a/specs/SUMMARY.md +++ b/specs/SUMMARY.md @@ -50,6 +50,7 @@ - [Granite](./protocol/granite/overview.md) - [Execution Engine](./protocol/granite/exec-engine.md) - [Derivation](./protocol/granite/derivation.md) + - [Holocene](./protocol/holocene/overview.md) - [Governance]() - [Governance Token](./governance/gov-token.md) - [Experimental]() @@ -60,13 +61,14 @@ - [Messaging](./interop/messaging.md) - [Predeploys](./interop/predeploys.md) - [Sequencer](./interop/sequencer.md) - - [Derivation](./interop/derivation.md) - [Verifier](./interop/verifier.md) - [Rollup Node P2P](./interop/rollup-node-p2p.md) - [Fault Proof](./interop/fault-proof.md) - [Upgrade](./interop/upgrade.md) - [Token Bridging](./interop/token-bridging.md) - [SuperchainWETH](./interop/superchain-weth.md) + - [Derivation](./interop/derivation.md) + - [Transaction Pool](./interop/tx-pool.md) - [OP Stack Manager](./experimental/op-stack-manager.md) - [Governance Token](./experimental/gov-token.md) - [Glossary](./glossary.md) diff --git a/specs/interop/derivation.md b/specs/interop/derivation.md index 6e0940d89..c0e9a3339 100644 --- a/specs/interop/derivation.md +++ b/specs/interop/derivation.md @@ -6,6 +6,9 @@ - [Overview](#overview) - [Deposit Context](#deposit-context) + - [Opening the deposit context](#opening-the-deposit-context) + - [Closing the deposit context](#closing-the-deposit-context) + - [Deposits-complete Source-hash](#deposits-complete-source-hash) - [Security Considerations](#security-considerations) - [Gas Considerations](#gas-considerations) @@ -20,21 +23,66 @@ A deposit context is scoped to a single block, commencing with the execution of and concluding immediately after the execution of the final deposited transaction within that block. As such, there is exactly one deposit context per block. -A deposit context is created by two operations: +The order of deposit transactions occurs as follows: -- An L1 attributes transaction that sets `isDeposit = true` on the `L1Block` contract. -This instantiates a deposit context for the current block. -- An L1 attributes transaction that sets `isDeposit = false`. This destroys the existing deposit context. +1. L1 attributes transaction, [opening the deposit context](#opening-the-deposit-context). +2. User deposits (if any). +3. L1 attributes transaction, [closing the deposit context](#closing-the-deposit-context). +4. During upgrades, additional deposits, inserted by derivation, may follow after the above. + See [upgrade specification](./upgrade.md). -These two operations wrap user deposits, such that `isDeposit = true` occurs during the first L1 attributes -transaction and `isDeposit = false` occurs immediately after the last user deposit, +The L1 attributes operations wrap user deposits, +such that `isDeposit = true` occurs during the first L1 attributes transaction +and `isDeposit = false` occurs immediately after the last user deposit, if any exists, or after the first L1 attributes transaction if there are no user deposits. -The order of deposit transactions occurs as follows: +#### Opening the deposit context + +A new `L1Block` predeploy function is introduced to set the L1 attributes: `setL1BlockValuesIsthmus()`. + +The block-attributes contents are unchanged from the previous fork. +See [Ecotone L1 attributes specifications](../protocol/ecotone/l1-attributes.md), +and [Holocene specifications](../protocol/holocene/overview.md). + +In addition to the setting L1 block attributes, the `setL1BlockValuesIsthmus` function +now sets `isDeposit = true` on the `L1Block` predeploy contract. + +This instantiates a deposit context for the current block. + +#### Closing the deposit context + +A new `L1Block` predeploy function is introduced to close the deposit context: `depositsComplete()`. + +This sets `isDeposit = false` in the `L1Block` predeploy contract. + +This function is called by a new L1 block system transaction. +This transaction MUST have the following values: + +1. `from` is `0xdeaddeaddeaddeaddeaddeaddeaddeaddead0001`, the address of the + [L1 Attributes depositor account](../protocol/deposits.md#l1-attributes-depositor-account). +2. `to` is `0x4200000000000000000000000000000000000015`, the address of the + [L1 attributes predeployed contract](../protocol/deposits.md#l1-attributes-predeployed-contract). +3. `mint` is `0`. +4. `value` is `0`. +5. `gasLimit` is set `36000` gas, to cover intrinsic costs, processing costs, and margin for change. +6. `isSystemTx` is `false`. +7. `data` is set to `0xe32d20bb`, the 4-byte selector of `depositsComplete()`. + This closes the existing deposit context. +8. `sourceHash` is computed with a new deposit source-hash domain, see below. + +##### Deposits-complete Source-hash + +The source hash is [computed](../protocol/deposits.md#source-hash-computation) alike to that +of the "L1 attributes deposited" deposit that opens the deposit context. +The one difference is the source-hash domain: `3` (instead of `1`). + +The source-hash is thus computed as: +`keccak256(bytes32(uint256(3)), keccak256(l1BlockHash, bytes32(uint256(seqNumber))))`. -1. L1 attributes transaction calling [`setL1BlockValuesIsthmus()`](../protocol/ecotone/l1-attributes.md). -1. User deposits -1. L1 attributes transaction calling [`depositsComplete()`](../protocol/ecotone/l1-attributes.md) +Where `l1BlockHash` refers to the L1 block hash of which the info attributes are deposited. +And `seqNumber = l2BlockNum - l2EpochStartBlockNum`, +where `l2BlockNum` is the L2 block number of the inclusion of the deposit tx in L2, +and `l2EpochStartBlockNum` is the L2 block number of the first L2 block in the epoch. ## Security Considerations diff --git a/specs/interop/overview.md b/specs/interop/overview.md index d781bc63d..55efce9e1 100644 --- a/specs/interop/overview.md +++ b/specs/interop/overview.md @@ -42,3 +42,5 @@ they need not be the same entity in practice. - [Upgrade](./upgrade.md): Superchain upgrade process to activate Interop. - [Token Bridging](./token-bridging.md): sending ERC20 tokens between chains - [Superchain WETH](./superchain-weth.md): Making ETH interoperable. +- [Derivation](./derivation.md): Changes to derivation of block-attributes. +- [Transaction Pool](./tx-pool.md): Transaction-pool validation of transactions. diff --git a/specs/interop/tx-pool.md b/specs/interop/tx-pool.md index f66db0f59..c933faf73 100644 --- a/specs/interop/tx-pool.md +++ b/specs/interop/tx-pool.md @@ -5,6 +5,7 @@ **Table of Contents** - [Message validation](#message-validation) +- [System deposits transaction margin](#system-deposits-transaction-margin) - [Security Considerations](#security-considerations) - [Mempool Denial of Service](#mempool-denial-of-service) @@ -51,6 +52,21 @@ The sequencer MAY choose to demote messages which are invalid but can still tech Transactions with invalid message-dependencies MUST NOT be included in block-building, and should thus be dropped from the transaction-pool. +## System deposits transaction margin + +The [Deposit context closing transaction](./derivation.md#closing-the-deposit-context) requires +a small margin of additional EVM gas to be available for system operations. + +The transaction-pool should filter out L2 transactions that spend more than the +gas limit, minus the gas spent on system transactions. +This ensures that the transaction can be included in a valid L2 block, +and does not get stuck in the transaction pool. + +A notion of an "effective gas limit", that subtracts 100,000 gas from the regular gas limit, +should be maintained in the transaction pool. +This leaves sufficient gas for the L1 attributes transaction (under 45,000 gas), +the new deposit-context closing transaction (under 36,000 gas), and margin for error / change. + ## Security Considerations ### Mempool Denial of Service diff --git a/specs/protocol/holocene/overview.md b/specs/protocol/holocene/overview.md index 568348754..359ca6d49 100644 --- a/specs/protocol/holocene/overview.md +++ b/specs/protocol/holocene/overview.md @@ -16,6 +16,4 @@ This document is not finalized and should be considered experimental. ## Consensus Layer -- [Interop](../interop/overview.md) - ## Smart Contracts