interop: Specify deposit handling (#258)

* interop: Specify deposit handling

* lint

* refine spec; include L1Block upgrade

* chore: rename reset to complete

* fix: fixes lint reference issues

* fix: missing rename of resetIsDeposit

* fix: mdbook references

* fix: Interop to Isthmus rename

* fix: typos

Co-authored-by: Disco <[email protected]>

* fix: reference L1BlockInterop instead of L1Block

Co-authored-by: Disco <[email protected]>

* fix: l1_attributes to -

* fix: l1-attributes reference to corresponding folder

* fix: l1-attributes reference to corresponding folder

* fix: l1-attributes reference to corresponding folder

* fix: l1-attributes reference to corresponding folder

* fix: l1-attributes reference to corresponding folder

* fix: remove trailing spaces

* fix: remove liq-migration

* fix: rename interop to isthmus, remove L1BlockInterop reference

---------

Co-authored-by: Skeletor Spaceman <[email protected]>
Co-authored-by: Skeletor Spaceman <[email protected]>
Co-authored-by: Disco <[email protected]>

Author: 3 people

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)

specs/interop/derivation.md

@@ -0,0 +1,52 @@
+# Derivation
+
+<!-- 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**
+
+- [Overview](#overview)
+  - [Deposit Context](#deposit-context)
+  - [Gas Considerations](#gas-considerations)
+- [Security Considerations](#security-considerations)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
+## 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

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                                        |

specs/interop/upgrade.md

@@ -4,6 +4,9 @@
 <!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
 **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)
 
 <!-- END doctoc generated TOC please keep comment here to allow auto update -->
@@ -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