@fiberevm/bridge

TypeScript SDK for Fiber Bridge - Cross-chain token transfers made easy

🌉 Overview

The Fiber Bridge SDK enables seamless cross-chain token transfers between Fiber and any supported EVM chain. Built with TypeScript, it provides both high-level (auto-managed) and low-level (manual control) APIs for maximum flexibility.

✨ Features

• 🔄 Dual API: High-level auto-managed operations + low-level manual control
• 🌍 Universal: Works in Node.js and browsers
• 📦 Type-Safe: Full TypeScript support with exported types
• 🔔 Event-Driven: Real-time progress tracking via EventEmitter
• 💾 Persistent: Optional transaction persistence with resume capability
• 🔁 Resilient: Automatic retries and comprehensive error recovery
• 🛠️ CLI Included: Command-line tool for quick operations
• 🔌 Extensible: Plugin architecture for custom integrations

📦 Installation

# Using pnpm (recommended)
pnpm add @fiberevm/bridge

# Using npm
npm install @fiberevm/bridge

# Using yarn
yarn add @fiberevm/bridge

Peer Dependencies

The SDK supports multiple providers. You'll need at least one:

# With wagmi (recommended for React apps)
pnpm add wagmi@^2 viem@^2

# With viem (for Node.js or non-React apps)
pnpm add viem@^2

# With ethers v6
pnpm add ethers@^6

# All options
pnpm add wagmi@^2 viem@^2 ethers@^6

🚀 Quick Start

High-Level API (Recommended)

import { FiberBridgeClient } from '@fiberevm/bridge';

// With wagmi (recommended)
import { useConfig } from 'wagmi';

function BridgeComponent() {
  const config = useConfig();
  
  const client = new FiberBridgeClient({
    provider: config, // wagmi config
    storage: 'localStorage', // Optional: 'localStorage', 'file', or 'memory'
  });
  
  // ... use client
}

// Or with ethers/viem
const client = new FiberBridgeClient({
  provider: window.ethereum, // or ethers provider or viem client
  storage: 'localStorage',
});

// Deposit tokens from origin chain to Fiber
const result = await client.deposit({
  sourceChainId: 1, // Ethereum
  destinationChainId: 100020, // Fiber
  token: '0x...', // Token address
  amount: '100', // Amount in token units
  receiverAddress: '0x...', // Receiver on Fiber
});

console.log('Deposit completed!', result);

// Listen to progress events
client.on('transaction_pending', (data) => {
  console.log('Transaction pending:', data.txHash);
});

client.on('attestation_ready', (data) => {
  console.log('Attestation ready, minting...');
});

Low-Level API (Advanced)

import { FiberBridgeLowLevel } from '@fiberevm/bridge';
import { useConfig } from 'wagmi';

const config = useConfig();

const lowLevel = new FiberBridgeLowLevel({
  provider: config, // wagmi config, or ethers/viem provider
});

// Step 1: Execute deposit (returns immediately with tx hash)
const txHash = await lowLevel.depositRaw({
  sourceChainId: 1,
  token: '0x...',
  amount: '100',
  receiverAddress: '0x...',
});

// Step 2: Monitor transaction manually
const monitor = lowLevel.createMonitor(txHash, 1);
monitor.on('confirmed', async () => {
  // Step 3: Wait for attestation
  const attestation = await lowLevel.waitForDepositAttestation(txHash, 1);
  
  // Step 4: Execute mint
  const mintTxHash = await lowLevel.mintRaw(attestation, attestation.signature);
  console.log('Mint tx:', mintTxHash);
});

🔧 CLI Tool

# Deposit tokens
fiber-bridge deposit --from ethereum --to fiber --token 0x... --amount 100

# Burn tokens
fiber-bridge burn --from fiber --to ethereum --token 0x... --amount 50

# Check status
fiber-bridge status --tx 0x...

# View history
fiber-bridge history --address 0x...

# List supported chains
fiber-bridge config --list-chains

💡 Examples

Deposit Operations

• Basic Deposit (ethers.js) - examples/deposit/basic-ethers.ts

Withdrawal Operations

• Basic Withdrawal (ethers.js) - examples/withdraw/basic-ethers.ts

Advanced Usage

• Low-Level API (viem) - examples/advanced/low-level-viem.ts
• Bidirectional Bridge - examples/advanced/bidirectional.ts

Framework Integrations

• Wagmi React Integration - examples/integrations/wagmi-react.tsx
• Error Handling Patterns - examples/integrations/error-handling.ts
• Transaction Management - examples/integrations/transaction-management.ts
• Event Tracking - examples/integrations/event-tracking.ts

Utilities

• Price Oracle - examples/utilities/price-oracle.ts

See examples/README.md for detailed documentation and usage.

Quick start:

pnpm example:help
pnpm example:list
pnpm example:deposit -- --token 0xA0b... --amount 100

📚 Documentation

User Guides

• Getting Started
• API Reference
• Error Handling
• Examples Guide
• Chain Selection Guide
• Architecture

Developer Guides

• Contributing Guide
• Publishing Guide
• Conventional Commits Guide
• Scripts Documentation

🧪 Development

# Install dependencies
pnpm install

# See all available commands with descriptions
pnpm commands

# Build
pnpm build

# Run tests
pnpm test

# Run tests in watch mode
pnpm test:watch

# Check types
pnpm typecheck

# Lint
pnpm lint

# Format
pnpm format

💡 Tip: Run pnpm commands to see all available commands with helpful descriptions organized by category!

🤝 Contributing

Contributions are welcome! Please see CONTRIBUTING.md for details.

For Contributors

When making commits, use conventional commit format for automatic changelog generation:

git commit -m "feat: add new feature"    # New features
git commit -m "fix: resolve bug"         # Bug fixes
git commit -m "docs: update guide"       # Documentation

📄 License

MIT © Fiber Team

🔗 Links

• Documentation
• GitHub
• npm

⚠️ Disclaimer

This software is provided "as is", without warranty of any kind. Use at your own risk. Always verify contract addresses and test with small amounts first.