How an onchain name resolves, and where it does not

Owning an onchain name and being able to use it are two different things. The token in the wallet records who holds the name. Resolution is what turns the string into something a wallet or a browser can act on. Without resolution, a name is a record on a ledger that nothing reads at the moment it is needed.

This article follows one name, pay.yourbrand, from the moment it is typed to the moment an address or a website comes back, first inside a wallet and then inside a browser. At each step, it explains what has to happen, which software makes it happen, and where the sequence stops. The comparison with the DNS is deliberate: the DNS is the baseline most decision-makers already understand, and the differences explain nearly everything about where an onchain name works.

After reading, you will be able to explain resolution to a colleague, state accurately where pay.yourbrand works and where it does not, and identify the gaps that matter for any customer-facing use of an onchain name.

What resolution means, starting from the DNS

Every time a browser loads a page, the device consults the Domain Name System, the DNS, to translate a readable string such as example.com into the numeric address of a server. The DNS is a globally distributed database with a single starting point, the DNS root, coordinated by ICANN. Authority for each TLD is delegated to a registry operator. That operator works with registrars, who register names under the TLD for their customers. The chain of authority runs outward from the DNS root, and every DNS resolver knows to start there.

Resolution, in the DNS sense, is the act of walking that chain: ask the DNS root which servers know about .com, ask those servers which servers know about example.com, and get an address back. The whole lookup usually completes in a fraction of a second and is invisible to the user.

Onchain names follow the same logical shape (a string is entered, a record is queried, a result comes back), but they use a different chain of authority. The record lives on a public blockchain, not in the ICANN root zone. The software that reads that record is a resolver that knows how to query a blockchain, not a DNS server. And the applications, wallets and browsers, have to be built or extended to call that resolver instead of the DNS. When they are not, the name does not resolve: the application rejects it or returns an error.

The practical point follows directly. In the DNS, resolution is a property of the network: once a name is delegated, every device can find it. Onchain, resolution is a property of each application: a name works where the software has been taught to look for it, and nowhere else.

Where the record of an onchain name lives

Start with .yourbrand itself: the Freename registry records a TLD onchain, as a token that a wallet holds. When a name such as pay.yourbrand is issued under that TLD, a corresponding record is written to the blockchain. That record can store data, such as an address for payments or a pointer to a website published on IPFS (a network that stores and serves files by their content, not by their location). The record is updated by a transaction sent from the wallet that controls the name.

That registry record is public: the entry for pay.yourbrand, like any other, can be checked by anyone on a block explorer. Control follows the wallet: whoever controls the wallet that holds the name can change its records. In the DNS, control runs through an account with a registrar, inside a hierarchy of contracts and policies that reaches up to ICANN. Onchain, there is no registrar account in the middle. That is a real difference in who can act on a record, although the terms of the registry and the design of its smart contracts still apply, and they are worth reading before you rely on them.

That model has a consequence for resolution. In the DNS, a change made at the top of the hierarchy reaches every resolver, because every resolver follows the same delegation. Onchain, there is no equivalent single point. A resolver has to read the right blockchain, interpret the right record format, and be integrated into the right applications. Each of those steps is deliberate work by the parties who build and maintain the software.

A name such as pay.yourbrand can be issued by one party only, the holder of the TLD above it. That exclusivity is enforced by the registry’s smart contracts, not only by policy. A smart contract is a program that runs on a blockchain and applies its rules automatically. In this context, a request to issue a name under .yourbrand that does not come from the holder of the TLD is refused.

What a resolver is

A resolver is the software component that receives a query about a name and returns a record. In the DNS, a resolver sits between the user’s device and the DNS hierarchy and does the walking described above, so the application does not have to. For onchain names, a resolver reads from a blockchain instead of from DNS servers.

A resolver for onchain names has several jobs. It identifies which naming system the name belongs to and where its records are kept. It reads the record stored there. It picks the field that matches the question asked: an address when a wallet asks, a website pointer when a browser asks. Then it returns that field to the application. The resolver is the bridge between the record and the software. If the application is not set up to call it, the bridge is not there, however complete the record is.

Naming systems do not all build this component in the same way, and you do not need the engineering detail to make decisions. Two points are enough. First, a resolver belongs to a naming system: the one that serves Freename names is Freename’s resolver, and MetaMask supports Freename names through it. Second, a resolver is only useful through the applications that call it. The glossary defines the component terms if any are unfamiliar.

Resolution in a wallet: turning a name into an address

The most direct use of an onchain name is payment addressing. Instead of pasting a long hexadecimal address, the sender types pay.yourbrand and the wallet retrieves the address stored in that name’s record. The name does for an address what a domain name does for a server: it replaces a string nobody can remember or check by eye with one that people can read.

1. The sender enters the nameThe sender types pay.yourbrand into the recipient field of a compatible wallet. The wallet recognizes the string as a name, not as a raw address.
2. The wallet calls the resolverThe wallet sends a query to the resolver that serves the naming system the name belongs to. For a Freename name, that is Freename's resolver.
3. The resolver reads the recordThe resolver looks up the record of pay.yourbrand on the blockchain and reads the address its holder stored there.
4. The address comes backThe resolver returns the address. The wallet fills in the recipient and shows it to the sender.
5. The sender confirmsThe sender reviews the resolved address and approves the transaction. The payment is sent to the address, not to the name: the name was only the way to find it.

Two things can stop this flow. First, if the wallet does not support the naming system, the second step never happens: the wallet treats the string as an invalid address. Second, if the holder issued the name but never stored an address in its record, the resolver has nothing to return. Holding a name is not the same as configuring it. The page on putting a TLD to work after a transfer covers that side of the work.

There is also a point of care that applies even when everything works. The last step matters. A name makes an address easier to enter, and the wallet still shows the address it resolved. A sender who pays a large amount should compare that address with the one the recipient published through another channel, in the same way a finance team confirms bank details before a first transfer. A name reduces copying errors. It does not replace verification.

Freename names are supported in Bitcoin.com Wallet, and in MetaMask through Freename’s resolver. Coverage is partial and changes as integrations are built or updated. Any statement about which wallets support a name should be checked against the registry’s own documentation at the moment you rely on it, not taken from a list assembled earlier.

Resolution in a browser: why support is needed

A browser follows the DNS by default. It has no built-in knowledge of onchain names. If a user types an address under .yourbrand into the address bar, the browser asks the DNS, gets no answer because .yourbrand is not in the ICANN root zone, and shows an error or hands the string to a search engine. The name exists onchain. The browser has no instruction to look there.

Support can reach a browser in two ways.

Through an extension

A browser extension is a small add-on that the user installs. It recognizes names that belong to a naming system it knows and sends the query to the appropriate resolver instead of the DNS. Freename names are supported in desktop browsers through the Freename Web3 extension. Once it is installed, a Freename name opens in that browser. A user who has not installed it sees the same failure as before.

Through the browser itself

A browser maker can also build support into the browser, which removes the installation step. Whether and when any browser does so is its maker’s decision. Nothing in this article should be read as a statement that a given browser will.

The distance between those two states matters for any customer-facing use. An extension requires a download, a grant of permissions, and a conscious choice by the user. In many organizations, employees cannot install extensions at all without approval from IT. A website that needs an extension to be reached is not the same product as one that opens in any browser with no setup.

A website on an onchain name also has to be published somewhere the resolver can point to. Freename’s website builder lets a holder build pages and publish them to IPFS, and the site is then reached through the holder’s onchain name in browsers that support it. The page on websites published on an onchain TLD sets out what that looks like in practice. For a business, the realistic audience is the set of visitors whose browser already has support, or who are willing to add it.

The DNS and onchain resolution compared

The same lookup, step by step, in each system.

The DNS has decades of head start and is present in practically every piece of networked software. On reach, the DNS is simply better, and nothing about onchain names changes that. What an onchain name offers is different: a public record, control held directly by a wallet, and a name that can carry a payment address as naturally as a website. The two systems serve overlapping but distinct purposes and run in parallel. One does not replace the other.

Where onchain names do not resolve

The honest answer is: in most software. An onchain name does not open in a browser that has no support for it. It does not resolve in a wallet that has not integrated the relevant resolver. It does not resolve in email clients, in messaging apps, in the lookup tools of an operating system, or in any application that uses the DNS and only the DNS. This is not a defect of one product. It follows from the model: the DNS is everywhere because every application was built on it, while an onchain naming system has to be adopted application by application.

Some consequences are easy to miss.

• Email. An onchain name is not an email domain. Mail servers find each other through the DNS, so an address under .yourbrand cannot receive mail.
• Links shared in messages. A link to a site on an onchain name, pasted into a chat or a document, opens only for readers whose browser has support. For everyone else it fails, and they have no way to know why.
• Search. A site that most browsers cannot reach should not be expected to behave like a DNS website in search engines.
• Mobile. The browser support described above is an extension for desktop browsers. Do not assume the same on a phone without checking.

For an organization deciding whether to direct customers to pay.yourbrand, the question is not whether resolution is technically possible. It is. The question is whether the customers who need to pay are using software that supports the name. That is a self-selected group: people who already use a compatible wallet, or who are prepared to.

For internal uses, the picture is more favorable. Payments between entities of a group, treasury operations and developer tooling all happen in an environment the organization controls, where a specific wallet or extension can be required. The pages on names that resolve in wallets and on what is live, with sources give the detail without speculation.

The way failure appears also matters. When a DNS name is down, people recognize an outage. When an onchain name does not resolve, the customer sees an “invalid address” message or a search results page, and concludes that the address is wrong or the company made a mistake. A name that customers cannot reach does not help them, and presenting it as one that works creates a problem the organization then has to explain.

What happens when two systems carry the same string

Onchain TLDs exist outside the ICANN root zone, and more than one naming system can record the same string independently. The same TLD can therefore exist in more than one place at once. An onchain TLD can also carry the same string as a TLD in the DNS, whether one that already exists or one that is delegated later. When that happens, software that supports both has to decide which record to return for a name the user typed.

Nothing obliges two resolvers to decide in the same way. One application may always prefer the DNS. Another may prefer the naming system it was built around. A third may ask the user. The result is that the same string can lead to different places in different software, which is exactly the confusion a naming system is supposed to prevent.

One structured answer to this problem is described in U.S. patent US 12,401,618 B1, held by Freename AG. It was filed on February 23, 2024 and granted on August 26, 2025. The patent covers rules-based resolution of names that collide: competing names are scored, and the result decides which one resolves. Among the weighted criteria is “first registration”, meaning the earliest date of creation. The collision of new ICANN TLDs with established web3 namespaces is named in the patent as a problem it addresses. The text is public on Google Patents, and Domain Name Wire reported on the grant.

It is important not to read more into it than it says. The patent describes a method. It is not a court ruling, and it does not bind ICANN or any other naming system. First registration is one criterion among several, so an early date of creation does not by itself settle which name resolves, and the patent does not tell you how a particular pair of names would come out.

For an organization that holds, or is considering acquiring, an onchain TLD whose string also exists or may come to exist in the DNS, the collision question belongs in the file from the start. The side-by-side comparison of an ICANN dotBrand and an onchain TLD covers the differences in authority and recognition between the two.

How resolution coverage tends to grow

Coverage grows one integration at a time. A naming system makes a resolver available. The developer of an application decides to call it. Users of that application can then use the names. Nothing in that sequence is automatic: each integration is a decision by the people who maintain the application, taken for their own reasons.

That explains the shape coverage tends to take, without any need to predict it.

Extensions tend to come before built-in browser support, because an extension can be published without the browser maker changing anything. Wallets are a shorter step than browsers, because a wallet is already built to read a blockchain, and turning a name into an address is close to what it does anyway. Controlled environments come before open ones, because an organization can require a given wallet or extension internally, while it cannot require anything of the public.

What moves a developer to integrate is ordinary: users who ask for it, a resolver that is straightforward to call, and enough names in real use to make the work worthwhile. A holder has no control over those decisions. A holder does control whether the names under the TLD are configured, so that they return something useful wherever support exists, and can tell the developers of the applications its customers use that the demand is there.

Coverage is partial and changes. No article and no adviser can say which software will support a given naming system at a given moment. A plan that depends on support that does not yet exist is a plan built on someone else’s decision.

What this means for an organization deciding what to do with a name

Resolution belongs in the internal brief before an organization commits an onchain name to any customer-facing use. The questions are concrete.

• Which wallets and browsers do the intended users actually run?
• Do those applications support the naming system the name belongs to?
• If an extension is needed, can those users reasonably be asked to install it?
• Are the records of the name configured, so that a supported application gets an answer?
• What does a user see when the name does not resolve, and where is the fallback?

If the answers to the first three are no or uncertain, the name is not ready for that use, and saying otherwise creates an expectation that cannot be met. The sound pattern is to publish the name next to the conventional route, never in place of it: the name together with the full address for a payment, the onchain site together with the DNS website.

That does not leave the name without a use. A name that does not resolve everywhere can still serve internal payment routing, developer environments, and the users who already run compatible software. Whether that is enough is a judgment for the organization, made on what works now and not on what may be supported later.

A test costs little and settles most arguments. Before any announcement, have someone outside the project type the name into each wallet and browser on the list of software your customers use, on a device that has never been set up for it. What that person sees is what your customers will see.

For teams concerned about onchain strings that match their brand, Namespace Watch and the free Namespace Exposure Score give a structured view of the exposure.

Hush Partners is a private desk for onchain TLDs. A TLD is sold or acquired through the desk under mandate, every exchange is covered by a standard mutual NDA, and closing runs through onchain escrow on an aftermarket. Only the client who gives the mandate is charged, and what that client pays is a fixed amount, never a percentage. Whoever answers a note from the desk, or buys a TLD it offers, pays the price of the TLD with no fee added. If the question of where a name resolves is part of a decision to acquire or to sell one, the desk is reached through the contact form.

Questions people ask

Does a change to a record take effect everywhere at once?

The record changes when the transaction that updates it is confirmed on the blockchain. A resolver that reads the blockchain directly sees the new value from then on. An application may keep an earlier answer for a while before asking again, as software often does. After changing a payment address, test the name in each supported wallet before telling anyone to use it.

What happens to the records when a name changes hands?

The records are stored with the name, so they do not reset because the holder changed. A payment address set by the previous holder may still be in place after a transfer. Reviewing and replacing every record is one of the first tasks of a new holder, before the name is used or announced.

Can the holder of an onchain TLD make a resolver stop resolving a competing name?

No. A resolver applies its own logic to decide which record to return, and the holder of a TLD has no authority over a resolver it does not operate. Legal remedies, such as trademark claims and dispute procedures, work separately from the behavior of software and do not automatically change what an application returns. Rules vary by country, and your own counsel decides what applies.

Does a TLD have to be renewed to keep resolving?

There is no annual renewal fee on a Freename TLD, so the TLD itself does not lapse for lack of a yearly payment in the way a DNS registration can. For the names issued under a TLD, check the registry’s current terms. Either way, resolution still depends on the records being set and on the application supporting the name.

Is an onchain TLD the same thing as a dotBrand applied for through ICANN?

No. A dotBrand is delegated in the DNS root and resolves in every application that uses the DNS. An onchain TLD is recorded on a blockchain and resolves only in software that has integrated the relevant resolver. They differ in authority, cost, control and recognition, and an organization can reasonably consider each on its own merits.