Wormhole Kurtosis Package

Overview

This Kurtosis package deploys Wormhole core infrastructure onto existing EVM networks. It orchestrates Foundry/Forge deployments straight from the upstream Wormhole repository and wires an on-demand guardian node to the contracts you deploy (or reuse). You bring RPC endpoints and funding; the package handles contract deployment, guardian configuration, and basic smoke checks.

Key Features

• Upstream-first deployments – uses the official Wormhole Foundry scripts (no local contract forks).
• Guardian automation – builds a production-style guardian image with deterministic key handling and the required CLI flag wiring.
• Config driven – supply networks, RPC endpoints, and guardian settings through an args-file or JSON.
• Performance optimisations – avoids shipping a 70+ MB submodule by building lean Docker layers and deriving guardian signers at runtime.

Repository Structure

Path	Purpose
main.star	Starlark orchestration: contract deployment, guardian bootstrap, smoke test wiring
example-configs/	Sample args-files for Sepolia/Arbitrum/Holesky deployments (copy before editing)
scripts/	Forge deployment helpers, token bridge deployer, guardian helpers (scripts/guardian/)
templates/	Kurtosis-rendered templates (e.g. guardiand.yaml)
Dockerfile.forge	Forge image with cached Wormhole repo
Dockerfile.guardian-prod	Builds the custom guardian image used by the package
Dockerfile.guardian	Legacy wrapper image kept for experimentation

Quick Start (never commit secrets)

1. Copy one of the example configs and supply your private keys locally:

   cp example-configs/sepolia-arbitrum.json config.local.json
   # edit config.local.json with funded private keys (0x-prefixed)

2. Run the package with your local args-file:

   kurtosis run --enclave wormhole-e2e config.local.json .

3. Verify the guardian heartbeat:

   curl -s http://localhost:7071/v1/heartbeat | jq '.'

Configuration Reference

config.networks[]

• name, rpc, chain_id, wormhole_chain_id
• deployer_private_key (hex string with 0x prefix) used by Forge
• core_address (optional) – reuse an existing deployment
• finality, weth_address, etc. depending on the chain

config.wormhole.guardian

• count, private_keys, log_level, p2p_port, public_rpc_port, admin_rpc_port, metrics_port
• Provide private_keys with length equal to count or omit it to auto-generate dev keys (not production)
• Optional fallbacks: eth_mainnet_rpc, eth_mainnet_contract

config.wormhole.contracts

• deploy_core, deploy_token_bridge, deploy_nft_bridge
• auto_register_token_bridges
• smoke_test toggles the Sepolia → Arbitrum transfer attempt

Governance

• gov_chain_id (default 1)
• gov_contract (bytes32, default 0x…04)

Supported & Tested Networks

Guardian CLI flag mapping currently supports:

• sepolia, base-sepolia, arbitrum-sepolia, optimism-sepolia, holesky, polygon-amoy

Arbitrary EVM networks require upstream guardian changes (custom CLI flags). The package warns when a network is unsupported.

Custom Testnet Usage

The guardian still expects an --ethRPC/--ethContract pair for guardian set management. When both are omitted the package falls back to the first configured network. To override:

wormhole:
  guardian:
    eth_mainnet_rpc:  "wss://your-guardian-set-rpc"
    eth_mainnet_contract: "0x..."

Known Limitations

1. Production guardian build still expects a WS endpoint that supports JSON-RPC batching. Some public providers throttle or reject batches (e.g. current Alchemy Sepolia/Arbitrum Sepolia behaviour).
2. Guardian count defaults to one; multi-guardian orchestration is not yet implemented.
3. Token and NFT bridges deploy optional components but registration automation is limited to EVM pairs.

Recommendations

• Prefer funded, rate-limit friendly RPC providers (WS + HTTP) for guardian connectivity.
• For rapid testing use pre-deployed Wormhole contracts and set deploy_core to false.
• If provider WS batching fails, patch the guardian image to disable batch calls or switch providers.

Testing & Maintenance Commands

# Build helper images
docker build -f Dockerfile.forge -t wormhole-forge:latest .
docker build -f Dockerfile.guardian-prod -t wormhole-guardian-prod:latest .

# Launch package with JSON args
kurtosis run . example-configs/sepolia-arbitrum.json

# Check guardian logs
kurtosis service logs <enclave> guardian-0

# Tear down
kurtosis enclave stop <enclave>
kurtosis enclave rm <enclave>

Upgrading the Upstream Submodule

The Wormhole repository is tracked via git submodule (see .gitmodules). Update the submodule to pick up upstream script changes before rebuilding this package.