---
title: "30.16 The registry service"
url: https://una-lang.org/en/docs/spec/30-packages/16-the-registry-service/
release: v0.4.0
source: https://github.com/una-lang/una/blob/v0.4.0/docs/spec/30-packages.md
---

# 30.16 The registry service

A registry (ADR 0122 rules 34 to 46) logs what it is sent only after verifying it, and serves the log as static files that every client verifies again with §11. Itaty's service is the crate `una-itaty`.

1. **Entries.** Each leaf of the log is a whole signed note, signature lines included, of at most 65,535 bytes: a release statement, a yank or an advisory (§11), an owner's registration or an owner's key event. An owner's registration is `ita-owner/1`, `source`, `owner`, `previous none`, `threshold <k>`, then one `key <name> <base64 key>` line per key, from 3 to 32 keys and at least k + 1, with k at least 2, and no `cosigner` line, each signing the note. A key event is `ita-key/1`, `source`, `owner`, `previous <index> <leaf hash>`, one of `add <name> <base64 key>`, `revoke <name>` or `revoke <name> since <index>`, and `threshold <k>`, the threshold after it; it is signed as §14 rule 5 requires, and a key added also signs it. A key event, a claim included, that would leave a threshold below 2, fewer current keys than the threshold plus one, or more than 32, as the chain is known after it, is refused, and so is a 65th claim of a chain. The floor counts the owner's current keys, not the keys that can still sign: a current key that a claim that counts compromised still counts toward it. With these, one stolen key alone signs nothing that the registry logs on the owner's chain or that counts, and an honest owner answers with its other keys (§14 rule 5, the replay's contract, item 4), adding a key first when it holds exactly one key more than its threshold. An owner whose current keys that sign as counted are fewer than its threshold, because its own claims left a current key compromised or because two of its keys are stolen, can log no key event, and one whose chain holds 64 claims logs no further claim: it registers under a new owner name, with new keys, since a key that another owner's chain named is refused (rule 2). This release's registry logs no recovery, dispute, co-signer change, cancellation or overruling. An owner's entries form the chain of the name `owner:<owner>` in the name map; a package's entries form the chain of its name. A leaf hash in `previous` is `sha256:` and the hex of the RFC 9162 leaf hash of the entry's bytes.
2. **What the registry verifies** before it logs an entry, refusing it otherwise with one sentence:
   - the entry's format, at most 65,535 bytes, and that its `source` is the registry's;
   - that its `previous` is the latest entry of its chain, or `none` for a chain with no entry;
   - for an owner's registration and key event: the rules of §14 rule 5, "What a registry logs", by the same function a client uses, on the chain the registry holds;
   - for a release: that it counts as logged on its owner's chain (§14 rule 6), or its signatures by the threshold of Itaúna's keys of the root metadata for an unscoped name; for a name new to the registry, rules 44 and 45 (form, reserved names and skeletons, a skeleton unique among the owner's names and the unscoped ones); that its version is not logged already; at most 10,000 releases per name; that each need names a release logged at the registry, at most 1,000, none of the release's own identity; rule 26 against the highest earlier release of its identity; and its archive (rule 37, below);
   - for a yank: that it stands as logged on its owner's chain (§15 rule 6), and a version released and not yanked; for an advisory: a security key of the root metadata, and affected versions all released;
   - for a registration: the operator's credential, which stands for the verification of the account; rules 44 and 45 for the owner name; an owner name one edit (an insertion, a deletion, a substitution or a swap of adjacent characters) from one of the 1,000 owners with the most dependents is held for review until the operator accepts it; every key signs; no key is another owner's.
3. **A release's archive.** It is read by §9 rule 3 and must have the statement's `digest`; its `ita.una` must have the statement's `manifest` digest, read with no error, pass the refusals of §11 rule 12, and give the statement's `name`, `version`, `edition`, `source` (its `publish to`) and `needs` (each at its least version). The statement's `authority` must be exactly the union of the `uses` clauses of the package's public functions and of its handlers, each capability with its operations, a clause with no operations counting every operation that the package's declaration of the capability, or the prelude's, lists (with neither, the package is refused); its `trust` must be exactly the modules `ita.una` lists under `trusted` and those whose header is `trusted module`. A module that does not lex or parse refuses the package. The archive is then served at `blobs/sha256/<hex>`.
4. **Promises** (rule 36.2). A logged submission is answered with the note `ita-promise/1`, `source`, `index <n>`, `leaf <leaf hash>`, `by <seconds>`, signed by the log's key; the service logs before it answers, so `by`, one hour after the registry's clock, is always met.
5. **Checkpoints.** After each entry, the log signs the checkpoint `<log key name>`, `<size>`, `<base64 root>`, `ita-map <base64 map root>`, `ita-root <n> sha256:<hex>` naming the root version in force (§11 rule 9), stored at `checkpoint/<size>` and served to witnesses at `witness/next`. A witness's cosignature is taken only from a witness of the root metadata, when it verifies, when its time is not below that witness's previous one nor more than one hour after the registry's clock, and when that witness has not cosigned a larger checkpoint; it is added to `checkpoint/<size>`. The newest checkpoint with the witness threshold of cosignatures is served at `checkpoint`.
6. **Witnesses** replay the entries since the checkpoint they last cosigned, from the entry bundles, recompute the log's root and the name map, checking each entry's `previous` against its name's head and its count rising by one, and cosign only a checkpoint whose two roots they reach, never with a time below their previous one.
7. **Static files** (rule 34): `root/<n>`; `checkpoint`, `checkpoint/<size>`, `witness/next`; the log's tiles in the layout of C2SP `tlog-tiles` (`tile/<L>/<N>` and `tile/entries/<N>`, `.p/<W>` while partial, removed once the tile is full, each entry of a bundle after its 16-bit big-endian length); the name map's tiles; and `blobs/sha256/<hex>`. **A map tile** at tile level t (0 to 31) holds the 256 nodes at depth 8t + 8 under the first t bytes of a key, indexed by its byte t: a bitmap of 32 bytes (bit i of byte i / 8, least significant first, set for each node that is not the empty subtree), then for each such node its hash, or at t = 31 the name's head (index, 8 bytes big-endian; leaf hash; count, 8 bytes). It is stored at `map/<t>/<hex of the root of the tile>`, so a client starts from the `ita-map` root, fetches the tiles on a name's path, recomputes each one's root and compares it with the hash that named it. A lookup reads at most 32 tiles.
8. **Endpoints.** `GET` serves the files of rule 7 and no other. `POST /publish` takes `ita-publish/1`, the statement's length in decimal, each on its line, the signed statement and the archive; `POST /submit` a yank, an advisory or a key event; `POST /register` a registration, with the operator's bearer token; `POST /cosign` a checkpoint's size and a cosignature line. A request's head is at most 16 KiB and 64 headers; a body needs `Content-Length` within its endpoint's bound, checked before it is read; chunked bodies, queries and percent-encoding are refused.
9. **Failure.** A write to the store that fails stops the service from logging until it is opened again. Opening replays the log from its entry bundles, checking each chain and the stored checkpoint, so a store changed by hand refuses to open. The checkpoint of a size is a function of the entries and of the root version it was first signed under: a root rotation takes effect from the checkpoint of the next entry, and a size whose checkpoint is stored keeps the version it names, its log key's signature and its bytes when the service opens again, so a size signed again after a crash is the same, and two log-signed checkpoints of one size never name different versions (§11 rule 9). Opening checks the stored checkpoint of every size: each size below the log's has one, each names a version of the chain with that version's digest, is signed by that version's log key and is the log's text under it, and the versions never decrease as the size grows; otherwise the store refuses to open. A size whose checkpoint was never stored is signed under the version in force. Until the checkpoint of the first entry after a rotation is cosigned, the point names the older version while the newer one is served, which clients treat as unavailable (§11 rule 9, U7013), so a registry logs an entry after a rotation. A store has one writer: the service locks it while open, and a second one refuses to open.
