Wormhole

Skill is based on Wormhole (reference implementation) at commit 612caaa, generated 2026-02-24.

Wormhole is a generic cross-chain messaging protocol: guardians observe finalized messages on connected chains, reach consensus, and produce Signed VAAs. Applications (Token Bridge, NFT Bridge, oracles) sit on top; the core does not hold assets or deliver messages. Use this skill to integrate contracts with the core bridge and Token Bridge, operate or reason about guardian nodes, and use Cross Chain Queries (CCQ).

Core References

Features

Best Practices

Contract Integration Best Practices

Emitter authorization

Token Bridge and other modules accept VAAs only from registered (emitterChain, emitterAddress) pairs. Token Bridge endpoints are registered via governance (RegisterChain). Your application contract should enforce an allowlist of allowed emitters for the payload types it handles; do not process VAAs from arbitrary emitters.

Replay protection

• Core and Token Bridge track consumed VAA body hashes (or equivalent). Never execute the same VAA twice.
• Use the VAA body hash (or digest) as the replay key, not only (chainId, emitter, sequence), since the same logical message could be re-observed with a new VAA in edge cases.

Redeem timing and guardian set changes

• Guardian sets are valid for at least 24 hours. If a user redeems a transfer more than 24 hours after signing, the guardian set may have changed and the VAA might not verify with the current set.
• Options: (1) Use the SDK repairVaa() to update guardian set index and remove old signatures so the VAA validates against the new set. (2) Fetch additional signatures (e.g. Wormholescan API) if the intersection of signers still meets quorum. (3) Request re-observation from guardians (possible if quorum has archive nodes).
• Prefer completing transfers within 24 hours when possible.

TransferWithPayload

• Only the recipient should call completeTransferWithPayload; the payload is application-specific and must be handled by the designated target. Do not allow arbitrary relayers to redeem TransferWithPayload.

Wrapped asset setup

• The first transfer of a token to a chain requires that the wrapped asset exists (via AssetMeta and createWrapped). Transfers for not-yet-wrapped assets become executable once the wrapped asset is created; no need to block the transfer.

Token metadata

• AssetMeta name/symbol may be truncated at 32 bytes; validate UTF-8 and trim invalid trailing bytes before displaying.

Amounts and decimals

• Amounts are truncated to 8 decimals over the bridge. Refund dust to the user on deposit. Ensure total bridged per token does not exceed MaxUint64 in 8-decimal units.

<!-- Source references:

• sources/wormhole/whitepapers/0003_token_bridge.md (Caveats)
• sources/wormhole/sdk/js/README.md

-->

Security Assumptions

When integrating or operating Wormhole, rely on these documented assumptions.

Gossip and availability

• Gossip (libp2p) is for availability only, not security. Compromise could cause DoS or message loss, not forgery.
• Observations may be retried (e.g. Solana polling, future chain replay); VAA body hash is deterministic and idempotent. Re-observation is safe.
• Prolonged outages can lead to dropped observations on non-Solana chains until chain replay exists.

Chain finality

• Guardians observe external events; they do not initiate them. Security depends on connected chains’ finality and consensus.
• Assumptions: transactions become final and are not rolled back; no double execution; account/state persistence; no equivocation at a given height.

Spam and fees

• Chains are assumed to use fees (or similar) to limit spam; Wormhole’s capacity is assumed greater than the sum of connected chains. Extreme fee-paying attacks are out of scope for the current threat model.

Guardian incentives

• Wormhole is a decentralized PoA bridge. Security relies on a carefully chosen guardian set with aligned incentives (reputation, ecosystem). No staking/slashing in the current design.

Host and keys

• Guardian nodes assume uncompromised hosts. A supermajority compromise can produce arbitrary VAAs; a superminority can cause temporary consensus loss. HSMs do not remove the risk of a compromised host using the HSM as a signing oracle; they only complicate theft.

Third-party code

• Dependencies are minimized and pinned (e.g. go.sum). Cryptography uses Go stdlib and go-ethereum. Assume no backdoors in third-party libraries.

Solana contracts

• Solana programs use unsafe blocks for (de)serialization under instruction limits. Invalid or out-of-bounds access is assumed to crash the VM and halt execution safely.

When building on Wormhole, verify VAAs on-chain via the official core/bridge; do not trust payload or emitter without contract-level checks.

<!-- Source references:

• sources/wormhole/docs/assumptions.md
• sources/wormhole/whitepapers/0001_generic_message_passing.md (Security Considerations)

-->

Governance Messaging

Governance decisions are emitted from a designated governance contract and delivered as VAAs. Core and modules (e.g. Token Bridge) accept governance from a hardcoded (emitterChain, emitterAddress) tuple.

Governance packet structure

All governance VAAs use a common header:

Module  [32]byte   // Left-padded module identifier (e.g. "Core", "TokenBridge")
Action  uint8      // Action ID
Chain   uint16     // Target chain (0 for global, e.g. guardian set)
// Action-specific payload

Core governance actions

ContractUpgrade (Action 1): Upgrade implementation on a specific chain.

• Module = "Core"
• Chain = target chain ID
• NewContract = 32-byte new implementation address

GuardianSetUpgrade (Action 2): Replace guardian set (chain-independent).

• Module = "Core"
• Chain = 0
• NewGuardianSetIndex, NewGuardianSetLen, NewGuardianSet[]

Other core actions (e.g. SetMessageFee = 3, TransferFees = 4) follow the same module/action pattern; see whitepapers for exact payloads.

Token Bridge governance

Token Bridge uses the same governance emitter; module identifier is "TokenBridge" (left-padded). Actions include RegisterChain (register bridge endpoint per chain) and UpgradeContract. Only the governance contract can emit these; endpoints verify emitter before applying.

Usage

• When integrating a new chain or upgrading contracts, governance VAAs are produced off-chain by the authorized governance process and submitted to the core/bridge on each target chain.
• Do not accept governance VAAs from arbitrary emitters; always verify against the known governance emitter address for the network (mainnet/testnet).

<!-- Source references:

• sources/wormhole/whitepapers/0002_governance_messaging.md
• sources/wormhole/whitepapers/0003_token_bridge.md
• sources/wormhole/whitepapers/0004_message_publishing.md

-->

Wormhole Overview

Wormhole is a generic cross-chain messaging protocol. Guardians observe finalized messages from connected chains, reach consensus, and produce Signed VAAs (Verifiable Action Approvals). Applications (e.g. Token Bridge, NFT Bridge) sit on top of the core; the core does not hold assets or deliver messages—only attests state.

Key concepts

• Core contract (per chain): Exposes postMessage(payload, consistencyLevel) and emits events guardians observe. Tracks sequence per emitter. Fee is paid in native currency when posting.
• VAA: Signed attestation from the guardian set. Identified by (emitterChain, emitterAddress, sequence). Body hash is used for replay protection.
• Guardian set: Multisig of nodes that observe chains and sign observations once quorum is reached. Set is upgraded via governance.
• Delivery: Off-chain. Relayers or users fetch the signed VAA (e.g. from guardian public RPC or Wormholescan) and submit it to the target chain contract.

Flow

1. Publish: User or contract calls core bridge postMessage on source chain (max 750 bytes payload). 2. Observe: Guardians watch the chain, wait for the requested consistency level, then sign the observation and gossip until quorum. 3. Attest: Signed VAA is published on the P2P network and can be retrieved via public API. 4. Execute: Anyone submits the VAA to the target chain contract (e.g. Token Bridge completeTransfer); the contract verifies guardian signatures and processes the payload.

Chain IDs and addresses

• Chain IDs are uint16 Wormhole chain identifiers (e.g. Ethereum = 2, Solana = 1). Defined in vaa/structs.go and in SDK constants.
• Addresses in VAAs are 32-byte, left-zero-padded (e.g. EVM 20-byte address).

Key points

• Core is application-agnostic; Token Bridge and NFT Bridge are separate modules that interpret payloads and manage custody/wrapped assets.
• Official docs and contract addresses: docs.wormhole.com, Live Contracts.
• In-repo TypeScript SDK under sdk/js is deprecated; use @wormhole-foundation/sdk for new integrations.

<!-- Source references:

• sources/wormhole/README.md
• sources/wormhole/whitepapers/0001_generic_message_passing.md
• sources/wormhole/sdk/README.md, sdk/js/README.md

-->

Token Bridge

The Token Bridge is an application on top of Wormhole core. It locks/burns on source and mints/releases on target. Each chain has a token bridge endpoint; only registered (emitterChain, emitterAddress) pairs are accepted.

Payload types

• Transfer (PayloadID 1): Amount, TokenAddress, TokenChain, To, ToChain, Fee. Redeemable by anyone; fee can go to relayer.
• TransferWithPayload (PayloadID 3): Same plus FromAddress and Payload. Must be redeemed by the target address (recipient handles payload).
• AssetMeta (PayloadID 2): TokenAddress, TokenChain, Decimals, Symbol, Name. Required before first transfer to a chain to create wrapped asset.
• RegisterChain / UpgradeContract: Governance-only; emitted by governance contract.

API (conceptual)

• attestToken(token) — Emit AssetMeta for a token (on native chain).
• transfer(token, amount, recipientChain, recipient, fee) — Lock/burn and emit Transfer.
• transferWithPayload(token, amount, recipientChain, recipient, payload) — Same with custom payload; recipient must redeem.
• createWrapped(assetMetaVaa) — Create wrapped asset from AssetMeta VAA.
• completeTransfer(transferVaa) — Execute Transfer (optionally specify fee recipient).
• completeTransferWithPayload(transferVaa) — Execute TransferWithPayload (called by recipient).

Amounts and decimals

Amounts over the bridge are truncated to 8 decimals. Total bridged per token (all targets) must not exceed MaxUint64 in 8-decimal units. Dust from truncation should be refunded to the user. Target chain can either preserve 8 decimals on wrapped tokens or shift back using AssetMeta decimals.

Replay and guardian set

Consumed message digests (including nonce) are stored for replay prevention. If the guardian set changes before redeem, the VAA may need to be repaired (e.g. SDK repairVaa()): update guardian set index and drop signatures from guardians no longer in the new set. Redeem within 24h when possible; after that, repair or re-observation may be required.

TransferWithPayload

Only the designated recipient can call completeTransferWithPayload; use for flows where the recipient must interpret the payload (e.g. swap instructions).

<!-- Source references:

• sources/wormhole/whitepapers/0003_token_bridge.md
• sources/wormhole/sdk/js/README.md

-->

VAA and Message Publishing

VAA structure (generic message passing)

VAAs have a header (not signed) and a body (signed). The body is hashed for replay protection.

Header: version, guardianSetIndex, lenSignatures, signatures[] (index + 65-byte signature).

Body (signed):

• timestamp — block timestamp when message was observed
• nonce — from emitter
• emitterChain — Wormhole chain ID
• emitterAddress — 32-byte contract address (left-zero-padded)
• sequence — per-(emitterChain, emitterAddress) counter from core contract
• consistencyLevel — finality requirement
• payload — arbitrary bytes (max 750 for postMessage)

Verifying contracts check guardian set index, validate signatures against the stored guardian set, then use body fields and payload.

Posting messages

Core contract API (per chain):

• postMessage(bytes payload, uint8 consistencyLevel) — Publish a message. Pay fee in native currency. Core increments sequence for the sender/emitter.

Fees are set per chain via governance (SetMessageFee VAA). Message fee is enforced on-chain.

Consistency levels

Guardians wait until the requested commitment level before signing.

EVM:

• 200 — publish immediately
• 201 — safe (or finalized fallback)
• 202 — finalized
• 203 — custom (read from CustomConsistencyLevel contract by emitter address)
• Other → treated as finalized

Solana: Core uses Confirmed (1) or Finalized (32) in the instruction; guardian maps to same semantics.

Other chains may not expose configurable levels (field 0).

Trust and security

• Header fields depend on the core bridge and runtime.
• Body emitterChain is set by guardians (trust: guardian set).
• timestamp comes from the chain RPC (trust: guardians + chain).
• emitterAddress, sequence from core bridge (trust: guardians + chain + core implementation).
• nonce, consistencyLevel, payload from the calling contract (trust: all of the above + emitter contract).

Always verify VAA on the target chain via the official core/bridge contract; do not trust payload content without verification.

Usage

When building an app: 1. Call core postMessage with your payload and desired consistency level. 2. Read sequence and emitterAddress from logs/tx to fetch the signed VAA (e.g. guardian API or Wormholescan). 3. Submit the VAA to the target chain contract that parses your payload and enforces emitter allowlist.

<!-- Source references:

• sources/wormhole/whitepapers/0001_generic_message_passing.md
• sources/wormhole/whitepapers/0004_message_publishing.md

-->

Governor and Notary

Chain Governor

Optional plugin; disabled by default. When enabled (--chainGovernorEnabled=true), enforces per-chain daily limits and max transfer size. VAAs that would exceed limits are held pending; release time is typically 24–72 hours.

Admin commands (via guardiand admin ... --socket /path/to/admin.sock):

• governor-status — List chains, limits, 24h total, and pending VAAs (emitter/seq, value, release time).
• governor-release-pending-vaa "chainId/emitter/sequence" — Manually release a pending VAA (does not count toward 24h limit). Use rarely; avoid for suspected exploits.
• governor-drop-pending-vaa "chainId/emitter/sequence" — Permanently drop; only for confirmed fraud affecting the network.
• governor-reset-release-timer "chainId/emitter/sequence" "days" — Reset release timer (max 7 days). For investigation time, not routine use.

Flow cancel extension: --governorFlowCancelEnabled=true to enable.

Notary

Disabled by default (--notaryEnabled=true to enable). Evaluates message publications and can Approve, Delay, or Blackhole. Currently only affects processing when Transfer Verifier is also enabled.

• Approve: Process normally.
• Delay: Hold for manual review (default 4 days, max 30). Stored with release time.
• Blackhole: Permanently block from publication.

Admin commands:

• notary-get-delayed-message "chainId/emitter/sequence" — Details of a delayed message.
• notary-get-blackholed-message "chainId/emitter/sequence" — Details of a blackholed message.
• notary-list-delayed-messages / notary-list-blackholed-messages — List all.
• notary-release-delayed-message "chainId/emitter/sequence" — Release delayed VAA immediately.
• notary-blackhole-delayed-message "chainId/emitter/sequence" — Move delayed to blackhole.
• notary-remove-blackholed-message "chainId/emitter/sequence" — Move blackholed back to delayed (zero delay). Use only if blackholing was wrong.
• notary-reset-release-timer "chainId/emitter/sequence" "days" — Reset delay (0–30 days).

Message ID format: chain_id/emitter_address/sequence_number (e.g. 1/0000...585/12345).

<!-- Source references:

• sources/wormhole/docs/governor.md
• sources/wormhole/docs/notary.md

-->

Guardian Node

The guardian node observes connected chains, aggregates observations until quorum, and publishes signed VAAs. Used when operating or integrating with guardian infrastructure.

Components

• Watchers: One per chain (EVM, Solana, Cosmwasm, Sui, Aptos, Algorand, Near, IBC). Subscribe or poll for core contract events and post observations to the processor. Handle reobservation requests.
• Processor: Aggregates observations from watchers and gossip, runs governor and accountant checks, signs when quorum is reached, batches and publishes signed VAAs to P2P.
• Governor: Optional; enforces per-chain daily and per-transfer limits; can delay or drop VAAs (see governor/notary docs).
• Accountant: Interfaces with accountant contracts on Gateway (wormchain) for token bridge and NTT notional limits.
• Query (CCQ): Processes Cross Chain Query requests on a separate P2P topic; forwards to watchers and publishes responses.

Observation lifecycle

1. Watcher sees core contract message; waits for requested consistency level. 2. Observation sent to processor; governor/accountant may delay. 3. Processor signs and batches; batches published to P2P. 4. Other guardians receive; each aggregates until quorum and has observed locally. 5. At quorum, VAA is generated and published as signed VAA.

Reobservation

Reobservation can be requested by: admin command, gossip from another guardian, or internally (processor/accountant). Request is (chainId, txId). Watcher fetches tx and reposts observation; throttling applies to avoid repeated requests for the same tx.

Configuration

Config: file (YAML preferred), env vars (GUARDIAND_*), or CLI flags (highest precedence). Example: ethRPC, solanaRPC, solanaContract, ethContract, etc. For public RPC: --publicWeb, optional --tlsHostname and --tlsProdEnv. Guardian key: guardiand keygen or guardianSignerUri for custom signer (e.g. KMS). Build: make node → build/guardiand.

Monitoring

Use /readyz for startup readiness and /metrics (Prometheus) for alerting; do not rely on log parsing. Ports: 8999/udp P2P, 8996/udp CCQ; public API if --publicWeb is set.

<!-- Source references:

• sources/wormhole/docs/guardian.md
• sources/wormhole/docs/operations.md

-->

Cross Chain Queries (CCQ)

Wormhole Queries (CCQ) let clients request attestations for cross-chain data. Guardians run query support; a query proxy server validates requests, forwards them to the guardian P2P network, aggregates responses, and returns results when quorum is reached.

Running the proxy

Same binary as guardiand: guardiand query-server. Required: --env (mainnet/testnet/devnet), --nodeKey, --permFile, --signerKey, --listenAddr. Need at least one chain config (e.g. --ethRPC, --ethContract) for guardian set read. Proxy must be reachable from the internet for REST and must reach guardian P2P (port 8996/udp). Generate signer key: guardiand keygen --desc "CCQ proxy" --block-type "CCQ SERVER SIGNING KEY" /path/to/file.

Guardians are permissioned: they only accept queries from configured proxy P2P keys and signed requests from configured signer keys. New proxies must be allowlisted by guardians.

Permissions file (permFile)

JSON: allowAnythingSupported (testnet only), defaultRateLimit, defaultBurstSize, and permissions[]. Each permission has:

• userName, apiKey — Client identifies with API key.
• allowUnsigned — If true, proxy signs with signerKey for this user.
• allowedCalls — List of allowed query shapes (see below). Omit if using allowAnything (testnet only).
• Optional: rateLimit, burstSize, logResponses.

Supported call types (see whitepaper 0013 for exact schema):

• EVM: ethCall, ethCallByTimestamp, ethCallWithFinality — each needs chain, contractAddress, call (4-byte selector). contractAddress can be "*" for any contract.
• Solana: solAccount (needs account), solPDA (needs programAddress). Addresses as 32-byte hex or base58.

Validate permissions file without reloading: guardiand query-server --env mainnet --verifyPermissions --permFile path/to/file.json.

Rate limiting

Global: defaultRateLimit, defaultBurstSize. Per-user: rateLimit, burstSize. Rate in queries/sec; burst size for spikes. Zero rate disables limiting.

Usage

Clients send REST requests to the proxy with API key and query payload. Proxy forwards to guardians, collects responses, verifies quorum, and returns. Use for reading state or proofs across chains without submitting on-chain transactions.

<!-- Source references:

• sources/wormhole/docs/query_proxy.md
• sources/wormhole/whitepapers/0013_ccq.md
• sources/wormhole/sdk/js-query/README.md

-->

Transfer Verifier

The Transfer Verifier lets guardians verify that token bridge (and related) transfers are valid before publishing observations. When enabled for a chain, suspect transfers can be blocked.

Enabling

Disabled by default. Enable per chain with a comma-separated list of Wormhole chain IDs:

--transferVerifierEnabledChainIDs=2
# or multiple:
--transferVerifierEnabledChainIDs=2,21

Only some chains have a Transfer Verifier implementation. If an unsupported chain ID is listed, the node fails to start with an error. Supported chains include certain EVM chains and Sui (e.g. 2 = Ethereum, 21 = Sui); check the guardian code for the current list.

Behavior

When Transfer Verifier is enabled for a chain, the guardian evaluates transfer observations against the verifier before publishing. If the verifier marks a transfer as invalid or suspicious, the observation is not published (blocked). The Notary can further delay or blackhole messages when both Notary and Transfer Verifier are enabled.

Standalone mode

The verifier can also run as a standalone monitoring tool (see node/cmd/txverifier/README.md) without blocking publication; in that case it is used for alerting or analysis only.

<!-- Source references:

• sources/wormhole/docs/transfer-verifier.md
• sources/wormhole/whitepapers/0014_transfer_verifier.md

-->