# pablosinyores/aether architecture

> Architecture diagram of the GitHub repository pablosinyores/aether, 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/pablosinyores/aether
- Repository: https://github.com/pablosinyores/aether

## Overview

Aether is an Ethereum arbitrage engine with two paths: block-driven cycle detection and pending-transaction backrunning. Both validate opportunities through EVM simulation and deliver them over gRPC to a Go executor for risk checks, bundle construction, and builder submission. Rust ingestion, pool models, and price state support detection; the mempool path also predicts victim post-state and validates a backrun. Go services provide risk control, monitoring, and prediction reconciliation. Several subsystem links rely on README architecture statements because the relevant source excerpts are incomplete; the contract source is not present in the supplied tree.

Main entry points: [`cmd/executor/main.go`](https://github.com/pablosinyores/aether/blob/main/cmd/executor/main.go) (Executor orchestration), [`crates/simulator/src/lib.rs`](https://github.com/pablosinyores/aether/blob/main/crates/simulator/src/lib.rs) (EVM simulation), [`crates/detector/src/opportunity.rs`](https://github.com/pablosinyores/aether/blob/main/crates/detector/src/opportunity.rs) (Cycle detection), [`crates/grpc-server/src/mempool_pipeline.rs`](https://github.com/pablosinyores/aether/blob/main/crates/grpc-server/src/mempool_pipeline.rs) (Mempool decode pipeline)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_rust_core["Rust market analysis"]
  node_ingestion["Chain ingestion"]
  node_pools["DEX pools and decoders"]
  node_state["Pool state and price graph<br/>[price_graph.rs]"]
  node_engine["Engine and cycle gating<br/>[engine.rs]"]
  node_detector["Cycle detection<br/>[opportunity.rs]"]
  node_simulator["EVM simulation<br/>[lib.rs]"]
  node_fork["Fork state and caches<br/>[fork.rs]"]
  node_bytecode_cache[("Bytecode cache<br/>[bytecode_cache.rs]")]
  node_grpc_service["gRPC arb service<br/>[service.rs]"]
  node_grpc_adapter["Arb conversion<br/>[pipeline.rs]"]
end

subgraph group_mempool["Mempool backrun"]
  node_mempool_feed["Pending transaction ingestion<br/>[mempool.rs]"]
  node_mempool_pipeline["Mempool decode pipeline"]
  node_post_state["Victim post-state prediction"]
  node_backrun["Backrun validation<br/>[mempool_backrun.rs]"]
end

subgraph group_execution["Go execution"]
  node_go_executor["Executor orchestration<br/>[main.go]"]
  node_risk["Risk management<br/>[manager.go]"]
  node_bundle["Bundle construction<br/>[bundle.go]"]
  node_submitter["Builder submission<br/>[submitter.go]"]
end

subgraph group_operations["Persistence and operations"]
  node_ledger[("PostgreSQL ledger<br/>[ledger_pg.go]")]
  node_reconciler["Prediction reconciliation<br/>[main.go]"]
  node_monitor["Monitoring and alerting"]
end

node_eth_nodes(("Ethereum nodes"))
node_alchemy(("Alchemy pending feed"))
node_builders["Block builders"]
node_executor_contract["On-chain executor"]

node_eth_nodes -->|"streams events"| node_ingestion
node_ingestion -->|"decodes updates"| node_pools
node_pools -->|"updates pool state"| node_state
node_state -->|"supplies graph state"| node_engine
node_engine -->|"finds cycles"| node_detector
node_detector -->|"simulates candidates"| node_simulator
node_fork -->|"loads cached code"| node_bytecode_cache
node_simulator -->|"uses fork state"| node_fork
node_alchemy -->|"streams pending transactions"| node_mempool_feed
node_mempool_feed -->|"feeds pending events"| node_mempool_pipeline
node_mempool_pipeline -->|"predicts post-state"| node_post_state
node_post_state -->|"validates backrun"| node_backrun
node_backrun -->|"uses fork simulation"| node_simulator
node_detector -->|"converts opportunity"| node_grpc_adapter
node_simulator -->|"converts simulation result"| node_grpc_adapter
node_grpc_adapter -->|"provides arb payload"| node_grpc_service
node_grpc_service -->|"streams validated arbs"| node_go_executor
node_go_executor -->|"checks preflight"| node_risk
node_go_executor -->|"builds transaction bundle"| node_bundle
node_go_executor -->|"submits bundle"| node_submitter
node_submitter -->|"fans out bundles"| node_builders
node_builders -->|"delivers transaction"| node_executor_contract
node_go_executor -.->|"persists trades"| node_ledger
node_mempool_pipeline -.->|"persists predictions"| node_ledger
node_reconciler -->|"reconciles predictions"| node_ledger
node_reconciler -->|"reports outcomes"| node_monitor

click node_ingestion "https://github.com/pablosinyores/aether/tree/main/crates/ingestion/src"
click node_pools "https://github.com/pablosinyores/aether/tree/main/crates/pools/src"
click node_state "https://github.com/pablosinyores/aether/blob/main/crates/state/src/price_graph.rs"
click node_engine "https://github.com/pablosinyores/aether/blob/main/crates/grpc-server/src/engine.rs"
click node_detector "https://github.com/pablosinyores/aether/blob/main/crates/detector/src/opportunity.rs"
click node_simulator "https://github.com/pablosinyores/aether/blob/main/crates/simulator/src/lib.rs"
click node_fork "https://github.com/pablosinyores/aether/blob/main/crates/simulator/src/fork.rs"
click node_bytecode_cache "https://github.com/pablosinyores/aether/blob/main/crates/simulator/src/bytecode_cache.rs"
click node_mempool_feed "https://github.com/pablosinyores/aether/blob/main/crates/ingestion/src/mempool.rs"
click node_mempool_pipeline "https://github.com/pablosinyores/aether/blob/main/crates/grpc-server/src/mempool_pipeline.rs"
click node_post_state "https://github.com/pablosinyores/aether/blob/main/crates/simulator/src/post_state_replay.rs"
click node_backrun "https://github.com/pablosinyores/aether/blob/main/crates/simulator/src/mempool_backrun.rs"
click node_grpc_service "https://github.com/pablosinyores/aether/blob/main/crates/grpc-server/src/service.rs"
click node_grpc_adapter "https://github.com/pablosinyores/aether/blob/main/crates/grpc-server/src/pipeline.rs"
click node_go_executor "https://github.com/pablosinyores/aether/blob/main/cmd/executor/main.go"
click node_risk "https://github.com/pablosinyores/aether/blob/main/internal/risk/manager.go"
click node_bundle "https://github.com/pablosinyores/aether/blob/main/cmd/executor/bundle.go"
click node_submitter "https://github.com/pablosinyores/aether/blob/main/cmd/executor/submitter.go"
click node_ledger "https://github.com/pablosinyores/aether/blob/main/internal/db/ledger_pg.go"
click node_reconciler "https://github.com/pablosinyores/aether/blob/main/cmd/reconciler/main.go"
click node_monitor "https://github.com/pablosinyores/aether/tree/main/cmd/monitor"

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_ingestion,node_pools,node_state,node_engine,node_detector,node_simulator,node_fork,node_bytecode_cache,node_grpc_service,node_grpc_adapter toneBlue
class node_mempool_feed,node_mempool_pipeline,node_post_state,node_backrun toneAmber
class node_go_executor,node_risk,node_bundle,node_submitter toneMint
class node_ledger,node_reconciler,node_monitor toneRose
class node_eth_nodes,node_alchemy,node_builders,node_executor_contract toneIndigo
```

## Components

### Rust market analysis

- [Chain ingestion](https://github.com/pablosinyores/aether/tree/main/crates/ingestion/src): `crates/ingestion/src`
- [DEX pools and decoders](https://github.com/pablosinyores/aether/tree/main/crates/pools/src): `crates/pools/src`
- [Pool state and price graph](https://github.com/pablosinyores/aether/blob/main/crates/state/src/price_graph.rs): `crates/state/src/price_graph.rs`
- [Engine and cycle gating](https://github.com/pablosinyores/aether/blob/main/crates/grpc-server/src/engine.rs): `crates/grpc-server/src/engine.rs`
- [Cycle detection](https://github.com/pablosinyores/aether/blob/main/crates/detector/src/opportunity.rs): `crates/detector/src/opportunity.rs`
- [EVM simulation](https://github.com/pablosinyores/aether/blob/main/crates/simulator/src/lib.rs): `crates/simulator/src/lib.rs`
- [Fork state and caches](https://github.com/pablosinyores/aether/blob/main/crates/simulator/src/fork.rs): `crates/simulator/src/fork.rs`
- [Bytecode cache](https://github.com/pablosinyores/aether/blob/main/crates/simulator/src/bytecode_cache.rs): `crates/simulator/src/bytecode_cache.rs`
- [gRPC arb service](https://github.com/pablosinyores/aether/blob/main/crates/grpc-server/src/service.rs): `crates/grpc-server/src/service.rs`
- [Arb conversion](https://github.com/pablosinyores/aether/blob/main/crates/grpc-server/src/pipeline.rs): `crates/grpc-server/src/pipeline.rs`

### Mempool backrun

- [Pending transaction ingestion](https://github.com/pablosinyores/aether/blob/main/crates/ingestion/src/mempool.rs): `crates/ingestion/src/mempool.rs`
- [Mempool decode pipeline](https://github.com/pablosinyores/aether/blob/main/crates/grpc-server/src/mempool_pipeline.rs): `crates/grpc-server/src/mempool_pipeline.rs`
- [Victim post-state prediction](https://github.com/pablosinyores/aether/blob/main/crates/simulator/src/post_state_replay.rs): `crates/simulator/src/post_state_replay.rs`
- [Backrun validation](https://github.com/pablosinyores/aether/blob/main/crates/simulator/src/mempool_backrun.rs): `crates/simulator/src/mempool_backrun.rs`

### Go execution

- [Executor orchestration](https://github.com/pablosinyores/aether/blob/main/cmd/executor/main.go): `cmd/executor/main.go`
- [Risk management](https://github.com/pablosinyores/aether/blob/main/internal/risk/manager.go): `internal/risk/manager.go`
- [Bundle construction](https://github.com/pablosinyores/aether/blob/main/cmd/executor/bundle.go): `cmd/executor/bundle.go`
- [Builder submission](https://github.com/pablosinyores/aether/blob/main/cmd/executor/submitter.go): `cmd/executor/submitter.go`

### Persistence and operations

- [PostgreSQL ledger](https://github.com/pablosinyores/aether/blob/main/internal/db/ledger_pg.go): `internal/db/ledger_pg.go`
- [Prediction reconciliation](https://github.com/pablosinyores/aether/blob/main/cmd/reconciler/main.go): `cmd/reconciler/main.go`
- [Monitoring and alerting](https://github.com/pablosinyores/aether/tree/main/cmd/monitor): `cmd/monitor`

### Other components

- **Ethereum nodes**
- **Alchemy pending feed**
- **Block builders**
- **On-chain executor**

## Connections

- Ethereum nodes → Chain ingestion: streams events
- Chain ingestion → DEX pools and decoders: decodes updates
- DEX pools and decoders → Pool state and price graph: updates pool state
- Pool state and price graph → Engine and cycle gating: supplies graph state
- Engine and cycle gating → Cycle detection: finds cycles
- Cycle detection → EVM simulation: simulates candidates
- Fork state and caches → Bytecode cache: loads cached code (evidence: `crates/simulator/src/fork.rs`)
- EVM simulation → Fork state and caches: uses fork state (evidence: `crates/simulator/src/lib.rs`)
- Alchemy pending feed → Pending transaction ingestion: streams pending transactions
- Pending transaction ingestion → Mempool decode pipeline: feeds pending events (evidence: `crates/grpc-server/src/mempool_pipeline.rs`)
- Mempool decode pipeline → Victim post-state prediction: predicts post-state (evidence: `crates/grpc-server/src/mempool_pipeline.rs`)
- Victim post-state prediction → Backrun validation: validates backrun (evidence: `crates/simulator/src/post_state_replay.rs`)
- Backrun validation → EVM simulation: uses fork simulation (evidence: `crates/simulator/src/lib.rs`)
- Cycle detection → Arb conversion: converts opportunity (evidence: `crates/grpc-server/src/pipeline.rs`)
- EVM simulation → Arb conversion: converts simulation result (evidence: `crates/grpc-server/src/pipeline.rs`)
- Arb conversion → gRPC arb service: provides arb payload (evidence: `crates/grpc-server/src/pipeline.rs`)
- gRPC arb service → Executor orchestration: streams validated arbs
- Executor orchestration → Risk management: checks preflight (evidence: `cmd/executor/main.go`)
- Executor orchestration → Bundle construction: builds transaction bundle
- Executor orchestration → Builder submission: submits bundle
- Builder submission → Block builders: fans out bundles
- Block builders → On-chain executor: delivers transaction
- Executor orchestration → PostgreSQL ledger: persists trades
- Mempool decode pipeline → PostgreSQL ledger: persists predictions
- Prediction reconciliation → PostgreSQL ledger: reconciles predictions (evidence: `cmd/reconciler/main.go`)
- Prediction reconciliation → Monitoring and alerting: reports outcomes
