• n0-space/whirlpool + client + server — Whirlpool CoinJoin Suite
  • Metadata
  • Purpose
  • Architecture
    • Core (whirlpool/) — MIT
    • Client (whirlpool-client/) — AGPL-3.0
    • Server (whirlpool-server/) — AGPL-3.0
  • Whirlpool Flow
  • Key Properties
  • Relevance to Kapnet
    • Treasury Privacy
    • Integration Points
    • License Implications
  • Action Items

§n0-space/whirlpool + client + server — Whirlpool CoinJoin Suite

§Metadata

• Source: https://github.com/n0-space/whirlpool (core), whirlpool-client, whirlpool-server
• License: MIT (core/docs), AGPL-3.0 (client + server)
• Language: Java (client/server), Markdown (core)
• Size: 2.5MB (core) + 1.2MB (client) + 1.7MB (server)
• Heritage: Samourai Wallet developers

§Purpose

Chaumian CoinJoin implementation. Mathematically disassociates ownership of inputs to outputs in Bitcoin transactions. Increases privacy, protects against financial surveillance, improves fungibility.

§Architecture

§Core (whirlpool/) — MIT

• Theory documentation (THEORY.md)
• Architecture documentation (ARCHITECTURE.md)
• Protocol specification

§Client (whirlpool-client/) — AGPL-3.0

• Java client library
• BIP-47 payment codes for payjoin
• UTXO management and selection
• Transaction construction for CoinJoin
• Server communication (coordinator)
• Blinded credentials for anonymity

§Server (whirlpool-server/) — AGPL-3.0

• Java server (coordinator)
• RPC client for Bitcoin node
• Pool management (denomination, fee configuration)
• TX0 fee management
• UTXO verification viaBitcoin RPC
• Participant matching for CoinJoin rounds
• REST API for client communication

§Whirlpool Flow

1. TX0 (Premix): User creates premix transaction with coordinator
2. Mixing: Coordinator matches participants, constructs CoinJoin
3. Postmix: User receives mixed UTXO (no deterministic link to input)

§Key Properties

• 100% maximum entropy per cycle (10.54 bits)
• 1496 possible interpretations per cycle
• Never deterministic links between inputs and outputs
• Never cycle with yourself
• Never cycle with UTXOs seen in previous cycle
• Fast: Many small cycles (exponential anonymity growth in minutes)
• Portable: Modular, works on mobile
• Usable: Enforces best practices automatically

§Relevance to Kapnet

§Treasury Privacy

Whirlpool can be used for Kapnet treasury privacy:

• Treasury UTXOs mixed before distribution
• No deterministic link between treasury and recipients
• Improves fungibility of Kapnet payments

§Integration Points

1. Post-mix payouts: Treasury → Whirlpool → mixed UTXOs → recipients
2. Hedlbit privacy: Hedlbit transactions mixed for privacy
3. Mining pool payouts: Pool payouts mixed before distribution

§License Implications

• Core (MIT): Free to use, modify, distribute
• Client + Server (AGPL-3.0): Must share source if modified AND served over network
• If we run a Whirlpool coordinator as a service, we must open-source our modifications

§Action Items

1. Read THEORY.md for CoinJoin theory
2. Read ARCHITECTURE.md for system design
3. Evaluate for treasury privacy integration
4. Assess AGPL implications for coordinator service
5. Consider running private coordinator for Kapnet treasury