Monetary policy engine - Revision history

Admin: Redact admin commands, internal filenames, exact tuning constants (keep page substance)

2026-07-21T12:11:36Z

Redact admin commands, internal filenames, exact tuning constants (keep page substance)

← Older revision		Revision as of 12:11, 21 July 2026
Line 9:		Line 9:
	The system operates across two custom-built layers.		The system operates across two custom-built layers.

	=== ~~Skript capture~~ layer (Minecraft server) ===		=== Capture layer (Minecraft server) ===
	Three custom ~~Skript files~~ capture every money flow event in real time:		Three custom capture systems record every money flow event in real time:

	* '''~~treasury-grant.sk~~''' — a single entry point for all money creation. Every ~~script~~ that pays a player routes through this wrapper, ensuring nothing enters circulation untracked.		* '''Creation gateway''' — a single entry point for all money creation. Every system that pays a player routes through this wrapper, ensuring nothing enters circulation untracked.
	* '''~~money-supply.sk~~''' — classifies every ~~Vault~~ transaction into a five-category taxonomy, computes money supply decomposition with exponential activity decay, runs stock-flow reconciliation, and exports ~~JSON~~ snapshots ~~every 5 minutes~~.		* '''Flow classifier''' — classifies every transaction into a five-category taxonomy, computes money supply decomposition with exponential activity decay, runs stock-flow reconciliation, and exports regular snapshots.
	* '''~~cpi-basket.sk~~''' — computes a winsorized geometric mean [[Consumer Price Index]] from real player-to-player trade data, with manipulation defenses and per-item confidence scoring.		* '''CPI computer''' — computes a winsorized geometric mean [[Consumer Price Index]] from real player-to-player trade data, with manipulation defenses and per-item confidence scoring.

	=== ~~Admin Hub controller~~ layer (~~TypeScript~~) ===		=== Controller layer (staff dashboard) ===
	A custom module in the ~~Next.js Admin Hub~~ ingests the ~~Skript-~~exported ~~JSON~~ and runs the policy controller:		A custom module in the staff dashboard ingests the exported data and runs the policy controller:

	* Loads current money supply, CPI, lagged CPI, reconciliation state, and money flow events		* Loads current money supply, CPI, lagged CPI, reconciliation state, and money flow events
Line 34:		Line 34:
	! Category !! Definition !! Effect on total supply		! Category !! Definition !! Effect on total supply
	\|-		\|-
	\| '''CREATE''' \|\| Money appears from nowhere (job wages, contract rewards, crate cash, ~~/eco give~~) \|\| Increases supply		\| '''CREATE''' \|\| Money appears from nowhere (job wages, contract rewards, crate cash, admin grants) \|\| Increases supply
	\|-		\|-
	\| '''DESTROY''' \|\| Money disappears (admin shop purchases, fees, ~~/eco take~~) \|\| Decreases supply		\| '''DESTROY''' \|\| Money disappears (admin shop purchases, fees, admin removals) \|\| Decreases supply
	\|-		\|-
	\| '''TRANSFER_TO_PUBLIC''' \|\| System pays player ([[Simulated ChestShop\|Sim Shop]] payouts) \|\| No change		\| '''TRANSFER_TO_PUBLIC''' \|\| System pays player ([[Simulated ChestShop\|Sim Shop]] payouts) \|\| No change
Line 45:		Line 45:
	\|}		\|}

	Currently tracked sources: Jobs payouts, ~~/eco give and /eco take~~, [[Contracts\|civic contract]] rewards, [[Simulated ChestShop]] payouts, and [[Admin shop]] (EconomyShopGUI) transactions. All hooks are live and producing data.		Currently tracked sources: Jobs payouts, admin adjustments, [[Contracts\|civic contract]] rewards, [[Simulated ChestShop]] payouts, and [[Admin shop]] (EconomyShopGUI) transactions. All hooks are live and producing data.

	== Money supply decomposition ==		== Money supply decomposition ==
Line 76:		Line 76:
	: '''Change in M_total = SUM of CREATE events - SUM of DESTROY events'''		: '''Change in M_total = SUM of CREATE events - SUM of DESTROY events'''

	If the observed total diverges from the predicted total ~~by more than 2%~~, the engine disables all recommendations. This is the "hard gate" — it prevents acting on bad data. As of deploy, reconciliation passes consistently with error under 0.01%.		If the observed total diverges from the predicted total beyond a tight internal tolerance, the engine disables all recommendations. This is the "hard gate" — it prevents acting on bad data. As of deploy, reconciliation passes consistently with error under 0.01%.

	== Controller: the actual formula ==		== Controller: the actual formula ==
Line 82:		Line 82:

	: '''gap = (current_basket_index / lagged_7d_basket_index) - 1 - target_growth'''		: '''gap = (current_basket_index / lagged_7d_basket_index) - 1 - target_growth'''
	: '''new_multiplier = old_multiplier x (1 - confidence x ~~0.20~~ x gap)'''		: '''new_multiplier = old_multiplier x (1 - confidence x K_p x gap)'''

	In words: the engine computes how fast the CPI basket is growing relative to the admin-set target ~~(+0.5% per week default)~~. If prices are rising too fast, it recommends lowering the Sim Shop multiplier. If too slow, it recommends raising it. The magnitude is scaled by data confidence.		In words: the engine computes how fast the CPI basket is growing relative to the admin-set target. If prices are rising too fast, it recommends lowering the Sim Shop multiplier. If too slow, it recommends raising it. The magnitude is scaled by data confidence.

	=== Locked constants ===		=== Locked constants ===
	~~{\| class="wikitable"~~		The controller runs with locked, deliberately conservative constants: a small proportional gain (the actuator response is still being learned), a modest positive weekly growth target, a dead-band that ignores tiny gaps, a hard clamp on how far the multiplier can move in a week, absolute floor/ceiling bounds on the multiplier, and minimum-confidence thresholds below which recommendations are suppressed (v1) or auto-apply is withheld (v2). The exact values are internal.
	\|-
	~~! Parameter !! Value !! Meaning~~
	\|-
	~~\| K_p \|\| 0.20 \|\| Proportional~~ gain (~~intentionally conservative —~~ actuator response is ~~unknown~~)
	\|-
	~~\| Target~~ growth ~~\|\| +0.5%/week \|\| Default healthy inflation rate~~
	\|-
	~~\| Dead~~-band ~~\|\| +/- 0.3% \|\| Below this gap magnitude~~, ~~engine outputs NO_OP~~
	\|-
	~~\| Max weekly change \|\| +/- 5% \|\| Hard~~ clamp on multiplier ~~movement per~~ week
	\|-
	~~\| Multiplier~~ bounds ~~\|\| 0.7 to 1.3 \|\| Absolute floor~~ and ~~ceiling~~
	\|-
	~~\| Min~~ confidence ~~(display) \|\| 0.30 \|\| Below this,~~ recommendations are suppressed
	\|-
	~~\| Min confidence~~ (~~auto-apply~~) ~~\|\| 0.70 \|\| v2~~ auto-apply ~~threshold~~ (~~not active in v1~~)
	\|}

	=== Why proportional-only ===		=== Why proportional-only ===
Line 135:		Line 118:
	The engine outputs "no action" when any of:		The engine outputs "no action" when any of:

	# Confidence below ~~0.30~~		# Confidence below the display threshold
	# Gap within dead-band ~~(+/- 0.3%)~~		# Gap within the dead-band
	# Reconciliation failing (hard gate)		# Reconciliation failing (hard gate)
	# Fewer than 5 active players in 7 days		# Fewer than 5 active players in 7 days

Maintenance script: Rewrite from locked v2 spec + deployed code audit

2026-05-27T16:57:21Z

Rewrite from locked v2 spec + deployed code audit

Show changes

Maintenance script: Initial content

2026-05-27T15:15:20Z

Initial content

New page

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]]