Entity Church Registry

The Entity Church Registry

A registry provides name resolution similar to DNS: given a name, which peer is it, and where do I reach it. It resolves a name to a peer identity, the endpoints that peer can be dialled at, the evidence for the association, and how long the answer is good for.

That is the whole job. Everything else — fetching a tree, verifying content, rendering a page — happens below it and does not involve the registry at all.

Concretely, an entry in this registry is six fields:

name:           "billslab.com"
kind:           "peer-issued"                 signed by the registry, not asserted locally
target_peer_id: "2KBj64an1PvKXMafcT2rCC8eaac4Kmyht7xTeCap8USWho"
transports:     [ <hash> ]                    → how to reach that peer
issued_at / ttl:                              an instant, and a duration — thirty days

Two hundred and nine bytes, signed, and it says who rather than where: the transports hash points at a separate profile carrying the actual URLs. That indirection is most of what people find surprising, and it is worth two minutes — the same name, resolved end to end, with the real artifacts.

The shape of that walk, before the artifacts:

How a name resolves to a peer, in two hops across two different origins. The client holds one pinned registry identity — an identity, not an address. From the registry's origin it fetches a by-name pointer, dereferences the hash it returns to get the binding, and checks the registry's signature against the pin; a failed check ends the walk rather than falling back. The binding points at a transport profile on the publisher's own origin, from which the client fetches the signed published root and then walks the published tree, recomputing every hash, with the registry no longer involved.

Two things in it are worth noticing before you read further. The second hop happens at a different origin — the registry hands over an address and is not involved in fetching anything. And the one line that is not a fetch is the check against your pin: it either passes or the walk ends. There is no path on that diagram where a failed check becomes a slightly-less-trusted answer.

What this registry is for

This is a working deployment run to exercise the design. The sites around it are a demonstration: several domains, published by different keys, resolving through this registry and linking to one another. There are more domains here than the content strictly needs, and that is deliberate — a name-resolution layer that is only ever described stays plausible, while one that has to actually resolve across independent publishers, from a real host, in a real browser, produces the failures worth knowing about.

So the honest description of this registry is: a small, real registry, running so that the design has somewhere to be explored. It carries the names this deployment needs. It is not an index of the network and makes no claim to completeness.

Concretely, it is static. The bindings are files — signed, published, and served by an ordinary host. There is no peer standing by to take a request: no sign-up, no submission form, nobody to ask. A name gets added when someone edits the deployment and republishes it. That is not a placeholder for missing infrastructure; a static registry is a supported shape, and it is the cheapest one that still proves the mechanism.

Whether it stays that way is open. A registry that accepts live registration, a sandbox that takes anything first-come-first-served, a curated one with a review step — all of these are reasonable things to build on this substrate, and they differ by trust model rather than by size. This one may grow into something people rely on. It is also fine if it doesn't, and the design should not care either way.

Preloaded is not default

You most likely did not choose this registry. It is the one shipped with these builds — preloaded, so that a fresh client can resolve something at all rather than starting from an empty configuration and a blank prompt.

The specification models this directly, and names the discipline that goes with it: distributions ship an opinion, and the user owns the configuration. The analogy it draws is the root certificates that come with an operating system — pre-trusted because you accepted the build, removable at any time. Pre-trust by acceptance is a real thing to have accepted, which is why it is worth stating on the front page rather than in a footnote:

What a name is worth here

There is no global namespace, and this registry does not create one. A name has no meaning on its own. It means what your resolver configuration says it means, and the same string can resolve to different peers for two people running different configurations. Anyone may publish a binding claiming any name; whether you trust that binding is your policy, not the registry's.

Three things follow:

Read on

The normative reference is the registry extension and the resolution guide, both published with the rest of the architecture corpus at entitychurchfoundation.org. This site explains; those specify, and they win on any conflict.