Treasury Overview

Treasury Overview

Concept Phase

Treasury exists because large servers eventually need more than “run this command as console” or “mail these items.” They need a canonical answer to whether a reward exists, whether a player earned it, whether it was already claimed, and what happened when delivery failed.

---

Core Philosophy

Rewards should be defined once, granted safely, claimed clearly, and audited forever.

Idempotent

The same source event should not duplicate rewards if it is replayed, retried, or processed on another node.

Player-Friendly

Players should see what they can claim, what expired, and what was already delivered.

Ops-Friendly

Staff need search, grant, revoke, retry, preview, and rollback tools with audit reasons.

---

System Design

flowchart LR
    Source[Jubilee/Festival/Journey/Admin] --> Grant[Treasury Grant API]
    Grant --> Ledger[Grant Ledger]
    Ledger --> Claimable[Claim Center]
    Claimable --> Claim[Player Claim]
    Claim --> Resolver[Reward Resolver]
    Resolver --> Courier[Courier Adapter]
    Resolver --> Commands[Command Adapter]
    Resolver --> Economy[Economy Adapter]
    Resolver --> Cosmetics[Cosmetic Adapter]
    Claim --> Receipts[Claim Receipts]

Catalog Entry

{
  "id": "jubilee:verdant_tier_50",
  "version": 3,
  "display": {
    "name": "Verdant Tier 50 Bundle",
    "description": "A mid-season Jubilee reward bundle."
  },
  "contents": [
    { "type": "item", "item": "minecraft:emerald", "count": 16 },
    { "type": "command", "command": "lp user {player} permission settemp titles.verdant true 90d" },
    { "type": "passport_badge", "badge": "jubilee:verdant_midseason" }
  ],
  "delivery": "courier_preferred",
  "expires_after_days": 90
}

Grant Receipt

{
  "grant_id": "grant_01HR...",
  "player": "uuid",
  "catalog_id": "jubilee:verdant_tier_50",
  "catalog_version": 3,
  "source": "jubilee:verdant_skies_2027:level_50",
  "status": "claimable",
  "created_at": "2027-04-04T20:15:00Z"
}

The tuple of player + catalog + source should be unique unless the catalog marks itself repeatable.

---

Gameplay Design

Player Loop

1. Player earns a reward from Jubilee, Festival, Journey, staff compensation, or another system.
2. Treasury records it and notifies the player.
3. Player opens /treasury to view claimable rewards.
4. Player claims now, saves for later, or inspects details.
5. Treasury delivers through the configured adapter and stores the receipt.

Claim Center Categories

• Claimable: ready to claim now.
• Pending: waiting on a condition, season end, staff approval, or payment settlement.
• Claimed: delivered with receipt details.
• Expired: no longer claimable.
• Revoked: removed by source mod or staff with a reason.
• Failed: delivery failed and can be retried by staff.

---

How Treasury Differs From Courier

Courier is still important. Treasury should use Courier heavily. But they solve different problems:

Scenario	Treasury Responsibility	Courier Responsibility
Season pass reward	Validate tier entitlement and prevent duplicate claims.	Deliver the claimed item/Pokemon mail.
Staff compensation	Record who approved it and why.	Send the compensation package to the player.
Failed delivery	Keep claim in failed/retryable state.	Report delivery error and retry package if asked.
Reward preview	Show bundle contents and policy before claim.	Optionally render a mail preview.
Audit request	Show source, catalog version, claim time, delivery adapter.	Show mail delivery status and attachment pickup.

Treasury can exist without Courier by using command/economy adapters. Courier can exist without Treasury as a mail mod. Together, they form a complete reward pipeline.

---

Cross-Mod Hooks

Mod	Treasury Role
Jubilee	Season pass grants, community milestone rewards, catch-up compensation
Festival	Attendance grants, event reward bundles, post-event compensation
Passport	Cosmetic badge/title entitlements and claim history display
Courier	Preferred delivery adapter for mail, items, and Pokemon attachments
Journey	Quest reward authority for high-value or delayed rewards
Frontier	Ranked season payouts and tournament rewards
Bazaar	Market compensation, fee refunds, promotional bundles
Relic	Catalyst bundles, inscription unlock grants, renown compensation

---

Safety Rules

• Every grant needs a source key.
• Every staff grant/revoke needs an audit reason.
• Catalog changes must not rewrite old grant meaning; use versions.
• Delivery retries must not duplicate already-delivered contents.
• Rewards with real-money or supporter implications should have stricter audit and export paths.