Stokkie

Status: active side project / portfolio work — runs on Solana devnet. Not deployed to mainnet; not audited. Source-available under BUSL-1.1 (see License).

Stokkie digitizes South African stokvels as a Social Yield Protocol on Solana. Groups contribute stablecoins (USDC/PYUSD) to a PDA vault, earn yield between rotations, and receive automated monthly payouts with transparent fees.

Built with Anchor (Rust) + a Next.js App Router frontend. The repo demonstrates an end-to-end Solana program: PDA-based vaults, rotation/payout logic, async on-chain governance, embedded-wallet onboarding (Privy), and a ZAR on/off-ramp design for a "crypto-invisible" UX.

Features

• PDA-based group vaults and config (Anchor 0.30+).
• Stablecoin-first flows (6 decimals), u64 on-chain math.
• Rotation payouts with a 0.5% platform fee to treasury.
• Optional yield adapter hooks (Kamino/Jito).
• PDA-based proposals with async member voting.
• Mobile-first Next.js App Router frontend.
• Constitution PDF generator aligned with NASASA guidance.

Advanced Roadmap (Notes)

• 90/10 capital preservation ("Permanent Pot") with endowment growth.
• Dynamic payouts: on-time score priority, emergency swaps, or bidding.
• Weekly/fortnightly cycles + milestone payouts.
• Multi-asset staking portfolio with auto-rebalancing.
• Social insurance add-on (burial/hospital cash).
• Plugin monetization tiers: Free (standard), Pro (bidding/swaps), Elite (endowment + multi-asset).

Bank-Grade Hardening (Notes)

• Price oracles: Pyth for SOL/USDC (and other pairs) to ensure fair value.
• Emergency pause: pause/unpause instruction for protocol incidents.
• Slippage protection: min-out checks on yield withdrawals using BPS limits.

On/Off-Ramp Integration (Planned)

For a fully "crypto-invisible" UX, integrate South African payment rails:

On-Ramps (ZAR → USDC)

• Stitch — ZAR bank transfers via their Pay API. User sees "Add R500", backend converts to USDC.
• VALR Pay — Instant ZAR to USDC conversion via VALR's merchant API.

Off-Ramps (USDC → ZAR)

• Luno — USDC withdrawal to ZAR bank account.
• VALR — Similar off-ramp capability.

Flow

1. User clicks "Add Funds" → Opens Stitch/VALR payment modal
2. User pays with EFT/card in ZAR
3. Backend receives webhook → Mints/transfers USDC to user's embedded wallet
4. User sees "R500 added" without knowing it's now USDC on Solana

Integration Notes

• Use Privy embedded wallets so users never see wallet addresses
• Store user's bank account preferences for quick off-ramp
• Show ZAR values everywhere, convert to USDC only for on-chain operations

Architecture (Brief)

sequenceDiagram
  participant Member
  participant WebApp
  participant StokkieProgram
  participant VaultPDA
  participant YieldAdapter
  participant TreasuryPDA

  Member->>WebApp: SMS/Email auth (Privy)
  WebApp->>StokkieProgram: InitializeStokkie
  Member->>StokkieProgram: DepositContribution
  StokkieProgram->>VaultPDA: Transfer USDC/PYUSD
  StokkieProgram->>YieldAdapter: Deposit/Withdraw yield
  StokkieProgram->>TreasuryPDA: PlatformFee (0.5%)
  StokkieProgram->>Member: Rotation Payout

Loading

Repo Layout

• programs/stokkie/ — Anchor program (accounts + instructions).
• tests/ — Anchor unit tests (rotation cycle, fees, late payments).
• tests/integration/ — BDD/Cucumber-style integration tests.
• web/ — Next.js App Router frontend + PDF generator + webhook route.
• web/lib/ — Anchor client hooks and utilities.

Frontend Routes

• / — Landing page.
• /signup — SMS onboarding (Privy).
• /create — Stokkie creation wizard (auth-gated).
• /invite — Platform + group invite links.
• /dashboard — Post-login dashboard.
• /constitution — Group selector (auth-gated).
• /constitution/[stokvelId] — Prefilled constitution builder.

Local Development

Quick Start (Localnet)

First-time setup — generate the local validator keypair (kept out of git):

mkdir -p keypairs && solana-keygen new --no-bip39-passphrase -o keypairs/localnet.json

Then run everything with one command:

npm run dev

This starts:

1. solana-test-validator (local blockchain)
2. Deploys the Stokkie program
3. Starts the Next.js frontend at http://localhost:3000

Manual Setup (Localnet)

Terminal 1 - Start validator:

solana-test-validator --reset

Terminal 2 - Build and deploy:

anchor build
anchor deploy

Terminal 3 - Start frontend:

cd web
cp env.local.example .env.local  # Configure environment
npm install
npm run dev

Deploy to Devnet

# Ensure you have SOL on devnet
solana airdrop 2 --url devnet

# Deploy
npm run deploy:devnet

# Update web/.env.local with devnet RPC
# NEXT_PUBLIC_SOLANA_RPC_URL=https://api.devnet.solana.com

Run All Tests

npm run test:all

Anchor (Program + Unit Tests)

npm run test
# or: anchor test

BDD/Integration Tests

The tests/integration/ folder contains Cucumber-style tests using Given/When/Then format:

npm run test:integration
# or: anchor test -- --grep "Feature:"

Frontend Client Tests

npm run test:web
# or: cd web && npm run test:integration

Frontend

cd web
npm install
npm run dev

One-command dev

npm install
npm run dev

Configuration Notes

• RPC/webhooks: use Helius in production.
• Stablecoins: USDC/PYUSD with 6 decimals.
• Privy auth: set NEXT_PUBLIC_PRIVY_APP_ID in web/.env.local.
• Solana RPC: set NEXT_PUBLIC_SOLANA_RPC_URL (defaults to devnet).
• Local validator wallet: keypairs/localnet.json (configured in Anchor.toml). This file is gitignored — generate your own (see Quick Start). Never commit keypairs.

Frontend-to-Contract Integration

The frontend uses Solana Wallet Adapter for wallet connection:

• Connect via Phantom or other Solana wallets.
• Create Stokkie groups on-chain from the /create wizard.
• View and manage groups from the dashboard.

Key client files:

• web/lib/anchor.ts — Program client setup and PDA derivation.
• web/lib/useStokkie.ts — React hook for program interactions.

Legal/Compliance Context (SA)

Stokkie is designed as non-custodial software. Funds are controlled by the program and group rules, not the platform. Groups should remain under 100 members and follow NASASA-aligned constitutions.

License

Source-available under the Business Source License 1.1 (BUSL-1.1) — see LICENSE.

• ✅ Read, copy, modify, and use for non-production purposes (study, dev, testing).
• ❌ No production or commercial use before the Change Date without a commercial license from the author.
• 🔓 On 2030-06-09 (the Change Date), it automatically converts to Apache-2.0.

For commercial licensing before then, contact the author.