# Keeping a DNS domain and an onchain name in step

> Linking a DNS domain and an onchain name is a launch task. Keeping both sides accurate through every change is the harder job. How to run it.

Source: https://hush.partners/keeping-a-dns-domain-and-an-onchain-name-in-step
Category: Onchain today
Published by Hush Partners.

---
An organization that holds an onchain name usually links it to the identity it already has. Its website, on a DNS domain users know, states that `.yourbrand` is its namespace and that `pay.yourbrand` is its payment name. The onchain name, in turn, can carry records that point back to the website. Each side vouches for the other, and a counterparty who checks both has good reason to trust the pair.

That link is established once, at launch. It then has to stay true for as long as the name is in use, through events that change one side without touching the other: a payment address rotated for security, a wallet moved to new custody, a product renamed, a subsidiary sold, a name retired. Each of those events opens a gap in which the two sides say different things. A gap is where errors happen: a supplier pays an old address, a customer trusts a retired name, a page keeps vouching for a namespace the organization no longer controls.

This article is about closing those gaps. It assumes the link has already been made, which the Journal covers under what an onchain name proves, and concentrates on the operational work of keeping it accurate: what the two sides contain, which events break them, who owns each update, and how to retire a name cleanly.

## The two halves of the link

The link has two halves, held in two different systems, usually managed by two different teams.

**The DNS half.** This is what the organization publishes on its established domain: a page stating which onchain TLD and names it holds and what each is used for, and sometimes a short text record in the domain's DNS zone saying the same thing in a form software can read. The DNS lets a domain holder publish free-form text records, and some organizations use one to declare their onchain namespace alongside other declarations they already make there. The DNS half is managed by whoever runs the website and the domain: web, marketing or IT.

**The onchain half.** This is what the onchain name itself carries: the addresses it resolves to on each blockchain, and records such as a website pointer or a text field. On Freename, names can carry addresses and records, and the holder of the TLD is the only party who can issue names under it. The onchain half is managed by whoever controls the wallet that holds the TLD: often finance, treasury or a technical team.

The link is only as good as the agreement between the two halves. A website page that lists `pay.yourbrand` while the name now resolves to a different address is not wrong in itself; the risk is that one side was updated and the other was not, and nobody knows which to believe.

| Item | DNS half | Onchain half |
| --- | --- | --- |
| What it states | Which names the organization holds, and their use | Where each name resolves, plus records |
| Who usually changes it | Web, marketing or IT | Holder of the wallet: finance or technical team |
| How a third party checks it | Visits the page on the known domain | Reads the registry record on a block explorer |
| Typical failure | Page left unchanged after an onchain change | Records left unchanged after a business change |

## The events that break the link

Most breaks come from ordinary business events, not from anything unusual. Knowing the list is the first step to catching them.

### Address rotation

Organizations change the addresses their names resolve to, for security or because they change wallet providers. A rotation updates the onchain half. If the website states the address as well as the name, or if internal documents and supplier records still hold the old address, the two sides no longer agree. The cleanest practice is for the DNS half to state the name and never the address, so that rotation changes only one side.

### Custody changes

The wallet that holds a TLD may change: a move to a multisignature wallet, a move to a custodian, a move between entities within a group. The registry record shows the new holder. A counterparty who checks the record and sees an unfamiliar holder may reasonably wonder whether the namespace still belongs to the organization. The page on [escrow and transfer](/escrow-and-transfer) covers how a transfer is run; for the link, what matters is that the DNS half explains the change before anyone asks.

### Rebrands and renamed products

When a product or the company is renamed, the DNS side usually changes quickly: new pages, new domain, redirects. The onchain names under the old name often stay as they were, still resolving, still carrying records that point to a website that now redirects. A user who meets the old name finds a namespace that looks abandoned but still works.

### Divestments and acquisitions

When a business unit is sold, its names may go with it, and the website of the seller may still list them. When a business is acquired, its onchain names arrive with no entry on the buyer's website. Either way, one side vouches for a namespace the other side no longer recognizes.

### Retired names

A campaign ends, a payment name is replaced, a pilot closes. The name may still exist and still resolve. If the page that once announced it has been deleted rather than updated, a counterparty who finds an old reference has no way to learn that the name is no longer in use.

<aside class="callout">
<span class="callout-label">For operations teams</span>
<h4>State names, not addresses, on the DNS side</h4>
<p>A website that lists the onchain name and its purpose, without the address it resolves to, survives every address rotation unchanged. Each address printed on a page is one more thing to update, and one more place for a stale value to sit.</p>
</aside>

## Writing the DNS statement so it ages well

Much of the drift between the two halves starts with the way the DNS statement was first written. A statement written for launch day, with a list of addresses, a promotional tone and no mention of what happens later, goes stale quickly. A statement written to be maintained survives.

A durable statement contains a small number of elements, each of which can be checked against the onchain half.

**The TLD and every name in use, written exactly.** Spell each name as it is recorded, in lowercase, with no decorative formatting. A name that appears in two spellings on the same page invites the question of which one is real.

**The purpose of each name.** One line per name: payments from customers, payments to suppliers, an agent identity, a support identity. A counterparty who knows what a name is for can spot a name used for something else.

**What the organization will never do through a name.** For example, that it never asks for a change of payment destination through a message alone, or that support staff never ask a user to approve a transaction. This line does more protective work than any other, because it gives counterparties a rule to apply.

**Retired names.** A short list of names no longer in use, with what replaced them. This is the part most organizations leave out, and the part that answers the counterparty holding an old reference.

**A route to confirm.** Where to go to check a name before relying on it: a contact form, a named function, the contract. Not an email address printed on the page, which is one more detail to keep current and one more thing to imitate.

The statement should live at a stable address on the known domain and keep that address through redesigns. A statement that moves every time the website is rebuilt breaks every reference to it, which defeats its purpose.

## Who owns each update

The structural reason the halves drift is that no single team owns both. The web team does not see the wallet, and the wallet's controllers do not edit the website. The fix is not a new team but a clear assignment.

**A single owner for the link.** One person or function, often in legal, security or treasury, owns the accuracy of the link as a whole. They do not make every change themselves; they make sure every change on one side triggers the matching change on the other.

**A change rule.** Any change to the onchain half, an address, a record, a custody move, is not complete until the DNS half has been checked. Any change to the DNS half that touches naming, a new product name, a removed page, a divestment, is not complete until the onchain half has been checked.

**A shared register.** One document lists every onchain name the organization holds, what it is used for, what the website says about it, where internal documents reference it, and when each was last checked. The register belongs with whoever owns the link, and a domain manager who already keeps a register of DNS domains is often the natural owner.

That last sentence points to an existing habit. Organizations that run a portfolio of DNS domains already keep a register with renewal dates and owners. Adding onchain names to it, with a column for what the website states and a column for the date of the last comparison, costs little and catches most drift.

## Comparing the two halves: a routine check

A check that compares the two halves takes minutes per name and should run on a schedule and after every change.

<figure class="fig">
<figcaption><b>Comparing the DNS half and the onchain half of a name</b></figcaption>
<ol class="fig-steps">
<li><b>Read the DNS statement</b>Open the page on the organization's known domain that declares its onchain names, and any text record the domain carries for the same purpose. Note each name and its stated use.</li>
<li><b>Read the registry record</b>For each name, look up the registry record on a block explorer. Confirm that the TLD is still held by the wallet the organization expects and that each name exists as stated.</li>
<li><b>Check where each name resolves</b>Resolve each name in a supporting wallet and confirm that it points to the address the organization's own records expect, and that any website or text records are current.</li>
<li><b>Check the references</b>Confirm that contracts, supplier records, support scripts and guidelines refer to the names the page lists, and to none it does not.</li>
<li><b>Record the result</b>Write the date and the outcome in the register, and open a correction for any difference before the next payment run or publication.</li>
</ol>
</figure>

The check needs resolution support to complete its third step. Onchain names resolve outside the DNS root, so an ordinary browser does not open them. Freename names resolve in Bitcoin.com Wallet, in MetaMask through Freename's resolver, and in desktop browsers with the Freename Web3 extension installed. That coverage is partial and it changes; the page on [what is live](/whats-live) lists the current capabilities with their sources.

## Retiring a name without leaving a gap

Retiring a name is where the link most often breaks, because retirement feels like removal and removal feels finished. A retired name that still resolves, with no statement anywhere that it has been retired, is the worst state the link can be in.

A clean retirement does three things. First, it changes the DNS statement rather than deleting it: the page says that the name is no longer in use, since when, and what replaces it. A counterparty who arrives with an old reference finds an answer instead of a missing page. Second, it changes the name's own records so that nobody using it is led to believe it is active, for example by removing payment addresses and replacing the website record with one that points to the statement. Third, it updates every internal reference so that no contract, template or script still offers the retired name.

Whether a name already issued can be withdrawn is a separate question. For names the organization issued to itself under its own TLD, the holder keeps control. For names issued to others, withdrawal or change is decided case by case, which is why the organization's rules for names should say in advance what happens when a use ends. The page on [putting a TLD to work after the transfer](/post-transfer-activation) covers those rules at launch.

## Payments: where a stale link costs money

Of all the uses of an onchain name, payments are where a gap between the halves is most expensive, because a payment to the wrong address is usually irreversible.

The principle is that the name, not the address, is what the organization asks counterparties to rely on, and that the name is resolved at the moment of payment. A supplier who stored the organization's address a year ago and pays it from memory has bypassed the name entirely; if the address has since been rotated, the funds go to an address the organization may no longer control. The page on [payments to a name](/onchain-tld-payments) describes the use.

Payment tools that resolve the name inside the flow remove most of this risk. An onchain payment router such as shaka lets a payment link pay out to a name rather than a raw address, with the split between parties agreed and signed onchain before any funds move; it routes funds and does not hold them. Whatever tool is used, three rules hold: counterparties pay the name, not a stored address; any change of address is announced on the DNS side before it takes effect; and a first payment to a name, or the first payment after a change, is confirmed through a separate channel.

## A scenario: a divestment, step by step

The following scenario is invented, to show how the pieces fit when a business event touches both halves. A group holds `.yourbrand` and uses three names under it: `pay.yourbrand` for customer payments, `supply.yourbrand` for payments to suppliers, and a third name for one business unit that runs its own payments. The group sells that business unit.

**Before closing.** The owner of the link adds the unit's name to the transaction checklist. The parties agree whether the name goes with the unit or stays with the group. Because the TLD stays with the group, the unit cannot simply take its name along: the name would remain under the group's namespace, issued by the group. The parties agree instead that the unit will stop using the name on a set date and will announce its new payment details through its own channels.

**At closing.** The group updates its DNS statement: the unit's name moves to the list of retired names, with a line saying the unit now operates independently and should be contacted through its own channels. On the onchain side, the group removes the payment addresses from the name and points its website record at the statement. The register records both changes and the date of the comparison that confirmed them.

**After closing.** The group checks its contracts, templates and support scripts for references to the unit's name and removes them. Customers who still hold the old name in their records find, on resolving it, no payment address, and on the group's site, an explanation.

At no point in this sequence did either half say something the other contradicted. That is the whole objective. The business event was complex; the naming work was a short list of updates, made in the right order, by people who knew they owned them.

## Agents and machines read both halves too

The link is not only read by people. Software reads it as well, and increasingly so as AI agents carry out tasks such as payments and integrations for users.

An agent that checks a counterparty may read the text record on the organization's DNS domain, then resolve the onchain name, and compare the two. That is the same comparison a careful person makes, done automatically, and it fails in the same way when the halves disagree. An agent that finds a mismatch should stop rather than choose; an agent that finds a match on stale data proceeds confidently on the wrong answer.

For an organization that publishes names its own agents use, the same discipline applies. Each agent identity under the TLD should appear in the register and on the DNS side, and should be retired with the same care as any other name. ERC-8004, "Trustless Agents", is a draft Ethereum standard with registries for agent identity, reputation and validation; it is a draft and may change, and how naming registries plug into it is still evolving. The page on [identities for AI agents](/onchain-tld-ai-agents) covers the naming side.

## Where the DNS remains the anchor

The link runs both ways, but the two halves are not equal. The DNS domain is the anchor: it is the identity most counterparties already know, and it opens in every browser without added support. The onchain name draws its credibility from the statement on the known domain, not the other way round. A page reached through an onchain name that claims to be official proves nothing on its own, because anyone holding any TLD can write such a page.

That asymmetry sets priorities when something goes wrong. If the two halves disagree and the cause is not clear, the DNS statement is the reference, and payments to the name should pause until the onchain half is confirmed. If the DNS domain itself is ever compromised, the onchain records are not a substitute anchor; the organization's contracts and direct relationships with counterparties are.

If your organization is considering acquiring the onchain TLD that matches its name, the work described here is part of what follows the purchase. The audience page for [brands and legal teams](/brands-and-legal-teams) sets out the decision itself. Hush Partners acts for organizations that mandate the desk to find and approach a holder, under a standard mutual NDA, and the contact form on the site is the way to start.

## Questions people ask

### Should the website list the addresses a name resolves to?

Generally not. Listing the name and its purpose is enough, and it survives address rotation without change. Counterparties should resolve the name at the moment they use it. Where a raw address must be shared, for example with a counterparty whose systems cannot resolve names, share it through a direct, confirmed channel and record it in the register.

### How often should the two halves be compared?

After every change to either side, and on a regular schedule in between. The right interval depends on how many names are in use and how often they change; an organization with one payment name and no changes can check rarely, while one with many names in active use should check often.

### What should a counterparty do if the two halves disagree?

Treat the DNS statement on the known domain as the reference, pause any payment, and confirm with the organization through a channel already established, such as a contact named in the contract. A mismatch is not proof of anything wrong, but it is a reason to stop until it is explained.

### Does a text record in the DNS zone replace the page on the website?

It complements it. A text record suits software that checks automatically; a page suits people and can explain context, such as a retirement or a custody change. Keeping both, and keeping them identical in substance, covers both readers.
