Mpawns Coin: architecture of the player economy

Overview#

Mpawns Coin is the internal player-economy layer that connects wallet balances, community rewards, Influence Score, and Prediction Markets.

This architecture article reflects the current runtime rather than the original MVP sketch. The important point is that the platform now uses one readable economy with shared wallet history instead of separate reward and market balances that users cannot reconcile.

Core principle#

One business event should have one finance explanation.

community participation creates reward events
reward events write wallet and ledger rows
Prediction Markets reserve, settle, refund, and claim through the same economy surface
the user-facing wallet history is expected to explain both reward flow and market flow

Main bounded contexts#

Economy config: config/pawn_coin_economy.php plus optional JSON overrides define starter wallet, reward amounts, influence tiers, wallet progression, ledger labels, and anti-abuse limits.
Wallet and rewards: private/pawn_coin/PawnCoinService.php handles wallet bootstrap, reward credits, ledger writes, reward summaries, and recent wallet activity.
Community signals: private/community_pool calculates prediction result and Influence Score, then synchronizes reward state.
Idea Box rewards: ibox/config.php applies publication rewards through shared Pawn-Coin rules and anti-abuse checks.
Prediction Markets: private/prediction_markets/PmService.php handles order book, positions, settlements, claims, and amount-first Quick Buy on top of the same wallet layer.
User UI: resources/react/init.jsx and related PM widgets expose wallet, history, multiplier visibility, and PM finance traces.

Canonical data surface#

mp_pawn_wallets for current balances
mp_pawn_grants for one-time wallet bootstrap facts
mp_pawn_ledger for human-readable finance trace
mp_pawn_reward_events for idempotent reward bookkeeping
mp_pm_markets, mp_pm_orders, mp_pm_positions, mp_pm_trades for PM execution state
mp_backed_forecasts as the bridge between simplified forecast UX and PM execution
mp_pm_market_resolutions, mp_pm_settlements, and mp_pm_claims for PM post-trade finance trace
mp_pm_quickbuy_configs for operator-managed Quick Buy routing and house-quote fallback behavior

Starter wallet and reward config#

The starter wallet is still a one-time onboarding grant, but the runtime no longer treats the mutable grant label as the uniqueness guarantee.

The active config now also centralizes:

base reward amounts for Community Voting and Idea Box
Influence Score tiers and multipliers
wallet progression tiers
standard ledger labels for grants, rewards, market stake, payout, and refund
anti-abuse thresholds such as minimum comment length and publication caps

Reward and Influence layer#

Influence Score now affects reward size through the shared economy config instead of isolated hardcoded formulas.

The important architecture rule is:

determine business result first
update the canonical Influence Score state
apply reward scaling and idempotency checks
write wallet and ledger trace

This avoids stale-multiplier credits and keeps rollback or adjustment flows possible when prediction correctness changes later.

Wallet and history surface#

The wallet is intentionally broader than a reward summary.

it shows starter grants
it shows reward credits and adjustments
it shows Prediction Market cash movements such as stake, settlement payout, and refund
it exposes recent ledger entries so the user can understand why the balance changed

Direct history access now bootstraps wallet state safely instead of assuming another request already created the starter wallet and grant rows earlier.

Prediction Markets inside the same economy#

Prediction Markets no longer sit next to the wallet as a separate black box.

orders reserve cash or shares
positions store cost basis and realized PnL
resolution writes canonical final outcome
settlements and claims connect PM results back into the shared Pawn-Coin ledger
amount-first Quick Buy stays user-friendly while the engine still tracks price and shares correctly

Quick Buy also has an operator-configured fallback layer, so live orderbook liquidity is not the only entry path into PM.

Control and operator surface#

The control layer is part of the architecture, not only an admin convenience.

Pawn-Coin control manages starter wallet, rewards, influence tiers, ledger labels, and anti-abuse settings
Prediction Markets control manages Quick Buy fallback probabilities, spreads, limits, priority, and featured fallback rows
validation and export tools reduce drift between code assumptions and operator-edited values

Source-of-truth rules#

Economy settings: effective Pawn-Coin config and validated control overrides
Reward uniqueness: idempotent reward-event keys and period guards
Influence-based scaling: canonical mp_users.current_influence_score plus shared influence tiers
PM final outcome: market resolution plus settlement and claim rows
User-readable finance trace: wallet ledger history plus PM panels

Current non-goals#

external cash-out
on-chain transfer logic
DAO governance
cross-chain settlement