npm package: @ravenhouse/compliant-bridge
Description: Headless SDK for Aztec-Ethereum compliant bridging with ZK Passport verification
Author: Raven House
Latest version: 0.1.0

# @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.