From 38c96cd290c36947e5d8fb39840ca5b9a18a2cbc Mon Sep 17 00:00:00 2001 From: youssefea Date: Thu, 2 Oct 2025 22:31:05 +0100 Subject: [PATCH 01/29] fix dead link --- .../framework-integrations/wagmi/other-use-cases.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/base-account/framework-integrations/wagmi/other-use-cases.mdx b/docs/base-account/framework-integrations/wagmi/other-use-cases.mdx index bf57aab2..24e25c47 100644 --- a/docs/base-account/framework-integrations/wagmi/other-use-cases.mdx +++ b/docs/base-account/framework-integrations/wagmi/other-use-cases.mdx @@ -106,7 +106,7 @@ Execute multiple transactions in a single user confirmation. ### Gasless Transactions Sponsor gas fees for your users. -**Learn more:** [Gasless Transactions Guide](/base-account/improve-ux/sponsor-gas/paymaster) | [Coinbase Developer Platform Paymaster](https://docs.cdp.coinbase.com/paymaster/introduction/welcome) +**Learn more:** [Gasless Transactions Guide](/base-account/improve-ux/sponsor-gas/paymasters) | [Coinbase Developer Platform Paymaster](https://docs.cdp.coinbase.com/paymaster/introduction/welcome) ### Full list of provider methods and capabilities Access the full list of Base Account provider methods and capabilities. From c9747bf3e3e2c95504e860f11f4734ec9204b25e Mon Sep 17 00:00:00 2001 From: youssefea Date: Fri, 3 Oct 2025 00:12:32 +0100 Subject: [PATCH 02/29] add to docs json --- docs/docs.json | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/docs.json b/docs/docs.json index 2c44b4db..2a274d5f 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -84,7 +84,8 @@ "base-chain/quickstart/why-base", "base-chain/quickstart/deploy-on-base", "base-chain/quickstart/connecting-to-base", - "base-chain/quickstart/bridge-token" + "base-chain/quickstart/bridge-token", + "base-chain/quickstart/bridge-to-solana" ] }, { From e69de30cacf4828c3765b7972a598700026081e9 Mon Sep 17 00:00:00 2001 From: youssefea Date: Fri, 3 Oct 2025 00:12:39 +0100 Subject: [PATCH 03/29] base solaa bridge --- .../quickstart/bridge-to-solana.mdx | 346 ++++++++++++++++++ 1 file changed, 346 insertions(+) create mode 100644 docs/base-chain/quickstart/bridge-to-solana.mdx diff --git a/docs/base-chain/quickstart/bridge-to-solana.mdx b/docs/base-chain/quickstart/bridge-to-solana.mdx new file mode 100644 index 00000000..e8c71038 --- /dev/null +++ b/docs/base-chain/quickstart/bridge-to-solana.mdx @@ -0,0 +1,346 @@ +--- +title: "Base-Solana Bridge" +description: "Bridge tokens and messages between Base and Solana" +icon: "bridge" +--- + +import { GithubRepoCard } from "/snippets/GithubRepoCard.mdx" + + +The Base-Solana bridge is currently in **testnet only** (Base Sepolia ↔ Solana Devnet). The code is a work in progress and has not been audited. **Do not use in production!** + + +The Base-Solana bridge enables bidirectional token transfers and message passing between Base and Solana networks. + +This guide is based on the following repository: + + + +## Getting Started + +First, clone the bridge repository to get access to the contracts, scripts, and CLI tools: + +```bash Terminal +git clone https://github.com/base/bridge.git +cd bridge +``` + +The repository contains: +- **`base/`**: Solidity contracts and Foundry scripts for Base-side operations +- **`solana/`**: Rust programs for Solana-side operations +- **`scripts/`**: TypeScript CLI tools for interacting with both chains +- **`clients/ts/`**: TypeScript SDK for developers + +In the following sections, we'll cover how to bridge tokens and messages between Base and Solana. +You can jump to a specific section using the links below: + + + + Send tokens from Base to Solana + + + Send tokens from Solana to Base + + + +## Base to Solana + +Bridge tokens from Base to Solana using the bridge contracts and CLI tools. + +### Prerequisites + +- [Foundry](https://getfoundry.sh/getting-started/installation) installed +- A funded Base Sepolia wallet (Get [faucets](/base-chain/tools/network-faucets)) + + +**Create or import a wallet using Foundry** + +To create a wallet using [Foundry](https://getfoundry.sh/), you can use [`cast wallet new`](https://getfoundry.sh/cast/reference/wallet/new). +To import a wallet, you can use [`cast wallet import`](https://getfoundry.sh/cast/reference/wallet/import). + + + +### How it works + +The Base bridge contract locks or burns your tokens and emits a message. Validators collect these messages into Merkle trees and post roots to Solana every ~15 minutes. You then prove your message exists in the tree to complete the transfer on Solana. + +**Smart contracts:** +- **Bridge Contract** (`0xB2068ECCDb908902C76E3f965c1712a9cF64171E`): Handles outgoing transfers +- **CrossChainERC20**: Mintable/burnable tokens for cross-chain transfers +- **BridgeValidator**: Validates messages with oracle signatures + +### Bridge tokens + + + + The simplest way to bridge tokens using predefined configurations: + + ```bash Terminal + cd base + + # Bridge wrapped SOL to native SOL on Solana + make bridge-sol-to-solana + + # Bridge wrapped SPL tokens to Solana + make bridge-spl-to-solana + + # Bridge ERC20 tokens to wrapped SPL on Solana + make bridge-erc20-to-solana + + # Bridge ETH to wrapped ETH on Solana + make bridge-eth-to-solana + ``` + + Configure recipients and amounts in the Makefile before running. + + + + For custom token bridging: + + ```bash Terminal + cd base + + BRIDGE_ENVIRONMENT=alpha \ + LOCAL_TOKEN=0x123... \ + REMOTE_TOKEN=0x456... \ + TO=0x789... \ + AMOUNT=1000000 \ + forge script BridgeTokensToSolanaScript \ + --account testnet-admin \ + --rpc-url $BASE_RPC \ + --broadcast -vvvv + ``` + + **Parameters:** + - `LOCAL_TOKEN`: ERC20 token address on Base + - `REMOTE_TOKEN`: bytes32 representation of SPL mint on Solana + - `TO`: bytes32 representation of Solana recipient address + - `AMOUNT`: Amount in wei (smallest unit) + + Convert Solana addresses to bytes32: `bun cli utils pubkey-to-bytes32 ` + + + +### Complete the transfer + +After initiating on Base, wait ~15 minutes for the Merkle root update, then complete on Solana: + +```bash Terminal +cd scripts +bun install + +# Prove your message exists in the Merkle tree +bun cli sol onchain bridge prove-message + +# Execute the proven message +bun cli sol onchain bridge relay-message +``` + +### Create wrapped tokens + +Deploy wrapped versions of Solana tokens on Base: + +```bash Terminal +cd base + +BRIDGE_ENVIRONMENT=alpha \ +TOKEN_NAME="MyToken" \ +TOKEN_SYMBOL="MTK" \ +REMOTE_TOKEN=0x1234... \ +forge script CreateTokenScript \ +--account testnet-admin \ +--rpc-url $BASE_RPC \ +--broadcast -vvvv +``` + +## Solana to Base + +Bridge tokens from Solana to Base using the bridge program and CLI tools. + +### Prerequisites + +- [Solana CLI](https://docs.solana.com/cli/install-solana-cli-tools) installed +- [Bun](https://bun.sh/docs/installation) for running scripts +- Funded Solana keypair at `~/.config/solana/id.json` +- Solana devnet SOL for transaction fees + +### How it works + +The Solana bridge program locks or burns your tokens and emits events. 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. + +**Programs:** +- **Bridge Program** (`HSvNvzehozUpYhRBuCKq3Fq8udpRocTmGMUYXmCSiCCc`): Handles outgoing transfers +- **Base Relayer Program** (`ExS1gcALmaA983oiVpvFSVohi1zCtAUTgsLj5xiFPPgL`): Coordinates message relay +- **Twin Contracts**: Your personal smart contract on Base for receiving tokens + +### Bridge tokens + + + + Bridge native SOL to wrapped SOL on Base: + + ```bash Terminal + cd scripts + bun install + bun cli sol onchain bridge bridge-sol + ``` + + The CLI will prompt for: + - Amount to bridge + - Base recipient address + - Confirmation of transaction details + + + + Bridge SPL tokens to wrapped ERC20 on Base: + + ```bash Terminal + bun cli sol onchain bridge bridge-spl + ``` + + The CLI will: + - Show your SPL token balances + - Let you select which token to bridge + - Prompt for amount and Base recipient + + + + Bridge wrapped Base tokens back to their native form: + + ```bash Terminal + bun cli sol onchain bridge bridge-wrapped-token + ``` + + This burns wrapped tokens on Solana and unlocks the original tokens on Base. + + + +### Create wrapped tokens + +Create wrapped versions of Base tokens on Solana: + +```bash Terminal +cd scripts +bun cli sol onchain bridge wrap-token +``` + +The CLI will prompt for: +- Base token contract address +- Token name and symbol +- Number of decimals + +### Manage SPL tokens + + + + ```bash Terminal + bun cli sol onchain spl create-mint + ``` + + + + ```bash Terminal + bun cli sol onchain spl create-ata + ``` + + + + ```bash Terminal + bun cli sol onchain spl mint + ``` + + + +## Contract Addresses + +### Base Sepolia +```json +{ + "Bridge": "0xB2068ECCDb908902C76E3f965c1712a9cF64171E", + "BridgeValidator": "0x8D2cD165360ACF5f0145661a8FB0Ff5D3729Ef9A", + "CrossChainERC20Factory": "0x58207331CBF8Af87BB6453b610E6579D9878e4EA", + "WrappedSOL": "0xC5b9112382f3c87AFE8e1A28fa52452aF81085AD", + "WrappedSPL": "0x955C7356776F9304feD38ed5AeC5699436C7C614" +} +``` + +### Solana Devnet +```json +{ + "BridgeProgram": "HSvNvzehozUpYhRBuCKq3Fq8udpRocTmGMUYXmCSiCCc", + "BaseRelayerProgram": "ExS1gcALmaA983oiVpvFSVohi1zCtAUTgsLj5xiFPPgL" +} +``` + +## Utilities + +### Address conversion +Convert Solana pubkeys to bytes32 format for Base contracts: + +```bash Terminal +cd scripts +bun cli utils pubkey-to-bytes32 +``` + +### Generate Solana keypair +```bash Terminal +bun cli sol generate-keypair +``` + +### Check bridge status +```bash Terminal +cd base +make check-root # Check current Merkle root on Base +``` + +## Troubleshooting + + + + - Ensure sufficient ETH for gas fees + - For ERC20 tokens, approve the bridge contract first + - Verify token addresses are correct + + + + - Wait at least 15 minutes for Merkle root update + - Check transaction was successful on Base + - Verify you're using the correct network (testnet) + + + + - Ensure you're using the latest Merkle root + - Verify message hash matches the original transaction + - Check validator signatures are valid + + + +## Security + + +**Important Security Notes:** +- Bridge is in active development and unaudited +- Only use testnet funds +- Validate all addresses before bridging +- Monitor transactions on both chains + + +## Resources + + + + View source code and contribute + + + Official Base documentation + + + Official Solana documentation + + + Get help from the community + + \ No newline at end of file From c3280ef23da4e68f60aeb1ed962adec23f94ca8e Mon Sep 17 00:00:00 2001 From: youssefea Date: Fri, 3 Oct 2025 00:16:44 +0100 Subject: [PATCH 04/29] add callout --- docs/base-chain/quickstart/bridge-to-solana.mdx | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/docs/base-chain/quickstart/bridge-to-solana.mdx b/docs/base-chain/quickstart/bridge-to-solana.mdx index e8c71038..c461c902 100644 --- a/docs/base-chain/quickstart/bridge-to-solana.mdx +++ b/docs/base-chain/quickstart/bridge-to-solana.mdx @@ -120,6 +120,16 @@ The Base bridge contract locks or burns your tokens and emits a message. Validat - `TO`: bytes32 representation of Solana recipient address - `AMOUNT`: Amount in wei (smallest unit) + + **Convert Solana addresses to bytes32** + + You can convert Solana addresses to bytes32 using the following command: + + ```bash Terminal + bun cli utils pubkey-to-bytes32 + ``` + + Convert Solana addresses to bytes32: `bun cli utils pubkey-to-bytes32 ` From 2f0efe9df7c4dc09884cd5d996afe5d860d7b34f Mon Sep 17 00:00:00 2001 From: youssefea Date: Fri, 3 Oct 2025 00:20:08 +0100 Subject: [PATCH 05/29] add links --- docs/base-chain/quickstart/bridge-to-solana.mdx | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/base-chain/quickstart/bridge-to-solana.mdx b/docs/base-chain/quickstart/bridge-to-solana.mdx index c461c902..004f845c 100644 --- a/docs/base-chain/quickstart/bridge-to-solana.mdx +++ b/docs/base-chain/quickstart/bridge-to-solana.mdx @@ -344,11 +344,11 @@ make check-root # Check current Merkle root on Base View source code and contribute - - Official Base documentation + + Official Foundry documentation - - Official Solana documentation + + Official Solana Anchor documentation Get help from the community From 32f1d0af8dbf7750e333bc32714ba2b676ddc29b Mon Sep 17 00:00:00 2001 From: youssefea Date: Fri, 3 Oct 2025 00:21:51 +0100 Subject: [PATCH 06/29] update the faucet link --- docs/base-chain/quickstart/bridge-to-solana.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/base-chain/quickstart/bridge-to-solana.mdx b/docs/base-chain/quickstart/bridge-to-solana.mdx index 004f845c..e332614e 100644 --- a/docs/base-chain/quickstart/bridge-to-solana.mdx +++ b/docs/base-chain/quickstart/bridge-to-solana.mdx @@ -175,7 +175,7 @@ Bridge tokens from Solana to Base using the bridge program and CLI tools. - [Solana CLI](https://docs.solana.com/cli/install-solana-cli-tools) installed - [Bun](https://bun.sh/docs/installation) for running scripts - Funded Solana keypair at `~/.config/solana/id.json` -- Solana devnet SOL for transaction fees +- Solana devnet SOL for transaction fees (get from [Solana Faucet](https://faucet.solana.com/)) ### How it works From e39203a65c7ad8d2a0e1c6f6355d8d0820ab91fb Mon Sep 17 00:00:00 2001 From: youssefea Date: Fri, 3 Oct 2025 00:25:36 +0100 Subject: [PATCH 07/29] update title --- docs/base-chain/quickstart/bridge-token.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/base-chain/quickstart/bridge-token.mdx b/docs/base-chain/quickstart/bridge-token.mdx index 4810fcba..6395a39c 100644 --- a/docs/base-chain/quickstart/bridge-token.mdx +++ b/docs/base-chain/quickstart/bridge-token.mdx @@ -1,6 +1,6 @@ --- title: "Bridging an L1 token to Base" -sidebarTitle: 'Bridge Tokens to Base' +sidebarTitle: 'Base-Mainnet Bridge' description: How to submit ERC-20 tokens for bridging between Ethereum and Base as a token issuer. --- From 4764c8fabd55914da3b2420cd7ea79ef28bb7e54 Mon Sep 17 00:00:00 2001 From: youssefea Date: Mon, 6 Oct 2025 23:05:11 +0100 Subject: [PATCH 08/29] update name --- .../quickstart/{bridge-to-solana.mdx => base-solana-bridge.mdx} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename docs/base-chain/quickstart/{bridge-to-solana.mdx => base-solana-bridge.mdx} (100%) diff --git a/docs/base-chain/quickstart/bridge-to-solana.mdx b/docs/base-chain/quickstart/base-solana-bridge.mdx similarity index 100% rename from docs/base-chain/quickstart/bridge-to-solana.mdx rename to docs/base-chain/quickstart/base-solana-bridge.mdx From a61e1e779573a1b6d4d0b6920c9743455e51d5ef Mon Sep 17 00:00:00 2001 From: youssefea Date: Mon, 6 Oct 2025 23:55:41 +0100 Subject: [PATCH 09/29] update docs json --- docs/docs.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docs.json b/docs/docs.json index 9d465d49..d9b4057c 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -85,7 +85,7 @@ "base-chain/quickstart/deploy-on-base", "base-chain/quickstart/connecting-to-base", "base-chain/quickstart/bridge-token", - "base-chain/quickstart/bridge-to-solana" + "base-chain/quickstart/base-solana-bridge" ] }, { From 6f675103f92f7e392c9c8c94d08f3bcbe494b79a Mon Sep 17 00:00:00 2001 From: youssefea Date: Tue, 7 Oct 2025 00:24:46 +0100 Subject: [PATCH 10/29] update base solana guide --- .../quickstart/base-solana-bridge.mdx | 656 +++++++++++------- 1 file changed, 404 insertions(+), 252 deletions(-) diff --git a/docs/base-chain/quickstart/base-solana-bridge.mdx b/docs/base-chain/quickstart/base-solana-bridge.mdx index e332614e..92c23168 100644 --- a/docs/base-chain/quickstart/base-solana-bridge.mdx +++ b/docs/base-chain/quickstart/base-solana-bridge.mdx @@ -7,277 +7,402 @@ icon: "bridge" import { GithubRepoCard } from "/snippets/GithubRepoCard.mdx" -The Base-Solana bridge is currently in **testnet only** (Base Sepolia ↔ Solana Devnet). The code is a work in progress and has not been audited. **Do not use in production!** + The Base-Solana bridge is currently in **testnet only** (Base Sepolia ↔ Solana Devnet). The code is a work in progress and has not been audited. **Do not use in production!** -The Base-Solana bridge enables bidirectional token transfers and message passing between Base and Solana networks. +The Base-Solana bridge enables bidirectional token transfers and message passing between Base and Solana networks. This bridge allows you to: -This guide is based on the following repository: +* **Transfer tokens** between Base and Solana +* **Send arbitrary cross-chain messages** +* **Deploy wrapped tokens** on either chain - +This guide covers the bridge architecture and provides practical examples for implementation. -## Getting Started +## How it works -First, clone the bridge repository to get access to the contracts, scripts, and CLI tools: +### On Base +The Base bridge contract locks or burns your tokens and emits a message. Validators collect these messages into Merkle trees and post roots to Solana every ~15 minutes. You then prove your message exists in the tree to complete the transfer on Solana. -```bash Terminal -git clone https://github.com/base/bridge.git -cd bridge -``` +**Smart contracts:** +- **Bridge Contract** (`0xB2068ECCDb908902C76E3f965c1712a9cF64171E`): Handles outgoing transfers +- **CrossChainERC20**: Mintable/burnable tokens for cross-chain transfers +- **BridgeValidator**: Validates messages with oracle signatures -The repository contains: -- **`base/`**: Solidity contracts and Foundry scripts for Base-side operations -- **`solana/`**: Rust programs for Solana-side operations -- **`scripts/`**: TypeScript CLI tools for interacting with both chains -- **`clients/ts/`**: TypeScript SDK for developers +### On Solana +The Solana bridge program locks or burns your tokens and emits events. 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. +**Programs:** +- **Bridge Program** (`HSvNvzehozUpYhRBuCKq3Fq8udpRocTmGMUYXmCSiCCc`): Handles outgoing transfers +- **Base Relayer Program** (`ExS1gcALmaA983oiVpvFSVohi1zCtAUTgsLj5xiFPPgL`): Coordinates message relay +- **Twin Contracts**: Your personal smart contract on Base for receiving tokens -In the following sections, we'll cover how to bridge tokens and messages between Base and Solana. -You can jump to a specific section using the links below: +**Key Contracts:** +- **Base**: Bridge (`0xB2068ECCDb908902C76E3f965c1712a9cF64171E`), Factory (`0x58207331CBF8Af87BB6453b610E6579D9878e4EA`) +- **Solana**: Bridge (`HSvNvzehozUpYhRBuCKq3Fq8udpRocTmGMUYXmCSiCCc`), Relayer (`ExS1gcALmaA983oiVpvFSVohi1zCtAUTgsLj5xiFPPgL`) - - - Send tokens from Base to Solana +You can access the full repository from the link below: + + +## Bridging Flows + + + + Automatic relay system for seamless transfers - - Send tokens from Solana to Base + + + Manual proof-based transfers with full control + + + + Complete application with frontend integration -## Base to Solana +## Solana to Base -Bridge tokens from Base to Solana using the bridge contracts and CLI tools. +**Flow:** Lock SOL → Auto-Relay → Mint wSOL on Base + +The Solana to Base flow in this example uses automatic relay for seamless transfers. Your SOL is locked in a Solana vault, and the relayer automatically executes the message on Base to mint wrapped SOL. + + + +```typescript solToBaseWithAutoRelay/index.ts expandable +// 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"), // wSOL + amount: BigInt(AMOUNT * 10**9), + }), + await buildPayForRelayIx(RELAYER_PROGRAM_ID, outgoingMessage, payer) +]; + +await buildAndSendTransaction(SOLANA_RPC_URL, ixs, payer); +``` -### Prerequisites +### Wrap Custom SPL Tokens -- [Foundry](https://getfoundry.sh/getting-started/installation) installed -- A funded Base Sepolia wallet (Get [faucets](/base-chain/tools/network-faucets)) +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. - -**Create or import a wallet using Foundry** + -To create a wallet using [Foundry](https://getfoundry.sh/), you can use [`cast wallet new`](https://getfoundry.sh/cast/reference/wallet/new). -To import a wallet, you can use [`cast wallet import`](https://getfoundry.sh/cast/reference/wallet/import). +```typescript wrapSolTokenOnBase/index.ts expandable +// 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], +}); +``` -### How it works +## Base to Solana -The Base bridge contract locks or burns your tokens and emits a message. Validators collect these messages into Merkle trees and post roots to Solana every ~15 minutes. You then prove your message exists in the tree to complete the transfer on Solana. +**Flow:** Burn wSOL → 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 (~15 minutes), then generate a cryptographic proof to execute on Solana and receive native SOL. + + + +```typescript bridgeSolFromBaseToSolana/index.ts expandable +// Step 1: Burn wSOL on Base +const transfer = { + localToken: "0xC5b9112382f3c87AFE8e1A28fa52452aF81085AD", // wSOL + 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); +``` -**Smart contracts:** -- **Bridge Contract** (`0xB2068ECCDb908902C76E3f965c1712a9cF64171E`): Handles outgoing transfers -- **CrossChainERC20**: Mintable/burnable tokens for cross-chain transfers -- **BridgeValidator**: Validates messages with oracle signatures +## Sol2Base: Full Stack Example -### Bridge tokens + - - - The simplest way to bridge tokens using predefined configurations: +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. - ```bash Terminal - cd base - - # Bridge wrapped SOL to native SOL on Solana - make bridge-sol-to-solana - - # Bridge wrapped SPL tokens to Solana - make bridge-spl-to-solana - - # Bridge ERC20 tokens to wrapped SPL on Solana - make bridge-erc20-to-solana - - # Bridge ETH to wrapped ETH on Solana - make bridge-eth-to-solana - ``` - - Configure recipients and amounts in the Makefile before running. - - - - For custom token bridging: - - ```bash Terminal - cd base +### Bridge Service Implementation + +The core bridge service handles SOL transfers with automatic relay and address resolution: + +```typescript src/lib/bridge.ts expandable +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 + ): Promise { + // Import address resolver and real bridge + const { addressResolver } = await import('./addressResolver'); + const { realBridgeImplementation } = await import('./realBridgeImplementation'); - BRIDGE_ENVIRONMENT=alpha \ - LOCAL_TOKEN=0x123... \ - REMOTE_TOKEN=0x456... \ - TO=0x789... \ - AMOUNT=1000000 \ - forge script BridgeTokensToSolanaScript \ - --account testnet-admin \ - --rpc-url $BASE_RPC \ - --broadcast -vvvv - ``` - - **Parameters:** - - `LOCAL_TOKEN`: ERC20 token address on Base - - `REMOTE_TOKEN`: bytes32 representation of SPL mint on Solana - - `TO`: bytes32 representation of Solana recipient address - - `AMOUNT`: Amount in wei (smallest unit) - - - **Convert Solana addresses to bytes32** - - You can convert Solana addresses to bytes32 using the following command: - - ```bash Terminal - bun cli utils pubkey-to-bytes32 - ``` - - - Convert Solana addresses to bytes32: `bun cli utils pubkey-to-bytes32 ` - - - -### Complete the transfer - -After initiating on Base, wait ~15 minutes for the Merkle root update, then complete on Solana: - -```bash Terminal -cd scripts -bun install - -# Prove your message exists in the Merkle tree -bun cli sol onchain bridge prove-message - -# Execute the proven message -bun cli sol onchain bridge relay-message + // 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 -### Create wrapped tokens +Supports ENS names and Basenames for user-friendly addressing: -Deploy wrapped versions of Solana tokens on Base: +```typescript src/lib/addressResolver.ts expandable +export class AddressResolver { + async resolveAddress(input: string): Promise { + const trimmedInput = input.trim(); -```bash Terminal -cd base + // If it's already a valid Ethereum address, return as-is + if (this.isValidEthereumAddress(trimmedInput)) { + return trimmedInput; + } -BRIDGE_ENVIRONMENT=alpha \ -TOKEN_NAME="MyToken" \ -TOKEN_SYMBOL="MTK" \ -REMOTE_TOKEN=0x1234... \ -forge script CreateTokenScript \ ---account testnet-admin \ ---rpc-url $BASE_RPC \ ---broadcast -vvvv -``` + // Handle ENS names (.eth) + if (trimmedInput.endsWith('.eth') && !trimmedInput.endsWith('.base.eth')) { + return await this.resolveEns(trimmedInput); + } -## Solana to Base + // Handle basenames (.base.eth or .base) + if (trimmedInput.endsWith('.base.eth') || trimmedInput.endsWith('.base')) { + return await this.resolveBasename(trimmedInput); + } -Bridge tokens from Solana to Base using the bridge program and CLI tools. + throw new Error('Invalid address format'); + } -### Prerequisites + private async resolveEns(ensName: string): Promise { + 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`); + } -- [Solana CLI](https://docs.solana.com/cli/install-solana-cli-tools) installed -- [Bun](https://bun.sh/docs/installation) for running scripts -- Funded Solana keypair at `~/.config/solana/id.json` -- Solana devnet SOL for transaction fees (get from [Solana Faucet](https://faucet.solana.com/)) + return data.address; + } +} +``` -### How it works +### React Bridge Interface + +Complete UI component with wallet integration and form validation: + +```typescript src/components/BridgeInterface.tsx expandable +export const BridgeInterface: React.FC = () => { + const { publicKey, connected, signTransaction } = useWallet(); + const [solBalance, setSolBalance] = useState(0); + const [transactions, setTransactions] = useState([]); + + // 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 ( +
+ + + + +
+ ); +}; +``` -The Solana bridge program locks or burns your tokens and emits events. 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. +### Bridge Form with Address Resolution + +Smart form component with ENS/Basename support and validation: + +```typescript src/components/BridgeForm.tsx expandable +export const BridgeForm: React.FC = ({ onBridge, maxAmount }) => { + const [amount, setAmount] = useState(''); + const [destinationAddress, setDestinationAddress] = useState(''); + const [resolvedAddress, setResolvedAddress] = useState(''); + const [isResolvingAddress, setIsResolvingAddress] = useState(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 ( +
+ setAmount(e.target.value)} + placeholder="Enter SOL amount" + /> + + setDestinationAddress(e.target.value)} + placeholder="0x..., Basename, or ENS" + /> + + {resolvedAddress && resolvedAddress !== destinationAddress && ( +
+ ✓ Resolved to: {resolvedAddress} +
+ )} + + +
+ ); +}; +``` -**Programs:** -- **Bridge Program** (`HSvNvzehozUpYhRBuCKq3Fq8udpRocTmGMUYXmCSiCCc`): Handles outgoing transfers -- **Base Relayer Program** (`ExS1gcALmaA983oiVpvFSVohi1zCtAUTgsLj5xiFPPgL`): Coordinates message relay -- **Twin Contracts**: Your personal smart contract on Base for receiving tokens +### Setup and Development + +```bash Terminal expandable +# 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) -### Bridge tokens - - - - Bridge native SOL to wrapped SOL on Base: - - ```bash Terminal - cd scripts - bun install - bun cli sol onchain bridge bridge-sol - ``` - - The CLI will prompt for: - - Amount to bridge - - Base recipient address - - Confirmation of transaction details - - - - Bridge SPL tokens to wrapped ERC20 on Base: - - ```bash Terminal - bun cli sol onchain bridge bridge-spl - ``` - - The CLI will: - - Show your SPL token balances - - Let you select which token to bridge - - Prompt for amount and Base recipient - - - - Bridge wrapped Base tokens back to their native form: - - ```bash Terminal - bun cli sol onchain bridge bridge-wrapped-token - ``` - - This burns wrapped tokens on Solana and unlocks the original tokens on Base. - - - -### Create wrapped tokens - -Create wrapped versions of Base tokens on Solana: - -```bash Terminal -cd scripts -bun cli sol onchain bridge wrap-token +# Start development server +npm run dev +# Open http://localhost:3000 ``` -The CLI will prompt for: -- Base token contract address -- Token name and symbol -- Number of decimals - -### Manage SPL tokens - - - - ```bash Terminal - bun cli sol onchain spl create-mint - ``` - - - - ```bash Terminal - bun cli sol onchain spl create-ata - ``` - - - - ```bash Terminal - bun cli sol onchain spl mint - ``` - - + +**Get your Coinbase Developer Platform (CDP) API credentials from the [the portal](https://portal.cdp.coinbase.com/projects/api-keys/client-key).** + +The example above uses the Coinbase Developer Platform faucet for SOL. +To get access to the faucet API, you can follow the instructions [here](https://docs.cdp.coinbase.com/faucets/introduction/welcome). + ## Contract Addresses ### Base Sepolia + ```json { "Bridge": "0xB2068ECCDb908902C76E3f965c1712a9cF64171E", - "BridgeValidator": "0x8D2cD165360ACF5f0145661a8FB0Ff5D3729Ef9A", "CrossChainERC20Factory": "0x58207331CBF8Af87BB6453b610E6579D9878e4EA", - "WrappedSOL": "0xC5b9112382f3c87AFE8e1A28fa52452aF81085AD", - "WrappedSPL": "0x955C7356776F9304feD38ed5AeC5699436C7C614" + "WrappedSOL": "0xC5b9112382f3c87AFE8e1A28fa52452aF81085AD" } ``` ### Solana Devnet + ```json { "BridgeProgram": "HSvNvzehozUpYhRBuCKq3Fq8udpRocTmGMUYXmCSiCCc", @@ -287,70 +412,97 @@ The CLI will prompt for: ## Utilities -### Address conversion -Convert Solana pubkeys to bytes32 format for Base contracts: +### Address Conversion + +The repository includes utilities for converting between Solana and Base address formats: + +```typescript +// Convert Solana pubkey to bytes32 for Base contracts +import { pubkeyToBytes32 } from "./utils/pubkeyToBytes32"; -```bash Terminal -cd scripts -bun cli utils pubkey-to-bytes32 +const bytes32Address = pubkeyToBytes32(solanaAddress); ``` -### Generate Solana keypair -```bash Terminal -bun cli sol generate-keypair +### Keypair Management + +Get your Solana CLI keypair for signing transactions: + +```typescript +import { getSolanaCliConfigKeypairSigner } from "./utils/keypair"; + +const payer = await getSolanaCliConfigKeypairSigner(); ``` -### Check bridge status -```bash Terminal -cd base -make check-root # Check current Merkle root on Base +### Transaction Building + +Build and send Solana transactions: + +```typescript +import { buildAndSendTransaction } from "./utils/buildAndSendTransaction"; + +const signature = await buildAndSendTransaction(SOLANA_RPC_URL, ixs, payer); ``` ## Troubleshooting - - Ensure sufficient ETH for gas fees - - For ERC20 tokens, approve the bridge contract first - - Verify token addresses are correct + * 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 - + - - Wait at least 15 minutes for Merkle root update - - Check transaction was successful on Base - - Verify you're using the correct network (testnet) + * Wait at least 15 minutes for Base block finalization + * 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 - + - - Ensure you're using the latest Merkle root - - Verify message hash matches the original transaction - - Check validator signatures are valid + * 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 + + + + * 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:** -- Bridge is in active development and unaudited -- Only use testnet funds -- Validate all addresses before bridging -- Monitor transactions on both chains + **Important Security Notes:** + + * Bridge is in active development and unaudited + * 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 - - View source code and contribute + + View source code and examples - - Official Foundry documentation + + + Monitor Solana devnet transactions - - Official Solana Anchor documentation + + + Monitor Base Sepolia transactions + Get help from the community - \ No newline at end of file + From fb5b257fb19ea223cd98f6e8e0dd9d1c59d3a6f4 Mon Sep 17 00:00:00 2001 From: youssefea Date: Tue, 7 Oct 2025 00:27:16 +0100 Subject: [PATCH 11/29] update real sub section --- docs/base-chain/quickstart/base-solana-bridge.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/base-chain/quickstart/base-solana-bridge.mdx b/docs/base-chain/quickstart/base-solana-bridge.mdx index 92c23168..d0921222 100644 --- a/docs/base-chain/quickstart/base-solana-bridge.mdx +++ b/docs/base-chain/quickstart/base-solana-bridge.mdx @@ -53,7 +53,7 @@ You can access the full repository from the link below: Manual proof-based transfers with full control - + Complete application with frontend integration From 5e47b9120255d1eb2adda532deaead34a87bd68c Mon Sep 17 00:00:00 2001 From: youssefea Date: Tue, 7 Oct 2025 00:29:40 +0100 Subject: [PATCH 12/29] update magnifying glass --- docs/base-chain/quickstart/base-solana-bridge.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/base-chain/quickstart/base-solana-bridge.mdx b/docs/base-chain/quickstart/base-solana-bridge.mdx index d0921222..a315b01b 100644 --- a/docs/base-chain/quickstart/base-solana-bridge.mdx +++ b/docs/base-chain/quickstart/base-solana-bridge.mdx @@ -494,11 +494,11 @@ const signature = await buildAndSendTransaction(SOLANA_RPC_URL, ixs, payer); View source code and examples - + Monitor Solana devnet transactions - + Monitor Base Sepolia transactions From feea961bac55c60d466d209ccecafbdad8262583 Mon Sep 17 00:00:00 2001 From: youssefea Date: Tue, 7 Oct 2025 00:30:44 +0100 Subject: [PATCH 13/29] remove key contracts --- docs/base-chain/quickstart/base-solana-bridge.mdx | 4 ---- 1 file changed, 4 deletions(-) diff --git a/docs/base-chain/quickstart/base-solana-bridge.mdx b/docs/base-chain/quickstart/base-solana-bridge.mdx index a315b01b..3e1d1759 100644 --- a/docs/base-chain/quickstart/base-solana-bridge.mdx +++ b/docs/base-chain/quickstart/base-solana-bridge.mdx @@ -35,10 +35,6 @@ The Solana bridge program locks or burns your tokens and emits events. Validator - **Base Relayer Program** (`ExS1gcALmaA983oiVpvFSVohi1zCtAUTgsLj5xiFPPgL`): Coordinates message relay - **Twin Contracts**: Your personal smart contract on Base for receiving tokens -**Key Contracts:** -- **Base**: Bridge (`0xB2068ECCDb908902C76E3f965c1712a9cF64171E`), Factory (`0x58207331CBF8Af87BB6453b610E6579D9878e4EA`) -- **Solana**: Bridge (`HSvNvzehozUpYhRBuCKq3Fq8udpRocTmGMUYXmCSiCCc`), Relayer (`ExS1gcALmaA983oiVpvFSVohi1zCtAUTgsLj5xiFPPgL`) - You can access the full repository from the link below: From d5453c12c6ce6703c101c3d2b23049a921e04bce Mon Sep 17 00:00:00 2001 From: youssefea Date: Tue, 7 Oct 2025 00:43:14 +0100 Subject: [PATCH 14/29] add updates --- .../quickstart/base-solana-bridge.mdx | 93 +++++++++++-------- 1 file changed, 52 insertions(+), 41 deletions(-) diff --git a/docs/base-chain/quickstart/base-solana-bridge.mdx b/docs/base-chain/quickstart/base-solana-bridge.mdx index 3e1d1759..dc398872 100644 --- a/docs/base-chain/quickstart/base-solana-bridge.mdx +++ b/docs/base-chain/quickstart/base-solana-bridge.mdx @@ -23,17 +23,23 @@ This guide covers the bridge architecture and provides practical examples for im ### On Base The Base bridge contract locks or burns your tokens and emits a message. Validators collect these messages into Merkle trees and post roots to Solana every ~15 minutes. You then prove your message exists in the tree to complete the transfer on Solana. -**Smart contracts:** -- **Bridge Contract** (`0xB2068ECCDb908902C76E3f965c1712a9cF64171E`): Handles outgoing transfers -- **CrossChainERC20**: Mintable/burnable tokens for cross-chain transfers -- **BridgeValidator**: Validates messages with oracle signatures +**Key Smart contracts:** +- [**Bridge Contract**](https://github.com/base/bridge/blob/main/base/src/Bridge.sol): Handles outgoing transfers +- [**CrossChainERC20**](https://github.com/base/bridge/blob/main/base/src/CrossChainERC20.sol): Mintable/burnable tokens for cross-chain transfers +- [**BridgeValidator**](https://github.com/base/bridge/blob/main/base/src/BridgeValidator.sol): Validates messages with oracle signatures +- [**Twin Contract**](https://github.com/base/bridge/blob/main/base/src/Twin.sol): 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 locks or burns your tokens and emits events. 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. -**Programs:** -- **Bridge Program** (`HSvNvzehozUpYhRBuCKq3Fq8udpRocTmGMUYXmCSiCCc`): Handles outgoing transfers -- **Base Relayer Program** (`ExS1gcALmaA983oiVpvFSVohi1zCtAUTgsLj5xiFPPgL`): Coordinates message relay -- **Twin Contracts**: Your personal smart contract on Base for receiving tokens +**Key Programs:** +- [**Bridge Program**](https://github.com/base/bridge/blob/main/solana/programs/bridge): Handles outgoing transfers +- [**Base Relayer Program**](https://github.com/base/bridge/blob/main/solana/programs/base_relayer): Coordinates message relay You can access the full repository from the link below: @@ -148,6 +154,44 @@ const relayIx = getRelayMessageInstruction({ message: messagePda }); await buildAndSendTransaction(SOLANA_RPC_URL, [proveIx, relayIx], payer); ``` +## 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. + + + +### Address Conversion + +Convert Solana pubkey to bytes32 for Base contracts: +```typescript 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: + +```typescript example.ts +import { getSolanaCliConfigKeypairSigner } from "./utils/keypair"; + +const payer = await getSolanaCliConfigKeypairSigner(); +``` + +### Transaction Building + +Build and send Solana transactions: + +```typescript example.ts +import { buildAndSendTransaction } from "./utils/buildAndSendTransaction"; + +const signature = await buildAndSendTransaction(SOLANA_RPC_URL, ixs, payer); +``` + ## Sol2Base: Full Stack Example @@ -406,39 +450,6 @@ To get access to the faucet API, you can follow the instructions [here](https:// } ``` -## Utilities - -### Address Conversion - -The repository includes utilities for converting between Solana and Base address formats: - -```typescript -// 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: - -```typescript -import { getSolanaCliConfigKeypairSigner } from "./utils/keypair"; - -const payer = await getSolanaCliConfigKeypairSigner(); -``` - -### Transaction Building - -Build and send Solana transactions: - -```typescript -import { buildAndSendTransaction } from "./utils/buildAndSendTransaction"; - -const signature = await buildAndSendTransaction(SOLANA_RPC_URL, ixs, payer); -``` - ## Troubleshooting From 660677e9da2cb1d8406d8c16dcac2aa27a8f27c6 Mon Sep 17 00:00:00 2001 From: youssefea Date: Tue, 7 Oct 2025 00:47:56 +0100 Subject: [PATCH 15/29] add line key programs --- docs/base-chain/quickstart/base-solana-bridge.mdx | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/base-chain/quickstart/base-solana-bridge.mdx b/docs/base-chain/quickstart/base-solana-bridge.mdx index dc398872..dd0c8963 100644 --- a/docs/base-chain/quickstart/base-solana-bridge.mdx +++ b/docs/base-chain/quickstart/base-solana-bridge.mdx @@ -37,6 +37,7 @@ It represents the `msg.sender` on Base when you send an arbitrary contract call ### On Solana The Solana bridge program locks or burns your tokens and emits events. 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**](https://github.com/base/bridge/blob/main/solana/programs/bridge): Handles outgoing transfers - [**Base Relayer Program**](https://github.com/base/bridge/blob/main/solana/programs/base_relayer): Coordinates message relay From 383251f44ede8a84f16f6616683355f1b32ab1e6 Mon Sep 17 00:00:00 2001 From: youssefea Date: Tue, 7 Oct 2025 00:52:13 +0100 Subject: [PATCH 16/29] remove jack --- docs/base-chain/quickstart/base-solana-bridge.mdx | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/base-chain/quickstart/base-solana-bridge.mdx b/docs/base-chain/quickstart/base-solana-bridge.mdx index dd0c8963..bd56fe23 100644 --- a/docs/base-chain/quickstart/base-solana-bridge.mdx +++ b/docs/base-chain/quickstart/base-solana-bridge.mdx @@ -67,7 +67,7 @@ You can access the full repository from the link below: The Solana to Base flow in this example uses automatic relay for seamless transfers. Your SOL is locked in a Solana vault, and the relayer automatically executes the message on Base to mint wrapped SOL. - + ```typescript solToBaseWithAutoRelay/index.ts expandable // Configure @@ -98,7 +98,7 @@ 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. - + ```typescript wrapSolTokenOnBase/index.ts expandable // Deploy wrapped token on Base @@ -118,7 +118,7 @@ await client.writeContract({ The Base to Solana flow requires manual proof generation. You burn wrapped SOL on Base, wait for finalization (~15 minutes), then generate a cryptographic proof to execute on Solana and receive native SOL. - + ```typescript bridgeSolFromBaseToSolana/index.ts expandable // Step 1: Burn wSOL on Base @@ -161,7 +161,7 @@ The repository includes utilities for converting between Solana and Base address getting your Solana CLI keypair for signing transactions, and building and sending Solana transactions. - + ### Address Conversion @@ -498,7 +498,7 @@ To get access to the faucet API, you can follow the instructions [here](https:// ## Resources - + View source code and examples From aa737ff744c8d4a7404e18b386e44033ebec153b Mon Sep 17 00:00:00 2001 From: youssefea Date: Tue, 7 Oct 2025 15:14:58 +0100 Subject: [PATCH 17/29] update doc --- docs/base-chain/quickstart/base-solana-bridge.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/base-chain/quickstart/base-solana-bridge.mdx b/docs/base-chain/quickstart/base-solana-bridge.mdx index bd56fe23..75a17d74 100644 --- a/docs/base-chain/quickstart/base-solana-bridge.mdx +++ b/docs/base-chain/quickstart/base-solana-bridge.mdx @@ -462,7 +462,7 @@ To get access to the faucet API, you can follow the instructions [here](https:// - * Wait at least 15 minutes for Base block finalization + * 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 From 709f3a6d108c306ccebfb83ac92dd2a6fa74f6e4 Mon Sep 17 00:00:00 2001 From: Youssef Date: Wed, 8 Oct 2025 15:14:14 +0100 Subject: [PATCH 18/29] Update docs/base-chain/quickstart/base-solana-bridge.mdx Co-authored-by: Jack Chuma --- docs/base-chain/quickstart/base-solana-bridge.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/base-chain/quickstart/base-solana-bridge.mdx b/docs/base-chain/quickstart/base-solana-bridge.mdx index 75a17d74..b741530c 100644 --- a/docs/base-chain/quickstart/base-solana-bridge.mdx +++ b/docs/base-chain/quickstart/base-solana-bridge.mdx @@ -63,7 +63,7 @@ You can access the full repository from the link below: ## Solana to Base -**Flow:** Lock SOL → Auto-Relay → Mint wSOL on Base +**Flow:** Lock SOL → Auto-Relay → Mint SOL on Base The Solana to Base flow in this example uses automatic relay for seamless transfers. Your SOL is locked in a Solana vault, and the relayer automatically executes the message on Base to mint wrapped SOL. From 8ea6f091941c4976a3cd1fd1d889634fd8fe8b0d Mon Sep 17 00:00:00 2001 From: youssefea Date: Wed, 8 Oct 2025 15:15:46 +0100 Subject: [PATCH 19/29] add combination --- docs/base-chain/quickstart/base-solana-bridge.mdx | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/base-chain/quickstart/base-solana-bridge.mdx b/docs/base-chain/quickstart/base-solana-bridge.mdx index b741530c..52f5c7f5 100644 --- a/docs/base-chain/quickstart/base-solana-bridge.mdx +++ b/docs/base-chain/quickstart/base-solana-bridge.mdx @@ -14,6 +14,7 @@ The Base-Solana bridge enables bidirectional token transfers and message passing * **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. From f1eecce9f17f4f612d1986e42fc97453e58057a3 Mon Sep 17 00:00:00 2001 From: youssefea Date: Wed, 8 Oct 2025 15:28:28 +0100 Subject: [PATCH 20/29] fix how it works section and remove wsol --- .../base-chain/quickstart/base-solana-bridge.mdx | 16 ++++++++++------ 1 file changed, 10 insertions(+), 6 deletions(-) diff --git a/docs/base-chain/quickstart/base-solana-bridge.mdx b/docs/base-chain/quickstart/base-solana-bridge.mdx index 52f5c7f5..a9e9371f 100644 --- a/docs/base-chain/quickstart/base-solana-bridge.mdx +++ b/docs/base-chain/quickstart/base-solana-bridge.mdx @@ -22,7 +22,11 @@ This guide covers the bridge architecture and provides practical examples for im ## How it works ### On Base -The Base bridge contract locks or burns your tokens and emits a message. Validators collect these messages into Merkle trees and post roots to Solana every ~15 minutes. You then prove your message exists in the tree to complete the transfer on Solana. +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. **Key Smart contracts:** - [**Bridge Contract**](https://github.com/base/bridge/blob/main/base/src/Bridge.sol): Handles outgoing transfers @@ -37,7 +41,7 @@ It represents the `msg.sender` on Base when you send an arbitrary contract call ### On Solana -The Solana bridge program locks or burns your tokens and emits events. 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. +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**](https://github.com/base/bridge/blob/main/solana/programs/bridge): Handles outgoing transfers @@ -84,7 +88,7 @@ const ixs = [ bridge: bridgeAccountAddress, outgoingMessage, to: toBytes(TO), - remoteToken: toBytes("0xC5b9112382f3c87AFE8e1A28fa52452aF81085AD"), // wSOL + remoteToken: toBytes("0xC5b9112382f3c87AFE8e1A28fa52452aF81085AD"), // SOL on Base amount: BigInt(AMOUNT * 10**9), }), await buildPayForRelayIx(RELAYER_PROGRAM_ID, outgoingMessage, payer) @@ -115,16 +119,16 @@ await client.writeContract({ ## Base to Solana -**Flow:** Burn wSOL → Wait 15min → Generate Proof → Execute on 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 (~15 minutes), then generate a cryptographic proof to execute on Solana and receive native SOL. ```typescript bridgeSolFromBaseToSolana/index.ts expandable -// Step 1: Burn wSOL on Base +// Step 1: Burn SOL on Base const transfer = { - localToken: "0xC5b9112382f3c87AFE8e1A28fa52452aF81085AD", // wSOL + localToken: "0xC5b9112382f3c87AFE8e1A28fa52452aF81085AD", // SOL (on Base) remoteToken: pubkeyToBytes32(SOL_ADDRESS), to: pubkeyToBytes32(solanaAddress), remoteAmount: BigInt(AMOUNT * 10**9), From 522efae0dbcc2b6b606ac1434a974a29551fa958 Mon Sep 17 00:00:00 2001 From: youssefea Date: Wed, 8 Oct 2025 15:30:28 +0100 Subject: [PATCH 21/29] add clarification to sol to base flow --- docs/base-chain/quickstart/base-solana-bridge.mdx | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/docs/base-chain/quickstart/base-solana-bridge.mdx b/docs/base-chain/quickstart/base-solana-bridge.mdx index a9e9371f..280b8af5 100644 --- a/docs/base-chain/quickstart/base-solana-bridge.mdx +++ b/docs/base-chain/quickstart/base-solana-bridge.mdx @@ -68,9 +68,15 @@ You can access the full repository from the link below: ## Solana to Base -**Flow:** Lock SOL → Auto-Relay → Mint SOL on Base +**Flow:** Lock SOL → Wait for Validator Pre-approval → Execute on Base -The Solana to Base flow in this example uses automatic relay for seamless transfers. Your SOL is locked in a Solana vault, and the relayer automatically executes the message on Base to mint wrapped SOL. +The Solana to Base bridge uses a pull-based model that requires 3 steps: + +1. **Initiate the bridge on Solana** - Lock your SOL in a Solana vault +2. **Wait for validators to pre-approve the message** - Validators verify and approve your bridge message +3. **Execute the message on Base** - The approved message is executed on Base to mint SOL and execute any additional arbitrary calls + +For convenience, we operate a relayer service 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. From 38e0d3ddd23a5dd49a949e90f20e5355d79c347b Mon Sep 17 00:00:00 2001 From: youssefea Date: Wed, 8 Oct 2025 15:47:25 +0100 Subject: [PATCH 22/29] update links of examples --- docs/base-chain/quickstart/base-solana-bridge.mdx | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/docs/base-chain/quickstart/base-solana-bridge.mdx b/docs/base-chain/quickstart/base-solana-bridge.mdx index 280b8af5..944c474b 100644 --- a/docs/base-chain/quickstart/base-solana-bridge.mdx +++ b/docs/base-chain/quickstart/base-solana-bridge.mdx @@ -78,7 +78,10 @@ The Solana to Base bridge uses a pull-based model that requires 3 steps: For convenience, we operate a relayer service 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. - + + +### Auto-Relay Example +We have a sample script that shows how to bridge SOL with auto-relay ```typescript solToBaseWithAutoRelay/index.ts expandable // Configure @@ -109,7 +112,7 @@ 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. - + ```typescript wrapSolTokenOnBase/index.ts expandable // Deploy wrapped token on Base From 95e6970af16b84f2f3784c514c360773e64401f4 Mon Sep 17 00:00:00 2001 From: youssefea Date: Wed, 8 Oct 2025 15:48:45 +0100 Subject: [PATCH 23/29] add callout --- docs/base-chain/quickstart/base-solana-bridge.mdx | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/docs/base-chain/quickstart/base-solana-bridge.mdx b/docs/base-chain/quickstart/base-solana-bridge.mdx index 944c474b..aa6052f4 100644 --- a/docs/base-chain/quickstart/base-solana-bridge.mdx +++ b/docs/base-chain/quickstart/base-solana-bridge.mdx @@ -45,11 +45,16 @@ The Solana bridge program handles token transfers by locking or burning tokens a **Key Programs:** - [**Bridge Program**](https://github.com/base/bridge/blob/main/solana/programs/bridge): Handles outgoing transfers -- [**Base Relayer Program**](https://github.com/base/bridge/blob/main/solana/programs/base_relayer): Coordinates message relay +- [**Base Relayer Program**](https://github.com/base/bridge/blob/main/solana/programs/base_relayer): Coordinates message relay (not part of the core bridge) You can access the full repository from the link below: + +The relayer program is not part of the core bridge. +This is a convenience feature we are operating on top of the bridge to reduce friction in the Solana -> Base direction. + + ## Bridging Flows From 8e0f074fa30e1c25e00f0c4cd2a2eb869d59e8a1 Mon Sep 17 00:00:00 2001 From: youssefea Date: Wed, 8 Oct 2025 16:21:30 +0100 Subject: [PATCH 24/29] remove "we" --- docs/base-chain/quickstart/base-solana-bridge.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/base-chain/quickstart/base-solana-bridge.mdx b/docs/base-chain/quickstart/base-solana-bridge.mdx index aa6052f4..3322ba94 100644 --- a/docs/base-chain/quickstart/base-solana-bridge.mdx +++ b/docs/base-chain/quickstart/base-solana-bridge.mdx @@ -52,7 +52,7 @@ You can access the full repository from the link below: The relayer program is not part of the core bridge. -This is a convenience feature we are operating on top of the bridge to reduce friction in the Solana -> Base direction. +This is a convenience feature built on top of the bridge to reduce friction in the Solana -> Base direction. ## Bridging Flows From c72b142a2ab0c68545884154cb1ea2e7d36dcf89 Mon Sep 17 00:00:00 2001 From: youssefea Date: Wed, 8 Oct 2025 16:22:09 +0100 Subject: [PATCH 25/29] remove we --- docs/base-chain/quickstart/base-solana-bridge.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/base-chain/quickstart/base-solana-bridge.mdx b/docs/base-chain/quickstart/base-solana-bridge.mdx index 3322ba94..e5c3484e 100644 --- a/docs/base-chain/quickstart/base-solana-bridge.mdx +++ b/docs/base-chain/quickstart/base-solana-bridge.mdx @@ -81,7 +81,7 @@ The Solana to Base bridge uses a pull-based model that requires 3 steps: 2. **Wait for validators to pre-approve the message** - Validators verify and approve your bridge message 3. **Execute the message on Base** - The approved message is executed on Base to mint SOL and execute any additional arbitrary calls -For convenience, we operate a relayer service 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. +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. From 8338ac4eac546d2d3537704782a4e837bb7ac4b1 Mon Sep 17 00:00:00 2001 From: youssefea Date: Wed, 8 Oct 2025 16:22:53 +0100 Subject: [PATCH 26/29] sample script --- docs/base-chain/quickstart/base-solana-bridge.mdx | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/base-chain/quickstart/base-solana-bridge.mdx b/docs/base-chain/quickstart/base-solana-bridge.mdx index e5c3484e..9fd14566 100644 --- a/docs/base-chain/quickstart/base-solana-bridge.mdx +++ b/docs/base-chain/quickstart/base-solana-bridge.mdx @@ -86,7 +86,7 @@ For convenience, a relayer service is available that automatically handles step ### Auto-Relay Example -We have a sample script that shows how to bridge SOL with auto-relay +This is a sample script that shows how to bridge SOL with auto-relay ```typescript solToBaseWithAutoRelay/index.ts expandable // Configure @@ -111,6 +111,8 @@ const ixs = [ await buildAndSendTransaction(SOLANA_RPC_URL, ixs, payer); ``` +For more details, see the [Solana to Base Relay Script](https://github.com/base/bridge/blob/main/scripts/src/commands/sol/onchain/bridge/solana-to-base/bridge-sol.handler.ts). + ### Wrap Custom SPL Tokens The example above shows how to bridge native SOL to Base. From 7df06acd9e0ee8aa4bc1ab23d5a2428d85d369b6 Mon Sep 17 00:00:00 2001 From: youssefea Date: Wed, 8 Oct 2025 16:23:49 +0100 Subject: [PATCH 27/29] fix links --- docs/base-chain/quickstart/base-solana-bridge.mdx | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/base-chain/quickstart/base-solana-bridge.mdx b/docs/base-chain/quickstart/base-solana-bridge.mdx index 9fd14566..0904a18b 100644 --- a/docs/base-chain/quickstart/base-solana-bridge.mdx +++ b/docs/base-chain/quickstart/base-solana-bridge.mdx @@ -139,7 +139,7 @@ await client.writeContract({ The Base to Solana flow requires manual proof generation. You burn wrapped SOL on Base, wait for finalization (~15 minutes), then generate a cryptographic proof to execute on Solana and receive native SOL. - + ```typescript bridgeSolFromBaseToSolana/index.ts expandable // Step 1: Burn SOL on Base @@ -182,7 +182,7 @@ The repository includes utilities for converting between Solana and Base address getting your Solana CLI keypair for signing transactions, and building and sending Solana transactions. - + ### Address Conversion @@ -519,7 +519,7 @@ To get access to the faucet API, you can follow the instructions [here](https:// ## Resources - + View source code and examples From ba0a562d3c11c05df5c42a6031165b63c8260622 Mon Sep 17 00:00:00 2001 From: youssefea Date: Wed, 8 Oct 2025 18:08:28 +0100 Subject: [PATCH 28/29] add callout to explain lock and burn mechanism --- docs/base-chain/quickstart/base-solana-bridge.mdx | 12 +++++++++++- 1 file changed, 11 insertions(+), 1 deletion(-) diff --git a/docs/base-chain/quickstart/base-solana-bridge.mdx b/docs/base-chain/quickstart/base-solana-bridge.mdx index 0904a18b..7650b277 100644 --- a/docs/base-chain/quickstart/base-solana-bridge.mdx +++ b/docs/base-chain/quickstart/base-solana-bridge.mdx @@ -28,6 +28,11 @@ 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**](https://github.com/base/bridge/blob/main/base/src/Bridge.sol): Handles outgoing transfers - [**CrossChainERC20**](https://github.com/base/bridge/blob/main/base/src/CrossChainERC20.sol): Mintable/burnable tokens for cross-chain transfers @@ -77,10 +82,15 @@ This is a convenience feature built on top of the bridge to reduce friction in t The Solana to Base bridge uses a pull-based model that requires 3 steps: -1. **Initiate the bridge on Solana** - Lock your SOL in a Solana vault +1. **Initiate the bridge on Solana** - Lock your SOL or native SPL token in a Solana vault 2. **Wait for validators to pre-approve the message** - Validators verify and approve your bridge message 3. **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. From 2d628b4202df20111f31290f0ec525bdd5647d25 Mon Sep 17 00:00:00 2001 From: youssefea Date: Thu, 9 Oct 2025 18:44:15 +0100 Subject: [PATCH 29/29] update audit notice --- docs/base-chain/quickstart/base-solana-bridge.mdx | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/base-chain/quickstart/base-solana-bridge.mdx b/docs/base-chain/quickstart/base-solana-bridge.mdx index 7650b277..e54e75b7 100644 --- a/docs/base-chain/quickstart/base-solana-bridge.mdx +++ b/docs/base-chain/quickstart/base-solana-bridge.mdx @@ -7,7 +7,7 @@ icon: "bridge" import { GithubRepoCard } from "/snippets/GithubRepoCard.mdx" - The Base-Solana bridge is currently in **testnet only** (Base Sepolia ↔ Solana Devnet). The code is a work in progress and has not been audited. **Do not use in production!** + 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: @@ -519,7 +519,6 @@ To get access to the faucet API, you can follow the instructions [here](https:// **Important Security Notes:** - * Bridge is in active development and unaudited * Only use testnet funds (Solana devnet SOL and Base Sepolia ETH) * Validate all addresses before bridging * Monitor transactions on both chains