# btcsuite/btcd architecture

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

- Interactive diagram: https://gitdiagram.com/btcsuite/btcd
- Repository: https://github.com/btcsuite/btcd

## Overview

btcd is a Go Bitcoin full node, not a wallet. Its main workflow accepts peer connections, synchronizes blocks and transactions, validates blocks into chain state, persists that state, and relays transactions and newly mined blocks. Mining, indexing, and JSON-RPC are important companion capabilities. The graph emphasizes relationships visible in the supplied excerpts, SOURCE INDEX references, and README; some runtime wiring is unsampled, so uncertain links are omitted or marked unverified.

Main entry points: [`server.go`](https://github.com/btcsuite/btcd/blob/master/server.go) (Node server), [`blockchain/chain.go`](https://github.com/btcsuite/btcd/blob/master/blockchain/chain.go) (Block validation), [`mining/mining.go`](https://github.com/btcsuite/btcd/blob/master/mining/mining.go) (Block templates), [`mempool/mempool.go`](https://github.com/btcsuite/btcd/blob/master/mempool/mempool.go) (Transaction pool)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_network["Peer networking"]
  node_server["Node server<br/>[server.go]"]
  node_peers["Peer connections<br/>[peer.go]"]
  node_peerdiscovery["Peer management<br/>[addrmanager.go]"]
  node_sync["Chain synchronization<br/>[manager.go]"]
  node_protocol["Bitcoin messages<br/>[message.go]"]
end

subgraph group_chain["Chain and storage"]
  node_chainproc["Block validation<br/>[chain.go]"]
  node_consensus["Consensus checks<br/>[validate.go]"]
  node_blockdb[("Block database<br/>[db.go]")]
  node_indexing["Chain indexes<br/>[manager.go]"]
end

subgraph group_txmining["Transactions and mining"]
  node_txpool[("Transaction pool<br/>[mempool.go]")]
  node_mining["Block templates<br/>[mining.go]"]
  node_cpuminer["CPU mining<br/>[cpuminer.go]"]
  node_script["Script execution<br/>[engine.go]"]
end

subgraph group_interfaces["Node interfaces"]
  node_rpcserver["JSON-RPC server<br/>[rpcserver.go]"]
  node_jsonapi["RPC command types<br/>[chainsvrcmds.go]"]
  node_ctl["RPC command-line client<br/>[httpclient.go]"]
  node_rpcclient["RPC client library<br/>[wallet.go]"]
end

node_operator(("Node operator"))
node_miner(("Miner"))
node_rpcuser(("RPC user"))

node_operator -->|"starts"| node_server
node_server -->|"configures"| node_peers
node_server -->|"configures"| node_peerdiscovery
node_server -->|"configures"| node_sync
node_server -->|"configures"| node_blockdb
node_server -->|"configures"| node_txpool
node_server -->|"configures"| node_mining
node_peers -.->|"exchanges"| node_protocol
node_sync -->|"processes blocks"| node_chainproc
node_sync -.->|"checks inventory"| node_txpool
node_chainproc -->|"reads and writes"| node_blockdb
node_chainproc -.->|"validates"| node_consensus
node_chainproc -.->|"updates"| node_indexing
node_indexing -->|"reads and writes"| node_blockdb
node_txpool -->|"checks inputs"| node_chainproc
node_txpool -->|"supplies transactions"| node_mining
node_mining -->|"queries chain"| node_chainproc
node_cpuminer -->|"requests templates"| node_mining
node_miner -.->|"runs"| node_cpuminer
node_mining -.->|"validates scripts"| node_script
node_rpcuser -->|"issues commands"| node_ctl
node_ctl -.->|"sends HTTP requests"| node_rpcserver
node_rpcserver -.->|"dispatches commands"| node_jsonapi
node_rpcclient -->|"builds commands"| node_jsonapi

click node_server "https://github.com/btcsuite/btcd/blob/master/server.go"
click node_peers "https://github.com/btcsuite/btcd/blob/master/peer/peer.go"
click node_peerdiscovery "https://github.com/btcsuite/btcd/blob/master/addrmgr/addrmanager.go"
click node_sync "https://github.com/btcsuite/btcd/blob/master/netsync/manager.go"
click node_protocol "https://github.com/btcsuite/btcd/blob/master/wire/message.go"
click node_chainproc "https://github.com/btcsuite/btcd/blob/master/blockchain/chain.go"
click node_consensus "https://github.com/btcsuite/btcd/blob/master/blockchain/validate.go"
click node_blockdb "https://github.com/btcsuite/btcd/blob/master/database/ffldb/db.go"
click node_indexing "https://github.com/btcsuite/btcd/blob/master/blockchain/indexers/manager.go"
click node_txpool "https://github.com/btcsuite/btcd/blob/master/mempool/mempool.go"
click node_mining "https://github.com/btcsuite/btcd/blob/master/mining/mining.go"
click node_cpuminer "https://github.com/btcsuite/btcd/blob/master/mining/cpuminer/cpuminer.go"
click node_script "https://github.com/btcsuite/btcd/blob/master/txscript/engine.go"
click node_rpcserver "https://github.com/btcsuite/btcd/blob/master/rpcserver.go"
click node_jsonapi "https://github.com/btcsuite/btcd/blob/master/btcjson/chainsvrcmds.go"
click node_ctl "https://github.com/btcsuite/btcd/blob/master/cmd/btcctl/httpclient.go"
click node_rpcclient "https://github.com/btcsuite/btcd/blob/master/rpcclient/wallet.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_server,node_peers,node_peerdiscovery,node_sync,node_protocol,node_rpcuser toneBlue
class node_chainproc,node_consensus,node_blockdb,node_indexing toneAmber
class node_txpool,node_mining,node_cpuminer,node_script toneMint
class node_rpcserver,node_jsonapi,node_ctl,node_rpcclient toneRose
class node_operator,node_miner toneIndigo
```

## Components

### Peer networking

- [Node server](https://github.com/btcsuite/btcd/blob/master/server.go): `server.go`
- [Peer connections](https://github.com/btcsuite/btcd/blob/master/peer/peer.go): `peer/peer.go`
- [Peer management](https://github.com/btcsuite/btcd/blob/master/addrmgr/addrmanager.go): `addrmgr/addrmanager.go`
- [Chain synchronization](https://github.com/btcsuite/btcd/blob/master/netsync/manager.go): `netsync/manager.go`
- [Bitcoin messages](https://github.com/btcsuite/btcd/blob/master/wire/message.go): `wire/message.go`

### Chain and storage

- [Block validation](https://github.com/btcsuite/btcd/blob/master/blockchain/chain.go): `blockchain/chain.go`
- [Consensus checks](https://github.com/btcsuite/btcd/blob/master/blockchain/validate.go): `blockchain/validate.go`
- [Block database](https://github.com/btcsuite/btcd/blob/master/database/ffldb/db.go): `database/ffldb/db.go`
- [Chain indexes](https://github.com/btcsuite/btcd/blob/master/blockchain/indexers/manager.go): `blockchain/indexers/manager.go`

### Transactions and mining

- [Transaction pool](https://github.com/btcsuite/btcd/blob/master/mempool/mempool.go): `mempool/mempool.go`
- [Block templates](https://github.com/btcsuite/btcd/blob/master/mining/mining.go): `mining/mining.go`
- [CPU mining](https://github.com/btcsuite/btcd/blob/master/mining/cpuminer/cpuminer.go): `mining/cpuminer/cpuminer.go`
- [Script execution](https://github.com/btcsuite/btcd/blob/master/txscript/engine.go): `txscript/engine.go`

### Node interfaces

- [JSON-RPC server](https://github.com/btcsuite/btcd/blob/master/rpcserver.go): `rpcserver.go`
- [RPC command types](https://github.com/btcsuite/btcd/blob/master/btcjson/chainsvrcmds.go): `btcjson/chainsvrcmds.go`
- [RPC command-line client](https://github.com/btcsuite/btcd/blob/master/cmd/btcctl/httpclient.go): `cmd/btcctl/httpclient.go`
- [RPC client library](https://github.com/btcsuite/btcd/blob/master/rpcclient/wallet.go): `rpcclient/wallet.go`

### Other components

- **Node operator**
- **Miner**
- **RPC user**

## Connections

- Node operator → Node server: starts
- Node server → Peer connections: configures (evidence: `server.go`)
- Node server → Peer management: configures (evidence: `server.go`)
- Node server → Chain synchronization: configures (evidence: `server.go`)
- Node server → Block database: configures (evidence: `server.go`)
- Node server → Transaction pool: configures (evidence: `server.go`)
- Node server → Block templates: configures (evidence: `server.go`)
- Peer connections → Bitcoin messages: exchanges
- Chain synchronization → Block validation: processes blocks (evidence: `netsync/manager.go`)
- Chain synchronization → Transaction pool: checks inventory
- Block validation → Block database: reads and writes (evidence: `blockchain/chain.go`)
- Block validation → Consensus checks: validates
- Block validation → Chain indexes: updates
- Chain indexes → Block database: reads and writes (evidence: `blockchain/indexers/manager.go`)
- Transaction pool → Block validation: checks inputs (evidence: `mempool/mempool.go`)
- Transaction pool → Block templates: supplies transactions (evidence: `mempool/mempool.go`)
- Block templates → Block validation: queries chain (evidence: `mining/mining.go`)
- CPU mining → Block templates: requests templates (evidence: `mining/cpuminer/cpuminer.go`)
- Miner → CPU mining: runs
- Block templates → Script execution: validates scripts
- RPC user → RPC command-line client: issues commands (evidence: `cmd/btcctl/httpclient.go`)
- RPC command-line client → JSON-RPC server: sends HTTP requests
- JSON-RPC server → RPC command types: dispatches commands
- RPC client library → RPC command types: builds commands (evidence: `rpcclient/wallet.go`)
