Prediction Markets, Pawn-Coin settlement, ledger, and schema guards

Overview#

This article documents the current Prediction Markets finance and operations layer on top of the Pawn-Coin economy.

It reflects the active runtime, including canonical market resolution, settlement and claim traces, cost-basis aware positions, amount-first Quick Buy, and the fallback MarketPawns house-quote path used when live asks are missing.

Why this article exists#

The trading schema was already present earlier, but the platform now exposes a fuller post-trade and operator surface:

positions store cost basis and realized PnL instead of raw shares only
markets carry canonical resolution metadata
settlements and claims create an explicit audit trail
backed forecasts keep payout and refund outcomes in the same economy
Quick Buy can stay available through control-managed fallback quotes

Canonical lifecycle#

Order creation: the service reserves either cash or shares, including proportional sell-side cost basis when needed.
Trade execution: fills update positions, reserve balances, and trade history.
Resolution: the market row receives a canonical final outcome and metadata that explains the source of the decision.
Settlement: winning payouts, losing closures, or cancel/excluded refunds are written into dedicated settlement rows.
Claim trace: the final wallet movement is linked to a claim-style record so PM history and Pawn-Coin ledger history tell the same story.

Core data model#

Orders and reserves#

mp_pm_orders tracks live order intent and reserve state.

locked_cash is used for buy-side cash reservation
locked_shares is used for sell-side reserved exposure
locked_cost_basis keeps proportional cost basis attached to reserved sell shares so cancel and partial-fill flows can restore accounting correctly

Positions and cost basis#

mp_pm_positions is no longer just an exposure table.

shares stores the current YES or NO exposure
avg_entry_price stores average entry cost per share
gross_cost stores total cost basis still attached to the open position
realized_pnl stores PnL already crystallized by sells
claimable_amount, claimed_amount, and settlement_status expose post-resolution state to UI and audits

This is why the product can accept an amount-first Quick Buy input while still preserving share-based finance semantics internally.

Resolution, settlement, and claims#

mp_pm_markets stores resolution_status, resolved_outcome, resolved_at, and related resolution metadata
mp_pm_market_resolutions keeps immutable resolution history
mp_pm_settlements stores payout, refund, and net finance rows derived from the final outcome
mp_pm_claims records the final claim-style wallet linkage for user-facing auditability

Forecast bridge#

mp_backed_forecasts remains the durable bridge between simplified forecast UX and Prediction Markets execution.

It stores the original stake amount together with the translated PM price and quantity, plus resolved outcome, payout amount, refund amount, and claim status.

Amount-first Quick Buy#

The current Quick Buy flow is intentionally amount-first for users, while the engine stays share-based internally.

the user enters spend amount
the service estimates average execution price
the engine derives share quantity from amount / price
settlement still pays per winning share rather than per original stake amount

This keeps the UI close to consumer PM products without sacrificing accounting correctness for sells, partial fills, refunds, and audit.

Quick Buy state and house quote path#

Quick Buy no longer depends only on one live orderbook path.

The service can now build a state from multiple layers:

preferred live market for the selected model and market key
fallback market selection using control priorities
MarketPawns house quote when live asks are unavailable or too thin
featured event fallback when no model is selected

The main supporting table is mp_pm_quickbuy_configs, which stores:

quick_buy_enabled and quick_buy_priority
fallback_enabled
default_yes_probability and probability_source
house_quote_enabled and house_spread
min_amount and max_amount
featured_if_no_model

Control users manage these values through the Prediction Markets control page, including tooltip-backed explanations for each operator column.

API and UI surface#

The main PM surface now spans both classic order-book trading and Quick Buy.

pm_markets and pm_wallet expose market and wallet state
pm_place_order remains the advanced or manual order path
pm_quick_buy_state exposes selected market, quote source, and operator-driven fallback decisions
pm_quick_buy_preview returns amount-based preview data
pm_quick_buy_execute submits the amount-first flow, including the house-quoted path when applicable

UI badges such as Live Market, MarketPawns Quote, Hybrid Quote, and Paused are derived from this state rather than from a single hardcoded orderbook assumption.

Schema safety layers#

The deterministic SQL source of truth is still the migration file:

starter/database/migration_005_prediction_markets_pawncoin_settlement.sql

Runtime safety remains layered:

ensureColumnExists and ensureIndexExists in PmService.php help legacy environments catch up safely
starter/apply_prediction_markets_pawncoin_settlement_migration.php provides controlled browser or CLI rollout
starter/audit_pawn_coin_prediction_markets_schema.php provides read-only schema verification

Minimum operational checklist#

place a buy and verify reserve balances and trade history
sell part of the position and confirm cost basis moves proportionally
cancel a reserved sell and verify cost basis is restored to the position
resolve a market to YES or NO and confirm settlement plus wallet history alignment
exercise a cancel or excluded path and verify refund uses real cost basis rather than a flat heuristic
test Quick Buy in both live-orderbook and house-quote modes
review control values for fallback priority, probability anchor, spread, and amount limits