From 30b8dc6de21c4e6adc72d92069d64d40a3ddb5ed Mon Sep 17 00:00:00 2001 From: planner-bot Date: Tue, 18 Aug 2026 15:12:46 +0000 Subject: [PATCH] =?UTF-8?q?WIP=20checkpoint:=20Plan:=20Economy=20=E2=80=94?= =?UTF-8?q?=20Currency,=20Marketplace=20&=20Creator=20Payouts?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/planning/economy.md | 295 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 295 insertions(+) create mode 100644 docs/planning/economy.md diff --git a/docs/planning/economy.md b/docs/planning/economy.md new file mode 100644 index 0000000..8a6f05a --- /dev/null +++ b/docs/planning/economy.md @@ -0,0 +1,295 @@ +# Economy — Currency, Marketplace & Creator Payouts — Plan + +> **Status:** Planned +> **Owner:** Platform team +> **Feature ID:** `economy` +> **Godot version:** 4.6.2 stable +> **Backend:** FastAPI + SQLAlchemy (async) + PostgreSQL + Redis + +## 1. Overview + +This document breaks the **Economy** feature into user stories and right-sized +implementation tasks. The feature delivers: + +- **Virtual currency ("Credits")** — a single, server-authoritative currency + with an immutable, append-only transaction ledger. +- **Premium purchase** — buying Credits with real money through a pluggable + payment-provider hook. +- **Marketplace** — user-generated content (UGC) listings where creators sell + items (assets, avatar items, experience passes) to players for Credits. +- **Creator payouts** — accumulating creator earnings and paying them out to + external accounts through a pluggable payout-provider hook. +- **Godot client** — wallet/transaction history, marketplace browse/buy/sell, + and creator payout screens. + +The economy is the monetization backbone of the platform. Because it moves +virtual value between real people, correctness (no double-spend, no lost funds, +no balance drift) and safety (fraud prevention, moderation, audit) are treated +as **blocking requirements**, not add-ons. + +## 2. Why correctness is the differentiator + +The platform is a creator economy (players buy UGC from other players). The +economy is the highest-risk surface after chat: a single arithmetic or +concurrency bug can mint or destroy value and irreversibly erode trust. +Correctness is therefore designed in from the start: + +- **One currency, integer units.** Credits are whole-number integers. There are + no floats, no rounding, and no client-computed totals. +- **Append-only ledger.** Every balance change is a row in a `transactions` + table with a signed amount, a `balance_after` snapshot, a reference to the + event that caused it, and an **idempotency key** so retries cannot double + credit or double debit. +- **Atomic, locked mutations.** Balance changes run in a single database + transaction with row locking (`SELECT ... FOR UPDATE`) so concurrent + purchases/payouts cannot race. +- **Escrow hold.** Marketplace proceeds are held in `pending_escrow` for a + configurable window before becoming available to the seller, so fraudulent + or moderated sales can be reversed without clawing back paid-out funds. +- **Server-authoritative fees.** The platform commission is computed + server-side from a configured rate; the client never supplies the fee or the + seller's net. + +## 3. Existing constraints (do not re-build) + +- **Auth:** JWT bearer tokens; `get_current_user` / `CurrentUser` dependency in + `app/dependencies.py`. All economy endpoints reuse this. +- **DB:** async SQLAlchemy + Alembic; migration `0001_initial` is the head. + Existing tables: `users`, `sessions`, `worlds`, `assets`. +- **Redis:** configured (`REDIS_URL`) but unused so far; adopted here for + idempotency short-caching and rate limiting. +- **Models:** `User` (owner_id), `Asset` (owner_id, is_public, asset_type). + Marketplace items reference existing `assets` rows and/or avatar items. +- **Content moderation:** `docs/architecture/content_moderation.md` defines + flag vocabulary, age gate, and moderation actions. Marketplace items and + listings must inherit and enforce these rules (see §7). +- **Client:** Godot 4.6.2, minimal `main_menu.gd`; no economy UI yet. + +## 4. Key design decisions + +| Concern | Decision | +|---|---| +| Currency model | Single virtual currency **"Credits" (CR)**, integer units. One wallet row per user; no fractional amounts. | +| Ledger | Append-only `transactions` table: signed `amount`, `balance_after`, `reference_type`/`reference_id`, unique `idempotency_key`. | +| Concurrency | `SELECT ... FOR UPDATE` on the wallet row inside the mutation transaction; never read-modify-write from stale data. | +| Payments | Pluggable `PaymentProvider` interface with a **no-op default** that simulates a confirmed payment for dev/testing (clearly flagged). Stripe/PayPal later. | +| Marketplace items | `catalog_items` (what is sold) + `marketplace_listings` (a seller's offer with a price/status). One item can have multiple listings over time. | +| Purchase flow | Atomic transaction: debit buyer → hold funds in escrow (`pending_escrow`) → grant item. Platform fee computed server-side. | +| Escrow | Configurable hold window (default 72h) before `pending_escrow` becomes available seller earnings. Refunds during the window reverse the sale. | +| Fees | Single configurable `MARKETPLACE_FEE_RATE` (default `0.30`). `seller_net = floor(price * (1 - fee_rate))`. | +| Creator balance | `creator_balances` table: `available` (earned, payable), `pending` (inside an open payout request), `lifetime_earned`. Updated in the same transaction as the sale completion. | +| Payouts | Pluggable `PayoutProvider.pay()` with a no-op default (simulated external ref). Minimum payout threshold, admin review for large payouts. | +| Idempotency | Every money-moving request carries a client-generated `Idempotency-Key`; duplicate keys return the original result. | +| Rate limiting | Redis token-bucket dependency reused from the social feature for purchase/listing/payout endpoints. | +| Moderation | Listings enforce content flags + age gate; moderators can `delist`/`remove`; fraud/chargeback reversal is an audited admin action. | + +## 5. User stories + +### US-1 Currency & wallet +As a player, I can see my Credit balance and transaction history, and the system +credits/debits my wallet only through server-authoritative events. + +**Acceptance criteria** +- Exactly one wallet per user, created lazily on first use. +- Balance is always a non-negative integer; no operation can make it negative. +- Every mutation appends an immutable ledger row with amount, resulting balance, + reference, and idempotency key. +- Retrying a request with the same idempotency key does not double-apply. +- `GET` endpoints expose current balance and paged transaction history. + +### US-2 Premium purchase (buy Credits) +As a player, I can purchase Credits with real money and have them credited only +after the payment is confirmed. + +**Acceptance criteria** +- A purchase session is created through the payment provider (or the no-op + default) and is idempotent. +- Credits are granted exactly once, only after a verified provider confirmation + (webhook/confirm endpoint), never on client claim. +- Purchase amounts are bounded and server-defined; clients cannot pick arbitrary + prices. +- Confirmation is idempotent and audited (provider reference recorded). + +### US-3 Marketplace listing (sell) +As a creator, I can list a catalog item for sale at a Credit price and +manage/remove my listings. + +**Acceptance criteria** +- A listing references a valid `catalog_item` owned by the seller (or an + authorized seller). +- Price is bounded (min/max) and set server-side; status transitions are + explicit (`active`, `sold`, `delisted`, `removed_by_moderation`). +- Only the seller (or a moderator) can update/remove a listing. +- Listings are searchable/filterable (item type, price range, owner). + +### US-4 Marketplace purchase (buy) +As a player, I can buy a listed item. The purchase is atomic, holds funds in +escrow, grants the item, and splits the payment between platform and seller. + +**Acceptance criteria** +- A single transaction debits the buyer, holds funds in escrow, and grants the + item — no partial states on failure. +- Platform fee and seller net are computed server-side from the configured rate. +- After the escrow hold window, funds move from escrow to the seller's + available balance. +- Refunds during the hold window reverse the sale and return funds to the buyer. +- Concurrent purchases of a one-of-a-kind listing cannot both succeed. + +### US-5 Creator payouts +As a creator, I can view my earned balance, request a payout, and track its +status; admins can review and approve/reject payouts. + +**Acceptance criteria** +- Available balance is derived only from completed (escrow-released) sales and + completed payouts; it never goes negative. +- Payout requests are bounded (min threshold, max per period) and rate-limited. +- Large payouts require admin review; all payout requests carry an audit trail + (requested by, reviewed by, provider reference, status). +- The payout provider is called exactly once; idempotent on retry. + +### US-6 Godot client +As a player, I can manage Credits, browse/buy/sell marketplace items, and manage +payouts from the game UI. + +**Acceptance criteria** +- An API client handles JWT auth, HTTP, and idempotency keys for all economy + calls. +- Dedicated screens: wallet + transaction history, marketplace browse/buy, + sell-listing, and creator payout. +- The client never computes balances, fees, or seller nets — it only displays + server responses. + +## 6. Task breakdown + +Right-sized to 1–3 files / one coherent piece of functionality each. Task IDs +are sequential for dependency chaining. + +| # | Task | Story | Depends on | +|---|------|-------|-----------| +| 1 | Wallet & ledger models + Alembic migration (`wallets`, `transactions`) | US-1 | — | +| 2 | Wallet service (atomic credit/debit, idempotency, locking) + wallet/transactions API | US-1 | 1 | +| 3 | Premium purchase: `PaymentProvider` interface + purchase/confirm endpoints | US-2 | 1 | +| 4 | Catalog item & listing models + migration (`catalog_items`, `marketplace_listings`, `creator_balances`) | US-3 | 1 | +| 5 | Marketplace listing API (create/list/search/update/remove) | US-3 | 4 | +| 6 | Marketplace purchase service + API (atomic escrow, fee split, item grant) | US-4 | 2, 4, 5 | +| 7 | Creator payout request models + API (`payout_requests`) | US-5 | 2, 6 | +| 8 | Payout admin review + `PayoutProvider` + audit | US-5 | 7 | +| 9 | Marketplace moderation + content-flag/age-gate enforcement | cross-cutting | 5, 6 | +| 10 | Godot economy API client (auth + HTTP + idempotency) | US-6 | 2 | +| 11 | Godot wallet & transaction history UI | US-6 | 10 | +| 12 | Godot marketplace browse/buy UI | US-6 | 6, 10 | +| 13 | Godot selling & payout UI | US-6 | 5, 7, 10 | + +## 7. Phasing + +- **Phase 1 (currency + payments):** tasks 1–3. The foundation — ledger and + money movement must be rock-solid before anything spends Credits. +- **Phase 2 (marketplace):** tasks 4–6. Listing and atomic purchase with escrow. +- **Phase 3 (payouts):** tasks 7–8. Turn released escrow into creator payouts. +- **Phase 4 (moderation):** task 9. Lock down the marketplace against mature + content and abuse. +- **Phase 5 (client):** tasks 10–13, each landing after its backend dependency. + +## 8. Data model sketch + +```text +wallets + id bigint PK + user_id int UNIQUE FK -> users.id + balance bigint NOT NULL DEFAULT 0 CHECK (balance >= 0) + created_at timestamptz + updated_at timestamptz + +transactions (append-only ledger) + id bigint PK + wallet_id bigint FK -> wallets.id + type enum(credit_purchase, marketplace_purchase, + marketplace_sale, escrow_release, payout, + refund, admin_adjustment) + amount bigint NOT NULL (signed) + balance_after bigint NOT NULL + reference_type text (e.g. "purchase", "sale", "payout_request") + reference_id text + idempotency_key text UNIQUE + metadata_json jsonb + created_at timestamptz + +catalog_items + id bigint PK + owner_id int FK -> users.id + asset_id int FK -> assets.id (nullable; null for non-asset virtual items) + item_type enum(asset, avatar_item, experience_pass) + name text + description text + metadata_json jsonb + created_at timestamptz + +marketplace_listings + id bigint PK + catalog_item_id bigint FK -> catalog_items.id + seller_id int FK -> users.id + price bigint NOT NULL CHECK (price > 0) + status enum(active, sold, delisted, removed_by_moderation) + created_at timestamptz + updated_at timestamptz + +purchases + id bigint PK + listing_id bigint FK -> marketplace_listings.id + buyer_id int FK -> users.id + seller_id int FK -> users.id + price bigint NOT NULL + platform_fee bigint NOT NULL + seller_net bigint NOT NULL + status enum(pending_escrow, completed, refunded, reversed) + escrow_hold_until timestamptz + created_at timestamptz + +creator_balances + id bigint PK + user_id int UNIQUE FK -> users.id + available bigint NOT NULL DEFAULT 0 + pending bigint NOT NULL DEFAULT 0 + lifetime_earned bigint NOT NULL DEFAULT 0 + updated_at timestamptz + +payout_requests + id bigint PK + creator_id int FK -> users.id + amount bigint NOT NULL CHECK (amount > 0) + status enum(pending, approved, paid, rejected) + external_ref text + provider_ref text + requested_by int FK -> users.id + reviewed_by int FK -> users.id (nullable) + reviewed_at timestamptz + created_at timestamptz +``` + +## 9. Security, anti-fraud & audit + +- **Server-authoritative balances/fees:** clients never compute totals; amounts + are validated server-side against bounds and the current listing. +- **Row locking:** wallet and creator-balance mutations use `SELECT ... FOR + UPDATE` within one transaction. +- **Idempotency:** every money-moving endpoint requires an `Idempotency-Key`; + duplicate keys return the stored original outcome. +- **Rate limiting:** purchase, listing, and payout endpoints are token-bucket + rate-limited per user. +- **Escrow & reversibility:** funds are not payable until the hold window + elapses; chargebacks/refunds reverse before release. +- **Moderation:** listings carry the item's effective content flags; mature + items require age verification (per `content_moderation.md`); moderators can + `delist`/`remove` and trigger audited reversals. +- **Audit:** the ledger plus `payout_requests` review fields form an append-only + audit trail for every movement of value. + +## 10. Out of scope for this feature + +- Real Stripe/PayPal/KYC integrations (provider interfaces leave the hooks; the + defaults are deterministic no-ops). +- Subscriptions, recurring billing, or premium memberships. +- Gift cards, promotional codes, or user-to-user Credit transfers. +- Partial refunds, chargeback disputes, and seller tax/VAT handling. +- In-world vending machines / scripted economy triggers (future, built on this + ledger via the scripting sandbox). -- 2.52.0