wormhole-foundation/wormhole

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).