@ravenhouse/bridge-sdk

Raven House Bridge SDK for deploying and managing token bridges between Ethereum (L1) and Aztec (L2).

Features

• API Key Authentication: Secure access via Raven House platform
• Token Deployment: Deploy ERC20 tokens on L1 and Aztec tokens on L2
• Bridge Infrastructure: Deploy complete bridge infrastructure (portal, bridge, fee handlers)
• Bridge Operations: Execute L1↔L2 token transfers
• Type-Safe: Full TypeScript support

Installation

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

Quick Start

1. Get API Key

Get your API key from Raven House Dashboard.

2. Initialize SDK

import { BridgeSDK, networks } from '@ravenhouse/bridge-sdk';
import { createWalletClient, http, publicActions } from 'viem';
import { sepolia } from 'viem/chains';
import { privateKeyToAccount } from 'viem/accounts';
import { TestWallet } from '@aztec/test-wallet/server';

// Setup L1 wallet (Ethereum)
const account = privateKeyToAccount(`0x${process.env.PRIVATE_KEY}`);
const l1Wallet = createWalletClient({
  account,
  chain: sepolia,
  transport: http('https://sepolia.infura.io/v3/YOUR_KEY'),
}).extend(publicActions);

// Setup L2 wallet (Aztec)
const node = createAztecNodeClient(networks.devnet.network.nodeUrl);
const l2Wallet = await TestWallet.create(node, { proverEnabled: true });

// Initialize SDK
const sdk = new BridgeSDK({
  apiKey: 'your-api-key',
  network: networks.devnet,
  l1Wallet,
  l1PublicClient: l1Wallet,
  l2Wallet,
  chain: 'sepolia',
});

// Validate API key
const auth = await sdk.validateApiKey();
console.log(`Authenticated: ${auth.valid}, Tier: ${auth.tier}`);

3. Deploy Token Bridge Infrastructure

Deploy complete bridge infrastructure in one command:

const deployment = await sdk.deployFullBridgeInfrastructure({
  tokenName: 'My Token',
  tokenSymbol: 'MTK',
  decimals: 18,
  owner: l1Wallet.account.address,
  initialMintAmount: BigInt(1_000_000) * BigInt(10 ** 18),
  options: {
    onProgress: (step) => {
      console.log(`${step.name}: ${step.status}`);
    },
  },
});

console.log('L1 Token:', deployment.l1.token.tokenAddress.toString());
console.log('L1 Portal:', deployment.l1.portal.portalAddress.toString());
console.log('L2 Token:', deployment.l2.token.tokenAddress.toString());
console.log('L2 Bridge:', deployment.l2.bridge.bridgeAddress.toString());

4. Bridge Tokens

// Get bridge instance
const bridge = sdk.getBridge({
  request: (method, params) => azguardClient.request(method, params),
  account: aztecAccountAddress,
  sessionId: aztecSessionId,
});

// Bridge L1 -> L2
const result = await bridge.bridgeL1ToL2({
  token: sdk.getToken('MTK')!,
  amount: '100',
  isPrivate: false,
  onStep: (step) => console.log(`${step.label}: ${step.status}`),
});

API Reference

BridgeSDK

Main SDK class for deployment and bridge operations.

Constructor

new BridgeSDK(config: BridgeSDKConfig)

Config:

• apiKey: Your Raven House API key
• network: Network configuration (networks.devnet, networks.testnet, networks.sandbox)
• l1Wallet: Viem wallet client for Ethereum
• l1PublicClient: Viem public client for reading state
• l2Wallet: Aztec wallet for L2 transactions
• chain: 'sepolia' or 'mainnet'
• backendUrl: Optional custom backend URL

Methods

validateApiKey(): Promise<AuthStatus>

Validate API key with Raven House backend.

deployFullBridgeInfrastructure(params): Promise<BridgeInfrastructure>

Deploy complete bridge infrastructure:

• L1 ERC20 Token
• L1 Fee Asset Handler
• L1 Token Portal
• L2 Dripper (faucet)
• L2 Token
• L2 Bridge

deployL1Token(name, symbol, decimals, owner): Promise<L1TokenDeployment>

Deploy L1 ERC20 token only.

deployL2Token(name, symbol, decimals, owner): Promise<L2TokenDeployment>

Deploy L2 Aztec token only.

deployTokenPortal(): Promise<TokenPortalDeployment>

Deploy L1 token portal only.

deployL2Bridge(l2Token, l1Portal): Promise<L2BridgeDeployment>

Deploy L2 bridge only.

registerDeployment(deployment): Promise<void>

Register deployment with Raven House backend.

listDeployments(): Promise<DeploymentStatus[]>

List all deployments for your API key.

CompliantBridge

Bridge operations class (obtained via sdk.getBridge()).

Methods

bridgeL1ToL2(params): Promise<BridgeResult>

Bridge tokens from L1 to L2.

bridgeL2ToL1(params): Promise<BridgeResult>

Bridge tokens from L2 to L1.

getSupportedTokens(): TokenConfig[]

Get supported tokens for the network.

Example: Step-by-Step Deployment

import { BridgeSDK, networks } from '@ravenhouse/bridge-sdk';
import { EthAddress, AztecAddress } from '@aztec/aztec.js/addresses';

const sdk = new BridgeSDK({
  apiKey: process.env.RAVENHOUSE_API_KEY!,
  network: networks.devnet,
  l1Wallet,
  l1PublicClient,
  l2Wallet,
});

// Deploy L1 token
const l1Token = await sdk.deployL1Token(
  'Test Token',
  'TEST',
  18,
  l1Wallet.account.address
);

// Deploy fee asset handler
const feeHandler = await sdk.deployFeeAssetHandler(
  l1Token.tokenAddress,
  l1Wallet.account.address,
  BigInt(1_000_000) * BigInt(10 ** 18)
);

// Deploy portal
const portal = await sdk.deployTokenPortal();

// Deploy L2 dripper
const dripper = await sdk.deployDripper();

// Deploy L2 token
const ownerAztec = AztecAddress.fromString(aztecAddress);
const l2Token = await sdk.deployL2Token(
  'Test Token',
  'TEST',
  18,
  ownerAztec
);

// Deploy L2 bridge
const l2Bridge = await sdk.deployL2Bridge(
  l2Token.tokenAddress,
  portal.portalAddress
);

// Initialize portal
const registry = EthAddress.fromString(networks.devnet.contracts.escrow);
await sdk.initializePortal(
  portal.portalAddress,
  registry,
  l1Token.tokenAddress,
  l2Bridge.bridgeAddress.toString()
);

console.log('Deployment complete!');

Networks

Pre-configured networks:

import { networks } from '@ravenhouse/bridge-sdk';

// Devnet: Aztec devnet + Sepolia
networks.devnet

// Testnet: Aztec testnet + Sepolia  
networks.testnet

// Sandbox: Local development
networks.sandbox

Error Handling

import { BridgeError } from '@ravenhouse/bridge-sdk';

try {
  await sdk.deployL1Token(...);
} catch (error) {
  if (error instanceof BridgeError) {
    console.error('Error code:', error.code);
    console.error('Message:', error.message);
  }
}

License

MIT

Support

• Dashboard: https://dashboard.ravenhouse.xyz
• Documentation: https://docs.ravenhouse.xyz
• Support: [email protected]