# Block and container audit with rollback

> Who broke, placed, blew up, took and put what, where and when - looked up with a click or a filter, undone with a rollback a few blocks each tick, CoreProtect's history imported. New in 0.4, on by default.

Source: https://stygion.eu/docs/keystone/audit
Updated: 2026-11-16

Somebody's base is griefed overnight, a chest is emptied, a creeper took the roof: Keystone keeps every change to blocks and containers, tells you who did it, and puts it back.

## What is recorded

| What | Under whom | Setting |
|---|---|---|
| Blocks broken, with what a chest or a sign held | the player, or a machine as `#` and its name | `record.break` |
| Blocks placed (players, endermen, snow golems) | the player or the mob | `record.place` |
| Blocks an explosion destroyed | the player who lit the TNT when the game knows, otherwise `#tnt`, `#creeper` … | `record.explode` |
| Items taken out of and put into any block with an inventory (chests, barrels, shulkers, any mod's storage) | the player | `record.containers` |
| What machines do: mods' fake players such as Create deployers and drills, quarries | `#` and the machine's name | `record.machines` |
| What a mod reports through the `AuditNoted` event | the mod's own words | `record.notes` |

Nothing is recorded in the worlds in `worlds.skip` (by default Keystone's own benchmark world).

**Left out on purpose:** water and lava spreading, fire, leaves decaying and crops growing are the world's own and would be most of the rows. Blocks that **Create contraptions and Sable ships** lift out of the world are not breaks - they still exist, inside the contraption or the ship, so putting them back would make two. Entity kills are not recorded in this version.

### Not drowned by machines

A drill in a cobblestone generator breaks the same block forever; a chain of TNT breaks thousands a second.

- `limits.repeat` (`10m`): a cause that is not a player changing the same block the same way again within this time is kept once.
- `limits.cause-per-second` (`5000`): past this many rows a second from one such cause, the rest of that second becomes one summary row (*"4211 more changes by #tnt in one second were not kept one by one"*).

Players are never limited.

## Looking it up

**Inspect:** `/keystone audit inspect`, then left-click a block to see its history, right-click a container to see who took and put what. The same command again stops it.

**A filter**, written the way CoreProtect writes it:

| Word | Means | Example |
|---|---|---|
| `u:` | who - players, or causes | `u:Ada,#tnt` |
| `t:` | how far back | `t:30m`, `t:2h`, `t:3d`, `t:1w` |
| `r:` | blocks around you (or `xyz:`); `#world` the whole world, `#global` every world | `r:20` |
| `a:` | actions: `break`, `place`, `explode`, `take` (`-container`), `put` (`+container`), `note` | `a:break,-container` |
| `b:` / `e:` | only these blocks or items / all but these | `b:diamond_ore e:dirt` |
| `w:` | the world | `w:the_nether` |
| `xyz:` | the centre, from the console | `xyz:100,64,-20` |
| `#preview` | count, change nothing | |
| `#force` | put blocks back even where something else stands now | |

A word that does not read is refused, never ignored: a rollback that quietly dropped a mistyped `u:` would undo everybody's work.

`/keystone audit lookup u:Ada t:6h r:30` lists the newest first, `/keystone audit page 2` the next page, `/keystone audit near` is `r:5 t:3d` around you.

## Rolling back

`/keystone audit rollback u:Grief3r t:6h r:40` undoes what the filter matches; `/keystone audit restore` with the same filter does it all again. Add `#preview` first to see how many changes and whose.

- **Newest first:** a block placed, broken and placed again ends as it began. A restore goes oldest first.
- **Nothing is overwritten.** A block goes back only where the block there now is the one the change left; anything built since is left alone and counted. `#force` overrides it.
- **No lag.** It runs a few blocks each tick: at most `rollback.budget-ms` (5 ms) and `rollback.per-tick` (2000) changes. Chunks that are not loaded are loaded for it and let go when it ends; it carries on with the loaded ones meanwhile. Blocks go back without neighbour updates, so sand does not fall and water does not flow while it works.
- **Containers:** a take is put back into the container, a put taken out again - all or nothing, only items exactly like those (with their enchantments and components).
- **Guards:** a rollback needs `t:` (`rollback.needs-time`) and `u:`, `r:` or `w:`; at most `rollback.max` (250 000) changes; one at a time. `/keystone audit cancel` stops it.

When it ends, Keystone says how many changes went back, how many were left alone, how long it took and over how many ticks, and tells mods through `AuditRolledBack`.

## CoreProtect

`/keystone import coreprotect` (see [Importers](/docs/keystone/import)) reads CoreProtect's `database.db` and takes its history into the audit: breaks and places (clicks and kills are left out) and container changes. Bukkit's world names become the game's (`world_nether` is `minecraft:the_nether`), causes keep CoreProtect's words. Running it again takes only what CoreProtect wrote since. Imported block changes can be rolled back like Keystone's own; imported container changes are for looking up only (CoreProtect keeps the items in a form only Bukkit reads). A MySQL CoreProtect cannot be read.

## How it costs nothing

The game only notices: each change asks whether it is kept, reads the block state (and a block entity's data only when there is one) and puts a row in a queue. A container is copied when it opens and compared when it closes. A thread of its own writes the queue to disk in batches. A full queue (`store.queue`) drops new rows and says so - the server never waits for the disk.

The rows live in `keystone/audit/audit.db`, a file of its own beside `keystone.db`, so a backup of the server's settings does not grow with the history. A change takes about **77 bytes** (strings are kept once and referred to by number; a chest's contents are deflated, `store.compress`). Older rows go after `keep.for` (30 days), the oldest first when the file passes `keep.max-size` (4096 MB). `/keystone audit purge 60d` deletes now.

## The editor

*Block audit & rollback* (in People): the filter as fields or typed, the changes newest first, **Preview**, **Roll back** and **Restore** with a confirmation, the rollback under way with a **Stop** button, and what is recorded, how much is kept and what it costs a tick.

## Commands

| Command | What it does | Permission |
|---|---|---|
| `/keystone audit` | status and help | `keystone.audit` |
| `/keystone audit inspect` | click blocks to see their history | `keystone.audit` |
| `/keystone audit lookup <filter>` / `page <n>` / `near` | look up | `keystone.audit` |
| `/keystone audit rollback <filter>` / `restore <filter>` | undo / do again | `keystone.audit.rollback` |
| `/keystone audit cancel` | stop the rollback under way | `keystone.audit.rollback` |
| `/keystone audit purge <time>` | delete rows older than a time | `keystone.audit.purge` |

## The API and events

`GET /v1/block-audit` (status), `/v1/block-audit/lookup`, `/v1/block-audit/preview`, `POST /v1/block-audit/rollback` (`confirm=true`), `/v1/block-audit/cancel`, `/v1/block-audit/purge`. The scopes `block-audit.read`, `block-audit.write` and `block-audit.purge` are carried only by the owner's keys: every block somebody placed is where they live, and a rollback rewrites the world. Details in [The interface - every route](/docs/keystone/api-reference).

For mods: emit **`AuditNoted`** (who, a word of your own, where, what, how many, a note) and the row sits beside Keystone's own, looked up but never rolled back; listen to **`AuditRolledBack`** to redraw a map or tell a claim after a rollback.

## Privacy

Everything stays in the server's own `audit.db`. Keystone sends nothing about it anywhere. Turn the module off in *Settings* and nothing is recorded.
