PrizeDistro · money flows

Vaults, communal pool, payouts

Partners deposit USDC into their own vault. Each live award freezes 10¢ in that vault. Monday 00:00 UTC the pool pulls reserved USDC, funds that week’s communal prize, claims, and sends each partner’s share to their payout address. Unused USDC never leaves the vault. Live weeks back the pool on-chain. Demo/sandbox does not.

Where money sits

flowchart LR
  subgraph partner["Partner"]
    Wallet["Their wallet"]
    Payout["Payout EOA"]
    Users["They pay users off-chain"]
  end

  subgraph vault["DistroVault per partner"]
    Free["freeBalance unused USDC"]
    Reserved["reserved spent 10¢"]
  end

  subgraph pool["Communal pool — Monday"]
    Holdings["Pool-held prize"]
    Claimed["Claimed USDC"]
  end

  Prize["External prize protocol"]
  Ref["PrizeDistro referral EOA"]

  Wallet -->|"deposit USDC"| Free
  Free -->|"withdraw unused"| Wallet
  Free -->|"reserve 10¢ per live award"| Reserved
  Reserved -->|"Monday pull"| Prize
  Prize -->|"pool is purchaser of record"| Holdings
  Prize -->|"protocol referral"| Ref
  Holdings -->|"claim"| Claimed
  Claimed -->|"partner share of net"| Payout
  Payout --> Users

During the week — reserve a credit

A credit is not a separate token. It is $0.10 already in the vault, marked so the partner cannot withdraw it or spend it twice. Ledger unswept_micros is the retry queue if the on-chain reserve tx fails.

sequenceDiagram
  participant P as Partner API
  participant L as Ledger
  participant V as DistroVault
  participant E as Executor EOA

  P->>L: POST entry
  L->>V: read freeBalance
  alt freeBalance less than 10¢
    L-->>P: 402 insufficient_funds
  else
    L->>L: unswept += 10¢, insert paid entry
    L->>E: flushVaultReserve
    E->>V: reserve(10¢)
    Note over V: USDC stays in vault
    L-->>P: 200 awarded
  end

Monday freeze — pull, fund, claim, pay

sequenceDiagram
  participant Cron as Keeper
  participant DB as Freeze snapshot
  participant Pool as DistroPool
  participant V as Partner vaults
  participant M as External prize protocol
  participant Pay as Partner payout EOAs

  Cron->>DB: lock last week W
  Note over DB: backing $ = floor((W + remainder) / 10)
  Cron->>Pool: pull reserved from vaults
  Pool->>V: sweep reserved to pool
  Cron->>Pool: fund 1 dollar per 10 entries, pool is purchaser
  Pool->>M: purchase
  M-->>Pool: pool-held prize
  Note over Pool,M: wait until that week’s prize is claimable
  Cron->>Pool: claim
  M-->>Pool: net USDC
  DB->>DB: split net by paid weight
  Pool->>Pay: each partner share
  Note over Pay: partner pays users from CSV

Who can move what

Bucket	Who can move it
Vault `freeBalance`	Partner only (withdraw unused)
Vault `reserved`	Executor (reserve) · DistroPool (pull to itself) · Executor backup sweep
Pool-held prize	DistroPool (purchaser of record)
Claimed pot USDC	DistroPool → partner payout EOAs
Protocol referral ($0.10 per $1 of backing)	PrizeDistro referral EOA via `claimReferralFees`
User payouts	Partner, off-chain, from the CSV

Spec: docs/superpowers/specs/2026-08-20-distro-pool.md (GitHub). This page is also at public/flows.html — open the file, or /flows.html when the app is running.