Architecture Overview

ZaphWork's escrow protocol is designed as infrastructure, not application-specific backend. This document explains the split-based settlement architecture and design principles.

Core Design Principles

1. Role-Agnostic

The protocol makes no assumptions about "freelancer" or "client" roles. It simply handles:

• Payer: The account that funds the escrow
• Recipients: Accounts that receive funds when settled

2. Externalized Policy

Business rules (fees, splits) are provided by the caller, not hardcoded in the program. This makes the protocol reusable for any use case.

3. Composable

Other programs and platforms can integrate without modification. The protocol is a primitive that can be composed with other Solana programs.

4. Backward Compatible

Version field allows handling both old and new escrows. Existing integrations continue to work.

Before vs After

V1: Application Backend

Client → create_escrow(amount, EscrowType::Task)
       → Program calculates: worker=90%, platform=10%
       → Hardcoded in program

V2: Infrastructure Primitive

Client → create_escrow(amount, splits=[{worker, 9000}, {platform, 1000}])
       → Program validates: sum(bps) == 10000
       → Generic, reusable

Split Structure

The core data structure is the Split:

pub struct Split {
    pub recipient: Pubkey,  // Who receives this portion
    pub bps: u16,           // Basis points (0-10000)
}

Invariants

• Sum of all bps must equal 10,000 (100%)
• No duplicate recipients
• No zero-address recipients
• Maximum 8 splits (MAX_SPLITS)

Escrow Lifecycle

1. Create

Caller provides splits and total amount. Program validates splits and creates escrow account.

2. Fund

Payer transfers tokens into the escrow vault. Vault is a PDA controlled by the program.

3. Approve (Optional)

For workflows requiring approval, the payer or admin can approve the escrow for settlement.

4. Settle

Program calculates amounts for each split and transfers from vault to recipients atomically. Remaining accounts must be provided for all recipients.

Security Model

PDA-Based Security

All critical accounts (escrow, vault) are PDAs derived from seeds. This prevents account confusion and ensures only the program can control funds.

Duplicate Account Checks

The program verifies no duplicate accounts in remaining accounts to prevent double-spending.

Overflow Protection

All arithmetic uses checked operations. Calculations use u128 intermediate values to prevent overflow.

Property-Based Testing

Mathematical invariants are proven across random inputs:

• Split amounts always sum to total
• No split exceeds total amount
• Calculation is deterministic
• Fee never exceeds amount

Use Case Examples

Freelance Marketplace

splits = [
  { recipient: freelancer, bps: 9000 },  // 90%
  { recipient: platform, bps: 1000 },    // 10%
]

Bounty with Referral

splits = [
  { recipient: contributor, bps: 9000 }, // 90%
  { recipient: platform, bps: 700 },     // 7%
  { recipient: referrer, bps: 300 },     // 3%
]

DAO Treasury Distribution

splits = [
  { recipient: team_lead, bps: 4000 },   // 40%
  { recipient: developer1, bps: 3000 },  // 30%
  { recipient: developer2, bps: 2000 },  // 20%
  { recipient: dao_treasury, bps: 1000 },// 10%
]

Integration Patterns

Direct Integration

Call the program directly from your Solana program using CPI (Cross-Program Invocation).

TypeScript SDK

Use the provided TypeScript SDK for easy integration from web applications.

Adapter Pattern

For backward compatibility, use the V2 adapter that maintains V1 API while using V2 splits internally.

Performance Characteristics

• Account Size: ~500 bytes per escrow (varies with number of splits)
• Compute Units: ~50k for create, ~100k for settle (depends on split count)
• Settlement Time: Single transaction, atomic
• Max Recipients: 8 per escrow

Future Enhancements

Potential future features (not yet implemented):

• Time-locked escrows
• Milestone-based releases
• Dispute resolution integration
• Multi-token support