# celo-org/optimism architecture

> Architecture diagram of the GitHub repository celo-org/optimism, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/celo-org/optimism
- Repository: https://github.com/celo-org/optimism

## Overview

This repository is a collection of OP Stack clients, services, and operator tools rather than one application. A representative chain workflow derives L2 payload attributes from rollup data, coordinates execution through an engine API, and submits batches to L1; fault-proof challenges and deployment are distinct operational workflows. The graph preserves these stages and major documented components, plus shared engine-facing and integration layers. Some subsystems are represented by directory paths because their source was not sampled; relationships are limited to visible imports or README descriptions.

Main entry points: [`op-node`](https://github.com/celo-org/optimism/tree/celo-rebase-19/op-node) (Rollup client), [`op-node/rollup/derive/pipeline.go`](https://github.com/celo-org/optimism/blob/celo-rebase-19/op-node/rollup/derive/pipeline.go) (Derivation pipeline), [`op-service/sources/engine_client.go`](https://github.com/celo-org/optimism/blob/celo-rebase-19/op-service/sources/engine_client.go) (Engine RPC client), [`op-node/rollup/engine/engine_controller.go`](https://github.com/celo-org/optimism/blob/celo-rebase-19/op-node/rollup/engine/engine_controller.go) (Engine controller)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_rollup["Rollup and execution"]
  node_rollup_node["Rollup client"]
  node_derive["Derivation pipeline<br/>[pipeline.go]"]
  node_attributes["Payload attributes"]
  node_engine_controller["Engine controller"]
  node_engine_rpc["Engine RPC client<br/>[engine_client.go]"]
  node_execution_client["Execution client<br/>[engine.rs]"]
  node_rust_derive["Rust derivation stages"]
end

subgraph group_batch["Batch submission"]
  node_batch_manager["Channel manager<br/>[channel_manager.go]"]
  node_throttler["Submission throttler<br/>[controller.go]"]
  node_batch_cli["Batcher service<br/>[main.go]"]
end

subgraph group_proof["Fault proofs"]
  node_challenger["Challenge agent"]
  node_challenge_cli["Challenger CLI<br/>[main.go]"]
  node_cannon["MIPS fault VM"]
  node_rust_pipeline["Rust proof pipeline<br/>[pipeline.rs]"]
end

subgraph group_deploy["Deployment and operations"]
  node_deployer["Contract deployer"]
  node_chain_ops["Chain operations<br/>[main.go]"]
  node_op_up["Devnet launcher<br/>[main.go]"]
end

subgraph group_integration["Integration and shared tools"]
  node_supernode["Multi-chain host"]
  node_interop_filter["Interop log ingester"]
  node_e2e_engine["E2E engine harness<br/>[l2_engine.go]"]
  node_e2e_api["Test engine API<br/>[l2_engine_api.go]"]
  node_wheel["Engine utility<br/>[engine.go]"]
end

node_operator(("Operator"))
node_chain_user(("Chain user"))

node_chain_user -.->|"uses chain"| node_rollup_node
node_rollup_node -.->|"derives blocks"| node_derive
node_derive -.->|"builds attributes"| node_attributes
node_engine_controller -.->|"uses derivation"| node_derive
node_engine_controller -.->|"creates client"| node_engine_rpc
node_engine_rpc -.->|"sends engine calls"| node_execution_client
node_batch_cli -.->|"runs batching"| node_batch_manager
node_batch_manager -.->|"throttles submissions"| node_throttler
node_operator -->|"starts agent"| node_challenge_cli
node_challenge_cli -->|"starts service"| node_challenger
node_challenger -.->|"uses fault VM"| node_cannon
node_operator -.->|"deploys contracts"| node_deployer
node_operator -->|"runs operations"| node_chain_ops
node_operator -->|"launches devnet"| node_op_up
node_supernode -->|"constructs client"| node_engine_rpc
node_interop_filter -->|"imports rollup types"| node_rollup_node
node_e2e_engine -->|"registers API"| node_e2e_api
node_rust_derive -.->|"derives proof inputs"| node_rust_pipeline
node_operator -.->|"uses engine tools"| node_wheel

click node_rollup_node "https://github.com/celo-org/optimism/tree/celo-rebase-19/op-node"
click node_derive "https://github.com/celo-org/optimism/blob/celo-rebase-19/op-node/rollup/derive/pipeline.go"
click node_attributes "https://github.com/celo-org/optimism/blob/celo-rebase-19/op-node/rollup/attributes/engine_consolidate.go"
click node_engine_controller "https://github.com/celo-org/optimism/blob/celo-rebase-19/op-node/rollup/engine/engine_controller.go"
click node_engine_rpc "https://github.com/celo-org/optimism/blob/celo-rebase-19/op-service/sources/engine_client.go"
click node_execution_client "https://github.com/celo-org/optimism/blob/celo-rebase-19/rust/op-reth/crates/node/src/engine.rs"
click node_batch_manager "https://github.com/celo-org/optimism/blob/celo-rebase-19/op-batcher/batcher/channel_manager.go"
click node_throttler "https://github.com/celo-org/optimism/blob/celo-rebase-19/op-batcher/batcher/throttler/controller.go"
click node_batch_cli "https://github.com/celo-org/optimism/blob/celo-rebase-19/op-batcher/cmd/main.go"
click node_challenger "https://github.com/celo-org/optimism/tree/celo-rebase-19/op-challenger"
click node_challenge_cli "https://github.com/celo-org/optimism/blob/celo-rebase-19/op-challenger/cmd/main.go"
click node_cannon "https://github.com/celo-org/optimism/tree/celo-rebase-19/cannon/mipsevm"
click node_deployer "https://github.com/celo-org/optimism/tree/celo-rebase-19/op-deployer/pkg/deployer"
click node_chain_ops "https://github.com/celo-org/optimism/blob/celo-rebase-19/op-chain-ops/cmd/check-lagoon/main.go"
click node_op_up "https://github.com/celo-org/optimism/blob/celo-rebase-19/op-up/main.go"
click node_supernode "https://github.com/celo-org/optimism/blob/celo-rebase-19/op-supernode/supernode/chain_container/engine_controller/engine_controller.go"
click node_interop_filter "https://github.com/celo-org/optimism/blob/celo-rebase-19/op-interop-filter/filter/logsdb_chain_ingester.go"
click node_e2e_engine "https://github.com/celo-org/optimism/blob/celo-rebase-19/op-e2e/actions/helpers/l2_engine.go"
click node_e2e_api "https://github.com/celo-org/optimism/blob/celo-rebase-19/op-e2e/actions/helpers/engineapi/l2_engine_api.go"
click node_rust_derive "https://github.com/celo-org/optimism/tree/celo-rebase-19/rust/kona/crates/protocol/derive/src/stages"
click node_rust_pipeline "https://github.com/celo-org/optimism/blob/celo-rebase-19/rust/kona/crates/proof/driver/src/pipeline.rs"
click node_wheel "https://github.com/celo-org/optimism/blob/celo-rebase-19/op-wheel/engine/engine.go"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_rollup_node,node_derive,node_attributes,node_engine_controller,node_engine_rpc,node_execution_client,node_rust_derive,node_chain_user toneBlue
class node_batch_manager,node_throttler,node_batch_cli toneAmber
class node_challenger,node_challenge_cli,node_cannon,node_rust_pipeline toneMint
class node_deployer,node_chain_ops,node_op_up toneRose
class node_supernode,node_interop_filter,node_e2e_engine,node_e2e_api,node_wheel,node_operator toneIndigo
```

## Components

### Rollup and execution

- [Rollup client](https://github.com/celo-org/optimism/tree/celo-rebase-19/op-node): `op-node`
- [Derivation pipeline](https://github.com/celo-org/optimism/blob/celo-rebase-19/op-node/rollup/derive/pipeline.go): `op-node/rollup/derive/pipeline.go`
- [Payload attributes](https://github.com/celo-org/optimism/blob/celo-rebase-19/op-node/rollup/attributes/engine_consolidate.go): `op-node/rollup/attributes/engine_consolidate.go`
- [Engine controller](https://github.com/celo-org/optimism/blob/celo-rebase-19/op-node/rollup/engine/engine_controller.go): `op-node/rollup/engine/engine_controller.go`
- [Engine RPC client](https://github.com/celo-org/optimism/blob/celo-rebase-19/op-service/sources/engine_client.go): `op-service/sources/engine_client.go`
- [Execution client](https://github.com/celo-org/optimism/blob/celo-rebase-19/rust/op-reth/crates/node/src/engine.rs): `rust/op-reth/crates/node/src/engine.rs`
- [Rust derivation stages](https://github.com/celo-org/optimism/tree/celo-rebase-19/rust/kona/crates/protocol/derive/src/stages): `rust/kona/crates/protocol/derive/src/stages`

### Batch submission

- [Channel manager](https://github.com/celo-org/optimism/blob/celo-rebase-19/op-batcher/batcher/channel_manager.go): `op-batcher/batcher/channel_manager.go`
- [Submission throttler](https://github.com/celo-org/optimism/blob/celo-rebase-19/op-batcher/batcher/throttler/controller.go): `op-batcher/batcher/throttler/controller.go`
- [Batcher service](https://github.com/celo-org/optimism/blob/celo-rebase-19/op-batcher/cmd/main.go): `op-batcher/cmd/main.go`

### Fault proofs

- [Challenge agent](https://github.com/celo-org/optimism/tree/celo-rebase-19/op-challenger): `op-challenger`
- [Challenger CLI](https://github.com/celo-org/optimism/blob/celo-rebase-19/op-challenger/cmd/main.go): `op-challenger/cmd/main.go`
- [MIPS fault VM](https://github.com/celo-org/optimism/tree/celo-rebase-19/cannon/mipsevm): `cannon/mipsevm`
- [Rust proof pipeline](https://github.com/celo-org/optimism/blob/celo-rebase-19/rust/kona/crates/proof/driver/src/pipeline.rs): `rust/kona/crates/proof/driver/src/pipeline.rs`

### Deployment and operations

- [Contract deployer](https://github.com/celo-org/optimism/tree/celo-rebase-19/op-deployer/pkg/deployer): `op-deployer/pkg/deployer`
- [Chain operations](https://github.com/celo-org/optimism/blob/celo-rebase-19/op-chain-ops/cmd/check-lagoon/main.go): `op-chain-ops/cmd/check-lagoon/main.go`
- [Devnet launcher](https://github.com/celo-org/optimism/blob/celo-rebase-19/op-up/main.go): `op-up/main.go`

### Integration and shared tools

- [Multi-chain host](https://github.com/celo-org/optimism/blob/celo-rebase-19/op-supernode/supernode/chain_container/engine_controller/engine_controller.go): `op-supernode/supernode/chain_container/engine_controller/engine_controller.go`
- [Interop log ingester](https://github.com/celo-org/optimism/blob/celo-rebase-19/op-interop-filter/filter/logsdb_chain_ingester.go): `op-interop-filter/filter/logsdb_chain_ingester.go`
- [E2E engine harness](https://github.com/celo-org/optimism/blob/celo-rebase-19/op-e2e/actions/helpers/l2_engine.go): `op-e2e/actions/helpers/l2_engine.go`
- [Test engine API](https://github.com/celo-org/optimism/blob/celo-rebase-19/op-e2e/actions/helpers/engineapi/l2_engine_api.go): `op-e2e/actions/helpers/engineapi/l2_engine_api.go`
- [Engine utility](https://github.com/celo-org/optimism/blob/celo-rebase-19/op-wheel/engine/engine.go): `op-wheel/engine/engine.go`

### Other components

- **Operator**
- **Chain user**

## Connections

- Chain user → Rollup client: uses chain (evidence: `README.md`)
- Rollup client → Derivation pipeline: derives blocks (evidence: `op-node/cmd/main.go`)
- Derivation pipeline → Payload attributes: builds attributes (evidence: `op-node/rollup/derive/pipeline.go`)
- Engine controller → Derivation pipeline: uses derivation (evidence: `op-node/rollup/engine/engine_controller.go`)
- Engine controller → Engine RPC client: creates client (evidence: `op-service/sources/engine_client.go`)
- Engine RPC client → Execution client: sends engine calls (evidence: `op-service/sources/engine_client.go`)
- Batcher service → Channel manager: runs batching (evidence: `README.md`)
- Channel manager → Submission throttler: throttles submissions (evidence: `op-batcher/batcher/channel_manager.go`)
- Operator → Challenger CLI: starts agent (evidence: `op-challenger/cmd/main.go`)
- Challenger CLI → Challenge agent: starts service (evidence: `op-challenger/cmd/main.go`)
- Challenge agent → MIPS fault VM: uses fault VM (evidence: `README.md`)
- Operator → Contract deployer: deploys contracts (evidence: `README.md`)
- Operator → Chain operations: runs operations (evidence: `op-chain-ops/cmd/check-lagoon/main.go`)
- Operator → Devnet launcher: launches devnet (evidence: `op-up/main.go`)
- Multi-chain host → Engine RPC client: constructs client (evidence: `op-supernode/supernode/chain_container/engine_controller/engine_controller.go`)
- Interop log ingester → Rollup client: imports rollup types (evidence: `op-interop-filter/filter/logsdb_chain_ingester.go`)
- E2E engine harness → Test engine API: registers API (evidence: `op-e2e/actions/helpers/l2_engine.go`)
- Rust derivation stages → Rust proof pipeline: derives proof inputs
- Operator → Engine utility: uses engine tools (evidence: `README.md`)
