Base-Solana Bridge - Base Documentation

The Base-Solana bridge is currently in testnet only (Base Sepolia ↔ Solana Devnet).

The Base-Solana bridge enables bidirectional token transfers and message passing between Base and Solana networks. This bridge allows you to:

Transfer tokens between Base and Solana
Send arbitrary cross-chain messages
Combine both flows (transfer with arbitrary calls)
Deploy wrapped tokens on either chain

This guide covers the bridge architecture and provides practical examples for implementation.

How it works

On Base

The Base bridge contract locks or burns tokens when sending messages to Solana, and mints or unlocks tokens when receiving messages from Solana. The Bridge contract itself builds Merkle trees from outgoing messages. Validators verify the Merkle root every 300 finalized blocks and relay it to Solana. You then prove your message exists in the tree to complete the transfer on Solana.

Tokens that are native to Base are locked and tokens that are native to Solana are burned when bridging to Solana. Tokens that are native to Solana are minted and tokens that are native to Base are unlocked when bridging to Base.

Key Smart contracts:

Bridge Contract: Handles outgoing transfers
CrossChainERC20: Mintable/burnable tokens for cross-chain transfers
BridgeValidator: Validates messages with oracle signatures
Twin Contract: Your personal smart contract on Base for executing calls from Solana

What is the Twin Contract? The Twin Contract is a smart contract that acts as your execution context on Base. It represents the msg.sender on Base when you send an arbitrary contract call from Solana.

On Solana

The Solana bridge program handles token transfers by locking or burning tokens and emitting events. For messaging, validators relay these messages to Base where they’re executed through your personal Twin contract - a smart contract that acts as your execution context on Base. Key Programs:

Bridge Program: Handles outgoing transfers
Base Relayer Program: Coordinates message relay (not part of the core bridge)

You can access the full repository from the link below:

Base Bridge - Official Repositoryhttps://github.com/base/bridge

The relayer program is not part of the core bridge. This is a convenience feature built on top of the bridge to reduce friction in the Solana -> Base direction.

Bridging Flows

Solana to Base

Automatic relay system for seamless transfers

Base to Solana

Manual proof-based transfers with full control

Builder Codes

Attribute traffic and earn rewards for your bridge integrations

Full Stack Example

Complete application with frontend integration

Solana to Base

Flow: Lock SOL → Wait for Validator Pre-approval → Execute on Base The Solana to Base bridge uses a pull-based model that requires 3 steps:

Initiate the bridge on Solana - Lock your SOL or native SPL token in a Solana vault
Wait for validators to pre-approve the message - Validators verify and approve your bridge message
Execute the message on Base - The approved message is executed on Base to mint SOL and execute any additional arbitrary calls

Tokens that are native to Solana are locked and tokens that are native to Base are burned when bridging to Solana. Tokens that are native to Base are minted and tokens that are native to Solana are unlocked when bridging to Base.

For convenience, a relayer service is available that automatically handles step 3 for users who only want to worry about the initial transaction on Solana. This provides a seamless bridging experience while maintaining the security of the pull-based model.

Solana to Base Relay Scripthttps://github.com/base/bridge/blob/main/scripts/src/commands/sol/onchain/bridge/solana-to-base/bridge-sol.handler.ts

Auto-Relay Example

This is a sample script that shows how to bridge SOL with auto-relay

solToBaseWithAutoRelay/index.ts

// Configure
const TO = "0x8c1a617bdb47342f9c17ac8750e0b070c372c721"; // Base address
const AMOUNT = 0.001; // SOL amount

// Bridge SOL with auto-relay
const ixs = [
  getBridgeSolInstruction({
    payer,
    from: payer,
    solVault: solVaultAddress,
    bridge: bridgeAccountAddress,
    outgoingMessage,
    to: toBytes(TO),
    remoteToken: toBytes("0xC5b9112382f3c87AFE8e1A28fa52452aF81085AD"), // SOL on Base
    amount: BigInt(AMOUNT * 10**9),
  }),
  await buildPayForRelayIx(RELAYER_PROGRAM_ID, outgoingMessage, payer)
];

await buildAndSendTransaction(SOLANA_RPC_URL, ixs, payer);

For more details, see the Solana to Base Relay Script.

Wrap Custom SPL Tokens

The example above shows how to bridge native SOL to Base. To bridge custom SPL tokens, you need to create wrapped ERC20 representations on Base using the CrossChainERC20Factory.

Token Wrapping Examplehttps://github.com/base/bridge/blob/main/scripts/src/commands/sol/onchain/bridge/solana-to-base/wrap-token.handler.ts

wrapSolTokenOnBase/index.ts

// Deploy wrapped token on Base
const mintBytes32 = getBase58Codec().encode(SOLANA_SPL_MINT_ADDRESS).toHex();

await client.writeContract({
  address: "0x58207331CBF8Af87BB6453b610E6579D9878e4EA", // Factory
  abi: TokenFactory,
  functionName: "deploy",
  args: [`0x${mintBytes32}`, "Token Name", "SYMBOL", 9],
});

Base to Solana

Flow: Burn SOL (on Base) → Wait 15min → Generate Proof → Execute on Solana The Base to Solana flow requires manual proof generation. You burn wrapped SOL on Base, wait for finalization, then generate a cryptographic proof to execute on Solana and receive native SOL.

Base to Solana Examplehttps://github.com/base/bridge/blob/main/scripts/src/internal/sol/base.ts

bridgeSolFromBaseToSolana/index.ts

// Step 1: Burn SOL on Base
const transfer = {
  localToken: "0xC5b9112382f3c87AFE8e1A28fa52452aF81085AD", // SOL (on Base)
  remoteToken: pubkeyToBytes32(SOL_ADDRESS),
  to: pubkeyToBytes32(solanaAddress),
  remoteAmount: BigInt(AMOUNT * 10**9),
};

const txHash = await client.writeContract({
  address: "0xB2068ECCDb908902C76E3f965c1712a9cF64171E", // Bridge
  abi: Bridge,
  functionName: "bridgeToken",
  args: [transfer, []],
});

// Step 2: Wait for finalization
const isProvable = await isBridgeMessageProvable(txHash);

// Step 3: Generate proof
const { event, rawProof } = await generateProof(txHash, baseBlockNumber);

// Step 4: Execute on Solana
const proveIx = getProveMessageInstruction({
  nonce: event.message.nonce,
  sender: toBytes(event.message.sender),
  data: toBytes(event.message.data),
  proof: rawProof.map(e => toBytes(e)),
  messageHash: toBytes(event.messageHash),
});

const relayIx = getRelayMessageInstruction({ message: messagePda });
await buildAndSendTransaction(SOLANA_RPC_URL, [proveIx, relayIx], payer);

Builder Codes

Builder codes allow developers to attribute bridge traffic and receive rewards when users bridge through their applications. This feature works with the Solana to Base bridge flow, enabling you to:

Earn rewards for driving bridge traffic
Track attribution for your application’s bridge volume
Chain additional calls on Base while maintaining attribution

Builder codes are currently available for Solana → Base bridge flows only.

Step 0: Register Your Builder Code

For now, Builder Codes are manually assigned by the Base team. Once issued, you’ll receive a bytes32 code to use in your bridge operations.

Hook Data Schema

hookData must be exactly the ABI encoding of:

(address user, bytes32 code, uint16 feeBps)

user → The (user) destination address on Base (NOT the Twin contract address)
code → Your builder code (as bytes32)
feeBps → Fee in basis points (e.g., 100 for 1%)

Example:

address user   = 0xUSER;
bytes32 builderCode = 0xBUILDER_CODE;  // Assigned code
uint16 feeBps      = 100;              // 1%

bytes memory hookData = abi.encode(user, builderCode, feeBps);

Simple Bridge (No Extra Call)

Original (no attribution): Bridge 100 SOL to 0xabc on Base

outgoing_message_salt: <random>
to:                  0xabc
remote_token:        <wSOL on Base>
amount:              100
call:                None

With builder code (prepend Flywheel.send):

outgoing_message_salt: <random>
to:                  <BRIDGE_CAMPAIGN_ADDRESS>
remote_token:        <wSOL on Base>
amount:              100
call:                Some(call_to_send)

call_to_send:
  ty:    Call
  to:    <FLYWHEEL_ADDRESS>
  value: 0
  data:  abi.encodeWithSelector(
           Flywheel.send.selector,
           <BRIDGE_CAMPAIGN_ADDRESS>,
           <wSOL_ADDRESS>,
           hookData // abi.encode(user, builderCode, feeBps)
         )

Why to = BRIDGE_CAMPAIGN_ADDRESS?When using a Builder Code, the token transfer must send the tokens to BRIDGE_CAMPAIGN_ADDRESS. That contract will then forward the tokens to the intended user (recipient) on the base network.

Bridge with Existing Follow-Up Call

Original (no attribution): Bridge 100 SOL to 0xabc on Base, then call Counter.increment()

outgoing_message_salt: <random>
to:                  0xabc
remote_token:        <wSOL on Base>
amount:              100
call:                Some(call)

call:
  ty:    Call
  to:    <COUNTER_ADDRESS>
  value: 0
  data:  abi.encodeWithSelector(Counter.increment.selector)

With builder code (prepend Flywheel + keep Counter call): Wrap both calls in a Multicall executed by DelegateCall from the Twin contract context.

outgoing_message_salt: <random>
to:                  <BRIDGE_CAMPAIGN_ADDRESS>
remote_token:        <wSOL on Base>
amount:              100
call:                Some(call_to_send)

call_to_send:
  ty:    DelegateCall
  to:    <MULTICALL_ADDRESS>
  value: 0
  data:  abi.encodeWithSelector(
           Multicall.multicall.selector,
           calls
         )

Where calls is the ABI-encoded array of Call:

struct Call {
  address to;
  uint256 value;
  bytes   data;
}

Call[] memory calls = new Call[](2);

// 1) Flywheel attribution first
calls[0] = Call({
  to:    <FLYWHEEL_ADDRESS>,
  value: 0,
  data:  abi.encodeWithSelector(
           Flywheel.send.selector,
           <BRIDGE_CAMPAIGN_ADDRESS>,
           <wSOL_ADDRESS>,
           hookData // abi.encode(user, builderCode, feeBps)
         )
});

// 2) Original follow-up
calls[1] = Call({
  to:    <COUNTER_ADDRESS>,
  value: 0,
  data:  abi.encodeWithSelector(Counter.increment.selector)
});

bytes memory data = abi.encodeWithSelector(Multicall.multicall.selector, calls);

Execution order matters! Flywheel.send must be first so attribution is recorded before subsequent actions and the tokens are properly redistributed to the user.

TL;DR

Register a builder code and build hookData = abi.encode(user, code, feeBps)
Set bridge to = <BRIDGE_CAMPAIGN_ADDRESS> and remote_token = <WRAPPED_TOKEN_ADDRESS_ON_BASE>
No extra call? call.ty = Call to Flywheel.send(...)
With extra calls? call.ty = DelegateCall to Multicall.multicall([ Flywheel.send(...), yourCall(...) ])

Utilities

The repository includes utilities for converting between Solana and Base address formats, getting your Solana CLI keypair for signing transactions, and building and sending Solana transactions.

Base Bridge Examples - Utilitieshttps://github.com/base/bridge/tree/main/scripts/src/commands

Address Conversion

Convert Solana pubkey to bytes32 for Base contracts:

example.ts

// Convert Solana pubkey to bytes32 for Base contracts
import { pubkeyToBytes32 } from "./utils/pubkeyToBytes32";

const bytes32Address = pubkeyToBytes32(solanaAddress);

Keypair Management

Get your Solana CLI keypair for signing transactions:

example.ts

import { getSolanaCliConfigKeypairSigner } from "./utils/keypair";

const payer = await getSolanaCliConfigKeypairSigner();

Transaction Building

Build and send Solana transactions:

example.ts

import { buildAndSendTransaction } from "./utils/buildAndSendTransaction";

const signature = await buildAndSendTransaction(SOLANA_RPC_URL, ixs, payer);

Sol2Base: Full Stack Example

Sol2Base - Full Stack Bridge Apphttps://github.com/base/sol2base

Sol2Base is a production-ready Next.js application that demonstrates how to build a complete frontend for the Base-Solana bridge. It features a “hacker” aesthetic with Matrix-style animations and includes wallet integration, CDP faucet, ENS/Basename resolution, and real-time transaction monitoring.

Bridge Service Implementation

The core bridge service handles SOL transfers with automatic relay and address resolution:

src/lib/bridge.ts

export class SolanaBridge {
  private connection: Connection;

  constructor() {
    this.connection = new Connection(SOLANA_DEVNET_CONFIG.rpcUrl, 'confirmed');
  }

  async createBridgeTransaction(
    walletAddress: PublicKey,
    amount: number,
    destinationAddress: string,
    signTransaction: (transaction: Transaction) => Promise<Transaction>
  ): Promise<string> {
    // Import address resolver and real bridge
    const { addressResolver } = await import('./addressResolver');
    const { realBridgeImplementation } = await import('./realBridgeImplementation');
    
    // Resolve destination address (handles ENS/basename)
    const resolvedAddress = await addressResolver.resolveAddress(destinationAddress);

    // Validate amount
    if (amount < BRIDGE_CONFIG.minBridgeAmount / Math.pow(10, 9)) {
      throw new Error(`Minimum bridge amount is ${BRIDGE_CONFIG.minBridgeAmount / Math.pow(10, 9)} SOL`);
    }

    // Create the real bridge transaction
    const transaction = await realBridgeImplementation.createBridgeTransaction(
      walletAddress,
      amount,
      resolvedAddress
    );

    // Submit the transaction
    const signature = await realBridgeImplementation.submitBridgeTransaction(
      transaction,
      walletAddress,
      signTransaction
    );

    return signature;
  }
}

Address Resolution Service

Supports ENS names and Basenames for user-friendly addressing:

src/lib/addressResolver.ts

export class AddressResolver {
  async resolveAddress(input: string): Promise<string> {
    const trimmedInput = input.trim();

    // If it's already a valid Ethereum address, return as-is
    if (this.isValidEthereumAddress(trimmedInput)) {
      return trimmedInput;
    }

    // Handle ENS names (.eth)
    if (trimmedInput.endsWith('.eth') && !trimmedInput.endsWith('.base.eth')) {
      return await this.resolveEns(trimmedInput);
    }

    // Handle basenames (.base.eth or .base)
    if (trimmedInput.endsWith('.base.eth') || trimmedInput.endsWith('.base')) {
      return await this.resolveBasename(trimmedInput);
    }

    throw new Error('Invalid address format');
  }

  private async resolveEns(ensName: string): Promise<string> {
    const response = await fetch(`https://api.ensdata.net/${ensName}`);
    const data = await response.json();
    
    if (!data.address) {
      throw new Error(`ENS name ${ensName} does not resolve to an address`);
    }

    return data.address;
  }
}

React Bridge Interface

Complete UI component with wallet integration and form validation:

src/components/BridgeInterface.tsx

export const BridgeInterface: React.FC = () => {
  const { publicKey, connected, signTransaction } = useWallet();
  const [solBalance, setSolBalance] = useState<number>(0);
  const [transactions, setTransactions] = useState<BridgeTransaction[]>([]);

  // Handle bridge transaction
  const handleBridge = async (amount: number, destinationAddress: string) => {
    if (!publicKey || !signTransaction) {
      setError('Wallet not connected');
      return;
    }

    try {
      const txHash = await solanaBridge.createBridgeTransaction(
        publicKey, 
        amount, 
        destinationAddress,
        signTransaction
      );

      // Add to transaction history
      const newTransaction: BridgeTransaction = {
        txHash,
        amount,
        destinationAddress,
        status: 'confirmed',
        timestamp: Date.now(),
        type: 'bridge'
      };

      setTransactions(prev => [newTransaction, ...prev]);
      await loadBalances();

    } catch (err) {
      setError(err instanceof Error ? err.message : 'Bridge transaction failed');
    }
  };

  return (
    <div className="max-w-4xl mx-auto space-y-8">
      <BalanceDisplay solBalance={solBalance} />
      <FaucetButton onFaucet={handleSolFaucet} />
      <BridgeForm onBridge={handleBridge} maxAmount={solBalance} />
      <TransactionStatus transactions={transactions} />
    </div>
  );
};

Bridge Form with Address Resolution

Smart form component with ENS/Basename support and validation:

src/components/BridgeForm.tsx

export const BridgeForm: React.FC<BridgeFormProps> = ({ onBridge, maxAmount }) => {
  const [amount, setAmount] = useState<string>('');
  const [destinationAddress, setDestinationAddress] = useState<string>('');
  const [resolvedAddress, setResolvedAddress] = useState<string>('');
  const [isResolvingAddress, setIsResolvingAddress] = useState<boolean>(false);

  // Debounced address resolution
  const resolveAddress = useCallback(async (address: string) => {
    if (!address.trim()) return;

    setIsResolvingAddress(true);
    try {
      const type = addressResolver.getInputType(address);
      
      if (type === 'Ethereum Address') {
        setResolvedAddress(address);
      } else {
        const resolved = await addressResolver.resolveAddress(address);
        setResolvedAddress(resolved);
      }
    } catch (error) {
      setErrors(prev => ({ 
        ...prev, 
        address: error instanceof Error ? error.message : 'Failed to resolve address'
      }));
    } finally {
      setIsResolvingAddress(false);
    }
  }, []);

  return (
    <form onSubmit={handleSubmit}>
      <input
        type="number"
        value={amount}
        onChange={(e) => setAmount(e.target.value)}
        placeholder="Enter SOL amount"
      />
      
      <input
        type="text"
        value={destinationAddress}
        onChange={(e) => setDestinationAddress(e.target.value)}
        placeholder="0x..., Basename, or ENS"
      />
      
      {resolvedAddress && resolvedAddress !== destinationAddress && (
        <div className="resolved-address">
          ✓ Resolved to: {resolvedAddress}
        </div>
      )}
      
      <button type="submit" disabled={!amount || !resolvedAddress}>
        Bridge to Base
      </button>
    </form>
  );
};

Setup and Development

Terminal

# Clone and setup
git clone https://github.com/base/sol2base.git
cd sol2base
npm install --legacy-peer-deps

# Environment setup
cp env.template .env.local
# Add Coinbase Developer Platform (CDP) API credentials for faucet (optional)

# Start development server
npm run dev
# Open http://localhost:3000

Get your Coinbase Developer Platform (CDP) API credentials from the the portal.The example above uses the Coinbase Developer Platform faucet for SOL. To get access to the faucet API, you can follow the instructions here.

Contract Addresses

Base Sepolia

{
  "Bridge": "0xB2068ECCDb908902C76E3f965c1712a9cF64171E",
  "CrossChainERC20Factory": "0x58207331CBF8Af87BB6453b610E6579D9878e4EA",
  "WrappedSOL": "0xC5b9112382f3c87AFE8e1A28fa52452aF81085AD"
}

Solana Devnet

{
  "BridgeProgram": "HSvNvzehozUpYhRBuCKq3Fq8udpRocTmGMUYXmCSiCCc",
  "BaseRelayerProgram": "ExS1gcALmaA983oiVpvFSVohi1zCtAUTgsLj5xiFPPgL"
}

Troubleshooting

Transaction failed on Base

Ensure sufficient ETH for gas fees
For ERC20 tokens, approve the bridge contract first using approve()
Verify token addresses are correct and match the expected format
Check that your private key is correctly set in the .env file

Message not appearing on Solana

Wait at least 15 minutes for message relay
Check that your Base transaction was successful and included a MessageRegistered event
Verify you’re using the correct network (testnet/devnet)
Ensure the Solana bridge has processed the Base block number

Proof verification failed

Ensure you’re using the latest Base block number from the Solana bridge
Verify the message hash matches the original transaction
Check that the proof was generated at the correct block height
Make sure all account addresses are correctly derived

Auto-relay not working

Verify you have sufficient SOL to pay for relay fees
Check that the Base Relayer program is properly configured
Ensure the outgoing message was created successfully
Monitor both Solana and Base explorers for transaction status

Security

Important Security Notes:

Only use testnet funds (Solana devnet SOL and Base Sepolia ETH)
Validate all addresses before bridging
Monitor transactions on both chains
Keep your private keys secure and never share them

Resources

GitHub Repository

View source code and examples

Solana Explorer

Monitor Solana devnet transactions

Base Sepolia Explorer

Monitor Base Sepolia transactions

Discord Support

Get help from the community

Quickstart

Network Information

Flashblocks

Node Operators

Tools

Security

​How it works

​On Base

​On Solana

​Bridging Flows

Solana to Base

Base to Solana

Builder Codes

Full Stack Example

​Solana to Base

​Auto-Relay Example

​Wrap Custom SPL Tokens

​Base to Solana

​Builder Codes

​Step 0: Register Your Builder Code

​Hook Data Schema

​Simple Bridge (No Extra Call)

​Bridge with Existing Follow-Up Call

​TL;DR

​Utilities

​Address Conversion

​Keypair Management

​Transaction Building

​Sol2Base: Full Stack Example

​Bridge Service Implementation

​Address Resolution Service

​React Bridge Interface

​Bridge Form with Address Resolution

​Setup and Development

​Contract Addresses

​Base Sepolia

​Solana Devnet

​Troubleshooting

​Security

​Resources

GitHub Repository

Solana Explorer

Base Sepolia Explorer

Discord Support

How it works

On Base

On Solana

Bridging Flows

Solana to Base

Auto-Relay Example

Wrap Custom SPL Tokens

Base to Solana

Builder Codes

Step 0: Register Your Builder Code

Hook Data Schema

Simple Bridge (No Extra Call)

Bridge with Existing Follow-Up Call

TL;DR

Utilities

Address Conversion

Keypair Management

Transaction Building

Sol2Base: Full Stack Example

Bridge Service Implementation

Address Resolution Service

React Bridge Interface

Bridge Form with Address Resolution

Setup and Development

Contract Addresses

Base Sepolia

Solana Devnet

Troubleshooting

Security

Resources