Knowledge Base

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

The Item Code

The item code, a 16-character Crockford base32 short name for an item (the leftmost 75 bits of its item_hash and a check symbol), how to check it from a proof, how Truestamp issues, shows and accepts it, how a typed code is read, and what a matching code does not prove.

Overview

An item code is a short name for an item, for people and links: 16 uppercase characters with no separator, such as 9WBPKNV7SCP87VZW. The first 15 symbols spell the leftmost 75 bits of the item’s item_hash, 5 bits each, in the Crockford base32 alphabet 0123456789ABCDEFGHJKMNPQRSTVWXYZ (no I, L, O or U), and the 16th is a check symbol computed over the other 15. The Truestamp verification specification (SPEC.md, section 3.9) defines it. Truestamp gives an item its code at submission, holds at most one item per code across every team, and accepts the code wherever an item is looked up.

A code is a name, never evidence. No proof carries it, no verification step reads it, and it is never a verdict input. Anyone holding an item’s proof can recompute the code from the item hash the proof lets them recompute, and a match shows only that the item hash begins with those 75 bits. Anything that needs to identify an item compares the whole item hash. The item hash itself, and the record it is the hash of, are described in the item record and its hash.

How the code is computed

The code is computed from the 32 bytes of the item hash and from nothing else:

  1. Take the leftmost 75 bits of the item hash, the most significant bit of the first byte first, as 15 values of 5 bits each.
  2. Compute the check value over those 15 values in GF(2^5) with the modulus x^5 + x^2 + 1: start with r = 0, and for each value v in order set r to m(r) XOR v, where m(v) shifts v left one bit and, if the result is 32 or more, XORs it with 37. The check value is m(r), one final multiplication that lets the check catch an exchange of the last two symbols.
  3. Write the 15 values and then the check value with the alphabet, each value as the character at its position, as one run of 16 characters.

That run, in uppercase with no separator, is the code’s only spelling in output. For example, the item hash 4f1769d767cb2c83eff1c48165939090d42fac433c5eabe6f02c5cf9d025181b has the code 9WBPKNV7SCP87VZW. The specification’s vectors/item-codes.json, in the truestamp-verification repository, lists known answers, and each of Truestamp’s verifiers is tested against every one of them.

Checking a code from a proof

An item’s proof carries everything needed to check its code, though never the code itself:

  1. Recompute the claims hash from the proof’s subject.claims, as SHA-256 over the byte 0x10 followed by the claims in JSON Canonicalization Scheme form, and compare it with subject.record.claims_hash.
  2. Recompute the item hash from subject.record, the three-member record of claims_hash, id and witness_hashes, as SHA-256 over the byte 0x11 followed by the record in canonical form, and compare it with subject.item_hash.
  3. Compute the code of the recomputed item hash as above, and compare it with the code you were given.

Use the item hash you recomputed, never the one the proof declares, as every verifier does (see verify a proof). The item page and the verify page show the code as the item’s name, never in place of its item hash and never with a pass status; the verify page says it is computed from the item’s hash and that anyone holding its proof can check it.

Reading a typed or pasted code

Truestamp reads a typed or pasted code exactly as the specification allows, and nothing more:

  • Letters may be in any mix of case, and the code comes back in uppercase.
  • I and L, in either case, read as 1, and O, in either case, reads as 0. A U is never read as anything.
  • One plain space, hyphen or underscore may sit at each of the three places between the four groups of four, and nowhere else: not before the first symbol, not after the last, not inside a group, and never two together. A code as typed is therefore at most 19 characters.
  • Nothing is trimmed. A tab, a line feed, a carriage return, any other ASCII character and any character that is not ASCII (a Unicode dash, a no-break space or a look-alike letter among them) make the value not a code.

A value of that shape whose 16 symbols fail the check, or that holds a U, is a typo. The check catches every single wrong symbol and every exchange of two different symbols, at any distance, so a mistyped code is refused rather than read as another item’s.

Where Truestamp issues and accepts it

  • Issued at submission. The code is fixed in the same step that computes the item hash. Truestamp draws the item’s id there, after the claims and the witnesses are fixed, and draws a new id when the code is already taken, at most three ids in all. A submission that finds no free code creates nothing and is refused as item_code_unavailable (HTTP 409 on the JSON:API), which a later request can retry. Redaction keeps the code with every hash, and Truestamp checks every stored code against its item hash once an hour.
  • Shown. The item page and the verify page show the code in monospace, in four groups of four set apart by spacing alone, so a double-click copies the 16 characters; item lists, the dashboard and search results show it under the item’s name.
  • Links. An item’s canonical pages are https://www.truestamp.com/items/<CODE> and https://www.truestamp.com/verify/item/<CODE>. Either page also takes the item’s id or its item hash, or the code in any spelling the reading rule accepts, and moves to the canonical link once the item has loaded for a reader allowed to see it. A missing item and one you may not read look the same, whatever the reference. A typo on the verify page says the code has a typo and opens a search for it.
  • APIs. Item reads on the JSON:API (GET /api/json/items/:id), GraphQL (getItem), the MCP server and the in-app chat take the item’s id, its code or its item hash, and every response carries item_code (itemCode in GraphQL) beside the item’s UUIDv7 id. A change to an item names it by its id. The MCP server and the chat say when a code has a typo; the JSON:API and GraphQL answer as for any item that is not found.
  • Proof files. An item’s proof downloads as <CODE>.proof.json.
  • The CLI. The command-line client shows the code the server issued in truestamp items create, truestamp items get and the console’s new-item card, and gives each row of truestamp items list its id and its code, whole. For an item’s proof, truestamp verify and truestamp inspect compute the code from the item hash recomputed from the proof’s record, and show it captioned “Item code” on the line after that whole item hash, as a name for the item and never a check. truestamp items get, truestamp items update and truestamp proofs get take an item by its code, in any spelling the reading rule accepts, by its id or by its item hash, and refuse an item or proof the server answers that does not carry it; truestamp proofs get --to-file writes an item’s proof as <CODE>.proof.json. truestamp items create reports item_code_unavailable as a refusal the same request may retry.

Limitations

  • A matching code shows only that the recomputed item hash begins with those 75 bits. It does not show that a proof passes, who issued it, that the item exists, or when it was submitted.
  • Two different item hashes can share a code. Truestamp’s service holds at most one item per code, but whoever chooses an item’s id could make two item hashes share a code with about 2^37.5 work, so only equal item hashes are the same item.
  • The code is not the item’s id. The id is a UUIDv7 that Truestamp records (see UUIDv7 identifiers); the code is computed from the item hash, which covers the id.