Feature: Coin Vault System

[gomaaz]

🏦 Feature: Coin Vault System

Summary

Players should be able to deposit their coins into a vault.
Deposited coins are completely locked but grow passively through a
bonus counter. Early withdrawal is possible at any time, but with a penalty.

---

Motivation

The coin economy should be extended with a passive, risk-free saving option.
Players who don't want to spend their coins have a meaningful incentive to
"park" them, without needing to participate in the active game flow.

---

Coin States

State	Description
coins_wallet	Freely usable (shop, items, transfers)
coins_vault	Deposited – completely locked

All existing spend checks use only coins_wallet.
coins_vault is never touched by any existing logic.

---

Behavior

Deposit

• Coins move from wallet → vault
• A bonus counter starts (e.g. +X% per hour, configurable)

Live Bonus

• Players can check their current status at any time:
  "Deposited: 200 Coins | Current Bonus: +18 Coins"
• Grows passively, no interaction required

Withdrawal (available at any time)

• Full withdrawal at party end: deposit + full bonus
• Early withdrawal: full deposit + bonus with penalty (e.g. 50% of bonus is forfeited)
• The deposit itself is always fully protected

Security

• The vault is absolutely secure
• No attack, chaos, or any other items can affect coins_vault

---

Example Flow

Time	Action	Wallet	Vault	Bonus
18:00	Deposit 200	50	200	0
19:00	(passive)	50	200	+10
20:00	Early withdrawal	255	0	0

Bonus would have been 20 → 50% penalty → only 5 paid out.
Wallet: 50 + 200 + 5 = 255

---

Technical Requirements

• Database field coins_vault per player
• Timestamp vault_deposited_at for bonus calculation
• API: POST /vault/deposit – Deposit coins
• API: POST /vault/withdraw – Withdraw coins (with penalty logic)
• API: GET /vault/status – Retrieve current bonus status
• UI: Vault view with live bonus display
• Configurable parameters: bonus rate, penalty percentage

---

Labels

enhancement economy vault coins