diff --git a/specs/SUMMARY.md b/specs/SUMMARY.md index 0e2b326cd..d25397125 100644 --- a/specs/SUMMARY.md +++ b/specs/SUMMARY.md @@ -54,6 +54,7 @@ - [Sequencer](./interop/sequencer.md) - [Verifier](./interop/verifier.md) - [Rollup Node P2P](./interop/rollup_node_p2p.md) + - [Supervisor API](./interop/supervisor-api) - [Fault Proof](./interop/fault_proof.md) - [Upgrade](./interop/upgrade.md) - [Token Bridging](./interop/token-bridging.md) diff --git a/specs/interop/overview.md b/specs/interop/overview.md index c20750ce9..ec07146a4 100644 --- a/specs/interop/overview.md +++ b/specs/interop/overview.md @@ -13,7 +13,7 @@ network upgrade will be included in this document in the future. | Source Chain | A blockchain that includes an initiating message | | Destination Chain | A blockchain that includes an executing message | | Initiating Message | An event emitted from a source chain | -| Executing Message | An event emitted from a destination chain's `CrossL2Inbox` that includes an initiating message | +| Executing Message | An event emitted from a destination chain's `CrossL2Inbox` that includes an initiating message | | Cross Chain Message | The cumulative execution and side effects of the initiating message and executing message | | Dependency Set | The set of chains that originate initiating transactions where the executing transactions are valid | diff --git a/specs/interop/supervisor-api.md b/specs/interop/supervisor-api.md new file mode 100644 index 000000000..751d0100c --- /dev/null +++ b/specs/interop/supervisor-api.md @@ -0,0 +1,232 @@ +# Supervisor API + + + +**Table of Contents** + +- [Optional Supervisor Backend](#optional-supervisor-backend) +- [Methods](#methods) + - [`interop_checkMessage`](#interop_checkmessage) + - [Parameters](#parameters) + - [Returns](#returns) + - [`interop_crossUnsafe`](#interop_crossunsafe) + - [Parameters](#parameters-1) + - [Returns](#returns-1) + - [`interop_nextDeriveTask`](#interop_nextderivetask) + - [Parameters](#parameters-2) + - [Returns](#returns-2) + - [`interop_blockDerived`](#interop_blockderived) + - [Parameters](#parameters-3) + - [Returns](#returns-3) + - [`interop_safe`](#interop_safe) + - [Parameters](#parameters-4) + - [Returns](#returns-4) + - [`interop_finalized`](#interop_finalized) + - [Parameters](#parameters-5) + - [Returns](#returns-5) + + + +## Optional Supervisor Backend + +Sequencers or verifies MAY utilise an external service to index the logs from chains in the dependency set and optimise +cross-chain validity checks. To aid compatibility between different implementations of sequencers, verifiers and +these supervisors, a standard API for such services to expose is defined here. + +The API uses [JSON-RPC] and follows the same conventions as the [Ethereum JSON-RPC API]. + +[JSON-RPC]: https://www.jsonrpc.org/specification + +[Ethereum JSON-RPC API]: https://ethereum.org/en/developers/docs/apis/json-rpc/ + +## Methods + +### `interop_checkMessage` + +Determines the safety level of an individual message. This can be used to verify initiating messages exist, for example +by the tx-pool and block-building, to verify user-input before inclusion into the chain. + +#### Parameters + +1. Object - The Identifier object + - origin: DATA, 20 Bytes - Account that emits the log + - blocknumber: QUANTITY - Block number in which the log was emitted + - logIndex: QUANTITY - The index of the log in the array o fall logs emitted in the block + - timestamp: QUANTITY - The timestamp that the log was emitted + - chainid: QUANTITY - The chain id of the chain that emitted the log +2. payloadHash: DATA, 32 bytes - the keccak256 hash of the [message payload](./messaging.md#message-payload) + +#### Returns + +`String` - The strictest applicable `SafetyLevel` of the message + +- `conflicts` - data is available for the block referenced by the identifier but does not contain a matching log +- `unknown` - data for the block referenced by the identifier is not yet available +- `finalized` - the specified log exists +- `unsafe` - the specified log exists and meets the requirements of [`unsafe` inputs] +- `cross-unsafe` - the specified log exists and meets the requirements of [`cross-unsafe` inputs] +- `safe` - the specified log exists and meets the requirements of [`safe` inputs] +- `finalized` - the specified log exists and meets the requirements of [`finalized` inputs] + +### `interop_crossUnsafe` + +Returns the latest `cross-unsafe` block in the canonical chain of the supervisor, up to and including the +specified `maxBlockNumber`. This can be used by sequencers or verifiers to determine when blocks on their chain have met +all cross-chain dependencies. For example, batchers may avoid posting batch data for transactions that have unsatisfied +cross-chain dependencies. + +As the supervisor and caller may have different local views of the chain, e.g. because a reorg has not yet been +processed, callers MUST confirm that the returned block is canonical in their local view of the chain. Callers MAY retry +the query with a lower `maxBlockNumber` if the returned block is non-canonical. + +Supervisors SHOULD consider calls where `maxBlockNumber` is ahead of their current `unsafe` head for a chain to be a +signal that additional blocks may be available to be indexed. However, supervisors MUST eventually index available +blocks even if `interop_crossUnsafe` is not called. + +#### Parameters + +1. chainID: QUANTITY - Chain ID of the chain to return data for +2. maxBlockNumber: QUANTITY - The maximum block number to return information for + +#### Returns + +`Object` - Block ID that meets the requirements of [`cross-unsafe` inputs] and `block.number <= maxBlockNumber` + +- `hash`: DATA, 32 Bytes - the block hash +- `number`: QUANTITY - the block number + +### `interop_nextDeriveTask` + +Returns the next derivation task that the supervisor needs for it to potentially progress the cross-chain safe head. +The response allows the supervisor to + +There are three possible cases: + +1. The supervisor has sufficient information for this chain and is awaiting information from other + chains (`derivationRequired: false`) +2. The supervisor is waiting for further local-safe blocks from the chain (`depositOnly: false`) +3. The supervisor has determined that a local-safe block has invalid executing messages and must be replaced by a + deposit-only block (`depositOnly: true`) + +When `derivationRequired` is `true`: + +- `l2Parent` MUST specify a L2 block that is canonical in the supervisor's view of the chain, that the next derived + block will be a child of +- `l1` MUST specify the L1 block to be treated as the L1 chain head when deriving the next block. + - The block MUST be the same as or higher than the L1 block used when deriving `l2Parent` + - Higher L1 blocks MUST NOT be used, even if they are seen as canonical + +#### Parameters + +1. chainID: QUANTITY - Chain ID of the chain to return the next derive task for + +#### Returns + +`Object` - The next derivation task required to perform in an attempt to progress the safe head + +- `derivationRequired`: Boolean - `true` if there is a derivation task required for this chain, otherwise `false`. + When `false` all other fields must be omitted. +- `l2Parent`: `Object` - The L2 block to attempt to derive the next block on top of + - `hash`: DATA, 32 Bytes - the block hash + - `number`: QUANTITY - the block number +- `depositOnly`: Boolean - `true` if the block should be restricted to deposit transactions only, otherwise `false` +- `l1`: `Object - The most recent L1 block that may be used when attempting to derive the next block + - `hash`: DATA, 32 Bytes - the block hash + - `number`: QUANTITY - the block number + +### `interop_blockDerived` + +Provides the result of a previous derivation task returned by `interop_nextDeriveTask`. The `derived` block MUST: + +- be derivable from data on the availability layer up to and including the specified `l1` block +- have `l2Parent` as its parent +- contain only deposit transactions from its origin L1 block if `depositOnly` is `true`. + +Supervisors MUST NOT return an error if multiple calls to `interop_blockDerived` are made for the same derivation task. + +Supervisors MAY return an error if the specified `l2Parent`, `depositOnly` and `l1` values do not match any derivation +task returned by `interop_nextDerivateTask`. + +#### Parameters + +1. chainID: QUANTITY - Chain ID of the chain the block was derived on +2. derived: `Object` - The block that was derived + - `hash`: DATA, 32 Bytes - the block hash + - `number`: QUANTITY - the block number +3. l2Parent: `Object` - The parent of the derived block. MUST be equal to the `l2Parent` from the original derive task. + - `hash`: DATA, 32 Bytes - the block hash + - `number`: QUANTITY - the block number +4. depositOnly: Boolean - `true` if the derived block was explicitly restricted to only include deposit transactions by + the derive task, otherwise `false`. MUST be `false` if the original task `depositOnly` was `false`, even if the block + only contains deposit transactions for any other reason. +5. l1: `Object` - The L1 block used as the L1 chain head when deriving. MUST be equal to the `l1` from the original + derive task. + - `hash`: DATA, 32 Bytes - the block hash + - `number`: QUANTITY - the block number + +#### Returns + +N/A + +### `interop_safe` + +Returns the highest block for the specified chain that meets the [`safe` inputs] requirements using only data up to and +including the specified `l1Number` block on the data availability layer. + +If the supervisor has not processed all data up to the specified `l1Number` is MUST use the latest L1 block it has fully +processed and MUST return that block as the `derivedFrom` block. Otherwise `derivedFrom` MUST be the block at +number `l1Number`. + +As the supervisor and caller may have different local views of the chain, e.g. because a reorg has not yet been +processed, callers MUST confirm that the returned `derivedFrom` block is canonical in their local view. Callers MAY +retry the query with a lower `l1Number` if the returned block is non-canonical. + +#### Parameters + +1. chainID: QUANTITY - Chain ID to get the `cross-safe` block for +2. `l1Number`: QUANTITY - Block number of the L1 block to limit data to + +#### Returns + +`Object` - The `safe` block for the specified chain and the L1 block required to derive it. + +- `safe`: `Object` - The highest L2 block from the specified chain that meets the [`safe` inputs] requirements after + applying all data from the availability layer up to and including block `l1Number` + - `hash`: DATA, 32 Bytes - the block hash + - `number`: QUANTITY - the block number +- `derivedFrom`: `Object` - The L1 block used as the chain head of the data availability layer when deriving + - `hash`: DATA, 32 Bytes - the block hash + - `number`: QUANTITY - the block number. + +### `interop_finalized` + +Returns the highest block for the specified chain that meets the [`finalized` inputs] requirements using only data up to +and including the specified `l1Number` block on the data availability layer. + +If `l1Number` is not finalized in the supervisor's view of the L1 chain, it MUST use the latest finalized block and +return it as the `derivedFrom` value. + +#### Parameters + +1. chainID: QUANTITY - Chain ID to get the `cross-safe` block for +2. `l1Number`: QUANTITY - Block number of the L1 block to limit data to + +#### Returns + +`Object` - The `finalized` block for the specified chain and the L1 block required to derive it. + +- `finalized`: `Object` - The highest L2 block from the specified chain that meets the [`finalized` inputs] requirements + after applying all data from the availability layer up to and including block `l1Number` + - `hash`: DATA, 32 Bytes - the block hash + - `number`: QUANTITY - the block number +- `derivedFrom`: `Object` - The finalized L1 block used as the chain head of the data availability layer when deriving + - `hash`: DATA, 32 Bytes - the block hash + - `number`: QUANTITY - the block number. + +[`unsafe` inputs]: ./verifier.md#unsafe-inputs + +[`cross-unsafe` inputs]: ./verifier.md#cross-unsafe-inputs + +[`safe` inputs]: ./verifier.md#safe-inputs + +[`finalized` inputs]: ./verifier.md#finalized-inputs