Pool Creation - Deploy and initialize Stellar distribution pools (Splitter V2)
Pool Metrics - Query APR, participants, distribution history, performance
Marketplace - Browse share listings, stats, and price history
Projects - Create and manage projects that group pools together
DobLink Widgets - Create embeddable widgets with analytics tracking
Wallet-agnostic - Works with Freighter, Albedo, xBull, Lobstr, or any Stellar wallet

Installation

npm install @dobprotocol/sdk

Quick Start

import { DobProtocolClient } from '@dobprotocol/sdk';

const dob = new DobProtocolClient({
  network: 'mainnet', // or 'testnet'
});

// Query public pools (no auth needed)
const pools = await dob.pools.getPublicPools({ limit: 10 });

// Get pool metrics
const metrics = await dob.pools.getPool('CDXYZ...');
console.log(`APR: ${metrics.estimated_apr}%`);
console.log(`Participants: ${metrics.quantity_participants}`);

Authentication

Authenticated operations (creating pools, widgets, projects) require wallet-based login:

// 1. Get challenge message
const { message } = await dob.auth.getNonce('GBDM...');

// 2. Sign with your wallet (Freighter example)
import { signMessage } from '@stellar/freighter-api';
const signature = await signMessage(message);

// 3. Sign in (token stored internally)
await dob.auth.signIn({
  wallet: 'GBDM...',
  signature,
  provider: 'freighter',
});

Creating a Pool

The SDK handles the full 5-step Stellar pool creation flow. You only need to provide a signTransaction callback:

const result = await dob.pools.createPool({
  userPublicKey: 'GBDM...',
  poolConfig: {
    name: 'Revenue Share Pool',
    access: 'public',
    joinMode: 'request',       // 'request' | 'buy' | 'qr' | 'staking'
    distributionType: 'trusted', // 'trusted' | 'business' | 'dam'
    maxParticipants: 50,
    estimatedApr: 12,
  },
  participants: [
    { address: 'GBDM...', percentage: 60 },
    { address: 'GDJTUK...', percentage: 40 },
  ],
  signTransaction: async (xdr) => {
    // Your wallet signs the XDR
    return await signTransaction(xdr, {
      networkPassphrase: dob.networkPassphrase,
    });
  },
  onStep: (step) => console.log(step.message),
});

console.log('Pool address:', result.contractId);

Step-by-Step Control

For more control, use the individual methods:

// 1. Create record
const { contractRecordId } = await dob.pools.createContractRecord(pubKey);

// 2. Get deploy XDR
const { xdr: deployXdr } = await dob.pools.prepareDeploy(pubKey);
const signedDeploy = await wallet.signTransaction(deployXdr);

// 3. Submit deploy
const { contractId } = await dob.pools.submitDeploy(signedDeploy, contractRecordId);

// 4. Get init XDR
const { xdr: initXdr } = await dob.pools.prepareInitialize({
  userPublicKey: pubKey,
  contractId,
  participants,
});
const signedInit = await wallet.signTransaction(initXdr);

// 5. Finalize
const { pool } = await dob.pools.finalize({
  signedXdr: signedInit,
  poolData,
  contractRecordId,
  participants,
});

Pool Metrics

const pool = await dob.pools.getPool('CDXYZ...');

// Financial
pool.estimated_apr       // Estimated APR (%)
pool.real_apr            // Actual APR based on distributions
pool.total_distributed   // Total amount distributed
pool.last_distribution   // Last distribution timestamp

// Participants
pool.quantity_participants   // Current count
pool.max_participants        // Maximum allowed
pool.remaining_participation // Remaining capacity (%)

// Schedule
pool.distribution_period // 'Daily', 'Weekly', 'Monthly', etc.
pool.next_distribution   // Next distribution timestamp
pool.distribution_dates  // Full schedule

// Performance (buy pools)
pool.performance_metrics?.performance_status  // 'on_track' | 'overperforming' | 'underperforming'
pool.performance_metrics?.distribution_progress // Completion %
pool.performance_metrics?.historical_apr       // Based on actual pace

Marketplace

// Pool listings
const listings = await dob.pools.getPoolListings('CDXYZ...');
const stats = await dob.pools.getMarketplaceStats('CDXYZ...');
const history = await dob.pools.getPriceHistory('CDXYZ...');

// All listings
const allListings = await dob.pools.getAllListings();

Pool Actions

All pool actions follow a prepare/sign/submit pattern:

// Deposit tokens
const { xdr } = await dob.pools.prepareDepositToken({
  userPublicKey: pubKey,
  contractId: poolAddress,
  tokenAddress: 'CDU3Q...',
  amount: '1000000000', // in stroops
});
const signed = await wallet.signTransaction(xdr);
await dob.pools.submitDepositToken(signed);

// Distribute (admin only)
// Transfer shares
// Withdraw allocation
// ... same prepare/sign/submit pattern

Projects

// Create a project
const project = await dob.projects.create({
  name: 'My Project',
  description: 'Revenue sharing for contributors',
  owner_wallet: 'GBDM...',
  pools: ['CDXYZ...'],
});

// Query
const projects = await dob.projects.getProjectsByOwner('GBDM...');
const featured = await dob.projects.getFeaturedProjects();

DobLink Widgets

// Create a widget
const widget = await dob.widgets.create({
  name: 'Homepage Widget',
  pool_address: 'CDXYZ...',
  theme: 'dark',
  primary_color: '#FF6B00',
  button_text: 'Join Pool',
});

// Get widget data (public - for embedding)
const data = await dob.widgets.get(widget.widget_id);

// Track views (call from your embed page)
await dob.widgets.recordView(widget.widget_id, 'mysite.com');

// Analytics
const analytics = await dob.widgets.getAnalytics(widget.widget_id, 30);
console.log(`Views: ${analytics.total_views}`);

Utilities

import {
  compressPoolData,
  expandPoolData,
  generateTicker,
  isValidStellarAddress,
} from '@dobprotocol/sdk';

// Compress/expand pool data
const compressed = compressPoolData({ name: 'My Pool', ... });
const expanded = expandPoolData(compressed);

// Generate ticker from name
generateTicker('My Revenue Pool'); // 'MRP'

// Validate Stellar address
isValidStellarAddress('GBDM...'); // true

Networks

Network	ID	Network Passphrase
Testnet	9	`Test SDF Network ; September 2015`
Mainnet	10	`Public Global Stellar Network ; September 2015`

Access via the client:

dob.networkId;         // 9 or 10
dob.networkPassphrase; // For wallet signing

Error Handling

import {
  DobProtocolError,
  AuthenticationError,
  TransactionError,
  NotFoundError,
} from '@dobprotocol/sdk';

try {
  await dob.pools.getPool('invalid');
} catch (err) {
  if (err instanceof NotFoundError) {
    console.log('Pool not found');
  } else if (err instanceof AuthenticationError) {
    console.log('Need to authenticate');
  } else if (err instanceof TransactionError) {
    console.log('Transaction failed:', err.details);
  }
}