diff --git a/specs/SUMMARY.md b/specs/SUMMARY.md index 3bfcac7e2..97c3326a5 100644 --- a/specs/SUMMARY.md +++ b/specs/SUMMARY.md @@ -39,6 +39,8 @@ - [Delta](./protocol/delta/overview.md) - [Span Batches](./protocol/delta/span-batches.md) - [Ecotone](./protocol/ecotone/overview.md) + - [Derivation](./protocol/ecotone/derivation.md) + - [L1 attributes](./protocol/ecotone/l1-attributes.md) - [Fjord](./protocol/fjord/overview.md) - [Execution Engine](./protocol/fjord/exec-engine.md) - [Derivation](./protocol/fjord/derivation.md) @@ -53,6 +55,7 @@ - [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) diff --git a/specs/interop/derivation.md b/specs/interop/derivation.md new file mode 100644 index 000000000..1727f2d93 --- /dev/null +++ b/specs/interop/derivation.md @@ -0,0 +1,52 @@ +# Derivation + + + +**Table of Contents** + +- [Overview](#overview) + - [Deposit Context](#deposit-context) + - [Gas Considerations](#gas-considerations) +- [Security Considerations](#security-considerations) + + + +## Overview + +This is an experimental section and may be changed in the future. It is not required +for the initial release. + +### Deposit Context + +Derivation is extended to create **deposit contexts**, which signifies the execution of a depositing transaction. +A deposit context is scoped to a single block, commencing with the execution of the first deposited transaction +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: + +- 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. + +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, +if any exists, or after the first L1 attributes transaction if there are no user deposits. + +The order of deposit transactions occurs as follows: + +1. L1 attributes transaction calling [`setL1BlockValuesInterop()`](../protocol/ecotone/l1-attributes.md). +1. User deposits +1. L1 attributes transaction calling [`depositsComplete()`](../protocol/ecotone/l1-attributes.md) + +### Gas Considerations + +There must be sufficient gas available in the block to destroy deposit context. +There's no guarantee on the minimum gas available for the second L1 attributes transaction as the block +may be filled by the other deposit transactions. As a consequence, a deposit context may spill into multiple blocks. + +This will be fixed in the future. + +## Security Considerations + +TODO diff --git a/specs/interop/predeploys.md b/specs/interop/predeploys.md index 0ab0062c0..08386a90f 100644 --- a/specs/interop/predeploys.md +++ b/specs/interop/predeploys.md @@ -12,6 +12,7 @@ - [Interop Start Timestamp](#interop-start-timestamp) - [`ExecutingMessage` Event](#executingmessage-event) - [Reference implementation](#reference-implementation) + - [Deposit Handling](#deposit-handling) - [`Identifier` Getters](#identifier-getters) - [L2ToL2CrossDomainMessenger](#l2tol2crossdomainmessenger) - [`relayMessage` Invariants](#relaymessage-invariants) @@ -40,6 +41,9 @@ - [L1Block](#l1block) - [Static Configuration](#static-configuration) - [Dependency Set](#dependency-set) + - [Deposit Context](#deposit-context) + - [`isDeposit()`](#isdeposit) + - [`depositsComplete()`](#depositscomplete) - [OptimismMintableERC20Factory](#optimismmintableerc20factory) - [OptimismMintableERC20](#optimismmintableerc20) - [Updates](#updates) @@ -182,6 +186,15 @@ function executeMessage(Identifier calldata _id, address _target, bytes calldata Note that the `executeMessage` function is `payable` to enable relayers to earn in the gas paying asset. +### Deposit Handling + +Any call to the `CrossL2Inbox` that would emit an `ExecutingMessage` event will reverts +if the call is made in a [deposit context](./derivation.md#deposit-context). +The deposit context status can be determined by callling `isDeposit` on the `L1Block` contract. + +In the future, deposit handling will be modified to be more permissive. +It will revert only in specific cases where interop dependency resolution is not feasible. + ### `Identifier` Getters The `Identifier` MUST be exposed via `public` getters so that contracts can call back to authenticate @@ -581,6 +594,28 @@ dependency set called `dependencySet()`. This function MUST return the array of `L1Block` MUST also provide a public getter to get the dependency set size called `dependencySetSize()`. This function MUST return the length of the dependency set array. +### Deposit Context + +New methods will be added on the `L1Block` contract to interact with [deposit contexts](./derivation.md#deposit-context). + +```solidity +function isDeposit() public view returns (bool); +function depositsComplete() public; +``` + +### `isDeposit()` + +Returns true if the current execution occurs in a [deposit context](./derivation.md#deposit-context). + +Only the `CrossL2Inbox` is authorized to call `isDeposit`. +This is done to prevent apps from easily detecting and censoring deposits. + +#### `depositsComplete()` + +Called after processing the first L1 Attributes transaction and user deposits to destroy the deposit context. + +Only the `DEPOSITOR_ACCOUNT` is authorized to call `depositsComplete()`. + ## OptimismMintableERC20Factory | Constant | Value | diff --git a/specs/interop/upgrade.md b/specs/interop/upgrade.md index 01cec2508..5bc5cc32f 100644 --- a/specs/interop/upgrade.md +++ b/specs/interop/upgrade.md @@ -4,6 +4,9 @@ **Table of Contents** +- [L1 Attributes](#l1-attributes) + - [L1 Attributes Predeployed Contract](#l1-attributes-predeployed-contract) + - [Interop L1Block upgrade](#interop-l1block-upgrade) - [Security Considerations](#security-considerations) @@ -30,6 +33,43 @@ The execution payload MUST set `noTxPool` to `true` for this block. The exact definitions for these upgrade transactions are still to be defined. +## L1 Attributes + +On the Interop activation block, and if Interop is not activated at Genesis, +the L1 Attributes Transaction includes a call to `setL1BlockValuesEcotone`. + +Every subsequent L1 Attributes transaction should include a call to the new `setL1BlockValuesIsthmus` function. +The input args and encoding of `setL1BlockValuesIsthmus` are identical to `setL1BlockValuesEcotone`. + +### L1 Attributes Predeployed Contract + +The L1 Attributes predeploy adds a new storage state in addition to the existing ones contained in the +pre-Interop L1 Attributes predeploy: + +- `isDeposit` (`bool`) - Set to `true` iff the current execution occurs in a [deposit context](./derivation.md#deposit-context). + +`setL1BlockValuesIsthmus` extends the behavior of `setL1BlockValuesEcotone` by additionally setting the +`isDeposit` state storage to `true`. + +### Interop L1Block upgrade + +The L1 Attributes Predeployed contract, `L1Block.sol`, is upgraded as part of the Interop upgrade. +The version is incremented to `1.3.0` to contain the new `isDeposit` storage slot. + +The function called by the L1 attributes transaction depends on the network upgrade: + +- Before the Interop activation: + - `setL1BlockValuesEcotone` is called, following the pre-Interop L1 attributes rules. +- At the Interop activation block: + - `setL1BlockValuesEcotone` function MUST be called, except if activated at genesis. + The contract is upgraded later in this block, to support `setL1BlockValuesIsthmus`. +- After the Interop activation: + - `setL1BlockValuesEcotone` function is deprecated and MUST never be called. + - `setL1BlockValuesIsthmus` MUST be called. + +The `setL1BlockValuesIsthmus` input parameters are identical to `setL1BlockValuesEcotone` as described in +[L1 Attributes Deposited Transaction Calldata](../protocol/ecotone/l1-attributes.md#l1-attributes-deposited-transaction-calldata). + ## Security Considerations TODO