Files
sor/Client/context-files/scenes/bazaar.scene.md
T

214 lines
5.6 KiB
Markdown

# Bazaar Scene
## Status
Active draft.
## Goals
- Provide a trusted in-game economy hub.
- Support player-to-player card marketplace using Origin Points.
- Support first-party store purchases (booster packs, premade decks, Origin Points).
- Support card sacrifice/disenchant flow for Origin Points.
- Ensure full transaction auditability and chain of custody for anti-cheat and bug investigation.
## Bazaar Sections (UI)
### 1) Player Marketplace
- Search/browse listed cards.
- View listing details:
- card identity (definition + variant)
- seller
- price (Origin Points)
- listed-at timestamp
- listing status
- Actions:
- buy listing
- cancel own listing
- create listing from owned inventory
- Filters/sort:
- card name/type/rarity/affinity
- min/max price
- newest/price asc/price desc
### 2) Official Store
- Buy booster packs.
- Buy premade decks.
- Buy Origin Points (USD purchase flow).
- Payment method display + confirmation modal.
- Show SKU details and pricing in:
- USD (fiat)
- Origin Points (when applicable)
### 3) Sacrifice / Disenchant
- Select cards from owned inventory.
- Preview Origin Points return before confirm.
- Explicit irreversible warning.
- Confirm action flow:
- cards are removed from active inventory (or flagged destroyed server-side)
- Origin Points credited
### 4) Ledger / History (Player View)
- Personal transaction history timeline:
- marketplace buys/sells
- store purchases
- sacrifices
- refunds/reversals
- Receipt details with transaction id.
## Client Interactions
- Load Bazaar bootstrap on scene open.
- Keep balances (Origin Points) fresh after every economy mutation.
- Use optimistic UI sparingly for economy operations; server response is source of truth.
- Require explicit confirmation modals for:
- listing creation
- purchase
- sacrifice
- USD spend
- Show clear pending/success/failure states for every transaction.
## Server Rules and Authority
- Server is fully authoritative for inventory ownership, balances, listing state, and purchase validity.
- Marketplace transactions must be atomic (debit buyer, credit seller, transfer card ownership, write ledger).
- Sacrifice operation must be atomic (mark destroyed/remove ownership, grant points, write ledger).
- All purchases (USD and Origin Points) must write immutable audit records.
- Every item/asset transaction must maintain chain-of-custody links.
## Data Contracts (Draft)
### Client -> Server (`BazaarBootstrapRequest`)
- `requestId`
- `accountId`
### Server -> Client (`BazaarBootstrapResponse`)
- `requestId`
- `originPointsBalance`
- `marketplaceSummary`
- `storeCatalog` (boosters, premade decks, point packs)
- `sacrificeRules`
- `recentTransactions`
---
### Marketplace
#### Client -> Server (`MarketplaceSearchRequest`)
- `requestId`
- `filters`
- `sort`
- `page`
- `pageSize`
#### Server -> Client (`MarketplaceSearchResponse`)
- `requestId`
- `results`
- `totalCount`
#### Client -> Server (`MarketplaceCreateListingRequest`)
- `requestId`
- `cardInstanceId`
- `priceOriginPoints`
#### Server -> Client (`MarketplaceCreateListingResponse`)
- `requestId`
- `success`
- `listingId`
- `errorCode` (if failed)
#### Client -> Server (`MarketplaceBuyListingRequest`)
- `requestId`
- `listingId`
#### Server -> Client (`MarketplaceBuyListingResponse`)
- `requestId`
- `success`
- `transactionId`
- `updatedBalance`
- `errorCode` (if failed)
#### Client -> Server (`MarketplaceCancelListingRequest`)
- `requestId`
- `listingId`
#### Server -> Client (`MarketplaceCancelListingResponse`)
- `requestId`
- `success`
- `errorCode` (if failed)
---
### Store Purchases
#### Client -> Server (`StorePurchaseRequest`)
- `requestId`
- `skuId`
- `currency` (`USD` | `ORIGIN_POINTS`)
- `paymentMethodId` (required for USD)
#### Server -> Client (`StorePurchaseResponse`)
- `requestId`
- `success`
- `transactionId`
- `receiptId`
- `updatedBalance`
- `grantedItems`
- `errorCode` (if failed)
---
### Sacrifice / Disenchant
#### Client -> Server (`SacrificeCardsRequest`)
- `requestId`
- `cardInstanceIds`
- `confirmIrreversible` (`true` required)
#### Server -> Client (`SacrificeCardsResponse`)
- `requestId`
- `success`
- `transactionId`
- `originPointsGranted`
- `updatedBalance`
- `destroyedCardRefs`
- `errorCode` (if failed)
---
### Ledger / Audit
#### Client -> Server (`TransactionHistoryRequest`)
- `requestId`
- `filters`
- `page`
- `pageSize`
#### Server -> Client (`TransactionHistoryResponse`)
- `requestId`
- `entries`
- `totalCount`
## Audit / Chain of Custody Requirements (Critical)
- Every economy event writes an immutable ledger entry with:
- `transactionId`
- `eventType`
- `accountId`(s) involved
- asset references (`cardInstanceId`, `skuId`, etc.)
- balance deltas (before/after)
- timestamp + request correlation (`requestId`)
- Every card instance should have a custody trail:
- minted/acquired -> listed -> sold/transferred -> sacrificed/destroyed
- USD purchases must include payment provider reference id(s) and receipt linkage.
- Support admin/internal investigation queries for suspicious activity patterns.
## Fraud / Abuse Signals (Planned)
- Repeated rapid buy/sell loops between same accounts.
- Outlier pricing patterns.
- High-frequency sacrifices after suspicious acquisitions.
- Chargeback/refund correlation with asset transfers.
- Multi-account linkage risk indicators.
## Open Questions
1. Should marketplace fees/taxes apply on player sales?
2. Are there listing limits per user or per card rarity?
3. Is there a hold/escrow period before purchased cards can be relisted?
4. What refund policy exists for Origin Points and digital goods?
5. Should sacrifice values be static or dynamic by card metadata?