Back to Documentation

API Reference

Complete reference for all program instructions, account structures, and error codes.

Program Information

Program ID (Devnet): 3iKABSF5zoQjGPykxUQNxbm7eQADqs8DreuGupggc679
Version: 2.0.0
Network: Solana Devnet

Instructions

create_escrow

Creates a new escrow with split-based payment distribution.

Parameters

  • escrow_id: u64 - Unique identifier for this escrow
  • splits: Vec<Split> - Payment distribution (must sum to 10000 bps)
  • total_amount: u64 - Total amount to escrow (in lamports)

Accounts

  • payer - Signer, pays for account creation
  • escrow - PDA, will be created
  • mint - Token mint (e.g., USDC)
  • vault - PDA, token account for holding funds
  • system_program
  • token_program

Example

await program.methods
  .createEscrow(
    new BN(escrowId),
    splits,
    new BN(totalAmount)
  )
  .accounts({
    payer: payer.publicKey,
    escrow: escrowPDA,
    mint: USDC_MINT,
    vault: vaultPDA,
    systemProgram: SystemProgram.programId,
    tokenProgram: TOKEN_PROGRAM_ID,
  })
  .signers([payer])
  .rpc();

fund_escrow

Transfers tokens from payer to escrow vault.

Accounts

  • payer - Signer
  • escrow - Must exist
  • payer_token_account - Source of funds
  • vault - Destination
  • token_program

approve_escrow

Marks escrow as approved for settlement (optional workflow step).

Accounts

  • authority - Signer (must be payer or admin)
  • escrow - Will be marked approved

settle_escrow

Distributes funds to all recipients according to splits.

Accounts

  • authority - Signer
  • escrow
  • vault
  • token_program

Remaining Accounts

Must provide token accounts for all recipients in split order:

.remainingAccounts([
  { pubkey: recipient1TokenAccount, isWritable: true, isSigner: false },
  { pubkey: recipient2TokenAccount, isWritable: true, isSigner: false },
  // ... one for each split
])

Account Structures

Split

pub struct Split {
    pub recipient: Pubkey,  // Recipient address
    pub bps: u16,           // Basis points (0-10000)
}

EscrowAccount

pub struct EscrowAccount {
    pub payer: Pubkey,
    pub escrow_id: u64,
    pub mint: Pubkey,
    pub vault: Pubkey,
    pub splits: Vec<Split>,
    pub total_amount: u64,
    pub status: EscrowStatus,
    pub created_at: i64,
    pub funded_at: Option<i64>,
    pub approved_at: Option<i64>,
    pub settled_at: Option<i64>,
    pub deadline: Option<i64>,
    pub version: u8,
    pub bump: u8,
    pub vault_bump: u8,
}

EscrowStatus

pub enum EscrowStatus {
    Created,      // Just created
    Funded,       // Tokens transferred to vault
    Approved,     // Approved for settlement
    Settled,      // Funds distributed
    Cancelled,    // Cancelled and refunded
    Disputed,     // Under dispute
}

Error Codes

CodeNameDescription
6000InvalidSplitsSplits validation failed
6001InvalidAmountAmount is zero or invalid
6002UnauthorizedCaller not authorized
6003InvalidStatusEscrow in wrong status
6004DeadlinePassedDeadline has passed

Constants

  • MAX_SPLITS: usize = 8 - Maximum recipients per escrow
  • BPS_DENOMINATOR: u16 = 10000 - Basis points denominator (100%)
  • ESCROW_SEED: &[u8] = b"escrow" - PDA seed for escrow accounts
  • VAULT_SEED: &[u8] = b"vault" - PDA seed for vault accounts

TypeScript SDK

The TypeScript SDK provides helper functions for common operations:

import { calculateTaskSplits, calculateJobSplits } from '@/lib/blockchain/split-calculator';

// Calculate splits for 10% fee
const result = calculateTaskSplits(
  workerAddress,
  platformAddress,
  100_000_000, // 100 USDC
  partnerAddress, // optional
  300 // 3% partner commission (optional)
);

// result.splits - ready to pass to create_escrow
// result.totalAmount - total including fees
// result.breakdown - human-readable amounts
MarketBrowse
MessagesProfile