@surfman/sdk

TypeScript SDK for SurfPool RPC API interaction - A powerful toolkit for Solana local development and testing.

📖 SurfPool Documentation - Learn more about SurfPool's local development environment

Features

• 🔧 Cheatcodes: Time travel, account manipulation, network control
• 🌐 Network APIs: Block queries, transactions, fees, cluster info
• 📦 Account APIs: Account info, token balances, batch queries
• 📊 Scan & Analytics: Program accounts, largest holders, supply metrics
• 💪 Type-safe: Full TypeScript support with comprehensive type definitions
• ⚡ Easy to use: Simple, intuitive API design

Installation

npm install @surfman/sdk

Quick Start

import { Surfman } from '@surfman/sdk';

// Initialize client
const client = new Surfman('http://localhost:8899');

// Cheatcodes - Time travel by epoch
await client.cheatcodes.timeTravel({ 
  absoluteEpoch: 100 
});

// Time travel to specific timestamp
await client.cheatcodes.timeTravel({
  absoluteTimestamp: Math.floor(Date.now() / 1000) + 86400  // +1 day
});

// Set or remove program authority
await client.cheatcodes.setProgramAuthority(
  'program-id',
  'new-authority-pubkey'  // or null to remove authority
);

// Network - Get latest blockhash
const blockhash = await client.network.getLatestBlockhash();

// Network - Send transaction
const signature = await client.network.sendTransaction(txData);

// Accounts - Get account info
const account = await client.accounts.getAccountInfo(pubkey);

// Scan - Get program accounts
const accounts = await client.scan.getProgramAccounts(programId, {
  filters: [{ dataSize: 165 }]
});

// Scan - Get largest accounts
const largest = await client.scan.getLargestAccounts();

API Modules

Cheatcodes (9 APIs)

Time travel and network manipulation for testing:

// Time control
await client.cheatcodes.timeTravel({ relativeSlots: 100 });
await client.cheatcodes.pauseClock();
await client.cheatcodes.resumeClock();

// Account manipulation
await client.cheatcodes.setAccount(pubkey, options);
await client.cheatcodes.setTokenAccount(account, options);
await client.cheatcodes.resetAccount(pubkey);

// Network management
await client.cheatcodes.resetNetwork();
await client.cheatcodes.setProgramAuthority(programId, newAuthority);
const sigs = await client.cheatcodes.getLocalSignatures();

Network (18 APIs)

Comprehensive network and transaction APIs:

// Block queries
const blockhash = await client.network.getLatestBlockhash();
const block = await client.network.getBlock(slot);
const blocks = await client.network.getBlocks(startSlot, endSlot);

// Transactions
const tx = await client.network.getTransaction(signature);
const sig = await client.network.sendTransaction(txData);
const result = await client.network.simulateTransaction(tx);

// Network info
const nodes = await client.network.getClusterNodes();
const fees = await client.network.getRecentPrioritizationFees();
const isValid = await client.network.isBlockhashValid(blockhash);

Accounts (5 APIs)

Account and token data queries:

// Account queries
const account = await client.accounts.getAccountInfo(pubkey);
const accounts = await client.accounts.getMultipleAccounts([pubkey1, pubkey2]);

// Token queries
const balance = await client.accounts.getTokenAccountBalance(tokenAccount);
const supply = await client.accounts.getTokenSupply(mint);
const commitment = await client.accounts.getBlockCommitment(slot);

Scan & Analytics (6 APIs)

Batch queries and network statistics:

// Program accounts
const accounts = await client.scan.getProgramAccounts(programId, {
  filters: [{ dataSize: 165 }],
  encoding: 'base64'
});

// Supply and distribution
const supply = await client.scan.getSupply();
const largest = await client.scan.getLargestAccounts();
const holders = await client.scan.getTokenLargestAccounts(mint);

// Token accounts
const owned = await client.scan.getTokenAccountsByOwner(owner, { mint });
const delegated = await client.scan.getTokenAccountsByDelegate(delegate, { mint });

Configuration

// String URL
const client = new Surfman('http://localhost:8899');

// Or with config object
const client = new Surfman({
  url: 'http://localhost:8899',
  timeout: 30000,
  // ... other RPC config options
});

Use Cases

Testing Smart Contracts

// Set up test environment - move forward 1 week
const oneWeekInSlots = 7 * 24 * 60 * 60 * 2;  // ~7 days
await client.cheatcodes.timeTravel({ relativeSlots: oneWeekInSlots });

// Fund test account
await client.cheatcodes.setAccount(testAccount, {
  lamports: 10_000_000_000
});

// Change program authority for testing
await client.cheatcodes.setProgramAuthority(
  programId,
  testAuthority
);

// Run your tests
// ...

// Clean up
await client.cheatcodes.resetNetwork();

Token Analytics

// Get token distribution
const supply = await client.scan.getSupply();
const largestHolders = await client.scan.getTokenLargestAccounts(mint);

// Analyze holder concentration
const top10Percentage = largestHolders
  .slice(0, 10)
  .reduce((sum, holder) => sum + holder.uiAmount, 0) / supply.circulating;

Program Account Scanning

// Find all token accounts for a specific mint
const accounts = await client.scan.getProgramAccounts(TOKEN_PROGRAM_ID, {
  filters: [
    { dataSize: 165 },
    { memcmp: { offset: 0, bytes: mintAddress } }
  ]
});

TypeScript Support

Full TypeScript definitions included:

import { 
  Surfman, 
  AccountInfo, 
  BlockInfo,
  TransactionResponse 
} from '@surfman/sdk';

CLI Companion

For command-line usage, install the companion CLI tool:

npm install -g surfman
surfman --help

Documentation

• SurfPool Documentation - Official SurfPool docs
• GitHub Repository
• CLI Tool
• Report Issues

License

MIT