Wormhole integration

Wormhole Integration

Wormhole is one of the largest cross-chain messaging protocols: 50+ supported networks including EVM, Solana, Aptos, Sui, Cosmos (via IBC gateway). By locked asset volume competes with LayerZero and Axelar. Behind Wormhole is network of ~19 Guardian nodes — validators observing events on source chain and signing VAA (Verified Action Approval).

Understanding VAA is key to Wormhole integration. This is message signed by Guardian network about event on one chain, which can be presented to contract on another chain. VAA = proof that event occurred.

Wormhole Architecture

Source Chain                    Wormhole Guardians              Target Chain
    │                                   │                            │
    │ publishMessage(payload)            │                            │
    │ → Core Bridge Contract             │                            │
    │   emits LogMessagePublished        │                            │
    │                            observe event                        │
    │                            sign VAA                             │
    │                            (19 guardians,                       │
    │                             13-of-19 threshold)                 │
    │                                   │  VAA signed                 │
    │                                   │ ──────────────────────────► │
    │                                                       receiveMessage(VAA)
    │                                                       verify Guardian sigs
    │                                                       execute payload

Guardian network is trusted third party. Compromise of 13 of 19 Guardian nodes = full protocol control. This is known Wormhole tradeoff vs more decentralized solutions.

Wormhole Connect: Quick Start for Bridge UI

To add bridge UI to app — Wormhole Connect component. No need to write smart contracts:

npm install @wormhole-foundation/wormhole-connect

import WormholeConnect from '@wormhole-foundation/wormhole-connect'

export default function BridgePage() {
    return (
        <WormholeConnect
            config={{
                network: 'Mainnet',
                chains: ['Ethereum', 'Solana', 'Arbitrum', 'Base', 'BNB'],
                tokens: ['ETH', 'USDC', 'USDT', 'WBTC'],
                rpcs: {
                    Ethereum: 'https://eth-mainnet.g.alchemy.com/v2/...',
                    Solana: 'https://api.mainnet-beta.solana.com',
                },
                ui: {
                    title: 'Bridge',
                    defaultInputs: {
                        fromChain: 'Ethereum',
                        toChain: 'Arbitrum',
                        tokenKey: 'ETH',
                    }
                }
            }}
        />
    )
}

Connect supports multiple routing protocols: Token Bridge (lock-and-mint), CCTP (Circle's native USDC bridge, no wrapped tokens), liquidity portals. Automatically selects optimal route.

Programmatic Integration via Wormhole SDK

For custom cross-chain workflows — TypeScript SDK (wormhole-sdk v3):

import { wormhole } from '@wormhole-foundation/sdk'
import { EvmPlatform } from '@wormhole-foundation/sdk-evm'
import { SolanaPlatform } from '@wormhole-foundation/sdk-solana'

const wh = await wormhole('Mainnet', [EvmPlatform, SolanaPlatform])

// Get chain contexts
const srcChain = wh.getChain('Ethereum')
const dstChain = wh.getChain('Solana')

// Token Bridge transfer
const tb = await srcChain.getTokenBridge()
const transferTxs = tb.transfer(
    senderAddress,
    { chain: 'Solana', address: recipientAddress },
    'native',    // ETH
    1_000_000_000_000_000_000n  // 1 ETH in wei
)

// Send transaction on Source chain
for await (const tx of transferTxs) {
    await signer.sendTransaction(tx.transaction)
}

// Wait for VAA (usually 15 minutes for Ethereum finality)
const [txid] = await srcChain.sendWait(transferTxs, signer)
const vaa = await wh.getVaa(txid, 'TokenBridge:Transfer', 60_000)

// Redeem on Target chain
const redeemTxs = dstChain.getTokenBridge().redeem(recipientAddress, vaa)
for await (const tx of redeemTxs) {
    await solanaSigner.sendTransaction(tx.transaction)
}

CCTP Route for USDC

Circle's Cross-Chain Transfer Protocol via Wormhole — native USDC without wrapped tokens. USDC burned on source chain, minted natively on target. Supported chains: Ethereum, Arbitrum, Base, Optimism, Avalanche, Polygon.

// CCTP transfer via Wormhole SDK — same API, different route
const cctp = await srcChain.getCircleBridge()
const transfer = cctp.transfer(
    sender,
    { chain: 'Arbitrum', address: recipient },
    'USDCeth', // USDC on Ethereum
    1_000_000n  // 1 USDC (6 decimals)
)

CCTP significantly faster than Token Bridge: ~2 minutes vs ~15-20 minutes on Ethereum. For USDC transfers — always prefer.

Custom Messaging: Cross-Chain Applications

Wormhole is not only bridge for tokens — general-purpose messaging. Application can send arbitrary payload from one chain, receive on another.

// Source chain: send message
interface IWormhole {
    function publishMessage(
        uint32 nonce,
        bytes memory payload,
        uint8 consistencyLevel  // 1 = finalized, 200 = instant (Solana)
    ) external payable returns (uint64 sequence);
}

contract CrossChainApp {
    IWormhole wormhole;

    function sendMessage(bytes memory payload) external payable {
        uint64 sequence = wormhole.publishMessage{value: msg.value}(
            0,      // nonce
            payload,
            1       // consistency level: wait for finalization
        );
        emit MessageSent(sequence);
    }
}

// Target chain: receive VAA
contract CrossChainReceiver {
    IWormhole wormhole;
    mapping(bytes32 => bool) processedVAAs;

    function receiveMessage(bytes memory encodedVAA) external {
        (IWormhole.VM memory vm, bool valid, string memory reason) =
            wormhole.parseAndVerifyVM(encodedVAA);

        require(valid, reason);
        require(!processedVAAs[vm.hash], "Already processed");
        processedVAAs[vm.hash] = true;

        // Process payload
        _processPayload(vm.payload);
    }
}

Wormhole Queries: Cross-Chain Data Without Transactions

Wormhole Queries — relatively new mechanism: on-demand reading on-chain data from another chain without sending transactions. Guardian nodes make RPC requests and return signed response.

Application: check balance/staking position on Ethereum directly from contract on Solana. Without oracle, without bridge transaction.

Development Tools and Monitoring

Wormholescan (wormholescan.io) — explorer for VAA and transactions. Invaluable for debugging: find VAA by txHash, check Guardian signature status.

Testnet. Wormhole supports testnets of all chains. Ethereum Sepolia → Solana Devnet — standard test route.

Development Process

Analytics (2-3 days). Define routes (which chains, which tokens), choose between Token Bridge / CCTP / custom messaging, need custom relayer.

Development (2-4 weeks). Depends on scope: Connect UI without contracts — 3-5 days. Custom messaging with contracts on 2 chains — 2-3 weeks. Custom relayer — another 1-2 weeks.

Testing. Mandatory on testnets of both chains. Test edge cases: VAA expiry, double-spend protection (processedVAAs), reorg on source chain.

Simple Wormhole Connect integration into existing app — 3-7 days. Custom cross-chain messaging protocol with relayer — 4-6 weeks.