Implement production network-wide multi-currency economy

docs/features/README.md

@@ -54,6 +54,7 @@ This directory documents all **64** feature modules currently present in ServerF
 - [VillagerOptimizer](villageroptimizer.md) — Reduces villager processing cost by applying configurable optimization rules without changing intended gameplay more than necessary.
 - [WorldEditVisualizer](worldeditvisualizer.md) — Visualizes WorldEdit selections for authorized builders with temporary particles or display markers.
 - [Graveyard](graveyard.md) — Stores death contents durably and renders claimable packet-only graves with active-server-time expiry and crash recovery.
+- [Economy](economy.md)
 - [Lottery](lottery.md) — Runs scheduled ticket-based draws with donations, offline payouts, history, leaderboards, and a small staff command set.
 
 ## Moderation and administration

docs/features/economy-deployment-checklist.md

@@ -0,0 +1,49 @@
+# Economy network deployment checklist
+
+Use this checklist before enabling Economy on a production HauntedMC network.
+
+## Required shared infrastructure
+
+- Every Paper instance must use the same authoritative MySQL database for shared/global currencies.
+- Redis messaging should use the same configured connection and channel on all participating instances. Redis is an invalidation and notification transport only; MySQL remains authoritative.
+- DataRegistry must resolve the same immutable player ID and UUID pair on every instance.
+- Every participating instance must run the same ServerFeatures build. Do not operate mixed Economy schema or messaging versions during rollout.
+
+## Stable scope keys
+
+- Give every logical gamemode one permanent local key, such as `survival`, `skyblock`, or `kitpvp`.
+- Set the top-level `server_key`, `gamemode_key`, or `local_key` to that logical gamemode key. A per-currency `scope.local_key` may override it when replicas need an explicitly shared local scope.
+- Physical replicas of one gamemode must use the same logical local key when they should share gamemode-local balances.
+- Do not rename a logical key after accounts exist. A different key intentionally selects a different account scope.
+- Configure Crowns and Credits as `GLOBAL` on every participating gamemode.
+- Configure Essence, Relics, Soulstones, and Money as gamemode-local `SERVER` currencies.
+- Expose only gamemode-local Money as the Vault primary currency on each Paper server.
+
+## Configuration consistency
+
+- Keep precision, starting balance, bounds, negative-balance policy, rounding, payment limits, cooldown, and payment-default settings identical for every server sharing a currency account scope.
+- Keep each currency ID in one scope family across the network. For example, `crowns` must not be global on one gamemode and local on another.
+- Startup must remain blocked when the persisted currency-family or scope definition conflicts with configuration. Do not bypass these guards.
+
+## Rollout
+
+1. Back up the economy database.
+2. Deploy the same plugin build to every participating Paper instance.
+3. Enable and validate one non-production gamemode first.
+4. Run `/economy status`, `/economy currencies`, and `/economy verify`.
+5. Test one local Money transfer between physical replicas of the same gamemode.
+6. Test one local currency transaction while the recipient is online on another gamemode; only the originating gamemode account should change.
+7. Test one global Crowns or Credits payment while the recipient is online on another gamemode; both servers should converge on the same committed MySQL balance.
+8. Repeat the global test with Redis temporarily unavailable. The transaction must still commit safely and the remote display must heal through authoritative refresh after messaging returns or the refresh interval elapses.
+9. Retry one native mutation with the same source and idempotency key. It must replay the original operation without changing the balance twice.
+10. Retry the same key with a different amount or recipient. It must return an idempotency conflict and apply nothing.
+11. Confirm Vault reports the correct gamemode-local Money balance and cannot expose Crowns, Credits, or other named currencies.
+12. Enable the remaining gamemodes only after all checks pass.
+
+## Operational rules
+
+- Never repair balances by editing cache or Redis data.
+- Never change balances outside `EconomyApi`, the Economy administration commands, or the registered Vault provider.
+- Preserve operation IDs, sources, and idempotency keys in logs for every high-value integration.
+- Keep financial data models immutable at API boundaries and retain null-safe failure handling in every compensation path.
+- Treat `/economy verify` findings, identity conflicts, currency-definition conflicts, or repeated temporary database failures as release-blocking incidents.

docs/features/economy-hauntedmc-example.yml

@@ -0,0 +1,237 @@
+# Example Economy feature configuration for one HauntedMC gamemode.
+# Change server_key per logical gamemode (survival, skyblock, kitpvp, ...).
+# Physical replicas of the same gamemode must use the same server_key.
+
+enabled: true
+network_key: hauntedmc
+server_key: survival
+
+database:
+  connection: system_data_rw
+
+messaging:
+  enabled: true
+  connection: hauntedmc
+  channel: serverfeatures.economy.balance
+
+vault:
+  enabled: true
+  primary_currency: money
+  conflict_policy: FAIL
+
+currencies:
+  crowns:
+    enabled: true
+    scope:
+      type: GLOBAL
+    display:
+      singular: Crown
+      plural: Crowns
+      symbol: "♛"
+      format: "{amount} {plural}"
+      fractional_digits: 0
+      grouping: true
+    balances:
+      starting: "0"
+      minimum: "0"
+      maximum: "999999999999999999999999999999"
+      allow_negative: false
+      rounding: UNNECESSARY
+    commands:
+      root: crowns
+      aliases: [crown]
+      balance: true
+      balance_others: true
+      pay: true
+      paytoggle: true
+      history: true
+      top: true
+    payments:
+      default_enabled: true
+      allow_offline_recipient: true
+      minimum: "1"
+      maximum: "1000000"
+      confirmation_threshold: "10000"
+      daily_send_limit: "0"
+      daily_receive_limit: "0"
+      cooldown: 1s
+
+  credits:
+    enabled: true
+    scope:
+      type: GLOBAL
+    display:
+      singular: Credit
+      plural: Credits
+      symbol: "✦"
+      format: "{amount} {plural}"
+      fractional_digits: 0
+      grouping: true
+    balances:
+      starting: "0"
+      minimum: "0"
+      maximum: "999999999999999999999999999999"
+      allow_negative: false
+      rounding: UNNECESSARY
+    commands:
+      root: credits
+      aliases: [credit]
+      balance: true
+      balance_others: true
+      pay: true
+      paytoggle: true
+      history: true
+      top: true
+    payments:
+      default_enabled: true
+      allow_offline_recipient: true
+      minimum: "1"
+      maximum: "1000000"
+      confirmation_threshold: "10000"
+      daily_send_limit: "0"
+      daily_receive_limit: "0"
+      cooldown: 1s
+
+  essence:
+    enabled: true
+    scope:
+      type: SERVER
+    display:
+      singular: Essence
+      plural: Essence
+      symbol: "✧"
+      format: "{amount} {plural}"
+      fractional_digits: 0
+      grouping: true
+    balances:
+      starting: "0"
+      minimum: "0"
+      maximum: "999999999999999999999999999999"
+      allow_negative: false
+      rounding: UNNECESSARY
+    commands:
+      root: essence
+      aliases: []
+      balance: true
+      balance_others: true
+      pay: true
+      paytoggle: true
+      history: true
+      top: true
+    payments:
+      default_enabled: true
+      allow_offline_recipient: true
+      minimum: "1"
+      maximum: "0"
+      confirmation_threshold: "0"
+      daily_send_limit: "0"
+      daily_receive_limit: "0"
+      cooldown: 1s
+
+  relics:
+    enabled: true
+    scope:
+      type: SERVER
+    display:
+      singular: Relic
+      plural: Relics
+      symbol: "◆"
+      format: "{amount} {plural}"
+      fractional_digits: 0
+      grouping: true
+    balances:
+      starting: "0"
+      minimum: "0"
+      maximum: "999999999999999999999999999999"
+      allow_negative: false
+      rounding: UNNECESSARY
+    commands:
+      root: relics
+      aliases: [relic]
+      balance: true
+      balance_others: true
+      pay: true
+      paytoggle: true
+      history: true
+      top: true
+    payments:
+      default_enabled: true
+      allow_offline_recipient: true
+      minimum: "1"
+      maximum: "0"
+      confirmation_threshold: "0"
+      daily_send_limit: "0"
+      daily_receive_limit: "0"
+      cooldown: 1s
+
+  soulstones:
+    enabled: true
+    scope:
+      type: SERVER
+    display:
+      singular: Soulstone
+      plural: Soulstones
+      symbol: "◈"
+      format: "{amount} {plural}"
+      fractional_digits: 0
+      grouping: true
+    balances:
+      starting: "0"
+      minimum: "0"
+      maximum: "999999999999999999999999999999"
+      allow_negative: false
+      rounding: UNNECESSARY
+    commands:
+      root: soulstones
+      aliases: [soulstone]
+      balance: true
+      balance_others: true
+      pay: true
+      paytoggle: true
+      history: true
+      top: true
+    payments:
+      default_enabled: true
+      allow_offline_recipient: true
+      minimum: "1"
+      maximum: "0"
+      confirmation_threshold: "0"
+      daily_send_limit: "0"
+      daily_receive_limit: "0"
+      cooldown: 1s
+
+  money:
+    enabled: true
+    scope:
+      type: SERVER
+    display:
+      singular: Coin
+      plural: Coins
+      symbol: "$"
+      format: "{symbol}{amount}"
+      fractional_digits: 2
+      grouping: true
+    balances:
+      starting: "0.00"
+      minimum: "0.00"
+      maximum: "999999999999999999999999999999.99999999"
+      allow_negative: false
+      rounding: HALF_UP
+    commands:
+      root: money
+      aliases: [balance, bal]
+      balance: true
+      balance_others: true
+      pay: true
+      paytoggle: true
+      history: true
+      top: true
+    payments:
+      default_enabled: true
+      allow_offline_recipient: true
+      minimum: "0.01"
+      maximum: "0.00"
+      confirmation_threshold: "100000.00"
+      daily_send_limit: "0.00"
+      daily_receive_limit: "0.00"
+      cooldown: 1s