# wormhole-foundation/wormhole architecture

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

- Interactive diagram: https://gitdiagram.com/wormhole-foundation/wormhole
- Repository: https://github.com/wormhole-foundation/wormhole

## Overview

#### Purpose and primary entry points
This is the reference implementation of the Wormhole cross-chain messaging protocol. Its central runtime is the Go guardian node: `node/main.go` dispatches commands, while `node/cmd/guardiand/node.go` configures and starts a guardian. Separate runnable services include the cross-chain query server (`node/cmd/ccq/query_server.go`), Spy API (`node/cmd/spy/spy.go`), and transaction verifier (`node/cmd/txverifier/txverifier.go`). `wormchain/cmd/wormchaind/main.go` starts the optional Cosmos-based Wormchain.

#### Guardian-node orchestration
The guardian process composes watchers, P2P, message processing, RPC services, persistence, telemetry, and optional governor/accountant/notary facilities. Runtime composition and lifecycle coordination are centered in `node/pkg/node/node.go` and `node/pkg/supervisor/supervisor.go`; command-level wiring lives in `node/cmd/guardiand/node.go`. This is a long-running Go service, not a web application.

#### Observation-to-VAA pipeline
Chain-specific watchers observe finalized source-chain events and emit observations. Implementations exist for EVM, Solana, Aptos, Algorand, CosmWasm, NEAR, Sui, XRPL, and IBC; representative boundaries are `node/pkg/watchers/watchers.go`, `node/pkg/watchers/evm/watcher.go`, and `node/pkg/watchers/solana/client.go`.

Observations enter the processor, which validates, batches/broadcasts them, collects guardian signatures, and constructs signed Verifiable Action Approvals (VAAs): `node/pkg/processor/processor.go`, `node/pkg/processor/observation.go`, `node/pkg/processor/vaa.go`. VAA serialization, payload types, quorum rules, and governance payload definitions are shared in `sdk/vaa/structs.go`, `sdk/vaa/quorum.go`, and `sdk/vaa/governance.go`.

#### Guardian consensus and external APIs
Guardians exchange observations, signed VAAs, and control traffic over libp2p-style P2P networking (`node/pkg/p2p/p2p.go`, `node/pkg/p2p/registry.go`). The node exposes public VAA retrieval/verification and subscriptions through gRPC/gateway-generated APIs (`proto/publicrpc/v1/publicrpc.proto`, `node/pkg/publicrpc/publicrpcserver.go`) and the Spy API (`proto/spy/v1/spy.proto`). Admin RPC is separately implemented in `node/pkg/adminrpc/adminserver.go`, an important operational trust boundary.

#### On-chain verification and bridge contracts
Each supported chain has native core contracts/programs that verify guardian-signed VAAs, track guardian sets and replay protection, and publish messages. Major implementations include EVM Solidity core and token bridge (`ethereum/contracts/Wormhole.sol`, `ethereum/contracts/bridge/TokenBridge.sol`), Solana programs (`solana/bridge/program/src/lib.rs`, `solana/modules/token_bridge/program/src/lib.rs`), and Move packages for Aptos/Sui (`aptos/wormhole/sources/wormhole.move`, `sui/wormhole/sources/vaa.move`).

The primary transfer flow is: source application/core contract emits a message → guardians observe and sign it into a VAA → a relayer/user submits the VAA to a destination core contract → token/NFT bridge validates it, prevents replay, and releases or mints the destination asset.

#### Governance, risk, and durable state
Governance VAAs update guardian sets, contracts, registrations, and protocol settings; contract-side governance paths are explicit in `ethereum/contracts/Governance.sol` and `solana/bridge/program/src/api/governance.rs`. The node’s governor applies transfer risk controls (`node/pkg/governor/governor.go`), while the accountant tracks cross-chain balances/observations (`node/pkg/accountant/accountant.go`). Persistent node state, including governor and accountant data, is isolated behind `node/pkg/db/db.go` and `node/pkg/db/manager.go`. Guardian signing supports file, generated, benchmark, and AWS KMS-backed signers in `node/pkg/guardiansigner/guardiansigner.go` and `node/pkg/guardiansigner/amazonkms.go`.

#### Client SDKs, query, and deployment environment
Consumers integrate through Go/TypeScript/Rust SDKs; the main TypeScript surface is `sdk/js/src/index.ts`, with VAA parsing and token-bridge operations under `sdk/js/src/vaa/index.ts` and `sdk/js/src/token_bridge/index.ts`. Cross-chain queries are modeled in `sdk/js-query/src/query/request.ts` and served by the guardian-side query subsystem (`node/pkg/query/query.go`).

Local multi-chain infrastructure is defined by Tilt and devnet manifests (`Tiltfile`, `devnet/node.yaml`, `devnet/eth-devnet.yaml`, `devnet/solana-devnet.yaml`). Material runtimes are Go, Rust, Solidity/EVM, Move, CosmWasm, and TypeScript/Node.js; external dependencies are the supported chain RPCs/nodes, guardian P2P peers, AWS KMS when configured, and Prometheus/Loki telemetry integrations (`node/pkg/telemetry/telemetry.go`).

Main entry points: [`node/pkg/processor/processor.go`](https://github.com/wormhole-foundation/wormhole/blob/main/node/pkg/processor/processor.go) (Observation processor), [`node/pkg/node/node.go`](https://github.com/wormhole-foundation/wormhole/blob/main/node/pkg/node/node.go) (Node runtime), [`ethereum/contracts/Wormhole.sol`](https://github.com/wormhole-foundation/wormhole/blob/main/ethereum/contracts/Wormhole.sol) (Core verification contracts), [`node/pkg/watchers/watchers.go`](https://github.com/wormhole-foundation/wormhole/blob/main/node/pkg/watchers/watchers.go) (Chain watchers)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_guardian["Guardian node"]
  node_guardian_cmd["guardiand command<br/>Go entrypoint<br/>[node.go]"]
  node_node_runtime["Node runtime<br/>Go orchestration<br/>[node.go]"]
  node_supervisor["Supervisor<br/>lifecycle control<br/>[supervisor.go]"]
  node_watchers["Chain watchers<br/>event observation<br/>[watchers.go]"]
  node_processor["Observation processor<br/>VAA pipeline<br/>[processor.go]"]
  node_p2p(("Guardian P2P<br/>libp2p network<br/>[p2p.go]"))
  node_signer["Guardian signer<br/>key backend<br/>[guardiansigner.go]"]
  node_vaa_sdk["VAA model &amp; quorum<br/>shared Go protocol<br/>[structs.go]"]
  node_governor["Governor<br/>transfer risk control<br/>[governor.go]"]
  node_accountant["Accountant<br/>balance tracking<br/>[accountant.go]"]
  node_node_db[("Node persistence<br/>durable state<br/>[db.go]")]
  node_public_rpc["Public RPC<br/>gRPC &amp; gateway API<br/>[publicrpcserver.go]"]
  node_admin_rpc["Admin RPC<br/>operational API<br/>[adminserver.go]"]
  node_query_service["Cross-chain query<br/>query service<br/>[query.go]"]
end

subgraph group_chains["Chains &amp; contracts"]
  node_source_chains(("Source chain RPCs<br/>external chain nodes<br/>[watcher.go]"))
  node_core_contracts{{"Core verification contracts<br/>on-chain core<br/>[Wormhole.sol]"}}
  node_bridge_contracts{{"Token &amp; NFT bridges<br/>on-chain bridge<br/>[TokenBridge.sol]"}}
  node_governance_contracts{{"On-chain governance<br/>contract governance<br/>[Governance.sol]"}}
end

subgraph group_clients["Consumers &amp; operations"]
  node_ts_sdk["TypeScript SDK<br/>client SDK<br/>[index.ts]"]
  node_relayer_user(("Relayer / user<br/>VAA submitter"))
  node_telemetry["Prometheus &amp; Loki<br/>telemetry integration<br/>[telemetry.go]"]
end

node_guardian_cmd -->|"starts"| node_node_runtime
node_node_runtime -->|"coordinates"| node_supervisor
node_node_runtime -->|"runs"| node_watchers
node_node_runtime -->|"runs"| node_processor
node_node_runtime -->|"serves"| node_public_rpc
node_node_runtime -->|"serves"| node_admin_rpc
node_node_runtime -->|"serves"| node_query_service
node_source_chains -->|"finalized events"| node_watchers
node_watchers -->|"observations"| node_processor
node_processor -->|"broadcasts observations and VAAs"| node_p2p
node_p2p -->|"peer observations"| node_processor
node_processor -->|"requests signatures"| node_signer
node_processor -->|"constructs"| node_vaa_sdk
node_processor -->|"checks transfers"| node_governor
node_processor -->|"records transfers"| node_accountant
node_governor -->|"persists"| node_node_db
node_accountant -->|"persists"| node_node_db
node_processor -->|"signed VAAs"| node_public_rpc
node_public_rpc -->|"retrieval and subscriptions"| node_ts_sdk
node_ts_sdk -->|"builds VAA operations"| node_relayer_user
node_relayer_user -->|"submits VAA"| node_core_contracts
node_core_contracts -->|"authorizes execution"| node_bridge_contracts
node_vaa_sdk -.->|"protocol format"| node_core_contracts
node_governance_contracts -->|"updates guardian sets and settings"| node_core_contracts
node_node_runtime -->|"emits metrics and logs"| node_telemetry

click node_guardian_cmd "https://github.com/wormhole-foundation/wormhole/blob/main/node/cmd/guardiand/node.go"
click node_node_runtime "https://github.com/wormhole-foundation/wormhole/blob/main/node/pkg/node/node.go"
click node_supervisor "https://github.com/wormhole-foundation/wormhole/blob/main/node/pkg/supervisor/supervisor.go"
click node_watchers "https://github.com/wormhole-foundation/wormhole/blob/main/node/pkg/watchers/watchers.go"
click node_processor "https://github.com/wormhole-foundation/wormhole/blob/main/node/pkg/processor/processor.go"
click node_p2p "https://github.com/wormhole-foundation/wormhole/blob/main/node/pkg/p2p/p2p.go"
click node_signer "https://github.com/wormhole-foundation/wormhole/blob/main/node/pkg/guardiansigner/guardiansigner.go"
click node_vaa_sdk "https://github.com/wormhole-foundation/wormhole/blob/main/sdk/vaa/structs.go"
click node_governor "https://github.com/wormhole-foundation/wormhole/blob/main/node/pkg/governor/governor.go"
click node_accountant "https://github.com/wormhole-foundation/wormhole/blob/main/node/pkg/accountant/accountant.go"
click node_node_db "https://github.com/wormhole-foundation/wormhole/blob/main/node/pkg/db/db.go"
click node_public_rpc "https://github.com/wormhole-foundation/wormhole/blob/main/node/pkg/publicrpc/publicrpcserver.go"
click node_admin_rpc "https://github.com/wormhole-foundation/wormhole/blob/main/node/pkg/adminrpc/adminserver.go"
click node_query_service "https://github.com/wormhole-foundation/wormhole/blob/main/node/pkg/query/query.go"
click node_source_chains "https://github.com/wormhole-foundation/wormhole/blob/main/node/pkg/watchers/evm/watcher.go"
click node_core_contracts "https://github.com/wormhole-foundation/wormhole/blob/main/ethereum/contracts/Wormhole.sol"
click node_bridge_contracts "https://github.com/wormhole-foundation/wormhole/blob/main/ethereum/contracts/bridge/TokenBridge.sol"
click node_governance_contracts "https://github.com/wormhole-foundation/wormhole/blob/main/ethereum/contracts/Governance.sol"
click node_ts_sdk "https://github.com/wormhole-foundation/wormhole/blob/main/sdk/js/src/index.ts"
click node_telemetry "https://github.com/wormhole-foundation/wormhole/blob/main/node/pkg/telemetry/telemetry.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_guardian_cmd,node_node_runtime,node_supervisor,node_watchers,node_processor,node_p2p,node_signer,node_vaa_sdk,node_governor,node_accountant,node_node_db,node_public_rpc,node_admin_rpc,node_query_service toneBlue
class node_source_chains,node_core_contracts,node_bridge_contracts,node_governance_contracts toneAmber
class node_ts_sdk,node_relayer_user,node_telemetry toneMint
```

## Components

### Guardian node

Long-running Go runtime.

- [guardiand command](https://github.com/wormhole-foundation/wormhole/blob/main/node/cmd/guardiand/node.go): Go entrypoint · `node/cmd/guardiand/node.go`
- [Node runtime](https://github.com/wormhole-foundation/wormhole/blob/main/node/pkg/node/node.go): Go orchestration · Composes guardian subsystems and lifecycle. · `node/pkg/node/node.go`
- [Supervisor](https://github.com/wormhole-foundation/wormhole/blob/main/node/pkg/supervisor/supervisor.go): lifecycle control · `node/pkg/supervisor/supervisor.go`
- [Chain watchers](https://github.com/wormhole-foundation/wormhole/blob/main/node/pkg/watchers/watchers.go): event observation · Adapters cover supported source chains. · `node/pkg/watchers/watchers.go`
- [Observation processor](https://github.com/wormhole-foundation/wormhole/blob/main/node/pkg/processor/processor.go): VAA pipeline · Validates observations, reaches quorum, and creates signed VAAs. · `node/pkg/processor/processor.go`
- [Guardian P2P](https://github.com/wormhole-foundation/wormhole/blob/main/node/pkg/p2p/p2p.go): libp2p network · Exchanges observations, VAAs, and control traffic. · `node/pkg/p2p/p2p.go`
- [Guardian signer](https://github.com/wormhole-foundation/wormhole/blob/main/node/pkg/guardiansigner/guardiansigner.go): key backend · Supports local and AWS KMS-backed signing. · `node/pkg/guardiansigner/guardiansigner.go`
- [VAA model & quorum](https://github.com/wormhole-foundation/wormhole/blob/main/sdk/vaa/structs.go): shared Go protocol · `sdk/vaa/structs.go`
- [Governor](https://github.com/wormhole-foundation/wormhole/blob/main/node/pkg/governor/governor.go): transfer risk control · `node/pkg/governor/governor.go`
- [Accountant](https://github.com/wormhole-foundation/wormhole/blob/main/node/pkg/accountant/accountant.go): balance tracking · `node/pkg/accountant/accountant.go`
- [Node persistence](https://github.com/wormhole-foundation/wormhole/blob/main/node/pkg/db/db.go): durable state · Stores governor and accountant state. · `node/pkg/db/db.go`
- [Public RPC](https://github.com/wormhole-foundation/wormhole/blob/main/node/pkg/publicrpc/publicrpcserver.go): gRPC & gateway API · VAA retrieval, verification, and subscriptions. · `node/pkg/publicrpc/publicrpcserver.go`
- [Admin RPC](https://github.com/wormhole-foundation/wormhole/blob/main/node/pkg/adminrpc/adminserver.go): operational API · Separate privileged trust boundary. · `node/pkg/adminrpc/adminserver.go`
- [Cross-chain query](https://github.com/wormhole-foundation/wormhole/blob/main/node/pkg/query/query.go): query service · `node/pkg/query/query.go`

### Chains & contracts

Message publication and VAA execution boundaries.

- [Source chain RPCs](https://github.com/wormhole-foundation/wormhole/blob/main/node/pkg/watchers/evm/watcher.go): external chain nodes · EVM, Solana, Move, IBC, and other supported chains. · `node/pkg/watchers/evm/watcher.go`
- [Core verification contracts](https://github.com/wormhole-foundation/wormhole/blob/main/ethereum/contracts/Wormhole.sol): on-chain core · Publish messages, verify VAAs, maintain guardian sets, and prevent replay. · `ethereum/contracts/Wormhole.sol`
- [Token & NFT bridges](https://github.com/wormhole-foundation/wormhole/blob/main/ethereum/contracts/bridge/TokenBridge.sol): on-chain bridge · Release or mint destination assets after VAA verification. · `ethereum/contracts/bridge/TokenBridge.sol`
- [On-chain governance](https://github.com/wormhole-foundation/wormhole/blob/main/ethereum/contracts/Governance.sol): contract governance · `ethereum/contracts/Governance.sol`

### Consumers & operations

- [TypeScript SDK](https://github.com/wormhole-foundation/wormhole/blob/main/sdk/js/src/index.ts): client SDK · Parses VAAs and submits bridge operations. · `sdk/js/src/index.ts`
- **Relayer / user**: VAA submitter · Submits signed VAAs on destination chains.
- [Prometheus & Loki](https://github.com/wormhole-foundation/wormhole/blob/main/node/pkg/telemetry/telemetry.go): telemetry integration · `node/pkg/telemetry/telemetry.go`

## Connections

- guardiand command → Node runtime: starts
- Node runtime → Supervisor: coordinates
- Node runtime → Chain watchers: runs
- Node runtime → Observation processor: runs
- Node runtime → Public RPC: serves
- Node runtime → Admin RPC: serves
- Node runtime → Cross-chain query: serves
- Source chain RPCs → Chain watchers: finalized events
- Chain watchers → Observation processor: observations
- Observation processor → Guardian P2P: broadcasts observations and VAAs
- Guardian P2P → Observation processor: peer observations
- Observation processor → Guardian signer: requests signatures
- Observation processor → VAA model & quorum: constructs
- Observation processor → Governor: checks transfers
- Observation processor → Accountant: records transfers
- Governor → Node persistence: persists
- Accountant → Node persistence: persists
- Observation processor → Public RPC: signed VAAs
- Public RPC → TypeScript SDK: retrieval and subscriptions
- TypeScript SDK → Relayer / user: builds VAA operations
- Relayer / user → Core verification contracts: submits VAA
- Core verification contracts → Token & NFT bridges: authorizes execution
- VAA model & quorum → Core verification contracts: protocol format
- On-chain governance → Core verification contracts: updates guardian sets and settings
- Node runtime → Prometheus & Loki: emits metrics and logs