How this works

Identity structure, worldwide routing, resolution, durability, and the design decisions behind registrar.earth — a technical overview.

The core idea

Every registered object receives a 128-bit identity encoded as an IPv6 address within reserved ULA address space. This identity is the object's permanent name. It does not depend on DNS, a specific server, or the continued existence of any company.

The identity is structured — its bits encode when it was minted, where it was minted, and a unique object discriminator. This makes identities self-describing, sortable, and independently verifiable without contacting a central authority.

The system solves three problems simultaneously: addressing (an IPv6 ULA space that encodes where a request should go), routing (a network fabric that steers requests to the nearest resolver), and resolution (a service that turns an identity into a description and metadata via region-aware database lookups with fallback).

Identity format

Identities use the SF128 format — a 128-bit layout that fits natively into IPv6 addressing and PostgreSQL storage. Each identity occupies the fd53::/16 Unique Local Address prefix, ensuring it will never collide with routable internet addresses.

  fd53 : RR SS : PP HH : ── ── : ── ── : ── ── : ── ── : ── ──
  ╰─┬─╯  ╰┬╯╰┬╯ ╰┬╯╰┬╯
    │     │  │   │  │
    fd53  │  │   │  └── Host ID         (8 bits)
    │     │  │   └───── Plane / Service (8 bits)
    │     │  └───────── Site / Cluster  (8 bits)
    │     └──────────── Region          (8 bits)
    └────────────────── Registry prefix (16 bits)

  ├─── upper 48 bits: addressing ───┤── lower 80 bits: identity ──┤

The upper 48 bits form a structured addressing prefix — the registry namespace, region, site, service plane, and host — providing predictable routing and resolver selection. The lower 80 bits carry the object identity: a millisecond-precision timestamp and a per-site sequence number that together produce a globally unique, chronologically sortable discriminator.

Field	Bits	Purpose
fd53	16	Registry namespace — ULA prefix, never collides with routable internet addresses
RR	8	Region code — operational geography (North America, Europe, East Asia, etc.)
SS	8	Site / cluster — datacenter, provider, or sub-region within a region
PP	8	Plane — service layer (resolver, database, relay, alias, observability, admin)
HH	8	Host ID — individual node within a plane
Timestamp	48	Millisecond-precision UTC mint time — natural chronological ordering
Sequence	32	Per-site counter — disambiguates objects minted in the same millisecond

When rendered as an IPv6 address, a registrar.earth identity looks like fd53:0301:1042:918f:3a7c:4200:bc3f:9e01 — Europe (03), site 01, resolver plane (10), host 42, followed by the timestamp and sequence. A valid address that can be stored, transmitted, and indexed by any system that understands IPv6.

Why IPv6? Because the format already exists in every operating system, database, and network stack on earth. There is no serialization overhead, no custom parser, and no dependency on a proprietary encoding. The identity is the address.

Global prefix plan

The RR:SS:PP:HH hierarchy described above does double duty: it structures object identities (every minted SF128 carries its region and site of origin) and it structures infrastructure addressing (every resolver, database, and gateway has an address within the same scheme).

A routing block is a /48 for a given region + site + plane combination: fd53:RRSS:PP00::/48. Individual nodes receive /128 or /120 allocations within that block. This scheme scales to 256 regions, 256 sites per region, and 256 service planes per site — far beyond foreseeable need.

Example: fd53:0301:1000::/48 is the resolver plane for Europe, site 01. fd53:0702:1100::/48 is the database plane for East Asia, site 02. The prefix itself tells you where and what.

Regions and planes

Region codes (RR)

Regions are operational, not geopolitical. They represent where infrastructure runs and where data is homed by preference. The site byte (SS) subdivides each region by provider, country, or datacenter as needed.

Code	Region	Notes
0x01	North America	US, Canada, Mexico
0x02	South America	Central + South America, Caribbean
0x03	Europe	EU, UK, EEA, non-EU Europe
0x04	Africa	Continental Africa
0x05	West Asia / Middle East	Gulf states, Levant, Turkey, Iran
0x06	South Asia	India, Pakistan, Bangladesh, Sri Lanka
0x07	East Asia	China, Japan, Korea, Mongolia, Taiwan
0x08	Southeast Asia	ASEAN states, Philippines, Indonesia
0x09	Oceania	Australia, New Zealand, Pacific Islands
0x0A	Antarctica / Special	Research stations, non-territorial
0xFE	Test	Development and staging environments
0xFF	Reserved	Future use

Service planes (PP)

Within each region and site, services are separated into planes — logical layers that keep the fabric legible and allow independent scaling of each concern.

Code	Plane	Function
0x10	Resolver	HTTP resolution endpoints — turns identities into records
0x11	Database	PostgreSQL gateways and read replicas
0x12	Relay	Message relays, PGN buses, notification delivery
0x20	SF128 Alias	Alias IP space — identity addresses that resolve as keys
0x30	Observability	Metrics collection, log shipping, health probes
0x40	Admin	Management interfaces, minting endpoints, key management

Resolution

"Resolution" means answering the question: given this identity, what is this object? The resolver accepts either a raw IPv6 address (fd53:...) or an SF128 identifier and returns a description, metadata, and provenance information about where the record was found.

Resolution algorithm

The resolver extracts the region and site from the identity's prefix bits, then queries databases in a defined fallback order. This is preference and resilience, not data sovereignty — any resolver can answer any query given sufficient fallback.

Region-aware lookup: local site first, then region, then global. Results include provenance metadata.

Responses include a resolved_via field describing which region, site, and endpoint produced the result. Locally resolved records are cached with a TTL to reduce cross-region lookups for frequently accessed objects.

Routing fabric

Alias addresses (the fd53:... identities) exist primarily as database keys, not as routed network addresses. A client submits an identity to a resolver API; the resolver extracts the suffix and performs the database lookup. No requirement exists for the network to route packets to that IP directly.

This is the simplest mode and scales best. It still "feels" like IPv6-based resolution — the identity is an address — but the network fabric only needs to route between resolvers and databases, not to every registered object.

Baseline: nearest resolver via DNS + WireGuard

Each node has a configured home region and site. Clients connect to the nearest resolver via DNS. Resolvers perform region-aware database lookups (local-first, with fallback). WireGuard provides encrypted links between resolvers and databases across regions.

Scale mode: gateways with dynamic routing

For multi-region deployments, regional gateways run BIRD or FRR over WireGuard tunnels. Gateways advertise their /48 plane prefixes — for example, a European gateway advertises fd53:03xx:10xx::/48 for its resolver plane. Route preference is tuned via local-pref or AS-path length. This is standard BGP mechanics applied to ULA space.

The key constraint: BIRD advertises plane blocks, not per-host addresses. The routing table stays compact regardless of how many objects are registered.

Network-routed aliases are an optional future mode. If operational needs require ICMP/ping/service semantics tied to identity space, alias prefixes can be advertised at L3 across gateways. This is heavier operationally and is not required for resolution.

Database model

Three tables form the core data model: a routing table (which databases exist and what they cover), an object record table (SF128 identities with descriptions and metadata), and an alias table (mapping the 112-bit suffix from an IPv6 alias back to its SF128 identity).

Route targets

The resolver uses this table to decide which database pool to query for a given region, site, and service plane. Lower priority values are preferred. Health checks mark endpoints as temporarily unavailable without removing them.

CREATE TABLE route_targets (
  id            bigserial PRIMARY KEY,
  region_rr     smallint NOT NULL,       -- 0x00..0xFF
  site_ss       smallint NOT NULL,       -- 0x00..0xFF
  plane_pp      smallint NOT NULL,       -- 0x10 resolver, 0x11 db, …
  priority      int NOT NULL DEFAULT 100,  -- lower = preferred
  endpoint      text NOT NULL,          -- "postgres://…" or "https://…"
  health_url    text,                    -- optional health check endpoint
  tags          jsonb NOT NULL DEFAULT '{}'::jsonb,
  enabled       boolean NOT NULL DEFAULT true
);

CREATE INDEX route_targets_lookup
ON route_targets(region_rr, site_ss, plane_pp, priority)
WHERE enabled = true;

Object records and aliases

Object records hold the SF128 identity, description, and metadata. The alias table maps the 14-byte suffix of an fd53:: IPv6 address back to its canonical SF128 identity, enabling resolution from either representation.

CREATE TABLE sf_objects (
  sf128_hex     char(32) PRIMARY KEY,   -- canonical SF128 identity
  descr         text,                       -- human-readable description
  meta          jsonb NOT NULL DEFAULT '{}'::jsonb,
  owner_pubkey  text,                       -- age public key for contact
  status        text NOT NULL DEFAULT 'active',
  created_at    timestamptz NOT NULL DEFAULT now()
);

CREATE TABLE ip6_alias (
  ip_suffix_14  bytea PRIMARY KEY,     -- 112-bit suffix (14 bytes)
  sf128_hex     char(32) REFERENCES sf_objects,
  created_at    timestamptz NOT NULL DEFAULT now()
);

Minting

"Minting" is the act of creating a new identity for an object. The identity generation follows a distributed Snowflake pattern: the minting region, site, plane, and host are combined with a millisecond timestamp and sequence number to produce a globally unique 128-bit value. No coordination between minting nodes is required — the addressing prefix and timestamp bits prevent collision.

RR + SS The region and site bytes identify the minting authority and geography, enabling federated issuance. Each site mints independently.

PP + HH The plane and host bytes identify which service node performed the mint, providing full provenance for every identity.

Timestamp 48 bits of millisecond-precision UTC time, providing natural chronological ordering and approximate date recovery from the identity alone.

Sequence A 32-bit per-site counter that disambiguates objects minted in the same millisecond at the same host.

Once minted, an identity is permanent. It is never reused, reassigned, or recycled. An object may change owners, status, or location — its identity does not change.

Privacy model

Registering an object does not require publishing personal information. The registry separates the identity of the object from the identity of the person.

Contact between a finder and an owner is mediated — a finder can report a found object without learning who the owner is, and an owner can respond without revealing their location or full name. This is achieved through encrypted contact channels rather than a public directory.

Communication payloads use age encryption, which is auditable, modern, and has no dependency on certificate authorities or key servers. The owner's public key is the only information associated with the record. Everything else is behind that key.

Durability by design

The system is designed around the assumption that any single component — including registrar.earth itself — may eventually fail. Durability comes from structural decisions, not operational promises.

The identity is self-contained. The 128-bit value carries its own timestamp, origin, and uniqueness. No external lookup is needed to interpret it.

The format is pre-adopted. IPv6 and PostgreSQL inet already exist in billions of systems. We did not invent a format — we chose one that already won.

No DNS dependency. Resolution does not require domain name resolution. The identity is a direct database key, not a URL. If the website disappears, the identity still works with any compatible resolver.

Offline legibility. A printed identity on a physical label can be manually entered decades later. There is no QR code requirement, no app dependency, no scan-to-activate step.

Replicable data. The registry data is standard PostgreSQL. It can be backed up, exported, mirrored, or transferred to another institution using existing tools.

Federated by default. The region and site hierarchy means resolution never depends on a single datacenter or a single organization. Any site with a copy of the data and a compatible resolver can answer queries.

The question is not "will this service stay online?" — it is "can this identity be resolved by anyone, even if this service does not?"

What happens when things fail

Every infrastructure system should be honest about failure modes. Here is how registrar.earth degrades, and why the identity survives each scenario.

Website goes down The identity is not a URL. It remains valid and resolvable by any system with a copy of the registry data.

Company ceases The PostgreSQL data can be transferred. The format is open. Another institution can operate a compatible resolver.

Region goes offline Resolvers in other regions fall back to global or cross-region databases. The route_targets table encodes this priority chain automatically.

Label is damaged Any surviving fragment of the identity — even a partial IPv6 address — narrows the search space. The timestamp bits alone identify the approximate mint date and region.

Internet unavailable The identity is human-readable and can be recorded, transmitted, or searched offline. Resolution requires data access, not internet access.

Encryption ages Contact channels use age encryption, designed for long-term readability. The identity itself is unencrypted — it's a number, not a secret.

Gateway fails BIRD/FRR withdraws the failed gateway's prefix advertisements. Remaining gateways absorb traffic. No manual intervention required.

Rollout

The system is designed to be deployed incrementally. Each phase adds capability without requiring the next.

Phase 1

Multi-region routing table + multi-DB lookup Implement route_targets. Resolver supports --region and --site configuration with fallback lists. Add health checks and caching. Single-writer, multi-reader.

Phase 2

Regional gateways + WireGuard interconnect One gateway per region/site. Establish WireGuard tunnels between gateways in mesh or hub-and-spoke topology. Route resolver and database plane prefixes across tunnels.

Phase 3

Dynamic routing Add BIRD on gateways. Advertise /48 plane blocks. Tune local-pref for nearest region/site. Automatic failover on gateway loss.

Phase 4

Federation "Where did this resolve from?" provenance in every response. Multi-writer reconciliation for distributed writes. Third-party resolvers can join the federation with compatible schemas.

The best infrastructure is the kind you can explain to someone
who will need to understand it in fifty years.