@voidaisdk/bridge-sdk 0.0.1

package/README.md

@@ -0,0 +1,435 @@
+# VoidAI Bridge SDK
+
+[![npm version](https://img.shields.io/npm/v/voidai-sdk.svg)](https://www.npmjs.com/package/voidai-sdk)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+**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
+
+```bash
+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](https://console.voidai.com)
+
+## 🚀 Quick Start
+
+### 1. Initialize the SDK
+
+```typescript
+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](#-backend-usage-nodejs) below.
+
+### 2. Fetch Supported Chains & Assets
+
+```typescript
+// 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)
+
+```typescript
+// 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
+
+```typescript
+// 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
+
+```typescript
+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
+
+```typescript
+// 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](docs/README.md)** - Complete API reference, guides, and examples
+
+- [Getting Started Guide](docs/getting-started.md)
+- [SDK Initialization](docs/sdk-initialization.md)
+- [API Reference](docs/api/overview.md)
+- [Frontend Integration Examples](docs/frontend-integration.md)
+- [Error Handling](docs/error-handling.md)
+- [Best Practices](docs/best-practices.md)
+
+## 💡 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`:
+
+```typescript
+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
+
+```typescript
+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
+
+```bash
+# Build for Node.js
+npm run build
+
+# Build for browser
+npm run build:browser
+
+# Build both
+npm run build:all
+```
+
+### Test
+
+```bash
+npm test
+```
+
+### Lint
+
+```bash
+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
+
+```html
+<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)
+
+```typescript
+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:
+
+```typescript
+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](docs/error-handling.md) 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](docs/best-practices.md) for more guidance.
+
+## 📖 Examples
+
+Check out the [example frontend app](examples/frontend/) for a complete integration example including:
+
+- SDK initialization
+- Wallet connections
+- Bridge operations
+- Swap routing
+- Fee estimation
+- Error handling
+
+## 🤝 Support
+
+- **Documentation**: [Full docs](docs/README.md)
+- **Issues**: [GitHub Issues](https://github.com/your-org/bridge-sdk/issues)
+- **FAQ**: [Troubleshooting Guide](docs/faq.md)
+
+## 📄 License
+
+MIT
+
+## 🙏 Contributing
+
+Contributions are welcome! Please ensure all tests pass before submitting a pull request.
+
+```bash
+# Run tests
+npm test
+
+# Run linter
+npm run lint
+
+# Build before committing
+npm run build:all
+```

package/dist/api/client.d.ts

@@ -0,0 +1,118 @@
+import { BridgeConfig } from '../config';
+import { Chain, Asset, ApiKeyValidationData, BridgeSwapRequest, BridgeSwapResponse, RouteTransactionRequest, RouteTransactionResponse, BridgeFeeEstimateRequest, BridgeFeeEstimateResponse, RouterSwapFeeEstimateRequest, RouterSwapFeeEstimateResponse, CancelCcipRequest, CancelRouterSwapRequest, CancelBridgeSwapRequest, CancelOperationResponse, ApiTransactionsResponse, ValidateBurnRequest, ValidateBurnResponse, CcipTxConfirmationRequest, CcipTxConfirmationResponse } from '../types';
+export declare class VoidAIBridgeClient {
+    private config;
+    private client;
+    private validatedApiKeyData;
+    private accessToken;
+    readonly ready: Promise<void>;
+    constructor(config: BridgeConfig);
+    /**
+     * Authenticate and set Authorization header for subsequent requests.
+     * New flow: POST /api/v1/auth/login
+     * Fallback: GET /api/v1/auth/validate-api-key (legacy)
+     */
+    private authenticate;
+    private setAccessToken;
+    /**
+     * Get access token (available after successful auth)
+     */
+    getAccessToken(): string | null;
+    private getLoginUrl;
+    /**
+     * Get EVM bridge contract address for burn operations.
+     */
+    getBridgeContractAddress(): string;
+    /**
+     * Login to obtain JWT access token.
+     * Frontend usage: { apiKey }
+     * Backend usage: { apiKey, secretKey }
+     */
+    login(): Promise<string>;
+    private tryDecodeTokenToValidationData;
+    private base64UrlDecode;
+    /**
+     * Validate API key with the backend
+     * @throws Error if API key is invalid
+     */
+    validateApiKey(): Promise<ApiKeyValidationData>;
+    /**
+     * Get validation URL - uses baseUrl from config
+     */
+    private getValidationUrl;
+    /**
+     * Get validated API key data
+     */
+    getValidatedApiKeyData(): ApiKeyValidationData | null;
+    private getUrl;
+    get<T>(path: string, params?: any, retryAttempted?: boolean): Promise<T>;
+    post<T>(path: string, data?: any, retryAttempted?: boolean): Promise<T>;
+    delete<T>(path: string, params?: any, retryAttempted?: boolean): Promise<T>;
+    patch<T>(path: string, data?: any, retryAttempted?: boolean): Promise<T>;
+    /**
+     * Bridge swap operation
+     */
+    bridgeSwap(payload: BridgeSwapRequest): Promise<BridgeSwapResponse>;
+    /**
+     * Route transaction operation (SWAP / BRIDGE / CCIP)
+     */
+    routeTransaction(payload: RouteTransactionRequest): Promise<RouteTransactionResponse>;
+    /**
+     * Cancel a CCIP route transaction
+     */
+    cancelCcip(params: CancelCcipRequest): Promise<CancelOperationResponse>;
+    /**
+     * Cancel a router swap transaction
+     */
+    cancelRouterSwap(params: CancelRouterSwapRequest): Promise<CancelOperationResponse>;
+    /**
+     * Cancel a bridge swap transaction
+     */
+    cancelBridgeSwap(params: CancelBridgeSwapRequest): Promise<CancelOperationResponse>;
+    /**
+     * Get recent API transactions (tenant-level)
+     *
+     * Maps to:
+     * POST /api/v1/bridge/api-transactions?page={page}&limit={limit}
+     */
+    getApiTransactions(page?: number, limit?: number): Promise<ApiTransactionsResponse>;
+    /**
+     * Manually validate a bridge burn transaction (EVM burn completion)
+     */
+    validateBurn(params: ValidateBurnRequest): Promise<ValidateBurnResponse>;
+    /**
+     * Manually confirm a CCIP transaction
+     */
+    confirmCcipTransaction(params: CcipTxConfirmationRequest): Promise<CcipTxConfirmationResponse>;
+    /**
+     * Get list of supported chains
+     * @param options - Optional query parameters
+     * @param options.isActive - Filter by active status
+     * @param options.isCcipSupported - Filter by CCIP support
+     * @param options.chainId - Filter by specific chain ID
+     */
+    getSupportedChains(options?: {
+        isActive?: boolean;
+        isCcipSupported?: boolean;
+        chainId?: string;
+    }): Promise<Chain[]>;
+    /**
+     * Get list of supported assets
+     */
+    getAssetList(chainId?: string): Promise<Asset[]>;
+    /**
+     * Get bridge fee estimate
+     * @param params - Fee estimation parameters
+     */
+    getBridgeFeeEstimate(params: BridgeFeeEstimateRequest): Promise<BridgeFeeEstimateResponse>;
+    /**
+     * Get router swap fee estimate
+     * @param params - Fee estimation parameters
+     */
+    getRouterSwapFeeEstimate(params: RouterSwapFeeEstimateRequest): Promise<RouterSwapFeeEstimateResponse>;
+    /**
+     * Normalize and rethrow errors with backend message (if available) so
+     * integrators can surface meaningful reasons to their users.
+     */
+    private handleError;
+}