SDK Reference

Complete API reference for all modules in @dobprotocol/sdk.

Modules

Module	Access	Description
dob.auth	--	Wallet authentication
dob.pools	Read/Write	Pool creation, queries, actions, marketplace
dob.projects	Read/Write	Project management
dob.widgets	Read/Write	DobLink widget management + analytics

---

Auth Module

auth.getNonce(walletAddress)

Get a challenge message for wallet authentication.

const { message } = await dob.auth.getNonce('GBDM6KRX...');
// message: "Sign this message to authenticate..."

auth.signIn(params)

Submit signed challenge to get a JWT token. Token is stored internally.

await dob.auth.signIn({
  wallet: 'GBDM6KRX...',
  signature: signedMessage,
  provider: 'freighter',  // 'freighter' | 'albedo' | 'xbull' | 'lobstr'
});

auth.isUser(walletAddress)

Check if a wallet is registered.

const { is_user } = await dob.auth.isUser('GBDM6KRX...');

auth.validate()

Check if the current JWT token is still valid.

const valid = await dob.auth.validate(); // true | false

auth.logout()

Clear the stored JWT token.

---

Pools Module

Queries (read scope)

pools.getPool(poolAddress)

Get detailed metrics for a single pool.

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

Returns: PoolMetrics with fields:

Field	Type	Description
address	string	Pool contract address
name	string	Pool name
ticker	string	Pool ticker symbol
estimated_apr	number	Estimated APR (%)
real_apr	number	Actual APR based on distributions
total_distributed	number	Total amount distributed
quantity_participants	number	Current participant count
max_participants	number	Maximum allowed
remaining_participation	number	Remaining capacity (%)
distribution_period	string	'Daily', 'Weekly', 'Monthly', etc.
next_distribution	number	Next distribution timestamp
distribution_dates	DistributionDate[]	Full schedule
performance_metrics	PerformanceMetrics	Performance analysis (buy pools)
is_verified	boolean	Has DobValidator certificate
pool_data	PoolDataExpanded	Full pool configuration

pools.getPublicPools(params?)

Get paginated list of public pools.

const pools = await dob.pools.getPublicPools({
  page: 1,
  limit: 20,
  network_id: 10,
  category: 'depin',
});

pools.getPoolsByCreator(walletAddress)

Get pools created by a wallet address.

pools.getUserPools(walletAddress)

Get pools where a wallet is a participant.

pools.getFeaturedPools()

Get curated featured pools.

pools.searchPool(poolAddress)

Search for a pool by address.

pools.getChainDistributed(poolAddress)

Get on-chain total distributed amount.

pools.getLastDistribution(poolAddress)

Get the most recent distribution details.

pools.getBalance(publicKey)

Get XLM and token balances for a Stellar account.

const { balance, balances } = await dob.pools.getBalance('GBDM...');

---

Pool Creation (write scope)

The SDK supports both high-level and low-level pool creation.

High-Level: pools.createPool(params)

Orchestrates the entire 5-step creation flow. Calls signTransaction twice (deploy + initialize).

const result = await dob.pools.createPool({
  userPublicKey: 'GBDM...',
  poolConfig: {
    name: 'Revenue Share Pool',
    ticker: 'RSP',
    description: 'Revenue sharing for contributors',
    access: 'public',           // 'public' | 'private'
    joinMode: 'request',        // 'request' | 'buy' | 'qr' | 'staking'
    distributionType: 'trusted', // 'trusted' | 'business' | 'dam'
    maxParticipants: 50,
    estimatedApr: 12,
    distributionTokenAddress: 'CDU3Q...',  // SAC token address
  },
  participants: [
    { address: 'GBDM...', percentage: 60 },
    { address: 'GDJTUK...', percentage: 40 },
  ],
  signTransaction: async (xdr) => {
    return await freighter.signTransaction(xdr, {
      networkPassphrase: dob.networkPassphrase,
    });
  },
  onStep: (step) => {
    // step: { step: number, status: string, message: string }
    updateUI(step.message);
  },
});

// result: { pool, contractId, transactionHash }

Step progression:

Step	Status	Description
1	creating_record	Creating contract record in DB
2	preparing_deploy	Building deploy transaction
3	awaiting_deploy_signature	Waiting for wallet signature
4	submitting_deploy	Submitting to Stellar network
5	preparing_initialize	Building init transaction
6	awaiting_init_signature	Waiting for wallet signature
7	finalizing	Saving pool to database
8	complete	Pool created

Low-Level Steps

For more control, use individual methods:

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

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

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

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

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

---

Pool Actions (write scope)

All actions follow a prepare → sign → submit pattern.

Deposit Tokens

const { xdr } = await dob.pools.prepareDepositToken({
  userPublicKey: 'GBDM...',
  contractId: 'CDXYZ...',
  tokenAddress: 'CDU3Q...',
  amount: '10000000', // in stroops (7 decimals)
});
const signed = await wallet.signTransaction(xdr);
await dob.pools.submitDepositToken(signed);

Distribute Tokens (admin only)

const { xdr } = await dob.pools.prepareDistributeTokens({
  userPublicKey: 'GBDM...',
  contractId: 'CDXYZ...',
  tokenAddress: 'CDU3Q...',
  amount: '5000000',
});
const signed = await wallet.signTransaction(xdr);
await dob.pools.submitDistributeTokens(signed);

Transfer Shares

const { xdr } = await dob.pools.prepareTransferShares({
  userPublicKey: 'GBDM...',
  contractId: 'CDXYZ...',
  toAddress: 'GDJTUK...',
  sharesAmount: 1000, // basis points (1000 = 10%)
});
const signed = await wallet.signTransaction(xdr);
await dob.pools.submitTransferShares(signed);

Withdraw Allocation

const { xdr } = await dob.pools.prepareWithdrawAllocation({
  userPublicKey: 'GBDM...',
  contractId: 'CDXYZ...',
  tokenAddress: 'CDU3Q...',
});
const signed = await wallet.signTransaction(xdr);
await dob.pools.submitWithdrawAllocation(signed);

---

Marketplace (read scope)

pools.getPoolListings(poolAddress)

Get active share listings for a pool.

const listings = await dob.pools.getPoolListings('CDXYZ...');
// listings: [{ sale_address, owner_address, price_per_share, shares_amount, ... }]

pools.getAllListings()

Get all active marketplace listings across all pools.

pools.getMarketplaceStats(poolAddress)

const stats = await dob.pools.getMarketplaceStats('CDXYZ...');
// stats: { total_listings, active_listings, total_volume, floor_price, average_price }

pools.getPriceHistory(poolAddress)

Get historical price data for a pool's shares.

---

Projects Module

projects.create(params) (auth required)

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

projects.getProject(id)

projects.getProjectsByOwner(walletAddress)

projects.getAllProjects()

projects.getFeaturedProjects()

projects.updateProject(id, data) (auth required)

await dob.projects.updateProject(1, {
  project: { name: 'Updated Name', description: 'New description' },
  pools: ['CDXYZ...'],
});

---

Widgets Module

widgets.create(params) (auth required)

Create a DobLink widget for a pool.

const widget = await dob.widgets.create({
  name: 'Homepage Widget',
  pool_address: 'CDXYZ...',
  theme: 'dark',
  primary_color: '#FF6B00',
  button_text: 'Join Pool',
  show_apr: true,
  show_members: true,
  show_distributions: true,
  show_network: true,
  allowed_domains: ['mysite.com', '*.mysite.com'],
});
// widget: { widget_id: 'wgt_...', ... }

widgets.list() (auth required)

List all widgets owned by the authenticated user.

widgets.get(widgetId)

Get widget configuration and associated pool data. Public -- no auth required.

const { widget, pool } = await dob.widgets.get('wgt_abc123...');

widgets.update(widgetId, params) (auth required)

await dob.widgets.update('wgt_abc123...', {
  theme: 'light',
  button_text: 'Invest Now',
});

widgets.delete(widgetId) (auth required)

Soft-deletes the widget (deactivates it).

widgets.recordView(widgetId, referrerDomain?)

Record an analytics view. Public -- call this from your embed page.

await dob.widgets.recordView('wgt_abc123...', 'mysite.com');

widgets.getAnalytics(widgetId, days?) (auth required)

const analytics = await dob.widgets.getAnalytics('wgt_abc123...', 30);
// analytics: { total_views, daily_views[], top_referrers[] }

---

Utility Functions

Exported directly from the package:

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

Function	Description
compressPoolData(config)	Convert PoolConfig to compressed DB format
expandPoolData(compressed)	Convert compressed format to human-readable
generateTicker(name)	Generate ticker from pool name (up to 5 chars)
isValidStellarAddress(addr)	Validate Stellar public key format
validateParticipants(list)	Validate participant array (sum=100, valid addresses)

---

TypeScript Types

All types are exported from the package:

import type {
  PoolConfig,
  PoolMetrics,
  PoolSummary,
  Participant,
  Widget,
  WidgetAnalytics,
  Project,
  SignTransactionFn,
  // ... and many more
} from '@dobprotocol/sdk';

See the package source for the complete type definitions.