Merge pull request #1181 from qbzzt/241215-arch

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,144 @@
+---
+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
+
+An OP Stack node consists of two pieces of software: a consensus client (e.g. op-node) and an execution client, which is responsible for processing user transactions and constructing blocks. Interoperability among OP Stack chains is enabled via a new service called 
+[*OP Supervisor*](/stack/interop/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:#FFE
+  classDef transparent fill:none, stroke:none
+  
+  subgraph chain1[OP Stack chain #1]
+    node1[OP Node]
+    super1[OP-Supervisor]
+    geth1[Execution Engine]
+    node1<-->super1<-->geth1<-->node1
+  end
+  subgraph X[ ]
+    chain2[OP Stack chain #2]
+    chain3[OP Stack chain #3]
+    l1node[L1 Consensus Layer]
+  end
+
+  chain2-->|log events|super1
+  chain3-->|log events|super1
+  l1node-->|block status|super1
+
+  class chain1,chain2,chain3 chain
+  class X transparent
+```
+
+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 service, 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 on the destination chain calls a contract called [`CrossL2Inbox`](https://specs.optimism.io/interop/predeploys.html#crossl2inbox).
+This call can be at the top level, directly from the externally owned account, or come through a smart contract.
+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).
+
+[For more information, see the  cross-chain messages anatomy page](./cross-chain-message).
+
+## 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 
+```
+
+Interop expands the scope of trust for unsafe blocks, blocks that are shared through [the gossip protocol](/builders/chain-operators/architecture#sequencer).
+To trust that an unsafe block is valid and is going to become safe and then finalized, you need to trust not only the sequencer that produces it, but also all the other sequencers that produce other blocks that are still unsafe, but that include initiating messages that are executed in that block.
+
+However, this is only for *unsafe* blocks, and only if the sequencer allows messages from unsafe blocks to be processed.
+A block is only considered promotable to *safe*, and therefore ready to be written to L1, when all the blocks on which it depends are safe.
+
+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=FKc5RgjtGes).
+*   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).

words.txt

@@ -154,6 +154,7 @@ Inator
 inator
 INFLUXDBV
 influxdbv
+inteoperates
 interchain
 IPCDISABLE
 ipcdisable