# metalblockchain/metalgo architecture

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

- Interactive diagram: https://gitdiagram.com/metalblockchain/metalgo
- Repository: https://github.com/metalblockchain/metalgo

## Overview

MetalGo is Metal’s blockchain node implementation, forked from AvalancheGo. A user starts the node with a selected network configuration; the application constructs the node, which manages chains and their virtual machines while consensus and peer networking process blockchain activity. Chain execution includes transaction verification, state updates, and persistent storage; APIs expose node information and administration. The graph includes documented and indexed major subsystems, but sampled excerpts do not establish every runtime connection, so uncertain relationships are omitted. The README describes network selection but not detailed runtime wiring.

Main entry points: [`vms/platformvm/service.go`](https://github.com/metalblockchain/metalgo/blob/master/vms/platformvm/service.go) (Platform VM), [`chains/manager.go`](https://github.com/metalblockchain/metalgo/blob/master/chains/manager.go) (Chain manager), [`vms/avm/vm.go`](https://github.com/metalblockchain/metalgo/blob/master/vms/avm/vm.go) (AVM), [`snow/engine/snowman/engine.go`](https://github.com/metalblockchain/metalgo/blob/master/snow/engine/snowman/engine.go) (Chain consensus)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Node Runtime"]
  node_entry["Executable entry<br/>[main.go]"]
  node_app["Application bootstrap<br/>[app.go]"]
  node_node["Node services<br/>[node.go]"]
end

subgraph group_network["Networking and Consensus"]
  node_avalanche["DAG engine<br/>[engine.go]"]
  node_snowman["Chain consensus<br/>[engine.go]"]
  node_validators["Validator manager<br/>[manager.go]"]
  node_p2p["Peer networking<br/>[network.go]"]
end

subgraph group_chains["Chains and Virtual Machines"]
  node_chainmgr["Chain manager<br/>[manager.go]"]
  node_avm["AVM<br/>[vm.go]"]
  node_avmexec["AVM block executor<br/>[manager.go]"]
  node_platformvm["Platform VM<br/>[service.go]"]
  node_platformexec["Platform block executor<br/>[manager.go]"]
  node_pvalidators["Platform validators<br/>[manager.go]"]
end

subgraph group_state["State and Storage"]
  node_sync["State sync<br/>[manager.go]"]
  node_blockdb[("Block database<br/>[database.go]")]
  node_simplex[("Simplex persistence<br/>[storage.go]")]
end

subgraph group_interfaces["Node Interfaces"]
  node_info["Info API<br/>[service.go]"]
  node_server["API server<br/>[server.go]"]
end

node_operator(("Node operator"))
node_actor(("API client"))

node_operator -->|"starts"| node_entry
node_entry -->|"calls"| node_app
node_app -->|"constructs"| node_node
node_chainmgr -->|"initializes"| node_avalanche
node_chainmgr -->|"initializes"| node_avm
node_chainmgr -.->|"initializes"| node_platformvm
node_snowman -.->|"parses blocks"| node_avm
node_snowman -.->|"parses blocks"| node_platformvm
node_avmexec -->|"applies transactions"| node_avm
node_platformexec -->|"executes blocks"| node_platformvm
node_pvalidators -->|"reads state"| node_platformvm
node_sync -.->|"updates database"| node_blockdb
node_simplex -.->|"stores finalizations"| node_blockdb
node_actor -.->|"requests"| node_server
node_server -.->|"routes requests"| node_info

click node_entry "https://github.com/metalblockchain/metalgo/blob/master/main/main.go"
click node_app "https://github.com/metalblockchain/metalgo/blob/master/app/app.go"
click node_node "https://github.com/metalblockchain/metalgo/blob/master/node/node.go"
click node_chainmgr "https://github.com/metalblockchain/metalgo/blob/master/chains/manager.go"
click node_avalanche "https://github.com/metalblockchain/metalgo/blob/master/snow/engine/avalanche/engine.go"
click node_snowman "https://github.com/metalblockchain/metalgo/blob/master/snow/engine/snowman/engine.go"
click node_validators "https://github.com/metalblockchain/metalgo/blob/master/snow/validators/manager.go"
click node_p2p "https://github.com/metalblockchain/metalgo/blob/master/network/p2p/network.go"
click node_avm "https://github.com/metalblockchain/metalgo/blob/master/vms/avm/vm.go"
click node_avmexec "https://github.com/metalblockchain/metalgo/blob/master/vms/avm/block/executor/manager.go"
click node_platformvm "https://github.com/metalblockchain/metalgo/blob/master/vms/platformvm/service.go"
click node_platformexec "https://github.com/metalblockchain/metalgo/blob/master/vms/platformvm/block/executor/manager.go"
click node_pvalidators "https://github.com/metalblockchain/metalgo/blob/master/vms/platformvm/validators/manager.go"
click node_sync "https://github.com/metalblockchain/metalgo/blob/master/x/sync/manager.go"
click node_blockdb "https://github.com/metalblockchain/metalgo/blob/master/x/blockdb/database.go"
click node_simplex "https://github.com/metalblockchain/metalgo/blob/master/simplex/storage.go"
click node_info "https://github.com/metalblockchain/metalgo/blob/master/api/info/service.go"
click node_server "https://github.com/metalblockchain/metalgo/blob/master/api/server/server.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_entry,node_app,node_node,node_actor toneBlue
class node_avalanche,node_snowman,node_validators,node_p2p toneAmber
class node_chainmgr,node_avm,node_avmexec,node_platformvm,node_platformexec,node_pvalidators toneMint
class node_sync,node_blockdb,node_simplex toneRose
class node_info,node_server,node_operator toneIndigo
```

## Components

### Node Runtime

- [Executable entry](https://github.com/metalblockchain/metalgo/blob/master/main/main.go): `main/main.go`
- [Application bootstrap](https://github.com/metalblockchain/metalgo/blob/master/app/app.go): `app/app.go`
- [Node services](https://github.com/metalblockchain/metalgo/blob/master/node/node.go): `node/node.go`

### Networking and Consensus

- [DAG engine](https://github.com/metalblockchain/metalgo/blob/master/snow/engine/avalanche/engine.go): `snow/engine/avalanche/engine.go`
- [Chain consensus](https://github.com/metalblockchain/metalgo/blob/master/snow/engine/snowman/engine.go): `snow/engine/snowman/engine.go`
- [Validator manager](https://github.com/metalblockchain/metalgo/blob/master/snow/validators/manager.go): `snow/validators/manager.go`
- [Peer networking](https://github.com/metalblockchain/metalgo/blob/master/network/p2p/network.go): `network/p2p/network.go`

### Chains and Virtual Machines

- [Chain manager](https://github.com/metalblockchain/metalgo/blob/master/chains/manager.go): `chains/manager.go`
- [AVM](https://github.com/metalblockchain/metalgo/blob/master/vms/avm/vm.go): `vms/avm/vm.go`
- [AVM block executor](https://github.com/metalblockchain/metalgo/blob/master/vms/avm/block/executor/manager.go): `vms/avm/block/executor/manager.go`
- [Platform VM](https://github.com/metalblockchain/metalgo/blob/master/vms/platformvm/service.go): `vms/platformvm/service.go`
- [Platform block executor](https://github.com/metalblockchain/metalgo/blob/master/vms/platformvm/block/executor/manager.go): `vms/platformvm/block/executor/manager.go`
- [Platform validators](https://github.com/metalblockchain/metalgo/blob/master/vms/platformvm/validators/manager.go): `vms/platformvm/validators/manager.go`

### State and Storage

- [State sync](https://github.com/metalblockchain/metalgo/blob/master/x/sync/manager.go): `x/sync/manager.go`
- [Block database](https://github.com/metalblockchain/metalgo/blob/master/x/blockdb/database.go): `x/blockdb/database.go`
- [Simplex persistence](https://github.com/metalblockchain/metalgo/blob/master/simplex/storage.go): `simplex/storage.go`

### Node Interfaces

- [Info API](https://github.com/metalblockchain/metalgo/blob/master/api/info/service.go): `api/info/service.go`
- [API server](https://github.com/metalblockchain/metalgo/blob/master/api/server/server.go): `api/server/server.go`

### Other components

- **Node operator**
- **API client**

## Connections

- Node operator → Executable entry: starts (evidence: `README.md`)
- Executable entry → Application bootstrap: calls (evidence: `main/main.go`)
- Application bootstrap → Node services: constructs (evidence: `app/app.go`)
- Chain manager → DAG engine: initializes (evidence: `chains/manager.go`)
- Chain manager → AVM: initializes (evidence: `chains/manager.go`)
- Chain manager → Platform VM: initializes
- Chain consensus → AVM: parses blocks
- Chain consensus → Platform VM: parses blocks
- AVM block executor → AVM: applies transactions (evidence: `vms/avm/block/executor/manager.go`)
- Platform block executor → Platform VM: executes blocks (evidence: `vms/platformvm/block/executor/manager.go`)
- Platform validators → Platform VM: reads state (evidence: `vms/platformvm/validators/manager.go`)
- State sync → Block database: updates database
- Simplex persistence → Block database: stores finalizations
- API client → API server: requests
- API server → Info API: routes requests
