A website on an onchain TLD: how publishing to IPFS works

Your organization holds an onchain TLD, say .yourbrand, and someone on the digital team has asked whether you should put a website on it. The question sounds simple. It is not, because a site published to IPFS and pointed at an onchain name works differently from anything your infrastructure team runs for the main website. The audiences who can reach it, the guarantees it offers and the team that should own it are all different.

This article explains the mechanism from first principles: how a conventional site reaches a visitor, what changes when you publish to IPFS, how an onchain name points at that content, and who can actually open the result. It then works through the uses that justify the effort, the ones that do not, and what a realistic first version looks like. By the end you will have enough to brief the right people inside your organization and make a considered decision.

None of what follows is legal or technical advice. Your own counsel and your infrastructure team decide how it applies to your situation.

How a conventional website reaches a visitor

When someone types the address of your main website, three things happen in quick succession. Their browser asks the Domain Name System (DNS), the global directory of names coordinated by ICANN, to translate that name into a numbered IP address that identifies a server. The browser then connects to that server and requests a file. The server sends the file back, and the browser renders it.

The content lives at a location. Change that location (move the server, switch providers, let the domain lapse) and the address breaks unless someone updates the directory. The visitor also has no direct way to know whether the file they received is the one you published, beyond trusting the server and the connection to it. Location is everything, and trust in that location is implicit.

This model works well for the vast majority of the web. It is optimized for speed, global reach, and the enormous tooling ecosystem that surrounds the DNS. For most of what your organization needs from a website, it remains the right choice.

What IPFS changes: content found by what it is

IPFS, the InterPlanetary File System, is a peer-to-peer protocol that inverts the address model. Instead of asking a specific server for a file by its location, you ask the network for a file by its content identifier (CID), a cryptographic hash of the content itself. A hash is a short fingerprint computed from the data: the same data always gives the same fingerprint, and different data gives a different one. Any node holding that content can serve it.

When you add a site to IPFS, its files are broken into smaller pieces, each piece is hashed, and the pieces are linked together under one identifier for the whole site. That single CID is what you hand to anyone, or anything, that needs to retrieve the site.

The practical consequence is tamper-evidence. Because the CID is derived from the content, the software that retrieves it can hash what it received and check that it matches. If even one character were altered, the hash would differ and the mismatch would show. For an organization that needs to make a verifiable public statement, such as a directory of its names or a record of its onchain presence, this property is meaningful. The content cannot silently change between publication and retrieval.

One constraint follows directly from the same mechanism. If the content changes, its CID changes too. A new version of the site is a new CID, and the pointer stored in the onchain record must be updated each time you publish a revision. This is not a flaw. It is the correct behavior of content addressing, and it shapes how you plan maintenance, which is covered further down.

Availability depends on pinning

Publishing a file to IPFS does not guarantee it stays there. IPFS nodes cache the content they fetch and serve it to other peers, but caches are finite, and nodes periodically clear cached content to make room (a process called garbage collection). Pinning marks a piece of content as exempt from that clearing on a particular node. Pinned content stays on that node for as long as the pin and the node last, however rarely it is requested.

Without a pin somewhere, content can become unreachable as the nodes that happened to cache it clear it over time. The CID still describes the content exactly. There is simply no one left to serve it.

In practice, the organization publishing the site is responsible for keeping it pinned. You either run your own IPFS node and pin to it, or you use a pinning service, a provider that runs nodes and keeps your content available, usually for a recurring fee. Most organizations without IPFS infrastructure will use a service or a builder that publishes for them. For a holder who would sooner not run nodes, Freename has a website builder in which pages are built and then published to IPFS. If you use it, ask how the published content is kept available and under which account, and write the answer down. Either way, someone in your organization needs to own that arrangement as a recurring operational responsibility, not a one-time step.

Pointing an onchain name at published content

Your .yourbrand, like every TLD on the Freename registry, exists onchain as a token that a wallet holds. Only the holder of .yourbrand can issue names under it, for example home.yourbrand or site.yourbrand. A name carries records, small labeled entries that say what the name points to. One kind of record points to a wallet address. Another points to content on IPFS, by its CID. The glossary defines these terms as they are used on this site.

When a browser or application that supports the registry resolves home.yourbrand, it reads the record, finds the CID stored there, and fetches the content from the IPFS network. The name is a human-readable pointer to verifiable content. The site is not tied to one server you rent, and the registry record is public: anyone can check it on a block explorer.

It helps to see the three layers separately, because each fails in its own way. The content layer is the set of files on IPFS, kept alive by pinning. The pointer layer is the record on the name, changed only by the wallet that controls the name. The resolution layer is the software on the visitor’s side that knows how to read the pointer. A site is reachable only when all three are in place. Most of the practical questions in the rest of this article come down to which layer is involved and who inside your organization answers for it.

Because updating the site produces a new CID, publishing a revision takes two operations: add the new content to IPFS and pin it, then update the record on the name to point to the new CID. A builder can carry you through both in one flow. Done by hand, they are two distinct operations, and the second requires the wallet that controls the name.

Who can open the site, and how

This is the part of the question that most organizations underestimate. A link to home.yourbrand is resolved outside the ICANN DNS root, as every onchain name is, which is why an ordinary browser will not open it without support. Access depends on one of three paths.

On a desktop, the Freename Web3 extension adds resolution of Freename names to the browsers it supports. In MetaMask, names resolve through Freename’s resolver. Freename names are also supported in Bitcoin.com Wallet. The page on websites published on an onchain TLD follows this capability and its sources.

Coverage is partial, and it changes as wallets and extensions add or update support. You cannot assume that a link to home.yourbrand sent to an arbitrary recipient will open in their browser. The table below makes the comparison explicit.

The honest reading of that table is that the conventional site wins on reach and simplicity for most purposes. The IPFS site on an onchain name wins on verifiability and on the direct tie between the content and the public record of the name. Both columns are worth understanding before you decide.

The reach gap also changes how you announce the site. A conventional address explains itself: people type it and it opens. An onchain name needs one sentence of instruction next to it, saying what to install or which wallet to use. The natural place for that sentence is a page on your main website, which every visitor can open. That page does two jobs. It tells people how to reach the onchain site, and it confirms from an address they already trust that the onchain name is yours. Plan it as part of the project, not as an afterthought.

Think, too, about who the realistic audience is. People who already use wallets and onchain services will open the site without friction, because the tooling is already on their device. A counterparty’s finance or compliance team may be willing to install an extension once in order to check an official record. A member of the general public who has never used a wallet will, in most cases, not do so for a single visit. If the people you most need to reach are in the third group, the conventional site is where the content belongs.

What such a site is good for

The limited reach is not an argument against having an onchain site. It is an argument for being precise about what you use it for. Three uses hold up well.

A verifiable official presence. The record for .yourbrand is public. Any party that wants to confirm which wallet holds the TLD can check the registry record on a block explorer. A site published to a name under that TLD extends the same logic to content: only the holder of the TLD can issue the name, and only the wallet that controls the name can set what it points to. For a third party carrying out due diligence on the organization’s onchain presence, pages reached through the organization’s own TLD carry a link to the holder that can be checked independently of any server. The reference page on what works on onchain TLDs sets this capability next to the others, with sources.

A statement or record that must not change silently. Consider a mid-sized manufacturer, an invented example, that has issued a public commitment and wants a record of it that cannot be quietly edited. Content addressed by a CID and pointed to by an onchain name cannot change without producing a new CID and a new onchain transaction to update the pointer. That transaction is recorded on the chain with its time. Anyone who kept the earlier CID can show what the earlier version said. The combination gives a public trail of changes that a conventional site does not provide by default. Whether that trail has any evidential weight in a given dispute is a question for counsel, and the answer varies by country.

A directory of the organization’s names. The holder is the only party who can issue names under .yourbrand. A site published under that TLD can list the names the organization has issued (pay.yourbrand for payments, id.yourbrand for credentials, and so on) along with their purposes. Anyone using a supporting extension or wallet can open the site and see the authoritative map of the namespace. This is a practical tool for counterparties, partners and internal teams who need to know which names are official. It is also the use that ages fastest, since every name issued or retired makes the directory out of date. The Launch Roadmap tool helps a holder plan this kind of structured rollout.

These uses share a common thread: they are served by the specific properties of an onchain site, not simply by having a site somewhere. If the purpose could be served equally well by a conventional page on your main domain, use the conventional page.

What an onchain site is not good for

An IPFS site on an onchain name is not a substitute for your main web presence. Search engines crawl the conventional web through the DNS. Their crawlers do not, as a rule, use the extensions or wallets needed to open onchain names. Visitors who do not already know your TLD will not find the site through search, and the site will not add to your organization’s search visibility.

Dynamic content (forms, authenticated sessions, database-driven pages, personalization) is not native to IPFS. IPFS stores and retrieves files by their content. You can publish a static site to it. You cannot run a backend on it. If the site you have in mind requires a server-side process, IPFS is the wrong layer.

E-commerce, lead generation, customer support and any application that requires real-time interaction all belong on conventional infrastructure. Payments to an onchain name are a separate capability: a name can point to a wallet address as well as to content, and the two records are set independently. The page on payments to a name explains that side. A site on the name and payments to the name do not conflict, but configuring one does nothing for the other.

Do not use an onchain site as the only home of content that must stay reachable for safety, compliance or regulatory reasons. The pinning arrangement is a commitment you must maintain, and resolution depends on software your visitors choose and you do not control. Publish such content on the conventional site first, and treat the onchain version as a second, checkable copy.

Finally, an onchain site is a poor place for anything you may need to withdraw. Publishing to IPFS is publishing to a public network. You can stop pinning a version and move the pointer, but you cannot recall copies that other nodes or readers have kept.

Keeping it up to date

Because a new version of the site produces a new CID, updating an IPFS site is a two-part operation: publish the new content to IPFS, then update the record on the name. Both parts require authorization: access to the publishing or pinning account for the first, and authority over the wallet that controls the name for the second.

Three practical points follow from this. First, you need a defined update process before you launch, not after. It names who can request an update, who approves the content, who approves the transaction, and how fast a correction can go out if something published is wrong. Put those answers in writing before the site goes live.

Second, the history is public. Each update of the pointer is a transaction that stays visible on the chain, with the CID it set. Earlier versions of the site remain retrievable by their CIDs for as long as any node keeps them, whether that node is yours or someone else’s. This helps with audit and matters for content governance: treat everything you publish as part of a lasting record. Organizations with strict document retention or litigation hold policies should factor this into the decision about what to publish.

Third, decide what triggers an update. A site that carries a directory of names is only useful if it matches the names actually issued. The simplest rule is to make the directory part of the procedure for issuing a name: no name is issued or retired without the matching change to the site being prepared, approved and published in the same piece of work. A scheduled review, at whatever interval suits your other public records, catches whatever slipped through.

Recovery from a lapse is possible as long as you kept the files. Publishing exactly the same content again yields the same CID, so the existing record works once the content is pinned. Otherwise you publish a new version and update the record. Keep the source files of every published version in your ordinary document systems for that reason. IPFS is where the site is served from, not where it is archived.

Who should own this inside the organization

A conventional website sits inside a clear ownership structure: a marketing or digital team owns the content, an infrastructure team owns the hosting, and whoever manages domains owns the DNS records. A site on an onchain TLD does not map cleanly to that structure.

The record on the name is controlled by a wallet. In many organizations that wallet sits with a treasury, legal or IT security function, not with a digital team. Content decisions and record updates therefore require cooperation between whoever controls the wallet and whoever controls the content. If those two functions operate independently, you will have delays every time the site needs updating.

A workable model treats the onchain TLD as an asset managed by the same function that manages the organization’s other digital assets, whichever function that is in your structure. A multisignature wallet, one that needs approval from several designated people before it acts, is a common way to avoid depending on a single person. The page on names that resolve in wallets covers the wallet side of a TLD. Content for the site can be drafted and approved by a digital or communications team, but the deployment step, updating the record, requires the wallet owner’s involvement.

That split is a strength if you design for it. The communications team cannot publish without a second function approving the transaction, and the function holding the wallet cannot change the public content without a new CID that the communications team would notice. Each side checks the other. The cost is turnaround time, so agree in advance how quickly the wallet function commits to act on an approved update, and who stands in when the usual approvers are away.

One more role is easy to forget: the person who answers when someone outside asks whether the onchain site is genuine. That is usually the same contact who answers for the main website, and they need to know the site exists, which name it sits on and where the confirming page on the main website is.

Document the wallet custody arrangement and the update authority explicitly. When an onchain site needs a correction quickly, missing documentation is an avoidable source of delay.

A realistic first version, from pages to a published site

A first version of an onchain site does not need to be elaborate. Three to five static pages are enough.

What to put in version one

A sensible starting scope is a homepage that identifies the organization and the purpose of the TLD, a directory listing each active name under .yourbrand with its function, and a page pointing to the organization’s conventional website for inquiries. Nothing on those pages requires dynamic content or a backend. The whole site can be written, reviewed by legal, published to IPFS and pointed at a name as one small project.

The value of starting small is not economy. It is that you learn the update cycle (how long wallet approval takes, how the publishing and pinning arrangement behaves, how long a record update takes to show) before you depend on that cycle for anything time-sensitive. The first version is as much a rehearsal of the operational process as it is a published artifact.

From there, the site can grow: a page for each official name, the statements the organization wants on the record, or a section on identities for AI agents if the organization issues them under the TLD. Each addition is a new CID and a new record update, which is why version one should be something you are confident will not need immediate revision.

The procedure

The procedure below describes a path from blank page to a name that resolves to content. A team using a builder and a technical team working directly with IPFS follow the same logical sequence with different tooling.

1. Agree on scope and contentDecide what the site will contain, such as a statement of the organization's onchain presence and a directory of its names, and get internal sign-off before touching any tooling. Keep version one small.
2. Build the pagesUse a website builder that publishes to IPFS, such as Freename's, or prepare static files in a local environment. The output must be a static site: no server-side processing, no database calls.
3. Publish to IPFS and record the CIDPublish the site through the builder or a pinning service. The result is a CID that identifies this exact version of the content. Record it with the source files.
4. Confirm the content is pinnedCheck that the content is kept by at least one always-on node under an account your organization controls, and that the CID can be retrieved. Record who owns the account and when it renews.
5. Update the record on the nameIn the registry's management tools, set the content record of the name under your TLD, for example home.yourbrand, to the CID from step three. Approve the transaction with the wallet that controls the name and wait for confirmation.
6. Verify resolutionOpen the name in a browser with the Freename Web3 extension or in a supporting wallet. Confirm the correct content loads. Have a second person on a different device repeat the check.
7. Document the update processWrite down who has authority over the wallet, how content updates are approved, and who owns the publishing and pinning accounts. File this with your other infrastructure documentation.

Where the website sits among your other decisions

Before anything is built, write a one-page brief and take it to the function that holds the wallet. It states the purpose of the site in one sentence, the audience and how that audience will open it, the pages in version one, the owner of the content, the owner of the wallet approval, and the owner of the pinning arrangement. If any of those six lines is hard to fill in, that is the decision to settle first.

The website is one of several things a TLD can do, and it is easier to configure well when it is planned with the others: the names you will issue, where payments to those names should go, which records each name carries. The Launch Roadmap tool mentioned above orders those decisions. Where the TLD has just changed hands, Hush Partners’ post-transfer activation service covers putting it to work after the transfer, the website included.

If your organization does not hold the onchain TLD that matches its name and wants to explore acquiring it, that is a separate conversation. Hush Partners is a private desk for onchain TLDs. It acts for organizations that mandate it to find and approach a holder, and for holders who mandate it to find a buyer. Every exchange is covered by a standard mutual NDA, and the desk is reached through the contact form on the site. The page for general counsel and brand protection teams is the place to start.

Questions people ask

Does publishing a site to IPFS mean anyone on the internet can see the content?

Yes, in the sense that matters. The content can be retrieved by anyone who knows the CID and can connect to the IPFS network. IPFS is not a private network, so treat it as a public medium. Do not publish anything to IPFS that you would not publish on a conventional public website. The onchain name makes the content easier to find for someone who knows the name. It does not restrict access to people who use that name.

Can ordinary browsers reach the content through a gateway?

Yes. An IPFS gateway is a conventional web server that fetches IPFS content by its CID and serves it at an ordinary web address, so any browser can open it without an extension. The trade-off is that the visitor is back to trusting a server: the gateway address does not pass through the onchain name, and the browser does not check the hash itself. A gateway link is useful for showing the content widely. Resolution through the name is the right entry point for audiences who need to check that the content is what the name points to.

What happens to the site if resolver support or the registry’s terms change?

The transaction that set the pointer stays on the chain, and the content, if pinned, remains retrievable by its CID. What can change is whether the name resolves for a given visitor. That depends on resolver support in wallets and browsers and on the integrations the registry maintains. It is a dependency to record in the governance discussion alongside your other infrastructure dependencies, and one more reason not to make the onchain site the only home of anything essential.

Who is responsible for what is published under a name on the organization’s TLD?

Only the holder can issue names under the TLD, so every name under .yourbrand starts with a decision by the organization. For names it keeps, the organization answers for the content they point to in the same way it answers for its main website. If it issues names to others, such as partners or members, the terms on which it does so should say who answers for the content, and how liability falls varies by country. A different question is a name resembling your brand that appears elsewhere onchain, under a TLD you do not hold. Monitoring of that kind is what the namespace watch service covers. In every case, your counsel decides what action is appropriate on the specific facts.