# Evidence Verification: SHA-256 & Ed25519

Canonical page: https://phishdestroy.io/tgwitness/docs/reference/how-it-works/

Study the TgWitness evidence chain: canonical records, SHA-256 hashes, Ed25519 signatures, checkpoints and witnesses, with the verifier's exact formulas.

[Project context and measured scale](https://phishdestroy.io/tgwitness/docs/reference/overview/)

[Documentation index](https://phishdestroy.io/tgwitness/llms.txt)

Hash chain, signatures, checkpoints and witnesses explained with the exact formulas the verifier uses.

[TgWitness](https://github.com/phishdestroy/TgWitness/blob/main/README.md) / [Documentation](https://github.com/phishdestroy/TgWitness/blob/main/docs/README.md) · [Evidence and verification](https://phishdestroy.io/tgwitness/docs/reference/evidence/)

![Evidence & verification](https://phishdestroy.io/tgwitness/assets/chapter-evidence.svg?v=e49c65feab6c)

TgWitness preserves what a collecting account observed, links those observations into a signed journal and lets another person verify an export against a trusted key, external time from a third party and an earlier retained checkpoint.

The [local documentation website](https://github.com/phishdestroy/TgWitness/blob/main/docs/internal/PUBLISHING.md#preview-the-website-locally) adds interactive examples at `/docs/concepts/`, a checkpoint decision explorer at `/docs/witness/`, and walkthroughs for [Case Board](https://phishdestroy.io/tgwitness/docs/reference/case-board/), [report design](https://phishdestroy.io/tgwitness/docs/reference/case-reports/) and [handover extracts](https://phishdestroy.io/tgwitness/docs/reference/evidence/#handover-extract). All example messages, counts and delays are fictional. Hashes in the chain sandbox are calculated with SHA-256 in the browser. Nothing is sent to Telegram.

**On this page**

- [A message changes; observations accumulate](https://phishdestroy.io/tgwitness/docs/reference/how-it-works/#a-message-changes-observations-accumulate)
- [What a hash covers](https://phishdestroy.io/tgwitness/docs/reference/how-it-works/#what-a-hash-covers)
- [What an earlier checkpoint adds](https://phishdestroy.io/tgwitness/docs/reference/how-it-works/#what-an-earlier-checkpoint-adds)
- [Where a witness belongs](https://phishdestroy.io/tgwitness/docs/reference/how-it-works/#where-a-witness-belongs)
- [Test delivery against known actions](https://phishdestroy.io/tgwitness/docs/reference/how-it-works/#test-delivery-against-known-actions)
- [Pick a workflow](https://phishdestroy.io/tgwitness/docs/reference/how-it-works/#pick-a-workflow)

## A message changes; observations accumulate

Sequence diagram · Telegram → Collector: New message: Meet at 10:00; Collector → Signed journal: Append message.new; Telegram → Collector: Edit: Meet at 11:00; Collector → Signed journal: Append message.edited; Telegram → Collector: Deletion notice; Collector → Signed journal: Append message.deleted; Note on Signed journal: Original + edit + deletion observation remain · Telegram · Collector · Signed journal · New message: Meet at 10:00 · Append message.new · Edit: Meet at 11:00 · Append message.edited · Deletion notice · Append message.deleted · Original + edit + deletion observation remain

**Diagram as text**

1. Telegram → Collector: New message: Meet at 10:00
2. Collector → Signed journal: Append message.new
3. Telegram → Collector: Edit: Meet at 11:00
4. Collector → Signed journal: Append message.edited
5. Telegram → Collector: Deletion notice
6. Collector → Signed journal: Append message.deleted
7. Note on Signed journal: Original + edit + deletion observation remain

This simplified sequence assumes Telegram delivered each update and the selected account could see it. Operational events also share the journal. A deletion notice does not supply the deleter or an exact deletion time. Repeated deliveries are separate observations; there is no journal-wide duplicate suppression.

## What a hash covers

![Observe, encode, hash and sign: each new event includes the preceding hash.](https://phishdestroy.io/tgwitness/assets/evidence-chain-animated.svg?v=368c25a3be9c)

Read the formula from the inside out: **C** turns the nine fields into exact bytes; **SHA-256** produces their digest; **hex** is how that digest is stored. The previous hash is already inside the event. **unhex** turns the stored hash back into the 32 bytes that Ed25519 signs.

[Static chain diagram](https://github.com/phishdestroy/TgWitness/blob/main/docs/assets/presentation/evidence-chain-static.svg)

Let C(ei) be the canonical UTF-8 JSON of the nine event fields. The first `previous_hash` is 64 zero characters. Each later record includes the preceding record's hexadecimal hash:

hi = hex(SHA256(C(ei)))

σi = Ed25519.Sign(sk,unhex(hi))

The signature covers the 32 raw digest bytes. The hash input contains exactly `seq`, `observed_at`, `source_at`, `kind`, `chat_id`, `message_id`, `actor_id`, `payload` and `previous_hash`. Object keys are sorted; whitespace and ASCII escaping are omitted; NaN and infinity are rejected. See the [exact encoding](https://phishdestroy.io/tgwitness/docs/reference/evidence/#event-canonicalization).

Flow diagram · 64 zero characters → Record 1 / hash h1; Record 1 / hash h1 → Record 2 includes h1 / hash h2; Record 2 includes h1 / hash h2 → Record 3 includes h2 / hash h3; Record 3 includes h2 / hash h3 → Signed checkpoint: count 3, head h3 (retain elsewhere) · 64 zero characters · Record 1 / hash h1 · Record 2 includes h1 /hash h2 · Record 3 includes h2 /hash h3 · Signed checkpoint:count 3, head h3 · retain elsewhere

**Diagram as text**

1. 64 zero characters → Record 1 / hash h1
2. Record 1 / hash h1 → Record 2 includes h1 / hash h2
3. Record 2 includes h1 / hash h2 → Record 3 includes h2 / hash h3
4. Record 3 includes h2 / hash h3 → Signed checkpoint: count 3, head h3 (retain elsewhere)

| Change to the supplied journal | What detects it |
| --- | --- |
| Alter record 2 while leaving its saved hash | Recomputed event hash differs; its signature no longer covers the changed event |
| Rebuild the altered record and every later hash | The original signatures fail; a retained checkpoint at the affected boundary also disagrees |
| Remove the tail but keep the remaining prefix intact | An earlier retained checkpoint beyond the supplied prefix reveals that the export is too short |
| Re-sign a replacement journal with another key | A separately trusted key fingerprint rejects the replacement identity |

![Changing a saved field changes its digest; rebuilding hashes does not restore the original signatures.](https://phishdestroy.io/tgwitness/assets/evidence-tamper-animated.svg?v=5ca92399bea5)

**Try the logic on record 2:** change `Meet at 11:00` to `Meet at 12:00` in the saved event. Its recomputed hash no longer matches. Recalculating the later chain can repair its links, but cannot make the original signatures cover the new digests. An observed Telegram edit, by contrast, becomes a new journal record.

[Static change diagram](https://github.com/phishdestroy/TgWitness/blob/main/docs/assets/presentation/evidence-tamper-static.svg)

Hash links alone do not prevent someone from recalculating a replacement chain. Trust comes from checking signatures under an independently trusted key, external time from a third party that fixes the journal head, and references retained outside the collector.

## What an earlier checkpoint adds

![Retain count 3 and head h3; a later export of 4 records is checked at position 3.](https://phishdestroy.io/tgwitness/assets/evidence-checkpoint-animated.svg?v=e68f4e7be4b9)

**The reference stays still while the journal grows.** If the checkpoint says “3 records, head h3”, a four-record export can pass by matching h3 at position 3. Its newest head is h4, which is expected to differ. An export of only two records fails.

[Static checkpoint diagram](https://github.com/phishdestroy/TgWitness/blob/main/docs/assets/presentation/evidence-checkpoint-static.svg)

After verifying the checkpoint signature, require:

Nexport ≥ Ncheckpoint and hexport[Ncheckpoint] = Hcheckpoint

An export may extend beyond a checkpoint. It must agree at the retained boundary. The collector key signs the checkpoint, so the collector could sign another one. It binds the records only if the recipient obtained it before the archive, through another channel; the minimum for evidence also needs external time from a third party. The real verifier also checks every event's sequence, previous link, hash and signature. Comparing only the final stored head would miss an altered interior record whose saved hash was not updated.

## Where a witness belongs

Flow diagram · Collector / account session / key A → Read-only checkpoint endpoint; Witness / pinned collector key / own key B → Separate signed witness journal; Witness / pinned collector key / own key B → Read-only checkpoint endpoint (Request a check); Read-only checkpoint endpoint → Witness / pinned collector key / own key B (Signed answer); Witness / pinned collector key / own key B → Channel with signed TGW1 posts (Bot API / own token) · Host A · Host B · Collector / accountsession / key A · Read-only checkpointendpoint · Witness / pinned collectorkey / own key B · Separate signed witnessjournal · Channel with signed TGW1posts · Request a check · Signed answer · Bot API / own token

**Diagram as text**

1. Collector / account session / key A → Read-only checkpoint endpoint
2. Witness / pinned collector key / own key B → Separate signed witness journal
3. Witness / pinned collector key / own key B → Read-only checkpoint endpoint (Request a check)
4. Read-only checkpoint endpoint → Witness / pinned collector key / own key B (Signed answer)
5. Witness / pinned collector key / own key B → Channel with signed TGW1 posts (Bot API / own token)

The witness records rollback, a different head at the same count, changed keys, invalid answers and missing responses. To confirm that every earlier record is unchanged, compare the export with retained checkpoints. A witness on another host avoids sharing the collector's host outage; a separate operator gives additional independence. The verifier checks that the witness key differs from the collector key; the custodian's key-control record shows who holds it. Telegram dates each post in a public channel, and `verify.py --channel https://t.me/s/…` reads those dates as external time.

The witness attests to the collector's reported journal state. Use a controlled delivery test to measure which Telegram actions reached a collecting account. See [witness setup](https://phishdestroy.io/tgwitness/docs/reference/witness/).

## Test delivery against known actions

Use a controlled group, distinct collecting accounts and a fresh marker. Send, edit and delete deliberately, checking capture between stages. Define the expected actions and a cutoff before inspecting the results.

R = |observed∩expected| / |expected| Δ t = treceipt - taction

Only matched expected actions count; duplicate receipts do not increase the numerator. The denominator must be nonzero. A missing receipt has no measured delay. Document clock uncertainty; use your own controlled deletion action time, because Telegram does not provide the exact deletion time. A result such as 5/6 (83.3%) describes the test actions, not the completeness of all Telegram traffic.

## Pick a workflow

The [complete investigation walkthrough](https://phishdestroy.io/tgwitness/docs/reference/investigation/) follows an incident across a channel, group, bot and private chat:

1. On a dedicated collecting account, enable whole-account Investigation mode and inventory accessible chats. Use selected chats or a folder for a main account.
2. Acquire journal snapshots, per-chat full history and preserved attachments.
3. Keep live changes and any deliberate panel interactions with their receipts.
4. Follow numeric sender IDs, reply relationships, repeated destinations and file hashes through cited records and people profiles.
5. Add source-linked notes and collections in Case Board. Reconstruct a cross-chat timeline with both timestamps and explicit gaps.
6. Compare other account workspaces while keeping their origins and keys separate.
7. Assemble and verify the signed journals, profiles and history exports with case notes.

The website's `/docs/cases/` guide includes an interactive case map and variants for bot disputes, removed messages and participants changing names. Case Board keeps notes and collections within a workspace. Group exports collect separate workspace packages; cross-workspace correlation and a combined timeline remain analyst work.

[Completed validation and remaining work](https://phishdestroy.io/tgwitness/docs/reference/verification/) · [Export and verify](https://phishdestroy.io/tgwitness/docs/reference/evidence/#investigation-handoff) · [Start with one account](https://phishdestroy.io/tgwitness/docs/reference/quickstart/)
