@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

npm install @ravenhouse/compliant-bridge
# or
bun add @ravenhouse/compliant-bridge
# or
yarn add @ravenhouse/compliant-bridge

Quick Start

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

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.

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.

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.

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:

interface L1WalletClient {
  account: { address: string };
  extend(actions: any): L1WalletClient;
}

Example with Wagmi:

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:

interface L2WalletClient {
  request(method: string, params: any): Promise<any>;
  account: string;
  sessionId: string;
}

Example with Azguard:

const l2Wallet = {
  account: aztecAccountAddress,
  sessionId: aztecSessionId,
  request: (method, params) => azguardClient.request(method, params)
};

Error Handling

The SDK provides specific error types:

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.