# darkhorse-techsolution/mev-lib architecture

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

- Interactive diagram: https://gitdiagram.com/darkhorse-techsolution/mev-lib
- Repository: https://github.com/darkhorse-techsolution/mev-lib

## Overview

mev-lib is a Rust utility library for Ethereum MEV tooling, not a complete bot: it provides typed DeFi primitives, AMM calculations, calldata decoding, and optional local transaction simulation. A typical consumer supplies transaction calldata to the decoder or configures a transaction and state for simulation; the library returns parsed calls or an execution result. The README also documents simulation state overrides, forking, and tracing. Those broader capabilities are represented, but unsampled implementation details and their wiring are not asserted.

Main entry points: [`src/decoder/mod.rs`](https://github.com/darkhorse-techsolution/mev-lib/blob/main/src/decoder/mod.rs) (Calldata decoder), [`src/simulation/executor.rs`](https://github.com/darkhorse-techsolution/mev-lib/blob/main/src/simulation/executor.rs) (EVM executor), [`src/decoder/selector.rs`](https://github.com/darkhorse-techsolution/mev-lib/blob/main/src/decoder/selector.rs) (Method selectors), [`src/decoder/uniswap_v2.rs`](https://github.com/darkhorse-techsolution/mev-lib/blob/main/src/decoder/uniswap_v2.rs) (Uniswap V2 decoder)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_primitives["Core primitives"]
  node_token["Token types<br/>[token.rs]"]
  node_pool["Pool and reserves<br/>[pool.rs]"]
  node_swap["Swap types<br/>[swap.rs]"]
end

subgraph group_decode["Calldata decoding"]
  node_decode_api["Calldata decoder<br/>[mod.rs]"]
  node_selector["Method selectors<br/>[selector.rs]"]
  node_v2decode["Uniswap V2 decoder<br/>[uniswap_v2.rs]"]
  node_v3decode["Uniswap V3 decoder<br/>[uniswap_v3.rs]"]
  node_erc20decode["ERC20 decoder<br/>[erc20.rs]"]
end

subgraph group_amm["AMM calculations"]
  node_v2math["Uniswap V2 math<br/>[uniswap_v2.rs]"]
end

subgraph group_sim["Transaction simulation"]
  node_sim_api["Simulation inputs<br/>[types.rs]"]
  node_executor["EVM executor<br/>[executor.rs]"]
  node_sim_result["Execution results<br/>[result.rs]"]
  node_state_override["State overrides<br/>[types.rs]"]
  node_state_fork[("Forked state")]
end

node_consumer(("Library consumer"))

node_consumer -->|"submits calldata"| node_decode_api
node_decode_api -->|"tries V2"| node_v2decode
node_decode_api -->|"tries V3"| node_v3decode
node_decode_api -->|"tries ERC20"| node_erc20decode
node_v2decode -->|"matches selectors"| node_selector
node_v3decode -->|"uses selectors"| node_selector
node_erc20decode -->|"uses selectors"| node_selector
node_decode_api -->|"returns decoded call"| node_consumer
node_consumer -->|"calculates swap outputs"| node_v2math
node_consumer -->|"configures transaction"| node_sim_api
node_consumer -->|"requests simulation"| node_executor
node_executor -->|"reads inputs"| node_sim_api
node_executor -->|"produces result"| node_sim_result
node_consumer -->|"sets state overrides"| node_state_override
node_consumer -->|"uses forked state"| node_state_fork

click node_token "https://github.com/darkhorse-techsolution/mev-lib/blob/main/src/types/token.rs"
click node_pool "https://github.com/darkhorse-techsolution/mev-lib/blob/main/src/types/pool.rs"
click node_swap "https://github.com/darkhorse-techsolution/mev-lib/blob/main/src/types/swap.rs"
click node_decode_api "https://github.com/darkhorse-techsolution/mev-lib/blob/main/src/decoder/mod.rs"
click node_selector "https://github.com/darkhorse-techsolution/mev-lib/blob/main/src/decoder/selector.rs"
click node_v2decode "https://github.com/darkhorse-techsolution/mev-lib/blob/main/src/decoder/uniswap_v2.rs"
click node_v3decode "https://github.com/darkhorse-techsolution/mev-lib/blob/main/src/decoder/uniswap_v3.rs"
click node_erc20decode "https://github.com/darkhorse-techsolution/mev-lib/blob/main/src/decoder/erc20.rs"
click node_v2math "https://github.com/darkhorse-techsolution/mev-lib/blob/main/src/math/uniswap_v2.rs"
click node_sim_api "https://github.com/darkhorse-techsolution/mev-lib/blob/main/src/simulation/types.rs"
click node_executor "https://github.com/darkhorse-techsolution/mev-lib/blob/main/src/simulation/executor.rs"
click node_sim_result "https://github.com/darkhorse-techsolution/mev-lib/blob/main/src/simulation/result.rs"
click node_state_override "https://github.com/darkhorse-techsolution/mev-lib/blob/main/src/simulation/types.rs"
click node_state_fork "https://github.com/darkhorse-techsolution/mev-lib/tree/main/src/simulation"

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_token,node_pool,node_swap toneBlue
class node_decode_api,node_selector,node_v2decode,node_v3decode,node_erc20decode toneAmber
class node_v2math toneMint
class node_sim_api,node_executor,node_sim_result,node_state_override,node_state_fork toneRose
class node_consumer toneIndigo
```

## Components

### Core primitives

- [Token types](https://github.com/darkhorse-techsolution/mev-lib/blob/main/src/types/token.rs): `src/types/token.rs`
- [Pool and reserves](https://github.com/darkhorse-techsolution/mev-lib/blob/main/src/types/pool.rs): `src/types/pool.rs`
- [Swap types](https://github.com/darkhorse-techsolution/mev-lib/blob/main/src/types/swap.rs): `src/types/swap.rs`

### Calldata decoding

- [Calldata decoder](https://github.com/darkhorse-techsolution/mev-lib/blob/main/src/decoder/mod.rs): `src/decoder/mod.rs`
- [Method selectors](https://github.com/darkhorse-techsolution/mev-lib/blob/main/src/decoder/selector.rs): `src/decoder/selector.rs`
- [Uniswap V2 decoder](https://github.com/darkhorse-techsolution/mev-lib/blob/main/src/decoder/uniswap_v2.rs): `src/decoder/uniswap_v2.rs`
- [Uniswap V3 decoder](https://github.com/darkhorse-techsolution/mev-lib/blob/main/src/decoder/uniswap_v3.rs): `src/decoder/uniswap_v3.rs`
- [ERC20 decoder](https://github.com/darkhorse-techsolution/mev-lib/blob/main/src/decoder/erc20.rs): `src/decoder/erc20.rs`

### AMM calculations

- [Uniswap V2 math](https://github.com/darkhorse-techsolution/mev-lib/blob/main/src/math/uniswap_v2.rs): `src/math/uniswap_v2.rs`

### Transaction simulation

- [Simulation inputs](https://github.com/darkhorse-techsolution/mev-lib/blob/main/src/simulation/types.rs): `src/simulation/types.rs`
- [EVM executor](https://github.com/darkhorse-techsolution/mev-lib/blob/main/src/simulation/executor.rs): `src/simulation/executor.rs`
- [Execution results](https://github.com/darkhorse-techsolution/mev-lib/blob/main/src/simulation/result.rs): `src/simulation/result.rs`
- [State overrides](https://github.com/darkhorse-techsolution/mev-lib/blob/main/src/simulation/types.rs): `src/simulation/types.rs`
- [Forked state](https://github.com/darkhorse-techsolution/mev-lib/tree/main/src/simulation): `src/simulation`

### Other components

- **Library consumer**

## Connections

- Library consumer → Calldata decoder: submits calldata (evidence: `README.md`)
- Calldata decoder → Uniswap V2 decoder: tries V2 (evidence: `src/decoder/mod.rs`)
- Calldata decoder → Uniswap V3 decoder: tries V3 (evidence: `src/decoder/mod.rs`)
- Calldata decoder → ERC20 decoder: tries ERC20 (evidence: `src/decoder/mod.rs`)
- Uniswap V2 decoder → Method selectors: matches selectors (evidence: `src/decoder/uniswap_v2.rs`)
- Uniswap V3 decoder → Method selectors: uses selectors (evidence: `src/decoder/uniswap_v3.rs`)
- ERC20 decoder → Method selectors: uses selectors (evidence: `src/decoder/erc20.rs`)
- Calldata decoder → Library consumer: returns decoded call (evidence: `src/decoder/mod.rs`)
- Library consumer → Uniswap V2 math: calculates swap outputs (evidence: `README.md`)
- Library consumer → Simulation inputs: configures transaction (evidence: `README.md`)
- Library consumer → EVM executor: requests simulation (evidence: `README.md`)
- EVM executor → Simulation inputs: reads inputs (evidence: `src/simulation/executor.rs`)
- EVM executor → Execution results: produces result (evidence: `README.md`)
- Library consumer → State overrides: sets state overrides (evidence: `README.md`)
- Library consumer → Forked state: uses forked state (evidence: `src/simulation/mod.rs`)
