AstralAuctionHouse Overview

AstralAuctionHouse is the player-to-player marketplace for AstralRealms. Players list items at a fixed price; buyers browse by category and purchase; the seller receives Polaris currency; the buyer receives the item through the AstralCore mailbox. Listings expire after a TTL; expired items go to a "claim" state so sellers can recover them.

What it does

Listings with permission-tiered limits, a configurable sell tax, and a 14-day default TTL.
Categories keyed by material similarity, including a fallback bucket for unmatched items.
Custom-item awareness — works with AstralItems, AstralScrolls, AstralPets out of the box.
Weighted price averaging based on the last 90 days of completed transactions, refreshed hourly.
Cross-server consistency via two RabbitMQ packets and a Redis-backed distributed lock.
In-game UI rendered through AstralCore menus, with two new actions (buy-item, claim-item).
Audit trail — every sale persists in the transactions table for 60 days.
Telemetry — listing and purchase events flow into AstralAnalytics.

Requirements

Dependency	Required	Notes
Paper 1.21+	Yes	—
AstralCore	Yes	Menus, configuration, economy service, mailbox, chat, analytics.
AstralEconomy (Polaris)	Yes	Currency back-end. The plugin uses `EconomyService.withdraw / deposit / transfer`.
AstralItems	Yes	Custom-item key resolution for averaging.
AstralPets	Yes	Pet food and pet items are matched as their custom types.
AstralScrolls	Yes	Scrolls participate in averaging via their rarity-aware key.
MariaDB / PostgreSQL	Yes	Two tables: `items`, `transactions`.
Redis	Yes	Average cache + distributed lock + listing snapshots.
RabbitMQ	Yes	`auctionhouse.items` exchange for cross-server invalidation.

Architecture at a glance

/ah sell                                                                          /ah (browse)
   │                                                                                  │
   ▼                                                                                  ▼
ItemService.sell ──► AuctionItem persisted ──► ItemUpdatedPacket ◄──── ItemPacketListener
   │                                  │                                            (other servers)
   ├── Polaris withdraw (sell tax)    │
   └── Player notified                ▼
                                      │
                                      ▼
                                  Redis lock (30s NX EX)
                                      │
                                      ▼
                                  Postgres `items`
                                      │
                                      ▼
                                  Caffeine cache (10 000 max, 14-day expiry)
                                  Multimap<ownerId, itemId>
                                  Sorted snapshot for menu rendering

/ah → AhItemProvider → auctionhouse-listings menu
                       │
                       ▼
                    BuyItemAction
                       │
                       ▼
                    ItemService.buy ──► Polaris transfer (buyer → seller)
                                  │
                                  ├── ItemRepository.delete + ItemDeletedPacket
                                  ├── MailboxService.giveOrAdd (buyer)
                                  ├── TransactionService.save
                                  └── notify both, log AstralAnalytics event

Storage at a glance

items
├── id              UUID PK
├── owner_id        UUID
├── owner_name      VARCHAR
├── category        VARCHAR
├── item_name       VARCHAR
├── item_key        VARCHAR        ← averaging key, e.g. "diamond_sword" or "eb_sh1_pr2"
├── item            LONGBLOB       ← serialized ItemStack (Bukkit NBT)
├── amount          INT
├── status          INT            ← LISTED / SOLD / CANCELLED / EXPIRED
├── price           BIGINT
├── expired_at      TIMESTAMP NULL
├── created_at      TIMESTAMP
└── updated_at      TIMESTAMP

transactions
├── id              UUID PK
├── item_key        VARCHAR
├── amount          INT
├── data            LONGBLOB       ← serialized ItemStack
├── buyer_id        UUID
├── buyer_name      VARCHAR
├── seller_id       UUID
├── seller_name     VARCHAR
├── price           BIGINT
└── created_at      TIMESTAMP

Index hints: idx_owner_status (owner_id, status), idx_buyer_transaction (buyer_id, created_at DESC), idx_seller_transaction (seller_id, created_at DESC).

Last modified: 25 July 2026