Puente

Local cross-chain testing for LayerZero V2 bridges involving Solana.

What would take 20 minutes on testnet takes seconds locally.

What it does

Puente spins up Surfpool (Solana) and Anvil (EVM), deploys a CPI-compatible mock of the LayerZero Endpoint, and relays messages between chains — all locally, no testnet, no waiting.

Quick start

# Prerequisites
cargo install puente-cli
# or: npm install puente-sdk (includes bundled CLI)

# Check prerequisites
puente doctor

# Start the environment
puente up

# In another terminal, run your tests
puente test --accept-fidelity-limits -- npx vitest run

With the TypeScript SDK

import { PuenteEnv } from 'puente-sdk';

const env = await PuenteEnv.create();

// Happy path
await yourOft.send(/* ... */);
await env.expect.delivered(msgId, { timeout: 5000 });

// Failure injection
env.relay.when('ethereum').thenFail('peer_mismatch');
await yourOft.send(/* ... */);
await env.expect.failed(msgId, 'peer_mismatch');

// Security test: rogue endpoint
env.relay.once('ethereum').thenDeliverViaRogue();

// Cleanup
await env.destroy();

Architecture

┌──────────────────────────────────────────┐
│              puente-cli                    │
│   puente up / puente test / puente doctor │
└─────────────────┬────────────────────────┘
                  │
┌─────────────────▼────────────────────────┐
│              puente (lib)                  │
│  PuenteEnv · Relay Engine · WS API        │
└─────────────────┬────────────────────────┘
                  │
      ┌───────────┼──────────┐
      │           │          │
  Surfpool      Anvil    Mock Endpoint
  (Solana)      (EVM)   (Anchor program)

Fidelity

The mock does NOT replicate:

• DVN verification (CRITICAL) — messages are auto-verified
• Executor authorization (CRITICAL) — any signer can deliver
• MessageLib CPI chain (HIGH) — fees are simplified

Run puente fidelity for the full table. Always verify on devnet before mainnet.

Prerequisites

• Surfpool — Solana runtime
• Anvil — EVM runtime (via Foundry)
• Solana CLI — for program deployment
• Node.js 20+ — for TypeScript SDK

License

MIT