BlockLedger

BlockLedger

Forensic anti-grief logging, lookup, rollback, restore, and staff investigation tools for Paper servers.

BlockLedger is a standalone forensic anti-grief ledger for Paper servers. It records gameplay activity, lets staff search exactly what happened, and provides rollback and restore tools for repairing damage after griefing, accidents, or staff investigations.

It works out of the box with SQLite and also supports MySQL and MariaDB for larger setups.

Features

• Logs block placement, breaking, natural break, fade, spread, growth, bonemeal, sculk changes, buckets, liquids, fire, explosions, pistons, falling blocks, portals, leaf decay, crop trampling, sponge absorption, cauldron changes, moisture changes, dispenser/dropper activity, and entity block changes.
• Logs signs, player interactions, sessions, chat, commands, deaths, username changes, entity kills, item drops and pickups, crafting, villager trades, inventory changes, container changes, hopper transfers, hanging entities, vehicles, bucketed entities, shearing, lightning, and entity transformations.
• Captures neighbor physics side effects around block changes, so dependent blocks such as flowers, torches, rails, signs, redstone, and other attachments can be rolled back with their support blocks.
• Stores Paper/Bukkit entity snapshots for item frames, paintings, armor stands, placed entities, destroyed vehicles, villager transformations, villager deaths, named mob deaths, and tamed pet deaths.
• Stores common tile/block state data for rollback, including signs, containers, crafters, chiseled bookshelves, decorated pots, jukeboxes, lecterns, brushable blocks, banners, skulls, spawners, vaults, and trial spawners where Bukkit exposes safe APIs.
• Stores exact serialized item stacks for container changes, including automated hopper transfers and hopper item pickup.
• Inspector mode lets staff toggle inspection and click blocks to view local history.
• Lookup filters for users, time, radius, world, action, material, entity, item, cause, source plugin, case, batch, session, before/after state, rolled-back status, include text, and exclude text.
• Rollback and restore support for stored block states, tile states, container changes, and supported entity snapshots.
• Rollback and restore batches include conflict reporting, skip reasons, partial-change reasons, and batch IDs for later review.
• Preview and count modes help staff verify dangerous operations before applying them.
• Staff case management with case creation, adding records, timelines, suspects, rollback/restore by case, export, close/reopen, and list.
• Reports for queue status, storage, activity, suspects, partial rollbacks, skipped rollback rows, retention, and top users.
• Audit-only alerts for suspicious bursts such as mass block changes, explosions, hazards, container removals, and entity harm.
• Backup, verify, reindex, migration check, retention status, queue flush, and consumer pause/resume commands.
• Purge tools with minimum-age protections, preview mode, count mode, and normal lookup filters.
• Configurable world filters, blacklists, logging categories, rollback limits, purge safety, queue settings, result limits, and messages.

Storage And Security

• SQLite works by default with no external database setup.
• MySQL and MariaDB are supported through JDBC.
• SQLite paths are confined to the plugin data folder.
• Example MySQL and MariaDB URLs use certificate and hostname verification.
• JDBC credentials are redacted from status and diagnostics.
• Credential-like JDBC query parameters are stripped before database connections are opened.
• Command arguments are not stored by default.
• Chat and command logging redact common password, token, bearer-token, JWT, and API-key patterns.
• Failed database flushes are written to a local continuity log and replayed on startup.

Commands

Main command aliases:

• /blockledger
• /bl
• /ledger

Common commands:

• /bl inspect
• /bl lookup u:<user> t:<time> r:<radius|#world|#global> a:<action>
• /bl near t:30m a:container
• /bl rollback u:<user> t:<time> r:<radius> #preview
• /bl rollback u:<user> t:<time> r:<radius>
• /bl restore u:<user> t:<time> r:<radius>
• /bl purge t:<age> #preview
• /bl case create <title>
• /bl case add <case> <query filters>
• /bl case timeline <case>
• /bl report suspects
• /bl report skips
• /bl alert status
• /bl backup
• /bl verify
• /bl reindex
• /bl migrate-db
• /bl retention
• /bl status
• /bl consumer <on|off|status>
• /bl flush
• /bl reload

Query Examples

• /bl lookup u:PlayerName t:1d r:20 a:block
• /bl lookup t:2h r:#world i:diamond #count
• /bl lookup t:1h-2h a:chat #verbose
• /bl lookup t:1d m:diamond_block cause:tnt plugin:minecraft
• /bl lookup t:1d r:#worldedit a:block #count
• /bl rollback u:PlayerName t:15m r:10 #preview
• /bl purge t:30d r:#world #preview

Permissions

Every permission defaults to operator access.

Grant everything:

• blockledger.*

Or assign individual permissions:

• blockledger.command
• blockledger.help
• blockledger.inspect
• blockledger.lookup
• blockledger.lookup.block
• blockledger.lookup.chat
• blockledger.lookup.click
• blockledger.lookup.command
• blockledger.lookup.container
• blockledger.lookup.inventory
• blockledger.lookup.item
• blockledger.lookup.kill
• blockledger.lookup.session
• blockledger.lookup.sign
• blockledger.lookup.username
• blockledger.rollback
• blockledger.restore
• blockledger.case
• blockledger.report
• blockledger.alert
• blockledger.backup
• blockledger.verify
• blockledger.reindex
• blockledger.migrate
• blockledger.retention
• blockledger.purge
• blockledger.reload
• blockledger.status
• blockledger.consumer
• blockledger.flush
• blockledger.admin

Optional Integrations

BlockLedger is fully usable on its own, but it can work with several other plugins when they are installed.

• ThunderPerms can be used for BlockLedger command permission checks. Bukkit permissions remain the fallback.
• WorldEdit selections can be used as lookup, rollback, restore, and purge regions with r:#worldedit or r:#we.
• StormFactions claim context can be added to ledger metadata when a record occurs in claimed land.
• StormParty party context can be added to ledger metadata for player-related records.
• Other plugins can use BlockLedgerApi to record custom ledger entries, run lookups, count matches, preview/apply rollback or restore operations, create cases, add entries to cases, read case timelines, check inspector state, and inspect storage health.
• Other plugins can listen for BlockLedger events such as record, rollback preview/apply, case, alert, and storage health events.

These hooks are optional. If the other plugins are missing, BlockLedger keeps working normally with its own logging, lookup, rollback, restore, storage, and commands.

Notes

BlockLedger does not auto-ban, auto-freeze, or automatically cancel suspicious actions. It is designed as a staff investigation and repair tool: record first, investigate clearly, preview destructive operations, then rollback or restore only when staff choose to.

Rollback and restore apply stored Bukkit block data, order removals before placements, restore lower support blocks before higher dependent blocks, skip unsafe operations such as bedrock replacement when configured, report current-state conflicts, record skipped/partial reasons, and tag each operation with a batch ID.

Entity rollback uses Paper/Bukkit entity snapshots, and container rollback uses Bukkit item serialization. No NMS is used.