npm package: @fiberevm/bridge
Description: TypeScript SDK for Fiber Bridge - Cross-chain token transfers made easy
Author: Fiber Team
Latest version: 0.6.1

# @fiberevm/bridge

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

[![npm version](https://img.shields.io/npm/v/@fiberevm/bridge.svg)](https://www.npmjs.com/package/@fiberevm/bridge)
[![CI](https://github.com/fiberevm/fiber-bridge-sdk/actions/workflows/ci.yml/badge.svg)](https://github.com/fiberevm/fiber-bridge-sdk/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![TypeScript](https://img.shields.io/badge/TypeScript-5.3-blue.svg)](https://www.typescriptlang.org/)
[![codecov](https://codecov.io/gh/fiberevm/fiber-bridge-sdk/branch/main/graph/badge.svg)](https://codecov.io/gh/fiberevm/fiber-bridge-sdk)

## 🌉 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

```bash
# 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:

```bash
# 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)

```typescript
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)

```typescript
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

```bash
# 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](./examples/README.md) for detailed documentation and usage.

**Quick start:**
```bash
pnpm example:help
pnpm example:list
pnpm example:deposit -- --token 0xA0b... --amount 100
```

## 📚 Documentation

### User Guides
- [Getting Started](./docs/getting-started.md)
- [API Reference](./docs/api-reference.md)
- [Error Handling](./docs/error-handling.md)
- [Examples Guide](./examples/README.md)
- [Chain Selection Guide](./examples/CHAIN_SELECTION.md)
- [Architecture](./docs/architecture.md)

### Developer Guides
- [Contributing Guide](./CONTRIBUTING.md)
- [Publishing Guide](./docs/PUBLISHING.md)
- [Conventional Commits Guide](./docs/CONVENTIONAL_COMMITS.md)
- [Scripts Documentation](./scripts/README.md)

## 🧪 Development

```bash
# 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](./CONTRIBUTING.md) for details.

### For Contributors

When making commits, use [conventional commit format](./docs/CONVENTIONAL_COMMITS.md) for automatic changelog generation:

```bash
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](https://bridge.fiberevm.com/docs)
- [GitHub](https://github.com/fiberevm/fiber-bridge-sdk)
- [npm](https://www.npmjs.com/package/@fiberevm/bridge)

## ⚠️ 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.