# spacemeshos/go-spacemesh architecture

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

- Interactive diagram: https://gitdiagram.com/spacemeshos/go-spacemesh
- Repository: https://github.com/spacemeshos/go-spacemesh

## Overview

go-spacemesh is a Go implementation of the Spacemesh peer-to-peer full node: it participates in consensus, maintains blockchain state, and exposes node services to operators and applications. A typical transaction workflow starts at the public gRPC API, enters transaction handling, and is incorporated into the mesh and processed by the VM; consensus and peer synchronization supply and validate chain data. The tree and README establish the major subsystems, but most implementation excerpts were not sampled, so edges show only high-level relationships and omit uncertain internal wiring.

Main entry points: [`node/node.go`](https://github.com/spacemeshos/go-spacemesh/blob/develop/node/node.go) (Node runtime), [`api/grpcserver/grpc.go`](https://github.com/spacemeshos/go-spacemesh/blob/develop/api/grpcserver/grpc.go) (gRPC services), [`mesh/mesh.go`](https://github.com/spacemeshos/go-spacemesh/blob/develop/mesh/mesh.go) (Mesh and blocks), [`txs/handler.go`](https://github.com/spacemeshos/go-spacemesh/blob/develop/txs/handler.go) (Transaction pool)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Node and API"]
  node_node["Node runtime<br/>[node.go]"]
  node_api["gRPC services<br/>[grpc.go]"]
  node_txapi["Transaction API"]
end

subgraph group_network["Peer Network"]
  node_p2p["P2P transport<br/>[host.go]"]
  node_syncer["Chain synchronizer<br/>[syncer.go]"]
  node_fetch["Peer data fetch<br/>[fetch.go]"]
  node_bootstrap["Bootstrap updates<br/>[updater.go]"]
end

subgraph group_consensus["Consensus and Mesh"]
  node_activation["Smeshing and ATX<br/>[handler.go]"]
  node_proposals["Proposals<br/>[handler.go]"]
  node_hare["Hare consensus<br/>[hare.go]"]
  node_tortoise["Tortoise consensus<br/>[tortoise.go]"]
  node_mesh["Mesh and blocks<br/>[mesh.go]"]
end

subgraph group_execution["Transactions and VM"]
  node_txs["Transaction pool<br/>[handler.go]"]
  node_vm["Smart-contract VM<br/>[vm.go]"]
  node_templates["Contract templates"]
end

subgraph group_state["Node State"]
  node_sql[("Persistent state<br/>[database.go]")]
  node_checkpoint["Checkpoint recovery<br/>[recovery.go]"]
  node_events["Events and subscriptions<br/>[events.go]"]
end

node_operator(("Node operator"))
node_app(("Applications"))

node_operator -->|"operates"| node_node
node_app -->|"calls"| node_api
node_node -->|"starts"| node_api
node_api -->|"dispatches"| node_txapi
node_txapi -->|"submits"| node_txs
node_node -->|"starts"| node_p2p
node_syncer -->|"exchanges data"| node_p2p
node_syncer -->|"requests chain data"| node_fetch
node_bootstrap -->|"distributes updates"| node_p2p
node_node -->|"starts"| node_activation
node_node -->|"starts"| node_proposals
node_proposals -->|"participates in rounds"| node_hare
node_hare -->|"supplies consensus data"| node_tortoise
node_tortoise -->|"determines validity"| node_mesh
node_proposals -->|"adds proposals"| node_mesh
node_mesh -->|"executes transactions"| node_txs
node_txs -->|"executes contracts"| node_vm
node_vm -->|"dispatches"| node_templates
node_node -->|"opens state"| node_sql
node_mesh -->|"persists chain state"| node_sql
node_txs -->|"reads and writes"| node_sql
node_checkpoint -->|"recovers state"| node_sql
node_node -->|"publishes events"| node_events
node_api -->|"serves subscriptions"| node_events

click node_node "https://github.com/spacemeshos/go-spacemesh/blob/develop/node/node.go"
click node_api "https://github.com/spacemeshos/go-spacemesh/blob/develop/api/grpcserver/grpc.go"
click node_txapi "https://github.com/spacemeshos/go-spacemesh/blob/develop/api/grpcserver/v1/transaction_service.go"
click node_p2p "https://github.com/spacemeshos/go-spacemesh/blob/develop/p2p/host.go"
click node_syncer "https://github.com/spacemeshos/go-spacemesh/blob/develop/syncer/syncer.go"
click node_fetch "https://github.com/spacemeshos/go-spacemesh/blob/develop/fetch/fetch.go"
click node_bootstrap "https://github.com/spacemeshos/go-spacemesh/blob/develop/bootstrap/updater.go"
click node_activation "https://github.com/spacemeshos/go-spacemesh/blob/develop/activation/handler.go"
click node_proposals "https://github.com/spacemeshos/go-spacemesh/blob/develop/proposals/handler.go"
click node_hare "https://github.com/spacemeshos/go-spacemesh/blob/develop/hare4/hare.go"
click node_tortoise "https://github.com/spacemeshos/go-spacemesh/blob/develop/tortoise/tortoise.go"
click node_mesh "https://github.com/spacemeshos/go-spacemesh/blob/develop/mesh/mesh.go"
click node_txs "https://github.com/spacemeshos/go-spacemesh/blob/develop/txs/handler.go"
click node_vm "https://github.com/spacemeshos/go-spacemesh/blob/develop/genvm/vm.go"
click node_templates "https://github.com/spacemeshos/go-spacemesh/tree/develop/genvm/templates"
click node_sql "https://github.com/spacemeshos/go-spacemesh/blob/develop/sql/database.go"
click node_checkpoint "https://github.com/spacemeshos/go-spacemesh/blob/develop/checkpoint/recovery.go"
click node_events "https://github.com/spacemeshos/go-spacemesh/blob/develop/events/events.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_node,node_api,node_txapi toneBlue
class node_p2p,node_syncer,node_fetch,node_bootstrap toneAmber
class node_activation,node_proposals,node_hare,node_tortoise,node_mesh toneMint
class node_txs,node_vm,node_templates toneRose
class node_sql,node_checkpoint,node_events,node_operator,node_app toneIndigo
```

## Components

### Node and API

- [Node runtime](https://github.com/spacemeshos/go-spacemesh/blob/develop/node/node.go): `node/node.go`
- [gRPC services](https://github.com/spacemeshos/go-spacemesh/blob/develop/api/grpcserver/grpc.go): `api/grpcserver/grpc.go`
- [Transaction API](https://github.com/spacemeshos/go-spacemesh/blob/develop/api/grpcserver/v1/transaction_service.go): `api/grpcserver/v1/transaction_service.go`

### Peer Network

- [P2P transport](https://github.com/spacemeshos/go-spacemesh/blob/develop/p2p/host.go): `p2p/host.go`
- [Chain synchronizer](https://github.com/spacemeshos/go-spacemesh/blob/develop/syncer/syncer.go): `syncer/syncer.go`
- [Peer data fetch](https://github.com/spacemeshos/go-spacemesh/blob/develop/fetch/fetch.go): `fetch/fetch.go`
- [Bootstrap updates](https://github.com/spacemeshos/go-spacemesh/blob/develop/bootstrap/updater.go): `bootstrap/updater.go`

### Consensus and Mesh

- [Smeshing and ATX](https://github.com/spacemeshos/go-spacemesh/blob/develop/activation/handler.go): `activation/handler.go`
- [Proposals](https://github.com/spacemeshos/go-spacemesh/blob/develop/proposals/handler.go): `proposals/handler.go`
- [Hare consensus](https://github.com/spacemeshos/go-spacemesh/blob/develop/hare4/hare.go): `hare4/hare.go`
- [Tortoise consensus](https://github.com/spacemeshos/go-spacemesh/blob/develop/tortoise/tortoise.go): `tortoise/tortoise.go`
- [Mesh and blocks](https://github.com/spacemeshos/go-spacemesh/blob/develop/mesh/mesh.go): `mesh/mesh.go`

### Transactions and VM

- [Transaction pool](https://github.com/spacemeshos/go-spacemesh/blob/develop/txs/handler.go): `txs/handler.go`
- [Smart-contract VM](https://github.com/spacemeshos/go-spacemesh/blob/develop/genvm/vm.go): `genvm/vm.go`
- [Contract templates](https://github.com/spacemeshos/go-spacemesh/tree/develop/genvm/templates): `genvm/templates`

### Node State

- [Persistent state](https://github.com/spacemeshos/go-spacemesh/blob/develop/sql/database.go): `sql/database.go`
- [Checkpoint recovery](https://github.com/spacemeshos/go-spacemesh/blob/develop/checkpoint/recovery.go): `checkpoint/recovery.go`
- [Events and subscriptions](https://github.com/spacemeshos/go-spacemesh/blob/develop/events/events.go): `events/events.go`

### Other components

- **Node operator**
- **Applications**

## Connections

- Node operator → Node runtime: operates
- Applications → gRPC services: calls
- Node runtime → gRPC services: starts
- gRPC services → Transaction API: dispatches
- Transaction API → Transaction pool: submits
- Node runtime → P2P transport: starts
- Chain synchronizer → P2P transport: exchanges data
- Chain synchronizer → Peer data fetch: requests chain data
- Bootstrap updates → P2P transport: distributes updates
- Node runtime → Smeshing and ATX: starts
- Node runtime → Proposals: starts
- Proposals → Hare consensus: participates in rounds
- Hare consensus → Tortoise consensus: supplies consensus data
- Tortoise consensus → Mesh and blocks: determines validity
- Proposals → Mesh and blocks: adds proposals
- Mesh and blocks → Transaction pool: executes transactions
- Transaction pool → Smart-contract VM: executes contracts
- Smart-contract VM → Contract templates: dispatches
- Node runtime → Persistent state: opens state
- Mesh and blocks → Persistent state: persists chain state
- Transaction pool → Persistent state: reads and writes
- Checkpoint recovery → Persistent state: recovers state
- Node runtime → Events and subscriptions: publishes events
- gRPC services → Events and subscriptions: serves subscriptions