Virtual-currency wallets with an append-only ledger.

Currencies are free-form string codes ("gold", "gems", "energy") — the game decides which exist. Every balance change is atomic and recorded in the ledger, so two concurrent spends can never overspend and every mutation is auditable.

Usage (server-side / hooks)

Economy.grant(user_id, "gold", 100, reason: "match_reward")
case Economy.spend(user_id, "gold", 30, reason: "store_purchase") do
  {:ok, balance} -> :ok
  {:error, :insufficient_funds} -> :not_enough_gold
end

Economy.balance(user_id, "gold")   #=> 70
Economy.balances(user_id)          #=> %{"gold" => 70}

Idempotency

Pass :idempotency_key so a retried request (network retry, at-least-once job) can't double-apply — the second call is a no-op that returns the current balance:

Economy.grant(user_id, "gems", 5, idempotency_key: "purchase:#{order_id}")

Safety

These are server-authoritative: expose them from hooks and admin tools, never as a raw client "add currency" endpoint. Clients only read their wallet.

Note: This is an SDK stub. Calling these functions will raise an error. The actual implementation runs on the GameServer.