Security Model

Security Architecture & Test Coverage

Token Distribution Protocol on Solana

Program ID: 6VkmhxbTH9dnzAE7Scpxn6R3HeXYtY4oZffAFMAYvECk

What is TDP?

A protocol for creating, managing, and claiming token vesting schedules on Solana — replacing spreadsheets and manual multisig transfers with an on-chain Anchor program.

graph LR
    A[Creator] -->|create_stream| B(Anchor Program)
    B --> C[PDA Vault]
    D[Recipient] -->|withdraw| B
    B -->|CPI| E[SPL Token]
    F[Web dApp] -->|reads| C
    G[TS SDK] -->|helpers| F

Architecture Overview

monorepo/
├── apps/
│   ├── solana-tdp-anchor/   ← Anchor program (Rust)
│   ├── dapp/                ← React frontend (Vite)
│   └── api/                 ← Cloudflare Worker
├── packages/
│   └── solana-tdp-sdk/      ← TypeScript SDK
└── docs/                    ← Architecture, deployment

Anchor 0.32.1 — on-chain vesting logic (7 instructions)
React + TanStack Router — frontend dApp
TypeScript SDK — PDA helpers, event parsing, vesting math

Security Model — Core Design

Design Decision	Purpose
PDA seeds include recipient	Cryptographically commits beneficiary to the PDA address — extra safety beyond Anchor’s `has_one`
Custom PDA vault (not ATA)	Fully closable on completion/cancellation — returns rent SOL
`invoke_signed` for all CPI transfers	Only the program can move tokens via PDA signing
Token-2022 transfer-hook rejection	Prevents mints with transfer hooks that could block CPI

Security Model — Guardrails

Guardrail	Where
Checked math (`checked_mul`, `checked_div`, etc.)	All vesting calculations
Custom error codes	Every invalid state transition
60-second minimum duration	Anti-griefing — prevents account space bloat
`cancelled` state set before CPI	Reentrancy protection during cancel operations
Cliff bounds validated against start/end	Prevents logical inconsistencies
Vesting count tracked per creator	Prevents stream address collision

Account Model

Three account types, all Program-Derived Addresses:

StreamAccount (187 bytes)
├── creator, recipient, mint, vault
├── amount, amount_withdrawn
├── start_time, end_time, cliff_time
├── vesting_count, cancelled, bump, vault_bump

MilestoneStreamAccount (196 bytes)
├── creator, recipient, mint, vault
├── amount, amount_withdrawn
├── milestone_authority, milestone_reached
├── vesting_count, cancelled, bump, vault_bump

CreatorConfig (48 bytes)
├── creator, vesting_count

PDA seeds: ["stream", creator, recipient, mint, vesting_count]

Testing Strategy — 3 Layers

graph TD
    subgraph "Layer 1: Rust Unit Tests"
        A[cargo test] --> A1[Error disciminants]
        A --> A2[Event serialization]
        A --> A3[PDA derivation]
    end
    subgraph "Layer 2: Anchor Integration Tests"
        B[Vitest + litesvm] --> B1[Create/Withdraw/Cancel]
        B --> B2[Milestone lifecycle]
        B --> B3[Security audit vectors]
    end
    subgraph "Layer 3: Web Unit Tests"
        C[Vitest + jsdom] --> C1[Format utilities]
        C --> C2[cn class merging]
    end

Layer 1 — Rust Unit Tests

Embedded program tests (#[cfg(test)]):

File	Tests	Coverage
`errors.rs`	2	Error discriminant values, error messages for all 15 variants
`events.rs`	4	Serialization round-trips for 4 event types (StreamCreated, TokensClaimed, StreamCompleted, StreamCancelled)
`create_stream.rs`	5	PDA derivation determinism, vesting_count uniqueness, duration boundary, balance checks

Run with: cargo test

Layer 2 — Anchor Integration Tests

Vitest + anchor-litesvm (SVM simulator, no validator needed):

Test File	Tests	Coverage
`000.create-stream.test.ts`	9	Happy path, cliff variant, 4 validation rejections, insufficient balance, event emission
`001.withdraw.test.ts`	15	Partial/full vesting, cumulative tracking, cliff/before-start/cancelled rejections, ExceedsClaimable, event, T/P third-party rejection
`002.cancel.test.ts`	8	Pre-start/partial/post-end splits, double-cancel, event, account closure
`003.milestone.test.ts`	18	Full milestone lifecycle: create, trigger, withdraw, cancel + events
`005.security-audit.test.ts`	19	Dedicated security audit suite — 7 attack categories

Custom alpha-sort sequencer ensures deterministic test order.

Layer 3 — Web Unit Tests

Vitest + jsdom for frontend utilities:

Test File	Tests	Coverage
`format.test.ts`	18	`formatAddress` (3), `formatSol` (5), `formatDate` (2), `formatDuration` (6), `clamp` (3)
`cn.test.ts`	4	Merging, conditional classes, Tailwind conflict resolution, empty input

Setup: @testing-library/jest-dom matchers + Buffer polyfill

Run with: pnpm test in apps/dapp/

Security Audit Test Suite — Deep Dive

File: solana-tdp.005.security-audit.test.ts

7 attack vector categories — 19 tests total:

#	Category	Tests	What It Verifies
1	Signer Authority	3	Non-sender rejected for create_milestone, non-creator for cancel_milestone, wrong sender for withdraw
2	PDA Uniqueness	4	Different senders → different PDAs, vesting_count chain prevents collision
3	Integer Overflow	1	Handles 10^16 amounts with vesting_count chain
4	Account Ownership	4	Vault authority = stream PDA, mint constraint on withdraw/cancel
5	State Transition Guards	2	`cancelled` set before CPI (reentrancy)
6	Wrong Account Attacks	4	Rejects wrong vault PDA, wrong sender_token account
7	Timestamp Boundaries	1	Rejects `create_stream` with past start_time

Attack Vectors — Detail

Signer Authority:
  ✗ CreateMilestoneStream with non-sender        → Unauthorized
  ✗ CancelMilestone with non-creator             → Unauthorized
  ✗ Withdraw with wrong sender account           → constraint raw 1

PDA Uniqueness:
  ✗ Same stream PDA for different senders        → address not unique
  ✗ Identical vault PDAs for different streams   → address not unique
  ✓ vesting_count increments → unique stream PDA

Integer Overflow:
  ✓ 10,000,000,000,000,000 lamports
  ✓ vesting_count chains across streams

Account Ownership:
  ✗ Vault owned by wrong PDA                     → TokenOwnerOff
  ✗ Withdraw with different mint vault           → constraint raw 1
  ✗ Cancel with different mint vault             → constraint raw 1

Pre-commit Security Gates

Every commit runs automatically:

┌─ nano-staged ──────────────────────────┐
│  *.{js,ts,tsx} → oxlint --fix + oxfmt  │
│  *.{css,md,json} → oxfmt               │
└─────────────────────────────────────────┘
┌─ TypeScript typecheck ─────────────────┐
│  web: tsgo --noEmit                    │
│  api: typecheck                        │
│  anchor: tsgo --noEmit                 │
└─────────────────────────────────────────┘
┌─ Rust checks ──────────────────────────┐
│  cargo fmt --check                     │
│  cargo clippy --all-targets -D warnings│
└─────────────────────────────────────────┘

Oxlint rules: no-explicit-any (error), no-non-null-assertion (error), import/no-cycle (error), no-console (warn)

CI/CD Security Pipeline

GitHub Actions — 13 jobs on push/PR to main:

Job	Guard
`typecheck-web`	TypeScript strict checks
`typecheck-api`	Worker type safety
`typecheck-sdk`	SDK type safety
`typecheck-anchor-ts`	Test code type safety
`lint`	`oxlint .` (304 rules)
`format`	`oxfmt --check .`
`lint-rust`	`cargo fmt --check` + `cargo clippy`
`build-web`	Production Vite build
`test-api`	API tests with vitest
`test-web`	Web unit + Storybook browser tests
`anchor`	`cargo fmt` + `clippy` + `anchor build` + vitest tests
`deploy-web`	Cloudflare Pages (main only)
`deploy-api`	Cloudflare Worker (main only)

Known Gaps & Future Work

Gap	Impact	Suggested Remediation
No dependency vulnerability scanning	Supply-chain risk from compromised npm/crates	Add `npm audit` / `cargo audit` or Dependabot to CI
No formal verification	Mathematical correctness of vesting math unproven	SMT solver (Z3) on vesting formulas
No fuzzing	Edge cases in account deserialization	`trident` fuzzing harness for Anchor
No manual audit	No third-party review of the economic logic	Professional Solana security audit
No invariant testing	Cross-instruction invariants untested	Fuzz testing with state invariants

Appendix — Full Test Coverage Map

Test File	Instructions/Utilities	Layer	Tests
`errors.rs`	Error discriminant stability	Rust unit	2
`events.rs`	Event serialization round-trips	Rust unit	4
`create_stream.rs`	PDA derivation, vesting math	Rust unit	5
`000.create-stream.test.ts`	`create_stream`	Integration	9
`001.withdraw.test.ts`	`withdraw`	Integration	15
`002.cancel.test.ts`	`cancel`	Integration	8
`003.milestone.test.ts`	Milestone lifecycle (4 ixns)	Integration	18
`005.security-audit.test.ts`	7 attack categories (all ixns)	Integration	19
`format.test.ts`	`formatAddress/Sol/Date/Duration/clamp`	Web unit	18
`cn.test.ts`	`cn()` class merging	Web unit	4
Total			~147

Solana TDP — Token Distribution Protocol

Program: 6VkmhxbTH9dnzAE7Scpxn6R3HeXYtY4oZffAFMAYvECk
Repo: github.com/simplyvest/simplyvest
Tests: pnpm test (all workspaces)
Build: pnpm build (all workspaces)