Skip to content

Nix cache protocol ​

Development preview

This page describes a pinned development revision, not a published release. Its package version may still identify the preceding release while the next version is being prepared.

This experimental protocol follows the event and Hashtree representation consumed by Narwal. It is independent of NIP-C1: a publisher need not operate a CI service, HTTP server or Nix daemon. The trust-list extension below is ngit-ci policy, not an assumption that existing Narwal clients implement delegation.

Root announcement ​

The default cache uses replaceable kind 17091. Named channels use addressable kind 37091, with exactly one nonempty d tag identifying the channel. A format version is not part of the channel name. The publisher signs the ordinary Nostr event envelope. Content is unused; the relevant tags are:

json
[
  ["htree", "htree://nhash1..."],
  ["nixSigKey", "publisher-key-name:base64-ed25519-public-key"],
  ["blossom", "https://storage.example.org"]
]

There is exactly one htree tag. nixSigKey and blossom may repeat. The event's pubkey identifies the publisher; Nix keys authorize output signatures; storage hints grant no signing authority and need not identify publisher-operated hosts. An announcement may have no storage hints when consumers already know replicas.

nhash is Bech32 (not Bech32m), with HRP nhash and a TLV payload. Type 0, length 32 is the SHA256 of the root node bytes. Public cache clients reject encrypted roots (type 5); unknown TLVs can be skipped. Duplicate hash TLVs are invalid.

Consumers verify event signatures and persist their accepted versions. Older announcements and same-timestamp conflicting announcements do not replace known state. A newer announcement from an explicitly trusted Nostr identity can rotate its Nix keys as well as update storage hints and the catalog. Operator approval of that identity is the authority; the bootstrap event is not a permanent key pin. A selected named channel is a separate coordinate and must not be silently replaced by another channel. This provider publishes the default channel.

Catalog nodes and narinfo ​

A Hashtree directory is a MessagePack map:

text
{ "t": 2, "l": [
  { "h": <32 binary bytes>, "n": "<store-hash>.narinfo", "s": <byte length>, "t": 0 },
  { "h": <32 binary bytes>, "n": "<directory name>", "s": <node byte length>, "t": 2 }
] }

Hashes cover the exact encoded child bytes. Blob links have type 0 (also the default when omitted); directory links have type 2. Filenames use Nix's 32-character store-path hash, not the hash of the resulting output. Readers support nested directories. Writers must avoid duplicate selected filenames across their tree.

ngit-ci uses stable store-hash-prefix partitions with at most 128 entries per leaf. Changing an entry rewrites that leaf and its ancestors; unrelated nodes retain their content hashes. Nodes are not fixed-size records. Readers accept other directory layouts rather than requiring this particular partitioning.

A leaf identifies the bytes of an ordinary signed .narinfo file. It contains StorePath, URL, Compression, FileHash, FileSize, NarHash, NarSize, References and one or more Sig fields. Nix signatures authenticate the uncompressed output identity, not its location or compression. Readers validate an authorized Nix signature even when the catalog's Nostr signature is valid.

Narwal-compatible archive URLs have the form nar/<Nix-base32 SHA256 of archive bytes>.nar[.<compression extension>]. Blossom serves those exact bytes at /<hex SHA256>. FileHash is the hash of compressed bytes; NarHash is the hash of the uncompressed NAR. zstd uses Compression: zstd and .nar.zst; xz uses Compression: xz and .nar.xz. Changing compression changes the blob address, not the output's signing identity.

A publisher selects one narinfo per store hash. A later build can replace that selection; different bytes alone are not a reproducibility failure. Neither catalog membership nor matching signatures claims an independent rebuild.

Catalog membership and storage availability ​

Catalog links are historical publication records, not an availability promise. They may continue to reference blobs after all copies have disappeared. They need no availability sweep or rewrite when a storage operator evicts an archive.

Our cache serves content-addressed narinfo only while its corresponding admitted archive remains retained and authorized. The same retained-record index gates both; eviction removes both from the public read surface. Hashtree nodes retain the references, not the narinfo bytes. Local metadata reads refresh recent-use protection. This pairing is a storage policy, not a property guaranteed by an arbitrary Blossom server or a client's metadata cache.

A consumer can fetch narinfo from a candidate storage server and immediately request the archive there, avoiding a preliminary HEAD in the common case. It must still handle eviction races, independently retained metadata and server failures. Other sources are tried before archive bytes are sent; interrupted or corrupt transfers fail integrity verification. No live narinfo is an ordinary cache miss; no surviving archive cannot be repaired by discovery.

Storage-only replicas need no signing credentials. Copying the exact narinfo and compressed archive preserves their content addresses. A Nix provider that imports and re-exports an output can produce another compression; its live /nix/<store-hash>.narinfo advertises that representation with the original Nix signature. It must not claim to host the original compressed hash unless it actually has those bytes. Pure Blossom replicas need not implement that Nix API.

Optional trust delegation ​

A publisher may also sign a NIP-78 application event, kind 30078, with exactly one d tag ngit-nar-trust, and JSON content:

json
{"version":1,"providers":["<trusted-provider-hex-pubkey>"]}

Consumers decide which direct identities to trust and which roots may delegate. An enabled edge authorizes the downstream identity's announced Nix keys and further delegation. It does not authorize storage operators merely listed in blossom tags. Removing an edge recomputes reachable authority; another direct or delegated route may preserve it. Cycles disconnected from approved roots cannot grant authority. This is acceptance of any authorized signature, not a quorum or evidence of independent reproducibility.

Operational trust policy describes bounds, relay outages, withdrawal cleanup and preparation snapshots. Existing Narwal consumers can use the catalog without implementing this extension; they still need an appropriate trusted-key configuration in their Nix daemon.

Tag extensions ​

Cache announcements and trust-list identifiers accept appended tag metadata and ignore unknown tag names. Known singleton identifiers, publisher signatures, URLs, keys and event-size limits remain validated. This does not relax the versioned trust-list JSON schema or authorize new providers.