npm package: @ravenhouse/bridge-sdk
Description: Raven House Bridge SDK - Deploy and manage token bridges between Ethereum and Aztec
Author: Raven House
Latest version: 0.1.0

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

```bash
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](https://dashboard.ravenhouse.xyz).

### 2. Initialize SDK

```typescript
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:

```typescript
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

```typescript
// 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

```typescript
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

```typescript
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:

```typescript
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

```typescript
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: support@ravenhouse.xyz