The records an onchain name can carry

A name issued under an onchain TLD is, at the moment it is issued, an empty container. The label pay.yourbrand exists on the blockchain, but it does nothing until someone writes records into it. Records are the entries that tell every system consulting the name what to do: where to send a payment, what content to display, what descriptive information to return. Until those entries are written and verified, the name is inert.

This article explains each kind of record, how it compares to the DNS records most IT teams already know, and where the analogy with DNS breaks. It then addresses who should be allowed to change a record, why that question is more serious for some kinds of record than for others, and what disciplines a responsible operator puts around the whole record set.

After reading, you will be able to identify the records that need to exist behind any name your organization issues or holds, assign clear ownership of each, and put a change procedure in place that matches the stakes.

What a record is, and why the DNS analogy helps

In the conventional Domain Name System, a domain name is a pointer. It holds no content itself. What it holds is a set of resource records, each of which maps the name to something concrete: an IP address (an A or AAAA record), a mail server (an MX record), an alias to another name (a CNAME record), or free-form text (a TXT record). A nameserver returns the appropriate record when queried, and the software that asked, whether a browser, a mail client or a certificate authority, uses the value it receives to continue.

Onchain names work on the same underlying principle. Take Freename: the TLD is a token recorded onchain and held in a wallet, and names under it can be issued by the holder of that TLD and by no one else. Behind a name sits a set of key-value records kept by the registry’s smart contracts (a smart contract is a program stored on the blockchain that runs as written). When a wallet or a browser looks up the name, a resolver, the component that reads the stored values and returns them, hands back whatever the application needs. The name is still a pointer. The records are still the substance behind it.

The difference is in where the records live and who controls them. In the DNS, a record sits on a nameserver that the registrant designates, and changing a record means editing the zone on that nameserver or pointing the domain to another one. The change then spreads as caches expire, under a value called the TTL (time to live) that tells resolvers how long they may keep an answer. Propagation takes minutes to hours.

In an onchain system, a record update is a blockchain transaction. It takes effect when the transaction is confirmed, and how long that takes depends on the chain the registry uses. From that point the chain holds the new value, and a resolver that reads the chain returns it. Some applications keep their own short-lived copy of an answer, but there is no scheduled propagation period for you to wait through or to rely on.

That speed is an operational advantage. It is also, for certain kinds of record, a risk that your controls must address directly.

Where the analogy with DNS breaks

The analogy is a good way in, and it fails in four places that matter to the person responsible for the records.

First, control is a key, not an account. A DNS zone is edited by someone who logs in to a provider, and the provider can reset a password, restore access or roll back a zone after proof of identity. A record on an onchain name is changed by a transaction from the wallet that controls the name. Whoever holds the key can change the record, and nobody else can. Your access policy is therefore your key policy.

Second, everything is public. A DNS zone shows its current answers to anyone who queries it, but its history of changes stays with the provider. Onchain, every record change is a public transaction that remains readable. That helps an audit. It also means that a mistake, once written, stays visible in the history even after you correct it.

Third, a change costs a transaction. Editing a DNS record is free once the service is paid for. Writing a record onchain requires a network fee paid from the wallet that sends the transaction, so the controlling wallet needs to hold a small balance, and that balance needs an owner too.

Fourth, reach is partial. A DNS record is honored by practically every device on the internet. A record on an onchain name is read only by software that supports the name, because such names resolve outside the ICANN DNS root and an ordinary browser does not open them without that support. A correct record is necessary, and it is not sufficient: the person on the other side also needs a wallet or a browser that reads it.

The three families of record

Across registries, the records behind an onchain name fall into three broad families. Each family serves a distinct purpose, and each carries a different level of operational risk when changed.

Address records map the name to a wallet address on a blockchain. They are what make a name usable for receiving payments. A sender types or scans the name, the sender’s wallet asks the resolver, the resolver returns the address, and the transaction goes to that address.

Content records map the name to published material on a content-addressed network. The usual form is a hash pointing to content stored on IPFS, the InterPlanetary File System, a peer-to-peer storage network in which a file is addressed by a fingerprint of its content instead of by the location of a server. A browser or other client that supports the name uses this record to find and display a website. The page on websites published on an onchain TLD gives a fuller account of how this works in practice.

Text records are free-form key-value pairs that carry descriptive or machine-readable information: a display name, a description, a web address, a contact point, a reference to a profile elsewhere. They are the least sensitive of the three families in most cases, but they are not without risk, because a text record that asserts a link to an outside account or a credential is a statement that others may rely on.

Some registries also offer DNS-style records behind a name, so that it can point to conventional infrastructure. Which record types are available differs from one registry to another, so check the documentation of the registry your names sit on before you design around a particular type. The principles in this article apply whatever the exact list: a record that routes value is governed like an address record, and a record that routes visitors is governed like a content record.

Address records: where payments to the name go

Of all the records a name can carry, the address record is the one that most directly controls the movement of funds. When a counterparty sends value to pay.yourbrand, the recipient is whoever controls the wallet whose address is stored in that record. The name does not receive the payment. The address does. The name is the route to that address.

This is a real shift from bank payment instructions. A bank transfer passes through institutions that can, in some circumstances, stop or recall it, and the rules for that vary by country. An onchain payment to a resolved address cannot be recalled by anyone. If the record points to the wrong address, whether through an error or through a change nobody approved, the funds go where the record says, and getting them back depends entirely on whoever controls the receiving wallet.

One name, several networks

An address is always an address on a particular blockchain. Many name systems let a name carry one address record per network, so that the same name can receive value on more than one chain. For the person responsible, this multiplies the work in a specific way: each address record is a separate payment instruction, with its own wallet, its own key custody and its own entry in your inventory.

Two practical rules follow. Set an address record only for a network on which your organization has actually decided to receive funds, with a wallet that finance already monitors. And treat an empty record as safer than a guessed one: a sender whose wallet finds no address for a network gets an error, while a sender whose wallet finds a wrong address loses the payment.

Support on the sender’s side also varies. Freename names are supported in Bitcoin.com Wallet and in MetaMask through Freename’s resolver, and coverage is partial and changes over time. Before you publish a name as a way to pay you, test it from the wallets your counterparties are likely to use. The page on names that resolve in wallets follows which wallets read a name.

Why a change is a payment-control matter

In a finance function, changing the bank account on which a supplier is paid is a controlled event, because a false change request is a classic way for money to go astray. The address record is the same object in another form. It is the standing instruction that says where money sent to the name arrives.

Because the change takes effect as soon as the transaction is confirmed, the window for detection and intervention afterward is narrow. The protection must come before the change, not after it.

Two wallets are involved, and they are often confused. The wallet that receives funds is the one named in the address record. The wallet that controls the name is the one allowed to change that record. Both deserve the custody you apply to other treasury credentials, and the second one is the one this article is mostly about.

A multisignature wallet, one that requires several keys to approve a transaction, helps on both sides. As the receiving wallet, it protects the funds once they have arrived. As the controlling wallet, it means that no single person can change a record alone, which turns your two-approver rule from a policy on paper into a technical fact. It does not protect a payment sent after a record was wrongly changed, because that payment never reaches your wallet.

If you route incoming payments through a payment link that pays out to a name, the same reasoning applies one step earlier: the link relies on the record, so the record is still the control point. The page on payments to a name describes that use.

Content records: what a browser opens

A content record stores a hash, a fixed-length fingerprint that identifies one specific version of content stored on IPFS or a comparable network. When a browser or application that supports the name looks it up, it receives this hash, fetches the corresponding content from the network and renders it.

Content-addressed storage has an important property: the hash is derived from the content itself, not from where the content is stored. If the content changes, the hash changes. Updating a website published under an onchain name therefore takes two operations. The new content is published to IPFS, which produces a new hash. Then the content record on the name is updated to that hash, and that update is itself an onchain transaction.

This is where most publishing errors occur. Content uploaded to IPFS without the matching record update is never reached by anyone who looks up the name. A record updated to content that was not pinned, meaning kept in persistent storage by a node that agrees to serve it, eventually stops loading. Both operations must succeed, and someone must be responsible for confirming that both did.

It also changes what a web release is. In a conventional setup, updating a website means uploading files to a server, and the DNS records do not move. With an onchain name pointing to IPFS, every release changes a record. The content record is therefore the most frequently changed record you will manage, and a proportionate form of the change procedure below belongs in your release process.

Tools reduce the manual work without removing the responsibility. Freename’s website builder lets a holder build pages and publish them to IPFS, after which the site is reached through the holder’s onchain name in browsers that support it. Whatever tool performs the publication, the question for you is the same: who is allowed to trigger a release, and where is it recorded.

On the reader’s side, an ordinary browser does not open an onchain name without support. Freename names open in desktop browsers through the Freename Web3 extension, and coverage is partial and changes. State that honestly in any internal plan, and do not make an onchain name the only route to material that people must be able to reach. The page on what is live lists what works, with sources.

Text records: descriptive information

Text records are the most flexible and the least formally specified of the three families. Each one pairs a key, such as url or description, with a value the holder supplies. Applications that look up the name can read these values and use them to present information about it.

For most keys, the operational risk is low. An incorrect description is an embarrassment, not a financial exposure. Some text records carry more weight. A record that asserts control over an outside account, or that an application reads as a credential, is a claim that others may act on. Setting it incorrectly, or allowing it to be set without review, can create a false impression of affiliation or authorization.

Legal teams should pay particular attention to text records that mention trademarks, domain names in the conventional DNS or other identifiers. A record stating that the name is affiliated with an organization it has no relationship with is not merely a configuration error. It is a public statement, and correcting it later does not remove the earlier version from the history of the chain.

Two habits keep text records under control. Write in them only what you would be comfortable publishing on your own website, since the audience is the same. And keep personal data out of them: a named employee’s details written to a public ledger cannot be withdrawn when that person leaves, and data protection rules, which vary by country, may apply. Your own counsel decides what is appropriate.

Who can change a record, and how fast a change takes effect

The controller and the owner

On many onchain name systems, the right to set or change records on a name belongs to an address registered as the name’s controller. The controller may be the same wallet as the owner, or a separate address to which the owner has delegated management. The distinction matters operationally: a delegation is a grant of authority over records, and it lasts until it is withdrawn.

The answer is to design the permission structure deliberately. An organization that issues names under its own TLD should have a clear policy for which roles can set records on which names, and those roles should map to wallets whose keys are held under appropriate controls. Whether the registry you use allows a separate controller, and what exactly that controller may do, is a point to verify in its documentation and not to assume. The glossary defines the terms used here.

Keep the two levels apart. The TLD is held in the holder’s wallet, and on Freename that holder alone manages it: management of a TLD is not delegated to another address. A name issued under it has its own record set, controlled by whoever holds or manages that name, who may be an employee, a partner or a customer. A change to the records on pay.yourbrand affects only that name. Your policy should say, for each name, which level of your organization answers for its records.

No propagation delay to hide behind

DNS caching creates a natural buffer. An administrator who pushes a wrong record has a period, sometimes hours, in which many resolvers still return the old value and the error can be caught before it has its full effect. The same delay is a nuisance when you need a change to apply quickly.

Onchain record changes have no equivalent buffer. Once a transaction is confirmed, the new value is the authoritative value.

This cuts both ways. Fast effect is useful when you need to replace an address whose key may have been exposed, or to withdraw published content. It is a liability when changes are made without adequate review. The response is to compensate for the missing buffer by enforcing the review before the transaction, not by counting on time after it.

A change procedure for address records

The following procedure applies to address records, where the stakes are highest. Content and text record changes may follow a lighter process with the same skeleton: documented request, authorized approval, logged execution.

1. Document the requested changeState the name, the network, the current address, the proposed new address, the reason for the change and the person requesting it. Store this in your change management system, not only in a chat thread.
2. Verify the destination address independentlyThe approver confirms the new wallet address through a channel separate from the one used to submit the request, and compares it in full, not only its first and last characters.
3. Obtain a second approvalA second named individual with authority over payment controls approves the change in writing. This mirrors the rule most organizations apply to a change of bank account.
4. Respect the review windowUnless the change is an emergency, allow the period set in your records policy before the transaction is sent. Fix that period as a standing rule, not case by case.
5. Send the transaction and record the confirmationOnce the transaction is confirmed, record its hash and block number in the change log next to the request and the approvals.
6. Verify the resolved valueLook up the name in a wallet that supports it and confirm that it returns the expected address. Then send a small test payment before telling counterparties the name is ready.

An emergency path should exist and should be written down in advance. If the key of a receiving wallet may have been exposed, waiting out a review window is the wrong choice. Decide beforehand who may shorten the window, require the second approval even then, and have the change reviewed afterward as an incident.

Keeping a log of records and changes

The blockchain keeps a permanent record of every transaction that changed a record. Anyone can inspect this history on a block explorer, a public tool for reading blockchain data. That transparency is valuable for an audit, but it is not a substitute for an internal change log.

The chain tells you what changed and when. It does not tell you who in your organization authorized the change, what the business reason was, or whether the change was intended. An internal log fills that gap. For every record change it should capture the name, the record type, the old value, the new value, the date and time of confirmation, the transaction hash, the person who requested the change and the person or persons who approved it.

This log has three uses. It supports incident response: if a payment goes to the wrong address, the log shows whether the record was changed, when, and on whose authority. It supports compliance: organizations that operate under financial controls or audit requirements need to show that changes to payment infrastructure followed policy. And it supports periodic review, which needs a statement of what the record set is supposed to be.

The log is also your means of detecting a change nobody approved. Compare the public history with the log at regular intervals. A transaction on the chain with no matching entry in the log is, by definition, a change made outside your procedure, and it deserves the same attention as an unexplained movement on a bank statement.

Organizations that issue names to third parties, such as operators who run a sector TLD as a namespace or brands that give names to partners, should also keep a register of which names were issued to whom and when, separate from the record-level log. These are two layers of the same question: who controls what, and since when.

Reviewing the record set periodically

Records are not set once and forgotten. A name that worked correctly on the day it was activated may carry stale or incorrect records months later. Wallets are replaced. Websites move. A text record that referred to a role or a profile becomes inaccurate when the person leaves or the profile closes. An address record that was correct when first set may point to a wallet whose key custody has weakened since.

A periodic review of all records behind all active names is a basic operational discipline. The frequency depends on the nature of the names and the volume of changes. For an organization with a small number of names in active use, a quarterly review is a reasonable baseline, with an extra review after any reorganization of finance or IT.

The review checks four things:

• Every address record points to a wallet that is still in use, whose keys are held under current controls and whose incoming funds are monitored.
• Every content record points to content that is still pinned, up to date and approved for publication.
• Every text record is accurate, with particular attention to claims of affiliation and to anything that mentions a trademark.
• The list of names under review is itself complete, with no name issued or transferred since the last review that escaped it.

A transfer deserves a specific check. Records may persist through a transfer unless they are explicitly changed, so the new holder of a name can inherit records set by the previous one, including an address record pointing to a wallet the new holder does not control. Assume nothing: after any transfer, read every record and reset each one before the name is used.

Assign the review to a named role instead of to a team in general. A name administrator with a standing mandate to review records, and with the access to do so, will catch drift before it becomes a problem.

Start with an inventory of your names and records

The next step is concrete and takes little time. List every name your organization holds or has issued. For each one, write down the records it carries, the wallet that controls it, the people who hold the keys of that wallet, and the person who answers for each record. Where a cell is empty, you have found the work to do.

Then write a one-page records policy from that inventory: the approvers for each family of record, the review window for address records, the emergency path, the location of the log and the date of the next review. None of this is specific to onchain names. These are the disciplines IT and finance teams already apply to payment accounts, DNS zones and published websites. What changes onchain is that a wrong record takes effect on confirmation and a payment sent on the strength of it cannot be recalled, which is why the controls have to exist before the first record is written.

For an organization that has acquired a TLD and is deciding what its names should carry, Hush Partners offers post-transfer activation, which covers putting a TLD to work after the transfer, records included. The desk is reached through the contact form.

Questions people ask

Does the owner of a name always control its records?

Usually by default, though many registries let the owner delegate record management to a separate controller address. This is common where a TLD holder issues names to internal teams or partners and wants them to manage their own records. A delegation is an onchain transaction in its own right, and it should be logged and reviewed under the same disciplines as a record change.

Can a TLD holder change the records on names issued under the TLD?

It depends on the registry and on how the name was issued, so do not assume either answer. Read the registry’s terms and test on a name of no importance before you build a process on the assumption. If you operate a TLD and issue names to others, state in your own terms who controls the records of an issued name, so that the holder of the name and your own team expect the same thing.

Are text records evidence of a claim?

This is a question for your own counsel, and the answer depends on the jurisdiction and the context. What can be said in general is that a text record is public and that the transaction which set it remains visible on a block explorer. A record asserting an affiliation or a right is therefore a visible statement made at an identifiable moment, which can support a legitimate claim and can equally document a false one.

Should records be set on the TLD itself or on a name under it?

Where a registry allows records on the TLD itself, the usual practice is still to give each function its own name, such as pay.yourbrand for payments. Separate names let you assign separate controllers and separate approvers, and a mistake on one name leaves the others untouched.