Unique at scale, with no central coordination
Several processes must be able to generate identifiers in parallel without consulting each other and without risking a collision.
A short code, signed and checkable at a glance
A unit’s identifier has to survive a small label, a mediocre camera and somebody typing it by hand. This is what is required of it and how it is built.
Five requirements that settle the design
The format is not an aesthetic choice: each requirement rules alternatives out. Together the five leave very few options open.
-
-
Not guessable
Knowing one code must not let you derive others. A simple sequence would be enumerable: someone would print valid “future” codes.
-
Checkable without consulting the database
The signature validates on its own. An invented code is discarded in microseconds of CPU, and the registry only serves codes that exist.
-
Short
It has to fit in a small QR with enough error correction to tolerate scuffs, humidity and a curved label.
-
Readable by a person
If the camera fails, the code is typed by hand on the lookup page. That forces grouped characters and a check digit.
Anatomy of the identifier
What travels inside the code is twenty bytes in four parts. Each one answers one of the requirements above.
- 1 byte Version
- 1 byte Key epoch
- 10 bytes Unique id
- 8 bytes Truncated signature
The signature protects against inventing codes, not against copying one: a copied code is valid. Other layers work against copying, and they are explained under Security and trust.
From twenty bytes to something you can read and type
The text uses Base32 Crockford, an alphabet that avoids the characters people confuse and that brings its own check digit.
The check digit is validated in the browser, before any service is called: a typing mistake is flagged instantly and does not spend a lookup.
The URL is uppercase on purpose. A QR’s alphanumeric mode encodes more information per module than byte mode, so the same content fits in a QR one or two versions smaller: it scans sooner and tolerates more damage. Scheme and domain are case-insensitive, and the server accepts the path in uppercase.
A short domain matters too: fewer characters mean fewer modules, and fewer modules let you print smaller at the same level of error correction.
TRZ-9FXK-2M4Q-J8TV-QH3N-7WPD-BL5R-XCK
URL inside the QR (uppercase, alphanumeric mode):
HTTPS://T.EXAMPLE/V/9FXK2M4QJ8TVQH3N7WPDBL5RXCKThe code is its own index
This is where the performance comes from, and it is the part of the design that departs most from the usual.
The epoch addresses the key, so no keys have to be tried. The signature discards junk without touching storage. The embedded issuance points straight at the single record holding the passport. And the position within the issuance is the exact key of the row.
Nothing searches; everything addresses. That is the difference between a random identifier — which forces a database lookup even to discard junk — and a signed one, which decides valid or invented before asking anything.
A code’s validity is proved by derivation, not by a stored row. Issuing an order writes one record with its size and its state; the labels exist mathematically from that moment. The row for a specific label is born on its first lookup, so only the units somebody actually looks at take up space.
A practical consequence: reprinting a range years later produces exactly the same bytes. There are no lost codes, and an archived range that somebody looks up comes back to life without breaking the lookup.
Print specifications
There is no proprietary hardware: each issuer prints with its own infrastructure. What is fixed is the minimum that makes the code readable in a shop with bad light.
- Symbology
- QR model 2
- The most widely supported standard in phone cameras.
- Error correction
- Level M minimum, Q recommended
- Tolerates scuffs and dirt and still decodes.
- Module size
- ≥ 0.33 mm
- Below that, lower-end cameras start to fail.
- Quiet zone
- 4 modules
- The white margin is part of the code, not decoration.
- Printed size
- ≥ 22 × 22 mm
- Enough for a bottle; it forces the content to stay short.
- Contrast
- ≥ 40 %
- Measured on the real substrate, not on the designer’s screen.
- Next to the code
- Last characters in plain text
- The fallback for when the camera will not cooperate.
Before the run, the issuer uploads a printed sample and the system checks it: it decodes the QR, measures quiet zone and contrast, and confirms the human-readable code matches. The approved sample stays linked to that issuance.
Templates and print outputs
The issuer picks a system template and does not edit the layout: the system injects the data. That way a label printed today and one printed next year are comparable.
-
Deterministic rendering
The same code with the same template version produces a byte-for-byte identical file. Artwork need not be stored: it is regenerated.
-
For the print shop
A vector imposition PDF, with cut and registration marks and bleed, to run full sheets.
-
For the production line
Native thermal-printer language, to label in line at the machine’s own speed.
-
For overprinting
A variable-layer-only output, when the security background is already pre-printed in offset.
Printing does not depend on the connection: the range is downloaded once and a local process feeds the printer, with its own queue and deferred reporting when it reconnects.
What comes next
If you want to know how an issuance is requested and activated from your own systems, the integration reference walks through it endpoint by endpoint. If you would rather see it working, public verification is open.