Compact SDK

A TypeScript SDK for interacting with The Compact protocol, providing easy-to-use methods for deposit, register, and allocation operations.

Installation

npm install @epoch-protocol/epoch-compact-sdk

Quick Start

import { CompactSDK } from '@epoch-protocol/epoch-compact-sdk';
import { createWalletClient, createPublicClient, http } from 'viem';
import { mainnet } from 'viem/chains';

// Initialize clients
const walletClient = createWalletClient({
  chain: mainnet,
  transport: http(),
  // ... your wallet configuration
});

const publicClient = createPublicClient({
  chain: mainnet,
  transport: http(),
});

// Initialize SDK
const sdk = new CompactSDK({
  apiBaseUrl: 'http://localhost:3000', // Your allocator API URL
  walletClient,
  publicClient,
});

// Deposit and register a compact
const result = await sdk.depositAndRegister({
  tokenType: 'erc20',
  tokenAddress: '0xA0b86a33E6441b8C4C8C0E4A8b4C4C4C4C4C4C4C',
  amount: '100',
  allocatorAddress: '0xB1c97a33E6441b8C4C8C0E4A8b4C4C4C4C4C4C4C',
  sponsorAddress: '0xC2d88a33E6441b8C4C8C0E4A8b4C4C4C4C4C4C4C',
  expiresInSeconds: 600, // 10 minutes
});

console.log('Transaction hash:', result.hash);
console.log('Receipt:', result.receipt);

API Reference

CompactSDK

The main SDK class for interacting with The Compact protocol.

Constructor

new CompactSDK(config: CompactSDKConfig)

Parameters:

• config.apiBaseUrl - Base URL of your allocator API
• config.walletClient - Viem wallet client for signing transactions
• config.publicClient - Viem public client for reading blockchain state

Methods

depositAndRegister

Deposits tokens and registers a compact on-chain.

async depositAndRegister(params: DepositAndRegisterParams): Promise<DepositResult>

Parameters:

• params.tokenType - Either 'native' or 'erc20'
• params.tokenAddress - Token contract address (required for ERC20)
• params.amount - Amount to deposit as string
• params.allocatorAddress - Address of the allocator
• params.sponsorAddress - Address of the sponsor
• params.expiresInSeconds - Expiration time in seconds (default: 600)
• params.witnessData - Optional witness/mandate data

Returns:

• DepositResult - Transaction hash and receipt

Example:

const result = await sdk.depositAndRegister({
  tokenType: 'erc20',
  tokenAddress: '0xA0b86a33E6441b8C4C8C0E4A8b4C4C4C4C4C4C4C',
  amount: '100',
  allocatorAddress: '0xB1c97a33E6441b8C4C8C0E4A8b4C4C4C4C4C4C4C',
  sponsorAddress: '0xC2d88a33E6441b8C4C8C0E4A8b4C4C4C4C4C4C4C',
  witnessData: {
    tokenIn: '0xA0b86a33E6441b8C4C8C0E4A8b4C4C4C4C4C4C4C',
    tokenInAmount: '100',
    tokenOut: '0xD3e99a33E6441b8C4C8C0E4A8b4C4C4C4C4C4C4C',
    minTokenOut: '95',
    destinationChainId: 1,
    protocolHashIdentifier:
      '0x0000000000000000000000000000000000000000000000000000000000000000',
    recipient: '0x0000000000000000000000000000000000000000',
  },
});

depositRegisterAndCreateAllocation

Performs deposit, register, and creates an allocation in one operation.

async depositRegisterAndCreateAllocation(params: DepositRegisterAndCreateAllocationParams): Promise<AllocationResult>

Parameters:

• All parameters from depositAndRegister
• params.sessionToken - Session token for API authentication
• params.sponsorSignature - Optional sponsor signature

Returns:

• AllocationResult - Both deposit result and allocation response

Example:

const result = await sdk.depositRegisterAndCreateAllocation({
  tokenType: 'erc20',
  tokenAddress: '0xA0b86a33E6441b8C4C8C0E4A8b4C4C4C4C4C4C4C',
  amount: '100',
  allocatorAddress: '0xB1c97a33E6441b8C4C8C0E4A8b4C4C4C4C4C4C4C',
  sponsorAddress: '0xC2d88a33E6441b8C4C8C0E4A8b4C4C4C4C4C4C4C',
  sessionToken: 'your-session-token',
  witnessData: {
    tokenIn: '0xA0b86a33E6441b8C4C8C0E4A8b4C4C4C4C4C4C4C',
    tokenInAmount: '100',
    tokenOut: '0xD3e99a33E6441b8C4C8C0E4A8b4C4C4C4C4C4C4C',
    minTokenOut: '95',
    destinationChainId: 1,
  },
});

console.log('Deposit hash:', result.depositResult.hash);
console.log('Allocation hash:', result.allocationResponse.hash);

getHealthCheck

Gets health check information from the allocator API.

async getHealthCheck(): Promise<HealthCheckResponse>

Returns:

• HealthCheckResponse - API health status and configuration

Types

DepositAndRegisterParams

interface DepositAndRegisterParams {
  tokenType: 'native' | 'erc20';
  tokenAddress?: Address; // Required for ERC20
  amount: string;
  allocatorAddress: Address;
  sponsorAddress: Address;
  expiresInSeconds?: number; // Default: 600
  witnessData?: {
    tokenIn: Address;
    tokenInAmount: string;
    tokenOut: Address;
    minTokenOut: string;
    destinationChainId: number;
    protocolHashIdentifier?: Hex;
    recipient?: Address;
  };
}

DepositResult

interface DepositResult {
  hash: Hash;
  receipt: {
    status: 'success' | 'reverted';
    transactionHash: Hash;
    blockNumber: bigint;
    gasUsed: bigint;
  };
}

AllocationResult

interface AllocationResult {
  depositResult: DepositResult;
  allocationResponse: {
    hash: string;
    signature: string;
    digest: string;
  };
}

Error Handling

The SDK provides specific error types for different failure scenarios:

import {
  CompactSDKError,
  TransactionError,
  APIError,
} from '@epoch-protocol/epoch-compact-sdk';

try {
  const result = await sdk.depositAndRegister(params);
} catch (error) {
  if (error instanceof TransactionError) {
    console.error('Transaction failed:', error.message);
    console.error('Transaction hash:', error.txHash);
  } else if (error instanceof APIError) {
    console.error('API error:', error.message);
    console.error('Status:', error.status);
  } else if (error instanceof CompactSDKError) {
    console.error('SDK error:', error.message);
  }
}

Advanced Usage

Custom Witness Data

For complex allocation scenarios, you can provide custom witness data:

const result = await sdk.depositRegisterAndCreateAllocation({
  tokenType: 'erc20',
  tokenAddress: '0xA0b86a33E6441b8C4C8C0E4A8b4C4C4C4C4C4C4C',
  amount: '1000',
  allocatorAddress: '0xB1c97a33E6441b8C4C8C0E4A8b4C4C4C4C4C4C4C',
  sponsorAddress: '0xC2d88a33E6441b8C4C8C0E4A8b4C4C4C4C4C4C4C',
  sessionToken: 'session-token',
  witnessData: {
    tokenIn: '0xA0b86a33E6441b8C4C8C0E4A8b4C4C4C4C4C4C4C',
    tokenInAmount: '1000',
    tokenOut: '0xD3e99a33E6441b8C4C8C0E4A8b4C4C4C4C4C4C4C',
    minTokenOut: '950',
    destinationChainId: 10, // Optimism
    protocolHashIdentifier:
      '0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef',
    recipient: '0x0000000000000000000000000000000000000000',
  },
});

Native Token Deposits

For native ETH deposits:

const result = await sdk.depositAndRegister({
  tokenType: 'native',
  amount: '1.5', // ETH amount
  allocatorAddress: '0xB1c97a33E6441b8C4C8C0E4A8b4C4C4C4C4C4C4C',
  sponsorAddress: '0xC2d88a33E6441b8C4C8C0E4A8b4C4C4C4C4C4C4C',
});

Testing

The SDK includes comprehensive test files in the test/ folder:

• test/test.ts - Basic test suite
• test/test-runner.ts - Advanced test runner
• test/integration-example.ts - Simple integration example
• test/test-config.ts - Test configuration
• test/TESTING.md - Testing documentation

Run tests with:

pnpm test
pnpm test:runner
pnpm example

Requirements

• Node.js 18+
• TypeScript 5.0+
• Viem 2.x

License

MIT