Knowledge Base

Browse the concepts behind Truestamp. Follow the links between concepts, or search across everything.

UUIDv7 Identifiers

Truestamp's record ids, items included, are UUIDv7s (RFC 9562), with four named exceptions such as an API key's random UUIDv4; 36 lowercase hyphenated characters, stored as 16 bytes, sortable by the millisecond time in its leading 48 bits, which is recorded, never trusted.

Overview

Every record Truestamp keeps gets its id when it is created, and that id is a UUIDv7: items, blocks, entropy observations, commitments, epochs, teams, users and the rest. There are four exceptions: an API key, whose id is a random UUIDv4; a sign-in token, which is keyed by its JWT id; and a knowledge-base concept and each of its sections, which are keyed by their path. UUIDv7 is the time-ordered UUID version of RFC 9562. An id is written in the usual 36-character hyphenated form, in lowercase:

018e90d8-06e8-7f9f-bfd7-6730ba98a51b

An item also has an item code, a 16-character short name computed from the leftmost 75 bits of its item hash and a check symbol. The code is a second way to name the item, not a second id, and no proof carries it; the search page tells the two apart by their shape.

What counts as a UUIDv7

Where Truestamp decides whether a value it was given is an id (search, item references, the verify, block and entropy pages, proof generation and the id utilities), it reads only the whole canonical text: 8, 4, 4, 4 and 12 hex digits separated by hyphens, the version digit 7, and a variant digit of 8, 9, a or b. Hex digits may be in either case, and an id is normalized to lowercase. Anything else is not an id: a UUID of another version, the 32-digit form without hyphens, a braced or urn:uuid: form, surrounding or embedded whitespace, or the raw 16 bytes. The test reads the text alone and never decodes it first.

Time-ordered and sortable

The leading 48 bits of a UUIDv7 are a Unix time in milliseconds. After them come the 4 version bits, a 12-bit fraction of a millisecond that keeps ids in order within one millisecond, the 2 variant bits, and 62 random bits. A verifier reads only the 48-bit time. Because the time leads, sorting ids as text or as bytes sorts them in the order they were generated, and new rows land at the end of an index instead of scattering across it. Truestamp generates ids with system time at sub-millisecond precision, which is what fills that 12-bit fraction.

The time inside an id can be read back from the id alone, as a Unix millisecond value or a date and time. It records when the id was generated. It is a convenience for ordering, not evidence: a proof’s timing comes from its submission window, whose two edges a verifier reads from public chains and entropy sources during verification. Inside a proof, an id and the time in it are values Truestamp recorded, bound by the record hashes and the signature, and never an edge: when the time inside the subject’s id falls outside a window a run establishes, the report adds one informational row, recorded_time_outside_window, and the verdict does not change. See domain-separated hashing for how the hashes that carry that weight are built.

Storage

An id is stored in a Postgres uuid column as its 16 bytes, not as text. A raw query against such a column takes the canonical text and reads the 16 bytes back, which convert losslessly to the same lowercase text.

Citations

  1. RFC 9562: Universally Unique IDentifiers (UUIDs). Defines UUIDv7 and the layout of its leading 48-bit millisecond time.