296 lines
14 KiB
Markdown
296 lines
14 KiB
Markdown
# 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).
|