Skip to content
TrackJet

tjvt2 · specification

TrackJet Verifiable Timeline

A tamper-evident seal for shipment event histories. Every event is hashed into an append-only SHA-256 chain at the moment it is recorded; any later edit, reorder or deletion of past events breaks verification. Check any tracked chain at /verify.

Construction

h(0) = SHA256( "<spec>:" || shipment_uuid || ":" || primary_tracking )
h(n) = SHA256( h(n-1) || canonical(event_n) )          n = 1..N

canonical(event) is deterministic JSON with this exact key order, no insignificant whitespace, unescaped UTF-8 and slashes:

{"v":"tjvt2","seq":<n>,"leg_order":<int>,"occurred_at":"<RFC3339>",
 "status":"<string>","description":"<string>","location":<string|null>,
 "country_code":<string|null>,"provenance":"sourced|estimated|declared"}

Events are ordered by (occurred_at, leg_order, ingest index) — the same stable order the timeline UI renders. seq binds each event to its position, so swapping two otherwise-identical events also breaks the chain.

tjvt2 (current, since 2026-07-27) appends provenance as the last key — an event's class (sourced / estimated / declared) is sealed and can no longer be changed after the fact. tjvt1 (since 2026-06-10) is identical without that key and stays verifiable forever: the spec version is stored per seal in the database, not in the running code. A chain born under tjvt1 keeps its tjvt1 genesis even when later events are sealed under tjvt2.

What a valid result proves — and what it doesn't

  • Proves: the event history stored today is byte-identical to what TrackJet recorded at ingest time — nothing was edited, reordered or deleted afterwards.
  • Does not prove: that the carrier's original data was correct. The seal covers TrackJet's record from the moment of ingest, not reality before it.
  • Seals are written after the database commit, append-only. Events that arrived seconds ago can be briefly unsealed ("unsealed tail") — that is reported as such, not as tampering.
  • The verifier and the proof API expose integrity metadata only (validity, counts, digests) — never event contents.

Programmatic access

  • GET /api/v1/shipments/{uuid}/proof — seal list (hashes only) + verification verdict (API key required; see API docs).
  • MCP server verify_timeline — same verdict for AI agents (MCP docs).

Current spec version tjvt2 · hash function SHA-256 · tjvt1 published 2026-06-10, tjvt2 on 2026-07-27. Changes to the canonical form will bump the version prefix; existing seals remain verifiable under their original version.