Reference / Evidence
Independent Evidence Witness & Journal Continuity
Run a witness with its own key and bot, publish signed checkpoints to a channel and check exports against it.
TgWitness / Documentation · Evidence and verification
Export and verify · High assurance · Panel guide
A witness retains signed checkpoints separately from the collector. It checks the collector's signature and journal continuity, signs the result with its own key, and publishes it to a Telegram channel. Run it on a separate server with read-only access to the collector's witness endpoint.
The technical result includes retained journal prefixes, challenge responses, signature checks, Merkle inclusion/consistency checks and signed continuity outcomes. For a witness operated by another custodian, retain the custodian and key-control record with its fingerprint. Separate keys and separate custody describe different parts of the setup. The verifier reports that a second key retained the journal head and up to which record; the custodian's key-control record shows who holds that key. The witness journal is a supporting check; the minimum for evidence is third-party time. The channel posts add external time: Telegram dates each public post, and the verifier reads those dates itself.
Diagram as text
- Collector → Witness (signed checkpoint: record count + head hash)
- Witness → Witness journal, own key
- Witness → Telegram channel (signed post via its own bot)
- Evidence ZIP → verify.py
- Witness journal, own key → verify.py
- Telegram channel → verify.py (t.me/s page read live, or Desktop export)
On this page
What the witness holds#
| The witness has | The witness never has |
|---|---|
| A read-only witness token for one workspace | The collector's Telegram session or API credentials |
| Its own Ed25519 key and journal | The collector's vault, signing key or panel token |
| Its own Telegram bot token | Message content: the head is a record count and a hash |
The token is created in More tools → Extras → Independent witness, shown once and stored only as a
SHA-256. It opens exactly one endpoint, GET /api/witness/head, which returns a freshly
signed checkpoint plus signed content-free collection counters and operational health.
It cannot open the panel, read message content or change settings, and the
panel token is not accepted there. Revoke a token on the same page. The collector records
when a new witness key starts checking (witness.seen) and shows the last check per token;
a witness that has not checked within 2.5 intervals is marked overdue.
New witnesses send a random challenge on each poll; the capture statement echoes it under the collector signature. Counters are bound to the exact checkpoint and are included in signed witness posts. Legacy heads remain accepted by the standalone witness. Journal growth alone is never counted as a new message.
What it checks and records#
Every interval (10 minutes by default) the witness:
- fetches the head itself (the collector cannot push or skip it);
- verifies the collector's signature, the pinned collector key (
--collector-fingerprint, or the first key seen), a nondecreasing count and an unchanged head at an unchanged count. Merkle inclusion and consistency proofs verify that a growing journal extends the retained checkpoint. Once continuity proofs have been used, removing them is rejected; - appends a signed record to its own journal:
witness.anchorwith statusok,key_changed,rollback(fewer records than before),fork(same length, different head) orinvalid(the answer failed verification), orwitness.no_responsewhen the collector did not answer; - posts the result to the channel, signed, including "no answer" while the witness is
running and can reach the Bot API. The post ID is recorded (
witness.posted), a failed post too (witness.post_failed).
A post looks like this; the last line carries the signed statement:
TgWitness witness #42 · journal head
Collector 3fa9c2d1e0b4a7f6: 18234 records
Head 9b1f…c07e
2026-10-28T19:40:00.123+00:00
TGW1.eyJhdCI6…<statement>.<signature>
Run a witness#
You need a Telegram bot (create one with @BotFather), a channel where that bot is an administrator, and the collector's address reachable from the witness — over HTTPS outside a private network (see the HTTPS profile in deployment).
Open More tools → Extras → Independent witness → Configure in the panel. Three steps cover
read-only access, your channel and interval, then launching the witness. Publication
policy, optional HTTP/SOCKS5 proxy and custom Bot API address are under Advanced settings. The form
downloads witness.json with this workspace's collector key pinned. Download the newly
created read-only token with Save access file as witness-token.txt; place it and a bot-token.txt
created on the witness host beside that JSON. The collector never receives the bot token.
Downloading does not start a service or publish a message. No hosted project witness is
implicitly enrolled.
python -m tgwitness.witness run --config witness.json --check-config
python -m tgwitness.witness run --config witness.json
python -m tgwitness.witness fingerprint --config witness.json
The first command checks configuration and secret files without network requests or key creation. Paths in JSON are relative to that file; CLI/environment paths are relative to the working directory. Retain the witness fingerprint outside its host. The collector's last-poll indicator confirms a request only; publication is reported by Proof or checked in the witness journal and channel.
If the panel stays behind an SSH tunnel, expose only the scoped witness endpoint on a
separate HTTPS hostname with this Caddy example.
The default workspace then uses https://witness.example.org, other workspaces use
https://witness.example.org/profiles/ID. Tokens are still required; the panel and its
other API routes are not forwarded by that virtual host.
Choose all for regularly published checkpoints. A five-minute interval means about 288
posts per workspace per day. changes/problems deliberately leave some checks unpublished.
MTProxy is for the collector's Telegram client. Witness HTTP polling and Telegram's HTTPS
Bot API use their own direct/HTTP/SOCKS5 route (Bot API).
Next to the collector, with Docker (same host — independent process and key, but the
same operator): put the values in .env and start the profile.
TGWITNESS_WITNESS_TOKEN=tgww_...
TGWITNESS_WITNESS_BOT_TOKEN=123456:ABC...
TGWITNESS_WITNESS_CHANNEL=@your_witness_channel
# another workspace: TGWITNESS_WITNESS_COLLECTOR=http://tgwitness:8787/profiles/<workspace ID>
docker compose --profile witness up -d
docker compose logs witness # prints the witness key fingerprint
With a published image use docker compose --project-directory . -f deploy/compose/compose.image.yaml --profile witness up -d.
On someone else's server (separate custody): copy the repository there, set
TGWITNESS_WITNESS_COLLECTOR=https://your-collector.example.org plus the three values above
in .env, then
docker compose --project-directory . -f deploy/compose/compose.witness.yaml up -d
or without Docker:
python -m tgwitness.witness run --collector https://your-collector.example.org \
--token-file witness-token.txt --bot-token-file bot-token.txt --channel @your_witness_channel
Publish to Discord#
A witness can post to a Discord channel instead of Telegram. In Discord, open
Edit Channel → Integrations → Webhooks, create a webhook and copy its URL. In
the panel, choose Discord webhook · your channel in step 2. On the witness host,
save the URL as discord-webhook.txt next to witness.json; it never reaches the
collector.
python -m tgwitness.witness run --collector https://your-collector.example.org \
--token-file witness-token.txt --discord-webhook-file discord-webhook.txt
A witness has one publisher: a Telegram channel or a Discord webhook, not both. Posts
carry the same signed statement and cannot ping anyone. A post longer than Discord's
2,000 characters is replaced by a short line with the full check attached as
witness-check.txt. Each post ID is recorded as witness.posted. verify.py --channel
reads Telegram channels only, so for Discord keep the witness journal: it holds every
check. Discord posts give the verifier no external time.
Options#
| Option | Environment | Default | Meaning |
|---|---|---|---|
--interval |
TGWITNESS_WITNESS_INTERVAL |
10 | Minutes between checks, 1–1440 |
--timeout |
_TIMEOUT |
30 | Seconds to wait for the collector and the Bot API, 5–600 |
--post |
_POST |
all |
all: every check; changes: a new head or a problem; problems: only problems and missing answers |
--title |
_TITLE |
TgWitness witness |
First words of every channel post |
--collector-fingerprint |
_COLLECTOR_FINGERPRINT |
– | Pin the collector key instead of trusting the first answer |
--proxy |
_PROXY |
direct | socks5://host:port or http://host:port |
--bot-api |
_BOT_API |
https://api.telegram.org |
Bot API address, e.g. a local Bot API server |
--data-dir |
_DATA |
witness-data |
Witness key and journal |
--config |
_CONFIG |
– | JSON file with any of the options above |
The collector address, tokens and channel come from --collector, --token or
--token-file, --bot-token or --bot-token-file, --discord-webhook-file and --channel,
or _COLLECTOR, _TOKEN, _TOKEN_FILE, _BOT_TOKEN, _BOT_TOKEN_FILE,
_DISCORD_WEBHOOK_FILE and _CHANNEL, which keeps secrets out of the process list.
A config file uses the option names with underscores, plus texts, which replaces the words
of the channel posts:
{"collector": "https://your-collector.example.org", "token_file": "witness-token.txt",
"bot_token_file": "bot-token.txt", "channel": "@your_witness_channel",
"interval": 5, "timeout": 30, "post": "changes", "title": "Partner witness",
"texts": {"ok": "journal head", "no_response": "no answer from the collector", "records": "records"}}
texts keys: ok, key_changed, rollback, fork, invalid, no_response, collector,
records, head. The command line wins over the environment, the environment over the file.
Unknown options or text keys stop the witness with a message instead of being ignored.
Wording never affects verification: verify.py checks the signed token at the end of every
post. With --post changes or problems, checks that were not posted are still in the
witness journal and verify.py lists them as never posted; the start record names the
policy. Every check still appears in the journal, so fewer posts mean fewer times dated
by Telegram, not fewer checks.
Without a channel the witness still keeps its journal. Keep the witness key fingerprint
(python -m tgwitness.witness fingerprint) somewhere else.
Public proof page for several workspaces#
python -m tgwitness.proof witnesses up to 32 workspaces at once and serves a read-only
page with the latest signed check of each. Every workspace gets its own witness key and
journal under the data folder and a pinned collector key; posting to a Telegram channel
is optional per workspace. Start from
proof.config.example:
| Field | Meaning |
|---|---|
title |
Page title, 1–100 characters |
data_dir |
Witness keys and journals, relative to the file; default proof-data |
interval, timeout |
Minutes between checks (1–1440, default 5); seconds to wait (5–600, default 20) |
workspaces[].id, label |
Short lowercase alias and the name shown |
workspaces[].collector |
Collector address; other workspaces end in /profiles/<workspace ID> |
workspaces[].collector_fingerprint |
Required, different for each workspace |
workspaces[].token_file |
File with that workspace's read-only witness token |
workspaces[].channel, bot_token_file |
Optional, together: post each check to a channel |
workspaces[].proxy, bot_api |
Optional route and Bot API address |
python -m tgwitness.proof --config proof.json --check-config
python -m tgwitness.proof --config proof.json --host 127.0.0.1 --port 8790
The first command validates the file and the token files without opening a connection. The page answers only GET and HEAD:
/shows every workspace; a workspace without a check for 2.5 intervals is marked stale./api/proofreturns the same as JSON./api/proof/<id>downloads the latest signed statement (tgwitness-public-proof-v1): witness record number and hash, status, pinned collector key, checkpoint, collection counters and whether the channel post succeeded, signed by that workspace's witness key./healthzanswers 503 when a workspace's monitor has stopped.
Give the page its own hostname, as in
Caddyfile.proof.example. For verification, export a
workspace's witness journal with
python -m tgwitness.witness export --data-dir proof-data/<id> --out witness.zip and use it
as described below.
Verify#
On the witness side, export its journal:
python -m tgwitness.witness export --out witness.zip
# Docker (add -f deploy/compose/compose.witness.yaml on a witness server):
docker compose exec witness python -m tgwitness.witness export --out /witness/witness.zip
docker compose cp witness:/witness/witness.zip .
Then, anywhere, with the collector's signed ZIP and the address of the public channel:
python verify.py tgwitness-evidence.zip --fingerprint COLLECTOR_SHA256 \
--witness witness.zip --witness-fingerprint WITNESS_SHA256 --channel https://t.me/s/your_witness_channel
--channel also accepts a Telegram Desktop export (Export chat history → JSON gives
result.json) or a saved copy of the page; these check the post content but give no
external time.
verify.py checks the witness journal (chain and signatures), then that every head the
witness saw is part of the exported journal: the record at that count must have exactly
that hash. A head that does not match fails verification — the journal was changed after
the witness saw it. It also reports heads seen after the export, anomalies the witness
recorded, answers that failed, periods whose matching checkpoints are present in this
export ("Witnessed from X to Y") and gaps. Later checkpoints do not extend those periods.
The result includes the last matched record number and the number of trailing records
without a matching checkpoint. Only answers signed by the export's own key count: an export signed
by a key the witness never saw is reported as not witnessed, and without --fingerprint its
signer stays unpinned. With --channel every signed post must match the witness journal
record by record: changed posts fail verification, missing posts are listed. Matching the
token authenticates the content; the date is outside the signed token.
With a live https://t.me/s/… or https://telegram.me/s/… address the verifier reads
each post's date from the page at verification time. Telegram sets that date; dates of
edited posts are not used. The earliest such date of a post at the export head is external
time for the last record, which meets that condition of the minimum for evidence. Dates
from any other source, such as a supplied result.json, a saved page or another web
address, are supplied metadata, not independent time; the result names where its post
dates came from (post_date_verification).
Require a witnessed export boundary#
For a handover that must include a witnessed final record, add --require-witness:
python verify.py tgwitness-evidence.zip --fingerprint COLLECTOR_SHA256 \
--witness witness.zip --witness-fingerprint WITNESS_SHA256 --require-witness
This requires the independently retained witness fingerprint, a key other than the
collector key, and a matching checkpoint at the exact end of this export. A checkpoint
covering only an earlier prefix is insufficient. Pause collection, let the witness
observe the final state, and export before further journal writes; if the journal changes, retain another checkpoint and
export that state. A later checkpoint alone cannot verify a shorter export's final hash.
When --channel is also supplied, missing claimed posts or an empty match set fail this
strict check. Without the flag, ordinary integrity checks still report unwitnessed
records without rejecting an otherwise intact archive.
Keep the witness journal and its pinned key separately. Online checks verify continuity between checkpoints; offline verification compares every retained checkpoint with the export. Legacy heads without continuity proofs retain the offline comparison and are reported without online continuity verification. The report lists witness downtime and failed publications by interval.
Daily seals and unavailable timestamp calendars#
The witness seals the previous UTC day's journal boundary and submits the hash of that signed seal to OpenTimestamps. A calendar submission is pending evidence; only independently checked Bitcoin commitments receive confirmation in the verifier.
If all calendars fail, the signed seal and unsuccessful attempt remain in the journal. The hourly maintenance pass retries that original record, including after a restart or a change of date. It scans at most 32 seals, submits at most two missing submissions and spends at most 60 seconds on retries per pass. A persistent cursor rotates through older seals. Retained submissions follow the existing proof-upgrade path.
A retry does not rewrite the seal, change its original date or claim that the
calendar received it earlier. A later Bitcoin commitment remains a later external
confirmation. Missing proofs remain none; pending proofs remain pending until
the verifier checks them independently.