# 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).