Reward Catalog
Define reusable reward bundles for seasons, events, quests, compensation, ranks, and purchases.
Treasury - Introduction
Treasury - Reward Authority
Section titled “Treasury - Reward Authority”What is Treasury?
Section titled “What is Treasury?”Treasury is the reward authority for Matcha! servers. It owns reward catalogs, grant receipts, claim state, idempotency, entitlement history, compensation packages, and payout policy. When another mod says “this player earned this reward,” Treasury decides whether that reward is valid, claimable, already claimed, expired, revoked, or ready to deliver.
Treasury is deliberately different from Courier. Courier is the delivery channel: it sends mail, item attachments, Pokemon attachments, and messages. Treasury is the accounting and entitlement layer: it defines what is owed, why it is owed, whether it has been claimed, and which delivery mechanism should fulfill it.
Grant Ledger
Store immutable receipts so rewards are idempotent and auditable across restarts and network nodes.
Claim Center
Give players one place to view claimable, claimed, expired, and revoked rewards.
Delivery Adapters
Fulfill claims through Courier, commands, economy APIs, Pokemon grants, cosmetics, or web-only entitlements.
Treasury vs Courier
Section titled “Treasury vs Courier”| Question | Treasury | Courier |
|---|---|---|
| What is it? | Reward entitlement and claim authority. | Mail and package delivery system. |
| Owns reward definitions? | Yes. Catalogs, bundles, conditions, expiries. | No. It can deliver a package it is given. |
| Prevents duplicate claims? | Yes. Grant ledger and claim receipts. | Not by itself; it delivers queued mail. |
| Knows why a player earned something? | Yes. Source receipts from Jubilee, Festival, staff, etc. | Usually only knows mail metadata/content. |
| Handles offline delivery? | Can decide a reward is claimable while offline. | Delivers mail/items when appropriate. |
| Example | ”Amo is entitled to verdant_tier_50_bundle once." | "Send Amo an inbox message containing these items.” |
Rule of thumb: Treasury says what is owed. Courier says how it is delivered.
Core Concepts at a Glance
Section titled “Core Concepts at a Glance”🏛 Catalogs
Section titled “🏛 Catalogs”Catalogs define reward bundles and policies. They are versioned so old grants remain understandable after configs change.
📜 Grants
Section titled “📜 Grants”Grants are source-backed entitlements: a player earned or was assigned a reward for a specific reason.
✅ Claims
Section titled “✅ Claims”Claims are the act of consuming a grant and fulfilling it. Claims must be idempotent.
🧾 Receipts
Section titled “🧾 Receipts”Receipts record who granted what, why, when, under which catalog version, and how delivery resolved.
🚚 Delivery Adapters
Section titled “🚚 Delivery Adapters”Adapters hand fulfilled rewards to Courier, economy systems, command runners, Pokemon grant APIs, cosmetic registries, or external web services.
Quick Example
Section titled “Quick Example”Step 1: Jubilee Unlocks
Jubilee sees a player reach level 50 and requests a Treasury grant for jubilee:verdant_tier_50.
Step 2: Treasury Records
Treasury validates the catalog entry, records an idempotent grant receipt, and marks it claimable.
Step 3: Player Claims
Player opens /treasury claim and chooses the unlocked bundle.
Step 4: Courier Delivers
Treasury resolves the bundle and asks Courier to deliver the item/Pokemon mail, while storing the claim receipt.
Documentation
Section titled “Documentation” Overview & Design Catalogs, grants, claims, delivery adapters, gameplay loop, and safety guarantees
Commands & Integrations Command sketches, permissions, web claim center, Discord alerts, and integration contracts
Naming Direction
Section titled “Naming Direction”Treasury fits the Matcha! naming style because it is a strong single noun with institutional weight. It implies value, custody, ledgers, and authorized release without sounding like a generic “Rewards” plugin.
| Candidate | Read |
|---|---|
| Treasury | Recommended. Premium, authoritative, and distinct from Courier’s delivery metaphor. |
| Vault | Strong, but more storage/security than reward authority. |
| Bounty | Fun, but sounds quest-specific. |
| Ledger | Accurate for records, but too internal and Ceremony-like. |
Development Status
Section titled “Development Status”- Phase 1: Catalog schema, grant ledger, claim state, basic
/treasuryUI - Phase 2: Courier adapter, command adapter, economy adapter, admin grants
- Phase 3: Web claim center, Discord/staff alerts, audit search
- Phase 4: Cross-network propagation, rollback/revoke flows, analytics, catalog migrations
Estimated Development Time: 8-12 weeks