Vaultime
Docs / Trust

The ledger and integrity

Each session keeps a log that only grows, and each PC keeps a signed ledger over those logs. Together they make changes made outside Vaultime visible. They cannot stop them.

On this page
  1. The session log
  2. The ledger
  3. Checking the ledger
  4. What the checks catch
  5. Where the checks end
  6. When the key is lost

The session log #

A session is not a single number that gets overwritten. It is a list of events: tracking started, the times saved along the way, sleep left out, the end, and later any correction you make. Each event carries a fingerprint of the one before it, so the events form a chain. The session's totals must match its newest event that counts time.

Changing an event, removing one or editing the totals breaks the chain or the match, and the session turns Suspicious. Corrections are events too. They name the old values and your reason, so nothing is overwritten without a trace. The event log on a game's page shows the newest events of its sessions, without the times saved along the way.

The ledger #

A chain inside the database can be rebuilt by someone who rewrites the whole database. That is what the ledger is for.

Each PC keeps a ledger, a second chain that it signs with a key of its own. The key is in the file device-key next to the database. It never goes into a backup and never leaves the PC through Vaultime. The ledger:

  • pins a session's record when the session starts, every five minutes while it runs, idle time included, when it ends and when it is corrected,
  • notes every session you remove, together with its game,
  • notes every restore and every session taken in from another PC,
  • notes when a new install takes over the PC whose backup it restored, see Several PCs.

The file device-keys lists every public key the PC has signed with or took over, so older entries still count as its own after a new key.

Between two pins, Vaultime saves a session's time every 30 seconds without pinning it. After a crash, a session counts up to its last saved note, but at most five minutes past the last one the ledger holds. A session whose notes run further, as when the last one was raised outside Vaultime, counts up to those five minutes and turns Suspicious. Sessions recorded before Vaultime pinned these notes keep their time as it was.

A session that was rewritten outside Vaultime, even with its own log rebuilt to match, no longer matches what the ledger pinned and turns Suspicious. So does a session no ledger knows. Sessions recorded before the ledger existed were taken in as they were when it began.

Checking the ledger #

Settings, This PC shows the state of the ledger:

In order
The ledger is unchanged and no session it knows is gone. A single session that no longer matches its pins still turns Suspicious.
Sessions missing
Sessions in the ledger are gone from the history without a note that you removed them.
Changed
The ledger itself was changed outside Vaultime, so the sessions it covers are marked Suspicious, also those recorded after the change. It stays Changed, as Vaultime never signs over an entry it did not sign. The PCs it trusted can no longer be read from it either, so every merge of another PC asks you to confirm its keys, and newer backups of your other PCs no longer come in by themselves.

What the checks catch #

  • A session's times or events edited in the database.
  • A session whose log was rebuilt to look consistent.
  • Sessions deleted outside Vaultime.
  • Clock changes while a game runs.
  • Time added to the last saved note of a session before a restart, beyond five minutes past what the ledger holds.
  • Times below zero or longer than ten years, which only a damaged or made up record holds.
  • Sessions that turn up without this PC or a trusted PC having recorded them. A PC this one has never seen is trusted on its first merge or restore.
  • Backups that are damaged or hold database parts Vaultime never writes. Those are refused before anything is merged or restored.

Where the checks end #

  • Someone with your PC and its key file can rewrite the history and the ledger together, and nothing will look wrong.
  • Removing the newest sessions together with the newest ledger entries leaves a shorter ledger that still checks out.
  • A made up backup of a PC this one has never seen can bring in made up play, since such a PC is taken at its word, see Several PCs.
  • Up to five minutes past the last note the ledger holds can be added to a session that was cut off without anything looking wrong.
  • Vaultime only knows what happened while it ran. Play while it was closed is not recorded at all.
  • No server checks your history. That is why there is no Verified label.

All of this helps you trust your own records and notice when something went wrong. It is not anti-cheat.

When the key is lost #

If device-key goes missing, for example after a fresh install without the old data folder, Vaultime makes a new key and goes on. The PC's earlier entries still count through device-keys when that file survived. Other PCs that merge from this one see a new key and count its sessions only once you confirm the backup comes from this PC, see Several PCs.

A fresh install that restores the PC's last backup before anything else continues as that PC and takes over the keys the backup names for it, see Several PCs.

A copy of the whole data folder keeps the key. A backup made in Vaultime does not, on purpose.

Edit this page on GitHub