docs: correct the USDF / launchpad-currency model

claude · claude · commit 7f654c5ee0bc · 2026-06-22T00:16:23.000Z
USDF is the base reserve currency ("core mint"); launchpad currencies are the user-facing tradable tokens backed by USDF reserves (like memecoins backed by USDC). The docs previously framed them as parallel holdings, understating the backing relationship. - 06: add a "Currency model" section — USDF (MintMetadata with launchpadMetadata = null) vs launchpad currencies (non-null LaunchpadMetadata: liquidityPool, coreMintVault USDF backing, price/marketCap in USDF, sellFeeBps), on-chain bonding-curve price discovery, buy/sell against USDF via SwapPurpose, and the two distinct senses of "reserves" (pool backing vs the user's USDF balance). Adds a reserve/pool/token Mermaid diagram. - glossary: rewrite USDF, launchpad token, and swap; add core mint, bonding curve, liquidity pool/coreMintVault, reserves, MintMetadata/Token. - README: reframe the overview around USDF-as-reserve / launchpad-as-circulating. - features: align cash, tokens (buy/sell vs USDF), and currency-creator rows. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01JRVfsXp4HDrDMy7Pbmw9fD
diff --git a/docs/architecture/06-payments-and-operations.md b/docs/architecture/06-payments-and-operations.md
@@ -1,8 +1,9 @@
 # 06 — Payments & operations
 
 Flipcash is **self-custodial**: the device holds the keys, derives Solana accounts,
-and signs every transaction locally. This document covers key management, the
-account model, the auth-state machine, and how a payment is actually submitted.
+and signs every transaction locally. This document covers the currency model, key
+management, the account model, the auth-state machine, and how a payment is actually
+submitted.
 
 ```mermaid
 graph TD
@@ -18,6 +19,80 @@ graph TD
     User --> TxController --> Stream --> Backend
 ```
 
+## Currency model: USDF & launchpad currencies
+
+Flipcash has **two kinds of currency**, and the relationship between them is the
+heart of the product:
+
+- **USDF** is the **base / reserve currency** — a USD-pegged stablecoin. In code it
+  is the *"core mint"*: `Mint.usdf`
+  ([`libs/encryption/keys/.../Mint.kt`](../../libs/encryption/keys/src/main/kotlin/com/getcode/solana/keys/Mint.kt)),
+  modeled as a `MintMetadata` (alias `Token`) with **`launchpadMetadata = null`**.
+- **Launchpad currencies** are the **user-facing, tradable tokens** — the unit people
+  actually create, buy, sell, and share. Each is a custom on-chain currency **backed
+  by USDF reserves**.
+
+> **Mental model:** launchpad currencies are to USDF what memecoins are to USDC on
+> Solana. USDF is the reserve everything is priced in and backed by; launchpad
+> currencies are what circulates socially.
+
+A launchpad currency is a `MintMetadata` whose `launchpadMetadata` is **non-null**
+([`services/opencode/.../model/financial/MintMetadata.kt`](../../services/opencode/src/main/kotlin/com/getcode/opencode/model/financial/MintMetadata.kt)).
+`LaunchpadMetadata` describes the backing and pricing:
+
+| Field | Meaning |
+|-------|---------|
+| `liquidityPool` | The on-chain bonding-curve pool. |
+| `mintVault` | Where the launchpad token itself is locked against the pool. |
+| `coreMintVault` | **Where USDF is locked against the pool — the on-chain backing/reserves.** |
+| `currentCirculatingSupplyQuarks` | Circulating supply; drives price via the curve. |
+| `price`, `marketCap` | Both denominated in **USDF** (`Fiat`). |
+| `sellFeeBps` | Sell fee in basis points (currently 1%). |
+
+```mermaid
+graph LR
+    User["User USDF balance<br/>(spendable reserve)"]
+    Pool["Liquidity pool (bonding curve)"]
+    Core["coreMintVault<br/>(USDF backing)"]
+    MintV["mintVault<br/>(launchpad token)"]
+    Token["Launchpad currency<br/>price = f(supply) in USDF"]
+
+    User -->|buy: USDF in| Pool
+    Pool -->|tokens out| Token
+    Token -->|sell: tokens in, −1% fee| Pool
+    Pool -->|USDF out| User
+    Pool --- Core
+    Pool --- MintV
+```
+
+**Price discovery is deterministic and on-chain.** `price = f(currentSupply)` is
+computed by a discrete bonding curve
+([`libs/currency-math/.../curves/DiscreteBondingCurve.kt`](../../libs/currency-math/src/main/kotlin/com/flipcash/libs/currency/math/internal/curves/DiscreteBondingCurve.kt));
+supply updates stream in via `LaunchpadReserveStateSnapshot` and `TokenCoordinator`,
+which recomputes balances and appreciation as the price moves. (This is separate
+from the **fiat** display rates in [04 — Networking](04-networking.md), which convert
+USDF to the user's local currency for display.)
+
+**Buying and selling always goes through USDF.** `SwapPurpose`
+([`apps/flipcash/core/.../tokens/TokenSwapPurpose.kt`](../../apps/flipcash/core/src/main/kotlin/com/flipcash/app/core/tokens/TokenSwapPurpose.kt))
+is either `Buy(mint, fundingSource)` or `Sell(mint)`, and the swap's counter-currency
+is `Mint.usdf`: a buy spends USDF to mint tokens (adding USDF to the pool's
+`coreMintVault`), a sell burns tokens for USDF (returning USDF, minus the 1% fee).
+Creating a currency (`CurrencyCreatorViewModel`) seeds an **initial USDF buy**
+(default ~$5, from a user flag) and hands the creator a cash bill of the new token.
+
+**Sending/sharing carries any token.** A cash bill (`Bill.Cash`) holds whichever
+`Token` is selected — a launchpad currency *or* USDF. Launchpad currencies render as
+a custom bill (`renderAsBill = token.address != Mint.usdf`); USDF renders as plain
+cash.
+
+> **Two senses of "reserves" — don't conflate them.** (1) The on-chain USDF locked in
+> a launchpad token's `coreMintVault` is the token's **backing**. (2)
+> `ReservesBalanceProvider.observeReservesBalance()` →
+> `balanceForToken(Mint.usdf)` is the **user's own USDF balance**, i.e. the spendable
+> reserve they buy launchpad currencies with. Both are USDF, but one is pool-side
+> backing and the other is the user's wallet balance.
+
 ## Keys & cryptography
 
 The crypto primitives live under `libs/encryption/*`:
diff --git a/docs/architecture/README.md b/docs/architecture/README.md
@@ -14,12 +14,16 @@ architectural concern; start here, then jump to the topic you need.
 ## What Flipcash is
 
 Flipcash is a **self-custodial mobile wallet** for instant, global, private
-payments. Users hold **USDF** (a USD stablecoin) and **launchpad tokens** (custom
-on-chain currencies). The signature interaction is a **device-to-device cash
-bill**: one phone renders an animated circular Kik Code on screen, another phone
-scans it, and a peer-to-peer handshake settles the payment. The app also supports
-contact/username sends, on-ramp funding (Coinbase, in-app purchase), token swaps,
-and on-chain withdrawals.
+payments. Its base reserve currency is **USDF** (a USD stablecoin); on top of it,
+users create, buy, sell, and share **launchpad currencies** — custom on-chain tokens
+**backed by USDF reserves** (think memecoins backed by USDC on Solana). Launchpad
+currencies are the unit that circulates socially; USDF is what they're priced in and
+redeemable for. The signature interaction is a **device-to-device cash bill** (which
+can carry a launchpad currency or USDF): one phone renders an animated circular Kik
+Code on screen, another phone scans it, and a peer-to-peer handshake settles the
+payment. The app also supports contact/username sends, on-ramp funding (Coinbase,
+in-app purchase), buying/selling launchpad currencies against USDF, and on-chain
+withdrawals.
 
 Under the hood it talks to **two gRPC backends** — the Flipcash service
 (accounts, profiles, chat, activity) and the Open Code Protocol / OCP service
diff --git a/docs/architecture/features/README.md b/docs/architecture/features/README.md
@@ -32,7 +32,7 @@ Two recurring shapes show up in the **Pattern** column:
 
 | Feature | Purpose | Screen / ViewModel | Pattern & integration |
 |---------|---------|--------------------|-----------------------|
-| **cash** | Amount entry for a device-to-device cash bill | `cash/CashScreen.kt` · `…/internal/CashScreenViewModel` | **VM-driven**; combines token + balance + rate flows, emits `PresentBill`, calls `SessionController.showBill` |
+| **cash** | Amount entry for a device-to-device cash bill (sends the selected token — a launchpad currency or USDF) | `cash/CashScreen.kt` · `…/internal/CashScreenViewModel` | **VM-driven**; combines token + balance + rate flows, emits `PresentBill`, calls `SessionController.showBill` |
 | **scanner** | Camera capture of a peer's cash bill / QR | `scanner/ScannerScreen.kt` | Screen-local; uses `:ui:scanner`, routes scans through `Router.classify` |
 | **direct-send** | Send to a contact / phone number | `directsend/SendFlowScreen.kt` · `…/internal/SendFlowViewModel` | **Flow**; contact list + phone gate steps |
 | **withdrawal** | Withdraw funds on-chain | `withdrawal/WithdrawalFlowScreen.kt` · `withdrawal/WithdrawalViewModel` | **Flow** (`AppRoute.Transfers.Withdrawal`); entry → destination → confirmation |
@@ -44,8 +44,8 @@ Two recurring shapes show up in the **Pattern** column:
 | Feature | Purpose | Screen / ViewModel | Pattern & integration |
 |---------|---------|--------------------|-----------------------|
 | **balance** | Wallet balance across tokens | `balance/BalanceScreen.kt` · `…/internal/BalanceViewModel` | **VM-driven**; observes token balances + exchange rates |
-| **tokens** | Token info, selection, and swaps | `tokens/TokenInfoScreen.kt`, `tokens/SwapFlowScreen.kt`, `tokens/TokenSelectScreen.kt` | **Flow** for swap (`FlowRouteWithResult<SwapResult>`); screen-local for info/selection |
-| **currency-creator** | Create a launchpad currency | `currencycreator/CurrencyCreatorFlowScreen.kt` · `…/internal/CurrencyCreatorViewModel` | **Flow**; name → icon → info → processing steps |
+| **tokens** | Token info (price/market cap in USDF), selection, and buy/sell swaps against USDF | `tokens/TokenInfoScreen.kt`, `tokens/SwapFlowScreen.kt`, `tokens/TokenSelectScreen.kt` | **Flow** for swap (`FlowRouteWithResult<SwapResult>`, `SwapPurpose.Buy`/`Sell`); screen-local for info/selection |
+| **currency-creator** | Create a launchpad currency (USDF-backed), seeded by an initial USDF buy | `currencycreator/CurrencyCreatorFlowScreen.kt` · `…/internal/CurrencyCreatorViewModel` | **Flow**; name → icon → info → processing steps |
 
 ## D. Profile, settings & misc
 
diff --git a/docs/architecture/glossary.md b/docs/architecture/glossary.md
@@ -8,12 +8,16 @@ full story.
 
 | Term | Meaning | See |
 |------|---------|-----|
-| **USDF** | The USD-pegged stablecoin users primarily hold and transact in. | [README](README.md) |
-| **Launchpad token / currency** | A custom on-chain currency (governed by an on-chain bonding curve) that users can create and trade, in addition to USDF. | [06](06-payments-and-operations.md) |
-| **Cash bill** | The animated, circular on-screen code that represents a payment for **device-to-device** transfer — one phone shows it, another scans it. | [README](README.md), [features](features/README.md) |
+| **USDF** | The USD-pegged **base / reserve** stablecoin (the "core mint"). Everything is priced in and backed by USDF; it is itself sendable. In code: a `Token` with `launchpadMetadata = null`. | [06](06-payments-and-operations.md) |
+| **Launchpad token / currency** | The user-facing, tradable currency people **create, buy, sell, and share** — a custom on-chain token **backed by USDF reserves** and priced by an on-chain bonding curve. Like a memecoin backed by USDC. | [06](06-payments-and-operations.md) |
+| **Core mint** | The codebase's name for USDF — the reserve currency that launchpad currencies are denominated in and backed by. | [06](06-payments-and-operations.md) |
+| **Bonding curve** | The on-chain formula that sets a launchpad currency's price from its circulating supply (`price = f(supply)`, in USDF). | [06](06-payments-and-operations.md) |
+| **Liquidity pool / `coreMintVault`** | A launchpad currency's bonding-curve pool; its `coreMintVault` holds the **USDF reserves** backing the token (vs `mintVault`, which holds the token). | [06](06-payments-and-operations.md) |
+| **Reserves** | Two senses: (1) on-chain USDF backing a token in its `coreMintVault`; (2) the **user's own USDF balance** (`observeReservesBalance()`) spent to buy launchpad currencies. | [06](06-payments-and-operations.md) |
+| **Cash bill** | The animated, circular on-screen code that represents a payment for **device-to-device** transfer — one phone shows it, another scans it. Carries any token (a launchpad currency or USDF). | [README](README.md), [features](features/README.md) |
 | **Kik Code** | The scannable code format rendered as a cash bill (captured via the camera scanner). | [07](07-design-system.md) |
 | **On-ramp** | Funding the wallet with fiat (Coinbase) or in-app purchase. | [04](04-networking.md), [06](06-payments-and-operations.md) |
-| **Swap** | Exchanging one token for another (e.g. via a launchpad currency's curve). | [03](03-navigation.md), [06](06-payments-and-operations.md) |
+| **Swap** | Buying or selling a launchpad currency **against USDF** (`SwapPurpose.Buy`/`Sell`); sells charge a ~1% fee. | [03](03-navigation.md), [06](06-payments-and-operations.md) |
 | **Withdrawal** | Moving funds on-chain to an external Solana address. | [features](features/README.md) |
 
 ## Identity, keys & accounts
@@ -40,7 +44,8 @@ full story.
 | **OCP / Open Code Protocol** | The gRPC backend for transactions, intents, swaps, and exchange rates (module `:services:opencode`). | [04](04-networking.md) |
 | **Flipcash service** | The gRPC backend for accounts, profiles, chat, and activity (module `:services:flipcash`). | [04](04-networking.md) |
 | **Intent** | A signed unit of money movement (transfer, remote send/receive, withdraw, swap, distribution) submitted over the `SubmitIntent` bidirectional stream. | [04](04-networking.md), [06](06-payments-and-operations.md) |
-| **Mint** | A Solana token mint address (`PublicKey` subtype); identifies a token such as USDF or a launchpad currency. | [06](06-payments-and-operations.md) |
+| **Mint** | A Solana token mint address (`PublicKey` subtype); identifies a token such as USDF (`Mint.usdf`) or a launchpad currency. | [06](06-payments-and-operations.md) |
+| **MintMetadata / Token** | The model for any currency (`MintMetadata`, aliased `Token`). A non-null `launchpadMetadata` makes it a launchpad currency; `null` means it's USDF (the core mint). | [06](06-payments-and-operations.md) |
 | **Protobuf / proto** | The Protocol Buffers contract; generated code lives in `:definitions:*:models` and is never hand-edited. | [13](13-protobuf-and-codegen.md) |
 | **NotifiableError** | Marker for errors that represent bugs (not user-caused) and should alert via Bugsnag/Slack. | [14](14-error-handling.md) |
 
