Atom Registry Documentation

Atom Registry is a multi-TLD Web3 DNS and on-chain content platform built on Cosmos Hub. It lets anyone register permanent domain names across dozens of top-level domains, deploy full HTML websites directly to the blockchain, build on-chain profiles and credentials, and deploy CosmWasm smart contracts — all from a browser, all signed with Keplr, all without a single centralized server involved in ownership or resolution.

Everything registered through Atom Registry lives in CosmWasm smart contracts on Cosmos Hub (cosmoshub-4). There are no renewal fees, no registrar accounts, and no company that can revoke your name. Your wallet owns it. The chain holds it. Forever.

Architecture

Atom Registry is built on eight CosmWasm contracts deployed to Cosmos Hub mainnet, plus a suite of browser-based tools that interact with them directly. No backend servers are involved in any transaction — all signing happens in your browser via Keplr and all state lives on the chain.

The Registry is the source of truth for domain ownership — it mints, transfers, and tracks all names and TLDs. The Registrar handles commit-reveal registration for domain names with tiered pricing by name length. The TLD Manager handles commit-reveal registration for TLDs with its own pricing tiers. The Resolver maps names to DNS records, cross-chain addresses, IPFS hashes, and federation handles. The Marketplace enables fixed-price listings, offers, and time-based auctions with built-in royalty support. The Metadata contract stores on-chain profiles — avatar, bio, social handles, custom fields — keyed by domain. The dSSL Manager is the trust and reputation layer — domains publish a cosmos.toml manifest, earn attestations, and resolve to a trust level visible in the browser extension. The Site Registry stores full HTML pages on-chain with version history.

All browser tools — the main site, on-chain sites manager, search, page builder, contract launcher, and document pipeline — use ProtoWriter, a hand-rolled protobuf encoder that constructs and signs transactions entirely in the browser without CosmJS or any external signing library. This eliminates the W.getPolyfill is not a function SES lockdown conflict that CosmJS triggers inside the Keplr extension environment.

Key Concepts

TLD vs Domain

A TLD (Top-Level Domain) is the namespace itself — .atom, .cosmos, .dev. TLD owners control the pricing and registration policy for all names registered under their namespace. Anyone can register a TLD for 2.5 ATOM at launch pricing.

A domain name (or subdomain) is a specific name registered under a TLD — satoshi.atom, myproject.cosmos. The registration fee goes directly to the TLD owner. The registrant owns the name permanently.

On-Chain Sites

On-chain sites are complete HTML pages stored as text in the Site Registry contract. When the browser extension resolves a name, it fetches the HTML directly from the contract and renders it in an iframe. The content lives entirely on Cosmos Hub — no IPFS, no Arweave, no hosting provider.

Because sites render inside an extension iframe with a strict Content Security Policy, JavaScript is blocked. On-chain sites must use CSS animations, SVG SMIL, and inline styles only.

Permanent Ownership

Names and TLDs registered on Atom Registry have no expiry date and no renewal fee. Once registered, they belong to the wallet that registered them until explicitly transferred. The chain enforces ownership — not Atom Registry.

ProtoWriter Signing

All transactions across every Atom Registry tool are signed using ProtoWriter — a minimal protobuf encoder built directly into each page. It constructs the transaction binary, passes it to Keplr for signing via signDirect, and broadcasts to multiple LCD endpoints with automatic fallback. No npm, no CosmJS, no external dependencies.

Quick Start

Get from zero to a registered on-chain name in under five minutes.

1. 1
   Install KeplrDownload the Keplr browser extension and create or import a wallet. Fund it with at least 5 ATOM to cover a TLD registration plus gas.
2. 2
   Go to atomregistry.comClick Connect Keplr in the top right. Approve the connection in the Keplr popup. Your balance and address will appear.
3. 3
   Pick a TLDScroll to the TLD browser. Click any available TLD to see its registration price. Click Register TLD and approve the 2.5 ATOM transaction in Keplr.
4. 4
   Register a nameWith your TLD registered, type a name in the search box, select your TLD, and click Register. Gas only — no additional fee since you own the TLD.
5. 5
   Deploy a site (optional)Go to On-Chain Sites, enter your registered name, paste or upload HTML, and click Deploy. Your site is now permanently on Cosmos Hub.

Core Platform

The main Atom Registry interface at atomregistry.com is your dashboard for registering names, managing TLDs, viewing your portfolio, and controlling TLD policies. Everything on this page transacts directly on Cosmos Hub with no intermediary.

Connecting Keplr

Atom Registry requires the Keplr wallet extension on desktop Chrome or Edge. Mobile browsers are not supported — Keplr mobile users can access the site through the Keplr in-app browser.

1. 1
   Click Connect Keplr in the top navigation bar.
2. 2
   Approve in Keplr — Keplr will ask permission to connect to cosmoshub-4. Click Approve.
3. 3
   Connected state — Your truncated address and ATOM balance appear. The page auto-reconnects on reload if Keplr has already approved the connection.

Registering a Domain Name

Domain names on Atom Registry are registered under an existing TLD. The registration fee is set by the TLD owner and paid directly to them — Atom Registry takes no cut.

1. 1
   Select a TLD from the TLD browser. Click it to expand its details — registration price, owner, and availability.
2. 2
   Search for your name in the Name Search box. Type the label (the part before the dot) and click Check. The contract is queried in real-time.
3. 3
   Register — If available, click the Register button. A Keplr popup appears showing the transaction details including the TLD fee in uatom. Approve to broadcast.
4. 4
   Confirmation — A TX hash appears with a Mintscan link. The name appears in your Portfolio tab immediately after confirmation.

Registering a TLD

Owning a TLD means owning an entire namespace on Cosmos Hub. You set the price, you set the policy, and you receive every registration fee paid by anyone who registers a name under your TLD. TLD ownership is permanent and transferable.

Parameter	Value	Notes
Launch price	2.5 ATOM	Subject to increase when v2 launches
Minimum label length	1 character	Single-letter TLDs are available
Allowed characters	a-z, 0-9, hyphens	No uppercase, no special characters
Ownership	Permanent	No renewal, no expiry
Revenue	100% to TLD owner	Paid at registration time to your wallet

1. 1
   Go to the Own a TLD tab on the main page.
2. 2
   Enter your desired TLD label — just the word, no dot. e.g. coffee for .coffee
3. 3
   Check availability — the contract is queried. If taken, the current owner is shown.
4. 4
   Click Register TLD — Keplr shows a 2.5 ATOM + gas transaction. Approve to register.

Portfolio Management

The Portfolio tab shows all names and TLDs owned by your connected wallet. Click any name to expand its management panel where you can set DNS records, transfer ownership, or link it to an on-chain site.

The My TLDs view shows your owned TLDs with current registration counts and policy status. Click a TLD to access its settings.

TLD Settings & Policy

TLD owners have complete control over their namespace. Policy changes execute SetSubdomainPolicy on the Registry contract and take effect immediately.

Setting	Description
Registration Price	Price in uatom for anyone to register a name under this TLD. Set to 0 for free registrations. 1 ATOM = 1,000,000 uatom.
Open / Closed	Open allows anyone to register. Closed restricts registration to the TLD owner only — useful for branded or private namespaces.
Transfer Policy	Whether registered names under this TLD can be transferred between wallets.

On-Chain Sites

On-Chain Sites lets you deploy complete HTML pages directly to the Cosmos Hub blockchain. The HTML is stored in the Site Registry contract, versioned, and served to anyone who resolves your domain through the Atom Registry browser extension. No hosting, no CDN, no DNS — just the chain.

What Is an On-Chain Site

An on-chain site is a string of HTML stored in the site_registry contract under a name you own. When the browser extension resolves yourname.yourtld, it queries the contract, retrieves the HTML, and renders it in a sandboxed iframe. The content is immutably recorded on Cosmos Hub with a full version history — every update creates a new version entry that can be retrieved by version number.

Deploying a Site

1. 1
   Connect Keplr on the On-Chain Sites page (/onchain.html). Your registered names are loaded automatically.
2. 2
   Enter your domain name — the full name including TLD, e.g. mysite.atom. Ownership is verified against the Registry contract.
3. 3
   Paste or upload HTML — use the editor or drag-and-drop a .html file. The KB counter shows your current size vs. the 100KB limit.
4. 4
   Preview — the live preview iframe shows exactly how your site will render in the extension.
5. 5
   Click Deploy — Keplr shows a 5 ATOM + gas transaction for first deployment (gas only for updates). Approve to store on-chain.

Updating & Version History

Every deployment creates a new version in the Site Registry. You can view and retrieve any previous version by querying site_versions then site_version with the version number. Updates cost gas only — the 5 ATOM storage fee is a one-time charge per name.

{"site_versions": {"name": "yourname.yourtld", "start_after": null, "limit": 20}}

{"site_version": {"name": "yourname.yourtld", "version": 1}}

CSP & the Zero-JS Rule

On-chain sites render inside the Atom Registry browser extension in a sandboxed iframe with a strict Content Security Policy. JavaScript is completely blocked. Any <script> tag — inline or external — will be silently ignored by the browser.

This is not a limitation to work around — it is a security guarantee that means on-chain sites can never execute malicious code, phone home, or track users. Build your on-chain sites with:

• CSS animations — @keyframes, transitions, transforms
• SVG SMIL animations — <animate>, <animateTransform>
• CSS variables and custom properties
• Pure HTML/CSS layouts — flexbox, grid, everything works
• Inline images — base64 encoded images in <img src="data:...">

On-Chain Page Builder

The On-Chain Page Builder (/profiles.html) lets you create a professional on-chain profile page without writing any HTML. Fill in fields, upload a photo, choose a color scheme, preview live, and deploy straight to your registered name — no code required.

Building a Profile Page

The builder has five sections that map directly to the generated HTML output:

Section	Fields	Notes
Identity	Name, title/tagline, domain	Name becomes the hero heading
Profile Image	Upload JPG/PNG/WebP	Auto-converted to WebP, quality slider
Links	Up to 6 links with labels and icons	Social, portfolio, GitHub, custom
Design	Color scheme, accent color	6 preset themes + custom
Extra Content	Section title + body text	About, skills, bio — freeform

The live preview iframe updates in real-time as you type. The generated HTML is fully self-contained — all styles inline, no external dependencies, no JavaScript, fully compliant with the on-chain site CSP rules.

Image Upload & WebP Conversion

Images uploaded to the builder are automatically converted to WebP format in the browser using the Canvas API before being embedded as base64 in the generated HTML. This is critical for keeping the page within the 100KB on-chain storage limit.

Quality	Approx Size (400x400px photo)	Visual Quality
Quality 40	~8.5 KB base64	Nearly identical to original
Quality 70	~11.8 KB base64	Excellent
Quality 85	~16 KB base64	Indistinguishable from original

Deploy to Chain

Once your profile looks right in the preview:

1. 1
   Save to computer (optional) — downloads the generated HTML file for your records.
2. 2
   Enter your domain name — the name you own on Atom Registry, e.g. sean.atom
3. 3
   Click Deploy to Chain — the page calls the Site Registry contract via ProtoWriter. Keplr shows the transaction. 5 ATOM first time, gas only for updates.

Web3 Search & Browser Extension

Atom Registry includes two ways to resolve and browse Web3 domains: the Search page (/search.html) for in-browser lookup, and the Chrome/Edge extension for native address-bar resolution.

Using the Search Page

The search page (/search.html) is a Google-style single-field interface for resolving any Atom Registry domain. Type a name and press Enter — or pass ?q=yourname.tld in the URL to resolve directly.

When a site is found, it renders in a full-viewport overlay with a mini address bar at the top. The overlay supports navigation within the on-chain site and includes a "New Tab" button to open the resolved content independently. Recent searches are stored in localStorage.

https://atomregistry.com/search.html?q=cosmos.onchain

Resolution Order

When you search for a name, the resolver queries contracts in this order, stopping at the first successful result:

1. 1
   Site Registry — checks if the name has on-chain HTML stored in the Site Registry contract. If yes, renders the HTML in the overlay viewer.
2. 2
   A Record — queries the Resolver contract for an IPv4/IPv6 address. If found, redirects to that IP.
3. 3
   CNAME — queries for a canonical name alias. If found, redirects to that target.
4. 4
   TXT Record — returns any stored text records for informational display.
5. 5
   Not Found — name is not registered or has no records. Shows a not-found state.

Chrome Extension

The Atom Registry Browser Extension brings Web3 DNS resolution natively into Chrome and Edge. Type any Atom Registry domain directly in the address bar — no separate app, no command line.

The ar Shortcut

The fastest way to resolve a domain is the ar keyword. Click the address bar, type ar followed by a space, then type any Web3 domain and press Enter:

ar cosmos.atom
ar myproject.dev
ar satoshi.btc

The extension resolves the name against Cosmos Hub and navigates you directly to the on-chain site.

Extension Popup

Clicking the Atom Registry icon in your Chrome toolbar opens the extension popup with:

• Keplr wallet connection — connect once and your portfolio is always visible
• Quick name search and availability check
• Your registered names and TLDs at a glance
• Direct links to manage names on atomregistry.com

Privacy

The extension queries Cosmos Hub directly via public LCD endpoints. No browsing data, search queries, or wallet information passes through Atom Registry servers during resolution.

Extension Installation

The extension is distributed as a ZIP file — no Chrome Web Store required.

1. 1
   Download atom-registry-extension.zip from atomregistry.com
2. 2
   Extract the ZIP to a folder on your computer. You should see a folder containing manifest.json and other extension files.
3. 3
   Open Chrome Extensions — navigate to chrome://extensions in your address bar.
4. 4
   Enable Developer Mode — toggle the switch in the top-right corner of the extensions page.
5. 5
   Load Unpacked — click the "Load unpacked" button and select the extracted folder (the one containing manifest.json).
6. 6
   Pin the extension — click the puzzle piece icon in the Chrome toolbar, find Atom Registry, and click the pin icon.
7. 7
   Test it — type ar cosmos.onchain in the address bar and press Enter.

Smart Contract Launcher

The Smart Contract Launcher (/contracts.html) lets you compile, store, and instantiate CosmWasm smart contracts on Cosmos Hub entirely from your browser. It handles the GitHub Actions compilation pipeline, WASM upload, gas estimation, and instantiation — returning both TX hashes and the deployed contract address.

Prerequisites

• Keplr wallet with enough ATOM for gas (~0.5–3 ATOM depending on contract size)
• GitHub account with a repository containing your Rust contract code
• GitHub Personal Access Token with repo and workflow scopes
• Build workflow file at .github/workflows/build.yml in your repo (template provided on the page)

GitHub Actions Workflow Setup

Add this file to your repository at .github/workflows/build.yml. This is a one-time setup. After it exists in your repo, you can compile any branch with one click from the Launcher page.

name: Build CosmWasm Contract

on:
  workflow_dispatch:
    inputs:
      contract_path:
        description: "Path to contract directory (leave blank for root)"
        required: false
        default: "."

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install Rust
        uses: dtolnay/rust-toolchain@stable
        with:
          targets: wasm32-unknown-unknown

      - name: Cache cargo
        uses: actions/cache@v4
        with:
          path: |
            ~/.cargo/registry
            ~/.cargo/git
            target
          key: ${{ runner.os }}-cargo-${{ hashFiles('**/Cargo.lock') }}

      - name: Build optimized WASM
        run: |
          cd ${{ github.event.inputs.contract_path }}
          docker run --rm -v "$(pwd)":/code \
            --mount type=volume,source="$(basename $(pwd))_cache",target=/target \
            --mount type=volume,source=registry_cache,target=/usr/local/cargo/registry \
            cosmwasm/optimizer:0.16.0

      - name: Upload artifact
        uses: actions/upload-artifact@v4
        with:
          name: contract-wasm
          path: ${{ github.event.inputs.contract_path }}/artifacts/*.wasm
          retention-days: 7

Compile via GitHub Actions

The compilation tab triggers a GitHub Actions workflow dispatch on your repo, polls until the build completes, then automatically downloads the compiled .wasm artifact into the browser — ready to store on-chain without any manual file handling.

1. 1
   Enter your GitHub repo URL — full URL, e.g. https://github.com/youruser/yourrepo
2. 2
   Enter your branch — defaults to main
3. 3
   Contract path — leave blank if Cargo.toml is in the repo root. For workspace repos enter the subdirectory, e.g. contracts/my-contract
4. 4
   Enter your GitHub PAT
5. 5
   Click Trigger Compilation — the workflow is dispatched. Status polls every 5 seconds showing queued → building → success/failed with elapsed time and a direct link to the GitHub Actions run.
6. 6
   Auto-download — on success the artifact ZIP is downloaded, the .wasm extracted, and the file loaded into the deploy step automatically.

Store & Instantiate

Once you have a compiled .wasm (either from GitHub or uploaded directly), the Launcher handles the two-step deployment process.

Step 1 — Store Code (MsgStoreCode)

Storing uploads the WASM bytecode to the chain and assigns a Code ID. This is separate from deployment — the same Code ID can be instantiated multiple times to create independent contract instances.

• Gas is simulated automatically before the Keplr signing prompt
• Gas adjustment factor: 1.8x of simulated gas
• Gas price: 0.025 uatom
• After confirmation, the Code ID is extracted from TX events automatically

Step 2 — Instantiate (MsgInstantiateContract)

Instantiation creates a running contract instance from a stored Code ID. You provide:

Field	Required	Notes
Contract Label	Yes	Human-readable name stored on-chain. Not unique.
Admin Address	No	Wallet that can migrate the contract. Leave blank for immutable contract.
Init Message	Yes	JSON matching your contract's InstantiateMsg schema
Funds	No	Initial ATOM to send with instantiation, e.g. 1000000uatom

After successful instantiation, the Launcher displays the contract address, both TX hashes with Mintscan links, and a ready-to-use gaiad query command.

Document → Contract Pipeline

The Document → Contract pipeline (/docmaker.html) takes any document — a resume, invoice, property deed, certificate, employment application — uploads it, uses Claude AI to extract every field, generates a complete production-ready CosmWasm Rust contract from those fields, compiles it via GitHub Actions, and deploys it to Cosmos Hub. The full document can optionally be embedded as base64 in the contract state, making the document itself permanently on-chain.

Concept

Traditional document storage — filing cabinets, cloud drives, IPFS — separates the document from its ownership record. Atom Registry closes that gap. When a document becomes a smart contract:

• Ownership is enforced by the chain — not a database
• The document content is immutable and verifiably timestamped
• Every field is individually queryable from any CosmWasm client
• Ownership transfer is a single on-chain transaction
• The full document (not a pointer to it) can be permanently stored in the contract state

AI Field Extraction

After uploading a document, Claude AI (claude-sonnet-4-20250514) reads the document image and extracts every meaningful field. For each field it returns a name, data type, sample value from the document, and whether the field is required.

Field Type	Rust Type	Example
String	String	Name, address, title, description
Uint128	Uint128	Invoice amount, salary, property value
bool	bool	Verified, active, paid
u64	u64	Dates as timestamps, counts, IDs
Addr	Addr	Wallet addresses, cosigners

The field editor lets you review, rename, change types, add custom fields, or remove irrelevant ones before contract generation. You have full control over what ends up in the on-chain state.

Full Document Embedding

The pipeline includes an option to store the complete document as a base64-encoded string field (document_data) in the contract state. This is the truly on-chain document — not a hash, not a pointer, the actual bytes.

Use Cases

Document Type	On-Chain Value
Resume / CV	Verifiable credential — employer can query skills, experience, education directly from the chain. Owner can grant/revoke verification.
Invoice	Payable smart contract — invoice amount, due date, and parties stored on-chain. Payment can trigger status update via Execute.
Property Deed	Tokenized real world asset — deed scan embedded, legal description queryable, chain of title tracked through Transfer messages.
Employment Application	Tamper-proof application record — submitted fields immutable, hiring status updatable only by contract owner.
Certificate / Credential	Issuer stores credential on-chain, marks verified. Recipient owns the contract. Anyone can verify by querying is_verified.
Medical Record	Patient owns the contract. Provider can append attestations. Full record embedded and encrypted if needed before upload.

Embeddable Widget SDK

The Atom Registry Widget SDK provides an embeddable TLD availability checker that any website can drop in. It queries the Cosmos Hub TLD Manager contract directly — no backend required — and returns live availability plus a registration link. Fully customizable via color, typography, and dimension parameters.

Embed Methods

Three embed methods are available. Use the Widget Builder at /widgets/ to generate the code visually with a live preview.

Method 1 — iFrame

The simplest method. Drop an iframe pointing to the hosted widget page with URL parameters for customization.

<iframe
  src="https://atomregistry.com/widget.html?bg=%230f0a19&border=%238b5cf6&title=Check+Availability"
  width="500"
  height="180"
  frameborder="0"
  style="border-radius:16px;">
</iframe>

Method 2 — Script Tag

Loads the widget SDK and injects it into a target element. More flexible — supports JavaScript callbacks.

<div id="atom-registry-widget"></div>
<script src="https://atomregistry.com/widget.js"></script>
<script>
  AtomRegistryWidget.init({
    container: "#atom-registry-widget",
    bgColor: "#0f0a19",
    borderColor: "#8b5cf6",
    title: "Check Availability",
    onCheck: function(tld, isAvailable, responseTime) {
      console.log(tld, isAvailable);
    },
    onRegister: function(tld) {
      window.open("https://atomregistry.com?tld=" + tld);
    }
  });
</script>

Method 3 — Raw HTML

Full self-contained HTML — paste it directly into your page. No external script dependency.

Options Reference

Option	Type	Default	Description
container	string	#atom-registry-widget	CSS selector for the target element
bgColor	string	#0f0a19	Background color (hex)
borderColor	string	#8b5cf6	Border color (hex)
btnFromColor	string	#9333ea	Button gradient start color
btnToColor	string	#06b6d4	Button gradient end color
accentColor	string	#22d3ee	Accent/highlight color
textColor	string	#ffffff	Text color
fontFamily	string	Orbitron	Font family
borderRadius	string	16px	Widget corner radius
width	string	500px	Widget width
title	string	Check Availability	Widget header text
placeholder	string	yourword	Input placeholder text
buttonText	string	Check	Button label
priceText	string	2.5 ATOM	Price display text
showFooter	bool	true	Show "Powered by Atom Registry" footer
apiEndpoint	string	rest.cosmos.directory	Cosmos Hub REST endpoint to query
tldManagerContract	string	cosmos1xa9s4...	TLD Manager contract address
mainSiteUrl	string	https://atomregistry.com	Where the Register button links

Callbacks

Callback	Arguments	Description
onCheck	(tld, isAvailable, responseTime)	Fires after each availability check. responseTime in ms.
onRegister	(tld)	Fires when the Register button is clicked. Override to customize registration flow.
onError	(error)	Fires on any API or network error.
onView	()	Fires on first widget render.

Analytics

The widget includes a built-in analytics hook that posts events to any endpoint you control. Enable it by setting analyticsEnabled: true and analyticsUrl to your collector endpoint.

AtomRegistryWidget.init({
  container: "#widget",
  analyticsEnabled: true,
  analyticsUrl: "https://your-endpoint.com/events",
  widgetId: "homepage-widget"
});

Each event includes: type, widgetId, sessionId, timestamp, url, and referrer. Events are batched and sent on a short interval.

Custom Contract Integration

Point the widget at any contract that implements the same TLD availability query interface by overriding tldManagerContract and apiEndpoint. This lets you embed Atom Registry availability checking on any domain, pointed at any compatible CosmWasm contract on any Cosmos SDK chain.

Smart Contract Reference

All Atom Registry contracts are deployed on Cosmos Hub mainnet (cosmoshub-4) and are written in CosmWasm 1.5+ Rust. Queries use the standard CosmWasm REST interface. Execute messages require a signed transaction broadcast via any compatible Cosmos SDK signing method.

Registry Contract

The Registry contract is the source of truth for name and TLD ownership. It handles registration, policy enforcement, and transfers.

Execute Messages

Message	Description	Auth
Mint	Register a new domain. Called by Registrar or TLD Manager — not directly by users.	Registrar / TLD Manager
BatchMint	Register multiple domains in a single transaction.	Registrar / TLD Manager
Transfer	Transfer domain ownership. Called by Marketplace or direct owner transfer.	Owner / Marketplace
SetPrimaryDomain	Set a domain as the primary reverse-lookup for your wallet address.	Domain owner
ClearPrimaryDomain	Remove primary domain reverse-lookup.	Domain owner
SetSubdomainConfig	Configure subdomain registration policy — price, open/closed, payment recipient.	Domain owner
MintSubdomain	Register a subdomain directly (admin/registrar only).	Registrar
RegisterSubdomain	Public subdomain registration under a domain with open subdomain policy.	Anyone (if policy allows)
InitializeRoyalty	Set royalty recipient and basis points for marketplace sales.	Admin
UpdateRegistrar	Set the authorized registrar contract address.	Admin
UpdateMarketplace	Set the authorized marketplace contract address.	Admin

Query Messages

Message	Returns
{"owner_of": {"domain": "satoshi.atom"}}	Owner address or null
{"exists": {"domain": "satoshi.atom"}}	Boolean
{"domains_by_owner": {"owner": "cosmos1...", "start_after": null, "limit": 100}}	Paginated list of owned domains
{"get_primary_domain": {"address": "cosmos1..."}}	Primary domain for a wallet address (reverse lookup)
{"total_supply": {}}	Total registered domain count
{"royalty_info": {"sale_price": "1000000", "denom": "uatom"}}	Royalty recipient and amount for a given sale price
{"get_subdomain_config": {"domain": "myname.atom"}}	Subdomain policy — price, open/closed, payment recipient
{"get_subdomain_count": {"parent": "myname.atom"}}	Number of subdomains registered under a parent

Registrar Contract

The Registrar handles name registration using a commit-reveal scheme to prevent front-running. Registration is a two-step process: first commit a hash, then reveal after a delay.

Commit-Reveal Flow

1. 1
   Commit — send SHA256(name + secret + sender) as a commitment hash. Pay the optional commit fee.
2. 2
   Wait — commitments require a short delay before reveal (prevents same-block front-running).
3. 3
   Register — reveal with the original name, owner address, and secret. If the commitment matches and the name is available, registration completes and the fee is sent to the treasury.

Tiered Pricing by Name Length

Registration fees are set per character length. Shorter names cost more — single-character names are premium. The pricing tiers are configurable by the contract owner.

Execute Messages

Message	Description	Auth
Commit	Submit commitment hash. SHA256(name + secret + sender)	Anyone
Register	Reveal and complete registration. Requires prior commitment.	Committer
UpdatePricing	Update price tiers by name length.	Owner
UpdateTreasury	Change the treasury recipient address.	Owner
Pause / Unpause	Emergency pause of new registrations.	Owner
CleanExpiredCommitments	Garbage collect old uncommitted hashes.	Anyone

Query Messages

Message	Returns
{"get_price": {"name": "satoshi"}}	Registration price in uatom based on name length
{"get_commitment": {"commitment_hash": "abc..."}}	Commitment details and timestamp
{"get_config": {}}	Pricing tiers, treasury, payment denom, pause state

TLD Manager Contract

The TLD Manager handles TLD registration with its own commit-reveal scheme. It also accepts optional subdomain configuration at registration time, letting TLD owners set their pricing and open/closed policy in a single transaction.

Execute Messages

Message	Description
CommitTld	Step 1 — submit SHA256(tld + secret + sender). Prevents front-running of premium TLD names.
RegisterTld	Step 2 — reveal tld, owner, secret, and optional subdomain setup. Requires 90 second delay from commit. Sends payment to treasury.
UpdateConfig	Update admin, treasury, pricing tiers, payment denom, or pause state.

Query Messages

Message	Returns
{"get_price": {"tld": "coffee"}}	TLD registration price in uatom
{"get_commitment": {"address": "cosmos1..."}}	Current commitment for this sender
{"get_config": {}}	Full config — pricing, treasury, payment denom, pause state

Marketplace Contract

The Marketplace enables buying and selling of registered domains through three mechanisms: fixed-price listings, offers (buyer-initiated), and time-based auctions. All settlements automatically pay royalties to the registry's royalty recipient.

Listing Types

Type	Flow	Settlement
Fixed Listing	Seller sets price → buyer calls BuyListing	Instant on BuyListing
Offer	Buyer makes offer with expiry → seller calls AcceptOffer	On AcceptOffer
Auction	Seller sets start price + duration → bidders call PlaceBid → anyone calls FinalizeAuction	On FinalizeAuction after end_time

Execute Messages

Message	Description	Auth
CreateListing	List a domain at a fixed price in any denom.	Domain owner
CancelListing	Remove active listing and return domain.	Seller
BuyListing	Purchase at listed price. Sends funds, triggers transfer.	Anyone with funds
MakeOffer	Make a buy offer on any domain with optional expiry duration.	Anyone with funds
CancelOffer	Withdraw an active offer and reclaim funds.	Offer maker
AcceptOffer	Accept a specific buyer's offer. Triggers transfer and payment.	Domain owner
CreateAuction	Start a timed auction with start price and duration in seconds.	Domain owner
PlaceBid	Bid on active auction. Must exceed current bid by min_bid_increment_bps.	Anyone with funds
FinalizeAuction	Settle auction after end_time. Transfers domain to winner.	Anyone (after end_time)
CancelAuction	Cancel auction if no bids placed yet.	Seller
CleanupExpiredOffers	Garbage collect expired offers, refund buyers.	Anyone

Query Messages

Message	Returns
{"get_listing": {"domain": "satoshi.atom"}}	Active listing or null
{"get_listings_by_seller": {"seller": "cosmos1...", "start_after": null, "limit": 20}}	All listings for a seller
{"get_all_listings": {"start_after": null, "limit": 20}}	Paginated all active listings
{"get_offer": {"domain": "satoshi.atom", "buyer": "cosmos1..."}}	Specific buyer's offer
{"get_offers_by_domain": {"domain": "satoshi.atom", "start_after": null, "limit": 10}}	All offers on a domain
{"get_auction": {"domain": "satoshi.atom"}}	Active auction details
{"get_active_auctions": {"start_after": null, "limit": 20}}	All active auctions

Metadata Contract

The Metadata contract stores on-chain profile data for registered domains. Profiles are owned by the domain owner — only the owner of the domain in the Registry can update their profile. Supports both full replacement and partial patch updates.

Profile Fields

Field	Type	Description
avatar	String (optional)	Image URL or IPFS hash
bio	String (optional)	Short biography or description
website	String (optional)	Primary website URL
email	String (optional)	Contact email address
twitter	String (optional)	Twitter/X handle
github	String (optional)	GitHub username
discord	String (optional)	Discord username
telegram	String (optional)	Telegram handle
custom_fields	HashMap<String, String>	Arbitrary key-value pairs for any additional data

Execute Messages

Message	Description
SetProfile	Full profile replacement for a domain.
PatchProfile	Partial update — only specified fields change. Some(None) clears a field, None leaves it unchanged.
UpdateAvatar / UpdateBio / UpdateWebsite / UpdateEmail	Single-field updates for convenience.
UpdateSocial	Set or clear any social platform handle by platform name string.
SetCustomField / RemoveCustomField	Manage arbitrary custom key-value pairs.
ClearProfile	Remove all profile data for a domain.

Query Messages

Message	Returns
{"get_profile": {"domain": "sean.atom"}}	Full profile object or null
{"get_avatar": {"domain": "sean.atom"}}	Avatar URL or null
{"get_bio": {"domain": "sean.atom"}}	Bio string or null
{"get_social": {"domain": "sean.atom", "platform": "twitter"}}	Handle string or null

dSSL Manager Contract

dSSL (Decentralized SSL) is the trust and reputation layer of Atom Registry. It lets domain owners publish a verifiable trust record — a cosmos.toml manifest — and earn a trust level based on their score and third-party attestations. The browser extension reads dSSL levels and displays trust badges next to resolved domains.

How dSSL Works

1. 1
   Publish a cosmos.toml — host a TOML manifest at any URI (IPFS, HTTPS, Arweave). It describes your domain, ownership proof, security posture, services, and audit history.
2. 2
   UpsertRecord — call the dSSL Manager with the URI, content hash, and a self-reported base score (0–10,000).
3. 3
   Earn attestations — approved attestors (auditors, verifiers, the Atom Registry admin) can attest your domain with an additional score boost and a proof URI.
4. 4
   Resolve a level — the contract sums base_score + attestation_boost and resolves it against the TLD's level rules to assign a level_id (e.g., spark, beacon, citadel).
5. 5
   Browser displays badge — the extension reads the dSSL record and shows the vibe name and icon next to the resolved domain.

Trust Levels

Trust levels are defined per TLD by the TLD owner via SetTldPolicy. Each level has a machine-readable level_id, a human-friendly vibe_name, an icon, and a minimum score threshold. Example level scheme:

level_id	vibe_name	Min Score	Meaning
spark	Spark	1	Basic dSSL record exists
beacon	Beacon	5000	Attested and verified
citadel	Citadel	8000	Fully audited and attested

The cosmos.toml Manifest

The cosmos.toml file is the heart of a dSSL record. It is a TOML document that declares everything about a domain or TLD in a structured, machine-readable format. Key sections:

Section	Contents
[meta]	Profile type, domain, TLD, chain ID, contract addresses, schema version
[dssl]	Trust level, score, badges, review window
[ownership]	Owner address, controller, proof method (registry_owner_of, multisig)
[branding]	Display name, tagline, icon, banner, theme color
[links]	Website, docs, support, status, social links
[services]	HTTP, API, RPC, gRPC endpoints — browser can render as connect buttons
[dns]	Hybrid mode DNS records — A, AAAA, CNAME, TXT, MX, DNSSEC flag
[security]	Policies, GDPR, SOC2, ISO27001 status
[proofs]	Verifiable proof items — registry_anchor, domain_control_http, kyb_document, audit_report
[audits]	Smart contract and infrastructure audit reports with IPFS references
[signatures]	Optional off-chain manifest signature for additional verification

Execute Messages

Message	Description	Auth
UpsertRecord	Create or update dSSL record with cosmos.toml URI, hash, and base score.	Domain owner
ClearRecord	Remove dSSL record (does not affect domain registration).	Domain owner
SetTldPolicy	Define level rules for a TLD.	Admin or TLD owner
AttestDomain	Add attestation with score boost and proof URI.	Approved attestor
RevokeAttestation	Remove own attestation from a domain.	Attestor
AddAttestor / RemoveAttestor	Manage approved attestor list.	Admin
RevokeRecord / UnrevokeRecord	Admin revocation of a domain's dSSL profile.	Admin

Query Messages

Message	Returns
{"get_record": {"domain": "cosmos.atom"}}	Full dSSL record with score, level, expiry
{"get_tld_policy": {"tld": "atom"}}	Level rules for the TLD
{"get_attestations": {"domain": "cosmos.atom", "start_after": null, "limit": 20}}	All attestations for a domain
{"is_expired": {"domain": "cosmos.atom"}}	Boolean — profile renewal required
{"is_revoked": {"domain": "cosmos.atom"}}	Boolean — admin revocation status
{"is_attestor": {"address": "cosmos1..."}}	Boolean — approved attestor check
{"records_by_owner": {"owner": "cosmos1...", "start_after": null, "limit": 50}}	All dSSL records owned by address

Resolver Contract

The Resolver maps names to any type of record. It supports arbitrary record types, cross-chain wallet addresses, IPFS content hashes, and ActivityPub/Matrix federation handles. Registry address updates use a timelock for security.

Execute Messages

Message	Description
SetRecord	Set a single record by type and value. Record type is a free-form string — A, CNAME, TXT, or any custom type.
SetRecords	Set multiple records in a single transaction.
DeleteRecord	Remove a specific record type from a domain.
SetAddress	Store a wallet address for a specific chain — e.g. chain: "ethereum", address: "0x..."
SetIpfs	Store an IPFS content hash for this domain.
SetFederation	Set an ActivityPub/Matrix handle — e.g. name: "mastodon", address: "@user@instance.social"
DeleteFederation	Remove a specific federation handle.
ClearAllRecords	Remove all records for a domain.
ProposeRegistryUpdate	Propose a new registry address (timelocked).
ExecuteRegistryUpdate	Apply a proposed registry update after timelock expires.
CancelRegistryUpdate	Cancel a pending registry update proposal.

Query Messages

Message	Returns
{"get_record": {"domain": "myname.atom", "record_type": "A"}}	Record value or null
{"get_all_records": {"domain": "myname.atom", "start_after": null, "limit": 50}}	All records as key-value map
{"get_address": {"domain": "myname.atom", "chain": "ethereum"}}	Cross-chain wallet address or null
{"get_ipfs": {"domain": "myname.atom"}}	IPFS content hash or null
{"get_federation": {"domain": "myname.atom", "name": "mastodon"}}	Federation handle or null
{"get_record_count": {"domain": "myname.atom"}}	Total record count for domain
{"get_pending_registry_update": {}}	Pending registry proposal with timestamp

Site Registry Contract

The Site Registry stores on-chain HTML content, manages version history, and collects the storage fee on first deployment.

Execute Messages

Message	Description	Fee
DeploySite	Store or update HTML content for a name. First deployment requires 5 ATOM attached. Updates are gas only.	5 ATOM first, then gas
DeleteSite	Remove the current site content. Version history is preserved.	Gas only
Withdraw	Admin only — withdraw accumulated fees from the contract.	Gas only (admin)

Query Messages

Message	Returns
{"site": {"name": "myname.atom"}}	Current HTML content, version number, and metadata
{"site_versions": {"name": "myname.atom", "start_after": null, "limit": 20}}	Paginated version history with timestamps
{"site_version": {"name": "myname.atom", "version": 1}}	HTML content for a specific version number
{"has_site": {"name": "myname.atom"}}	Boolean — whether a site exists for this name

ProtoWriter — Native Transaction Signing

All Atom Registry browser tools sign transactions using ProtoWriter, a hand-rolled protobuf encoder that replaces CosmJS entirely. This was necessary because CosmJS imports conflict with Keplr's SES (Secure ECMAScript) lockdown environment, causing W.getPolyfill is not a function errors in production.

ProtoWriter encodes the transaction wire format manually using field numbers and wire types from the Cosmos SDK protobuf schemas. It constructs:

• TxBody — wraps the encoded message in a TxRaw.body_bytes
• AuthInfo — signer info with secp256k1 public key, mode info (DIRECT), and fee
• TxRaw — the final signed transaction with body, auth info, and signature bytes

The signing flow uses Keplr's signDirect method, which takes the raw bodyBytes and authInfoBytes and returns the secp256k1 signature. ProtoWriter assembles the final TxRaw which is base64-encoded and broadcast.

// 1. Encode the message
const msgBytes = encodeMsgExecute(sender, contract, msgObj, fundsUatom);
const bodyBytes = txBody(msgBytes);

// 2. Get account info
const { accountNumber, sequence } = await getAccount(address);

// 3. Simulate gas
const gasLimit = await simulateGas(bodyBytes, authBytes);
const feeAmount = Math.ceil(gasLimit * 0.025);

// 4. Sign with Keplr
const signResp = await keplr.signDirect(chainId, address, {
  bodyBytes, authInfoBytes, chainId, accountNumber
});

// 5. Broadcast
const rawBytes = txRaw(
  signResp.signed.bodyBytes,
  signResp.signed.authInfoBytes,
  unb64(signResp.signature.signature)
);
await broadcastTx(rawBytes);

Developer Guide

Everything you need to build on top of Atom Registry — query contracts from the command line, integrate the widget, or build new tools using the ProtoWriter pattern.

CLI Examples (gaiad)

All contract queries use the standard CosmWasm smart query interface. These examples use gaiad with the public node RPC.

gaiad query wasm contract-state smart   cosmos16nff0lmuegn2zr6ca3dp8jnqltpq2c9ayhmqn3avjq0wne95h2xqkhn9qe   '{"owner_of": {"name": "satoshi.atom"}}'   --node https://cosmos-rpc.publicnode.com:443 -o json

gaiad query wasm contract-state smart   cosmos16nff0lmuegn2zr6ca3dp8jnqltpq2c9ayhmqn3avjq0wne95h2xqkhn9qe   '{"names_by_owner": {"owner": "cosmos1mn2ekfxs8zc40hdjt44edfaht0pdgquluzrs2j", "start_after": null, "limit": 100}}'   --node https://cosmos-rpc.publicnode.com:443 -o json

gaiad query wasm contract-state smart   cosmos1xg6jh7nechv6kxrw35m08qdpaysnu97xjz5alql75p2k5xrcdvjs8rx7jt   '{"site": {"name": "cosmos.onchain"}}'   --node https://cosmos-rpc.publicnode.com:443 -o json

gaiad query wasm contract-state smart   cosmos1swmjnderkae2hpegvt75dn34kya388vydxg5k5mzd0dl6wme2teq2xxpkv   '{"resolve": {"name": "mysite.atom", "record_type": "A"}}'   --node https://cosmos-rpc.publicnode.com:443 -o json

Querying Contracts via REST

All contracts are queryable via the standard CosmWasm REST interface without any SDK. Base64-encode your JSON query and hit the endpoint directly.

const query = {"owner_of": {"name": "cosmos.atom"}};
const queryB64 = btoa(JSON.stringify(query));
const url = `https://cosmos-rest.publicnode.com/cosmwasm/wasm/v1/contract/${CONTRACT_ADDR}/smart/${queryB64}`;
const result = await fetch(url).then(r => r.json());

LCD Endpoint Fallback Chain

All Atom Registry tools use a multi-endpoint fallback strategy — if one LCD endpoint fails, the next is tried automatically. The current fallback order:

Priority	Endpoint
1	https://cosmos-rest.publicnode.com
2	https://rest.cosmos.directory/cosmoshub
3	https://cosmoshub-api.lavenderfive.com
4	https://cosmos-api.polkachu.com

Integration Guide

Add TLD Availability to Your Site

The fastest integration is the Widget SDK. Drop in the script tag, configure your colors, and you have a live availability checker on your site in under five minutes. See Section 8 — Widget SDK for the full reference.

Query Name Ownership from Your App

If you need to verify that a visitor owns a specific Atom Registry name, query the Registry contract with their connected wallet address and check the returned name list:

async function ownsName(walletAddr, name) {
  const query = {
    names_by_owner: { owner: walletAddr, start_after: null, limit: 100 }
  };
  const b64 = btoa(JSON.stringify(query));
  const REGISTRY = "cosmos16nff0lmuegn2zr6ca3dp8jnqltpq2c9ayhmqn3avjq0wne95h2xqkhn9qe";
  const res = await fetch(
    `https://cosmos-rest.publicnode.com/cosmwasm/wasm/v1/contract/${REGISTRY}/smart/${b64}`
  ).then(r => r.json());
  return (res.data?.names || []).includes(name);
}

Build With the ProtoWriter Pattern

If you are building browser-based tooling that needs to sign Cosmos SDK transactions without CosmJS, copy the ProtoWriter implementation from any Atom Registry page. It has no external dependencies, works in any modern browser, and is fully compatible with Keplr's signDirect method. The core is ~50 lines of vanilla JavaScript.

On-Chain NFTs & Real World Assets

The same 128KB storage capability that powers on-chain sites opens up a more fundamental breakthrough: NFTs and tokenized real world assets where the asset itself — not a pointer to it — lives permanently on the blockchain.

The 128KB Storage Breakthrough

CosmWasm contract state entries on Cosmos Hub support up to approximately 128KB per key. This is enough to store a complete, high-quality image alongside rich metadata in a single contract state entry. No IPFS. No Arweave. No external storage. The asset is the contract.

Compare this to the current NFT landscape:

Type	What's on-chain	What can disappear
Standard NFT	Token ID + pointer (IPFS URL)	The image, the metadata, the IPFS gateway
Arweave NFT	Token ID + Arweave TX ID	Arweave itself (different network, different risk)
Atom Registry NFT	Token ID + full image bytes + all metadata	Nothing. It's all on Cosmos Hub.

WebP Base64 — Truly On-Chain Images

The key to fitting a real photographic image within the 128KB limit is WebP encoding. WebP achieves dramatically better compression than JPEG or PNG at the same visual quality level.

The image is embedded as a base64 data URL directly in the contract state:

// Query the NFT contract
const result = await queryContract(nftContract, {"get_token": {"token_id": "1"}});

// The image is immediately usable — no additional fetch needed
const imgSrc = result.data.image; // "data:image/webp;base64,ABC..."
document.getElementById("nft-image").src = imgSrc;

Real World Asset Tokenization

The Atom Registry infrastructure — registry, resolver, transfer, version history — maps directly onto the requirements of real world asset tokenization. The same contracts that manage domain name ownership can manage property records, with the deed scan embedded as the NFT image.

Property Deed on Cosmos Hub

A property deed token built on the Atom Registry model would store:

• document_data — WebP scan of the physical deed (base64, ~40–80KB)
• parcel_id — Legal parcel identifier (String)
• legal_description — Full legal description of the property (String)
• owner — Current owner wallet address (Addr)
• acquisition_date — Unix timestamp (u64)
• assessed_value — Current assessed value in uatom or USD string (Uint128/String)
• encumbrances — Liens, easements, restrictions (String)
• verified — Notary or authority attestation (bool)
• chain_of_title — Transfer history via contract events

Transfer of ownership is a single Transfer execute message — the same mechanism already working in the Atom Registry domain system. Every transfer is recorded immutably in the contract event history.

Other RWA Applications

• Vehicle titles — VIN, make, model, odometer history, lien status
• Business licenses — Issuing authority, expiry, scope of license
• Academic credentials — Institution, degree, graduation date, GPA, issuer verification
• Equipment leases — Asset description, lease terms, payment schedule, condition reports
• Art provenance — Artist, creation date, exhibition history, appraisals, ownership chain

Deployment & Operations

Reference information for deploying the Atom Registry web application, managing server files, and configuring the blockchain infrastructure.

Server File Layout

All Atom Registry web files are deployed to the webroot on an AlmaLinux/Webuzo shared hosting environment. The application is entirely static — no server-side code, no database, no PHP. All blockchain interaction happens client-side.

File	URL	Description
index.html	/	Main dapp — name and TLD registration
onchain.html	/onchain.html	On-chain sites manager
search.html	/search.html	Web3 domain search and resolver
profiles.html	/profiles.html	On-chain page builder
contracts.html	/contracts.html	Smart contract launcher
docmaker.html	/docmaker.html	Document → contract pipeline
browser.html	/browser.html	Chrome extension marketing page
widget.js	/widget.js	Embeddable widget SDK
widget.html	/widget.html	Standalone iframe widget
widgets/index.html	/widgets/	Visual widget builder
atomextension.zip	/atomextension.zip	Chrome extension download
cosmocon.png	/cosmocon.png	Site favicon and logo
docs.html	/docs.html	This documentation

LCD Endpoints & RPC

All LCD (REST) endpoints used by Atom Registry tools are public community endpoints. No API keys are required. The application automatically falls back through the list on any failure.

Endpoint	Provider	Used For
https://cosmos-rest.publicnode.com	PublicNode	Primary REST — account, simulate, broadcast, query
https://rest.cosmos.directory/cosmoshub	Cosmos Directory	REST fallback
https://cosmoshub-api.lavenderfive.com	Lavender Five	REST fallback
https://cosmos-api.polkachu.com	Polkachu	REST fallback
https://cosmos-rpc.publicnode.com:443	PublicNode	gaiad CLI / RPC operations

Gas & Fee Reference

All Atom Registry tools use the following gas parameters for transaction construction:

Parameter	Value	Notes
Gas price	0.025 uatom	Standard Cosmos Hub minimum gas price
Gas adjustment	1.8x	Applied to simulated gas to set the limit
Fallback gas limit	10,000,000	Used if simulation fails
Simulation	Auto	Every transaction simulates before presenting to Keplr

Typical Transaction Costs

Operation	Approximate Gas	Approximate ATOM Fee
Register a name	~150,000	~0.004 ATOM
Register a TLD (+ 2.5 ATOM fee)	~200,000	~0.005 ATOM + 2.5 ATOM
Deploy on-chain site (+ 5 ATOM fee)	~500,000–2,000,000	~0.05–0.05 ATOM + 5 ATOM
Update on-chain site	~500,000–2,000,000	~0.05 ATOM
Store WASM code (~100KB)	~4,000,000–8,000,000	~0.1–0.2 ATOM
Instantiate contract	~200,000–500,000	~0.005–0.013 ATOM
Transfer name or TLD	~150,000	~0.004 ATOM

Updating atomextension.zip

The extension download is served directly from /atomextension.zip. To update the extension, build the new version, create the ZIP containing the extension files (not a wrapper folder), and upload it to the webroot replacing the existing file. The download link on /browser.html always points to this single file.