Bridge SDK

The Bridge SDK provides a comprehensive TypeScript interface for interacting with the Solayer Bridge Program. It enables cross-chain asset transfers between Solana and Solayer networks with built-in security features and proof verification.

Installation

npm install @solayer-labs/bridge-sdk

Bridge Flow

Cross-chain transfers follow a secure five-step process:

Source Chain: User initiates bridge transaction on source chain (Solana/Solayer)
Proof Generation: Bridge proof is created with transaction details
Guardian Verification: Guardians verify and sign the bridge proof
Target Chain: Operator executes bridge on target chain using verified proof
Asset Transfer: Assets are transferred to recipient on target chain

Key Components

BridgeHandler: Manages bridge state and configuration
BridgeProof: Contains bridge transaction details and verification data
GuardianInfo: Stores guardian public keys and threshold information
TokenInfo: Maps tokens between chains

BridgeClient

The main client class for bridge operations.

import { BridgeClient, Chain } from "@solayer-labs/bridge-sdk";
import { Connection, PublicKey } from "@solana/web3.js";

const bridgeClient = new BridgeClient({
  connection: new Connection("https://api.devnet.solana.com"),
  userPublicKey: new PublicKey("your_public_key_here"),
  chain: Chain.Solana,
  commitment: "confirmed",
});

Important Note: The BridgeClient class only provides transaction creation methods. You need to sign and send transactions yourself using sendAndConfirmTransaction or similar methods.

Query Methods

Bridge Handler Information

const bridgeHandler = await bridgeClient.getBridgeHandler(Chain.Solana);

Bridge Proof Queries

import * as anchor from "@coral-xyz/anchor";
import { getBridgeHandlerPDA } from "@solayer-labs/bridge-sdk";

// Get source chain bridge proof
const [bridgeHandler] = getBridgeHandlerPDA(Chain.Solana);
const bridgeProof = await bridgeClient.getSourceChainBridgeProof(
  bridgeHandler,
  userPublicKey,
  new anchor.BN(12345)
);

// Get destination chain bridge proof
const destProof = await bridgeClient.getDestinationChainBridgeProof(
  bridgeHandler,
  "source_transaction_signature"
);

// Get bridge proof by account address
const proofByAccount = await bridgeClient.getSourceChainBridgeProofByAccount(
  new PublicKey("bridge_proof_account_address")
);

Bridge Handler Vault PDA

const [bridgeHandler] = getBridgeHandlerPDA(Chain.Solana);
const vaultPDA = bridgeClient.getBridgeHandlerVaultPDA(
  bridgeHandler,
  new PublicKey("token_mint_address")
);

Transaction Builders

createBridgeAssetSourceChainTransaction

Creates bridge transaction without sending it. The method automatically determines the target chain mint address using the get_target_mint utility function.

const tx = await bridgeClient.createBridgeAssetSourceChainTransaction(
  params,
  accounts
);
// Customize transaction if needed
const signature = await sendAndConfirmTransaction(connection, tx, [
  userKeypair,
]);

createBridgeAssetSourceChainSolTransaction

Creates SOL bridge transaction without sending it.

const tx = await bridgeClient.createBridgeAssetSourceChainSolTransaction(
  params
);
// Customize transaction if needed
const signature = await sendAndConfirmTransaction(connection, tx, [
  userKeypair,
]);

Utility Functions

PDA Helpers

import * as anchor from "@coral-xyz/anchor";
import {
  getBridgeHandlerPDA,
  getSourceChainBridgeProofPDA,
  getDestinationChainBridgeProofPDA,
} from "@solayer-labs/bridge-sdk";

// Get bridge handler PDA
const [bridgeHandler, bump] = getBridgeHandlerPDA(Chain.Solana);

// Get source chain bridge proof PDA
const [bridgeProof, bump] = getSourceChainBridgeProofPDA(
  bridgeHandler,
  userKeypair.publicKey,
  new anchor.BN(12345)
);

// Get destination chain bridge proof PDA
const [destProof, bump] = getDestinationChainBridgeProofPDA(
  bridgeHandler,
  "source_transaction_signature"
);

Token Utilities

import {
  calculateTargetChainBridgedMintAddress,
  calculateTokenInfoAddress,
  is_mint_bridged_token,
  get_target_mint,
  Chain,
} from "@solayer-labs/bridge-sdk";
import { PublicKey } from "@solana/web3.js";

// Calculate target chain bridged mint address
const targetMint = calculateTargetChainBridgedMintAddress(
  new PublicKey("source_mint_address"),
  bridgeHandler
);

// Calculate token info PDA address
const tokenInfoAddress = calculateTokenInfoAddress(
  new PublicKey("token_mint_address"),
  bridgeHandler
);

// Check if mint is a bridged token
const isBridged = await is_mint_bridged_token(
  connection,
  bridgeHandler,
  new PublicKey("token_mint_address")
);

// Get target chain mint address
const targetMint = await get_target_mint(
  Chain.Solana,
  connection,
  bridgeHandler,
  new PublicKey("source_mint_address")
);

Bridge Status Tracking

import {
  getTargetChainBridgeTxIdFromSourceTxId,
  getSourceChainBridgeTxIdFromTargetChainBridgeProof,
  getUserBridgeTx,
  Chain,
} from "@solayer-labs/bridge-sdk";
import { PublicKey } from "@solana/web3.js";

// Check if bridge is completed on target chain
const targetTxId = await getTargetChainBridgeTxIdFromSourceTxId(
  "source_tx_signature",
  Chain.Solana,
  solayerConnection
);

// Get source transaction from target chain bridge proof
const sourceTxId = await getSourceChainBridgeTxIdFromTargetChainBridgeProof(
  new PublicKey("bridge_proof_key"),
  solayerConnection
);

// Get user's bridge transaction history
const userTxs = await getUserBridgeTx(
  connection,
  user.publicKey,
  bridgeHandler
);

Types and Interfaces

Core Configuration Types

interface BridgeClientConfig {
  connection: Connection;
  userPublicKey: PublicKey;
  chain: Chain;
  programId?: PublicKey;
  commitment?: anchor.web3.Commitment;
}

enum Chain {
  Solana = 1,
  Solayer = 2,
}

Bridge Parameter Types

interface BridgeAssetSourceChainParams {
  bridgeProofNonce: anchor.BN;
  amount: anchor.BN;
  recipient: PublicKey;
  additionalSolGas: anchor.BN;
}

interface BridgeAssetSourceChainSolParams {
  bridgeProofNonce: anchor.BN;
  amount: anchor.BN;
  recipient: PublicKey;
}

interface UserBridgeTx {
  sourceChainBridgeTx: string[];
  targetChainBridgeTx: string[];
}

Program Account Types

export type BridgeHandler = BridgeProgram["accounts"][0];
export type BridgeProof = BridgeProgram["accounts"][1];
export type BridgeProofSourceChain = BridgeProgram["accounts"][2];
export type TokenInfo = BridgeProgram["types"][0];

Usage Examples

Complete Bridge Workflow

import {
  BridgeClient,
  Chain,
  getBridgeHandlerPDA,
  getTargetChainBridgeTxIdFromSourceTxId,
} from "@solayer-labs/bridge-sdk";
import {
  Connection,
  Keypair,
  PublicKey,
  sendAndConfirmTransaction,
} from "@solana/web3.js";
import * as anchor from "@coral-xyz/anchor";

async function completeBridgeWorkflow() {
  const connection = new Connection("https://api.devnet.solana.com");
  const userKeypair = Keypair.generate();

  const bridgeClient = new BridgeClient({
    connection,
    userPublicKey: userKeypair.publicKey,
    chain: Chain.Solana,
    commitment: "confirmed",
  });

  // Bridge parameters
  const params = {
    bridgeProofNonce: new anchor.BN(Date.now()),
    amount: new anchor.BN(1000000000), // 1 token
    recipient: new PublicKey("recipient_address"),
    additionalSolGas: new anchor.BN(0),
  };

  const accounts = {
    mint: new PublicKey("token_mint"),
    signerVault: new PublicKey("your_token_account"),
  };

  try {
    // Create bridge transaction
    const transaction =
      await bridgeClient.createBridgeAssetSourceChainTransaction(
        params,
        accounts
      );

    // Sign and send transaction
    const signature = await sendAndConfirmTransaction(connection, transaction, [
      userKeypair,
    ]);
    console.log("Bridge initiated:", signature);

    // Track bridge completion
    const targetTxId = await getTargetChainBridgeTxIdFromSourceTxId(
      signature,
      Chain.Solana,
      new Connection("https://rpc.devnet.solayer.com")
    );

    if (targetTxId) {
      console.log("Bridge completed on target chain:", targetTxId);
    }
  } catch (error) {
    console.error("Bridge failed:", error);
  }
}

SOL Bridge Workflow

async function bridgeSOL() {
  const userKeypair = Keypair.generate();
  const bridgeClient = new BridgeClient({
    connection: new Connection("https://api.devnet.solana.com"),
    userPublicKey: userKeypair.publicKey,
    chain: Chain.Solana,
  });

  const params = {
    bridgeProofNonce: new anchor.BN(Date.now()),
    amount: new anchor.BN(5000000), // 0.005 SOL
    recipient: new PublicKey("recipient_address"),
  };

  try {
    const transaction =
      await bridgeClient.createBridgeAssetSourceChainSolTransaction(params);
    const signature = await sendAndConfirmTransaction(connection, transaction, [
      userKeypair,
    ]);
    console.log("SOL bridge initiated:", signature);
  } catch (error) {
    console.error("SOL bridge failed:", error);
  }
}

Working with Bridged Tokens

import {
  getBridgeHandlerPDA,
  is_mint_bridged_token,
  get_target_mint,
  calculateTokenInfoAddress,
  Chain,
} from "@solayer-labs/bridge-sdk";
import { Connection, PublicKey } from "@solana/web3.js";

async function workWithBridgedTokens() {
  const connection = new Connection("https://api.devnet.solana.com");
  const [bridgeHandler] = getBridgeHandlerPDA(Chain.Solana);
  const sourceMint = new PublicKey("token_mint_address");

  // Check if a mint is a bridged token
  const isBridged = await is_mint_bridged_token(
    connection,
    bridgeHandler,
    sourceMint
  );
  console.log("Is bridged token:", isBridged);

  // Get the target chain mint address
  const targetMint = await get_target_mint(
    Chain.Solana,
    connection,
    bridgeHandler,
    sourceMint
  );
  console.log("Target mint:", targetMint.toString());

  // Get token info PDA address
  const tokenInfoAddress = calculateTokenInfoAddress(sourceMint, bridgeHandler);
  console.log("Token info PDA:", tokenInfoAddress.toString());
}

Error Handling

Common bridge errors and their meanings:

InsufficientAmount: User doesn’t have enough tokens
BridgePaused: Bridge is currently paused by admin
TokenPaused: Specific token is paused for bridging
TooMuchAdditionalSolGas: Additional SOL gas exceeds limit
TooLittleAdditionalSolGas: Additional SOL gas below minimum
InvalidChain: Invalid chain specified
InvalidOperator: Invalid operator for the operation

try {
  const tx = await bridgeClient.createBridgeAssetSourceChainTransaction(
    params,
    accounts
  );
  const signature = await sendAndConfirmTransaction(connection, tx, [
    userKeypair,
  ]);
} catch (error) {
  if (error.message.includes("BridgePaused")) {
    console.error("Bridge is currently paused");
  } else if (error.message.includes("InsufficientAmount")) {
    console.error("Insufficient token balance");
  } else if (error.message.includes("TokenPaused")) {
    console.error("This token is paused for bridging");
  }
}

Best Practices

Pre-flight Checks

// Check bridge status before initiating
const bridgeHandler = await bridgeClient.getBridgeHandler(Chain.Solana);
if (bridgeHandler.pause) {
  throw new Error("Bridge is currently paused");
}

Transaction Management

// Use unique nonces
const bridgeProofNonce = new anchor.BN(Date.now() + Math.random());

// Create and confirm transactions
const tx = await bridgeClient.createBridgeAssetSourceChainTransaction(
  params,
  accounts
);
const signature = await sendAndConfirmTransaction(connection, tx, [
  userKeypair,
]);

Progress Monitoring

import {
  getTargetChainBridgeTxIdFromSourceTxId,
  Chain,
} from "@solayer-labs/bridge-sdk";

// Poll for bridge completion with timeout
async function waitForBridgeCompletion(sourceTxId: string, maxAttempts = 30) {
  for (let i = 0; i < maxAttempts; i++) {
    const targetTxId = await getTargetChainBridgeTxIdFromSourceTxId(
      sourceTxId,
      Chain.Solana,
      solayerConnection
    );

    if (targetTxId) return targetTxId;
    await new Promise((resolve) => setTimeout(resolve, 2000));
  }

  throw new Error("Bridge timeout");
}

Parameter Validation

import { BridgeAssetSourceChainParams } from "@solayer-labs/bridge-sdk";
import * as anchor from "@coral-xyz/anchor";

// Validate bridge parameters
function validateBridgeParams(params: BridgeAssetSourceChainParams) {
  if (params.amount.lte(new anchor.BN(0))) {
    throw new Error("Amount must be greater than 0");
  }

  if (params.additionalSolGas.gt(new anchor.BN(10000000))) {
    // 0.01 SOL
    throw new Error("Additional SOL gas too high");
  }
}

Introduction

API Reference

System Architecture

Advanced Features

Block Propagation

Consensus

Run a Node

Solayer Bridge

Installation

Bridge Flow

Key Components

BridgeClient

Query Methods

Bridge Handler Information

Bridge Proof Queries

Bridge Handler Vault PDA

Transaction Builders

createBridgeAssetSourceChainTransaction

createBridgeAssetSourceChainSolTransaction

Utility Functions

PDA Helpers

Token Utilities

Bridge Status Tracking

Types and Interfaces

Core Configuration Types

Bridge Parameter Types

Program Account Types

Usage Examples

Complete Bridge Workflow

SOL Bridge Workflow

Working with Bridged Tokens

Error Handling

Best Practices

Pre-flight Checks

Transaction Management

Progress Monitoring

Parameter Validation

Introduction

API Reference

System Architecture

Advanced Features

Block Propagation

Consensus

Run a Node

Solayer Bridge

​Installation

​Bridge Flow

​Key Components

​BridgeClient

​Query Methods

​Bridge Handler Information

​Bridge Proof Queries

​Bridge Handler Vault PDA

​Transaction Builders

​createBridgeAssetSourceChainTransaction

​createBridgeAssetSourceChainSolTransaction

​Utility Functions

​PDA Helpers

​Token Utilities

​Bridge Status Tracking

​Types and Interfaces

​Core Configuration Types

​Bridge Parameter Types

​Program Account Types

​Usage Examples

​Complete Bridge Workflow

​SOL Bridge Workflow

​Working with Bridged Tokens

​Error Handling

​Best Practices

​Pre-flight Checks

​Transaction Management

​Progress Monitoring

​Parameter Validation

Installation

Bridge Flow

Key Components

BridgeClient

Query Methods

Bridge Handler Information

Bridge Proof Queries

Bridge Handler Vault PDA

Transaction Builders

createBridgeAssetSourceChainTransaction

createBridgeAssetSourceChainSolTransaction

Utility Functions

PDA Helpers

Token Utilities

Bridge Status Tracking

Types and Interfaces

Core Configuration Types

Bridge Parameter Types

Program Account Types

Usage Examples

Complete Bridge Workflow

SOL Bridge Workflow

Working with Bridged Tokens

Error Handling

Best Practices

Pre-flight Checks

Transaction Management

Progress Monitoring

Parameter Validation