View source for Monetary policy engine

The '''monetary policy engine''' is a custom-built automated economic management system on Prosperity SMP. It tracks every dollar created and destroyed on the server, computes real-time inflation metrics, and generates policy recommendations to maintain a healthy economy. It is believed to be the first implementation of classical monetary theory applied to a live Minecraft server economy.

== Overview ==
The engine applies the '''quantity theory of money''' — the same framework used by real-world central banks — to the server economy:

<blockquote>
'''M x V = P x Q'''

Where M = money supply, V = velocity (turnover rate), P = price level ([[Consumer Price Index|CPI]]), and Q = real output (goods traded).
</blockquote>

If money supply grows faster than real output, prices must rise (inflation). If it grows slower, prices fall (deflation). The engine measures these forces in real time and recommends adjustments to keep the economy stable.

== Architecture ==
The system operates across two custom-built layers, both developed specifically for Prosperity SMP.

=== Skript capture layer ===
Custom Skript files running on the Minecraft server capture every money flow event in real time:

* '''treasury-grant.sk''' — a single entry point for all money creation events. Every script that pays a player routes through this wrapper, ensuring no money enters circulation without being tracked.
* '''money-supply.sk''' — classifies every Vault transaction into a five-category taxonomy, computes money supply decomposition with exponential activity decay, and runs stock-flow reconciliation.
* '''cpi-basket.sk''' — computes a winsorized geometric mean Consumer Price Index from real player-to-player trade data, with built-in manipulation defenses.

=== Admin Hub controller layer ===
A TypeScript module in the custom Next.js Admin Hub ingests Skript-exported JSON and runs the policy controller:

* Computes EWMA-smoothed inflation gap
* Evaluates confidence from data maturity, sample depth, and participant diversity
* Applies proportional control with locked safety bounds
* Generates recommendations with reasoning traces and uncertainty bands
* Persists an audit log for historical analysis and future regression

== Event taxonomy ==
Every balance change on the server is classified into exactly one of five categories:

{| class="wikitable" style="width:100%;"
|-
! Category !! Definition !! Effect on money supply
|-
| '''CREATE''' || Money appears from nowhere (job wages, contract rewards, crate cash, /eco give) || Increases total supply
|-
| '''DESTROY''' || Money disappears (admin shop purchases, fees, /eco take) || Decreases total supply
|-
| '''TRANSFER_TO_PUBLIC''' || System account pays a player ([[Simulated ChestShop|Sim Shop]] payouts) || No change (reserve to active)
|-
| '''TRANSFER_FROM_PUBLIC''' || Player pays a system account (rent to system landlord) || No change (active to reserve)
|-
| '''TRANSFER_PRIVATE''' || Player pays another player ([[ChestShop]] sales, /pay) || No change (changes hands)
|}

Only CREATE and DESTROY events change the total money supply. Transfers redistribute existing money.

== Money supply decomposition ==
The engine does not treat all money equally. It decomposes the total into three buckets:

{| class="wikitable"
|-
! Bucket !! Definition !! Policy relevance
|-
| '''M_active''' || Balances of recently active players, weighted by exponential decay || The money actively chasing goods — the primary inflation signal
|-
| '''M_dormant''' || Balances of players inactive for 14+ days || Not circulating; a returning player creates a liquidity shock
|-
| '''M_reserve''' || CentralBank and system accounts || Sterilized reserve — only inflationary when disbursed
|}

The effective money supply formula:

: '''M_effective = M_active + (0.20 x M_dormant) + (lambda x M_reserve)'''

Where lambda forecasts how much reserve money will enter circulation in the next 7 days. The activity decay uses an exponential curve:

: '''weight = max(0.05, e^(-days_since_login / 14))'''

This prevents the engine from panicking when a large dormant balance reactivates.

== Stock-flow reconciliation ==
An hourly integrity check verifies that the tracked events match reality:

: '''Change in M_total = SUM of CREATE - SUM of DESTROY'''

If observed and predicted totals diverge by more than 2%, the engine disables all recommendations and flags the discrepancy. This prevents acting on bad data.

== Controller design ==
The v1 controller uses a '''proportional-only''' formula with conservative tuning:

: '''new_multiplier = old_multiplier x (1 - confidence x K_p x gap)'''

Where:
* '''gap''' = observed weekly CPI growth minus admin-set target (decimal form)
* '''K_p''' = 0.20 (proportional gain constant)
* '''confidence''' = data quality score from 0 to 1

Safety bounds:
* Maximum weekly change: +/- 5%
* Multiplier range: 0.7 to 1.3
* Dead-band: if gap is smaller than 0.3%, the engine outputs NO_OP

The controller is '''advisory only''' in v1. Recommendations require manual admin approval. Auto-application requires confidence above 0.70 for four consecutive weeks.

== Confidence scoring ==
The confidence score is a geometric mean of four components, each bounded between 0.1 and 1.0:

{| class="wikitable"
|-
! Component !! What it measures !! Maximum (1.0) when
|-
| Basket coverage || Fraction of CPI basket items with valid data || All basket items have enough trades
|-
| Sample depth || Average transactions per basket item || 50+ transactions per item
|-
| Diversity || Number of unique buyers and sellers || 8+ unique participants
|-
| Maturity || Time since server deploy || 90+ days of operation
|}

: '''confidence = (coverage x depth x diversity x maturity) ^ (1/4)'''

The geometric mean prevents any single component from dominating — all four must be healthy for confidence to be high.

== NO_OP conditions ==
The engine outputs no action when any of:

# Confidence below 0.30
# Gap within dead-band (+/- 0.3%)
# Reconciliation failing
# Fewer than 5 active players
# Previous action not yet observed (one-week cooldown)
# New-player spike (3+ new players in 48 hours)
# Within first 14 days of operation (Phase A bootstrap)

NO_OP is the most common output on a small server. The engine is designed to be cautious.

== Bootstrap schedule ==
{| class="wikitable"
|-
! Period !! Behavior
|-
| Day 0-14 || Advisory disabled. Dashboards live. Data collection running.
|-
| Day 14-30 || Advisory enabled with confidence scaling. No auto-apply.
|-
| Day 30-90 || Perturbation experiments to measure actuator response.
|-
| Day 90+ || Auto-apply eligible if confidence sustained above 0.70.
|}

== Source-flow ratios ==
The engine computes diagnostic ratios displayed in the Admin Hub Treasury panel:

{| class="wikitable"
|-
! Ratio !! What it measures
|-
| '''sink_ratio''' || How fast money is removed from circulation
|-
| '''bank_drain_ratio''' || How fast the bank injects liquidity into player hands
|-
| '''jobs_faucet_ratio''' || Job wage intensity relative to active money pool
|}

== Design process ==
The engine was designed through a five-round iterative critique between two AI systems (Claude and ChatGPT), correcting three material design flaws in the original draft:

# CentralBank balance incorrectly counted as active money (corrected to sterilized reserve with lambda-weighted forecast)
# Policy response was inverted — raising the target during inflation is accommodation, not control (corrected to proportional tightening)
# "Deflation via fewer purchases" was a misnomer — reducing the faucet slows growth but does not contract existing supply (corrected to "disinflation")

The full technical spec is maintained in the server's internal documentation.

== See also ==
* [[Consumer Price Index]] — the CPI basket the engine consumes
* [[Economy]] — how money flows through the server
* [[Simulated ChestShop]] — the bank-funded market activity system
* [[Admin shop]] — server-run shop (a money sink)
* [[Prestige]] — endgame money sink

[[Category:Systems]]