# epiccash/epic architecture

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

- Interactive diagram: https://gitdiagram.com/epiccash/epic
- Repository: https://github.com/epiccash/epic

## Overview

Epic is a MimbleWimble blockchain node: an operator starts the server, which participates in peer networking, synchronizes and validates chain state, and can expose APIs or produce blocks. The graph separates protocol/core validation, chain state, networking, server operations, and client-facing APIs. Several subsystem links are documented at the product level; where sampled files do not show the runtime wiring, those links are omitted rather than inferred.

Main entry points: [`chain/src/chain.rs`](https://github.com/epiccash/epic/blob/master/chain/src/chain.rs) (Chain Validation), [`servers/src/epic/server.rs`](https://github.com/epiccash/epic/blob/master/servers/src/epic/server.rs) (Epic Server), [`p2p/src/serv.rs`](https://github.com/epiccash/epic/blob/master/p2p/src/serv.rs) (Peer Service), [`src/bin/cmd/server.rs`](https://github.com/epiccash/epic/blob/master/src/bin/cmd/server.rs) (Command Line)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_operations["Node Operations"]
  node_cli["Command Line<br/>[server.rs]"]
  node_server["Epic Server<br/>[server.rs]"]
  node_sync["Chain Sync"]
  node_mining["Mining Services"]
end

subgraph group_network["Peer Networking"]
  node_p2p["Peer Service<br/>[serv.rs]"]
  node_peers["Peer Management<br/>[peers.rs]"]
  node_protocol_net["Peer Protocol<br/>[protocol.rs]"]
end

subgraph group_chain["Chain Processing"]
  node_chain_core["Chain Validation<br/>[chain.rs]"]
  node_block_pipe["Block Processing<br/>[pipe.rs]"]
  node_txhashset["UTXO State<br/>[txhashset.rs]"]
  node_chain_store[("Chain Store<br/>[store.rs]")]
end

subgraph group_protocol["Blockchain Protocol"]
  node_consensus["Consensus Rules<br/>[consensus.rs]"]
  node_transactions["Transaction Model<br/>[transaction.rs]"]
  node_serialization["Core Serialization<br/>[ser.rs]"]
end

subgraph group_interfaces["Node Interfaces"]
  node_api_server["HTTP API Server<br/>[rest.rs]"]
  node_router["Request Router<br/>[router.rs]"]
  node_api_handlers["API Handlers<br/>[handlers.rs]"]
  node_foreign_rpc["Foreign RPC<br/>[foreign_rpc.rs]"]
  node_foreign_api["Foreign API<br/>[foreign.rs]"]
end

node_operator(("Node Operator"))

node_operator -->|"starts node"| node_cli
node_cli -.->|"runs server"| node_server
node_server -->|"starts synchronization"| node_sync
node_server -->|"starts mining"| node_mining
node_server -->|"participates in network"| node_p2p
node_server -->|"validates blocks"| node_chain_core
node_p2p -.->|"manages peers"| node_peers
node_p2p -.->|"exchanges messages"| node_protocol_net
node_chain_core -.->|"processes blocks"| node_block_pipe
node_chain_core -.->|"maintains state"| node_txhashset
node_chain_core -.->|"persists chain data"| node_chain_store
node_consensus -.->|"defines validation rules"| node_chain_core
node_transactions -.->|"provides transaction model"| node_chain_core
node_operator -->|"uses node API"| node_api_server
node_api_server -->|"serves routed requests"| node_router
node_router -->|"dispatches routes"| node_api_handlers
node_api_handlers -->|"handles RPC requests"| node_foreign_rpc
node_foreign_rpc -->|"delegates API calls"| node_foreign_api
node_foreign_api -.->|"accepts transactions"| node_transactions
node_protocol_net -.->|"encodes protocol data"| node_serialization

click node_cli "https://github.com/epiccash/epic/blob/master/src/bin/cmd/server.rs"
click node_server "https://github.com/epiccash/epic/blob/master/servers/src/epic/server.rs"
click node_sync "https://github.com/epiccash/epic/tree/master/servers/src/epic/sync"
click node_mining "https://github.com/epiccash/epic/tree/master/servers/src/mining"
click node_p2p "https://github.com/epiccash/epic/blob/master/p2p/src/serv.rs"
click node_peers "https://github.com/epiccash/epic/blob/master/p2p/src/peers.rs"
click node_protocol_net "https://github.com/epiccash/epic/blob/master/p2p/src/protocol.rs"
click node_chain_core "https://github.com/epiccash/epic/blob/master/chain/src/chain.rs"
click node_block_pipe "https://github.com/epiccash/epic/blob/master/chain/src/pipe.rs"
click node_txhashset "https://github.com/epiccash/epic/blob/master/chain/src/txhashset/txhashset.rs"
click node_chain_store "https://github.com/epiccash/epic/blob/master/chain/src/store.rs"
click node_consensus "https://github.com/epiccash/epic/blob/master/core/src/consensus.rs"
click node_transactions "https://github.com/epiccash/epic/blob/master/core/src/core/transaction.rs"
click node_serialization "https://github.com/epiccash/epic/blob/master/core/src/ser.rs"
click node_api_server "https://github.com/epiccash/epic/blob/master/api/src/rest.rs"
click node_router "https://github.com/epiccash/epic/blob/master/api/src/router.rs"
click node_api_handlers "https://github.com/epiccash/epic/blob/master/api/src/handlers.rs"
click node_foreign_rpc "https://github.com/epiccash/epic/blob/master/api/src/foreign_rpc.rs"
click node_foreign_api "https://github.com/epiccash/epic/blob/master/api/src/foreign.rs"

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_cli,node_server,node_sync,node_mining toneBlue
class node_p2p,node_peers,node_protocol_net toneAmber
class node_chain_core,node_block_pipe,node_txhashset,node_chain_store toneMint
class node_consensus,node_transactions,node_serialization toneRose
class node_api_server,node_router,node_api_handlers,node_foreign_rpc,node_foreign_api,node_operator toneIndigo
```

## Components

### Node Operations

- [Command Line](https://github.com/epiccash/epic/blob/master/src/bin/cmd/server.rs): `src/bin/cmd/server.rs`
- [Epic Server](https://github.com/epiccash/epic/blob/master/servers/src/epic/server.rs): `servers/src/epic/server.rs`
- [Chain Sync](https://github.com/epiccash/epic/tree/master/servers/src/epic/sync): `servers/src/epic/sync`
- [Mining Services](https://github.com/epiccash/epic/tree/master/servers/src/mining): `servers/src/mining`

### Peer Networking

- [Peer Service](https://github.com/epiccash/epic/blob/master/p2p/src/serv.rs): `p2p/src/serv.rs`
- [Peer Management](https://github.com/epiccash/epic/blob/master/p2p/src/peers.rs): `p2p/src/peers.rs`
- [Peer Protocol](https://github.com/epiccash/epic/blob/master/p2p/src/protocol.rs): `p2p/src/protocol.rs`

### Chain Processing

- [Chain Validation](https://github.com/epiccash/epic/blob/master/chain/src/chain.rs): `chain/src/chain.rs`
- [Block Processing](https://github.com/epiccash/epic/blob/master/chain/src/pipe.rs): `chain/src/pipe.rs`
- [UTXO State](https://github.com/epiccash/epic/blob/master/chain/src/txhashset/txhashset.rs): `chain/src/txhashset/txhashset.rs`
- [Chain Store](https://github.com/epiccash/epic/blob/master/chain/src/store.rs): `chain/src/store.rs`

### Blockchain Protocol

- [Consensus Rules](https://github.com/epiccash/epic/blob/master/core/src/consensus.rs): `core/src/consensus.rs`
- [Transaction Model](https://github.com/epiccash/epic/blob/master/core/src/core/transaction.rs): `core/src/core/transaction.rs`
- [Core Serialization](https://github.com/epiccash/epic/blob/master/core/src/ser.rs): `core/src/ser.rs`

### Node Interfaces

- [HTTP API Server](https://github.com/epiccash/epic/blob/master/api/src/rest.rs): `api/src/rest.rs`
- [Request Router](https://github.com/epiccash/epic/blob/master/api/src/router.rs): `api/src/router.rs`
- [API Handlers](https://github.com/epiccash/epic/blob/master/api/src/handlers.rs): `api/src/handlers.rs`
- [Foreign RPC](https://github.com/epiccash/epic/blob/master/api/src/foreign_rpc.rs): `api/src/foreign_rpc.rs`
- [Foreign API](https://github.com/epiccash/epic/blob/master/api/src/foreign.rs): `api/src/foreign.rs`

### Other components

- **Node Operator**

## Connections

- Node Operator → Command Line: starts node (evidence: `README.md`)
- Command Line → Epic Server: runs server
- Epic Server → Chain Sync: starts synchronization (evidence: `servers/src/epic/server.rs`)
- Epic Server → Mining Services: starts mining (evidence: `servers/src/epic/server.rs`)
- Epic Server → Peer Service: participates in network (evidence: `README.md`)
- Epic Server → Chain Validation: validates blocks (evidence: `README.md`)
- Peer Service → Peer Management: manages peers
- Peer Service → Peer Protocol: exchanges messages
- Chain Validation → Block Processing: processes blocks
- Chain Validation → UTXO State: maintains state
- Chain Validation → Chain Store: persists chain data
- Consensus Rules → Chain Validation: defines validation rules
- Transaction Model → Chain Validation: provides transaction model
- Node Operator → HTTP API Server: uses node API (evidence: `README.md`)
- HTTP API Server → Request Router: serves routed requests (evidence: `api/src/rest.rs`)
- Request Router → API Handlers: dispatches routes (evidence: `api/src/handlers.rs`)
- API Handlers → Foreign RPC: handles RPC requests (evidence: `api/src/handlers.rs`)
- Foreign RPC → Foreign API: delegates API calls (evidence: `api/src/foreign_rpc.rs`)
- Foreign API → Transaction Model: accepts transactions
- Peer Protocol → Core Serialization: encodes protocol data
