Architecture Decision: Registrar vs. Registry Model

1. Context & The Question

As interest in the .agent and .chatbot TLDs grows, other platforms and registrars want to resell these domains to their own users. This raises a fundamental architectural question: Are we building a Registrar or a Registry?

In traditional ICANN infrastructure, these roles are strictly separated: * Registry (e.g., Verisign for .com): The authoritative wholesale database. They maintain the master zone files (often using tools like PowerDNS) and provide an API (EPP) for registrars to connect to. They do not sell directly to retail customers. * Registrar (e.g., GoDaddy, Namecheap): The retail storefront. They handle user accounts, credit card billing, UI, and talk to the Registry's API to provision the names.

2. Our Current State

Right now, HeadlessDomains is acting as a Monolith (Registry + Registrar Combined): * Registry Function: We maintain the master database of who owns janice.agent. * Registrar Function: We provide the retail UI, user accounts, and billing (Gems/MPP). * DNS Backend Function: We use domains.skyinclude.com as our DNS nameserver infrastructure (the equivalent of PowerDNS). SkyInclude is not the Registry—it is simply the dumb pipes where the final zone files live. HeadlessDomains is the brain (the Registry).

3. The Path Forward: The "Combined" Web3 Model

While traditional DNS forces a split between Registry and Registrar, modern Web3 and AI-first systems (like ENS or Handshake) often combine them for efficiency.

Recommendation: We should keep them combined in this current app, but expose a "Wholesale Registry API."

Splitting the app into registry.headlessdomains.com and registrar.headlessdomains.com right now would double our DevOps overhead, require syncing two databases, and slow down development.

Instead, we can support resellers elegantly within the current app by introducing Reseller Accounts.

4. How Resellers Will Work (The Architecture)

4.1. Account Tiers

We already have tier = 'human' and tier = 'agent'. We will introduce tier = 'reseller'. A Reseller is simply a special user account with API keys.

4.2. Wholesale Billing (Pre-funded)

Just like traditional registrars prepay registries, Resellers will pre-fund their HeadlessDomains account with GFA Gems (or USDC via MPP). When a reseller provisions a domain via the API, the wholesale cost is instantly deducted from their balance.

4.3. The Registry API (/api/v1/registry/...)

We will build a dedicated Blueprint in the current app for resellers to use. * GET /api/v1/registry/check?domain=name&tld=agent: Checks availability (respecting our global Trademark/Reserved Names table). * POST /api/v1/registry/register: Registers the domain to the reseller's account. * POST /api/v1/registry/dns: Allows the reseller to pass through DNS records (A, TXT, CNAME) from their retail users directly to our SkyInclude backend.

5. Summary

By keeping HeadlessDomains as a combined entity, we maintain our fast iteration speed. We serve as our own primary retail Registrar (the UI you see today), while the new /api/v1/registry/ endpoints will allow us to act as a wholesale Registry for partners. SkyInclude remains our trusted, silent DNS backend.