Reaper Protocol SDK

A TypeScript SDK for interacting with the Reaper Protocol on Solana. This SDK provides a simple, typed interface for dApps and integration partners to interact with Reaper vaults and protocol features.

Architecture

The SDK follows a modular architecture that mirrors the Solana program structure:

• Unified Interface: VaultInstructions provides a simple facade for all operations
• Specialized Handlers: Individual instruction handlers for advanced features
• Backward Compatibility: Existing code continues to work unchanged

See INSTRUCTION_ARCHITECTURE.md for detailed architectural decisions and patterns.

Installation

npm install @reaper-protocol/sdk
# or
yarn add @reaper-protocol/sdk

Quick Start

import { ReaperClient, RPC_ENDPOINTS } from '@reaper-protocol/sdk';
import { Connection, Keypair } from '@solana/web3.js';

// Create a connection and wallet
const connection = new Connection(RPC_ENDPOINTS.DEVNET);
const wallet = new Wallet(Keypair.generate()); // Use your actual wallet

// Initialize the SDK client
const client = ReaperClient.create(RPC_ENDPOINTS.DEVNET, wallet);

// Initialize a vault
const result = await client.initializeVault();
console.log('Vault created:', result.vaultAddress.toString());

// Get vault data
const vault = await client.getVaultForOwner(wallet.publicKey);
console.log('Vault owner:', vault?.owner.toString());

API Reference

ReaperClient

The main SDK client for interacting with the Reaper Protocol.

Constructor

const client = new ReaperClient(connection, wallet, config);

Static Methods

// Create a new client with RPC URL
const client = ReaperClient.create(rpcUrl, wallet, config);

Instance Methods

initializeVault(config?, options?): Promise<VaultInitResult>

Initialize a new vault for the connected wallet.

const result = await client.initializeVault();
// Returns: { signature, vaultAddress, vault }

getVault(vaultAddress): Promise<Vault | null>

Get vault account data by address.

const vault = await client.getVault(vaultPda);

getVaultForOwner(owner): Promise<Vault | null>

Get vault for a specific owner.

const vault = await client.getVaultForOwner(ownerPublicKey);

getVaultAddress(owner): [PublicKey, number]

Get vault PDA address and bump for an owner.

const [vaultAddress, bump] = client.getVaultAddress(ownerPublicKey);

vaultExists(owner): Promise<boolean>

Check if a vault exists for the given owner.

const exists = await client.vaultExists(ownerPublicKey);

getAllVaults(): Promise<Array<{address, vault}>>

Get all vaults (useful for analytics).

const allVaults = await client.getAllVaults();

Types

Vault

interface Vault {
  owner: PublicKey;
  createdAt: BN;
  bump: number;
}

VaultConfig

interface VaultConfig {
  seeds?: Buffer[];
}

ReaperSDKConfig

interface ReaperSDKConfig {
  rpcUrl?: string;
  commitment?: 'processed' | 'confirmed' | 'finalized';
  skipPreflight?: boolean;
}

TransactionOptions

interface TransactionOptions {
  commitment?: 'processed' | 'confirmed' | 'finalized';
  skipPreflight?: boolean;
  maxRetries?: number;
}

Utilities

ReaperProgram

Static utilities for the Reaper Protocol.

// Program ID
ReaperProgram.PROGRAM_ID

// Find vault address
const [vaultPda, bump] = ReaperProgram.findVaultAddress(ownerPublicKey);

// Validate address
const isValid = ReaperProgram.isValidAddress(addressString);

ReaperError

Custom error class for SDK errors.

try {
  await client.initializeVault();
} catch (error) {
  if (error instanceof ReaperError) {
    console.log('Error code:', error.code);
    console.log('Error message:', error.message);
  }
}

Examples

Basic Vault Operations

import { ReaperClient, RPC_ENDPOINTS } from '@reaper-protocol/sdk';
import { Connection, Keypair } from '@solana/web3.js';

async function main() {
  // Setup
  const connection = new Connection(RPC_ENDPOINTS.LOCALHOST);
  const wallet = new Wallet(Keypair.generate());
  const client = ReaperClient.create(RPC_ENDPOINTS.LOCALHOST, wallet);

  try {
    // Initialize vault
    const initResult = await client.initializeVault();
    console.log('✅ Vault initialized');
    console.log('Address:', initResult.vaultAddress.toString());
    console.log('Signature:', initResult.signature);

    // Check if vault exists
    const exists = await client.vaultExists(wallet.publicKey);
    console.log('Vault exists:', exists);

    // Get vault data
    const vault = await client.getVaultForOwner(wallet.publicKey);
    if (vault) {
      console.log('Vault owner:', vault.owner.toString());
      console.log('Created at:', new Date(vault.createdAt.toNumber() * 1000));
    }
  } catch (error) {
    console.error('Error:', error);
  }
}

main();

Integration with React

import { useConnection, useWallet } from '@solana/wallet-adapter-react';
import { ReaperClient } from '@reaper-protocol/sdk';
import { useEffect, useState } from 'react';

function useReaperClient() {
  const { connection } = useConnection();
  const wallet = useWallet();
  const [client, setClient] = useState<ReaperClient | null>(null);

  useEffect(() => {
    if (connection && wallet.publicKey && wallet.signTransaction) {
      const reaperClient = new ReaperClient(connection, wallet);
      setClient(reaperClient);
    }
  }, [connection, wallet]);

  return client;
}

function VaultComponent() {
  const client = useReaperClient();
  const [vault, setVault] = useState(null);

  const initializeVault = async () => {
    if (!client) return;
    
    try {
      const result = await client.initializeVault();
      console.log('Vault created:', result.vaultAddress.toString());
      setVault(result.vault);
    } catch (error) {
      console.error('Failed to initialize vault:', error);
    }
  };

  return (
    <div>
      <button onClick={initializeVault}>Initialize Vault</button>
      {vault && <div>Vault Owner: {vault.owner.toString()}</div>}
    </div>
  );
}

Error Handling

The SDK provides comprehensive error handling:

import { ReaperError } from '@reaper-protocol/sdk';

try {
  await client.initializeVault();
} catch (error) {
  if (error instanceof ReaperError) {
    switch (error.code) {
      case 'VaultAlreadyInitialized':
        console.log('Vault already exists');
        break;
      case 'InvalidVaultOwner':
        console.log('Invalid vault owner');
        break;
      default:
        console.log('Unknown error:', error.message);
    }
  }
}

Development

Building

npm run build

Testing

npm test

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Submit a pull request

License

MIT

Support

For support and questions, please visit our GitHub repository or join our Discord community.