One name, several blockchains: how a name maps to addresses

An onchain name is not, in itself, a single address. It is a record, stored on a blockchain, that can hold a list of addresses, one for each network the holder chooses to configure. When a wallet or payment router reads the name, it selects the entry that matches the network it is operating on, returns that address, and completes the transaction. Nothing else happens. There is no currency conversion, no bridging, no movement from one chain to another. The name simply points.

That mechanism is straightforward in theory and hazardous in practice. An organization that operates on three networks may configure two of them and leave the third silent. A counterparty who tries to pay on the unconfigured network is not necessarily warned in a way they understand. Depending on the tool they use, the payment fails, or it goes to an address the recipient never thought to watch. The cost of that oversight can be material, and a confirmed onchain transfer cannot be reversed by the sender.

This article explains how the mapping works from the ground up, how a wallet selects the right record, what happens when it finds nothing, and what procedures reduce the risk of error. It is written for the people who configure names and explain them to counterparties: treasury leads, product managers, legal advisers and the operators who run a namespace under a TLD.

Why an organization has more than one address

The starting point is a fact about blockchain architecture: addresses are not portable across networks. A string that receives funds on one network is not the same object as a visually identical string on another network. Some families of networks share an address format, so the same string of characters can be a valid destination on several of them. Sharing a format does not mean sharing a ledger. A deposit made on the wrong network lands in a different ledger, governed by different rules, and may not be accessible to the intended recipient at all.

Organizations accumulate multiple addresses for several reasons. Different business functions may run on different networks: a treasury that holds a reserve asset on one network, a payment rail that settles vendor invoices on a second, and a token program or loyalty mechanism on a third. Counterparties may have preferences or constraints: some operate only on networks that their compliance tooling supports, and an organization that wants to receive from them must meet them there. Network-specific smart contracts, for vesting, escrow or revenue sharing, create additional addresses that must be monitored and funded. Over time, the number of live addresses grows, and so does the operational load of communicating them accurately.

A human-readable name is the natural answer to that load. Instead of sharing a different address for each conversation, the organization publishes one name and configures it to answer correctly for each network a counterparty might use. The name becomes, in effect, a directory.

A name as a directory of addresses, one per network

When a name is issued and its records are set, the holder writes one or more address records into the resolver, the smart contract that holds the name’s configuration. Each record is keyed to a network identifier, under a scheme that depends on the registry. The resolver stores them as a list.

Consider a worked example. Assume an organization configures the name pay.yourbrand under a TLD it holds. It operates on four networks, which we will call Network A, Network B, Network C and Network D. It holds a distinct address on each. After configuration, the resolver for pay.yourbrand holds four address records, one per network. A fifth network, Network E, is used by one counterparty but was never added to the record. The mapping looks like this:

The name itself does not know which record will be requested next. It simply stores the list and waits.

This is comparable, in structure, to how a traditional DNS zone holds several record types for one domain: one record for web traffic, another for mail, a text record for verification. The difference is that the records here are keyed to blockchain networks rather than to services, and the resolver is a smart contract on a blockchain rather than a nameserver in the DNS. The lookup never touches the ICANN DNS root, which is why a name such as pay.yourbrand means nothing to a wallet or a browser that has not added support for the registry behind it. That support exists in some tools and not in others, and the picture shifts over time; the page on what is live lists the capabilities that work, with their sources.

The directory model has one consequence that is easy to miss. The quality of the name is the quality of its least maintained entry. A list of four correct records and one missing record is not “mostly right” from the point of view of the counterparty on the fifth network. For that counterparty, the name is either unusable or misleading, and they have no way of knowing which until they try.

How a wallet decides which address to use

When a user pastes or types pay.yourbrand into a supporting wallet, the wallet queries the resolver. The query includes the name and the identifier of the network the wallet is connected to, or of the asset the user has chosen to send. The resolver matches the identifier against its stored records and returns the address set for that network, if one exists.

The wallet does not ask the holder what network it should use. It asks the resolver what address is set for the network the wallet already knows it is on. If the wallet is connected to Network B, it receives Address AB. If it is connected to Network C, it receives Address AC. The user sees a human-readable name; the wallet handles the lookup out of sight.

This means the correctness of the outcome depends on two things: whether the sender’s network is one on which the recipient expects funds, and whether the holder has configured a record for that network. Neither is guaranteed. A wallet can be connected to a network the recipient never configured. A holder can forget to add a record for a network that has become active in its operations. The sender is badly placed to detect either problem. They see a name they trust and, at best, an address they have no means of checking against the recipient’s intentions.

A name can also be the destination of a payment link rather than of a manual transfer. shaka is an onchain payment router of that kind: its payment links are able to pay out to a name in place of a raw address, the parties agree and sign the split onchain before any funds move, and the router passes funds along without holding them. Whatever tool reads the name, a wallet or a router, the principle is the same. The name answers only for the networks its holder has configured, so the gaps in the mapping matter in every flow that relies on it.

What happens when a network has no record

If the resolver holds no address record for the network being queried, the lookup comes back empty. What the sender sees next depends on the wallet or integration, and you should not assume uniform behavior. Many tools report that the name could not be resolved and stop there. Some block the transaction until a valid address is entered by hand.

A third possibility deserves attention. Some naming setups allow a general or default address record alongside the network-specific ones, and an integration may return that default when the specific record is missing. Where that happens, the sender sees an address appear in the recipient field and has no reason to doubt it.

From a treasury point of view, the substituted address is the outcome to plan for, because it produces a completed payment rather than a visible failure. A sender who types pay.yourbrand on Network E and sees an address populated may not know that the address was configured with a different network in mind. They confirm the transaction. The funds move on Network E, to that address as it exists on Network E. Whether the recipient controls that address on Network E depends on how it was created, and whether anyone is watching it there is a separate question again.

From the recipient’s side, the funds are simply absent. They did not arrive on Network A, B, C or D. No notification exists in the systems the recipient monitors. Discovering the error requires the sender to share a transaction reference, the recipient to identify the network, and both parties to assess whether recovery is possible. Sometimes it is, with effort. Sometimes it is not, and the effort of finding out can be out of proportion to the amount.

The clean failure has a cost too, though a smaller one. A counterparty whose wallet refuses the name will ask for a raw address, often under time pressure, and a raw address supplied in a hurry is exactly the unverified, copied string the name was meant to replace.

The classic error: funds sent on a network the recipient does not watch

The situation above has a recurring form. It appears when an organization expands its network coverage without updating its name records and its counterparty communications at the same moment.

Consider a mid-sized manufacturer, invented for this illustration, that holds pay.yourbrand and has configured records for Network A and Network B. A new product line settles on Network C. The team opens a wallet on Network C, begins receiving from one counterparty who was given the raw address, and considers the setup functional. The name is not updated; there is no record for Network C. A second counterparty, operating only on Network C and unaware of the omission, sends a payment to pay.yourbrand. Assume their tool, finding no record for Network C, falls back to the address configured for Network A and completes the transaction.

The payment is now on Network C, at Address AA. It is not on Network A, and it is not at the new Network C wallet the treasury team reconciles against. Reconciliation fails. The counterparty believes it has paid, and it has a confirmed transaction to show for it. The manufacturer believes it has not been paid, and its records agree.

What happens next depends on what Address AA is. If it is an ordinary account controlled by a private key, and Network C shares the address format of Network A, the same key may control the same string on Network C, and the funds can be retrieved once someone thinks to look. If Address AA is a smart contract, such as a multisignature wallet, the position is harder. A contract exists only on the network where it was deployed. The same string on Network C may have no contract behind it, and nobody may be able to move what was sent there.

The structure of this fictional case reflects what happens when name maintenance lags behind operational change. The error is not technical: the resolver and the tools worked as designed. The error is procedural. The name record was not updated when the organization’s network footprint changed.

Preventing it requires treating the name record as a live operational document, not a one-time configuration. Every time an address on a new network becomes part of the organization’s payment operations, the resolver record for the relevant names must be updated before that network is mentioned to counterparties.

Naming conventions that reduce confusion

A single name like pay.yourbrand is easy to communicate and easy to remember. It becomes a liability when it is used on networks whose records have not been set, or when different names in the same namespace are configured inconsistently.

Several conventions help:

Use function-specific names, not network-specific names. A name like pay.yourbrand is appropriate when all configured networks lead to the same economic outcome: the organization’s treasury receives funds. A name like networkb.yourbrand inverts the logic and forces senders to choose the right name for the network they happen to be on. That choice is precisely what the resolver is supposed to remove. Network-specific names create more opportunities for error, not fewer.

Use a consistent name for the same function across all networks it supports. If pay.yourbrand is the payment name, it should hold records for every network on which payments are accepted. If vendor payments are accepted on three networks and treasury receipts on a fourth, consider whether those should be separate names with documented scope: vendors.yourbrand and treasury.yourbrand, each configured only for the networks it actually serves.

Decide the names before you need them. On Freename, nobody but the holder of a TLD is able to issue names under it, so no outside party can take pay.yourbrand ahead of you. The risk is internal: two teams issuing overlapping names for the same function, each configured differently. Settle the list of functional names early, and issue a name only when its purpose and its owner inside the organization are clear. The glossary defines the terms used here, including the difference between holding a TLD and configuring a name under it.

Document what each name is for and what networks it covers. A short internal document is the minimum governance record for any organization that uses onchain names operationally: a table with the name, its purpose, the networks it covers, the address for each, and the date it was last reviewed.

Telling counterparties what is supported

A name is only as useful as the counterparty’s ability to use it correctly. Telling a counterparty “our payment name is pay.yourbrand” without specifying which networks are configured invites the errors described above. The counterparty’s wallet will query the resolver for whatever network the counterparty happens to be on. If that network has no record, the outcome is left to the behavior of their tool.

The communication to counterparties should be specific:

• The name: pay.yourbrand
• The networks for which records are set, listed explicitly
• What to do if the counterparty’s preferred network is not on the list

That last point matters. If the counterparty operates only on Network E and the organization has no record for Network E, there is no safe path through the name. The counterparty must either use a different network or receive a raw address for Network E directly, if the organization has one. Telling them this explicitly is a service; leaving them to discover it by sending funds is not.

It also helps to tell counterparties what the name does not do. A name does not convert an asset, and it does not move funds from one network to another. A sender who holds an asset on Network E cannot reach Address AB by typing the name. Counterparties who are new to onchain payments sometimes expect the name to work like a bank identifier that routes any incoming payment to the right place. Correcting that expectation in the first exchange prevents a class of errors that no record can fix. The page on payments to a name gives the wider context.

The right format depends on the relationship. For a bilateral arrangement between two treasury teams, a short document with the supported networks is sufficient, sent through the channel the two teams already use for payment instructions. For a public-facing payment name that any counterparty might use, the supported networks should appear on the organization’s own documentation page, linked from wherever the name itself is published. A counterparty who has to contact the organization to find out whether their network is supported may simply give up and request a raw address instead.

Reviewing the mapping when networks are added or dropped

The resolver record for a name is not static. Networks are added to an organization’s operations; networks are retired; wallet addresses change when keys are rotated; multisignature setups change when signatories change. Each of those events is a potential source of divergence between what the name says and what is operationally true.

Adding a network is the most frequent change, and the order of operations matters more than any single step:

1. Confirm the addressEstablish and verify the address the organization will use to receive on the new network. If it is a multisignature address, confirm that it is deployed on that network and that the signatories and threshold are correct before any record is set.
2. Update the resolver recordWrite the new network identifier and address into the resolver for the relevant name or names. Check the resulting transaction on a block explorer before proceeding.
3. Test with a small transferSend a nominal amount from a controlled address on the new network to the name. Confirm receipt at the intended address. Do not mention the network to external counterparties until this test passes.
4. Update counterparty documentationAdd the new network to the list of supported networks in all counterparty-facing materials: documentation pages, bilateral agreements, treasury instructions. Date the update so that recipients know when the change took effect.
5. Archive the previous stateRecord what the mapping looked like before the update, with the date of change. This creates an audit trail if a historical transaction needs to be traced.

The same discipline applies in reverse when a network is dropped. Before removing a record, confirm that no pending obligations exist on that network. Check that counterparties who were using the name on that network have been notified and have moved to a supported alternative. Remove the record only after those confirmations. Removing a record without notice is like closing a bank account without telling the people who pay into it: the sender learns of the change only when a payment fails or goes astray.

A change of address on a network that stays supported is the third case, and the one most often forgotten. When keys are rotated or a multisignature wallet is replaced, the old address usually remains valid on the ledger. A name that still points to it will keep delivering funds to a wallet the organization has stopped watching. The record must change on the same day as the wallet, and the old address should stay under observation for a period afterward.

For organizations that use names as identities for automated processes, such as AI agents, programmatic settlement or recurring onchain obligations, the review cadence should follow the operational review of those processes, not an annual calendar. The page on names that resolve in wallets covers the wallet side of the picture.

The governance posture that contains the risk

Mapping one name to addresses on several chains is, at its core, a records management problem in technical dress. The resolver is a database. The wallet is a client that queries it. The risk arises not from the technology but from the gap between what the record says and what the organization’s operations require.

Three postures contain that risk.

Ownership of the record. Someone in the organization must own the resolver record as an operational document: know what it says, know when it was last updated, and be able to update it within a defined time window when something changes. In practice, this is often split between a technical team that can execute the update and a treasury or legal team that approves it. The handoff between them must be documented.

Communication before use. Counterparties must know what is supported before they attempt a transaction, not after. A name that is not yet configured for a network should not be shared with any counterparty who might use that network, even informally. The informal share, whether a chat message, a meeting note or a verbal instruction, is a common starting point for these errors because it travels without the list of supported networks attached.

Periodic reconciliation. At a defined interval, compare the name’s resolver records against the organization’s live wallet inventory. Every address in the resolver should correspond to an address that the organization actively monitors and controls. Every address the organization actively uses for incoming funds should appear in the resolver for the relevant names. Gaps in either direction are findings that require action.

Reconciliation does not depend on any private system. The records of a name sit on a public ledger, so an internal auditor, or a counterparty’s own team, can read them on a block explorer and compare them with the documentation they were given. That transparency cuts both ways. It makes the review cheap, and it means a stale record is visible to anyone who looks.

Taking the next step with a configured TLD

If your organization has acquired a TLD and is working through the configuration of names and network records, the practical starting point is a complete inventory: every network the organization uses, every address on each, and every name that should resolve to each address. That inventory drives the resolver configuration and the counterparty communication.

Two resources on this site help from there. The Launch Roadmap is a free tool that builds a launch roadmap for a newly acquired TLD. Post-transfer activation is the service concerned with putting a TLD to work once the transfer is complete.

Where an organization does not yet hold the TLD that matches its brand, it can mandate Hush Partners to find and approach a holder. Reach the desk through the contact form.

Questions people ask

Can I configure the same address for all networks?

You can write the same address string into several network records, provided those networks share an address format. Whether that address is valid, controlled and monitored on each of those networks is a separate question. The same string refers to a different account on each network’s ledger, and a smart contract wallet deployed on one network does not exist on another unless it has been deployed there too. Test each configured network individually before communicating the name.

What if a counterparty’s wallet does not support onchain name resolution at all?

Some wallets do not query onchain resolvers. In that case, the name does not resolve, and the wallet will require a raw address. The correct response is to maintain raw addresses for every supported network and provide them on request through a verified channel. The name is a convenience layer, not a replacement for the underlying addresses. Always have both ready.

Who can change a name’s resolver records?

As a general matter, the records of a name are controlled by whoever controls the wallet that holds it; the registry’s documentation gives the exact rule. If that wallet is a multisignature wallet, a record update needs the number of approvals the wallet defines. Key management for the holding wallet is therefore a prerequisite for accurate records. Losing control of that wallet means losing the ability to update the resolver.

Is there a standard format for communicating supported networks to counterparties?

No single format is in general use. The practical approach is a short table: name, supported networks, address per network, date of last update. Some organizations include this in a treasury operations document; others publish it on an internal wiki or a public documentation page. Whatever format is used, the date of last update is essential, because counterparties need to know whether the information they hold is still valid.

Can a name hold records for a network other than the one the TLD is recorded on?

The TLD is recorded on one blockchain, and the names issued under it are recorded there too. The address records of a name are a different matter: each is an entry in a smart contract that pairs a network identifier with an address, and that address can belong to another network. Which network identifiers a given resolver accepts is a question for the registry’s documentation, and the answer can change.