Wormhole

⚠️ WORK IN PROGRESS — CURRENTLY UNDERGOING AUDIT, DO NOT USE. ⚠️

Read our introduction blog article for more details on Wormhole and its major design decisions.

See DEVELOP.md for instructions on how to set up a local devnet.

Repo overview:

• bridge/ — The guardian node which connects to both chains, observes lockups and submits VAAs. Written in pure Go.

  • cmd/guardiand — Most of the business logic for cross-chain communication lives here. Consists of multiple loosely coupled services communicating via Go channels.
  • pkg/devnet — Constants and helper functions for the deterministic local devnet.
  • pkg/ethereum — Ethereum chain interface with auto-generated contract ABI. Uses go-ethereum to directly connect to an Eth node.
  • pkg/solana — Solana chain interface. Light gRPC wrapper around a Rust agent (see below) which actually talks to Solana.
  • pkg/supervisor — Erlang-inspired process supervision tree imported from Certus One's internal code base. We use this everywhere in the bridge code for fault tolerance and fast convergence.
  • pkg/vaa — Go implementation of our VAA structure, including serialization code.

• ethereum/ — Ethereum wormhole contract, tests and fixtures.

  • contracts/ — Wormhole itself, the wrapped token and helper libraries.
  • migrations/ — Ganache migration that deploys the contracts to a local devnet. This is the starting point for both the tests and the devnet. Note that devnet and tests result in different devnet states.
  • src/send-lockups.js — Sends ETH lockups in a loop. See DEVELOP.md for usage.

• solana/ — Solana sidecar agent, contract and CLI.

  • agent/ — Rust agent sidecar deployed alongside each Guardian node. It serves a local gRPC API to interface with the Solana blockchain. This is far easier to maintain than a pure-Go Solana client.
  • bridge/ — Solana Wormhole smart contract code.
  • cli/ — Wormhole user CLI tool for interaction with the smart contract.
  • devnet_setup.sh — Devnet initialization and lockup generator (the Solana equivalent to the Ganache migration + send-lockups.js). Runs as a sidecar alongside the Solana devnet.

• proto/ — Protocol Buffer definitions for the P2P network and the local Solana agent RPC. These are heavily commented and a good intro.

• third_party/ — Build machinery and tooling for third party applications we use.

  • abigen/ — Reproducible build for the go-ethereum ABI code generator we use.
  • solana/ — Build for the full Solana project plus a floating patchset we maintain while waiting for features to be implemented in the upstream project.

• docs/ — Operator documentation and project specs.

• web/ — User interface for cross-chain transfers. Not yet wired into the local devnet. Uses Metamask and Web3.js to initiate transfers from a browser. Watch this video as an introduction.

• tools/ — Reproducible builds for local development tooling like buf and protoc-gen-go.

• Tiltfile, devnet/ and various Dockerfiles — deployment code and fixtures for local development. Deploys a determimistic devnet with an Ethereum devnet, Solana devnet, and a variably sized guardian set that can be used to simulate full cross-chain transfers. The Dockerfiles are carefully designed for fast incremental builds with local caching, and require a recent Docker version with Buildkit support. See DEVELOP.md for usage.

• generate-abi.sh and generate-protos.sh — Helper scripts to (re-)build generated code. The Eth ABI is committed to the repo, so you only need to run this script if the Wormhole.sol interface changes. The protobuf libraries are not committed and will be regenerated automatically by the Tiltfile.