VoidAI Bridge SDK

TypeScript SDK for VoidAI Bridge - Cross-chain asset bridging and routing across Bittensor, Ethereum, Solana, and other supported chains.

🎯 What is VoidAI Bridge SDK?

The VoidAI Bridge SDK provides a unified interface to:

• Bridge assets between chains (TAO ↔ wTAO, Alpha ↔ wAlpha, cross-chain transfers)
• Route transactions via SWAP, BRIDGE, or CCIP operations
• Estimate fees before executing transactions
• Connect wallets (Bittensor, Ethereum/MetaMask, Solana/Phantom)
• Build EVM transactions automatically for bridge burn operations

Perfect for building DeFi applications, cross-chain DEXs, or any app that needs to move assets between Bittensor, EVM chains, and Solana.

📦 Installation

npm install voidai-sdk
# or
yarn add voidai-sdk
# or
pnpm add voidai-sdk

Requirements

• Node.js: ≥ 18 (for backend usage)
• Browser: Modern browsers with ES6+ support
• API Key: Get your VoidAI Bridge API key from the VoidAI Console

🚀 Quick Start

1. Initialize the SDK

import { BridgeSDK } from 'voidai-sdk';

const sdk = new BridgeSDK({
  apiKey: process.env.VOIDAI_API_KEY!,
  environment: 'testnet', // 'devnet' | 'testnet' | 'mainnet'
});

// Wait for authentication & API key validation
await sdk.ready;

Backend? Use BridgeSDKServer instead – it requires apiKey + secretKey and has no wallet integrations. See Backend Usage below.

2. Fetch Supported Chains & Assets

// Get all active chains
const chains = await sdk.api.getSupportedChains({
  isActive: true,
  isCcipSupported: true,
});

// Get assets (optionally filtered by chain)
const assets = await sdk.api.getAssetList('ETHEREUM_SEPOLIA');

3. Connect Wallets (Browser Only)

// Connect MetaMask
const ethAccount = await sdk.wallets.ethereum.connect();
console.log('Connected:', ethAccount.address);

// Connect Bittensor wallet (Talisman/Subwallet/Polkadot.js)
const bittensorAccount = await sdk.wallets.bittensor.connect();
console.log('Connected:', bittensorAccount.address);

// Connect Phantom (Solana)
const solanaAccount = await sdk.wallets.solana.connect();
console.log('Connected:', solanaAccount.address);

4. Execute a Bridge Operation

// Bridge TAO from Bittensor to Ethereum
const result = await sdk.bridge.bridge({
  fromWallet: '5DqAEsZi...', // Bittensor address
  toWallet: '0x742d35...',    // Ethereum address
  fromToken: 'tao',
  toToken: 'wtao',
  fromChain: 'BITTENSOR',
  toChain: 'ETHEREUM_SEPOLIA',
  amount: 1.0,
});

console.log('Bridge identifier:', result.identifier);

// For EVM burn flows (wTAO → TAO), use the pre-built transaction
if (result.evmTransaction) {
  const txHash = await window.ethereum.request({
    method: 'eth_sendTransaction',
    params: [{
      from: ethAccount.address,
      to: result.evmTransaction.to,
      data: result.evmTransaction.data,
      value: result.evmTransaction.value,
    }],
  });
  console.log('Transaction sent:', txHash);
}

5. Route a Swap Transaction

const route = await sdk.bridge.routeSwap({
  operationType: 'SWAP',
  originAssetId: 1,
  destinationAssetId: 2,
  fromAddress: '0xSource...',
  toAddress: '0xDestination...',
  amount: 0.5,
});

if (route.success && route.data) {
  // Execute via MetaMask
  await window.ethereum.request({
    method: 'eth_sendTransaction',
    params: [{
      from: '0xSource...',
      to: route.data.to,
      data: route.data.data,
      value: route.data.value,
    }],
  });
}

6. Estimate Fees

// Bridge fee estimate
const bridgeFee = await sdk.bridge.getBridgeFeeEstimate({
  fromToken: 'tao',
  toToken: 'wtao',
  amount: 2.5,
});

console.log('Bridge fee:', bridgeFee.data.fee);
console.log('Recipient will receive:', bridgeFee.data.recipientAmount);

// Router swap fee estimate
const swapFee = await sdk.bridge.getRouterSwapFeeEstimate({
  originAssetId: 1,
  destinationAssetId: 2,
  amount: 0.75,
  operationType: 'SWAP',
  toAddress: '0xDestination...',
});

console.log('Total fee:', swapFee.totalFee);

📚 Documentation

📖 Full Documentation - Complete API reference, guides, and examples

• Getting Started Guide
• SDK Initialization
• API Reference
• Frontend Integration Examples
• Error Handling
• Best Practices

💡 Key Features

✅ Multi-Chain Support

• Bittensor (TAO, Alpha)
• Ethereum (Mainnet, Sepolia)
• Base (Mainnet, Sepolia)
• Solana
• More chains added regularly

✅ Wallet Integration

• Bittensor: Talisman, Subwallet, Polkadot.js
• Ethereum: MetaMask
• Solana: Phantom

✅ Bridge Operations

• TAO ↔ wTAO (Bittensor ↔ Ethereum)
• Alpha ↔ wAlpha
• Cross-chain asset transfers
• Automatic EVM transaction building for burn operations

✅ Routing & Swaps

• Unified route-transaction API
• SWAP, BRIDGE, and CCIP operations
• Fee estimation before execution

✅ Frontend vs Backend

• BridgeSDK – Frontend usage (apiKey only, no secretKey)
• BridgeSDKServer – Backend usage (apiKey + secretKey for JWT auth, no wallets)

✅ Production Ready

• TypeScript-first with full type definitions
• Automatic JWT refresh on token expiry
• Normalized error messages
• Environment-aware configuration
• Works in Node.js and browsers

🖥️ Backend Usage (Node.js)

For server-side or backend integrations, use BridgeSDKServer with both apiKey and secretKey:

import { BridgeSDKServer } from 'voidai-sdk';

const sdk = new BridgeSDKServer({
  apiKey: process.env.VOIDAI_API_KEY!,
  secretKey: process.env.VOIDAI_SECRET_KEY!,
  environment: 'production',
});

await sdk.ready;

// Same bridge/api API, no wallets
const chains = await sdk.api.getSupportedChains();
const result = await sdk.bridge.bridge({ /* ... */ });

BridgeSDKServer exposes config, api, bridge, and ready – no wallets (use BridgeSDK in frontend for that).

🔧 Environment Configuration

The SDK supports three environments:

| Environment | Base URL | Use Case | |---------------|-----------------------------------------------|-----------------------| | development | http://localhost:3003 | Local development | | staging | https://api-staging.voidai.envistudios.com | Testing & QA | | production | https://api.voidai.envistudios.com | Live applications |

📝 Example: Complete Bridge Flow

import { BridgeSDK } from 'voidai-sdk';

async function bridgeTAO() {
  // 1. Initialize SDK
  const sdk = new BridgeSDK({
    apiKey: process.env.VOIDAI_API_KEY!,
    environment: 'staging',
  });
  
  await sdk.ready;

  // 2. Connect wallets
  const bittensorAccount = await sdk.wallets.bittensor.connect();
  const ethAccount = await sdk.wallets.ethereum.connect();

  // 3. Estimate fees
  const fee = await sdk.bridge.getBridgeFeeEstimate({
    fromToken: 'tao',
    toToken: 'wtao',
    amount: 1.0,
  });
  
  console.log(`Fee: ${fee.data.fee}, You'll receive: ${fee.data.recipientAmount}`);

  // 4. Execute bridge
  const result = await sdk.bridge.bridge({
    fromWallet: bittensorAccount.address,
    toWallet: ethAccount.address,
    fromToken: 'tao',
    toToken: 'wtao',
    fromChain: 'BITTENSOR',
    toChain: 'ETHEREUM_SEPOLIA',
    amount: 1.0,
  });

  console.log('Bridge initiated:', result.identifier);
  
  // 5. Execute on-chain transaction (if EVM burn flow)
  if (result.evmTransaction) {
    const txHash = await window.ethereum.request({
      method: 'eth_sendTransaction',
      params: [{
        from: ethAccount.address,
        ...result.evmTransaction,
      }],
    });
    console.log('On-chain tx:', txHash);
  }
}

bridgeTAO().catch(console.error);

🛠️ Development

Build

# Build for Node.js
npm run build

# Build for browser
npm run build:browser

# Build both
npm run build:all

Test

npm test

Lint

npm run lint

📁 Project Structure

bridge-sdk/
├── src/                    # SDK source code
│   ├── api/               # HTTP client
│   ├── config.ts          # Configuration
│   ├── core/              # Bridge domain logic
│   ├── types/             # TypeScript types
│   ├── utils/             # Utilities
│   ├── wallet/            # Wallet integrations
│   └── index.ts           # Main entry point
├── dist/                  # Compiled SDK (Node.js)
├── dist-browser/          # Browser bundle
├── docs/                  # Full documentation (mdBook)
├── test/                  # Test suite
├── examples/              # Example applications
│   └── frontend/          # Frontend demo app
└── package.json

🌐 Browser Usage

ES Modules

<script type="module">
  import { BridgeSDK } from './node_modules/voidai-sdk/dist-browser/voidai-sdk.js';
  
  const sdk = new BridgeSDK({
    apiKey: 'your-api-key',
    environment: 'staging',
  });
</script>

Bundler (Webpack/Vite/Rollup)

import { BridgeSDK } from 'voidai-sdk';

// Use normally - bundler will handle it
const sdk = new BridgeSDK({ apiKey, environment: 'production' });

⚠️ Error Handling

The SDK throws Error instances with user-friendly messages:

try {
  await sdk.bridge.bridge({ /* ... */ });
} catch (error) {
  // error.message contains a clear, actionable message
  console.error('Bridge failed:', error.message);
  
  // Common errors:
  // - "Session expired or unauthorized..." → Check API key
  // - "Failed to execute bridge swap" → Check parameters
  // - "User rejected the connection request" → User cancelled wallet
}

See Error Handling Guide for detailed patterns.

🔐 Security Best Practices

• ✅ Never commit API keys - Use environment variables
• ✅ Use BridgeSDKServer for backend - Pass secretKey only in server code; use BridgeSDK (no secretKey) in frontend
• ✅ Validate user inputs before passing to SDK
• ✅ Keep dependencies updated - Monitor security advisories

See Best Practices for more guidance.

📖 Examples

Check out the example frontend app for a complete integration example including:

• SDK initialization
• Wallet connections
• Bridge operations
• Swap routing
• Fee estimation
• Error handling

🤝 Support

• Documentation: Full docs
• Issues: GitHub Issues
• FAQ: Troubleshooting Guide

📄 License

MIT

🙏 Contributing

Contributions are welcome! Please ensure all tests pass before submitting a pull request.

# Run tests
npm test

# Run linter
npm run lint

# Build before committing
npm run build:all