Chestlogger

📦 ChestLogger

High-Performance, Zero-Blocking Container Audit, Rollback, Item Provenance & Smart Theft Detection System
Dual Native Server Releases for Fabric Mod & Paper Plugin on Minecraft 26.2 (Pure Java 25).

---

✨ Overview

ChestLogger is an ultra-fast, zero-lag anti-griefing system, smart theft detection engine, and item custody tracker built from first principles for modern Minecraft servers.

Unlike traditional SQL-heavy loggers that trigger server tick lag and database locks, ChestLogger intercepts container events into a lock-free memory ring buffer and streams them to append-only binary files (.clog) using pure LZ4 compression.

Feature	📦 ChestLogger (Fabric & Paper)	📜 Traditional SQL Loggers
Server Tick Impact	0.00 ms (Lock-Free MPSC Ring Buffer)	1.5 – 15.0 ms (JDBC connection pool contention)
Storage Engine	Append-Only Binary (.clog LZ4, <30 bytes/tx)	Heavy SQLite / MySQL tables (25–45 MB/100k tx)
Crash Safety	Self-Healing CRC32 Tail Checkpoints	Database lock corruptions on SIGKILL / crash
Smart Theft Engine	Sub-20ms Raid Velocity & Distance Heuristics	Alert spam on any container touch
Item Custody Tracing	Full DAG Provenance Tree (/chestlog trace)	None (Flat tables without custody linkage)
Rollback Safety	Non-Destructive Slot Compensation	Hard snapshots (deletes newer legitimate items)
Low-End HDD Tuned	Sequential Batched Writes (Zero seek storms)	Random disk I/O thrashing on budget hosts

---

🚀 Key Features

🛡️ Smart Theft & Raid Detection Engine

• Context-Aware Presence Detection: Distinguishes legitimate cooperative teamwork from griefing in sub-20ms. Detects 🔴 Offline Theft, 🟡 Absent Owner Looting, and suppresses alerts during 🟢 Consensual Proximity (owner nearby).
• Sliding-Window Raid Velocity Tracking: Detects rapid multi-chest looting bursts across distinct coordinates within a 300s window, raising instant CRITICAL_RAID alerts.
• Directional Player Trust System: Players can trust teammates with /chestlog trust <player> to exempt them from alarms.
• Natural Wilderness Classification: World-gen containers (dungeons, mineshafts, shipwrecks) default to UNCLAIMED_NATURAL to prevent false alert spam while exploring.

🔐 Container Claiming & Anti-Sniping Protection

• Automatic Placement Claims: Containers are claimed under your name the moment you place them down.
• Single & Mass Claiming: Secure unowned containers with /chestlog claim or batch-claim an entire area with /chestlog claim [radius] (up to 16 blocks for players, 32 for admins).
• Anti-Sniping Defense: Prevents griefers from claiming chests if recent audit history proves prior ownership by someone else.
• Claim Transfers: Safely transfer container ownership with /chestlog transfer <newOwner>.

🔍 Item Provenance & Chain of Custody (/chestlog trace)

• Trace Item Lifecycles: Reconstruct the complete custody journey of the item held in your main hand (/chestlog trace) or at any container slot (/chestlog trace <X> <Y> <Z> [slot]).
• Cycle-Safe DAG Traversal: Follows items through player trades, chest deposits, withdrawals, and hopper automation routes.
• 64-Bit Component Fingerprinting: Accurately follows custom-enchanted, renamed, or modified items.

🖥️ In-Game Graphical Menus & Mod Menu

• Click-to-Inspect Mode (/chestlog i): Left-click any container to view logs in chat, or right-click to open the full 54-slot interactive visual history menu (available on both Paper and Fabric).
• In-Game Configuration Screen (/chestlog config): Adjust alert cooldowns, owner proximity distances, and web ports inside an interactive GUI with live hot-reloading (zero server restarts required).
• Mod Menu Support (Fabric Client): Access the configuration screen directly from the pause screen: Game Menu ➔ Mods ➔ ChestLogger ➔ Configure.

⏪ Safe Non-Destructive Rollbacks

• Two-Stage Confirmation Token System: Running /chestlog rollback calculates an inverse slot delta plan in memory and provides a temporary safety token before applying any world changes.
• Zero-Overwrite Protection: Merges into existing partial stacks and relocates items to empty slots. If a container is 100% full, it flags a conflict rather than deleting newer legitimate items.
• Double Chest (54-Slot) Parity: Full dual-coordinate tracking across both halves of linked double chests and automated hoppers.
• Adaptive Broken-Half Recovery: If a griefer breaks one half of a double chest, items are adaptively restored into available slots of the surviving single chest.

🔔 Multi-Channel Alerting & Discord Webhooks

• In-Game Staff HUD: Real-time Action-Bar warnings and interactive chat alert cards with clickable [Teleport] and [Inspect] buttons.
• Discord Security Webhooks: Asynchronous alerts sending rich embeds detailing the incident type, coordinates, items taken, and player presence states.

📊 Built-In Web Dashboard & REST API

• Zero-dependency embedded web server running on port 8080 (or host-allocated port).
• Live incident telemetry feed, filterable log explorer, and visual SVG item custody journey visualizer.
• Export filtered container audit trails directly to RFC 4180 CSV spreadsheets or raw JSON.

---

🎮 Commands Summary

💡 Aliased as /cl or /chestlog.

🛡️ For All Players (No OP Required)

• /chestlog help — Interactive, permission-filtered command directory
• /chestlog i — Toggle click inspection mode (Left-click chat, Right-click GUI)
• /chestlog claim [radius] — Claim targeted container (or mass-claim area up to 16 blocks)
• /chestlog transfer <player> — Transfer ownership of your container to another player
• /chestlog unclaim — Release ownership claim from targeted container
• /chestlog trust <player> — Trust a teammate to share containers without alerts
• /chestlog untrust <player> | /chestlog trustlist — Manage your trusted teammates
• /chestlog trace — Reconstruct custody history for the item held in your main hand

🛠️ For Staff & Administrators

• /chestlog inspect <X> <Y> <Z> [page] — Inspect paginated container history
• /chestlog inspect <X> <Y> <Z> <player> [page] — Filter container history by player
• /chestlog wand — Inspect wand information and quick usage instructions
• /chestlog trace <X> <Y> <Z> [slot] — Trace custody history for item in container slot (0–53)
• /chestlog rollback <X> <Y> <Z> <seconds> [player] — Preview rollback compensation plan
• /chestlog rollback <X> <Y> <Z> <sec> confirm <token> — Execute live rollback
• /chestlog stats — Real-time memory queue depth, throughput, and index telemetry
• /chestlog config — Open interactive In-Game Configuration GUI
• /chestlog purge <days> [token] — Two-step safe purge of old log segments
• /chestlog web [start|stop] — (Paper) Start/stop embedded Web Dashboard

---

📦 Installation & Requirements

Fabric Mod (Server & Client)

1. Download chestlogger-fabric-2.6.4.jar and place it into your mods/ directory.
2. Requirements:
   • Minecraft 26.2 (~26.2)
   • Fabric Loader 0.19.3+
   • Fabric API (Required)
   • Java 25 (>= 25)
3. (Optional) Install Mod Menu to configure settings in-game.

Paper Plugin (Server)

1. Download chestlogger-paper-2.6.4.jar and place it into your plugins/ directory.
2. Requirements:
   • Paper 26.2 (or modern Paper 1.21.x running on Java 25)
   • Java 25 (>= 25)
3. Restart your server (Zero external library dependencies required).

---

📜 Links & Documentation

• 📖 Comprehensive Wiki
• 📋 Master Command Reference
• 🌐 Source Code & Issues
• ⚖️ License: MIT