Raven House Omni SDK

All-in-one SDK for Raven House - A cross-chain privacy-preserving token bridge between Ethereum (L1) and Aztec (L2).

Features

• 🔒 Privacy-Preserving: Built on Aztec's privacy-focused L2 infrastructure
• 🌉 Cross-Chain Bridge: Seamless token transfers between L1 and L2
• ✅ ZKPassport Integration: Identity verification for compliant bridging
• 🛠️ TypeScript First: Full TypeScript support with type definitions
• 📦 Dual Module Support: Both ESM and CommonJS compatible

Installation

# Using bun
bun add @ravenhouse/omni-sdk

# Using npm
npm install @ravenhouse/omni-sdk

# Using yarn
yarn add @ravenhouse/omni-sdk

Browser Setup

The SDK depends on Aztec.js which uses Node.js-specific modules (fs, os, net, pino, etc.). For browser environments, you need to configure polyfills.

Vite (Recommended)

The SDK provides a Vite plugin that handles all the necessary configuration:

# Install required dependencies
npm install --save-dev \
  vite-plugin-node-polyfills \
  vite-plugin-wasm \
  vite-plugin-top-level-await

// vite.config.ts
import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
import wasm from 'vite-plugin-wasm';
import topLevelAwait from 'vite-plugin-top-level-await';
import { nodePolyfills } from 'vite-plugin-node-polyfills';
import { omniSdk } from '@ravenhouse/omni-sdk/vite';

export default defineConfig({
  plugins: [
    react(),
    wasm(),
    topLevelAwait(),
    nodePolyfills({
      include: ['buffer', 'crypto', 'util', 'process', 'stream', 'path', 'events'],
      globals: {
        Buffer: true,
        global: true,
        process: true,
      },
      // These are handled by omniSdk plugin
      exclude: ['fs', 'net', 'tty', 'os'],
    }),
    omniSdk({
      // Fix static field initialization issues (AztecAddress.ZERO, Fr.ZERO, etc.)
      fixStaticFields: true,
      // Shim fs, net, tty, os modules
      shimNodeBuiltins: true,
      // Use browser-compatible pino logger
      pinoBrowser: true,
    }),
  ],
  optimizeDeps: {
    exclude: [
      '@aztec/noir-acvm_js',
      '@aztec/noir-noirc_abi',
      '@aztec/bb.js',
    ],
  },
});

Why this configuration?

1. vite-plugin-wasm - Aztec uses WebAssembly for proof generation
2. vite-plugin-top-level-await - Required for async WASM initialization
3. vite-plugin-node-polyfills - Polyfills Node.js modules (buffer, crypto, etc.)
4. omniSdk() plugin - Handles Aztec-specific issues:
   • Shims fs, os, net, tty modules (Aztec imports these but doesn't use them in browser)
   • Aliases pino to its browser version
   • Fixes static field initialization issues (Rollup transforms static ZERO = new X() incorrectly)

Next.js

// next.config.js
/** @type {import('next').NextConfig} */
const nextConfig = {
  webpack: (config, { isServer }) => {
    if (!isServer) {
      config.resolve.fallback = {
        ...config.resolve.fallback,
        fs: false,
        'fs/promises': false,
        net: false,
        tls: false,
        tty: false,
        os: require.resolve('os-browserify/browser'),
        crypto: require.resolve('crypto-browserify'),
        stream: require.resolve('stream-browserify'),
        buffer: require.resolve('buffer/'),
        process: require.resolve('process/browser'),
        util: require.resolve('util/'),
        path: require.resolve('path-browserify'),
      };
      
      config.plugins.push(
        new webpack.ProvidePlugin({
          Buffer: ['buffer', 'Buffer'],
          process: 'process/browser',
        })
      );

      // Alias pino to browser version
      config.resolve.alias = {
        ...config.resolve.alias,
        'pino': 'pino/browser.js',
      };
    }
    
    return config;
  },
};

module.exports = nextConfig;

Webpack

// webpack.config.js
module.exports = {
  resolve: {
    fallback: {
      fs: false,
      'fs/promises': false,
      net: false,
      tls: false,
      tty: false,
      os: require.resolve('os-browserify/browser'),
      crypto: require.resolve('crypto-browserify'),
      stream: require.resolve('stream-browserify'),
      buffer: require.resolve('buffer/'),
      process: require.resolve('process/browser'),
      util: require.resolve('util/'),
      path: require.resolve('path-browserify'),
    },
    alias: {
      'pino': 'pino/browser.js',
    },
  },
  plugins: [
    new webpack.ProvidePlugin({
      Buffer: ['buffer', 'Buffer'],
      process: 'process/browser',
    }),
  ],
};

Required Polyfill Packages

npm install --save-dev \
  buffer \
  process \
  crypto-browserify \
  stream-browserify \
  util \
  path-browserify \
  os-browserify \
  vite-plugin-node-polyfills \
  vite-plugin-wasm \
  vite-plugin-top-level-await

Usage

Basic Setup

import { BridgeSDK, createAztecNodeClient } from '@ravenhouse/omni-sdk'

// Initialize the SDK
const sdk = new BridgeSDK({
  aztecNodeUrl: 'http://localhost:8080',
  l1RpcUrl: 'http://localhost:8545',
  // ... other config
})

// Bridge tokens from L1 to L2
const tx = await sdk.bridgeL1ToL2({
  token: 'DAI',
  amount: 1000000000000000000n, // 1 DAI
  recipient: aztecWalletAddress,
})

L1 to L2 Bridge Flow

import { L1ToL2Orchestrator } from '@ravenhouse/omni-sdk'

const orchestrator = new L1ToL2Orchestrator(config)

// Step-by-step bridging
await orchestrator.depositToL1Portal(amount)
await orchestrator.waitForL1Confirmation()
await orchestrator.claimOnL2(recipient)

Identity Verification (ZKPassport)

import { IdentityVerifier } from '@ravenhouse/omni-sdk'

const verifier = new IdentityVerifier({
  apiKey: 'your-api-key',
})

const isVerified = await verifier.verify(proof)

AztecWallet (Wallet Connection)

The SDK includes a complete wallet connection system for Aztec, similar to wagmi for Ethereum.

Quick Start

import {
  AztecWalletProvider,
  createAztecWalletConfig,
  ConnectButton,
} from '@ravenhouse/omni-sdk/aztec-wallet';

const config = createAztecWalletConfig({
  networks: [{ name: 'devnet', nodeUrl: 'https://devnet.aztec.network' }],
  showNetworkPicker: 'full',
  walletGroups: {
    embedded: true,
    evmWallets: ['metamask', 'rabby'],
    aztecWallets: ['azguard'],
  },
});

function App() {
  return (
    <AztecWalletProvider config={config}>
      <ConnectButton />
    </AztecWalletProvider>
  );
}

Theming

The SDK uses CSS custom properties for theming, with sensible defaults that work in both light and dark modes.

Default Theme (Automatic)

By default, AztecWalletProvider automatically injects a default theme:

// Default theme is automatically applied
<AztecWalletProvider config={config}>
  <YourApp />
</AztecWalletProvider>

Customizing the Theme

Override CSS variables in your own stylesheet:

:root {
  /* Accent/Primary color */
  --aw-accent: #your-brand-color;
  --aw-accent-hover: #your-brand-hover;
  
  /* Background colors */
  --aw-surface-secondary: #f5f5f5;
  
  /* Text colors */
  --aw-text-default: #1a1a1a;
  --aw-text-muted: #666666;
}

/* Dark mode */
.dark {
  --aw-surface-secondary: #2a2a2a;
  --aw-text-default: #fafafa;
}

Disabling Default Theme

If you want complete control over styling:

<AztecWalletProvider config={config} enableDefaultTheme={false}>
  <YourApp />
</AztecWalletProvider>

Custom Theme CSS

Inject custom CSS alongside the default theme:

<AztecWalletProvider 
  config={config} 
  customThemeCss={`
    :root {
      --aw-accent: #custom-color;
    }
  `}
>
  <YourApp />
</AztecWalletProvider>

Available CSS Variables

| Variable | Default Light | Default Dark | Description | |----------|--------------|--------------|-------------| | --aw-accent | #3b82f6 | #3b82f6 | Primary accent color | | --aw-accent-hover | #2563eb | #2563eb | Accent hover state | | --aw-background | #ffffff | #0f0f0f | Page background | | --aw-surface-primary | #ffffff | #1a1a1a | Cards, modals | | --aw-surface-secondary | #f3f4f6 | #262626 | Buttons, inputs | | --aw-surface-tertiary | #e5e7eb | #333333 | Hover states | | --aw-text-default | #111827 | #fafafa | Primary text | | --aw-text-muted | #6b7280 | #a3a3a3 | Secondary text | | --aw-border-default | #e5e7eb | #333333 | Borders | | --aw-success | #22c55e | #22c55e | Success states | | --aw-warning | #f59e0b | #f59e0b | Warning states | | --aw-error | #ef4444 | #ef4444 | Error states |

Local Development

Using the SDK Locally in Other Projects

When you want to test the SDK in another project without publishing to npm, you have a few options:

Option 1: Bun Link (Recommended for bun users)

In the SDK directory:

cd /path/to/omni-sdk
bun link

In your target project:

cd /path/to/your-project
bun link @ravenhouse/omni-sdk

Option 2: Local Path in package.json

In your target project's package.json:

{
  "dependencies": {
    "@ravenhouse/omni-sdk": "file:/path/to/omni-sdk"
  }
}

Then run:

bun install

Option 3: Bun Workspace (for monorepos)

If you're using a monorepo structure, add to your root package.json:

{
  "workspaces": ["packages/*", "../omni-sdk"]
}

Note: After making changes to the SDK locally, remember to rebuild it:

bun run build

Publishing to NPM

Prerequisites

1. Ensure you have an NPM account
2. Be added as a collaborator to the @ravenhouse organization on NPM
3. Have 2FA enabled on your NPM account

Publishing Steps

1. Update version (follow semver):

   # Update version in package.json manually or use:
   npm version patch  # or minor, major

2. Build and verify:

   bun run build
   bun run typecheck

3. Commit your changes first

4. Create a new tag with naming convention omni-sdk-v<VERSION>

git tag omni-sdk-v0.1.5

5. Push your tag on remote

git push origin omni-sdk-v0.1.5

Available Scripts

# Development
bun run dev           # Watch mode build
bun run build         # Production build

# Code Quality
bun run typecheck     # TypeScript type checking
bun run lint          # ESLint
bun run format        # Prettier formatting

# Testing
bun run test          # Run tests
bun run test:coverage # Run tests with coverage

# L2 Contracts (Aztec)
bun run build:l2-contracts   # Compile and generate L2 contract artifacts
bun run compile:l2          # Compile Aztec contracts
bun run codegen:l2          # Generate TypeScript from compiled contracts
bun run clean:contracts     # Clean contract build artifacts

Project Structure

src/
├── adapters/        # Wallet adapters
├── artifacts/       # Generated contract artifacts
├── auth/           # Authentication clients
├── clients/        # L1/L2 client implementations
├── config/         # Network and token configurations
├── contracts/      # L1 contract ABIs and artifacts
├── core/           # Bridge SDK core logic
├── deploy/         # Deployment utilities
├── types/          # TypeScript type definitions
├── utils/          # Utility functions
└── verification/   # Identity verification

Dependencies

• @aztec/aztec.js - Aztec L2 interaction
• viem - Ethereum L1 interaction

License

MIT © Raven House