Testing an onchain name before you publish it

You have an onchain name. Someone on your team has verified the registry record, confirmed the token is in the right wallet, and linked the name to a target address. The name looks correct from the inside. None of that tells you whether it works from the outside, in the environment your counterparty will actually use when the name appears on an invoice or a payment screen.

The gap between “set up in the registry” and “works reliably for the people who matter” is where a launch can go wrong. Resolution support is partial and uneven across wallets, routers, and browsers, and it changes. A name that resolves cleanly in the tool your team uses may fail entirely in the one tool your largest customer uses. Discovering that failure after you have printed the name on a term sheet is expensive. Discovering it beforehand costs an afternoon.

This article gives you a structured test plan: what to test, how to record the results, how to run a live payment under controlled conditions, and the single rule that determines whether the name is ready to announce. By the end you have a checklist you can hand to whoever runs the technical side of your activation, and a clear go or no-go criterion.

Why a payment name cannot be tested in isolation

A conventional domain name resolves through the ICANN DNS, a global infrastructure that every browser queries automatically. An onchain name resolves through a separate mechanism, outside the DNS root, that each application must deliberately implement. No application is required to support onchain resolution, and not all of them do. The ones that do may support different registries, different record types, or different fallback behaviors when a name is not found.

This matters for payment names in particular because the cost of failure is asymmetric. If a payment name fails to resolve in a wallet, the sender typically sees an error and cannot proceed. Some senders will then ask you for a raw address, but only after frustration and a support exchange that erodes confidence in the name you just put in front of them. A name that works is transparent. A name that does not work is not neutral: it is worse than no name at all, because it creates a failed transaction attempt in a commercial context.

The partial and changing nature of support is not a criticism of any particular wallet or registry. It is what partial adoption looks like: each application adds support on its own schedule. The right response is to know exactly where your name works, to test that scope before you publish, and to tell counterparties only what you have confirmed. The page on what is live keeps a sourced record of the capabilities that work.

Defining your scope before you test

Testing everything is not achievable, and testing the wrong things wastes time. The first step is to define the scope by asking one question: where will your audience actually use this name?

A payment name is typically used inside a wallet or a payment router when a counterparty sends funds. A site name is used inside a browser, either one that supports onchain resolution natively or one with an extension installed. Some names serve both purposes: they are entered in a wallet for payments and opened in a browser for a company profile or a credential page. Each purpose has different test requirements.

Write down every surface before you test anything:

• Which wallets are your counterparties most likely to use? If you serve a counterparty base that primarily uses MetaMask, that slot is your highest-priority test. If they use a mobile wallet from a different provider, that is your test target.
• Is there a payment router in the workflow? If payments are routed through a named tool, the name must resolve there specifically.
• Is there a site attached to this name? If so, which browsers will your audience use, with or without extensions?
• Are there secondary surfaces, such as AI agents, credential displays or directories, that your TLD is activated for?

Narrow the list to the surfaces that matter to your specific audience. A name that resolves correctly in every surface your counterparties use is ready. A name that resolves in surfaces they never use is not.

Scope also has a second dimension that is easy to miss: the conditions under which each surface is used. The same wallet can behave differently on a phone and in a desktop browser, and a counterparty who installed it long ago may not have the component that resolves your name. For each surface on the list, note the device type and whether anything has to be installed or enabled first. If your largest counterparty will tell you what they use, ask them. One precise answer from the party that matters most is worth more than a broad guess about the market.

As a reference point for wallet resolution, Freename names are supported in Bitcoin.com Wallet and in MetaMask through Freename’s resolver. Coverage is partial and changes: verify against the registry’s documentation before each test cycle, not once at setup.

Building the test case table

A test case has four components: the surface being tested (wallet, browser, router), the exact input (the full name as typed), the action taken (enter in send field, navigate to URL, submit payment), and the expected result. Writing down the expected result before you test forces precision: “it works” is not a result, but “the send field resolves pay.yourbrand to an address, and that address matches the one in the registry record” is.

The table below shows a minimal set of test cases for a name used for payments and as a site. Adapt the surface column to your actual scope.

Test IDs beginning with R are positive resolution tests. Test IDs beginning with N are negative tests, which are covered separately below. Run each test in a clean session to avoid cached results from a prior test affecting the outcome.

Running a live payment as a confirmation test

Resolving a name to an address in a wallet’s send field is not the same as completing a payment. The full payment path includes resolution, amount entry, gas fee handling, and transaction confirmation. Each step can surface problems that resolution alone does not reveal.

Run at least one live payment during the test phase. Keep it small, since the amount is a rounding error against the cost of a failed payment in production, and run it under controlled conditions.

The controls are what make the payment a test and not a gamble. Both wallets, sending and receiving, are under your control, so nothing leaves the organization. The expected destination is read from the registry record, never from the wallet being tested, because the wallet’s answer is the thing under examination. The amount and the asset are agreed before the test starts. One person operates the wallet and a second person compares the addresses, so the comparison is not made by the person who expects it to match. Change one variable per run: if you test a second wallet, keep the name, the amount and the destination the same.

Worked example, for illustration: assume a TLD holder issuing pay.yourbrand on a Freename-registered TLD, sending a token to a wallet they control, with the test wallet address confirmed in writing before the transfer.

Before the payment:

1. Note the exact address registered to pay.yourbrand in the registry record. This is the expected destination.
2. Check the balance of the destination wallet so you can verify the arrival.
3. Confirm the sending wallet has enough balance for the test amount plus the expected gas cost.

During the payment:

4. Enter pay.yourbrand in the send field of the target wallet.
5. Confirm the resolved address that the wallet displays. It must match the address from step 1, character for character, before you proceed.
6. Send the minimum test amount.

After the payment:

7. Check the destination wallet balance. The test amount must have arrived.
8. Check the block explorer for the transaction record. The recipient address on the transaction must match the address from step 1.
9. Record the transaction hash as your evidence.

If the resolved address displayed by the wallet does not match the registry record before you confirm, stop. Do not proceed to send. The mismatch is a test failure and must be investigated before the name is used in any real payment.

A payment router adds one more path to test. On shaka, an onchain payment router, a payment link can pay out to a name instead of a raw address, and the split between parties is agreed and signed onchain before funds move. If a router is in your scope, run the same controlled payment through it and apply the same check: the funds must arrive at the address in the registry record.

The one-day test plan as a procedure

The pieces above and the ones that follow fit into one ordered sequence. The order matters: each step produces what the next one relies on, and the decision comes only after the evidence is compiled.

1. Define scopeList every surface your audience will use. Reduce to the set you will test. Write down the expected result for each test case before you begin.
2. Verify the registry recordCheck the name's registration and linked address on the block explorer. Confirm the token is in the correct wallet and the linked address is the intended destination. Record both.
3. Run positive resolution testsEnter the name in each in-scope wallet and browser. For each, record whether the name resolved, what address was returned, and whether that address matches the registry record.
4. Run the live payment testSend a small test amount from a controlled sending wallet to the name in your highest-priority wallet. Verify arrival at the correct destination. Record the transaction hash.
5. Run site tests, if applicableOpen the name in each in-scope browser, with and without the extension. Document what the browser returns: site loaded, error, or nothing.
6. Run negative testsTest an unregistered name, a misspelling, and (if the address has been changed since initial setup) a name after an address update. Document the behavior in each case.
7. Compile the evidence recordGather screenshots, transaction hashes, and written notes into a single document. Mark each test case pass or fail against the expected result.
8. Apply the go or no-go ruleCheck the rule below. Decide. If no-go, open a remediation item and retest before setting a new publication date.

Testing the site, if there is one

If the name is used as a site address, pointing to content on IPFS (the InterPlanetary File System, a distributed storage network often used for onchain sites) or on another decentralized host, the test set includes browser behavior.

Onchain names do not resolve in an ordinary browser without additional support, because the browser queries the DNS by default and the name is not in the DNS. In general, there are three ways a visitor can reach such a site: a browser that supports onchain resolution for the relevant registry by itself, a browser extension that sends the query to the onchain resolver, or a gateway address that resolves the name on a server and returns the content over a conventional web connection. For Freename names, the documented path is desktop browsers through the Freename Web3 extension. Which paths exist for your name is a question for the registry’s documentation, not an assumption.

Each path that applies needs its own test:

• Built-in browser support. If the registry documents a browser that supports the TLD without an extension, test in that browser without any extension installed. Confirm the content loads and that there is no security warning.
• Extension path. Install the extension documented for your TLD in a clean browser profile. Navigate to the name. Confirm the content loads and the browser shows no warning.
• Gateway path. If a gateway address is available, test it. The gateway address is not the same as the onchain name: a user who types the onchain name into a standard browser without support will not be redirected to the gateway automatically.
• Unsupported browser. Test in a browser that has no support installed. Record what happens. This is the experience your counterparty will have if they try the name without preparation.

The unsupported-browser result matters for what you tell customers. If the site is only accessible with the extension, say so. Do not imply the name opens like a standard website.

Negative tests: what must not happen

Positive tests confirm that your name resolves correctly. Negative tests confirm that the namespace around your name is safe: that similar names do not resolve unexpectedly, that your name does not return a stale address, and that resolution errors fail cleanly rather than silently.

Run four negative tests:

Misspelling. Enter a common misspelling of your name in each in-scope wallet, both a misspelling of the name and a misspelling of the TLD. The correct result is a clear error. On Freename, only the holder of a TLD can issue names under it, so a misspelled name under your own TLD should not exist unless you issued it. A misspelled TLD is a different matter: it is a separate TLD that someone else may hold. If a misspelling resolves to any address, investigate. A confusingly similar name is a brand protection issue that belongs with your IP team, not a launch issue you resolve by proceeding.

Unregistered sibling names. If you are issuing pay.yourbrand and invoice.yourbrand is unregistered, test invoice.yourbrand in a wallet. The correct result is an error. The wrong result is a resolution to any address. If it resolves to an address you did not register, the TLD’s record state needs investigation before launch.

Stale address. If the registered address was updated at any point during setup (for example, because the receiving wallet was changed), run a resolution test after the update and confirm the wallet returns the new address, not the prior one. Some resolvers cache results. If caching is a factor in your test environment, clear the cache between tests and document the cache behavior.

Name after TLD transfer. If the TLD itself changed hands and the post-transfer activation steps have been completed, confirm that every name issued before the transfer resolves to an address the new holder intends. A name that still points to an address chosen by the previous holder resolves without any error, which is why it needs a specific test pass and not a general one.

Recording results: what the evidence file must contain

A test that is not recorded did not happen, from the perspective of anyone reviewing the launch decision after the fact. Keep a single evidence file, not a collection of screenshots in a chat thread.

For each test case, the file contains:

• The test ID and description
• The surface tested (application name, version, and whether any extension was active)
• The date and time of the test
• The exact input used
• The result observed
• The expected result
• A pass or fail mark
• For resolution tests: the address returned by the resolver and the address in the registry record
• For the payment test: the transaction hash and a screenshot of the destination wallet balance before and after

For tests that fail, add a remediation note: what was found, what was changed, and the date of the retest. This creates an audit trail that is useful if the launch is challenged later, and it prevents regressions from being re-introduced during the remediation period.

Keep the evidence file version-controlled or timestamped. A result recorded after a problem is identified has less evidentiary value than one recorded at the time of the test. This matters more than it may seem when a payment failure prompts a retrospective review.

The go or no-go rule, and what to publish about support

The rule is simple because it has to be applied under time pressure, often by someone who did not write the test plan.

Go if: every positive resolution test in every in-scope surface passes, the live payment test arrives at the correct destination and is confirmed on the block explorer, every negative test returns the expected error or failure, and no unresolved brand protection issue was surfaced.

No-go if: any positive resolution test in any in-scope surface fails, the live payment arrives at the wrong address or does not arrive, or any negative test resolves to an address when it should have failed.

A partial pass (“it works in most wallets”) is a no-go for publication as a general payment address. It may be a conditional go if the name is being published only to a specific counterparty who has confirmed they will use one of the surfaces that passed. In that case, the scope of publication must match the scope that was tested. Do not publish a name to a general audience on the basis of testing that covered only one wallet.

What to do with a no-go: open a specific remediation item for each failure, assign it, set a retest date, and do not set a publication date until the retest passes. The activation roadmap tool on this site helps sequence these steps if the TLD was acquired by transfer and activation is still in progress.

What to tell counterparties about where the name works

When you announce the name, the announcement should include a short, specific statement of where the name works. “Send to pay.yourbrand in” followed by the wallet you confirmed is correct. “Send to pay.yourbrand from any wallet” is not, because it is not true for all wallets. The distinction matters because a counterparty who follows incorrect instructions and has a failed transaction will blame the name, not the wallet.

The statement of supported surfaces is not a marketing document. It is a technical specification for the recipient of your payment instructions. If you are uncertain whether a new wallet your counterparty mentions is supported, test it specifically before you tell them to use it.

For teams managing a TLD as a namespace with multiple names issued under it, this becomes a support documentation task, not a one-off note: one statement per name, each tied to the evidence file that supports it. For IP and brand protection teams reviewing the onchain exposure picture before or after launch, the namespace watch service monitors the names of a brand onchain.

Your next step

If your test plan is not yet written, start with the scope definition in the second section of this article. Write down the three to five surfaces that matter most to your specific counterparties. Then build the test case table with expected results before you run a single test. The discipline of stating expected results in advance is what separates a test from a demo: a demo finds things that work; a test finds things that do not.

If the TLD was acquired through a transfer and you have not yet worked through the full activation sequence, the activation roadmap tool builds the ordered task list from your current state. A record left as the previous holder configured it produces a failure that looks like a resolution problem and is not one. Fix the activation sequence first, then run the test plan.

If you are working with a legal or brand team that needs a brief on what onchain TLDs can do (what is confirmed live, what is partial, and what is not available), start that conversation from the sourced record of capabilities, not from the announcement you hope to make. Hush Partners assists teams that need a structured approach to activation after a transfer. The place to begin is the contact form.

Questions people ask

What happens if a counterparty tries to use the name before the test is complete?

They will encounter the same failure your test would have caught. If you have not published the name, the practical impact is limited. If you published the name before testing and a failure occurs, the counterparty’s experience of the failure is the same regardless of whether you knew about it. The cost of testing before publication is a day. The cost of a failed payment in a commercial context is larger and harder to quantify.

Is the block explorer confirmation sufficient evidence that the address is correct?

The block explorer confirms the transaction reached the address recorded on the relevant blockchain. It does not confirm that the address was the intended recipient. The check that matters is the comparison between the address the resolver returns and the address you registered. Those two should match before any payment is made. The block explorer confirms the payment was routed; the pre-payment check confirms it was routed to the right place.

If the name resolves correctly in testing, does that mean it will always resolve correctly in production?

Not permanently. Resolver support can change as wallets and extensions are updated. A name that has passed should be retested after any of the following: a change to the registered address, a wallet or extension update in a primary surface, a transfer of the TLD, or the addition of a new surface. Treat the test plan as something to run on a schedule, not a one-time event.

What if the TLD I am using is not yet supported in any wallet my counterparty uses?

That is a no-go for payment use with that counterparty. The honest answer is to tell them the name is not yet supported in their preferred wallet and give them a raw address in the meantime. Announce the name only when a surface they use supports it. Premature announcement does not accelerate adoption; it consumes the goodwill that a successful launch would have created.