voidai-sdk 0.1.1 → 0.2.0

package/README.md

@@ -1,53 +1,303 @@
 # VoidAI Bridge SDK
 
-TypeScript SDK for VoidAI Bridge - A bridge application that bridges TAO tokens between Bittensor and Ethereum blockchains.
+[![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';
 
-// Initialize the SDK
 const sdk = new BridgeSDK({
-    apiKey: 'your-api-key',
-    environment: 'development' // or 'production', 'staging'
+  apiKey: process.env.VOIDAI_API_KEY!,
+  environment: 'testnet', // 'devnet' | 'testnet' | 'mainnet'
 });
 
-await sdk.init();
+// 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
 
-// Connect wallets
-await sdk.wallets.bittensor.connect();
-await sdk.wallets.ethereum.connect();
-await sdk.wallets.solana.connect();
+### ✅ Frontend vs Backend
+- **BridgeSDK** – Frontend usage (apiKey only, no secretKey)
+- **BridgeSDKServer** – Backend usage (apiKey + secretKey for JWT auth, no wallets)
 
-// Use API methods
+### ✅ 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 assets = await sdk.api.getAssetList();
+const result = await sdk.bridge.bridge({ /* ... */ });
 ```
 
-## 🔑 Features
+`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     |
 
-- **Multi-Wallet Support**
-  - Bittensor (Talisman, Polkadot.js, Subwallet)
-  - Ethereum (MetaMask)
-  - Solana (Phantom)
+## 📝 Example: Complete Bridge Flow
+
+```typescript
+import { BridgeSDK } from 'voidai-sdk';
 
-- **API Methods**
-  - Get supported chains
-  - Get asset list
-  - Chain filtering (by chainId, isActive, isCcipSupported)
+async function bridgeTAO() {
+  // 1. Initialize SDK
+  const sdk = new BridgeSDK({
+    apiKey: process.env.VOIDAI_API_KEY!,
+    environment: 'staging',
+  });
+  
+  await sdk.ready;
 
-- **TypeScript Support**
-  - Full type definitions included
-  - IntelliSense support
+  // 2. Connect wallets
+  const bittensorAccount = await sdk.wallets.bittensor.connect();
+  const ethAccount = await sdk.wallets.ethereum.connect();
 
-## 🔧 Development
+  // 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
 
@@ -68,44 +318,118 @@ npm run build:all
 npm test
 ```
 
+### Lint
+
+```bash
+npm run lint
+```
+
 ## 📁 Project Structure
 
 ```
 bridge-sdk/
 ├── src/                    # SDK source code
-│   ├── api/               # API client
+│   ├── api/               # HTTP client
 │   ├── config.ts          # Configuration
-│   ├── core/              # Core bridge logic
+│   ├── 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
+│   └── frontend/          # Frontend demo app
 └── package.json
 ```
 
 ## 🌐 Browser Usage
 
-For browser usage, include the bundled SDK:
+### ES Modules
 
 ```html
-<script src="node_modules/voidai-sdk/dist-browser/voidai-sdk.js"></script>
-<script>
-    const sdk = new VoidAISDK.BridgeSDK({
-        apiKey: 'your-api-key',
-        environment: 'development'
-    });
+<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>
 ```
 
-## 📝 License
+### 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
+## 🙏 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

@@ -1,12 +1,89 @@
 import { BridgeConfig } from '../config';
-import { Chain, Asset } from '../types';
+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): Promise<T>;
-    post<T>(path: string, data?: any): Promise<T>;
+    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
@@ -23,5 +100,19 @@ export declare class VoidAIBridgeClient {
      * 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;
 }