From fa59525d2e1d570fb14efc98ff034d2226068743 Mon Sep 17 00:00:00 2001
From: Adrian Sutton <adrian@oplabs.co>
Date: Tue, 23 Jul 2024 13:35:27 +1000
Subject: [PATCH] interop: Add initial indexing api spec

---
 specs/SUMMARY.md              |  1 +
 specs/interop/indexing_api.md | 56 +++++++++++++++++++++++++++++++++++
 specs/interop/overview.md     |  2 +-
 3 files changed, 58 insertions(+), 1 deletion(-)
 create mode 100644 specs/interop/indexing_api.md

diff --git a/specs/SUMMARY.md b/specs/SUMMARY.md
index fe2779279..99a737b3c 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)
+    - [Indexing API](./interop/indexing_api)
     - [Fault Proof](./interop/fault_proof.md)
     - [Upgrade](./interop/upgrade.md)
     - [Token Bridging](./interop/token-bridging.md)
diff --git a/specs/interop/indexing_api.md b/specs/interop/indexing_api.md
new file mode 100644
index 000000000..13c0ce06f
--- /dev/null
+++ b/specs/interop/indexing_api.md
@@ -0,0 +1,56 @@
+# Indexing API
+
+<!-- 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**
+
+- [Optional Indexing Backend](#optional-indexing-backend)
+- [Methods](#methods)
+  - [`interop_checkMessage`](#interop_checkmessage)
+    - [Parameters](#parameters)
+    - [Returns](#returns)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
+## Optional Indexing 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
+backends, a standard API for indexers to expose is defined here.
+
+The API uses [JSON-RPC] and follows the same conventions as the [Ethereum JSON-RPC API].
+
+## 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`](./verifier.md#unsafe-inputs)
+- `cross-unsafe` - the specified log exists and meets the requirements
+  of [`cross-unsafe` inputs`](./verifier.md#cross-unsafe-inputs)
+- `safe` - the specified log exists and meets the requirements of [`safe` inputs`](./verifier.md#safe-inputs)
+- `finalized` - the specified log exists and meets the requirements
+  of [`finalized` inputs`](./verifier.md#finalized-inputs)
+
+[JSON-RPC]: https://www.jsonrpc.org/specification
+
+[Ethereum JSON-RPC API]: https://ethereum.org/en/developers/docs/apis/json-rpc/
diff --git a/specs/interop/overview.md b/specs/interop/overview.md
index d0e0311a7..3ee3e3766 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 |