# What a resolver is, and why it decides where a name works
> Between a name and an address there is a piece of software that answers the question. What it does, who runs it, and why it matters to an owner.
Source: https://hush.partners/what-a-resolver-is
Category: Onchain today
Published by Hush Partners.
---
Every name is a question. When someone types `pay.yourbrand` into a wallet or a browser, the software receiving that string has to decide what it means: which wallet address, which website, which record to return. The component that performs that lookup is called a resolver. It is not the name itself, not the registry that issued the name, and not the blockchain storing the record. It is the layer that answers when something asks what a name points to.
Most people who meet the word "resolver" in the context of onchain names already use one without knowing it. Every time a browser opens a website, a resolver is working in the background. The onchain version follows the same logic but reads from a different source of truth. The difference between those two sources, and the matter of who controls each resolver, explains nearly everything about where an onchain name will and will not work.
This article builds the concept from the DNS you already use, then moves to the onchain equivalent, and finishes with practical questions that any owner, operator or adviser can put to a wallet or a browser before relying on resolution. By the end you should be able to explain the word to a colleague and predict, for a given name and a given piece of software, whether the name will work there.
## The question every name raises
A name on its own is only a string of characters. The string `pay.yourbrand` carries no routing information. Something else has to convert it into an address or a resource that software can act on. In a payment context, that destination is usually a wallet address: a long string of letters and digits that nobody types voluntarily. In a website context, the destination is an IP address, the numeric address of a server, or a content hash, the fingerprint of a set of files on a distributed file system such as IPFS. In both cases, the name is the human-readable layer and the destination is the machine-readable layer, and a resolver bridges the two.
This is not a web3 invention. It is the original problem the Domain Name System was built to solve. The approach the DNS takes is to separate the human-readable name from the technical address and to maintain an infrastructure that answers lookup requests. Onchain naming systems follow the same model, with important differences in who controls that infrastructure.
One consequence follows at once, and it is easy to miss. The same name can raise different questions depending on who is asking. A wallet asks for a payment address on a particular blockchain. A browser asks where a website lives. An application may ask for a piece of text attached to the name. A resolver that answers the first question does not necessarily answer the second. "Does this name resolve?" is therefore an incomplete question. The complete one is: does this name resolve, for this purpose, in this software?
## How the DNS handles the same problem
When you type an ordinary web address such as `yourbrand.com` into a browser, your device passes the query to a recursive resolver, a service that does the looking up on your behalf. It is usually operated by your internet service provider, by your employer's network team or by a public resolver service. That resolver works down a hierarchy. It first asks the servers of the DNS root which servers are authoritative for the ending of the name. It then asks those servers which name server holds the records for `yourbrand.com`, and finally asks that name server for the answer. The answer is an IP address, and the browser connects to it.
Two things in that description matter for what follows. First, the recursive resolver is run by a third party, not by the owner of the domain. The owner controls the records it publishes, but not the resolver that reads them. Second, the entire chain works because every resolver starts from the same place: the ICANN root, the single list of top-level domains that the whole public DNS agrees on. Whoever operates a resolver, it begins there. That common starting point is what makes a DNS name work everywhere without any coordination between individual resolver operators.
The DNS has corners where this universality stops, and they are a useful preview. Many organizations run internal names that resolve only inside their own network, because only their own resolvers have been told about them. Step outside the network and the same name returns nothing. Nobody considers that a fault. The name works where a resolver answers for it.
Onchain names do not have the common starting point, and that is the source of almost every practical limit they carry.
## The onchain equivalent
An onchain name is a record stored in a smart contract on a blockchain. A smart contract is a program that runs on a distributed network and keeps its data in a public ledger that is very hard to alter. The registry is the smart contract that records who holds a given name. The resolver is the component that reads from that contract and returns a result to the software asking the question.
In some systems the resolver is itself a smart contract: a separate program that maps a name to its records. In others the resolver is ordinary software, a library or a service, that queries the blockchain and returns the answer. For a wallet or a browser trying to resolve `pay.yourbrand`, that distinction is invisible, and a manager does not need to follow it further. What matters is whether the wallet or browser has been built to call that resolver at all.
The owner of an onchain name sets its records: a wallet address for each blockchain the name should receive payments on, a content hash if a website is published, and text records for other information. Those records are public, and anyone who reads the contract can verify them.
It helps to keep three layers apart when you read or hear a claim about an onchain name. The registry says who holds the name. The records say what the holder wants the name to point to. The resolver, inside a given piece of software, decides whether that software ever reads those records. A statement such as "the name is live" can be true of the first two layers and still tell you nothing about the third.
### DNS and onchain resolution compared
The table below maps the same functions across the two systems. The goal is not to declare one superior. For most public internet traffic the DNS remains the better-supported system, a point made plainly in the [comparison between a dotBrand and an onchain TLD](/dotbrand-vs-onchain-tld). The goal is to show where the resolver fits in each structure.
| Function | DNS | Onchain |
|---|---|---|
| Authoritative record store | Name servers run by the owner or its provider | Smart contract on a public blockchain |
| Resolver operator | ISP, public resolver service or enterprise network | Wallet, browser, extension or application developer |
| Who chooses the resolver | The user's device or network settings | The developer, then sometimes the user |
| Coverage by default | Universal: one DNS root | Partial: no shared equivalent |
| Owner controls records | Yes | Yes |
| Owner controls resolver choice | No | No |
The column on the right carries the weight of this article. Because no single starting point is shared by all onchain resolvers, each wallet, browser and application makes an independent decision about which namespaces and which resolvers to support. Coverage is therefore a function of adoption by software developers, not a property of the name itself.
The last two rows deserve a second look, because they are identical in both columns. An owner's position toward resolvers is the same in the DNS and onchain: it publishes, others read. What differs is the row above them. In the DNS the owner never has to think about resolvers, because all of them reach its records by the same path. Onchain, the owner has to think about them one by one.
## Who runs resolvers and who decides which one the software asks
In the DNS, resolver operators are a known category: internet service providers, enterprise IT teams and public resolver services. Onchain, the party that decides is whoever built the application the user is running.
When a user opens a wallet and types a name into the recipient field, that wallet contains code, written by its developers, that either does or does not look up names in that namespace. If it does, it calls a specific resolver that the wallet's team has chosen to integrate. The user rarely sees that choice, and can seldom change it without installing a different wallet or an extension.
Browsers are structurally similar. An ordinary browser has no built-in ability to resolve onchain names, because onchain TLDs are not in the ICANN DNS root and an ordinary recursive resolver has no record of them. Browser support typically comes by one of three routes: an extension that recognizes onchain names and sends them to an onchain resolver, a browser built from the start to support a given namespace, or a gateway that makes the onchain record reachable through a conventional web address. Each route is a separate integration decision by a separate party.
For Freename names specifically, resolution is supported in Bitcoin.com Wallet, in MetaMask through Freename's resolver, and in desktop browsers through the Freename Web3 extension. That list is partial, and it moves as developers add or change support. The [capabilities that are live](/whats-live) are documented separately with sources. No onchain naming system offers universal resolution, and a claim that one does describes a goal, not a fact.
The practical reading is that there are three decision makers between a name and its user, and the owner is none of them. The developer decides whether the software supports the namespace. The developer also decides which resolver it calls. The user decides which software to install, and whether to add an extension. An owner influences all three and commands none.
## Why support is piecemeal
The absence of a common starting point is the structural cause. Every developer makes a standalone decision: which namespaces to support, which resolver to query, and how to handle names the software does not recognize. No authority can instruct a wallet developer to support a given TLD, and nothing extends resolution to a new platform automatically when a TLD is created.
This is a consequence of design, not an oversight. Onchain naming systems exist outside the governance structures that make the DNS work universally. For many users that independence is part of the appeal. Its cost is that each application serves its own subset of names, and that the picture is assembled integration by integration.
Each integration is also work for the developer who takes it on. Supporting a namespace means writing and testing code, keeping it up to date as the registry evolves, and answering users when a lookup fails. A wallet team weighs that work against the number of its users who would benefit. This is ordinary product reasoning, and it explains why support tends to arrive first where a namespace already has users, and why a new TLD with no names under it gives a developer little reason to act.
The practical consequence for an owner or operator is that building a useful namespace requires active integration work. Holding a TLD and issuing names under it is the prerequisite. Resolution is a separate project, and it belongs to the period of [putting a TLD to work after the transfer](/post-transfer-activation), not to the acquisition itself.
## What happens when two systems answer for the same string
Onchain TLDs are created outside the ICANN DNS root, and ICANN adds new TLDs through its own application process. The same string can therefore exist both as an ICANN TLD and as an onchain TLD. When a user types a name ending in that string, the software returns one result or the other, depending on the source it was built to consult.
From the perspective of any individual resolver, there is no conflict: it answers from its own source and ignores the other. From the perspective of the name owner, the result depends entirely on which resolver the end user's software calls. The same is true between two onchain registries that have each issued the same string.
A resolver that consults more than one source needs a rule for choosing between them. The rule can be simple, such as always preferring the DNS, or always preferring one registry. It can also be more elaborate. Freename AG holds U.S. patent US 12,401,618 B1 on one such approach. The filing date is February 23, 2024, and the grant followed on August 26, 2025. The patent covers resolution by rules where names collide: the competing names receive scores, and the outcome of the scoring determines the one that resolves. In that scoring a resolver built on the method weighs several criteria, and one of them is "first registration", that is, the earliest date of creation. A problem the text sets out to address is that of new ICANN TLDs colliding with established web3 namespaces. Anyone who wants to see how such a resolver rule is worded can read the patent on Google Patents; the grant itself was covered by Domain Name Wire.
Read the patent for what it is. It sets out a method, no court has ruled on anything by granting it, and ICANN is not bound by it. Neither is any other resolver operator. What it shows is that a resolver can be built to apply stated rules to a collision, where otherwise the outcome would simply follow whichever source the developer happened to wire in.
For anyone holding an onchain TLD whose string also exists elsewhere, the operative question is therefore not "which system is right" but "which resolver does my audience use, and what rule does it apply." Whether a collision also raises a legal question, for example under trademark law, is a separate matter that varies by country and that your own counsel decides. The [glossary](/glossary) defines the terms used here.
## What an owner controls and what it does not
The owner of an onchain TLD, or of a name issued under one, controls a specific and bounded set of things. Knowing the boundary prevents both over-reliance on what the owner cannot change and under-investment in what it can.
### What the owner controls
The records associated with the name. An owner sets which wallet address a name resolves to on each blockchain, which content hash a name points to for a website, and which text records are attached. Those records live in a smart contract, and the owner can update them. Anyone who reads the contract, whether through a resolver or on a block explorer, a public website that displays what a blockchain holds, sees the state the owner has set.
On a Freename TLD, the holder also controls issuance: nobody else can issue names under that TLD. The holder decides which names exist in the namespace. Under the registry's royalty program, part of every registration fee paid for a name under the TLD goes to the holder, on the registry's current terms and once its activation conditions are met. That share is not free of cost to the owner: the TLD has no annual renewal fee, but taking part in the royalty program carries an annual cost set by the registry. Some TLDs were registered under earlier terms that include the program for life, and whether those terms follow the TLD to a buyer is a point to confirm with the registry before closing. The [subname revenue calculator](/subname-revenue-calculator) estimates what that can amount to at different issuance volumes.
The owner also controls the effort it puts into distribution: which developers it approaches, what it asks them to support, and how clearly it tells its own users which software to use.
### What the owner does not control
Two further limits follow from that one. The owner does not control how a collision is handled by a resolver that consults more than one source. And it does not control whether a given user has installed the wallet or the extension that makes resolution possible.
The contrast with the DNS is narrow but decisive. The owner of `yourbrand.com` cannot choose the recursive resolver a visitor's device consults either, and cannot order a corporate network to let its records through. But every resolver of the public DNS ends up at the same authoritative answer. Onchain, two well-built resolvers may return different answers for the same string, because they draw from different registries.
Owners who want to extend the reach of their names should treat resolution as a distribution problem, not a configuration problem. Configuration is finished in an afternoon and is entirely in the owner's hands. Distribution is a list of third parties, each with its own priorities. The free [Launch Roadmap tool](/activation-roadmap) builds a launch roadmap for a newly acquired TLD, and resolver coverage belongs on that roadmap from the first line.
## Questions to ask a wallet or a browser about support
Before building a payment flow or a website on an onchain name, put a set of direct questions to the software that will handle the lookup. The documentation of a wallet or a browser often answers them. Where it does not, its support team can.
Five questions to settle before you rely on a name
Which namespaces do you resolve?Ask for the specific TLDs or registries that are supported. "Web3 names" is not an answer. Support is either built for a given namespace or it is not.
Which resolver do you call?The developer should be able to say which resolver the software queries and who operates it. If it is a third-party service, ask what happens when that service is unavailable.
How do you handle a string that exists in more than one system?Software that reads from several onchain registries, or from both the DNS and an onchain registry, needs a rule for collisions. Ask what the rule is and whether it is documented.
Is resolution built in, or does it need user action?Some wallets resolve names directly in the send field. Others need the user to install an extension or change a setting. Know which applies, because your users will meet the barrier.
Who decides which namespaces are added, and how often?Software that supports a registry does not always pick up TLDs created after the integration was built. Ask how new TLDs are added and who makes the decision.
These questions are not confrontational. A team that has thought carefully about resolution will answer them quickly and precisely. A vague answer is itself information: it suggests the integration is shallow and may not behave reliably under the conditions your use requires.
Which question matters most depends on the use. For [names that resolve in wallets](/onchain-tld-wallets), built-in versus extension-based support comes first, because it shapes every payment made to a name. For [websites published on an onchain TLD](/onchain-tld-websites), the question is which browsers can open the site and what a visitor has to install beforehand.
## A way to reason about any name before you depend on it
You can now test a claim about a name without technical help. Take the name, the purpose and the software, and walk through three checks in order.
First, the record. Does the name carry a record for this purpose: a payment address on the right blockchain, or a content hash for a site? The record is public, so this is a matter of looking, not of trusting.
Second, the software. Does the wallet or browser your audience actually uses support this namespace, for this purpose, and through which resolver? This is where most names stop, and it is the check that documentation and the five questions above are for.
Third, the user. Does support work as installed, or must the user add something first? A name that resolves only after an installation works for a motivated audience and fails for a casual one.
A name passes for a given audience only when all three checks pass. That gives you a sober way to describe the position to a board or a client: not "the name works" or "the name does not work", but "the name works for payments in these wallets, and for the website in these browsers with this extension." For a legal or brand protection team, the same discipline applies to evidence. A record of what a name pointed to is complete only when it states which software was used to look it up.
It also shows where the DNS is simply the better tool. If the audience is the general public using ordinary browsers with nothing installed, a DNS name reaches all of it and an onchain name reaches part of it. An onchain name earns its place where the audience already uses supporting software, or where the function, such as paying to a name from a wallet, is one the DNS does not perform.
## Mapping resolver coverage for your own TLD
The concrete next step is a one-page coverage map. List the two or three uses you intend for the TLD. Against each, list the wallets and browsers your audience uses. Fill each cell with one of three entries: supported as installed, supported after a user action, or not supported. The empty and negative cells are your integration list, in order of the audience behind each one.
Keep the map current. Support changes, and each cell is worth confirming against the documentation of the wallet or browser itself before you rely on it.
Where the TLD has just changed hands, this work is part of what Hush Partners covers under post-transfer activation, the service concerned with putting a TLD to work after the transfer. If you are working with counsel on a namespace question and resolution is part of the picture, the desk is reached through the [contact form](/contact).
## Questions people ask
### Does a resolver decide who holds a name?
No. Holding is recorded by the registry, not by the resolver. On Freename, a TLD is a token recorded onchain and sits in a wallet; the registry record is public and anyone can check it on a block explorer. A resolver only reads what the registry and the records say, and a resolver that does not support a namespace changes nothing about who holds the names in it.
### If a wallet does not support my TLD, can support be added later?
Yes, in principle. A wallet developer can add a namespace by integrating the relevant resolver. Whether a specific wallet does so for a specific TLD is a product decision made by its team, and nothing obliges them to. A request carries more weight when the namespace already has names in use and a clear audience.
### What happens to resolution if the resolver is unavailable?
If the resolver is a third-party service, the name fails to resolve in the software that depends on it until the service returns. If the resolver is a smart contract, it is available as long as the blockchain is, but the application still needs working software to call it. In neither case are the records lost: they remain in the registry, and resolution resumes when the path to them does.
### Can the same name lead to different places in different wallets?
Yes. If two wallets use different resolvers, and those resolvers consult different registries or apply different collision rules, the same string can return different results. Neither wallet is malfunctioning. This is the strongest practical reason to ask, before you publish a name for payments, which resolver each of your audience's wallets calls.