Run your own registry

The most useful thing about this registry is that you do not need it.

A registry is not infrastructure in the sense that requires an operator, a budget or a service agreement. A registry is just a peer — one publishing name bindings into its own tree. Running one is closer to publishing a website than to operating DNS, and the reference deployment guide's lowest tier is exactly this: object storage and a CDN, no server at all, essentially free.

That is worth stating plainly, because a design where everyone must point at one registry is the failure mode this one exists to avoid — including when the registry everyone points at is ours. Plenty of people may end up using this one, and that is fine. What should never be true is that they had no alternative.

What it consists of

Four things, and none of them is a running process.

A keypair that signs names, and nothing else. The key that signs name bindings should not be the key that signs any content you publish. Keeping them separate is what lets someone pin a name-issuer and a content-publisher independently; one key doing both means asking people to trust a name-issuer to also be the thing it names.

Signed bindings. Each one associates a name with a target peer, the transports to reach it at, and an expiry. The registry signs a body carrying the name and target together, so that signature is the association — not the index that points at it.

Somewhere to answer two reads from. A resolver asks your registry for a name and then for a body; anything that can answer those is a host. A live peer on the network can, and gets you issue-on-request and immediate revocation. So can a directory of files on a static host, which gets you nothing to keep running and a bill of roughly zero — the authority is in the signatures either way, so the cheap option gives up less than it looks like. And you may serve it to nobody but yourself. A registry reachable only inside your own network, or sitting entirely on your own disk, is a registry in the same sense as any other. Publishing is a choice about audience, not a requirement of the design.

The rest of this page describes the static shape, because it is the one worth starting with and the one this deployment runs. None of it is load-bearing on the mechanism.

Hosting a registry this way is the same act as hosting any other peer, and it is a general property of the system rather than anything the registry invented — a signed content-addressed tree on a host that runs nothing, published by a peer that need not stay online afterwards. The Foundation site's Publishing on ordinary hosting explains that property in full, at entitychurchfoundation.org.

A pin your users hold. One string — your registry's peer identity — which their configuration holds and every answer is checked against. It carries the public key that verifies your signatures, so nothing has to be fetched to know who you are.

What comes out, if you publish it statically

A directory. This is the shape a statically published registry takes — every path below is a real one, and a client resolving against you reads exactly these. A live registry peer holds the same entities at the same tree paths and answers for them over a session instead; the paths are the registry, the files are one way of serving them.

<peer-id>/
  system/
    registry/binding/
      by-name.list                     the menu — unsigned, a convenience
      by-name/<name>.bin               name → hash of the binding body
      <binding-hash>.bin               the binding, addressed by its own hash
    registry/revocation/
      by-target/<hex(binding-hash)>    a revocation, if one exists
    signature/
      <hex(binding-hash)>.bin          the commitment, at a path derived from the hash
    peer/transport/
      <target-peer-id>/primary.bin     how to reach the peer a name points at
    peer/published-root                your signed root

content/
  <xx>/<yy>/<hash>                     the bodies, addressed by hash

Two things about that layout are worth noticing before you build one.

The .bin files under the tree are pointers, not bodies. A tree path hands back the content hash bound at it; the bytes come from content/ on a second fetch. That is what lets the same content sit at ten paths and be stored once, and it is why a binding appears twice above — once by name, once by hash — without being duplicated.

Serve everything your bindings reference, or the names resolve to nothing. A binding points at a transport profile by hash and has a signature at a derived path. Publish the names without those and a client enumerates your whole registry perfectly and then fails to resolve a single entry — with a 404 it cannot tell apart from you withholding the file. Publishing the whole system/ prefix covers it.

The revocation path is the one that will be empty on day one and matters most later. Note what it can and cannot tell a client: a revocation being present proves a binding is dead, and its absence proves nothing at all, because an absent file and a withheld one are identical at the far end. That asymmetry is why your bindings need a finite expiry — it is the only bound on a revocation you fail to serve.

Getting there

The reference deployment guide on the architecture site is the document to work from: its static tier describes the CDN-hosted registry shape end to end, alongside the tiers above it if you eventually want more than a static reef. The registry extension specifies the binding format, the resolver contract and the trust model, so that a registry built from it interoperates with clients that never heard of you.

The tooling that emits and verifies a registry directory ships with the browser implementation rather than with this site. Take the invocation from that project's own documentation rather than from prose here — a command line copied out of an explainer is exactly the kind of thing that goes stale silently.

If you run one, tell us what broke

A second independent registry exercises the design in ways this one cannot, and is worth more to us than another name in ours. The reports worth sending are the unglamorous ones: a host whose cache headers made a signed root stale, a client that resolved a name it should have refused, an enumeration that came back short without saying so. Those are the ones that get fixed.

Reports go to the project repositories linked from the Foundation site.