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-intents-sdk

Quick Start

import { CompactSDK } from "@epoch-protocol/epoch-intents-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-intents-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