BlockLedger

BlockLedger

Forensic anti-grief logging, lookup, rollback, restore, crime reconstruction, 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, restore, purge, case, report, alert, and reconstruction 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, harvest, fade, spread, growth, bonemeal, archaeology brushing, sculk changes, buckets, liquids, fire, TNT priming, explosions, pistons, falling blocks, portals, leaf decay, crop trampling, sponge absorption, cauldron changes, moisture changes, dispenser/dropper activity, hanging entities, and entity block changes.
• Logs signs, player interactions, sessions, chat, commands, deaths, username changes, entity kills and deaths, entity placement and destruction, item drops, pickups, throws and uses, projectile launches and hits, crafting, villager trades, inventory changes, container changes, hopper transfers, vehicles, riding/dismounting, bucketed entities, shearing, item-frame rotation, raid triggers, lightning, and entity transformations.
• Captures neighbour 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, armour 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 serialised item stacks for container changes, 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, WorldEdit selections, world, action, material, entity, item, cause, source plugin, case, batch, session, before/after state, rolled-back status, include text, exclude text, pages, and lines per page.
• 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, CSV export, close/reopen, and list commands.
• Reports for queue status, storage, activity, suspects/top users, partial rollbacks, skipped rollback rows, and retention.
• Audit-only alerts for suspicious bursts such as mass block changes, explosions, hazards, container removals, and entity harm.
• Safe crime reconstructions in an isolated CrimeReconstruction world.
• Reconstruction requests prepare scenes in the background and only start playback when an authorised viewer clicks the ready message or runs the view command.
• Reconstruction sessions track PREPARING, READY, PLAYING, and finished states.
• Reconstruction builds chunks, context blocks, scene blocks, displays, and safe platforms in bounded batches per tick.
• Reconstruction playback supports fake actors through optional NPCs fake-player support, TNT priming visuals, grouped explosion frames, sounds, and safe viewer platforms.
• Reconstruction world guards cancel damage and unsafe interaction, and recover viewers who fall below the platform.
• Backup, verify, reindex, migration check, retention status, queue flush, and consumer pause/resume commands.
• Purge tools with minimum-age protections, preview mode, count mode, silent mode, and normal lookup filters.
• Configurable world filters, blacklists, logging categories, rollback limits, purge safety, queue settings, reconstruction 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.
• Reconstruction metadata is stored separately from normal rollback data, so legacy rows remain lookup/rollback-capable without being treated as exact reconstruction evidence unless configured.

Commands

Main command aliases:

• /blockledger
• /bl
• /ledger

Common commands:

• /bl help
• /bl inspect
• /bl lookup u:<user> t:<time> r:<radius|#world|#global|#worldedit> a:<action>
• /bl near [filters]
• /bl page <session> <page>
• /bl rollback u:<user> t:<time> r:<radius> #preview
• /bl restore u:<user> t:<time> r:<radius> #preview
• /bl reconstruct preview <filters>
• /bl reconstruct start <filters>
• /bl reconstruct entry <id[,id...]>
• /bl reconstruct case <case>
• /bl reconstruct view <session>
• /bl reconstruct stop <session>
• /bl reconstruct status
• /bl purge t:<age> #preview
• /bl case create <title>
• /bl case add <case> <query filters>
• /bl case timeline <case>
• /bl case suspects <case>
• /bl case rollback <case> [#preview]
• /bl case restore <case> [#preview]
• /bl case export <case>
• /bl case close <case>
• /bl case reopen <case>
• /bl case list
• /bl report queue|storage|activity|suspects|top|partial|skips|retention
• /bl alert status|ack|mute|test
• /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 lookup t:1d rolledback:false before:oak_planks after:air
• /bl rollback u:PlayerName t:15m r:10 #preview
• /bl restore u:PlayerName t:15m r:10
• /bl reconstruct start u:PlayerName t:10m r:20 a:block
• /bl reconstruct view <session>
• /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.teleport
• blockledger.reconstruct
• blockledger.reconstruct.admin
• blockledger.admin

Optional Integrations

BlockLedger is fully usable on its own, but it can work with 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, reconstruct, and purge regions with r:#worldedit or r:#we.
• NPCs can provide fake-player support for reconstruction playback. BlockLedger still loads without NPCs, but reconstruction can be unavailable when reconstruction.require-npcs is enabled.
• 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, inspect storage health, prepare reconstructions, view reconstructions, stop reconstructions, and list reconstruction sessions.
• 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, cases, reports, alerts, 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, restore, purge, or reconstruct 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 serialisation. BlockLedger itself avoids direct NMS; reconstruction playback can optionally rely on NPCs fake-player support when exact actor playback is enabled.