docs(interop/architecture): first version

pages/stack/interop.mdx

@@ -11,9 +11,12 @@ import { Card, Cards } from 'nextra/components'
 Documentation covering Cross Chain Message, Explainer, Message Passing, Op Supervisor, Superchain Erc20, Superchain Weth, Supersim, Transfer Superchainerc20 in the Interop section of the OP Stack ecosystem.
 
 <Cards>
+  <Card title="Interoperability explainer" href="/stack/interop/explainer" />
+
+  <Card title="Architecture" href="/stack/interop/architecture" />  
+
   <Card title="Anatomy of a cross-chain message" href="/stack/interop/cross-chain-message" />
 
-  <Card title="Interoperability explainer" href="/stack/interop/explainer" />
 
   <Card title="Interop message passing overview" href="/stack/interop/message-passing" />
 

pages/stack/interop/_meta.json

@@ -1,5 +1,6 @@
 {
     "explainer": "Interop explainer",
+    "architecture": "Architecture",
     "devnet": "Interop devnet",
     "supersim": "Supersim Multichain Development Environment",
     "cross-chain-message": "Anatomy of cross-chain message",

pages/stack/interop/architecture.mdx

@@ -0,0 +1,146 @@
+---
+title: Interoperability architecture
+lang: en-US
+description: How it works.
+---
+
+import { Callout } from 'nextra/components'
+import Image from 'next/image'
+
+import { InteropCallout } from '@/components/WipCallout'
+
+<InteropCallout />
+
+# Interoperability architecture
+
+Interoperability among OP Stack chains is enabled via a new service called *OP-Supervisor*.
+Every node operator is expected to run this service in addition to the [rollup node](/builders/node-operators/architecture#rollup-node) and [execution client](/builders/node-operators/architecture#execution-client).
+
+```mermaid
+
+graph LR
+
+  classDef chain fill:#FFC
+
+  subgraph chain1[OP Stack chain #1]
+    node1[OP Node]
+    super1[OP-Supervisor]
+    geth1[Execution Engine]
+    super1-->|remote block status|node1
+    node1-->|local block status|super1
+    super1-->|initiating message validation|geth1    
+    node1<-->geth1
+  end
+  chain2[OP Stack chain #2]
+  chain3[OP Stack chain #3]
+  subgraph l1[Ethereum L1 chain]
+     l1node[Consensus Layer]
+     l1geth[Execution Layer]
+  end
+
+  chain2-->|log events|super1
+  chain3-->|log events|super1
+  l1node-->|block status|super1
+
+  class chain1,chain2,chain3,l1 chain
+```
+
+OP-Supervisor holds a database of all the log events of all the chains in the interoperability cluster.
+Every event can potentially initiate a cross domain message, and it is the job of OP-Supervisor to validate that the log event really happened on the source chain.
+Additionally, OP-Supervisor reads information from L1's consensus layer to determine the transaction safety of L2 blocks.
+
+## How messages get from one chain to the other
+
+To understand *why* we need this additional component, it is useful to know how interop messages get from one blockchain to another.
+
+```mermaid
+
+sequenceDiagram
+    participant app as Application
+    participant src as Source Chain
+    box rgba(0,0,0,0.1) Destination Chain
+      participant dst-sup as OP-Supervisor
+      participant dst-geth as Execution Engine
+    end
+    app->>src: Transaction
+    src->>dst-sup: Log Event
+    note over src,dst-sup: Log Event = Initializing Message
+    app->>dst-geth: Transaction
+    dst-geth->>dst-geth: Call to CrossL2Inbox to execute or verify a message.
+    dst-geth->>dst-sup: Did you receive this initiating message?
+    dst-sup->>dst-geth: Yes
+    note left of dst-geth: Call is successful
+    dst-geth->>dst-geth: CrossL2Inbox emits ExecutingMessage.
+    note over dst-geth: Executing Message
+```
+
+Cross domain messages require two transactions.
+The first transaction creates an *initiating message* on the source chain.
+The second transaction creates an *executing message* on the destination chain.
+This executing message could result in a contract function being executed on the destination chain.
+
+The initiating message is simply a log event.
+Any log event on any chain that inteoperates with the destination can initiate a cross domain message.
+
+The transaction that receives the message calls a contract called [`CrossL2Inbox`](https://specs.optimism.io/interop/predeploys.html#crossl2inbox), directly or indirectly.
+The call to `CrossL2Inbox`, also known as the *executing message*, needs to [identify the initiating message uniquely](https://github.com/ethereum-optimism/optimism/blob/develop/packages/contracts-bedrock/src/L2/CrossL2Inbox.sol#L35-L42), using the chain ID of the source chain, the block number, and the index of the log event within that block, as well as a few other fields as a sanity check.
+
+`CrossL2Inbox` can either [validate the message exists](https://github.com/ethereum-optimism/optimism/blob/develop/packages/contracts-bedrock/src/L2/CrossL2Inbox.sol#L171-L185), or [call a contract if the message exists](https://github.com/ethereum-optimism/optimism/blob/develop/packages/contracts-bedrock/src/L2/CrossL2Inbox.sol#L171-L185).
+
+## Safety levels
+
+```mermaid
+
+flowchart LR
+    classDef finalized fill:#CCC
+    classDef safe fill:#8F8
+    classDef unsafe fill:#F89
+    subgraph I[Blocks with Initiating Messages]
+    style I fill:none
+      subgraph A[Chain A]
+        A0[Block n]
+        A1[Block n+100]
+        A2[Block n+105]
+        class A0 finalized
+        class A1 safe
+        class A2 unsafe
+      end
+      subgraph B[Chain B]
+        B0[Block m]
+        B1[Block m+3]
+        class B0,B1 safe
+      end
+    end
+    subgraph C[Chain C]
+      C0[Block with executing messages]
+      class C0 unsafe
+    end
+    A0 --> C0
+    A1 --> C0
+    A2 --> C0
+    B0 --> C0
+    B1 --> C0 
+```
+
+In addition to being written to L1, a *safe* block is one that only depends on other safe blocks.
+For example, in the image below, most blocks are safe.
+Block `n` in chain A is even finalized, and immune from reorgs.
+However, block `n+105` in chain A is unsafe, it (or a block on which it depends is not written to L1).
+Because the new block depends upon it, it is also unsafe.
+
+## Next steps
+
+- Want to learn more? 
+  Read our guide on the anatomy of a [cross-chain message](./cross-chain-message) or check out this 
+  [interop design video walk-thru]([https://www.youtube.com/watch?v=FKc5RgjtG](https://www.youtube.com/watch?v=FKc5RgjtG)
+- Ready to get started? Use [Supersim](./supersim), a local dev environment that simulates interop for testing applications against a local version of the Superchain.
+- For more info about how OP Stack interoperability works under the hood, 
+  [check out the specs](https://specs.optimism.io/interop/overview.html).
+
+{/* 
+- *Unsafe* - not yet written to L1, obtained through gossip channels, ultimately based on trust in a sequencer.
+- *Cross unsafe* - verified that all executing messages have legitimate initiating messages, but otherwise still unsafe.
+  Treated as unsafe for most purposes.
+- *Safe* - the block and all the blocks on which it depends (those with initiating mesages to which it has executing messages) have been written to L1.
+- *Finalized* - the block and all the blocks on which it depends have been on L1 for long enough to make a reorg impossible.
+*/}

words.txt

@@ -154,7 +154,9 @@ Inator
 inator
 INFLUXDBV
 influxdbv
+inteoperates
 interchain
+intero
 IPCDISABLE
 ipcdisable
 ipcfile