TgWitness / Documentation

Repository / docs/wiki/Independent-Witness.md

Independent witness

Keep an independent check. Retained checkpoints and independent witness records.

03 · INDEPENDENT CHECKS · All guides · Get help

On this page
Component Purpose
Collector Records what its account sees
Witness Fetches the signed journal head, signs what it saw, can post it to a channel
Controlled delivery test Compares known sends/edits/deletes with what got captured

The witness has its own key and a read-only token. That token can't read messages, control the collector or get the Telegram session.

Keep a boundary you can compare#

A four-record export matches the independently retained boundary at record three.

An export can be longer than a checkpoint. Check the checkpoint signature, then compare the hash at its record count. A shorter export can't match it; a matching boundary confirms the prefix, and verification checks every event. The collector key signs the checkpoint, so it counts when the recipient got it before the archive, through another channel. It is an optional supporting check.

Open the full-size animation · Static diagram · Exact checkpoint formula

Set up a witness#

  1. Open More tools → Extras → Independent witness → Configure.
  2. Create a read-only token, save it as witness-token.txt.
  3. Pick a Telegram channel or Discord webhook, the interval and the collector address. Download witness.json (it pins the collector key).
  4. Put the JSON and token together on the witness host. Telegram: bot token in bot-token.txt, bot allowed to post. Discord: webhook URL in discord-webhook.txt.
  5. Check and start:
python -m tgwitness.witness run --config witness.json --check-config
python -m tgwitness.witness run --config witness.json

The check makes no network calls. Starting it will post according to your config.

Keep its fingerprint somewhere else:

python -m tgwitness.witness fingerprint --config witness.json

Look at the witness log and the channel itself. "Last poll" in the collector only means a request came in.

Interpret the result#

A witness on another host, under another custodian, adds an independent key; custody records show who holds it. The witness journal is a supporting check. Its posts give external time: with --channel https://t.me/s/CHANNEL the verifier reads the date Telegram set on each post, skipping edited posts. Dates in a Telegram Desktop result.json are supplied metadata, not independent time.

A growing counter shows that the witness is active. Compare proof receipts with the matching evidence archive, and use a controlled test for specific events.

Next: Witness reference · Evidence limits