Register a .dot domain

A .dot domain is a readable name on the Polkadot Products Devnet. It has an owner account and can point to an app bundle, so that opening your-app.dot in the Polkadot app or the web gateway loads your app.

You register and manage names with the DotNS CLI (@polkadot-community-foundation/dotns-cli). Ordinary app names follow the normal registration path, and short or reserved names have extra gates.

Owning a name means owning an ERC-721 token. Binding it to an app means writing an IPFS content hash into its resolver, which clients read to fetch your bundle. Naming (DotNS) covers the resolution path and the contracts behind it.

Paseo Next v2

This page covers the PCF Products Devnet (devnet preset). For Paseo Next v2 (paseo preset), see Register a .dot Domain.

Install the CLI

The dotns command ships in @polkadot-community-foundation/dotns-cli. Packages & tools has the install line.

Every command takes a network with --env devnet (or the DOTNS_ENV environment variable).

Set up an account

The CLI signs with its own key, separate from any account in the Polkadot app. Set one up before you register anything.

Fastest: a throwaway account

For a hackathon, you don't need to import a seed phrase or set a keystore password. Create a fresh account and pass its mnemonic to the CLIs through the environment:

# One fresh BIP-39 mnemonic, generated with the crypto that ships inside the CLIs
export MNEMONIC="$(NODE_PATH="$(npm root -g)/@polkadot-community-foundation/dotns-cli/node_modules" \
  node -e 'const c=require("@polkadot/util-crypto");c.cryptoWaitReady().then(()=>console.log(c.mnemonicGenerate()))')"

export DOTNS_MNEMONIC="$MNEMONIC"   # dotns signs with this — no `dotns auth set`, no password
dotns account address               # the throwaway's address — fund THIS at the faucet

pad takes the same $MNEMONIC when it publishes (--mnemonic "$MNEMONIC"), so one account both owns the name and deploys to it. The phrase only lives in this shell session. Save it if you want to keep the name. If you discard it, the account really is throwaway.

Set a key, or you sign as a shared account

With neither DOTNS_MNEMONIC/DOTNS_KEY_URI set nor dotns auth set run, dotns falls back to a shared public dev account that anyone can control. A name registered to it is not yours, and anyone can transfer it away. dotns prints a warning on every command when this happens.

Then check which account is active:

dotns account address
dotns account info --env devnet

Keep it: the encrypted keystore

To reuse an account across sessions, store a mnemonic or key-uri in the password-protected dotns keystore instead of the environment:

dotns auth set

The prompt first asks which kind of secret you are storing. Answer mnemonic or key-uri, then paste the value. Finally it asks you to set a keystore password. Every later dotns command needs that password: pass it with --password, or export DOTNS_KEYSTORE_PASSWORD so scripts don't stall on a hidden prompt.

To do it in one non-interactive step instead:

export DOTNS_KEYSTORE_PASSWORD="…"
dotns auth set --mnemonic "…" --account my-app

Fund and map the account

Registration signs a PolkaVM transaction, so your account also needs a balance for fees and a mapped EVM address. Fund it from the faucet, then:

# Map your Substrate account to its EVM address (once per account)
dotns account map --env devnet

# Check whether an address is already mapped
dotns account is-mapped <address> --env devnet

dotns account is-mapped checks the address you pass in. Its connection banner still shows the CLI's default signer, so it may show the shared dev account even when your keystore is set up. Trust the mapped: line for the address you asked about, not the banner.

Reserved and short-name gating

Not every label is open to everyone. The public commit-reveal path requires a label of at least three characters, and sorts labels by their stem (the label with any trailing digits stripped):

• Reserved: stems of five characters or fewer are gated and cannot be claimed through the open path.
• Personhood-gated: stems of six to eight characters need proof of personhood (the lite tier for a stem plus exactly two digits, the full tier for no digits).
• Open: stems of nine characters or more register without a personhood check.

The controller rejects governance-reserved and explicitly reserved names. Personhood-tier usernames are issued through the gateway path when you prove personhood in the Polkadot app, not through the CLI commands below.

So if you just want a name for an app, use a label whose stem is nine characters or longer, for example my-cool-app. It is the only band that registers without proof of personhood, which today comes from the Polkadot app and not from the CLI. Shorter names such as my-app (a six-character stem) will be refused.

You can't check a label's tier before committing to it, so count the stem yourself.

Register a name

Registration is a commit-reveal handshake: you commit a hashed intent, wait a minimum commitment age, then reveal and pay. The CLI runs all three steps:

dotns register domain -n my-cool-app --env devnet

It takes several minutes, because the commitment has to finalize, then mature, then be revealed. Before the final step the CLI prints the tier and the price it is about to pay:

  name tier:  NoStatus
  your tier:  NoStatus
  message:    Available to all
  price:      10 PAS

Useful options:

• -r, --reverse: also set this name as your account's reverse (primary) record.
• --json: print machine-readable output.

Whatever the CLI printed, check the result on chain before you do anything else:

dotns lookup owner-of my-cool-app --env devnet
dotns lookup name my-cool-app --env devnet    # full record view

You can also look the name up in the DotNS UI.

If the owner is your address, the name is yours and you are done. Only if it is not, resume the handshake:

dotns register list --env devnet     # inspect cached commitments
dotns register retry my-cool-app --env devnet

Bind a name to a bundle

Once you have deployed your app (see Build & publish an app), you have an IPFS CID for the bundle. Write it into the content resolver to make the name resolve to your app:

# Set the content hash (IPFS CID) for a name you own
dotns content set my-cool-app <cid> --env devnet

# Read it back
dotns content view my-cool-app --env devnet

After this, opening my-cool-app.dot in the Polkadot app or at dev-dot.li resolves the name, decodes the content hash to the CID and fetches your bundle from the gateway.

Manage a name

# Set one of your names as the primary (reverse) name for your account
dotns primary set my-cool-app --env devnet
dotns primary status --env devnet

# Transfer ownership to another address or label
dotns lookup transfer my-cool-app --destination <address-or-label> --env devnet

# Create a subname under a name you own
dotns register subname --env devnet

Learn more

• Naming (DotNS): resolution, the contracts and the naming rules
• DotNS UI: the same lookups in a browser
• Build & publish an app: bind the name to a bundle