Selling subnames

The SubdomainRegistrar is a companion contract that lets you sell subnames under a name you own. Buyers pay your price, get their subname instantly, and the proceeds are yours. The protocol takes nothing.

Setting up a sale

From your name’s manage page, open Sell subnames and configure:

  • Price: in ETH per subname.
  • Payout address: where proceeds go (defaults to you).
  • Token gate (optional): require buyers to hold a token or NFT you nominate, for community-only drops. See Token gating.
  • Enabled: sales can be switched on and off at any time.

The registrar itself can also price a sale in any ERC-20 token, but this app only handles ETH sales. Setting an ERC-20 price, and buying from a sale priced that way, are done by calling the contract directly.

Token gating

A gate turns a sale into a community-only drop: buyers must hold a minimum balance of a token you nominate, or their purchase reverts. Point it at your DAO’s ERC-20 and require 100 of them, or at your membership NFT and require 1.

Both standards work through the same field, because the registrar only ever calls balanceOf(address), which ERC-20 and ERC-721 both expose. It never asks which standard it is. The minimum you set follows from that:

  • ERC-20: an amount in base units. 100 tokens at 18 decimals is 100000000000000000000.
  • ERC-721: a count of NFTs held. At least one from the collection is 1.

The gate is a balance check and nothing more. Nothing is transferred, nothing is approved, and the buyer’s gate token is never touched: they still pay the sale price in ETH. It also applies to a whole contract rather than a token ID, so you can require “holds at least one from this collection”, never “holds #42”.

The contract enforces it, not the website. The check runs inside register, so it applies to every buyer on every route: this app, Etherscan, a script, another contract. There is no path to a subname that skips it.

A gate proves a balance, not a membership. The check reads the buyer’s balance at the moment of purchase. Nothing requires them to have held the token before or to keep it after, so they can buy it, register, and sell it back in one transaction, or flash-loan it outright. The gate also applies to whoever pays: a holder can have a subname minted to someone who holds nothing, and any subname can be transferred once it exists. If you need a durable claim about who ends up holding your subnames, a gate is the wrong tool.

ERC-1155 does not work. Its balanceOf takes a token ID as well, so the call does not match and the gate rejects everyone.

A bad address fails closed. If the gate address is not a token, its balance reads as zero and nobody can buy. The sale stays enabled and simply stops selling, with nothing to tell you why, so check the address before you save.

Escrow mode vs flash mode

To mint a subname, the registrar must momentarily control the parent name. There are two ways to allow that:

Escrow mode: you deposit the parent NFT into the registrar. Sales work with no further setup, and you can withdraw the parent at any time (which disables the sale). While escrowed, you remain the controller: you keep configuring the sale, and only you can pull the parent out.

Flash mode: you keep the parent in your wallet and give the registrar approval. Each purchase pulls the parent in, mints the subname, and returns the parent to you in the same transaction. You keep custody, at slightly higher gas per sale.

Escrow is simpler if you sell often; flash if you want the NFT in your own wallet.

Withdrawing proceeds

  • ETH sales accumulate in the registrar under a pull-payment ledger. Withdraw your balance any time from the same tab.
  • ERC-20 sales transfer directly to the payout address on each purchase, so there is nothing to withdraw. Buyers approve the token before purchasing.

Safety properties

The registrar was designed to make rug-pulls structurally hard:

  • Configurations are bound to the current owner and epoch of the parent. If the parent expires, is re-registered, or is sold, stale configurations stop working automatically.
  • The buyer’s purchase mints directly to the buyer in the same transaction as payment, so there is no window where the seller holds both the money and the goods.
  • Anyone can clear a stale escrow record once the registrar no longer owns the parent.

If you register a name that a previous owner had once listed for subname sales, their old escrow record lingers (harmless and dead, bound to their epoch) until it is cleared. Clear it once (the manage tab does this automatically) and you can then set up your own sales, with all proceeds going to you.

One caveat buyers should understand: the parent owner can later reclaim any subname by re-registering its label (see Subnames). A subname purchase is trust in the parent’s owner, priced accordingly.