@ravenhouse/compliant-bridge 0.1.0

package/README.md

@@ -0,0 +1,262 @@
+# @ravenhouse/compliant-bridge
+
+Headless SDK for Aztec-Ethereum compliant bridging with ZK Passport verification.
+
+## Features
+
+- Framework-agnostic (works with React, Vue, vanilla JS, etc.)
+- Pre-configured networks (devnet, sandbox, testnet)
+- ZK Passport identity verification integration
+- Type-safe TypeScript API
+- L1 → L2 token bridging
+- Comprehensive token management
+
+## Installation
+
+```bash
+npm install @ravenhouse/compliant-bridge
+# or
+bun add @ravenhouse/compliant-bridge
+# or
+yarn add @ravenhouse/compliant-bridge
+```
+
+## Quick Start
+
+```typescript
+import { CompliantBridge, networks } from '@ravenhouse/compliant-bridge';
+
+// Initialize the SDK
+const bridge = new CompliantBridge({
+  network: networks.devnet,
+  l1Wallet: myEthereumWallet,  // Your L1 wallet client (Wagmi/viem)
+  l2Wallet: myAztecWallet,      // Your L2 wallet client (Aztec/Azguard)
+  backendApiUrl: 'https://api.ravenhouse.xyz'
+});
+
+// Get supported tokens
+const tokens = bridge.getSupportedTokens();
+const rht = bridge.getToken('RHT');
+
+// Execute L1 → L2 bridge
+const result = await bridge.bridgeL1ToL2({
+  token: rht,
+  amount: '100.5',
+  isPrivate: true,
+  onStep: (step) => {
+    console.log(`${step.label}: ${step.status}`);
+    if (step.explorerUrl) {
+      console.log(`View transaction: ${step.explorerUrl}`);
+    }
+  }
+});
+
+console.log('Bridge result:', result);
+```
+
+## API Reference
+
+### CompliantBridge
+
+Main SDK class for bridge operations.
+
+#### Constructor
+
+```typescript
+new CompliantBridge(config: BridgeConfig)
+```
+
+**Parameters:**
+- `network`: Network configuration (devnet, sandbox, or testnet)
+- `l1Wallet`: L1 wallet client (Ethereum/Wagmi)
+- `l2Wallet`: L2 wallet client (Aztec/Azguard)
+- `backendApiUrl`: Backend API URL for verification
+- `logger?`: Optional logger instance
+- `timeouts?`: Optional timeout configuration
+
+#### Methods
+
+##### `bridgeL1ToL2(params: L1ToL2Params): Promise<BridgeResult>`
+
+Bridge tokens from L1 (Ethereum) to L2 (Aztec).
+
+**Parameters:**
+- `token`: Token to bridge
+- `amount`: Amount to bridge (decimal string, e.g., "100.5")
+- `isPrivate`: Whether to bridge privately
+- `onStep?`: Callback for step progress updates
+
+**Returns:** `Promise<BridgeResult>`
+
+##### `getSupportedTokens(): TokenConfig[]`
+
+Get all supported tokens for the current network.
+
+##### `getToken(symbol: string): TokenConfig | undefined`
+
+Get a specific token by symbol.
+
+### BridgeResult
+
+Result of a bridge operation.
+
+```typescript
+interface BridgeResult {
+  success: boolean;
+  direction: 'l1-to-l2' | 'l2-to-l1';
+  amount: string;
+  symbol: string;
+  finalTxHash?: string;
+  explorerUrl?: string;
+  message: string;
+  steps: BridgeStep[];
+}
+```
+
+### TokenConfig
+
+Token configuration.
+
+```typescript
+interface TokenConfig {
+  symbol: string;
+  name: string;
+  decimals: number;
+  icon?: string;
+  isNative?: boolean;
+  l1: {
+    tokenAddress: string | null;
+    portalAddress: string;
+    feeAssetHandlerAddress: string;
+  };
+  l2: {
+    tokenAddress: string;
+    bridgeAddress: string;
+    dripper?: string;
+  };
+}
+```
+
+### IdentityVerifier
+
+Check and manage user verification status.
+
+```typescript
+const verifier = bridge.verifier;
+
+// Check if user is verified
+const status = await verifier.checkStatus(aztecAddress);
+console.log(status.isVerified); // boolean
+```
+
+## Supported Networks
+
+- **devnet**: Aztec devnet with Sepolia L1
+- **sandbox**: Local development environment
+- **testnet**: Aztec testnet with Sepolia L1
+
+## Supported Tokens
+
+- **RHT**: Raven House Test token
+- **ETH**: Ethereum (bridged as WETH)
+
+## Wallet Integration
+
+### L1 Wallet (Ethereum/Wagmi)
+
+Your L1 wallet client must implement:
+
+```typescript
+interface L1WalletClient {
+  account: { address: string };
+  extend(actions: any): L1WalletClient;
+}
+```
+
+**Example with Wagmi:**
+
+```typescript
+import { useWalletClient } from 'wagmi';
+
+function useCompliantBridge() {
+  const { data: walletClient } = useWalletClient();
+
+  const bridge = useMemo(() => {
+    if (!walletClient) return null;
+
+    return new CompliantBridge({
+      network: networks.devnet,
+      l1Wallet: walletClient,
+      l2Wallet: myAztecWallet,
+      backendApiUrl: 'https://api.ravenhouse.xyz'
+    });
+  }, [walletClient]);
+
+  return bridge;
+}
+```
+
+### L2 Wallet (Aztec/Azguard)
+
+Your L2 wallet client must implement:
+
+```typescript
+interface L2WalletClient {
+  request(method: string, params: any): Promise<any>;
+  account: string;
+  sessionId: string;
+}
+```
+
+**Example with Azguard:**
+
+```typescript
+const l2Wallet = {
+  account: aztecAccountAddress,
+  sessionId: aztecSessionId,
+  request: (method, params) => azguardClient.request(method, params)
+};
+```
+
+## Error Handling
+
+The SDK provides specific error types:
+
+```typescript
+import {
+  BridgeError,
+  VerificationError,
+  WalletError,
+  TokenError,
+  NetworkError,
+  TransactionError
+} from '@ravenhouse/compliant-bridge';
+
+try {
+  const result = await bridge.bridgeL1ToL2({ ... });
+} catch (error) {
+  if (error instanceof TokenError) {
+    console.error('Token error:', error.message);
+  } else if (error instanceof WalletError) {
+    console.error('Wallet error:', error.message);
+  } else if (error instanceof BridgeError) {
+    console.error('Bridge error:', error.message);
+  }
+}
+```
+
+## Examples
+
+See the `examples/` directory for complete integration examples with different frameworks.
+
+## License
+
+MIT
+
+## Contributing
+
+Contributions are welcome! Please open an issue or submit a pull request.
+
+## Support
+
+For issues and questions, please use the GitHub issue tracker.