KZP Mini is a Solana implementation of a workplace mutual-aid fund (Kasa Zapomogowa Pracownicza).

Members:

• join a shared pool
• deposit savings
• request loans with two guarantors
• repay obligations
• withdraw savings and leave

The protocol enforces financial mechanics on-chain while allowing membership policy and governance to remain off-chain. Built in Rust using Anchor.

Superteam Poland submission - entry for Build everyday real-world systems as on-chain Rust programs on Superteam Earn.

Repository: github.com/vvylym/kzp-mini

Traditional workplace savings associations rely on spreadsheets, manual bookkeeping, paper signatures, and committee decisions. That creates opaque balances, delayed settlement, manual verification, and dispute risk.

KZP Mini replaces administrative coordination with on-chain enforcement.

Deeper domain and mapping: docs/ARCHITECTURE.md.

• One-time entry fee on join
• Member deposits to shared vault
• Per-member savings ledger

• Loan requests with two nominated guarantors
• Partial then full co-sign
• Automatic disbursement when both guarantors approve

• Loan cap at 3× member savings
• One active loan per borrower
• Up to five guarantees per member
• Exit blocked while borrowing or guaranteeing

• Pool initialization and SPL mint binding
• Default settlement with guarantor SPL recovery

Program ID: GsjUnBFvYtcxNwCrydPUjQTngGTqdx5v7APnWahnqwkx

• Deploy program
• Initialize pool
• Join members (admin + two guarantors)
• Deposit savings
• Request loan
• Co-sign (guarantor A, then B)
• Disburse principal
• Repay loan
• Exit pool

Demo accounts: pool 4nZf8sPfRvKUucN43FirPQ3T3JvvkCo4LFukGYCRL7tg · loan toqwDKpVPAdHPkLSJWyh5yLdDTf7szVEKPRtVNek4bL · mint 9CsRiEPkagzfTLTDhsBhuvfHNXupBugtHzy1wPefTi4V

bash scripts/devnet-demo.sh   # full scripted lifecycle

Rust 1.89, Solana CLI 3.x, Anchor 1.0.2, cargo-nextest. Full toolchain notes: docs/GETTING_STARTED.md.

git clone https://github.com/vvylym/kzp-mini.git && cd kzp-mini
mkdir -p target/deploy && cp keys/program.json target/deploy/kzp_mini-keypair.json
NO_DNA=1 anchor build --ignore-keys
cargo build -p kzp-cli --release

Keypairs are local-only - see keys/README.md.

bash scripts/deploy.sh devnet

cargo run -p kzp-cli --release -- config

Commands grouped by role. Full reference: docs/CLI.md.

kzp pool initialize --name "My Pool" --entry-fee 50 --mint <MINT>
kzp pool join --pool <POOL> --entry-fee 50
kzp pool deposit --pool <POOL> --amount 1000000
kzp loan request --pool <POOL> --nonce 1 --amount 500000 \
  --guarantor-a <PUBKEY_A> --guarantor-b <PUBKEY_B>
kzp loan cosign --loan <LOAN>
kzp loan repay --loan <LOAN> --amount 500000
kzp pool exit --pool <POOL>

Global flags: --cluster, --rpc-url, --wallet, --dry-run.

                    Pool PDA
                        │
                        ▼
                   Vault PDA
                        │
        ┌───────────────┼───────────────┐
        ▼               ▼               ▼
   Member PDA      Member PDA      Member PDA
        │
        ▼
    Loan PDA

Instructions (10): initialize_pool · join_pool · deposit_savings · request_loan · co_sign_loan · repay_loan · cancel_loan · withdraw_cosign · settle_default · exit_pool

Details: docs/ARCHITECTURE.md · docs/INSTRUCTIONS.md · docs/STATE.md

Two parallel views:

1. SPL vault - actual token balance
2. Ledger - pool.total_savings and member.savings_balance

Entry fees fund the vault but not member savings (liquidity buffer). Disburse and exit are fail-closed if vault balance is insufficient.

Full model: docs/ACCOUNTING.md.

Pending → Active → Repaid
                 ↘ Defaulted
Pending → cancel_loan

• Membership and savings state
• Loan limits and guarantor rules
• Co-sign before disbursement
• Vault liquidity checks
• Arithmetic safety (checked_add / checked_sub)

• Who may join the pool (workplace policy)
• Whether a default is justified (admin judgment)
• SPL mint legitimacy at pool creation

Full threat model: docs/SECURITY.md.

programs/kzp-mini/src/
├── instructions/   Anchor account constraints
├── handlers/       CPIs + state updates
├── operations/     Pure business rules (unit-tested)
├── state.rs        Pool, Member, Loan
└── utils/          PDA helpers

cli/                kzp command-line client
tests/              solana-program-test integration suite
docs/               Architecture, CLI, accounting, security
scripts/            ci.sh, deploy.sh, devnet-demo.sh
keys/               Local keypairs (gitignored)

Philosophy: instructions = validation · handlers = orchestration · operations = testable rules without Anchor contexts.

bash scripts/ci.sh

Conventions: tests/README.md.

Index: docs/README.md.

• Multisig pool administration
• On-chain governance voting for defaults
• Accrued yield on member savings (pool-level interest distribution)
• Dynamic guarantee models (e.g. variable split)
• Account migration support

bash scripts/ci.sh

Before opening a PR: cargo fmt, cargo clippy, cargo nextest, anchor build. See docs/GETTING_STARTED.md for toolchain details.

MIT