# hemilabs/heminetwork architecture

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

- Interactive diagram: https://gitdiagram.com/hemilabs/heminetwork
- Repository: https://github.com/hemilabs/heminetwork

## Overview

Hemi Network’s core daemons provide Bitcoin-node RPC and indexing, Bitcoin finality queries, PoP mining, and RPC balancing for Hemi execution nodes. The main user-facing path is an RPC request to tbcd, handled by its service and exposed through the TBC API; indexing and database components support node data queries. Other daemon capabilities are shown as separate branches. The graph follows documented capabilities and indexed imports; unsampled internals are omitted where their call relationships cannot be verified.

Main entry points: [`api/tbcapi/tbcapi.go`](https://github.com/hemilabs/heminetwork/blob/main/api/tbcapi/tbcapi.go) (Bitcoin RPC), [`service/bfg/bfg.go`](https://github.com/hemilabs/heminetwork/blob/main/service/bfg/bfg.go) (Finality Service), [`service/popm/popm.go`](https://github.com/hemilabs/heminetwork/blob/main/service/popm/popm.go) (PoP Miner), [`service/hproxy/hproxy.go`](https://github.com/hemilabs/heminetwork/blob/main/service/hproxy/hproxy.go) (RPC Proxy)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_node["Bitcoin Node"]
  node_tbcdcmd["tbcd Daemon<br/>[tbcd.go]"]
  node_tbcservice["Node Service<br/>[tbc.go]"]
  node_tbcapi["Bitcoin RPC<br/>[tbcapi.go]"]
  node_peer["Peer Manager<br/>[peermanager.go]"]
  node_ordinal["Ordinal Queries<br/>[ordinalquery.go]"]
  node_tbcddata[("Node Database<br/>[database.go]")]
  node_leveldb[("Level Storage<br/>[level.go]")]
end

subgraph group_finality["Finality Service"]
  node_bfgd["bfgd Daemon<br/>[bfgd.go]"]
  node_bfg["Finality Service<br/>[bfg.go]"]
end

subgraph group_mining["PoP Mining"]
  node_popmd["popmd Daemon<br/>[popmd.go]"]
  node_popm["PoP Miner<br/>[popm.go]"]
  node_wallet["Bitcoin Wallet<br/>[wallet.go]"]
end

subgraph group_proxy["RPC Proxy"]
  node_hproxyd["hproxyd Daemon<br/>[hproxyd.go]"]
  node_hproxy["RPC Proxy<br/>[hproxy.go]"]
end

subgraph group_shared["Shared Protocol"]
  node_protocol["RPC Protocol<br/>[protocol.go]"]
  node_keystone["Keystone Types<br/>[hemi.go]"]
  node_hemictl["Network CLI<br/>[hemictl.go]"]
end

node_user(("RPC User"))
node_opgeth["Hemi Execution Node"]
node_bitcoin(("Bitcoin Network"))
node_heminode["Hemi RPC Nodes"]

node_user -->|"starts node"| node_tbcdcmd
node_tbcdcmd -->|"runs service"| node_tbcservice
node_user -.->|"requests RPC"| node_tbcapi
node_ordinal -->|"reads blocks"| node_tbcddata
node_tbcddata -.->|"stores records"| node_leveldb
node_bfgd -->|"runs service"| node_bfg
node_bfg -->|"queries RPC"| node_opgeth
node_bfg -.->|"reads Bitcoin data"| node_bitcoin
node_popmd -->|"runs service"| node_popm
node_popm -->|"reads L2 data"| node_opgeth
node_popm -->|"uses wallet"| node_wallet
node_wallet -.->|"builds transactions"| node_bitcoin
node_hproxyd -->|"runs proxy"| node_hproxy
node_hproxy -->|"proxies requests"| node_heminode
node_tbcapi -->|"uses messages"| node_protocol
node_tbcapi -->|"exchanges types"| node_keystone
node_hemictl -->|"uses RPC"| node_tbcapi
node_hemictl -->|"controls proxy"| node_hproxy

click node_tbcdcmd "https://github.com/hemilabs/heminetwork/blob/main/cmd/tbcd/tbcd.go"
click node_tbcservice "https://github.com/hemilabs/heminetwork/blob/main/service/tbc/tbc.go"
click node_tbcapi "https://github.com/hemilabs/heminetwork/blob/main/api/tbcapi/tbcapi.go"
click node_peer "https://github.com/hemilabs/heminetwork/blob/main/service/tbc/peermanager.go"
click node_ordinal "https://github.com/hemilabs/heminetwork/blob/main/service/tbc/ordinalquery.go"
click node_tbcddata "https://github.com/hemilabs/heminetwork/blob/main/database/tbcd/database.go"
click node_leveldb "https://github.com/hemilabs/heminetwork/blob/main/database/tbcd/level/level.go"
click node_bfgd "https://github.com/hemilabs/heminetwork/blob/main/cmd/bfgd/bfgd.go"
click node_bfg "https://github.com/hemilabs/heminetwork/blob/main/service/bfg/bfg.go"
click node_popmd "https://github.com/hemilabs/heminetwork/blob/main/cmd/popmd/popmd.go"
click node_popm "https://github.com/hemilabs/heminetwork/blob/main/service/popm/popm.go"
click node_wallet "https://github.com/hemilabs/heminetwork/blob/main/bitcoin/wallet/wallet.go"
click node_hproxyd "https://github.com/hemilabs/heminetwork/blob/main/cmd/hproxyd/hproxyd.go"
click node_hproxy "https://github.com/hemilabs/heminetwork/blob/main/service/hproxy/hproxy.go"
click node_protocol "https://github.com/hemilabs/heminetwork/blob/main/api/protocol/protocol.go"
click node_keystone "https://github.com/hemilabs/heminetwork/blob/main/hemi/hemi.go"
click node_hemictl "https://github.com/hemilabs/heminetwork/blob/main/cmd/hemictl/hemictl.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_tbcdcmd,node_tbcservice,node_tbcapi,node_peer,node_ordinal,node_tbcddata,node_leveldb,node_user toneBlue
class node_bfgd,node_bfg toneAmber
class node_popmd,node_popm,node_wallet toneMint
class node_hproxyd,node_hproxy toneRose
class node_protocol,node_keystone,node_hemictl,node_opgeth,node_bitcoin,node_heminode toneIndigo
```

## Components

### Bitcoin Node

- [tbcd Daemon](https://github.com/hemilabs/heminetwork/blob/main/cmd/tbcd/tbcd.go): `cmd/tbcd/tbcd.go`
- [Node Service](https://github.com/hemilabs/heminetwork/blob/main/service/tbc/tbc.go): `service/tbc/tbc.go`
- [Bitcoin RPC](https://github.com/hemilabs/heminetwork/blob/main/api/tbcapi/tbcapi.go): `api/tbcapi/tbcapi.go`
- [Peer Manager](https://github.com/hemilabs/heminetwork/blob/main/service/tbc/peermanager.go): `service/tbc/peermanager.go`
- [Ordinal Queries](https://github.com/hemilabs/heminetwork/blob/main/service/tbc/ordinalquery.go): `service/tbc/ordinalquery.go`
- [Node Database](https://github.com/hemilabs/heminetwork/blob/main/database/tbcd/database.go): `database/tbcd/database.go`
- [Level Storage](https://github.com/hemilabs/heminetwork/blob/main/database/tbcd/level/level.go): `database/tbcd/level/level.go`

### Finality Service

- [bfgd Daemon](https://github.com/hemilabs/heminetwork/blob/main/cmd/bfgd/bfgd.go): `cmd/bfgd/bfgd.go`
- [Finality Service](https://github.com/hemilabs/heminetwork/blob/main/service/bfg/bfg.go): `service/bfg/bfg.go`

### PoP Mining

- [popmd Daemon](https://github.com/hemilabs/heminetwork/blob/main/cmd/popmd/popmd.go): `cmd/popmd/popmd.go`
- [PoP Miner](https://github.com/hemilabs/heminetwork/blob/main/service/popm/popm.go): `service/popm/popm.go`
- [Bitcoin Wallet](https://github.com/hemilabs/heminetwork/blob/main/bitcoin/wallet/wallet.go): `bitcoin/wallet/wallet.go`

### RPC Proxy

- [hproxyd Daemon](https://github.com/hemilabs/heminetwork/blob/main/cmd/hproxyd/hproxyd.go): `cmd/hproxyd/hproxyd.go`
- [RPC Proxy](https://github.com/hemilabs/heminetwork/blob/main/service/hproxy/hproxy.go): `service/hproxy/hproxy.go`

### Shared Protocol

- [RPC Protocol](https://github.com/hemilabs/heminetwork/blob/main/api/protocol/protocol.go): `api/protocol/protocol.go`
- [Keystone Types](https://github.com/hemilabs/heminetwork/blob/main/hemi/hemi.go): `hemi/hemi.go`
- [Network CLI](https://github.com/hemilabs/heminetwork/blob/main/cmd/hemictl/hemictl.go): `cmd/hemictl/hemictl.go`

### Other components

- **RPC User**
- **Hemi Execution Node**
- **Bitcoin Network**
- **Hemi RPC Nodes**

## Connections

- RPC User → tbcd Daemon: starts node (evidence: `README.md`)
- tbcd Daemon → Node Service: runs service (evidence: `cmd/tbcd/tbcd.go`)
- RPC User → Bitcoin RPC: requests RPC
- Ordinal Queries → Node Database: reads blocks (evidence: `service/tbc/ordinalquery.go`)
- Node Database → Level Storage: stores records
- bfgd Daemon → Finality Service: runs service (evidence: `cmd/bfgd/bfgd.go`)
- Finality Service → Hemi Execution Node: queries RPC (evidence: `service/bfg/bfg.go`)
- Finality Service → Bitcoin Network: reads Bitcoin data
- popmd Daemon → PoP Miner: runs service (evidence: `cmd/popmd/popmd.go`)
- PoP Miner → Hemi Execution Node: reads L2 data (evidence: `service/popm/popm.go`)
- PoP Miner → Bitcoin Wallet: uses wallet (evidence: `service/popm/popm.go`)
- Bitcoin Wallet → Bitcoin Network: builds transactions
- hproxyd Daemon → RPC Proxy: runs proxy (evidence: `cmd/hproxyd/hproxyd.go`)
- RPC Proxy → Hemi RPC Nodes: proxies requests (evidence: `service/hproxy/hproxy.go`)
- Bitcoin RPC → RPC Protocol: uses messages (evidence: `api/tbcapi/tbcapi.go`)
- Bitcoin RPC → Keystone Types: exchanges types (evidence: `api/tbcapi/tbcapi.go`)
- Network CLI → Bitcoin RPC: uses RPC (evidence: `cmd/hemictl/hemictl.go`)
- Network CLI → RPC Proxy: controls proxy (evidence: `cmd/hemictl/hemictl.go`)
