[!WARNING] This open source code is provided for research, experimentation, and developer education only. This code has not been audited, is actively experimental, and may contain bugs, vulnerabilities, or incomplete features. Use at your own risk.

Dotns

Smart contracts for registering .dot names on Polkadot.

DotNS is a naming system for Polkadot. An account can register a .dot name, receive an ERC721 token that represents ownership of that name, attach records to it (addresses, text, content hashes, chat keys), and create subnames beneath it. Two independent issuance paths coexist on the same underlying registrar: a public commit-reveal path for anyone who wants a name, and a Proof-of-Personhood gateway path that issues lite-person and full-person usernames on behalf of verified users. Every piece of state the protocol surfaces is readable through public view functions on the chain itself, so a client needs only a node and a small set of well-known contract addresses to answer any question about the system.

Diagrams

System diagram

Deployment and operations

Deployment notes are in DEPLOYMENTS.md. Network addresses are recorded in deployments/<network>/<chain-id>.json and published with each release.

Cutting a release

A release publishes the contract ABIs and the deployed addresses as GitHub release assets, described in RELEASE_ARTIFACTS.md. It does not deploy anything; deploying contracts to a network is a separate process, described in DEPLOYMENTS.md.

Run Publish Release Package from the Actions tab, pick the branch to release from, and enter the version (v0.5.5). The workflow does the rest: it builds, tests, extracts the ABIs listed in .github/abi-contracts.txt, generates the address and manifest files, creates the release as a draft with every asset attached, verifies the set against what the build produced, and only then publishes. Pushing a matching tag runs the same workflow, so git tag v0.5.5 && git push origin v0.5.5 remains equivalent.

Pre-releases use Publish Beta Package with a suffixed version, v0.5.5-rc1. The version is the release identity; the version field in package.json is unrelated and nothing reads it.

Do not create releases through the GitHub UI's release form, or with gh release create. Both publish immediately, and because this repository has immutable releases enabled, a published release can no longer accept assets: only its title and notes stay editable. A release made that way carries no ABIs at all. The workflow rejects an already-published version before building, so the mistake fails in seconds rather than silently shipping an empty release.

If a run fails partway, re-run it from the Actions tab; the draft is updated rather than duplicated. One case needs a manual step: the upload replaces an asset of the same name but never removes others, so if the contract list changed since the failed run, the draft still carries the assets it no longer expects and the verification step will keep refusing to publish. Delete the draft and re-run. If the version has already been published, use a different one, since its assets cannot be changed.

Economics

Every name admitted to public sale costs the same refundable deposit: 10 DOT at launch. The amount is not fixed in the registration path. It comes from a cost model resolved through the protocol registry under the costModel key, and governance can replace that model without touching the registrar or its storage. The launch model, DotnsFlatPricing, returns one deposit for every length. A length-sensitive scarcity curve, DotnsScarcityPricing, ships alongside it as a candidate for a later version but is not the registered default.

Base length and the digit rule

Pricing and eligibility read a name's base length: the character count once a trailing number is set aside. A name carries no trailing digits or exactly two; one digit, or three or more, is rejected before pricing. The trailing digits come off before the length is measured, so andrew and andrew01 both classify as a six-character name. Base length decides which band a name falls in and who may register it; under the flat model it does not change the amount.

What a name costs

Only names of nine characters or more are on public sale by default. The short-name switch, off at launch, keeps base lengths below nine off the public paid path. Every name on sale costs the flat deposit:

Who can register a name

Three bands share the one deposit.

Personhood unlocks only the six-to-eight band. A no-digit name there needs full-person verification; a two-digit name needs lite-person verification. It gates who may buy, not the price: the deposit is the same one everyone pays.

Names shorter than nine characters are closed on the public paid path by default. A paid registration below nine reverts until governance opens the short-name market with a single switch. The switch gates the public paid path alone: the personhood gateway issues names of any length without it, and the reserved path does not consult it. It defaults off, so at launch only names of nine characters or more are for sale.

Names of five characters or fewer are never sold on the public path, which rejects a reserved-tier label outright. Such a name enters circulation only through the reserved path, which the contract owner or a whitelisted operator calls to mint an available label at zero base cost with no deposit and no personhood check. There is no treasury: no value moves when a reserved name is issued.

Worked examples

The path decides whether the amount is a refundable deposit, a non-refundable fee, or nothing at all. Every amount below is the flat launch deposit of 10 DOT.

Deposits and protocol fees

Registering a name under your own key locks a refundable deposit equal to the name's price. The deposit is bound to the name rather than to you, so it travels with the token on every transfer and unlocks only when the current holder releases the name back to escrow.

A name someone else pays for, and a transfer, pay a non-refundable fee instead. When a third party pays for another wallet's registration, the charge is the same owner-side price, with no separate friction added; it routes to a single protocol fee pot, and the owner's escrow slot is seeded with a zero amount so the release lifecycle stays reachable. A gateway grant carries neither a deposit nor a fee. The protocol fee pot only ever grows: it backs no refunds, and nothing burns, sweeps, or withdraws from it. Refunds draw solely on the separate per-asset reserve that deposits fund. A holder's own deposit is their money held in trust and is never moved into fees.

Transfers re-price at the name's own length

A transfer charges the name's own price, but only in two cases: the recipient cannot clear the name's band, or the move is a personhood downgrade, where the recipient's tier is lower than the sender's. Passing a six-character name to a wallet that could never have registered it costs the name's own price, so there is no cheap way to hand a band-gated name to a party who could not have earned it. A move between two wallets that both clear the band, and a move to the same address, cost nothing. The fee, when one is owed, settles into the protocol fee pot. The deposit, when present, rides with the name: the escrow position rebinds to the new holder rather than refunding, and only releasing the name back to escrow unlocks the locked deposit.

Versioned pricing

The cost model is chosen by governance and swapped, not upgraded. Registering a new model adds it under a fresh version and points the current version at it; earlier versions stay priceable, so a registration already committed against an earlier version settles at the amount it committed to. A commitment binds the version current when it is made, and the reveal reverts if it is presented at a different version, so a model change between commit and reveal cannot move the amount. Governance can also point the current version back at an earlier registered model.

Release lifecycle

Releasing a name starts two independent clocks, and the distinction between them is what makes a released name both recoverable and recyclable.

Both are stamped at release time, so a governance change never moves the clocks on a name already released. Inside the redeem window the name belongs to its previous holder, and DotnsRegistrar.available reports false so no client advertises it as free. The holder has two mutually exclusive options:

• redeem returns the token and moves no value. The position keeps its recipient, asset and amount, so the deposit stays locked and the name lands back in its exact pre-release state, releasable again later on a fresh pair of clocks. This is the undo for an accidental release.
• withdraw credits the deposit and forfeits the right to redeem. A holder paid for the name cannot also take it back, otherwise they would hold a name no deposit backs.

Once redeemableUntil passes, reclaim is permissionless through the ordinary commit-reveal path, whether or not the previous holder ever withdrew. If the position still holds value, reclaim settles it: the amount is credited to the previous holder's pull-payment balance and stays claimable with no deadline. The value follows the departing holder; the name does not wait for them. Cross-paid registrations seed zero-amount positions, so those names have nothing to withdraw and nothing to settle.

Cost-model versioning

D and F are fixed for the life of a pricing model. Changing either means deploying a fresh model with the new values and registering it, at which point it becomes the current version; there is no live setter that edits the numbers in place. Governance can also point the current version back at an earlier registered model to roll a change back. An in-flight registration prices at the version it committed to, so a model change between commit and reveal leaves its cost unchanged.

What governance controls

Governance sets D and F to whatever values it chooses. The contracts hold them coherent and nothing more: D above zero, F above zero and no greater than D, and D within a ceiling that keeps the six-character multiplication from overflowing. There is no cap on how high or low D goes and no limit on how fast it moves, so any rate limit or advance notice comes from the governance process rather than from these contracts. Governance also opens or closes the short-name market with the switch, tunes the release cooldown within its one-hour bound, sets the redeem window between 1 and 30 days, and sets the gateway's reservation duration. None of these controls lets governance seize, reassign, or destroy a name anyone already holds.

Refund ledgers

The escrow keeps two separate pull-payment ledgers. One has no cooldown and serves as the fallback when a registration overpayment cannot be pushed back to the sender inline. The other gives every credit its own cooldown clock and holds transfer-fee overpayments. A deposit unlocked by releasing a funded name lands on the no-cooldown ledger; its delay comes instead from the position's own withdrawAvailableAt stamp, so once withdraw lands the credit is immediately pullable. Clients enumerate pending refunds through the escrow's public views, which page under a fixed cap so discovery stays bounded.

Clients that need the exact moment a released name becomes registrable should read redeemableUntil from getReleasePosition rather than polling available.

Contracts

Two controllers sit on top of a single registrar and a single protocol registry. The registrar holds the ERC721 token per name; the registry holds the forward node => (owner, resolver) mapping and subname hierarchy; the resolvers hold per-name records; the protocol registry is the indirection layer through which every contract resolves its siblings at runtime. Controllers are the entry points: they mint names and drive the side effects. Neither controller imports the other. The layers underneath arbitrate collision handling: ERC721 uniqueness on the registrar, and a single reservation table on PopRules that both flows read through.

DotnsRegistrarController

Commit-reveal controller for the public registration path. A caller first submits a commitment hash, waits out the minimum commitment age, then reveals the registration parameters alongside the payment. The controller validates the commitment, routes price and eligibility through PopRules, and orchestrates every side effect of a successful registration: the mint on the registrar, the forward wire-up on the registry, the reverse record on the reverse resolver, the immutable Store write, and any refund owed on overpayment. Acceptable input is a single DNS label of at least the minimum-length policy; shorter labels revert with LabelTooShort. Labels classified as governance-reserved revert with GovernanceReserved; a base stem held by another user reverts with NameReserved. On the cross-payer path the owner's recorded PoP tier must meet the label's required tier, so verified-payer-for-unverified-owner sponsorship is rejected with OwnerStatusInsufficient and the direct-path personhood guarantee carries over to sponsored registrations.

DotnsPopController

Dedicated controller for the Proof-of-Personhood gateway flow. Lives behind its own UUPS proxy with its own storage and is registered on the registrar via addController alongside the commit-reveal controller. Its gated entry points are callable only under a substrate Root origin, which the controller verifies itself by reading originIsRoot from the revive System precompile.

Today the Pop gateway does not write a standalone user-status mapping. It materialises the PoP flow through gateway-issued labels, PoP resolver records, and reservation queue state; user tier checks for public pricing still come from the personhood precompile/context read.

The first, reserveBaseName, mints a lite-person username to a user. The gateway-facing input is a stem.suffix shape: a single DNS label followed by exactly one dot and a digits-only suffix of exactly two digits (for example michal.03). The controller normalises that input by stripping the dot before classification, pricing, and minting, so the on-chain label is always flat (michal.03 becomes michal03). Inputs with more than one dot, no dot, a non-digit suffix, or a suffix length other than two digits are rejected at the boundary. The stem may be any DNS-valid label of at least six characters, not only the 6 to 8 of the public PopLite tier; only governance-reserved stems (five characters or fewer) are rejected. A lite username whose stem is nine characters or longer classifies as NoStatus for public pricing and transfers, so its lite status is an issuance property rather than an economic tier. The call also persists the user's chat key on the PoP resolver and optionally enqueues a reservation for a full-person base name the user intends to claim later.

The second, registerBaseName, mints a full-person username. Whether the call is a claim against a prior lite reservation or a fresh standalone registration is derived from on-chain reservation state; the caller does not choose. The link argument selects the chat-key source: inherit from a prior lite label, or accept a fresh one in the payload. When inheriting, the call also writes the liteLink (full => lite) and fullClaim (lite => full) records on the PoP resolver in the same transaction so downstream consumers can resolve either direction without scanning events.

Each base label carries a head/tail-indexed reservation queue with a capacity of MAX_RESERVATION_QUEUE and a governance-configurable reservationDuration. The queue head is mirrored into PopRules on every head transition (enqueue-from-empty, expiry-driven promotion, non-expiry head removal, claim-wipes-queue), so the public commit-reveal flow sees the same cross-flow lock through its existing PopRules price check. The gateway path is symmetric: registerBaseName consults the live PopRules slot before mint and rejects with NotHolder when another user holds the stem, so PopRules is the single cross-flow authority in both directions. registerBaseName additionally rejects lite-classified labels (those belong on reserveBaseName) and governance-reserved labels with InvalidBaseLabel. Expiry advancement is permissionless: anyone can call expireReservation to garbage-collect a stale head, which is what the pallet does on its own cadence.

Early testnet quirk: LabelStore deployment

Pop-gateway issuances mint the name and persist its label, but LabelStore deployment is deferred for users who have not yet interacted with the protocol from their own address. The current pallet-revive runtime does not let substrate Root deploy contracts on behalf of an account it does not control, so the per-user LabelStore cannot be created at the moment the gateway writes. The controller stamps a pending-claim entry instead, and settlement writes the label into the owner's store, deploying the store on the first write. Settlement is permissionless via settlePendingClaims: the owner settles their own store, or after the claim window anyone settles a given owner's entry and pays the cost. Settlement always writes the label rather than dropping the entry, so a pending name is never stranded. When the runtime supports root-origin contract deployment, the deferred path collapses to a no-op and the issuance flow becomes one transaction end-to-end. This is a runtime limitation, not a protocol design choice.

Operational consequence for transfers: the registrar derives the transfer-floor price by reading the label from the sender's LabelStore. A gateway-issued name whose pending claim is not yet settled has no readable label on the sender side, so _quoteTransferFee returns zero regardless of the recipient's tier. Until the name is settled into a LabelStore, a downward transfer (for example PopFull to NoStatus) does not charge the cross-tier friction it would otherwise owe. Clients that consume gateway-issued names should treat settlement as a prerequisite for accurate transfer-time pricing, not just for label discovery.

DotnsRegistrar

ERC721-backed registrar that mints ownership of label IDs (labelhashes). Minting is restricted to every address in the controllers mapping; the mapping is owner-gated through addController and removeController. Every other contract in the system that needs to check "is this address authorised to drive name state?" consults this mapping rather than keeping a parallel list, which is what lets multiple controllers coexist on the same registrar without per-contract configuration changes.

DotnsRegistry

Forward registry mapping node to (owner, resolver) and supporting subnode creation. When a base name is minted on the registrar, the matching controller wires the node to the new owner through this registry. Privileged node wiring defers to the same controllers mapping on the registrar, so both controllers can write without the registry tracking controllers of its own.

Subnames are created by the base-name owner. A subname carries its own (owner, resolver) and can in turn carry subnames, so the registry is the place the name hierarchy actually lives.

The registry exposes isAuthorised(node, account) as the canonical check for whether an address may manage a node: the stored owner for a subname, or the ERC-721 holder, a single-token approvee, or an operator-for-all on the registrar for a tokenised name. Sibling contracts consult this view so a single registrar-level approval delegates management across the protocol rather than each contract maintaining its own approval list.

PopRules

PoP-aware name classification and pricing. Classification reads the label's stem length (the character count after stripping the trailing digit suffix) and the trailing digit count itself, then maps to one of four tiers: NoStatus (stem of 9+ characters, open to anyone at the cost-model price, with zero or exactly two trailing digits permitted), PopLite (stem of 6-8 characters with exactly two trailing digits, gateway-issued to lite-verified users), PopFull (stem of 6-8 characters with no trailing digits, requires full-person verification), and Reserved (stem of 5 characters or fewer, governed by the protocol). Labels carrying one trailing digit or more than two trailing digits are rejected at the classifier. The classification determines the price and the eligibility gate the commit-reveal controller enforces.

Classification examples and failure modes

The classifier bands on the stem, not the total label length. The stem is the label after removing any trailing digits. The trailing digit count must be zero or exactly two; a one-digit suffix and suffixes longer than two digits are invalid before tier eligibility is considered. The price column gives the flat deposit for a registrable example; a rejected or reserved name has no price.

Tier assignment is read on every pricing call, not stored: PopRules queries the alias-accounts personhood precompile at DotnsConstants.PERSONHOOD with the dotns context (bytes32("dotns")), and translates the returned status byte into a PopStatus (0=NoStatus, 1=PopLite, 2=PopFull). Unknown tier bytes collapse to NoStatus, so a future precompile addition fails closed rather than silently being treated as a higher tier. There is no on-chain self-attestation; users obtain personhood off-chain through the People-chain ring proof and the alias-accounts pallet propagates the result via XCM.

Classification is not the same thing as effective holder context. A long label such as andrewsays is always a NoStatus-tier label by shape, but it may be held by a PopFull, PopLite, or NoStatus account. Consumers that need to know what rules apply to that live name should combine three reads: classify the label, query the registrar owner, then query the owner's dotns-context PoP status through the precompile or gateway-written state. The escrow position is the economic qualifier: if the token has an active release position with a non-zero amount, it came through the refundable NoStatus deposit path; if no such deposit exists, a verified holder can own the same long label without it being deposit-backed. In other words, andrewsays does not become a PopFull-tier label when a PopFull user owns it, but the owner can still be PopFull for transfer pricing, reverse resolution, and UI display.

Whitelisting is the exception path for users or organisations that need to register without satisfying the live PoP tier check. DotNS still does not accept self-attestation: the contracts only consume PoP status from the personhood precompile, and a user cannot set or prove their own status inside DotNS. Instead, the public registrar controller has an owner-managed whitelist for registerReserved, which bypasses the PoP pricing gate for approved addresses while still using the normal commit-reveal and availability checks.

To request a whitelist entry, open a Whitelist Request issue in this repository. The issue is labelled whitelist-request by the template and must include the address, address type, target network (Paseo V2 or Paseo Review), and a clear description of why the PoP bypass is needed. A maintainer can approve the request by applying whitelist-approved, after which the workflow checks account mapping on the selected network and executes the on-chain whitelist transaction. Whitelisting does not register a name, reserve a label, or bypass ownership rules; it only allows the approved address to use the reserved registration path without a PoP status.

For the operator-side mechanics, granting the whitelist-operator role, granting it to many operators, and whitelisting one or many addresses through the dotNS SDK CLI, the hosted app, or cast, see the Whitelisting section in DEPLOYMENTS.md.

PopRules also holds the cross-flow reservation table for base names. Two write paths share one mapping keyed by the bare stem. The first is used by the commit-reveal controller during a lite registration: it classifies the incoming label, strips the trailing digits, and writes the bare stem. The second is used by the PoP controller on every reservation-queue head transition: it takes a bare stem directly and rejects the update when the slot is held by a different user, so the caller's local queue bookkeeping never silently diverges from the PopRules state.

Two read paths, priceWithCheck and priceWithoutCheck, are what the public flow consults. Both strip trailing digits before looking up the reservation, so any live entry on a bare stem blocks registrations of any variant under that stem for the reservation window (12 weeks by default).

DotnsReverseResolver

Reverse records mapping an address to its primary name, with two write paths. The first, setReverseName, is the controller-only seeder: when a direct reserved registration lands and the registrant has no existing primary, the commit-reveal controller calls this entry point so a subsequent reserved registration does not silently overwrite the primary. Writes through this path are restricted to the addresses registered under CONTROLLER and REGISTRAR on the protocol registry. The second, claimReverseRecord, is the self-service path open to any current name owner: the caller hands in a label and the resolver checks that registrar.ownerOf(namehash(label)) equals the caller before overwriting their reverse entry. Past ownership is never sufficient; the registrar is the single source of truth for the gate.

Reads are open but fail-closed: nameOf(address) re-validates current ownership against the registrar before returning the stored name, so an address that has transferred their primary away resolves to the empty string until they claim a new name they currently hold. The protocol still best-effort clears reverse entries on transfer (cheaper reads, no behavioural change), but the security guarantee is the fail-closed read, not the eager clear.

DotnsContentResolver

Stores contenthash and text records per node. This is where external content links (for example IPFS hashes) and arbitrary key-value text records (for example social handles, verification metadata) live. Writes accept the node owner, any address the registry recognises as authorised for the node through isAuthorised (the ERC-721 holder, a single-token approvee, or an operator-for-all on the registrar), or an operator approved directly on this resolver; reads are open. The registry-recognised path lets a registrar-level name admin manage records without a separate grant, while the resolver-local operator is a narrower record-only delegation that confers no power over ownership or transfer. Authority is evaluated against the current owner on every write, so transferring the name reassigns write access automatically.

Choosing a delegation mechanism:

Revoke any grant with the inverse call (approve(address(0), tokenId) or setApprovalForAll(operator, false)). Because every write re-reads the current owner, a transfer drops all delegates the prior owner had set.

DotnsResolver

Stores forward-resolution address records per node. This is the conventional "name to address" lookup: a client has a .dot name and wants to know the Ethereum address behind it. Writes require node ownership; reads are open.

DotnsPopResolver

Per-node resolver for records produced by the Proof-of-Personhood flow. Three record kinds. The chat key is ECDH public-key bytes keyed by node; it is written by the PoP controller during a lite reservation and during any claim path that inherits from a prior lite entry, and is what gives verified users an on-chain discovery channel for end-to-end encrypted messaging. The lite link answers "which lite username did this full name claim from?" and is keyed by the full-person node. The full claim is the reverse direction: it answers "which full name did this lite user claim?" and is keyed by the lite labelhash. The forward and reverse links are written by the same call, so they stay in lockstep; downstream consumers that look up by lite username (Nova's pallet, for one) resolve the full name without scanning events.

Writer authorisation is dynamic: the PoP controller address is fetched from the protocol registry on every write. Rotating the PoP controller is a single set call on the protocol registry with no resolver upgrade required.

DotnsProtocolRegistry

On-chain lookup table mapping well-known bytes32 keys (declared in DotnsConstants) to contract addresses. Every DotNS contract resolves its siblings through this registry at runtime.

Without it, each contract would store direct addresses to every contract it calls. An upgrade that changes one address would require a separate owner transaction for every contract that references it. The protocol registry reduces this to one: update the key in the registry, and every caller picks up the new address on its next call. The indirection also means a governance-driven rotation of, say, the PoP controller does not break any consumer that has already been deployed.

The registered keys include REGISTRAR, CONTROLLER, REGISTRY, REVERSE_RESOLVER, RESOLVER, CONTENT_RESOLVER, POP_RULES, STORE_FACTORY, POP_CONTROLLER, POP_RESOLVER, NAME_ESCROW, and MULTICALL3.

Multicall3

Generic arbitrary-target batching helper using the standard Multicall3 interface. It is protocol infrastructure rather than a dotNS-specific authorisation surface: anyone can call it, and each target contract still enforces its own permissions.

For read batching, Multicall3 lets clients collect several results from the same block through one call. For write batching, callers must remember that target contracts observe Multicall3 as the caller, not the original externally owned account. That means public owner-gated dotNS writes should not be routed through Multicall3 unless the target flow explicitly supports that caller model.

StoreFactory, LabelStore, and UserStore

Stores are the per-user storage layer. They exist because two query paths the rest of the system needs are not answerable from anywhere else: "what names has this address ever held?" cannot be served by resolvers (keyed per-node) or the registry (live ownership only, no history), and "what user-controlled records does this address publish?" has nowhere on a resolver to live since the data is not bound to any one name. Each address gets at most one of each store, forever, and the factory is the single source of truth for which store belongs to which user.

LabelStore is the protocol-managed half. The registrar and the controller set write a label entry once and the slot is permanently locked. The invariant is labels only: every per-name record category (reverse, content, forward address, chat key, lite link) goes to a dedicated resolver, and the Store stays the durable per-owner registration ledger. Because entries are append-only, transferring a name writes a fresh entry on the recipient and leaves the sender's locked entry in place, so LabelStore doubles as the address's lifetime-of-ownership ledger while the registry continues to answer for live ownership.

UserStore is the user-claimed half. The bound owner is the only writer and prior values are snapshotted into a per-key history. It exists so that user-controlled records that do not belong to a name have a home that bills the user's own contract rather than polluting a shared resolver. The labels-only invariant is preserved by the split: nothing user-written ever lands on the protocol-managed side.

Deployments

Addresses are recorded per network in deployments/<network>/<chain-id>.json, and published with each release as deployments.json. See DEPLOYMENTS.md for how a deployment is run and RELEASE_ARTIFACTS.md for what a release contains.

Build and test

Builds and tests are run with Foundry. Fork tests use the local Paseo Asset Hub adapter described in DEPLOYMENTS.md; ordinary unit, fuzz, and invariant tests run against Foundry's in-process EVM.

Security

Before deploying it for real use cases, you are responsible for:

• Reviewing the code yourself, we publish a reference, not a hardened production build
• Checking that the dependencies are up to date and free of known vulnerabilities
• Securing your own fork or deployment environment (keys, secrets, network configuration)
• Tracking the latest tagged release/commits for security fixes; older releases are not backported (exceptions might apply)

For Parity's security disclosure process, and Bug Bounty program, feel free to visit: https://parity.io/bug-bounty

Known limitations

The protocol carries a handful of constraints worth knowing before deploying or building against it. Most stem from the current pallet-revive runtime rather than from protocol design, and collapse to a no-op once the runtime gains the corresponding capability. KNOWN_ISSUES.md is the consolidated reference; each issue is also described in full where the relevant contract is documented below.

• Deferred LabelStore deployment (runtime). See DotnsPopController.
• Transfer fee is zero until the store is settled (runtime). See DotnsPopController.
• No standalone user-status mapping (current implementation). See DotnsPopController.

License

Licensed under the MIT License. See LICENSE. External interface definitions under contracts/external/ retain their upstream licences (the SPDX header in each file is authoritative). Security policy and disclosure: see SECURITY.md.

Contents

• DotnsRoleManager
• IDotnsRoleManager

DotnsRoleManager

Git Source

Inherits: AccessControlUpgradeable, OwnableUpgradeable, IDotnsRoleManager

Title: Dotns Role Manager

Shared owner-administered role layer for DotNS contracts with operational roles.

Consuming contracts define their supported role set in @custom:function _isSupportedRole. The owner remains the only account that can grant or revoke roles; role holders receive only the operational permissions each consuming contract explicitly gates with

Notes:

• function: _checkRoleOrOwner.

• security-contact: admin@parity.io

Functions

_dotnsRoleManagerInit

Initialises the OpenZeppelin access-control state for consuming contracts.

Must be called during the consuming contract initialiser.

function _dotnsRoleManagerInit() internal onlyInitializing;

setRole

Grants or revokes an operational role.

Only the owner can manage roles (otherwise @custom:reverts OwnableUnauthorizedAccount); role must be one of the roles recognised by the consuming contract (otherwise

Note: reverts: UnsupportedRole); account must not be the zero address (otherwise

function setRole(bytes32 role, address account, bool enabled) external override onlyOwner;

Parameters

grantRole

Grants role to account. If account had not been already granted role, emits a {RoleGranted} event. Requirements:

• the caller must have role's admin role.

function grantRole(
    bytes32 role,
    address account
)
    public
    override(AccessControlUpgradeable, IAccessControl)
    onlyOwner;

revokeRole

Revokes role from account. If account had been granted role, emits a {RoleRevoked} event. Requirements:

• the caller must have role's admin role.

function revokeRole(
    bytes32 role,
    address account
)
    public
    override(AccessControlUpgradeable, IAccessControl)
    onlyOwner;

supportsInterface

function supportsInterface(bytes4 interfaceId)
    public
    view
    virtual
    override(AccessControlUpgradeable)
    returns (bool supported);

_checkRoleOrOwner

Reverts unless the caller is the owner or holds role.

Consuming contracts use this for operational paths where the owner keeps super-user access and role holders receive a narrower permission; any other caller is rejected with @custom:reverts NotRoleOrOwner.

function _checkRoleOrOwner(bytes32 role) internal view;

_setRole

Grants or revokes a supported role for account.

role must be recognised by the consuming contract (otherwise

Notes:

• reverts: UnsupportedRole) and account must be non-zero (otherwise

• reverts: InvalidRoleAccount). Delegates to OpenZeppelin's _grantRole or _revokeRole, which emit @custom:emits IAccessControl.RoleGranted on grant and

• emits: IAccessControl.RoleRevoked on revoke.

function _setRole(bytes32 role, address account, bool enabled) internal;

_isSupportedRole

Returns whether role is recognised by the consuming contract.

Implemented by each consuming contract so unsupported role identifiers fail closed.

function _isSupportedRole(bytes32 role) internal view virtual returns (bool supported);

IDotnsRoleManager

Git Source

Inherits: IAccessControl

Title: DotNS Role Manager

Shared owner-administered role API for DotNS contracts with operational roles.

Role identifiers are declared in DotnsConstants. Ownership remains the source of super-user authority: the owner grants and revokes supported roles, while role holders receive only the operational permissions each consuming contract recognises.

Note: security-contact: admin@parity.io

Functions

setRole

Grants or revokes an operational role.

Only the owner can manage roles (otherwise @custom:reverts OwnableUnauthorizedAccount); role must be one of the roles recognised by the consuming contract (otherwise

Notes:

• reverts: UnsupportedRole); account must not be the zero address (otherwise

• reverts: InvalidRoleAccount). Emits @custom:emits IAccessControl.RoleGranted on grant and @custom:emits IAccessControl.RoleRevoked on revoke.

function setRole(bytes32 role, address account, bool enabled) external;

Parameters

Errors

NotRoleOrOwner

Thrown when a caller is neither the contract owner nor a holder of role.

error NotRoleOrOwner(address caller, bytes32 role);

UnsupportedRole

Thrown when role management is attempted for a role the contract does not use.

error UnsupportedRole(bytes32 role);

InvalidRoleAccount

Thrown when role management is attempted for the zero address.

error InvalidRoleAccount(address account);

Contents

• Create3Factory

Create3Factory

Git Source

Title: Dotns CREATE3 Factory

Permissionless wrapper around Solady's audited CREATE3 library.

Anyone may call @custom:function deploy. CREATE3 addresses are a pure function of (factory_address, salt) — the caller never enters the derivation — so caller-gating would not strengthen address determinism. Salt-squatting griefing is in-scope for the caller, not the factory: salts in the DotNS namespace (CREATE3_SALT_NAMESPACE in BaseDeployer) get bumped end-to-end if a slot is ever found occupied. Keeping the factory permissionless removes the cross-chain ownership-coordination burden and lets CI keys, ops keys, and recovery flows all coexist without ownership transfers.

Note: security-contact: admin@parity.io

Functions

receive

Accepts native transfers so callers can pre-fund the factory if they want constructors that take msg.value.

The dotNS pipeline never forwards native value; this exists purely so the factory is compatible with payable-constructor callers from other consumers.

receive() external payable;

deploy

Deploys initCode at the deterministic address derived from salt.

Permissionless: any caller may invoke. The deployed address is CREATE3.predictDeterministicAddress(salt) and is independent of msg.sender. The call reverts if initCode is empty (@custom:reverts EmptyInitCode) or if the predicted slot is already occupied (Solady raises its own revert on collision). Emits

Note: emits: Deployed on success. Native value attached to the call is forwarded to the new contract's constructor.

function deploy(
    bytes32 salt,
    bytes calldata initCode
)
    external
    payable
    returns (address deployed);

Parameters

Returns

predict

Returns the address that @custom:function deploy would target for salt.

Pure projection of (factory_address, salt) — does not check whether the address is currently occupied. Callers that need occupancy info should follow up with an addr.code.length check.

function predict(bytes32 salt) external view returns (address predicted);

Parameters

Returns

Events

Deployed

Emitted on every successful CREATE3 deployment through this factory.

salt and deployed are indexed so consumers can filter by either. initCodeHash is published alongside the deployment so downstream tooling can pin codehash expectations against the on-chain artefact without re-fetching bytecode.

event Deployed(
    bytes32 indexed salt, address indexed deployed, bytes32 initCodeHash, uint256 value
);

Parameters

Errors

EmptyInitCode

Thrown when @custom:function deploy is called with an empty initCode blob.

CREATE3 with empty init code would deploy a zero-byte contract at the predicted address; the factory rejects the call early so callers fail fast on a malformed artefact lookup rather than land a useless deployment.

error EmptyInitCode();

Contents

• DotnsNameEscrow
• IDotnsNameEscrow

DotnsNameEscrow

Git Source

Inherits: Initializable, UUPSUpgradeable, OwnableUpgradeable, ReentrancyGuardTransient, ERC165Upgradeable, IERC721Receiver, IDotnsNameEscrow

Title: Dotns Name Escrow

Holds refundable deposits for registered names and manages the release/reclaim lifecycle. @custom:security-contact admin@parity.io

Constants

MAX_RELEASED_PAGE_SIZE

Maximum page size for releasedTokens pagination.

uint256 public constant MAX_RELEASED_PAGE_SIZE = 200

MAX_REFUND_PAGE_SIZE

Maximum page size for pendingRefunds pagination and batch claims.

uint256 public constant MAX_REFUND_PAGE_SIZE = 200

MAX_COOLDOWN

Upper bound on the configurable release-cooldown.

The cooldown gates only the release-to-withdraw delay, not the long-lived deposit lock and not the reclaim boundary (see redeemWindow), so it is intentionally kept short. Capping at one hour also keeps the cast to uint64 well below the saturation point at every plausible block timestamp.

uint256 public constant MAX_COOLDOWN = 1 hours

MAX_REDEEM_WINDOW

Upper bound on the configurable redeem window.

The redeem window is a different quantity from the cooldown: it is the period after release in which only the previous holder may act, and it gates reclaim rather than withdrawal. The bound limits how long policy can hold a released name out of circulation, and keeps the cast to uint64 in release well below saturation.

uint256 public constant MAX_REDEEM_WINDOW = 30 days

MIN_REDEEM_WINDOW

Lower bound on the configurable redeem window.

A window short enough to elapse before its holder can plausibly notice the release offers no protection at all, and one of zero length turns every release into an immediate hand-off to whoever is watching. The floor keeps the window long enough to span a holder being asleep or away for a day, so the guarantee survives any setting the owner is able to choose.

uint256 public constant MIN_REDEEM_WINDOW = 1 days

State Variables

protocolRegistry

The protocol registry for resolving sibling contract addresses.

IDotnsProtocolRegistry public protocolRegistry

cooldown

Delay after release before the deposit withdrawal may be credited.

Forces a delay between release and withdraw. It does not bound reclaim: the release-to-reclaim boundary is redeemWindow, a separate and longer quantity. Also supplies the per-entry clock for time-locked refund credits, which is why raising it would slow every refund path and not just the deposit one.

uint256 public cooldown

tokenReserved

Total amount of a specific asset reserved across all positions.

Keyed by asset so future ERC20 support can track per-token liabilities independently; address(0) represents the native token and is the only asset currently accepted.

mapping(address asset => uint256 amount) public tokenReserved

_positions

Per-token escrow position storing recipient, amount, lifecycle flags and cooldown.

mapping(uint256 tokenId => ReleasePosition position) private _positions

_releasedTokens

Ordered set of tokens currently in escrow custody, used for paginated enumeration.

uint256[] private _releasedTokens

_releasedIndexPlusOne

Reverse lookup into _releasedTokens (one-based) for O(1) remove-by-swap.

mapping(uint256 tokenId => uint256 indexPlusOne) private _releasedIndexPlusOne

protocolFees

Cumulative balance of non-refundable protocol fees; only accumulates.

Credited by cross-paid registration fees and transfer fees. Never debited: protocol fees do not back refunds, which draw solely on the per-asset reserve.

uint256 public protocolFees

_pendingWithdrawals

Pull-payment ledger storing each recipient's claimable refund balance.

Per-recipient isolation ensures a failing or reentrant receiver cannot block other users' withdrawals. Used as the fallback path for registration overpayments whose direct push back to msg.sender failed (because the caller is a contract that rejects incoming value).

mapping(address recipient => uint256 amount) private _pendingWithdrawals

_refundEntries

Time-locked refund ledger keyed by entryId.

Every credit allocates a fresh entryId so per-entry cooldowns are independent and drip-feed credits cannot reset an existing entry's clock.

mapping(uint256 entryId => RefundEntry entry) private _refundEntries

_entriesByRecipient

Per-recipient list of pending entryIds for paginated enumeration and batch claim.

mapping(address recipient => uint256[] entryIds) private _entriesByRecipient

_entryIndexPlusOne

Reverse lookup into _entriesByRecipient (one-based) for O(1) remove-by-swap.

mapping(uint256 entryId => uint256 indexPlusOne) private _entryIndexPlusOne

_nextEntryId

Monotonic counter assigning entryIds to new refund credits.

uint256 private _nextEntryId

redeemWindow

Period after release during which only the previous holder may act.

Distinct from cooldown. Inside this window the holder may redeem the name back and nobody else may take it (available reports false); once it elapses reclaim becomes permissionless and any unwithdrawn deposit is credited to the recipient rather than stranded. Appended after the pre-existing variables and paid for out of __gap, so the layout of everything above is untouched.

uint256 public redeemWindow

__gap

Reserved storage space to allow for layout changes in the future. A new variable appended above must shrink this array by the same number of slots so the contract's total storage footprint stays fixed.

uint256[49] private __gap

Functions

onlyController

Restricts calls to the configured registrar controller.

modifier onlyController() ;

onlyRegistrar

Restricts calls to the configured registrar from the protocol registry.

modifier onlyRegistrar() ;

constructor

Note: oz-upgrades-unsafe-allow: constructor

constructor() ;

initialize

Initialises the name escrow.

Runs once behind the proxy; subsequent calls trigger @custom:reverts InvalidInitialization via the initializer modifier. registry must be non-zero, otherwise @custom:reverts InvalidAsset; cooldownSeconds is forwarded to

Note: function: updateCooldown, which rejects a zero value (@custom:reverts InvalidCooldown) and any value above @custom:constant MAX_COOLDOWN (@custom:reverts CooldownTooLong), and emits @custom:emits CooldownUpdated as part of seeding the initial cooldown. redeemWindowSeconds is forwarded to @custom:function updateRedeemWindow, which rejects any value below @custom:constant MIN_REDEEM_WINDOW (@custom:reverts RedeemWindowTooShort) or above @custom:constant MAX_REDEEM_WINDOW (@custom:reverts RedeemWindowTooLong), and emits @custom:emits RedeemWindowUpdated.

function initialize(
    IDotnsProtocolRegistry registry,
    uint256 cooldownSeconds,
    uint256 redeemWindowSeconds
)
    external
    initializer;

Parameters

updateCooldown

Updates the cooldown duration for future releases.

Owner-only. Affects only releases recorded after this call; positions already released keep the withdrawAvailableAt snapshot taken at their release time. newCooldown must be non-zero, otherwise @custom:reverts InvalidCooldown, and must not exceed the contract's MAX_COOLDOWN upper bound, otherwise @custom:reverts CooldownTooLong; the bound keeps the release-to-reclaim window short and protects the uint64 cast in release from truncation. Emits @custom:emits CooldownUpdated with the prior and new values.

function updateCooldown(uint256 newCooldown) public override onlyOwner;

updateRedeemWindow

Updates the redeem window for future releases.

Owner-only. Affects only releases recorded after this call; positions already released keep the redeemableUntil snapshot taken at their release time. newRedeemWindow must fall within MIN_REDEEM_WINDOW and MAX_REDEEM_WINDOW inclusive, otherwise

Note: reverts: RedeemWindowTooShort or @custom:reverts RedeemWindowTooLong. The floor keeps the window long enough to be worth having, so no setting the owner can choose leaves a holder without a usable chance to recover an accidental release; the ceiling limits how long a released name can be held out of circulation and protects the uint64 cast in release from truncation. Emits @custom:emits RedeemWindowUpdated with the prior and new values. This is also the post-upgrade seeding hook: pair it with upgradeToAndCall so an upgraded proxy never runs with an unseeded window.

function updateRedeemWindow(uint256 newRedeemWindow) public override onlyOwner;

getReleasePosition

Returns the escrow state for a token.

function getReleasePosition(uint256 tokenId)
    external
    view
    override
    returns (ReleasePosition memory position);

releasedTokenCount

Returns the number of tokens currently held by escrow pending reclaim or withdrawal.

function releasedTokenCount() external view override returns (uint256 count);

Returns

reserves

Returns total amount of assets liabilities reserved for withdrawals.

function reserves(address asset) external view returns (uint256 amount);

Parameters

releasedTokens

Returns a bounded paginated slice of released token identifiers.

limit must be non-zero and at most MAX_RELEASED_PAGE_SIZE, otherwise

Note: reverts: InvalidPageSize.

function releasedTokens(
    uint256 start,
    uint256 limit
)
    external
    view
    override
    returns (uint256[] memory tokenIds);

Parameters

deposit

Records an asset deposit position for a token.

Only the configured controller may call this, otherwise @custom:reverts NotController. params.amount must equal msg.value, otherwise @custom:reverts InvalidAmount; a zero amount is accepted so cross-payer and free-tier registrations can still seed a position that the release lifecycle can advance. Only native deposits are accepted today, so a non-zero params.asset triggers @custom:reverts AssetNotSupported, and a zero params.recipient triggers @custom:reverts InvalidRecipient. The slot for params.tokenId must be empty (sentinel: position.recipient == address(0)): a previously funded position triggers @custom:reverts PositionAlreadyFunded, and a position already in the released phase triggers @custom:reverts AlreadyReleased. Emits @custom:emits NativeDepositRecorded once the deposit is booked.

function deposit(DepositParams calldata params) external payable override onlyController;

creditOverpayment

Credits msg.value to recipient's pull-payment ledger so the caller can later pull the balance with @custom:func claimWithdrawal.

Only the configured controller may call this, otherwise @custom:reverts NotController. recipient must be non-zero (@custom:reverts InvalidRecipient) and msg.value must be non-zero (@custom:reverts InvalidAmount). Used by the registrar controller to refund overpayment without pushing native value into a potentially reverting contract receiver. Emits @custom:emits OverpaymentRefunded once the credit lands.

function creditOverpayment(address recipient) external payable override onlyController;

Parameters

depositProtocolFee

Records a cross-paid registration fee into the protocol fee pot.

Only the configured controller may call this, otherwise @custom:reverts NotController. msg.value must be non-zero, otherwise @custom:reverts InvalidAmount. Emits

Note: emits: CrossTierFeePaid with isRegistration = true once the fee is booked.

function depositProtocolFee(ProtocolFeeDepositParams calldata params)
    external
    payable
    override
    onlyController;

chargeTransferFee

Charges the transfer fee and rebinds the token's escrow position to the new holder.

Only the configured registrar may call this, otherwise @custom:reverts NotRegistrar. When a fee is owed, the attached value must cover it or @custom:reverts InsufficientValue. Whenever a position exists for the token and the NFT is leaving its prior recipient, the position recipient is rebound to the new holder so the deposit (when funded) and the lifecycle marker (when zero-amount) both follow the NFT. The escrow does not refund anyone at transfer time; the only path back to the locked deposit is for the current holder to release into escrow and wait the cooldown. Emits @custom:emits CrossTierFeePaid (non-registration) when a non-zero fee is credited to the protocol fee pot, and credits any surplus value to the payer on the time-locked refund ledger via @custom:emits RefundCredited.

function chargeTransferFee(ChargeTransferFeeParams calldata params)
    external
    payable
    override
    onlyRegistrar
    returns (uint256 charged);

Returns

release

Releases a token into escrow and starts the withdrawal cooldown.

First step of the phased lifecycle. The caller must be the current NFT holder and the current position recipient (the field is rebound to the holder on every transfer that moves the name off the prior recipient), otherwise @custom:reverts NotRefundRecipient. Approved operators cannot release on behalf of the holder because the recipient field is keyed to the holder, not to any approval set, which keeps the deposit refund tied to the on-chain owner. The slot for tokenId must already hold a position (sentinel: position.recipient != address(0)); an unseeded slot triggers @custom:reverts DepositNotConfigured, and a position already in the released phase triggers

Note: reverts: AlreadyReleased. Zero-amount positions are still releasable so every minted name has a reachable lifecycle. The escrow must additionally be approved to move the NFT, otherwise @custom:reverts EscrowNotApproved. Emits @custom:emits NameReleased once the NFT is moved into custody. Release stamps two independent clocks. withdrawAvailableAt (release + cooldown) opens the deposit withdrawal; redeemableUntil (release + redeemWindow) closes the holder's exclusive redeem phase and opens permissionless reclaim. Both are snapshots so later policy changes never move an in-flight position. A release attempted while redeemWindow is unseeded triggers @custom:reverts RedeemWindowNotConfigured.

function release(uint256 tokenId) external override nonReentrant;

withdraw

Credits the refundable deposit for a released token to the recipient's pending balance.

Second step of the phased lifecycle. The position must already be released (@custom:reverts NotReleased otherwise) and not yet claimed (@custom:reverts AlreadyClaimed on re-entry). Only the current position recipient (the address that released the name, which mirrored the NFT holder at that moment) may call this, otherwise @custom:reverts NotRefundRecipient, and block.timestamp must have reached withdrawAvailableAt, otherwise @custom:reverts WithdrawalTooEarly. Refunds are backed entirely by the per-asset tokenReserved pool; if that reserve is short,

Note: reverts: InsufficientFunds. Protocol fees never back a refund. Funds are not transferred here, only credited to the pull-payment ledger. Emits @custom:emits RefundWithdrawn once the credit lands.

function withdraw(uint256 tokenId) external override nonReentrant;

_settleDeposit

Moves a position's outstanding deposit onto the recipient's pull-payment balance.

Shared by @custom:function withdraw, where the recipient pulls the deposit themselves, and by @custom:function reclaim, where a third party takes the name and the deposit is settled on the departing holder's behalf. Both credit the same ledger and neither transfers value, so the accounting is identical and lives here once. The per-asset tokenReserved pool backs the refund in full, and @custom:reverts InsufficientFunds when it cannot cover the amount owed. Emits @custom:emits RefundWithdrawn. A zero-amount position is a no-op: it writes nothing and emits nothing, which keeps the free-registration lifecycle free of meaningless ledger entries and events.

function _settleDeposit(
    ReleasePosition storage position,
    uint256 tokenId,
    address recipient
)
    private;

Parameters

claimWithdrawal

Pulls the caller's accumulated pending refund balance.

Final step of the phased lifecycle. Pull-payment isolation: each recipient owns an independent ledger entry, so a failing or reentrant receiver cannot block other users' withdrawals. The caller must have a positive pending balance, otherwise

Note: reverts: NoPendingWithdrawal; a failing native transfer triggers

function claimWithdrawal() external override nonReentrant returns (uint256 amount);

Returns

pendingWithdrawal

Returns the pending refund balance owed to recipient.

function pendingWithdrawal(address recipient) external view override returns (uint256 amount);

Returns

claimRefund

Pulls a single time-locked refund entry.

Caller must be the entry's recipient (@custom:reverts NotRefundRecipient otherwise), the entry must exist (@custom:reverts NoSuchRefundEntry on a deleted or unknown id), and block.timestamp must have reached availableAt (@custom:reverts RefundLocked otherwise). The entry is deleted before the transfer; a failing native transfer triggers @custom:reverts RefundFailed. Emits @custom:emits RefundClaimed.

function claimRefund(uint256 entryId) external override nonReentrant returns (uint256 amount);

Parameters

Returns

claimRefundsBatch

Pulls multiple time-locked refund entries in one call.

Atomic: any invalid entry in the batch (wrong recipient, missing, or locked) reverts the entire call. The batch size is bounded by MAX_REFUND_PAGE_SIZE (@custom:reverts InvalidPageSize otherwise). Aggregates the per-entry amounts and transfers once; on transfer failure @custom:reverts RefundFailed. Emits

Note: emits: RefundClaimed once per entry.

function claimRefundsBatch(uint256[] calldata entryIds)
    external
    override
    nonReentrant
    returns (uint256 totalAmount);

Parameters

Returns

pendingRefundCount

Returns the number of pending refund entries owed to recipient.

function pendingRefundCount(address recipient) external view override returns (uint256 count);

pendingRefundIds

Returns up to limit pending refund entry ids for recipient, starting at offset.

Limit must be in (0, MAX_REFUND_PAGE_SIZE], otherwise @custom:reverts InvalidPageSize.

function pendingRefundIds(
    address recipient,
    uint256 offset,
    uint256 limit
)
    external
    view
    override
    returns (uint256[] memory entryIds);

pendingRefunds

Returns up to limit pending refund entries for recipient, paired with their entry ids.

Limit must be in (0, MAX_REFUND_PAGE_SIZE], otherwise @custom:reverts InvalidPageSize.

function pendingRefunds(
    address recipient,
    uint256 offset,
    uint256 limit
)
    external
    view
    override
    returns (uint256[] memory entryIds, RefundEntry[] memory entries);

refundEntry

Returns a single refund entry by id, or a zero-filled struct if the id is unknown.

function refundEntry(uint256 entryId)
    external
    view
    override
    returns (RefundEntry memory entry);

_creditRefund

Internal helper: allocate a new entryId and credit a refund to recipient.

Assigns the next monotonic entryId, stores the entry, appends to the recipient's enumeration array, and emits @custom:emits RefundCredited. The cooldown is read from the configured cooldown storage value; @custom:constant MAX_COOLDOWN bounds it so the cast to uint64 cannot truncate for any plausible block timestamp.

function _creditRefund(
    address recipient,
    uint256 amount,
    uint256 tokenId
)
    internal
    returns (uint256 entryId);

_removeRefundEntry

Internal helper: delete a refund entry and swap-pop its slot in the recipient's enumeration array.

function _removeRefundEntry(uint256 entryId, address recipient) internal;

reclaim

Transfers a released token whose redeem window has elapsed to a new owner.

Hands the NFT back to the controller for re-registration. Only the configured controller may call this, otherwise @custom:reverts NotController, and the position must be released with redeemableUntil reached, otherwise @custom:reverts NotReclaimable. Emits @custom:emits NameReclaimed once custody is transferred. Reclaim does not require the deposit to have been withdrawn first. If the position still holds value, this call settles it: the amount is debited from tokenReserved (@custom:reverts InsufficientFunds if the reserve is short) and credited to the previous recipient's pull-payment balance, claimable through @custom:function claimWithdrawal with no deadline. That is what keeps a name recyclable when its previous holder never returns: the value follows them, the name does not wait for them. Emits @custom:emits RefundWithdrawn on settlement.

function reclaim(
    uint256 tokenId,
    address newOwner
)
    external
    override
    onlyController
    nonReentrant;

Parameters

isReclaimable

Returns whether a token may currently be reclaimed out of escrow custody.

public rather than external so reclaim can gate on it without a self-call, which is what keeps the condition in one place instead of two.

function isReclaimable(uint256 tokenId) public view override returns (bool reclaimable);

Returns

redeem

Returns a released token to its previous holder during the redeem window.

The undo for an accidental release, and the reason the redeem window exists. Only the position recipient may call this (@custom:reverts NotRefundRecipient otherwise), the position must be released and not yet withdrawn, and block.timestamp must still be below redeemableUntil; a position failing any of those is not redeemable and

Note: reverts: NotRedeemable. No value moves. The position keeps its recipient, asset and amount, so the deposit stays locked exactly as it was before the release and the name returns to its pre-release state, releasable again later on a fresh pair of clocks. Excluding withdrawn positions is deliberate: a holder who has already pulled the deposit would otherwise recover the name without it being deposit-backed, breaking the one-deposit- per-live-name bound. The choice is therefore exclusive — take the value back, or take the name back. Emits @custom:emits NameRedeemed once custody returns.

function redeem(uint256 tokenId) external override nonReentrant;

onERC721Received

Whenever an {IERC721} tokenId token is transferred to this contract via {IERC721-safeTransferFrom} by operator from from, this function is called. It must return its Solidity selector to confirm the token transfer. If any other value is returned or the interface is not implemented by the recipient, the transfer will be reverted. The selector can be obtained in Solidity with IERC721Receiver.onERC721Received.selector.

function onERC721Received(
    address,
    address,
    uint256 tokenId,
    bytes calldata
)
    external
    view
    override
    returns (bytes4 selector);

supportsInterface

function supportsInterface(bytes4 interfaceId) public view override returns (bool supported);

version

Returns implementation version.

function version() external pure virtual returns (string memory versionString);

Returns

_registrar

Returns the configured registrar from the protocol registry.

function _registrar() internal view returns (IDotnsRegistrar registrar);

_onlyController

Restricts calls to the configured controller from the protocol registry.

function _onlyController() internal view;

_onlyRegistrar

Restricts calls to the configured registrar from the protocol registry.

function _onlyRegistrar() internal view;

_addReleasedToken

Adds a token to the released-token set if absent.

function _addReleasedToken(uint256 tokenId) internal;

_removeReleasedToken

Removes a token from the released-token set if present.

function _removeReleasedToken(uint256 tokenId) internal;

_authorizeUpgrade

Function that should revert when msg.sender is not authorized to upgrade the contract. Called by {upgradeToAndCall}. Normally, this function will use an xref:access.adoc[access control] modifier such as {Ownable-onlyOwner}.

function _authorizeUpgrade(address) internal onlyOwner {}

function _authorizeUpgrade(address newImplementation) internal override onlyOwner;

IDotnsNameEscrow

Git Source

Title: Dotns Name Escrow Interface

Escrows refundable deposits for registered names and manages the release lifecycle.

Note: security-contact: admin@parity.io

Functions

reserves

Returns total amount of assets liabilities reserved for withdrawals.

function reserves(address asset) external view returns (uint256 amount);

Parameters

getReleasePosition

Returns the escrow state for a token.

function getReleasePosition(uint256 tokenId)
    external
    view
    returns (ReleasePosition memory position);

releasedTokenCount

Returns the number of tokens currently held by escrow pending reclaim or withdrawal.

function releasedTokenCount() external view returns (uint256 count);

Returns

releasedTokens

Returns a bounded paginated slice of released token identifiers.

limit must be non-zero and at most MAX_RELEASED_PAGE_SIZE, otherwise

Note: reverts: InvalidPageSize.

function releasedTokens(
    uint256 start,
    uint256 limit
)
    external
    view
    returns (uint256[] memory tokenIds);

Parameters

deposit

Records an asset deposit position for a token.

Only the configured controller may call this, otherwise @custom:reverts NotController. params.amount must equal msg.value, otherwise @custom:reverts InvalidAmount; a zero amount is accepted so cross-payer and free-tier registrations can still seed a position that the release lifecycle can advance. Only native deposits are accepted today, so a non-zero params.asset triggers @custom:reverts AssetNotSupported, and a zero params.recipient triggers @custom:reverts InvalidRecipient. The slot for params.tokenId must be empty (sentinel: position.recipient == address(0)): a previously funded position triggers @custom:reverts PositionAlreadyFunded, and a position already in the released phase triggers @custom:reverts AlreadyReleased. Emits @custom:emits NativeDepositRecorded once the deposit is booked.

function deposit(DepositParams calldata params) external payable;

depositProtocolFee

Records a cross-paid registration fee into the protocol fee pot.

Only the configured controller may call this, otherwise @custom:reverts NotController. msg.value must be non-zero, otherwise @custom:reverts InvalidAmount. Emits

Note: emits: CrossTierFeePaid with isRegistration = true once the fee is booked.

function depositProtocolFee(ProtocolFeeDepositParams calldata params) external payable;

creditOverpayment

Credits msg.value to recipient's pull-payment ledger so the caller can later pull the balance with @custom:func claimWithdrawal.

Only the configured controller may call this, otherwise @custom:reverts NotController. recipient must be non-zero (@custom:reverts InvalidRecipient) and msg.value must be non-zero (@custom:reverts InvalidAmount). Used by the registrar controller to refund overpayment without pushing native value into a potentially reverting contract receiver. Emits @custom:emits OverpaymentRefunded once the credit lands.

function creditOverpayment(address recipient) external payable;

Parameters

chargeTransferFee

Charges the transfer fee and rebinds the token's escrow position to the new holder.

Only the configured registrar may call this, otherwise @custom:reverts NotRegistrar. When a fee is owed, the attached value must cover it or @custom:reverts InsufficientValue. Whenever a position exists for the token and the NFT is leaving its prior recipient, the position recipient is rebound to the new holder so the deposit (when funded) and the lifecycle marker (when zero-amount) both follow the NFT. The escrow does not refund anyone at transfer time; the only path back to the locked deposit is for the current holder to release into escrow and wait the cooldown. Emits @custom:emits CrossTierFeePaid (non-registration) when a non-zero fee is credited to the protocol fee pot, and credits any surplus value to the payer on the time-locked refund ledger via @custom:emits RefundCredited.

function chargeTransferFee(ChargeTransferFeeParams calldata params)
    external
    payable
    returns (uint256 charged);

Returns

protocolFees

Returns the cumulative protocol fee balance, non-refundable and accumulating.

function protocolFees() external view returns (uint256 balance);

Returns

release

Releases a token into escrow and starts the withdrawal cooldown.

First step of the phased lifecycle. The caller must be the current NFT holder and the current position recipient (the field is rebound to the holder on every transfer that moves the name off the prior recipient), otherwise @custom:reverts NotRefundRecipient. Approved operators cannot release on behalf of the holder because the recipient field is keyed to the holder, not to any approval set, which keeps the deposit refund tied to the on-chain owner. The slot for tokenId must already hold a position (sentinel: position.recipient != address(0)); an unseeded slot triggers @custom:reverts DepositNotConfigured, and a position already in the released phase triggers

Note: reverts: AlreadyReleased. Zero-amount positions are still releasable so every minted name has a reachable lifecycle. The escrow must additionally be approved to move the NFT, otherwise @custom:reverts EscrowNotApproved. Emits @custom:emits NameReleased once the NFT is moved into custody. Release stamps two independent clocks. withdrawAvailableAt (release + cooldown) opens the deposit withdrawal; redeemableUntil (release + redeemWindow) closes the holder's exclusive redeem phase and opens permissionless reclaim. Both are snapshots so later policy changes never move an in-flight position. A release attempted while redeemWindow is unseeded triggers @custom:reverts RedeemWindowNotConfigured.

function release(uint256 tokenId) external;

withdraw

Credits the refundable deposit for a released token to the recipient's pending balance.

Second step of the phased lifecycle. The position must already be released (@custom:reverts NotReleased otherwise) and not yet claimed (@custom:reverts AlreadyClaimed on re-entry). Only the current position recipient (the address that released the name, which mirrored the NFT holder at that moment) may call this, otherwise @custom:reverts NotRefundRecipient, and block.timestamp must have reached withdrawAvailableAt, otherwise @custom:reverts WithdrawalTooEarly. Refunds are backed entirely by the per-asset tokenReserved pool; if that reserve is short,

Note: reverts: InsufficientFunds. Protocol fees never back a refund. Funds are not transferred here, only credited to the pull-payment ledger. Emits @custom:emits RefundWithdrawn once the credit lands.

function withdraw(uint256 tokenId) external;

claimWithdrawal

Pulls the caller's accumulated pending refund balance.

Final step of the phased lifecycle. Pull-payment isolation: each recipient owns an independent ledger entry, so a failing or reentrant receiver cannot block other users' withdrawals. The caller must have a positive pending balance, otherwise

Notes:

• reverts: NoPendingWithdrawal; a failing native transfer triggers

• reverts: RefundFailed. Emits @custom:emits WithdrawalClaimed once the transfer succeeds.

function claimWithdrawal() external returns (uint256 amount);

Returns

pendingWithdrawal

Returns the pending refund balance owed to recipient.

function pendingWithdrawal(address recipient) external view returns (uint256 amount);

Returns

reclaim

Transfers a released token whose redeem window has elapsed to a new owner.

Hands the NFT back to the controller for re-registration. Only the configured controller may call this, otherwise @custom:reverts NotController, and the position must be released with redeemableUntil reached, otherwise @custom:reverts NotReclaimable. Emits @custom:emits NameReclaimed once custody is transferred. Reclaim does not require the deposit to have been withdrawn first. If the position still holds value, this call settles it: the amount is debited from tokenReserved (@custom:reverts InsufficientFunds if the reserve is short) and credited to the previous recipient's pull-payment balance, claimable through @custom:function claimWithdrawal with no deadline. That is what keeps a name recyclable when its previous holder never returns: the value follows them, the name does not wait for them. Emits @custom:emits RefundWithdrawn on settlement.

function reclaim(uint256 tokenId, address newOwner) external;

Parameters

isReclaimable

Returns whether a token may currently be reclaimed out of escrow custody.

True once the position is released and its redeem window has elapsed. Whether the deposit was ever withdrawn makes no difference: @custom:function reclaim settles any outstanding amount as part of the transfer. Both @custom:function reclaim and @custom:function IDotnsRegistrar.available derive their answer from isReclaimable, so a name is advertised as registrable exactly when registering it would succeed. Consumers should call isReclaimable rather than rebuilding the condition from @custom:function getReleasePosition.

function isReclaimable(uint256 tokenId) external view returns (bool reclaimable);

Returns

redeem

Returns a released token to its previous holder during the redeem window.

The undo for an accidental release, and the reason the redeem window exists. Only the position recipient may call this (@custom:reverts NotRefundRecipient otherwise), the position must be released and not yet withdrawn, and block.timestamp must still be below redeemableUntil; a position failing any of those is not redeemable and

Note: reverts: NotRedeemable. No value moves. The position keeps its recipient, asset and amount, so the deposit stays locked exactly as it was before the release and the name returns to its pre-release state, releasable again later on a fresh pair of clocks. Excluding withdrawn positions is deliberate: a holder who has already pulled the deposit would otherwise recover the name without it being deposit-backed, breaking the one-deposit- per-live-name bound. The choice is therefore exclusive — take the value back, or take the name back. Emits @custom:emits NameRedeemed once custody returns.

function redeem(uint256 tokenId) external;

updateCooldown

Updates the cooldown duration for future releases.

Owner-only. Affects only releases recorded after this call; positions already released keep the withdrawAvailableAt snapshot taken at their release time. newCooldown must be non-zero, otherwise @custom:reverts InvalidCooldown, and must not exceed the contract's MAX_COOLDOWN upper bound, otherwise @custom:reverts CooldownTooLong; the bound keeps the release-to-reclaim window short and protects the uint64 cast in release from truncation. Emits @custom:emits CooldownUpdated with the prior and new values.

function updateCooldown(uint256 newCooldown) external;

updateRedeemWindow

Updates the redeem window for future releases.

Owner-only. Affects only releases recorded after this call; positions already released keep the redeemableUntil snapshot taken at their release time. newRedeemWindow must fall within MIN_REDEEM_WINDOW and MAX_REDEEM_WINDOW inclusive, otherwise

Note: reverts: RedeemWindowTooShort or @custom:reverts RedeemWindowTooLong. The floor keeps the window long enough to be worth having, so no setting the owner can choose leaves a holder without a usable chance to recover an accidental release; the ceiling limits how long a released name can be held out of circulation and protects the uint64 cast in release from truncation. Emits @custom:emits RedeemWindowUpdated with the prior and new values. This is also the post-upgrade seeding hook: pair it with upgradeToAndCall so an upgraded proxy never runs with an unseeded window.

function updateRedeemWindow(uint256 newRedeemWindow) external;

cooldown

Delay after release before the deposit withdrawal may be credited.

function cooldown() external view returns (uint256 duration);

Returns

redeemWindow

Period after release during which only the previous holder may act.

function redeemWindow() external view returns (uint256 duration);

Returns

claimRefund

Pulls a single time-locked refund entry.

Caller must be the entry's recipient (@custom:reverts NotRefundRecipient otherwise), the entry must exist (@custom:reverts NoSuchRefundEntry on a deleted or unknown id), and block.timestamp must have reached availableAt (@custom:reverts RefundLocked otherwise). The entry is deleted before the transfer; a failing native transfer triggers @custom:reverts RefundFailed. Emits @custom:emits RefundClaimed.

function claimRefund(uint256 entryId) external returns (uint256 amount);

Parameters

Returns

claimRefundsBatch

Pulls multiple time-locked refund entries in one call.

Atomic: any invalid entry in the batch (wrong recipient, missing, or locked) reverts the entire call. The batch size is bounded by MAX_REFUND_PAGE_SIZE (@custom:reverts InvalidPageSize otherwise). Aggregates the per-entry amounts and transfers once; on transfer failure @custom:reverts RefundFailed. Emits

Note: emits: RefundClaimed once per entry.

function claimRefundsBatch(uint256[] calldata entryIds) external returns (uint256 totalAmount);

Parameters

Returns

pendingRefundCount

Returns the number of pending refund entries owed to recipient.

function pendingRefundCount(address recipient) external view returns (uint256 count);

pendingRefundIds

Returns up to limit pending refund entry ids for recipient, starting at offset.

Limit must be in (0, MAX_REFUND_PAGE_SIZE], otherwise @custom:reverts InvalidPageSize.

function pendingRefundIds(
    address recipient,
    uint256 offset,
    uint256 limit
)
    external
    view
    returns (uint256[] memory entryIds);

pendingRefunds

Returns up to limit pending refund entries for recipient, paired with their entry ids.

Limit must be in (0, MAX_REFUND_PAGE_SIZE], otherwise @custom:reverts InvalidPageSize.

function pendingRefunds(
    address recipient,
    uint256 offset,
    uint256 limit
)
    external
    view
    returns (uint256[] memory entryIds, RefundEntry[] memory entries);

refundEntry

Returns a single refund entry by id, or a zero-filled struct if the id is unknown.

function refundEntry(uint256 entryId) external view returns (RefundEntry memory entry);

Events

NativeDepositRecorded

Emitted when a native-token deposit is recorded.

event NativeDepositRecorded(uint256 indexed tokenId, uint256 amount);

NameReleased

Emitted when a token is released into escrow.

event NameReleased(
    uint256 indexed tokenId,
    address indexed recipient,
    address indexed asset,
    uint256 amount,
    uint256 withdrawAvailableAt,
    uint256 redeemableUntil
);

Parameters

RefundWithdrawn

Emitted when a refund is credited to the recipient's pending balance.

event RefundWithdrawn(
    uint256 indexed tokenId, address indexed recipient, address indexed asset, uint256 amount
);

Parameters

WithdrawalClaimed

Emitted when a recipient pulls their accumulated pending refund balance.

event WithdrawalClaimed(address indexed recipient, uint256 amount);

RefundCredited

Emitted when a refund is credited to the time-locked refund ledger.

event RefundCredited(
    address indexed recipient,
    uint256 indexed entryId,
    uint256 amount,
    uint64 availableAt,
    uint256 indexed tokenId
);

Parameters

RefundClaimed

Emitted when a recipient claims a single refund entry.

event RefundClaimed(address indexed recipient, uint256 indexed entryId, uint256 amount);

Parameters

NameReclaimed

Emitted when a released token is reclaimed by a new owner via registration.

event NameReclaimed(
    uint256 indexed tokenId, address indexed previousRecipient, address indexed newOwner
);

Parameters

CooldownUpdated

Emitted when the cooldown duration for future releases is updated.

event CooldownUpdated(uint256 indexed currentCooldown, uint256 indexed newCooldown);

RedeemWindowUpdated

Emitted when the redeem window for future releases is updated.

event RedeemWindowUpdated(uint256 indexed currentRedeemWindow, uint256 indexed newRedeemWindow);

NameRedeemed

Emitted when a released token is redeemed by its previous holder.

The counterpart to @custom:emits NameReleased: custody returns to recipient and the deposit stays locked, so no value event accompanies this.

event NameRedeemed(uint256 indexed tokenId, address indexed recipient);

Parameters

CrossTierFeePaid

Emitted when a cross-paid fee is paid into the protocol fee pot.

event CrossTierFeePaid(
    uint256 indexed tokenId,
    address indexed payer,
    address indexed recipient,
    uint256 amount,
    bool isRegistration
);

Parameters

OverpaymentRefunded

Emitted when overpayment is refunded to the payer.

event OverpaymentRefunded(address indexed payer, uint256 amount);

Errors

NotController

Thrown when the caller is not the configured registrar controller.

error NotController(address caller);

NotRegistrar

Thrown when the caller is not the configured registrar.

error NotRegistrar(address caller);

InvalidRecipient

Thrown when the supplied refund recipient is invalid (e.g. zero address).

error InvalidRecipient();

InsufficientValue

Thrown when the attached call value is insufficient to cover the computed charge.

error InsufficientValue();

InsufficientFunds

Thrown when the per-asset reserve cannot cover the refund owed.

error InsufficientFunds(uint256 tokenId, uint256 owed, uint256 available);

Parameters

AssetNotSupported

Thrown when assets being deposited are not supported by the escrow.

error AssetNotSupported(address asset);

InvalidPageSize

Thrown when the configured page size is invalid.

error InvalidPageSize(uint256 limit);

InvalidCooldown

Thrown when the configured cooldown is invalid.

error InvalidCooldown();

CooldownTooLong

Thrown when the supplied cooldown exceeds the contract's configured upper bound.

error CooldownTooLong(uint256 supplied, uint256 maxAllowed);

Parameters

RedeemWindowNotConfigured

Thrown by release when the redeem window has never been seeded.

A configuration fault rather than a bad argument: the caller supplied nothing, and the deployment is missing a policy value. Fails the release closed rather than collapsing the holder's exclusive redeem phase to zero length, which would hand the name to whoever is watching the moment it is released. Cleared by calling

Note: function: updateRedeemWindow.

error RedeemWindowNotConfigured();

RedeemWindowTooShort

Thrown when the supplied redeem window is below the contract's configured lower bound.

error RedeemWindowTooShort(uint256 supplied, uint256 minAllowed);

Parameters

RedeemWindowTooLong

Thrown when the supplied redeem window exceeds the contract's configured upper bound.

error RedeemWindowTooLong(uint256 supplied, uint256 maxAllowed);

Parameters

InvalidAmount

Thrown when the supplied amount is invalid.

error InvalidAmount();

InvalidAsset

Thrown when the supplied ERC20 asset is invalid.

error InvalidAsset();

PositionAlreadyFunded

Thrown when a deposit position is already funded.

error PositionAlreadyFunded(uint256 tokenId);

DepositNotConfigured

Thrown when no deposit is configured for the token.

error DepositNotConfigured(uint256 tokenId);

AlreadyReleased

Thrown when the token has already been released.

error AlreadyReleased(uint256 tokenId);

NotReleased

Thrown when the token has not been released.

error NotReleased(uint256 tokenId);

AlreadyClaimed

Thrown when the refund has already been claimed.

error AlreadyClaimed(uint256 tokenId);

NotReclaimable

Thrown when a token is not in a reclaimable state.

Reclaimable means released with the redeem window elapsed. A released token still inside its window is deliberately not reclaimable: that window belongs to the previous holder. Whether the deposit was withdrawn is irrelevant, because reclaim settles any unwithdrawn amount itself.

error NotReclaimable(uint256 tokenId);

NotRedeemable

Thrown when a token is not in a redeemable state.

Redeemable means released, not yet withdrawn, and still inside the redeem window. A withdrawn position is excluded on purpose: the holder has already taken the deposit value out, so returning the name as well would leave it unbacked.

error NotRedeemable(uint256 tokenId);

EscrowNotApproved

Thrown when escrow is not approved to transfer the token.

error EscrowNotApproved(uint256 tokenId);

NotRefundRecipient

Thrown when the caller is not the refund recipient.

error NotRefundRecipient(address caller, uint256 tokenId);

WithdrawalTooEarly

Thrown when withdrawal is attempted before cooldown has elapsed.

error WithdrawalTooEarly(uint256 tokenId, uint256 availableAt, uint256 currentTime);

Parameters

RefundFailed

Thrown when a refund transfer fails.

error RefundFailed(uint256 tokenId);

NoPendingWithdrawal

Thrown when claimWithdrawal() is called but the caller has no pending balance.

error NoPendingWithdrawal();

NoSuchRefundEntry

Thrown when a refund entry is referenced but does not exist.

error NoSuchRefundEntry(uint256 entryId);

RefundLocked

Thrown when a refund entry is claimed before its availableAt cooldown has elapsed.

error RefundLocked(uint256 entryId, uint64 availableAt);

NotAcceptedTransfer

Thrown when escrow receives an ERC721 transfer from a non-registrar source.

error NotAcceptedTransfer(address caller);

UnsolicitedDeposit

Thrown when escrow receives a registrar-sourced ERC721 transfer that does not correspond to a live release. Blocks holders who try to push a token into custody by calling @custom:function safeTransferFrom directly without going through @custom:function release, which would otherwise trap the NFT and any deposit permanently.

error UnsolicitedDeposit(uint256 tokenId);

Structs

DepositParams

Parameters for recording a deposit position.

The refund recipient is seeded at deposit time but is not locked: it rebinds to the current NFT holder on every transfer that moves the name off the prior recipient, so the deposit follows the name rather than the original payer. Only the current holder can release into escrow and pull the refund.

struct DepositParams {
    uint256 tokenId;
    address asset;
    uint256 amount;
    address recipient;
}

Properties

ProtocolFeeDepositParams

Parameters for recording a cross-paid registration fee into the protocol fee pot.

The pot is non-refundable and only accumulates; it never backs a refund. payer is preserved purely for event accounting since the fee itself is non-refundable.

struct ProtocolFeeDepositParams {
    uint256 tokenId;
    address payer;
    address recipient;
}

Properties

ChargeTransferFeeParams

Inputs for charging transfer friction and rebinding the escrow position.

The fee charged is the name's own price returned by @custom:function PopRules.transferFloor, settled to the protocol fee pot. The deposit, when present, travels with the NFT: the position is rebound to the recipient so the new holder is the only address that can later release into escrow and unlock the locked value. There is no transfer-time refund path.

struct ChargeTransferFeeParams {
    uint256 tokenId;
    uint256 transferFee;
    address payer;
    address to;
}

Properties

ReleasePosition

Canonical escrow state for a token.

Tracks the phased lifecycle as two flags: released flips on release (NFT in escrow, cooldown started); claimed flips on withdraw (refund credited to the pull-payment ledger). The position is deleted on reclaim, freeing the slot for re-registration.

struct ReleasePosition {
    address recipient;
    address asset;
    uint256 amount;
    uint64 withdrawAvailableAt;
    bool released;
    bool claimed;
    uint64 redeemableUntil;
}

Properties

RefundEntry

Time-locked refund entry produced when the protocol owes a recipient value outside the registration-overpayment path.

Every credit creates a fresh entry with its own availableAt; later credits do not reset earlier entries' clocks. Recipients claim entries individually or in batches.

struct RefundEntry {
    address recipient;
    uint256 amount;
    uint64 availableAt;
    uint256 tokenId;
}

Properties

Contents

• personhood
• revive

Contents

• IPersonhood

IPersonhood

Git Source

Title: IPersonhood - Proof of Personhood Precompile

Query personhood status of an account.

Available at address 0x000000000000000000000000000000000a010000. The precompile reads from the alias-accounts pallet which stores per-context alias mappings backed by ring membership proofs. Ring roots are received from the People chain via XCM pub/sub. Example usage: IPersonhood personhood = IPersonhood(0x000000000000000000000000000000000a010000); IPersonhood.PersonhoodInfo memory info = personhood.personhoodStatus(someAddress, bytes32("dotns")); if (info.status == 2) { // full person ... }

Note: security-contact: admin@parity.io

Functions

personhoodStatus

Returns personhood info for an account within a specific application context.

function personhoodStatus(
    address account,
    bytes32 context
)
    external
    view
    returns (PersonhoodInfo memory info);

Parameters

Returns

Structs

PersonhoodInfo

Personhood information for an account in a given context.

status tiers are defined incrementally: 0=None, 1=Lite, 2=Full. If we add more types in the future, the existing ones remain unchanged.

struct PersonhoodInfo {
    uint8 status;
    bytes32 contextAlias;
}

Properties

Contents

• ISystem

ISystem

Git Source

Title: ISystem

Minimal subset of revive's System precompile, vendored from polkadot-sdk's substrate/frame/revive/uapi/sol/ISystem.sol. Exposed at @custom:address SYSTEM_ADDR on every revive runtime that opts the precompile in.

Kept intentionally minimal. New methods should be added on demand rather than mirrored wholesale, so the audit surface stays small and any upstream change is a deliberate review event.

Functions

callerIsRoot

Returning true iff the immediate caller's substrate origin is Root. Reverts on a RuntimeOrigin::Signed(_) or non-Root origin.

function callerIsRoot() external view returns (bool);

originIsRoot

Returning true iff the transaction-level substrate origin is Root.

Reads the stack origin rather than the immediate caller, so it holds through a UUPS proxy's delegatecall frame where callerIsRoot returns false. Returns false, rather than reverting, on a non-Root origin.

function originIsRoot() external view returns (bool);

Contents

• DotnsCostModelRegistry
• DotnsFlatPricing
• DotnsScarcityPricing
• IDotnsCostModelRegistry
• IDotnsPricing
• IPopRules
• PopRules

DotnsCostModelRegistry

Git Source

Inherits: Ownable, IDotnsCostModelRegistry

Title: DotNS Cost Model Registry

Keeps every registered cost model addressable by version and tracks the current one.

Holds only pointers, so it stays a plain owner-gated contract. PopRules resolves it once through DotnsConstants.COST_MODEL and prices the current version for fresh reads and a specific version for in-flight registrations.

Note: security-contact: admin@parity.io

State Variables

modelOf

mapping(uint256 version => IDotnsPricing model) public override modelOf

currentVersion

Returns the version currently serving fresh pricing.

uint256 public override currentVersion

Functions

constructor

Sets the owner permitted to register models.

constructor(address owner_) Ownable(owner_);

Parameters

register

Registers a model and makes it current.

Owner-only. Keys the model by its own version, so a version can be registered once; a repeat triggers @custom:reverts AlreadyRegistered. Moves the current pointer to the new version and emits @custom:emits CostModelRegistered.

function register(IDotnsPricing model) external override onlyOwner;

Parameters

setCurrentVersion

Points the current version at an already-registered model.

Owner-only. Reverts to a previously registered version without redeploying it, so governance can roll fresh pricing back to an earlier curve. @custom:reverts UnknownVersion when no model is registered for version. Emits @custom:emits CurrentModelSet.

function setCurrentVersion(uint256 version) external override onlyOwner;

Parameters

current

Returns the current model.

function current() external view override returns (IDotnsPricing model);

Returns

priceForBaseLength

Prices a base length at the current version.

function priceForBaseLength(uint256 baseLength)
    external
    view
    override
    returns (uint256 weiPrice);

Parameters

Returns

priceForBaseLengthAtVersion

Prices a base length at a specific version.

@custom:reverts UnknownVersion when no model is registered for version.

function priceForBaseLengthAtVersion(
    uint256 version,
    uint256 baseLength
)
    external
    view
    override
    returns (uint256 weiPrice);

Parameters

Returns

DotnsFlatPricing

Git Source

Inherits: IDotnsPricing

Title: DotNS Flat Pricing

Prices every registration at a single deposit, whatever the base length.

The launch cost model: one constant amount for any name the bands admit, so a nine-plus character name costs the same flat deposit and shorter names stay gated by PopRules. The deposit is fixed at deployment, so a new amount is a fresh deployment registered under DotnsConstants.COST_MODEL. DotnsScarcityPricing is the length-sensitive alternative held as a later candidate; it is not the registered default.

Note: security-contact: admin@parity.io

Constants

FORM_ID

Identifier of the flat model form, mixed into version.

Separates this form from another model that reuses the same deposit, so version cannot collide across model forms.

uint256 public constant FORM_ID = uint256(keccak256("dotns.pricing.flat.v1"))

deposit

Deposit in wei charged for every base length.

uint256 public immutable deposit

Functions

constructor

Fixes the deposit for the life of this model.

Requires a strictly positive deposit so the model can never price at zero; a zero amount triggers @custom:reverts PricingError.

constructor(uint256 depositValue) ;

Parameters

priceForBaseLength

Returns the registration cost in wei for a label of the given base length.

Returns the same deposit for every base length: the amount does not vary with the label, so the argument is read only to satisfy the interface.

function priceForBaseLength(uint256) external view override returns (uint256 weiPrice);

Parameters

Returns

version

Returns a stable identifier for this model and its parameters.

Two deployments with the same deposit share a version; any change to the deposit changes it.

function version() external view override returns (uint256 modelVersion);

Returns

DotnsScarcityPricing

Git Source

Inherits: IDotnsPricing

Title: DotNS Scarcity Pricing

Prices a registration on a geometric scarcity curve driven by base length.

The curve doubles the base fee for each character below nine and halves it for each character from nine upward, never below the floor. The base fee is the curve's value at nine characters. Both parameters are fixed at deployment, so a new curve is a fresh deployment registered under DotnsConstants.COST_MODEL. Held as a length-sensitive candidate for a later cost-model version; the launch default is the constant DotnsFlatPricing, so this model ships unregistered until governance registers it.

Note: security-contact: admin@parity.io

Constants

FORM_ID

Identifier of the scarcity curve form, mixed into version.

Distinguishes this curve shape from another model that reuses the same base fee and floor, so version cannot collide across model forms.

uint256 public constant FORM_ID = uint256(keccak256("dotns.pricing.scarcity.v1"))

baseFee

Base fee D in wei: the curve's value at nine characters.

uint256 public immutable baseFee

minPrice

Price floor F in wei: the least any name can cost. Never above the base fee.

uint256 public immutable minPrice

Functions

constructor

Fixes the base fee and floor for the life of this model.

Carries the curve invariants: the base fee and floor are both strictly positive, the floor does not exceed the base fee, and the base fee stays within type(uint256).max / 512 so the multiplication below nine characters cannot overflow. An all-digit label such as "42" strips to base length 0 and reaches the 2**9 multiplier, which sets the /512 ceiling. Any breach triggers @custom:reverts PricingError.

constructor(uint256 baseFeeValue, uint256 minPriceValue) ;

Parameters

priceForBaseLength

Returns the registration cost in wei for a label of the given base length.

Below nine the multiplier is at most 512, and the constructor caps the base fee at type(uint256).max / 512 so the multiplication cannot overflow. From nine upward the base fee is right-shifted by baseLength - 9, so it only decreases and the floor stops a long base length costing nothing. The floor stays at or below the base fee, so it only binds from nine characters upward, never in the doubling range below nine.

function priceForBaseLength(uint256 baseLength)
    external
    view
    override
    returns (uint256 weiPrice);

Parameters

Returns

version

Returns a stable identifier for this model and its parameters.

Two deployments with the same parameters share a version; any change to the base fee or floor changes it.

function version() external view override returns (uint256 modelVersion);

Returns

IDotnsCostModelRegistry

Git Source

Title: DotNS Cost Model Registry

Holds every cost model the protocol has run and names the current one.

The address registered under DotnsConstants.COST_MODEL points here, set once and never repointed. Changing the live curve registers a new model, which adds its version and moves the current pointer. Prior models stay live and priceable by version, so a registration committed against an earlier curve settles at the amount it committed to.

Note: security-contact: admin@parity.io

Functions

register

Registers a model and makes it current.

Owner-only. Keys the model by its own version, so a version can be registered once; a repeat triggers @custom:reverts AlreadyRegistered. Moves the current pointer to the new version and emits @custom:emits CostModelRegistered.

function register(IDotnsPricing model) external;

Parameters

setCurrentVersion

Points the current version at an already-registered model.

Owner-only. Reverts to a previously registered version without redeploying it, so governance can roll fresh pricing back to an earlier curve. @custom:reverts UnknownVersion when no model is registered for version. Emits @custom:emits CurrentModelSet.

function setCurrentVersion(uint256 version) external;

Parameters

modelOf

Returns the model registered for a version, or the zero address when none.

function modelOf(uint256 version) external view returns (IDotnsPricing model);

Parameters

Returns

currentVersion

Returns the version currently serving fresh pricing.

function currentVersion() external view returns (uint256 version);

Returns

current

Returns the current model.

function current() external view returns (IDotnsPricing model);

Returns

priceForBaseLength

Prices a base length at the current version.

function priceForBaseLength(uint256 baseLength) external view returns (uint256 weiPrice);

Parameters

Returns

priceForBaseLengthAtVersion

Prices a base length at a specific version.

@custom:reverts UnknownVersion when no model is registered for version.

function priceForBaseLengthAtVersion(
    uint256 version,
    uint256 baseLength
)
    external
    view
    returns (uint256 weiPrice);

Parameters

Returns

Events

CostModelRegistered

Emitted when a model is registered and becomes current.

event CostModelRegistered(uint256 indexed version, address indexed model);

Parameters

CurrentModelSet

Emitted when the current version is pointed at an already-registered model.

event CurrentModelSet(uint256 indexed version);

Parameters

Errors

AlreadyRegistered

Thrown when registering a model whose version is already held.

error AlreadyRegistered(uint256 version);

Parameters

UnknownVersion

Thrown when pricing against a version that was never registered.

error UnknownVersion(uint256 version);

Parameters

ZeroVersion

Thrown when registering a model whose version is zero, which is the sentinel for an unregistered version and so cannot name a real model.

error ZeroVersion();

PricingVersionMismatch

Thrown when a registration reveals at a different version than it committed to.

Raised where a commit-reveal flow binds a version at commit and checks it at reveal, so the version a name prices at cannot move after the commitment is made.

error PricingVersionMismatch(uint256 committed, uint256 revealed);

Parameters

IDotnsPricing

Git Source

Title: DotNS Pricing Cost Model

Prices a registration from the base length of its label alone.

The seam between name policy and the wei amount a registration costs. PopRules and the public commit-reveal controller keep the classification, reservation, and tier rules; the model owns only the amount for a given base length, so the curve can be swapped by registering a new model under DotnsConstants.COST_MODEL without touching either. Only the base length crosses the seam: the model reads no personhood band or PopStatus. The public controller prices NoStatus deposits through this same path, so the model carries no PoP name.

Note: security-contact: admin@parity.io

Functions

priceForBaseLength

Returns the registration cost in wei for a label of the given base length.

Pure amount lookup: the caller supplies the digit-stripped base length and the model returns the curve value for it. Runs on the ERC721 transfer floor read, so it stays a view with no state writes.

function priceForBaseLength(uint256 baseLength) external view returns (uint256 weiPrice);

Parameters

Returns

version

Returns a stable identifier for this model and its parameters.

Changes when the model shape or its parameters change, so clients and telemetry can tell one live curve from another. Not consulted on the pricing path.

function version() external view returns (uint256 modelVersion);

Returns

Errors

PricingError

Thrown when a model constructor parameter breaks a pricing invariant.

error PricingError(string reason);

Parameters

IPopRules

Git Source

Title: Proof of Personhood Rules for Dotns

Proof of personhood interface defining Dotns price calculation, PoP-tier requirements, and base-name reservation rules.

Classifies labels into the PoP tier required for registration and exposes reservation metadata. Length <= 5 is reserved for governance; lengths 6-8 require PopFull unless they carry exactly two trailing digits (PopLite, gateway-issued); lengths >= 9 are open to every caller as NoStatus when they carry zero or exactly two trailing digits. Any one-digit suffix, and any suffix longer than two digits, is invalid; internal digits do not affect classification. Reservations are keyed by the digit-stripped stem so alice and alice42 share a slot. Amounts come from the cost model registered under DotnsConstants.COST_MODEL, which owns the curve; only the base length crosses that seam. Every caller pays the same amount for a given length; personhood only unlocks the premium band.

Note: security-contact: admin@parity.io

Functions

classifyName

Classifies a name into a required PoP tier per DotNS naming rules.

Pure; inputs are the label bytes only. Callers use the returned tier to decide which pricing and verification branch applies. Non-canonical labels (anything other than a single lowercase ASCII DNS label) and labels with exactly one or more than two trailing digits both trigger @custom:reverts PopError.

function classifyName(string calldata name)
    external
    pure
    returns (PopStatus requirement, string memory message);

Parameters

Returns

setShortNamesEnabled

Opens or closes the public market for names shorter than nine characters.

Owner-only; unauthorised callers trigger @custom:reverts OwnableUnauthorizedAccount. While closed, which is the deploy default, @custom:function priceWithCheck and

Note: function: priceWithoutCheck trigger @custom:reverts PopError for a base length below nine, so no public caller buys a short name. The gateway free grant and the registrar's registerReserved path do not read this flag. Emits @custom:emits ShortNamesEnabledUpdated.

function setShortNamesEnabled(bool enabled) external;

Parameters

personhoodOf

Returns the personhood tier recorded for an account.

Reads the account's dotns-scoped tier from the personhood precompile and maps it to a PopStatus. This is the direct account-tier read; the same tier otherwise surfaces only as the userStatus field of a pricing query. Never returns Reserved, so the result is one of NoStatus, PopLite, or PopFull.

function personhoodOf(address account) external view returns (PopStatus tier);

Parameters

Returns

reserveBaseName

Creates or refreshes a reservation entry for a PopLite-eligible stem.

Commit-reveal reservation path. Only an authorised controller on the registrar may call this, otherwise @custom:reverts NotRegistry. The caller passes the already-stripped stem; the contract enforces stem shape (no trailing digits) and PopLite-eligibility (length in [6, 8]), and a non-canonical label or a label outside that shape triggers

Note: reverts: PopError. Cross-user collision on a live slot triggers @custom:reverts PopError so the caller cannot silently overwrite another user's reservation; same-user refresh and writes into an empty or expired slot emit @custom:emits BaseNameReserved.

function reserveBaseName(string calldata stem, address user) external;

Parameters

reserveBaseNameForPop

Writes or refreshes a reservation for a bare base-name stem.

Gateway-driven reservation path used by the PoP controller. Only a controller in the registrar's controllers set may call this, otherwise @custom:reverts NotRegistry. Does not apply the lite-format length window that @custom:function reserveBaseName enforces, but does require the input to be canonical and stem-shaped (no trailing digits); a non-canonical or non-stem label triggers @custom:reverts PopError. If the slot is already live and held by a different user, @custom:reverts PopError so the caller's local bookkeeping and PopRules state stay in lockstep; if it is live for the same user, expiry is refreshed to block.timestamp + MAX_RESERVATION_TIME. Emits

Note: emits: BaseNameReserved on every successful write.

function reserveBaseNameForPop(string calldata stem, address user) external;

Parameters

releaseBaseName

Clears a reservation for a base-name stem.

Only a controller in the registrar's controllers set may call this, otherwise

Notes:

• reverts: NotRegistry. Non-canonical or non-stem labels trigger

• reverts: PopError. Live reservations may only be cleared by the same controller that wrote them; another authorised controller attempting to clear a live slot triggers

• reverts: PopError. Expired reservations may be cleared by any authorised controller as garbage collection. Used by the PoP controller when a reservation is claimed, relinquished, or a queue head promotion leaves the slot empty. Emits

• emits: BaseNameReleased once the slot is cleared.

function releaseBaseName(string calldata stem) external;

Parameters

releaseReservationForReclaim

Clears a reservation when the slot owner matches expectedOwner, allowing any registrar-authorised controller (not only the stamping one) to release the slot.

Narrower than @custom:function releaseBaseName: callers must prove they know the slot owner, so cross-controller release is gated on a positive match rather than on caller identity. Intended for the public registrar controller's reclaim path, where a prior occupant has handed the name back to escrow and the new registrant needs the cross-flow guard cleared regardless of which controller originally stamped it. Only a registrar-authorised controller may call this (@custom:reverts NotRegistry). Non-canonical or non-stem labels trigger @custom:reverts PopError. A live reservation whose owner does not match expectedOwner triggers @custom:reverts PopError; expired reservations are cleared regardless. Emits @custom:emits BaseNameReleased.

function releaseReservationForReclaim(string calldata stem, address expectedOwner) external;

Parameters

getBaseNameReservation

Retrieves reservation information for a base name.

Raw accessor: returns the stored slot regardless of expiry. Use

Notes:

• function: isBaseNameReserved when live-window semantics are needed. Non-canonical labels trigger

• reverts: PopError.

function getBaseNameReservation(string calldata baseName)
    external
    view
    returns (address owner, uint64 expires);

Parameters

Returns

stripDigits

Returns the bare stem of a label, i.e. the label with any trailing ASCII digits removed.

Mirrors the normalisation that @custom:function reserveBaseName applies before writing a reservation, so callers can look up or release a reservation by passing the full label without re-implementing the digit-stripping rule. Non-canonical labels trigger @custom:reverts PopError.

function stripDigits(string calldata name) external pure returns (string memory stem);

Parameters

Returns

isBaseNameReserved

Indicates whether a base name is currently reserved.

Applies the live-window predicate to the stored slot so an expired reservation reads as free. Non-canonical labels trigger @custom:reverts PopError.

function isBaseNameReserved(string calldata baseName)
    external
    view
    returns (bool reservedStatus, address owner, uint64 expires);

Parameters

Returns

priceWithCheck

Calculates price with PoP classification and reservation enforcement.

Reverting pricing path used by the commit-reveal controller. Price is the scarcity curve for the label's base length and is charged to every caller, verified or not; personhood only unlocks the premium band. Non-canonical labels, a base stem held live by another user, a governance-reserved label, or a userAddress whose personhood tier does not meet the label's required tier each trigger @custom:reverts PopError.

function priceWithCheck(
    string calldata name,
    address userAddress
)
    external
    view
    returns (PriceWithMeta memory metadata);

Parameters

Returns

priceWithCheckAtVersion

Calculates price at a specific cost-model version with PoP classification and reservation enforcement.

The versioned counterpart of @custom:function priceWithCheck: identical classification, tier gating, and reservation rules, but the amount comes from the model registered for pricingVersionValue rather than the current one. The commit-reveal controller prices a reveal at the version bound into its commitment, so a model change between commit and reveal does not move the amount. @custom:reverts UnknownVersion when the version was never registered.

function priceWithCheckAtVersion(
    string calldata name,
    address userAddress,
    uint256 pricingVersionValue
)
    external
    view
    returns (PriceWithMeta memory metadata);

Parameters

Returns

priceWithoutCheck

Calculates price with PoP classification and reservation metadata, without reverting on conflicts.

Non-reverting counterpart to priceWithCheck: surfaces the same fields, but reports a Reserved status through metadata instead of reverting when the base stem is held by another user. Used by front-ends that need to present a price and eligibility preview without forcing a transaction attempt. Governance-reserved names are not rejected here either; the caller decides what to do. Non-canonical labels still trigger @custom:reverts PopError because the input is malformed rather than just contested.

function priceWithoutCheck(
    string calldata name,
    address userAddress
)
    external
    view
    returns (PriceWithMeta memory metadata);

Parameters

Returns

priceWithoutCheckAtVersion

Calculates price at a specific cost-model version with PoP classification and reservation metadata, without reverting on conflicts.

The versioned counterpart of @custom:function priceWithoutCheck: same non-reverting preview behaviour, but the amount comes from the model registered for pricingVersionValue. @custom:reverts UnknownVersion when the version was never registered.

function priceWithoutCheckAtVersion(
    string calldata name,
    address userAddress,
    uint256 pricingVersionValue
)
    external
    view
    returns (PriceWithMeta memory metadata);

Parameters

Returns

transferFloor

Transfer-time floor: the greater of the recipient-reach component and the sender-tier-downgrade component, each priced at the name's own length.

Re-prices the name at its own length on every move: returns the name's curve price when either (i) the recipient does not meet the label's required tier, or (ii) the recipient's personhood tier is strictly below the sender's, and zero when neither holds. Passing a name to a wallet that could never have registered it therefore costs the name's own curve price. The two components overlap on pure tier mismatches, so the function takes their maximum rather than their sum to avoid double-charging. Consumed by @custom:function DotnsRegistrar.quoteTransferFee. Non-canonical labels and labels with exactly one or more than two trailing digits trigger @custom:reverts PopError.

function transferFloor(
    string calldata name,
    address from,
    address to
)
    external
    view
    returns (uint256 floor);

Parameters

Returns

isBaseName

Returns whether name is a base name under PoP rules.

A base name has no trailing digits; lite-person labels always have exactly two trailing digits, so the two spaces are disjoint. Non-canonical labels trigger

Note: reverts: PopError.

function isBaseName(string calldata name) external pure returns (bool isBase);

Parameters

Returns

price

Calculates registration cost for a label.

Prices the label by its base length through the cost model registered under DotnsConstants.COST_MODEL. Ignores the caller's personhood status and reservation state. A label whose trailing-digit suffix is neither zero nor exactly two, and any non-canonical label, trigger @custom:reverts PopError.

function price(string calldata name) external view returns (uint256 cost);

Parameters

Returns

pricingVersion

Returns the current cost-model version.

The current version held by the registry under DotnsConstants.COST_MODEL. The commit-reveal controller binds it into a commitment and prices the reveal at that version, so a model change between commit and reveal leaves the committed amount unchanged. @custom:reverts PopError when no registry is configured.

function pricingVersion() external view returns (uint256 modelVersion);

Returns

Events

BaseNameReserved

Emitted when a base name receives a reservation.

event BaseNameReserved(string indexed baseName, address indexed owner, uint64 expires);

Parameters

ShortNamesEnabledUpdated

Emitted when the public market for names shorter than nine characters is opened or closed.

Owner-only setter @custom:function setShortNamesEnabled.

event ShortNamesEnabledUpdated(bool enabled);

Parameters

BaseNameReleased

Emitted when a base-name reservation is cleared.

event BaseNameReleased(string indexed baseName);

Parameters

Errors

PopError

Thrown when a name violates PoP-tier or reservation requirements.

error PopError(string reason);

Parameters

NotRegistry

Thrown when a caller is not an authorised controller on the registrar.

error NotRegistry();

NameReserved

Thrown when registering a name whose base stem is held as a live reservation by another user.

error NameReserved(string label);

Parameters

GovernanceReserved

Thrown when registering a label that classifies as governance-reserved at the protocol level.

Distinct from @custom:reverts NameReserved so off-chain consumers can tell "wait for the holder to relinquish" apart from "this label is permanently held by governance".

error GovernanceReserved(string label);

Parameters

OwnerStatusInsufficient

Thrown on the cross-payer path when the owner's recorded PoP tier does not meet the label's required tier. The direct path's priceWithCheck covers this same condition via its own revert.

error OwnerStatusInsufficient(string label, PopStatus userStatus, PopStatus required);

Parameters

Structs

PriceWithMeta

Bundle returned from metadata-aware pricing queries.

struct PriceWithMeta {
    uint256 price;
    PopStatus status;
    PopStatus userStatus;
    string message;
}

Properties

Reservation

Reservation metadata for a base name (digits removed).

struct Reservation {
    address owner;
    uint64 expires;
    address controller;
}

Properties

Enums

PopStatus

Proof-of-Personhood eligibility tier.

NoStatus is the default for unverified users; PopLite and PopFull are the two personhood tiers; Reserved covers both governance-held names and base stems held by another user through the reservation table.

enum PopStatus {
    NoStatus,
    PopLite,
    PopFull,
    Reserved
}

PopRules

Git Source

Inherits: Initializable, UUPSUpgradeable, OwnableUpgradeable, ERC165Upgradeable, IPopRules

Title: PopRules

Implements DotNS classification, cost-model-driven pricing, and base-name reservations.

Tiers: base lengths <= 5 are governance-reserved, base lengths 6-8 require PopFull (or PopLite when carrying exactly two trailing digits, for gateway-issued lite names), base lengths >= 9 are open to any caller as NoStatus when they carry zero or exactly two trailing digits. A one-digit suffix and more than two trailing digits are invalid. Every caller pays the same amount for a given base length. The amount comes from the cost model registered under DotnsConstants.COST_MODEL, which owns the curve; this contract passes it only the base length and keeps the classification, reservation, and tier rules. Personhood only unlocks the premium band. Base lengths below nine are closed to the public paid path until governance sets shortNamesEnabled; the gateway and registerReserved do not consult it.

Note: security-contact: admin@parity.io

Constants

MAX_RESERVATION_TIME

Maximum time a base name can be reserved.

uint256 public constant MAX_RESERVATION_TIME = 12 weeks

State Variables

reservations

Active reservations keyed by digit-stripped base name.

mapping(string baseName => Reservation reservation) public reservations

protocolRegistry

Protocol-level address registry for all DotNS contracts.

IDotnsProtocolRegistry public protocolRegistry

shortNamesEnabled

Whether the public paid path may register names shorter than nine characters. Closed by default; only governance opens it.

bool public shortNamesEnabled

__gap

uint256[50] private __gap

Functions

onlyRegistry

Restricts function to any registry-authorised controller.

modifier onlyRegistry() ;

constructor

Note: oz-upgrades-unsafe-allow: constructor

constructor() ;

initialize

Initialises the oracle (public entry point).

Runs once behind the proxy; subsequent calls trigger @custom:reverts InvalidInitialization via the initializer modifier. Amounts come from the cost model registered under DotnsConstants.COST_MODEL, so no price is seeded here.

function initialize(IDotnsProtocolRegistry registry) public initializer;

Parameters

setShortNamesEnabled

Opens or closes the public market for names shorter than nine characters.

Owner-only; unauthorised callers trigger @custom:reverts OwnableUnauthorizedAccount. While closed, which is the deploy default, @custom:function priceWithCheck and

Note: function: priceWithoutCheck trigger @custom:reverts PopError for a base length below nine, so no public caller buys a short name. The gateway free grant and the registrar's registerReserved path do not read this flag. Emits @custom:emits ShortNamesEnabledUpdated.

function setShortNamesEnabled(bool enabled) external override onlyOwner;

Parameters

classifyName

Classifies a name into a required PoP tier per DotNS naming rules.

Pure; inputs are the label bytes only. Callers use the returned tier to decide which pricing and verification branch applies. Non-canonical labels (anything other than a single lowercase ASCII DNS label) and labels with exactly one or more than two trailing digits both trigger @custom:reverts PopError.

function classifyName(string calldata name)
    external
    pure
    override
    returns (PopStatus requirement, string memory message);

Parameters

Returns

reserveBaseName

Creates or refreshes a reservation entry for a PopLite-eligible stem.

Commit-reveal reservation path. Only an authorised controller on the registrar may call this, otherwise @custom:reverts NotRegistry. The caller passes the already-stripped stem; the contract enforces stem shape (no trailing digits) and PopLite-eligibility (length in [6, 8]), and a non-canonical label or a label outside that shape triggers

Note: reverts: PopError. Cross-user collision on a live slot triggers @custom:reverts PopError so the caller cannot silently overwrite another user's reservation; same-user refresh and writes into an empty or expired slot emit @custom:emits BaseNameReserved.

function reserveBaseName(
    string calldata stem,
    address userAddress
)
    external
    override
    onlyRegistry;

Parameters

isBaseName

Returns whether name is a base name under PoP rules.

A base name has no trailing digits; lite-person labels always have exactly two trailing digits, so the two spaces are disjoint. Non-canonical labels trigger

Note: reverts: PopError.

function isBaseName(string calldata baseName) external pure override returns (bool isBase);

Parameters

Returns

getBaseNameReservation

Retrieves reservation information for a base name.

Raw accessor: returns the stored slot regardless of expiry. Use

Notes:

• function: isBaseNameReserved when live-window semantics are needed. Non-canonical labels trigger

• reverts: PopError.

function getBaseNameReservation(string calldata baseName)
    external
    view
    override
    returns (address reservationOwner, uint64 expiryTimestamp);

Parameters

Returns

isBaseNameReserved

Indicates whether a base name is currently reserved.

Applies the live-window predicate to the stored slot so an expired reservation reads as free. Non-canonical labels trigger @custom:reverts PopError.

function isBaseNameReserved(string calldata baseName)
    external
    view
    override
    returns (bool isReserved, address reservationOwner, uint64 expiryTimestamp);

Parameters

Returns

priceWithCheck

Calculates price with PoP classification and reservation enforcement.

Reverting pricing path used by the commit-reveal controller. Price is the scarcity curve for the label's base length and is charged to every caller, verified or not; personhood only unlocks the premium band. Non-canonical labels, a base stem held live by another user, a governance-reserved label, or a userAddress whose personhood tier does not meet the label's required tier each trigger @custom:reverts PopError.

function priceWithCheck(
    string calldata name,
    address userAddress
)
    external
    view
    override
    returns (PriceWithMeta memory metadata);

Parameters

Returns

priceWithCheckAtVersion

Calculates price at a specific cost-model version with PoP classification and reservation enforcement.

The versioned counterpart of @custom:function priceWithCheck: identical classification, tier gating, and reservation rules, but the amount comes from the model registered for pricingVersionValue rather than the current one. The commit-reveal controller prices a reveal at the version bound into its commitment, so a model change between commit and reveal does not move the amount. @custom:reverts UnknownVersion when the version was never registered.

function priceWithCheckAtVersion(
    string calldata name,
    address userAddress,
    uint256 pricingVersionValue
)
    external
    view
    override
    returns (PriceWithMeta memory metadata);

Parameters

Returns

priceWithoutCheck

Calculates price with PoP classification and reservation metadata, without reverting on conflicts.

Non-reverting counterpart to priceWithCheck: surfaces the same fields, but reports a Reserved status through metadata instead of reverting when the base stem is held by another user. Used by front-ends that need to present a price and eligibility preview without forcing a transaction attempt. Governance-reserved names are not rejected here either; the caller decides what to do. Non-canonical labels still trigger @custom:reverts PopError because the input is malformed rather than just contested.

function priceWithoutCheck(
    string calldata name,
    address userAddress
)
    external
    view
    override
    returns (PriceWithMeta memory metadata);

Parameters

Returns

priceWithoutCheckAtVersion

Calculates price at a specific cost-model version with PoP classification and reservation metadata, without reverting on conflicts.

The versioned counterpart of @custom:function priceWithoutCheck: same non-reverting preview behaviour, but the amount comes from the model registered for pricingVersionValue. @custom:reverts UnknownVersion when the version was never registered.

function priceWithoutCheckAtVersion(
    string calldata name,
    address userAddress,
    uint256 pricingVersionValue
)
    external
    view
    override
    returns (PriceWithMeta memory metadata);

Parameters

Returns

_priceWithCheck

Shared body for the reservation-enforcing pricing reads.

atVersion selects the amount source: the current model when false, the model for pricingVersionValue when true. Classification, tier gating, and reservation rules are the same on both paths, so they live here once.

function _priceWithCheck(
    string calldata name,
    address userAddress,
    bool atVersion,
    uint256 pricingVersionValue
)
    internal
    view
    returns (PriceWithMeta memory metadata);

_priceWithoutCheck

Shared body for the non-reverting pricing reads.

Mirror of @custom:function _priceWithCheck for the front-end preview path: reports a contested reservation through metadata rather than reverting. atVersion selects the amount source in the same way.

function _priceWithoutCheck(
    string calldata name,
    address userAddress,
    bool atVersion,
    uint256 pricingVersionValue
)
    internal
    view
    returns (PriceWithMeta memory metadata);

price

Calculates registration cost for a label.

Prices the label by its base length through the cost model registered under DotnsConstants.COST_MODEL. Ignores the caller's personhood status and reservation state. A label whose trailing-digit suffix is neither zero nor exactly two, and any non-canonical label, trigger @custom:reverts PopError.

function price(string calldata name) external view override returns (uint256);

Parameters

Returns

pricingVersion

Returns the current cost-model version.

The current version held by the registry under DotnsConstants.COST_MODEL. The commit-reveal controller binds it into a commitment and prices the reveal at that version, so a model change between commit and reveal leaves the committed amount unchanged. @custom:reverts PopError when no registry is configured.

function pricingVersion() external view override returns (uint256 modelVersion);

Returns

transferFloor

Transfer-time floor: the greater of the recipient-reach component and the sender-tier-downgrade component, each priced at the name's own length.

Re-prices the name at its own length on every move: returns the name's curve price when either (i) the recipient does not meet the label's required tier, or (ii) the recipient's personhood tier is strictly below the sender's, and zero when neither holds. Passing a name to a wallet that could never have registered it therefore costs the name's own curve price. The two components overlap on pure tier mismatches, so the function takes their maximum rather than their sum to avoid double-charging. Consumed by @custom:function DotnsRegistrar.quoteTransferFee. Non-canonical labels and labels with exactly one or more than two trailing digits trigger @custom:reverts PopError.

function transferFloor(
    string calldata name,
    address from,
    address to
)
    external
    view
    override
    returns (uint256 floor);

Parameters

Returns

personhoodOf

Returns the personhood tier recorded for an account.

Reads the account's dotns-scoped tier from the personhood precompile and maps it to a PopStatus. This is the direct account-tier read; the same tier otherwise surfaces only as the userStatus field of a pricing query. Never returns Reserved, so the result is one of NoStatus, PopLite, or PopFull.

function personhoodOf(address account) external view override returns (PopStatus tier);

Parameters

Returns

_personhoodTier

Reads account's dotns-scoped personhood tier from the alias-accounts precompile and translates it into a PopStatus.

Single source of truth so callers cannot read the precompile directly and drift on the status mapping. Tiers are defined incrementally on the precompile side: 0=None, 1=Lite, 2=Full. Anything outside that range collapses to NoStatus so a future tier addition fails closed instead of silently being treated as a higher level than it actually is.

function _personhoodTier(address account) private view returns (PopStatus);

_meetsReach

Single canonical "is userStatus at reach for required?" predicate.

Both priceWithCheck and transferFloor build on this so the tier-eligibility rule lives in exactly one place and the callers cannot disagree about who clears a given label. _personhoodTier never returns Reserved, so userStatus is in {NoStatus, PopLite, PopFull} and the enum comparison reflects tier ordering directly. A Reserved required (governance label) is unreachable by any verified user, so the comparison returns false and the caller charges the friction fee, providing defence-in-depth if a Reserved label ever enters circulation.

function _meetsReach(PopStatus required, PopStatus userStatus) private pure returns (bool);

_priceValidatedName

Amount for a base length at the current cost-model version.

The cost-model registry owns the curve; this contract passes it only the base length. The call is a view because it runs on the ERC721 transfer floor read through

Note: function: transferFloor.

function _priceValidatedName(uint256 baseLength) internal view returns (uint256 priceValue);

_priceValidatedNameAtVersion

Amount for a base length at a specific cost-model version.

Prices an in-flight registration at the version it committed to, so a model change between commit and reveal does not move its cost. @custom:reverts UnknownVersion (from the registry) when the version was never registered.

function _priceValidatedNameAtVersion(
    uint256 pricingVersionValue,
    uint256 baseLength
)
    internal
    view
    returns (uint256 priceValue);

_costModelRegistry

Resolves the cost-model registry registered under DotnsConstants.COST_MODEL.

@custom:reverts PopError when no registry is configured, so a pricing read fails closed rather than resolving through the zero address.

function _costModelRegistry() private view returns (IDotnsCostModelRegistry registry);

_requireShortNamesOpen

Reverts a public paid registration of a base length below nine while the short-name market is closed.

The one gate both public price reads share. Base lengths of nine and above are always open. @custom:reverts PopError when a base length below nine is priced while shortNamesEnabled is false. The gateway and @custom:function registerReserved never reach this, so neither is gated.

function _requireShortNamesOpen(uint256 baseLength) private view;

_validatedBaseLength

Validates the digit suffix and returns the base length that pricing and classification both use to place a name in its band.

A name carries no digit suffix or exactly two digits; any other count triggers

Note: reverts: PopError, so a longer suffix cannot slip a name into a shorter band.

function _validatedBaseLength(string calldata name) internal pure returns (uint256 baseLength);

_enforceReservationRules

Enforces base-name reservation rules.

function _enforceReservationRules(string calldata name, address userAddress) internal view;

Parameters

_isLive

Returns whether reservation is live at block.timestamp.

function _isLive(Reservation memory reservation) internal view returns (bool);

_countTrailingDigits

Counts trailing digits in a string.

function _countTrailingDigits(string calldata label)
    internal
    pure
    returns (uint256 digitCount);

Parameters

Returns

_stripDigits

Strips trailing digits from a name.

function _stripDigits(string calldata name) internal pure returns (string memory baseName);

Parameters

_classifyValidatedName

function _classifyValidatedName(string calldata name)
    internal
    pure
    returns (PopStatus requirement, string memory message, uint256 baseLength);

_requireCanonicalLabel

function _requireCanonicalLabel(string calldata name) internal pure;

supportsInterface

function supportsInterface(bytes4 interfaceId)
    public
    view
    virtual
    override
    returns (bool supported);

_authorizeUpgrade

Function that should revert when msg.sender is not authorized to upgrade the contract. Called by {upgradeToAndCall}. Normally, this function will use an xref:access.adoc[access control] modifier such as {Ownable-onlyOwner}.

function _authorizeUpgrade(address) internal onlyOwner {}

function _authorizeUpgrade(address newImplementation) internal override onlyOwner;

version

Returns implementation version.

function version() external pure virtual returns (string memory versionString);

_onlyRegistry

Ensures the caller is any controller authorised on the registrar.

function _onlyRegistry() internal view;

reserveBaseNameForPop

Writes or refreshes a reservation for a bare base-name stem.

Gateway-driven reservation path used by the PoP controller. Only a controller in the registrar's controllers set may call this, otherwise @custom:reverts NotRegistry. Does not apply the lite-format length window that @custom:function reserveBaseName enforces, but does require the input to be canonical and stem-shaped (no trailing digits); a non-canonical or non-stem label triggers @custom:reverts PopError. If the slot is already live and held by a different user, @custom:reverts PopError so the caller's local bookkeeping and PopRules state stay in lockstep; if it is live for the same user, expiry is refreshed to block.timestamp + MAX_RESERVATION_TIME. Emits

Note: emits: BaseNameReserved on every successful write.

function reserveBaseNameForPop(
    string calldata stem,
    address userAddress
)
    external
    override
    onlyRegistry;

Parameters

stripDigits

Returns the bare stem of a label, i.e. the label with any trailing ASCII digits removed.

Mirrors the normalisation that @custom:function reserveBaseName applies before writing a reservation, so callers can look up or release a reservation by passing the full label without re-implementing the digit-stripping rule. Non-canonical labels trigger @custom:reverts PopError.

function stripDigits(string calldata name) external pure override returns (string memory stem);

Parameters

Returns

releaseBaseName

Clears a reservation for a base-name stem.

Only a controller in the registrar's controllers set may call this, otherwise

Notes:

• reverts: NotRegistry. Non-canonical or non-stem labels trigger

• emits: BaseNameReleased once the slot is cleared.

function releaseBaseName(string calldata stem) external override onlyRegistry;

Parameters

releaseReservationForReclaim

Clears a reservation when the slot owner matches expectedOwner, allowing any registrar-authorised controller (not only the stamping one) to release the slot.

Narrower than @custom:function releaseBaseName: callers must prove they know the slot owner, so cross-controller release is gated on a positive match rather than on caller identity. Intended for the public registrar controller's reclaim path, where a prior occupant has handed the name back to escrow and the new registrant needs the cross-flow guard cleared regardless of which controller originally stamped it. Only a registrar-authorised controller may call this (@custom:reverts NotRegistry). Non-canonical or non-stem labels trigger @custom:reverts PopError. A live reservation whose owner does not match expectedOwner triggers @custom:reverts PopError; expired reservations are cleared regardless. Emits @custom:emits BaseNameReleased.

function releaseReservationForReclaim(
    string calldata stem,
    address expectedOwner
)
    external
    override
    onlyRegistry;

Parameters

_writeReservation

Internal single-source-of-truth writer for stem reservations.

Routes both @custom:function reserveBaseName and @custom:function reserveBaseNameForPop through one path so the cross-user collision semantics stay identical: a live slot held by a different user @custom:reverts PopError, and any other case writes a fresh expiry and emits @custom:emits BaseNameReserved. Same-owner re-reservations refresh the expiry to block.timestamp + MAX_RESERVATION_TIME. Callers are responsible for validating stem is canonical and stem-shaped (no trailing digits); this helper does no input validation of its own so each public entry can layer additional eligibility checks.

function _writeReservation(string calldata stem, address userAddress) internal;

Contents

• DotnsPopController
• DotnsPopLens
• DotnsRegistrar
• DotnsRegistrarController
• IDotnsController
• IDotnsPopController
• IDotnsPopLens
• IDotnsRegistrar
• IDotnsRegistrarController

DotnsPopController

Git Source

Inherits: Initializable, UUPSUpgradeable, OwnableUpgradeable, ERC165Upgradeable, IDotnsPopController

Title: DotnsPopController

Dedicated PoP controller orchestrating lite-person and full-person username issuance on behalf of the PoP gateway pallet.

Lives behind its own UUPS proxy with its own storage. Registered on DotnsRegistrar via addController, which is how multiple controllers coexist on the same registrar without interfering with each other. Enforcement: Personhood is attested off-chain by the gateway pallet before the call reaches this contract, so the on-chain personhood precompile is not re-queried on the gateway path. Every base-label mint path still calls @custom:function IPopRules.classifyName to reject governance-reserved labels (@custom:reverts InvalidBaseLabel on the base path,

Notes:

• reverts: InvalidLiteLabel on the lite path). The lite leg accepts any two-digit lite label whose stem is not governance-reserved, regardless of stem length. Native-token pricing is bypassed entirely; the gateway pays no rent. Decoupling: This contract does not import or call IDotnsRegistrarController. The public commit-reveal controller is equally unaware of this one. Cross-flow collision handling relies on two distinct properties, neither of which requires the two controllers to know about each other: (1) Lite-person labels (NAMEXX) share the public namespace: they are just DNS labels with exactly two trailing digits. First-to-mint wins at the ERC721 layer, so a lite-user and a public registrant cannot hold the same flat label simultaneously. Keeping one namespace removes the ambiguity downstream tooling (dotli, dweb) would see with a separate separator form. (2) Base-name reservations are synchronised into IPopRules. The head of this controller's reservation queue is written through IPopRules.reserveBaseNameForPop on every head transition; the slot is cleared through IPopRules.releaseBaseName when the queue empties (claim, final relinquish, final expiry). The public commit-reveal controller routes through IPopRules.priceWithCheck, which rejects any registration targeting a base-name stem reserved for another user, so the public flow respects gateway reservations without ever importing this contract. PopRules is the single cross-flow authority; the queue here is the intra-PoP ordering layer on top of it. Shared primitives: labelhash / namehash via @custom:contract LabelUtils; the mint + forward-registry + store-write triad via @custom:contract RegistrationUtils; chat-key and lite-to-full link persistence via

• contract: IDotnsPopResolver. Keeping per-name records on the resolver preserves the "Store = labels only" invariant.

• security-contact: admin@parity.io

Constants

MAX_RESERVATION_QUEUE

Upper bound for the number of simultaneously queued reservations per label.

Keeps expireReservation gas bounded.

uint16 public constant MAX_RESERVATION_QUEUE = 64

MIN_RESERVATION_DURATION

Minimum value accepted by @custom:function setReservationDuration.

Prevents owner misconfiguration from instantly expiring every live queue and pending-claim entry. The actual production duration is governance-tuned higher.

uint64 public constant MIN_RESERVATION_DURATION = 1 hours

CHAT_KEY_LENGTH

Required byte length for a non-empty chat key.

Mirrors @custom:contract IDotnsPopResolver InvalidChatKeyLength so the controller can fail closed before the mint instead of bubbling the resolver's revert after partial state has been committed.

uint256 private constant CHAT_KEY_LENGTH = 65

State Variables

protocolRegistry

Protocol-level address registry for all DotNS contracts.

IDotnsProtocolRegistry public protocolRegistry

_reservationMeta

Per-label queue metadata (head/tail pointers).

mapping(bytes32 labelhash => ReservationQueueMeta meta) internal _reservationMeta

_reservationEntries

Per-label sparse entries keyed by monotonically-increasing index.

mapping(bytes32 labelhash => mapping(uint64 index => ReservationEntry entry)) internal
    _reservationEntries

_userReservations

Single per-user pointer into the reservation queues.

Keeps per-user reservation data behind one key and one struct value so callers read both fields in one call instead of two.

mapping(address user => UserReservation reservation) internal _userReservations

_reservedBaseLabel

Remembers the base-label string for each reserved labelhash so the PopRules sync path can address the reservation by its original string form (PopRules keys its reservations mapping by string).

Populated on first enqueue for a label, cleared when the queue empties. Exists only to bridge the queue's bytes32 key space to PopRules' string key space; nothing else reads it.

mapping(bytes32 labelhash => string baseLabel) internal _reservedBaseLabel

reservationDuration

Duration (in seconds) after which a reservation entry is considered expired.

Mirrors pallet_resources::UsernameReservationDuration. Configurable by governance via setReservationDuration.

uint64 public override reservationDuration

_pendingClaimUsers

Enumeration set of users holding at least one pending claim.

Membership equals the set of users with a non-empty queue. Used by pendingClaimUserCount and pendingClaimUsers for paginated enumeration.

EnumerableSet.AddressSet private _pendingClaimUsers

_pendingClaimQueue

Per-user pile of deferred names awaiting a LabelStore.

The Root gateway origin cannot deploy a LabelStore (contract creation is forbidden from Root), so deferred names accumulate here until a signed-origin

Note: function: settlePendingClaims deploys the store and writes the stashed labels. Each entry's deadline is measured from its own mintedAt against reservationDuration.

mapping(address user => PendingClaim[] queue) internal _pendingClaimQueue

__gap

Reserved storage space to allow for layout changes in future upgrades.

uint256[50] private __gap

Functions

onlyRoot

Restricts calls to a substrate Root origin.

modifier onlyRoot() ;

constructor

Note: oz-upgrades-unsafe-allow: constructor

constructor() ;

initialize

Initialises the PoP controller.

Called once through the UUPS proxy; _disableInitializers on the implementation makes direct calls revert with @custom:reverts InvalidInitialization, and any nested call outside an active initialiser scope reverts with @custom:reverts NotInitializing. Emits @custom:emits ReservationDurationSet so indexers observe the initial value through the same event the setter uses later.

function initialize(
    IDotnsProtocolRegistry registry,
    uint64 reservationDuration_
)
    external
    initializer;

reserveLiteName

Registers a lite-person username on behalf of the supplied user without touching the base-name reservation queue.

Callable only under a substrate Root origin (otherwise @custom:reverts NotRoot). The supplied label must satisfy the dotted stem.NN shape and the flattened label must classify as PopLite (otherwise @custom:reverts InvalidLiteLabel); a supplied chat key whose length is neither zero nor CHAT_KEY_LENGTH reverts

Notes:

• reverts: InvalidChatKey before mint and resolver writes run. On a warm-path mint

• emits: LiteNameReserved and @custom:emits NameRegistered. On a cold-path mint @custom:emits LiteNameReserved and @custom:emits PendingClaimStashed, with

function reserveLiteName(LiteRegistration calldata params) external override onlyRoot;

Parameters

reserveBaseName

Registers a lite-person username on behalf of the supplied user and optionally enqueues a reservation for a base name they intend to claim as a full person later.

Callable only under a substrate Root origin (otherwise @custom:reverts NotRoot). The lite leg validates the dotted stem.NN shape and requires the flattened label to classify as PopLite (otherwise @custom:reverts InvalidLiteLabel), and rejects a supplied chat key whose length is neither zero nor CHAT_KEY_LENGTH (otherwise @custom:reverts InvalidChatKey). On a warm-path mint (user already has a LabelStore) it @custom:emits LiteNameReserved and @custom:emits NameRegistered; on a cold-path mint it @custom:emits LiteNameReserved and

Notes:

• emits: PendingClaimStashed, with @custom:emits NameRegistered deferred to

• function: settlePendingClaims when the claim settles. The base-name leg only runs when reservedBaseLabel is non-empty: it validates the DNS-label shape and requires a true base label with no trailing digits (otherwise @custom:reverts InvalidBaseLabel) and with no owner on the registrar (otherwise @custom:reverts BaseNameAlreadyRegistered), since a name that already has an owner could never be claimed. This validation runs before both the lite mint and any queue mutation, so an already-registered reservedBaseLabel aborts the whole call and the candidate receives no lite username either; callers should validate the reserved label before attesting rather than relying on this revert. It then advances the head past expired entries (@custom:emits ReservationExpired for each one), removes the user from any prior queue position so a single user holds at most one live reservation across all labels, and enqueues a fresh entry (@custom:emits ReservationQueued). The enqueue rejects with @custom:reverts AlreadyReserved when the user already holds a reservation that was not cleared by the prior removal and with @custom:reverts QueueFull when the per-label queue has reached MAX_RESERVATION_QUEUE. Cross-chain callers pass the ABI-encoded reservation tuple as the call's payload, which Solidity decodes directly.

function reserveBaseName(BaseReservation calldata params) external override onlyRoot;

Parameters

reserveBaseNameOnly

Enqueues only the full/base-name reservation for a user.

Callable only under a substrate Root origin (otherwise @custom:reverts NotRoot). This is the second step of the split gateway flow: @custom:function reserveLiteName mints the lite username first, then this function reserves the full/base label in a separate transaction so proof-size stays below per-call limits. Reverts with @custom:reverts InvalidBaseLabel when the label is empty, non-canonical, digit-suffixed, or governance-reserved, and with

Note: reverts: BaseNameAlreadyRegistered when the label already has an owner on the registrar and so could never be claimed. The caller remains agnostic about backend batching; it simply exposes a small retryable primitive.

function reserveBaseNameOnly(BaseNameReservation calldata params) external override onlyRoot;

Parameters

_reserveLite

Lite-only mint shared by @custom:function reserveLiteName and the lite leg of @custom:function reserveBaseName.

Gateway attestation is the authority for personhood on this path; the on-chain precompile is not consulted. The dotted-format check accepts only stem.NN, then PopRules classification must place the flattened label outside the governance-reserved tier before minting; any non-reserved two-digit lite label is accepted regardless of stem length. Takes the @custom:struct LiteRegistration struct directly so both call sites pass the same payload shape: the typed entrypoint forwards its own params, the reserveBaseName entrypoint forwards params.lite.

function _reserveLite(IPopRules rules, LiteRegistration calldata params) internal;

registerBaseName

Registers a full-person username on behalf of the supplied user.

Callable only under a substrate Root origin (otherwise @custom:reverts NotRoot). The base label must satisfy the DNS-label shape and be a true base label with no trailing digits (otherwise @custom:reverts InvalidBaseLabel), and the label must not classify as governance-reserved (otherwise @custom:reverts InvalidBaseLabel). The gateway also defers to PopRules as the single cross-flow authority: when PopRules carries a live base-name slot held by another user (stamped by the public commit-reveal flow or this controller's prior queue head), the call reverts @custom:reverts NotHolder before any queue mutation. Two orthogonal axes drive the state machine. The reservation axis treats the user as claiming if and only if they hold the live head-of-queue reservation on the base label: a claim wipes the entire queue, releases the PopRules slot, and @custom:emits BaseNameClaimed; a non-claim silently relinquishes any pending entry the user holds and @custom:emits StandaloneNameRegistered. Advancing the queue head past expired entries @custom:emits ReservationExpired for each one. The chat-key axis selects whether a fresh key is persisted on the resolver or the new entry inherits its key from a prior lite-person username. The fresh-key branch rejects a chat key whose length is neither zero nor CHAT_KEY_LENGTH (otherwise

Notes:

• reverts: InvalidChatKey). The LiteUsername branch validates the lite label's NAMEXX shape (otherwise @custom:reverts InvalidLiteLabel), requires the registrant to own the lite token (otherwise @custom:reverts LiteLabelNotOwnedByUser), reads the lite node's chat key from the resolver and copies it across; if the lite node carries no chat key the inherited value is empty and the full node's chat-key write is silently skipped (the LiteToFullLinked event still fires). @custom:emits LiteToFullLinked alongside the registration event. On a warm-path mint the event order is

• emits: NameRegistered first (from the inner mint), then

function registerBaseName(FullRegistration calldata params) external override onlyRoot;

Parameters

expireReservation

Permissionlessly removes expired entries from the head of a reservation queue.

Permissionless on purpose: anyone (typically a UI or a bot) can poke a stale queue so the next live head takes over without waiting for the next gateway call. Validates the DNS-label shape of reservedBaseLabel (otherwise @custom:reverts InvalidBaseLabel) and @custom:emits ReservationExpired for every expired entry reaped from the head. Only base-shaped labels (no trailing digits) ever key a reservation queue, so a lite-shaped label still passes the shape check but resolves to an empty queue and the call is a no-op.

function expireReservation(string calldata reservedBaseLabel) external override;

relinquishReservation

Lets the caller voluntarily drop their own active reservation.

Reverts with @custom:reverts NoActiveReservation when the caller holds no live reservation. On success the caller's entry is removed from its queue and

Note: emits: ReservationRelinquished is emitted; if the removed entry was the queue head, head advancement may additionally @custom:emits ReservationExpired for any stale entries reaped behind it.

function relinquishReservation() external override;

claimLabelStore

Settles the caller's own pending claims into their LabelStore.

Convenience for a user settling their own store: equivalent to

Notes:

• function: settlePendingClaims with msg.sender and a bounded batch. The caller deploys and pays for their store on the first write. Settles at most one bounded batch so the call cannot exceed the block gas limit; moreRemaining reports whether the caller still holds unsettled entries, in which case they call again. Emits the same

• emits: PendingClaimSettled and @custom:emits NameRegistered as

function claimLabelStore() external override returns (bool moreRemaining);

Returns

settlePendingClaims

Settles up to limit of a user's pending claims, writing each stashed label into the user's LabelStore and deploying that store when the user has none yet.

Permissionless: any caller may settle any user's claims and bears the full cost, including the LabelStore storage deposit, which pallet-revive charges to the transaction signer. Settlement is never destructive: the name is already minted, so this only completes the deferred label write. Each settled entry is removed from the queue and the user leaves the pending-claim enumeration set once their queue empties. At most limit entries are processed so a large queue cannot exceed the block gas limit; moreRemaining reports whether entries are left for a follow-up call, and a limit of zero settles nothing. Writes are idempotent on an already-locked store slot, so a claim whose label was independently written settles harmlessly. Emits

Note: emits: PendingClaimSettled and @custom:emits NameRegistered per settled entry, with settledBy set to the caller so a third-party settlement is distinguishable from a self-settlement.

function settlePendingClaims(
    address user,
    uint256 limit
)
    external
    override
    returns (uint256 settledCount, bool moreRemaining);

Parameters

Returns

_settlePending

Shared settlement loop behind @custom:function claimLabelStore and

Settles up to limit of the user's pending claims, deploying the store on the first write, and removes the user from the enumeration set once their queue empties.

Note: function: settlePendingClaims.

function _settlePending(
    address user,
    uint256 limit
)
    internal
    returns (uint256 settledCount, bool moreRemaining);

_settlePendingLabel

Writes a single pending label into the user's store, deploying the store lazily.

The store is created only when there is a label to write, so a caller who settles an empty queue never leaves a fresh store behind with nothing in it. Returns the (possibly newly deployed) store so the caller threads it through the remaining entries.

function _settlePendingLabel(
    IStoreFactory factory,
    address store,
    address user,
    string memory label
)
    internal
    returns (address);

isReservedForClaim

Returns whether a label currently has a live reservation at the queue head.

Validates the DNS-label shape of reservedBaseLabel (otherwise

Note: reverts: InvalidBaseLabel) before inspecting the queue.

function isReservedForClaim(string calldata reservedBaseLabel)
    external
    view
    override
    returns (bool reserved, address holder);

setReservationDuration

Updates the reservation duration used to decide when queue entries expire.

Owner-gated (otherwise @custom:reverts OwnableUnauthorizedAccount); emits

Note: emits: ReservationDurationSet on success.

function setReservationDuration(uint64 duration) external override onlyOwner;

reservationMeta

Returns the queue metadata (head, tail) for labelhash.

Read-only accessor over the per-label reservation queue. head == tail means the queue is empty; active entries occupy [head, tail). Exposed on the interface because invariant tests and off-chain consumers (dotli, dweb) use it to enumerate live queue state without scanning storage.

function reservationMeta(bytes32 labelhash)
    external
    view
    override
    returns (uint64 head, uint64 tail);

Parameters

Returns

reservationEntry

Returns the queue entry at index for labelhash.

Sparse storage: a zero entryOwner means the slot was relinquished, expired and reaped, or never written. Callers pair this with @custom:function reservationMeta to walk the live window [head, tail).

function reservationEntry(
    bytes32 labelhash,
    uint64 index
)
    external
    view
    override
    returns (address entryOwner, uint64 joinedAt);

Parameters

Returns

userReservation

Returns user's current reservation pointer.

A zero labelhash on the returned struct means the user holds no reservation; index is meaningful only when labelhash is non-zero.

function userReservation(address user)
    external
    view
    override
    returns (UserReservation memory reservation);

Parameters

Returns

pendingClaims

Returns a paginated slice of a user's pending claims in queue order.

An empty array means the user has no pending claims at offset. Each entry carries its mintedAt; the settlement deadline is mintedAt + reservationDuration. An offset past the end returns an empty array rather than reverting, and a page holds at most DotnsConstants.MAX_PAGE_SIZE entries.

function pendingClaims(
    address user,
    uint256 offset,
    uint256 limit
)
    external
    view
    override
    returns (PendingClaim[] memory claims);

Parameters

Returns

pendingClaimCountOf

Returns the number of pending claims currently staged for user.

function pendingClaimCountOf(address user) external view override returns (uint256 count);

Parameters

Returns

pendingClaimUserCount

Returns the number of users with at least one live pending claim.

Exact live count, not an all-time tally: fully settled users are removed from the enumeration set so off-chain consumers can page through every stalled user without filtering.

function pendingClaimUserCount() external view override returns (uint256 count);

Returns

pendingClaimUsers

Returns a paginated slice of users with at least one live pending claim.

Pair with @custom:function pendingClaims to read each user's stashed entries. Ordering is not chronological; callers MUST NOT assume mintedAt is monotonic across the slice. Returns an empty array when offset is past the live count, and a page holds at most DotnsConstants.MAX_PAGE_SIZE entries.

function pendingClaimUsers(
    uint256 offset,
    uint256 limit
)
    external
    view
    override
    returns (address[] memory users);

Parameters

Returns

reservedBaseLabelOf

Returns the base label a reservation queue is keyed under.

Reverse lookup from the bytes32 queue key to its label string, so a consumer that observed a queue by labelhash (for example from a reservation event) can recover the human-readable label without holding its preimage. Returns an empty string when no reservation was ever enqueued under labelhash.

function reservedBaseLabelOf(bytes32 labelhash)
    external
    view
    override
    returns (string memory baseLabel);

Parameters

Returns

supportsInterface

function supportsInterface(bytes4 interfaceId)
    public
    view
    override(ERC165Upgradeable, IERC165)
    returns (bool);

version

Returns implementation version.

function version() external pure virtual returns (string memory versionString);

Returns

_completeGatewayRegistration

Mints a name, wires forward registry, persists PoP-flow records (chat key, lite link) on the PoP resolver, and either writes the label into the owner's existing LabelStore or stashes a pending claim when the owner has none yet.

The mint + forward-registry pair is delegated to

Notes:

• function: RegistrationUtils.registerAndStore so this flow and the public commit-reveal flow share exactly one implementation of that sequence. The label is passed empty so the registrar does not deploy a LabelStore; substrate Root cannot run the LabelStore constructor under pallet-revive. PoP-flow per-name records (chat key, lite link) are persisted eagerly on @custom:contract IDotnsPopResolver here, before the label is written, so the resolver carries the full identity record from mint time regardless of whether the owner already has a LabelStore. The Store stays labels-only. Warm path emits @custom:emits NameRegistered immediately; the cold path emits @custom:emits PendingClaimStashed at mint and defers

• emits: NameRegistered to @custom:function settlePendingClaims when the claim settles.

function _completeGatewayRegistration(
    address user,
    string memory label,
    bytes32 labelhash,
    bytes32 node,
    bytes memory chatKeyBytes,
    bytes32 liteLabelhash
)
    internal;

_writeRecord

Writes a name's label into store.

Single canonical persistence step shared by the warm gateway path and

Note: function: settlePendingClaims. The store key is node, matching the registrar's _writeOwnerLabel convention. Idempotent on already-locked slots so a user whose store was pre-populated under the same node (e.g. by a sibling protocol flow) can still settle their pending claim without bricking on LabelAlreadyExists.

function _writeRecord(address store, bytes32 node, string memory label) internal;

Parameters

_stashPendingClaim

Appends a deferred binding for user and adds them to the enumeration set.

The Root gateway origin cannot deploy the user's LabelStore, so deferred names pile up in _pendingClaimQueue until a signed-origin @custom:function settlePendingClaims writes them. Adding the user to the set is idempotent, so repeat stashes keep a single enumeration entry. Emits @custom:emits PendingClaimStashed.

function _stashPendingClaim(address user, string memory label, bytes32 labelhash) internal;

_isExpired

Returns whether a queue entry is expired relative to block.timestamp.

function _isExpired(uint64 joinedAt) internal view returns (bool);

_enqueueReservation

Appends a new reservation entry to the tail of the queue for labelhash.

Reverts if the queue is full or the user already holds a reservation. When the enqueued entry is the new head of an empty queue, the controller also reserves the base name on PopRules so the public commit-reveal flow sees the reservation through its existing priceWithCheck guard. Subsequent waiters only live in the local queue until they are promoted.

function _enqueueReservation(
    IPopRules rules,
    bytes32 labelhash,
    string memory baseLabel,
    address user
)
    internal;

_clearQueue

Wipes the entire reservation queue for labelhash and releases the corresponding PopRules reservation.

Used when a holder claims their reservation: every waiter is evicted and their per-user tracking state is cleared, and PopRules is told the slot is free so future public registrations are unblocked (the claim itself just minted the name, so there is nothing left to reserve).

function _clearQueue(bytes32 labelhash) internal;

_advanceExpiredHead

Advances the queue head past every expired entry at the head of the queue.

Reset semantics matter: when the queue empties (head catches tail), the meta slot is deleted AND the PopRules base-name slot is released, so the public commit-reveal flow can register the label again. When a new live head emerges, PopRules is re-synced to that head so reservations cannot be paid around by another address. Emits

Note: emits: ReservationExpired once per expired entry reaped from the head.

function _advanceExpiredHead(bytes32 labelhash) internal;

_removeUserFromQueue

Removes user from whichever reservation queue they currently occupy.

For a head removal, we delete the entry without bumping meta.head and delegate the advance to _advanceExpiredHead. Its existing zero-owner skip walks past the freshly-deleted slot, and its head != meta.head branch fires the PopRules resync in the one place head promotion is actually handled. Non-head removals leave the queue shape intact, so no advance or resync is needed.

function _removeUserFromQueue(address user) internal;

_validateLiteLabel

Validates a lite-person NAMEXX label and derives (labelhash, node).

function _validateLiteLabel(string memory liteLabel)
    internal
    view
    returns (bytes32 labelhash, bytes32 node);

_validateBaseLabel

Validates a base (full-person) DNS label and derives (labelhash, node).

function _validateBaseLabel(string calldata baseLabel)
    internal
    view
    returns (bytes32 labelhash, bytes32 node);

_validateReservableBaseLabel

Validates a base label as reservable and returns its hashes.

Shared by both reservation entrypoints so the guard cannot drift between them. Runs three checks and reverts on the first failure, before any reservation state is mutated: the label must classify outside the governance-reserved tier and be a base name, be a canonical single label, and have no owner on the registrar. The last check is the fix for a reservation queued over an already-registered name: the queue keys by stem, so such a reservation could never be redeemed yet would lock every two-digit variant of the stem for the full reservation window. exists (owner set) mirrors exactly what makes the eventual claim's mint revert, so a label that passes here is one a claim can still register.

function _validateReservableBaseLabel(
    IPopRules rules,
    string calldata baseLabel
)
    internal
    view
    returns (bytes32 labelhash, bytes32 node);

_requireValidChatKey

Reverts when a non-empty chat key is not exactly CHAT_KEY_LENGTH bytes.

Mirrors the resolver's own length gate so the gateway sees a controller-local InvalidChatKey revert before any mint state is written.

function _requireValidChatKey(bytes memory chatKey) internal pure;

_popResolver

Resolves the PoP resolver via the protocol registry.

function _popResolver() internal view returns (IDotnsPopResolver);

_popRules

Resolves the PopRules contract via the protocol registry.

function _popRules() internal view returns (IPopRules);

_storeFactory

Resolves the Store factory via the protocol registry.

function _storeFactory() internal view returns (IStoreFactory);

_registrar

Resolves the registrar via the protocol registry.

function _registrar() internal view returns (IDotnsRegistrar);

_syncPopRulesToHead

Writes the new head of the queue into PopRules so the public commit-reveal flow rejects registrations of this base name for anyone other than newHead.

Callers guarantee newHead is non-zero (the queue holds a live entry) and that _reservedBaseLabel[labelhash] is non-empty (any non-empty queue had its first head write the slot). The release-then-reserve pair satisfies PopRules' ownership gate on reserveBaseNameForPop.

function _syncPopRulesToHead(bytes32 labelhash, address newHead) internal;

_releasePopRulesSlot

Clears the PopRules slot and the local label bookkeeping when the queue empties (claim, last-relinquish, last-expire).

function _releasePopRulesSlot(bytes32 labelhash) internal;

_onlyRoot

Internal check enforcing a substrate Root origin.

Authorises a call when @custom:function SystemUtils.originIsRoot is true, and reverts with NotRoot otherwise. msg.sender is deliberately not consulted: a Root origin has no account behind it, so reading msg.sender traps. The same applies to anything reachable from an onlyRoot entrypoint.

function _onlyRoot() internal view;

_authorizeUpgrade

Function that should revert when msg.sender is not authorized to upgrade the contract. Called by {upgradeToAndCall}. Normally, this function will use an xref:access.adoc[access control] modifier such as {Ownable-onlyOwner}.

function _authorizeUpgrade(address) internal onlyOwner {}

function _authorizeUpgrade(address newImplementation) internal override onlyOwner;

DotnsPopLens

Git Source

Inherits: IDotnsPopLens

Title: DotnsPopLens

Read-only view over PoP identity data.

Stateless beyond the protocol registry it holds, and never mints or settles. It composes each field from the contract that owns it: names from the owner's LabelStore and the controller's pending queue, ownership from the registrar, chat keys and links from the PoP resolver, and label classification from PopRules. Living outside the controller keeps the controller within the contract-size limit and keeps the registrar the single source of ownership truth. Deployed as a plain contract through the CREATE3 factory, so its address is deterministic and it can be redeployed on a read change without touching stored state.

Note: security-contact: admin@parity.io

Constants

_protocolRegistry

Protocol-level address registry used to resolve every sibling contract.

IDotnsProtocolRegistry internal immutable _protocolRegistry

Functions

constructor

Binds the lens to the protocol registry it reads through.

constructor(IDotnsProtocolRegistry registry) ;

Parameters

protocolRegistry

The protocol registry the lens resolves siblings through.

function protocolRegistry() external view override returns (address registry);

Returns

liteNamesOf

Lists the lite-person names currently owned by user.

Reads the user's LabelStore labels and pending claims, keeps the lite-person shaped ones, and re-checks each against registrar.ownerOf so a name transferred away drops out and a name transferred in shows under its current owner. Ordering follows the store then the pending queue. An offset past the end returns an empty array rather than reverting, and a short return means the slice ended. A gateway name transferred before it settles has its label in no store, so it cannot appear here and is reachable only by node via @custom:function nameDetailByNode. Gas grows with the account's holdings, so call it off-chain. A page holds at most DotnsConstants.MAX_PAGE_SIZE entries, and the pending portion covers up to that many staged claims.

function liteNamesOf(
    address user,
    uint256 offset,
    uint256 limit
)
    external
    view
    override
    returns (Name[] memory names);

Parameters

Returns

fullNamesOf

Lists the full-person names currently owned by user.

Same ownership-verified read as @custom:function liteNamesOf, keeping base-shaped labels instead of lite-shaped ones.

function fullNamesOf(
    address user,
    uint256 offset,
    uint256 limit
)
    external
    view
    override
    returns (Name[] memory names);

Parameters

Returns

liteNameCountOf

Counts the lite-person names currently owned by user.

Uses the same ownership-verified read as @custom:function liteNamesOf; counting scans the account's holdings, so gas grows with them. Call it off-chain.

function liteNameCountOf(address user) external view override returns (uint256 count);

Parameters

Returns

fullNameCountOf

Counts the full-person names currently owned by user.

Uses the same ownership-verified read as @custom:function fullNamesOf; counting scans the account's holdings, so gas grows with them. Call it off-chain.

function fullNameCountOf(address user) external view override returns (uint256 count);

Parameters

Returns

nameDetail

Returns the full on-chain record for a name given its label string.

Resolves the node internally, so a caller holding only the string needs no namehash implementation. Never reverts on an unknown name: absent fields read as zero or empty. This overload can populate fullClaim because it holds the label and so its labelhash.

function nameDetail(string calldata name) external view override returns (NameDetail memory);

Parameters

Returns

nameDetailByNode

Returns the full on-chain record for a name given its node.

The node cannot be inverted to its labelhash, so fullClaim is populated only when the label is independently resolvable from the node and reads zero otherwise; every other field is resolved directly. Never reverts on an unknown node.

function nameDetailByNode(bytes32 node) external view override returns (NameDetail memory);

Parameters

Returns

profileOf

Returns an account-level summary of a user's PoP state.

O(1) facts only; lite and full name counts are read separately via

Note: function: liteNameCountOf and @custom:function fullNameCountOf because those scan the account's holdings. Never reverts.

function profileOf(address user) external view override returns (PopProfile memory profile);

Parameters

Returns

_matchesShape

Whether label belongs in the lite listing (wantLite) or the full listing.

A lite-person label is a single label with two trailing digits; a full-person label is any other single label. The two sets are disjoint and together cover every single label, so one predicate drives both listings.

function _matchesShape(string memory label, bool wantLite) internal pure returns (bool);

_countNames

Counts the names currently owned by user that match the requested shape.

Walks the user's LabelStore (settled names) then their pending claims, keeping only shape matches still owned by user on the registrar. A pending entry already written into the store by a sibling flow is skipped so it is not counted twice.

function _countNames(address user, bool wantLite) internal view returns (uint256 count);

_pageNames

Returns a page of user's owned names matching the requested shape.

Same ownership-verified walk as @custom:function _countNames, in the same order (store then pending), skipping the first offset matches and returning up to limit entries. limit is clamped to DotnsConstants.MAX_PAGE_SIZE to bound the memory and the scan.

function _pageNames(
    address user,
    uint256 offset,
    uint256 limit,
    bool wantLite
)
    internal
    view
    returns (Name[] memory names);

_ownedBy

Whether node is a minted name currently owned by user.

Guards the ownerOf call with exists so a missing token returns false rather than reverting, keeping the listing reads total.

function _ownedBy(
    IDotnsRegistrar registrar,
    bytes32 node,
    address user
)
    internal
    view
    returns (bool);

_detail

Gathers a name's record from the registrar, PoP resolver, and PopRules.

Reads defensively so an unminted or unsettled name yields zeroed fields instead of reverting. fullClaim is left for the caller because it needs the labelhash, which is recoverable from the label string but not from the node alone. tier classifies the label shape and is skipped for an empty label.

function _detail(bytes32 node) internal view returns (NameDetail memory detail);

_pendingClaims

Reads a bounded page of user's pending claims from the controller.

The listings scan this page in memory; it holds up to DotnsConstants.MAX_PAGE_SIZE staged claims, which the reads document as their pending-portion bound.

function _pendingClaims(address user)
    internal
    view
    returns (IDotnsPopController.PendingClaim[] memory claims);

_controller

Resolves the PoP controller via the protocol registry.

function _controller() internal view returns (IDotnsPopController);

_registrar

Resolves the registrar via the protocol registry.

function _registrar() internal view returns (IDotnsRegistrar);

_storeFactory

Resolves the store factory via the protocol registry.

function _storeFactory() internal view returns (IStoreFactory);

_popResolver

Resolves the PoP resolver via the protocol registry.

function _popResolver() internal view returns (IDotnsPopResolver);

_popRules

Resolves the PopRules contract via the protocol registry.

function _popRules() internal view returns (IPopRules);

DotnsRegistrar

Git Source

Inherits: Initializable, UUPSUpgradeable, OwnableUpgradeable, ERC721Upgradeable, IDotnsRegistrar

Title: Dotns Registrar

ERC721-backed registrar implementing permanent name ownership.

Deliberately policy-free. Transfers are supported to allow ownership changes without registry hooks, and the registrar itself does not encode pricing, reservations, or PoP gating; those live in the controllers and @custom:contract IPopRules. The fee-on-transfer hook in _update is a thin enforcement layer that consults the escrow.

Note: security-contact: admin@parity.io

State Variables

controllers

Mapping of authorised controllers.

Controllers may call register. Keyed by the shared baseline @custom:contract IDotnsController interface so the registrar doesn't depend on any specific controller shape. Commit-reveal, PoP, and future controllers coexist here so long as they implement the baseline interface.

Note: oz-retyped-from: mapping(IDotnsRegistrarController => bool)

mapping(IDotnsController controller => bool exists) public controllers

protocolRegistry

Protocol-level address registry for all DotNS contracts.

Used to resolve sibling contract addresses (store factory, controller, registry) without storing individual references.

IDotnsProtocolRegistry public protocolRegistry

__gap

Reserved storage space to allow for layout changes in the future.

uint256[50] private __gap

Functions

onlyController

Restricts function access to authorised controllers.

modifier onlyController() ;

constructor

Note: oz-upgrades-unsafe-allow: constructor

constructor() ;

initialize

Initialises the registrar.

Uses OpenZeppelin upgradeable initialisers and is callable once through the UUPS proxy; direct calls on the implementation revert with @custom:reverts InvalidInitialization because _disableInitializers runs in the constructor, and any nested call outside an active initialiser scope reverts with @custom:reverts NotInitializing.

function initialize(
    string calldata name,
    string calldata symbol,
    IDotnsProtocolRegistry registry
)
    external
    initializer;

addController

Adds an authorised controller.

Typed against the baseline IDotnsController (not a concrete subtype) so a single authorisation surface accepts every controller flavour (commit-reveal, PoP gateway, future variants) without per-flavour setters. Owner-gated (otherwise

Note: reverts: OwnableUnauthorizedAccount); emits @custom:emits ControllerAdded on success.

function addController(IDotnsController controller) external onlyOwner;

removeController

Removes an authorised controller.

Mirrors the @custom:function addController baseline-typed signature so any registered controller can be revoked through the same entry point. Owner-gated (otherwise

Note: reverts: OwnableUnauthorizedAccount); emits @custom:emits ControllerRemoved on success.

function removeController(IDotnsController controller) external onlyOwner;

available

Returns whether a registration call may proceed for id.

Signals two distinct paths to the controller. Returns true when the owner slot is empty (a fresh @custom:function register call may mint) OR when the current owner is the configured escrow and the released position's redeem window has elapsed (the controller must then route through @custom:function IDotnsNameEscrow.reclaim instead of

Note: function: register, because register calls _mint which rejects existing tokens). All other holders return false. The controller distinguishes the two true cases via @custom:function exists. Escrow custody inside the redeem window returns false: that window belongs to the previous holder, who may still @custom:function IDotnsNameEscrow.redeem the name, and reclaim would revert until it elapses. Clients wanting the exact moment a released name becomes registrable should read redeemableUntil from

function available(uint256 id) public view override returns (bool isAvailable);

register

Registers a name permanently.

Permanence is by construction: there is no expire, renew, or release path on the registrar. Custody only moves via ERC721 transfers (which the registrar polices via the fee-on-transfer hook) or via escrow reclaim. Restricted to authorised controllers (otherwise @custom:reverts NotController) and rejects ids that are not available (otherwise @custom:reverts NameNotAvailable). Emits @custom:emits NameRegistered on success.

function register(
    uint256 id,
    address owner,
    string calldata label
)
    external
    override
    onlyController;

Parameters

labelOf

Returns the human-readable label a token was registered with.

Canonical state source for the label string; any client that holds a node or tokenId can resolve the original label in one view call without scanning registration events. Returns the empty string when the token does not exist.

function labelOf(uint256 tokenId) external view override returns (string memory);

quoteTransferFee

Quotes the additional native fee required to transfer a token to to.

Returns the fee from @custom:function PopRules.transferFloor: the name's own price as the maximum of (i) the reach component charged when the recipient does not meet the label's required tier and (ii) the downgrade component charged when the recipient tier is strictly below the sender tier. Self-transfers and escrow-touching transfers (release into escrow, reclaim out of escrow) return zero. A token whose sender has no stored label also returns zero because there is no label-derived price to charge against; this covers gateway-cold PoP mints (the controller passes an empty label to @custom:function register so substrate Root does not have to deploy a LabelStore) until the user settles via

Notes:

• function: IDotnsPopController.claimLabelStore. Because settlement writes the label into the original claimant's store, a transfer that happens before settlement leaves the recipient with no label entry and the zero-fee branch persists for that token under all future holders. A token registered with no label that is moved off-chain prior to settlement therefore carries no PoP-tier transfer friction. Off-chain consumers integrating PoP mints should treat

• reverts: ERC721InvalidReceiver, an unminted tokenId with

function quoteTransferFee(
    uint256 tokenId,
    address to
)
    external
    view
    override
    returns (uint256 requiredFee);

transferFrom

Subject to the same fee-on-transfer gate as the safe overloads; reverts with

Note: reverts: TransferFeeRequired when the recipient owes a non-zero transfer fee and the caller has not forwarded it as msg.value.

function transferFrom(
    address from,
    address to,
    uint256 tokenId
)
    public
    payable
    override(ERC721Upgradeable, IDotnsRegistrar);

safeTransferFrom

Subject to the same fee-on-transfer gate as the four-argument overload; reverts with

Note: reverts: TransferFeeRequired when the recipient owes a non-zero transfer fee and the caller has not forwarded it as msg.value.

function safeTransferFrom(
    address from,
    address to,
    uint256 tokenId
)
    public
    payable
    override(ERC721Upgradeable, IDotnsRegistrar);

safeTransferFrom

The registrar's _update hook consults @custom:function PopRules.transferFloor to compute the required transfer fee; if the caller does not forward at least that amount as msg.value, the transfer reverts with @custom:reverts TransferFeeRequired. The payable modifier on every transfer overload exists so the fee can be forwarded in the same call.

function safeTransferFrom(
    address from,
    address to,
    uint256 tokenId,
    bytes memory data
)
    public
    payable
    override(ERC721Upgradeable, IDotnsRegistrar);

version

Returns implementation version.

function version() external pure virtual returns (string memory versionString);

Returns

exists

Returns whether a given token id has been minted.

function exists(uint256 tokenId) external view override returns (bool tokenExists);

_exists

Checks whether a token ID exists.

function _exists(uint256 tokenId) internal view returns (bool);

_onlyController

Internal function to check for controller access.

function _onlyController() internal view;

_update

Transfers tokenId from its current owner to to, or alternatively mints (or burns) if the current owner (or to) is the zero address. Returns the owner of the tokenId before the update. The auth argument is optional. If the value passed is non 0, then this function will check that auth is either the owner of the token, or approved to operate on the token (by the owner). Emits a {Transfer} event. NOTE: If overriding this function in a way that tracks balances, see also {_increaseBalance}.

function _update(
    address to,
    uint256 tokenId,
    address auth
)
    internal
    override
    returns (address from);

_syncRecipientStore

Mirrors the sender's label entry into the recipient's LabelStore.

function _syncRecipientStore(
    IStoreFactory factory,
    address to,
    address from,
    uint256 tokenId
)
    internal;

_readLabelFor

Reads the full name (label.tld) for tokenId from holder's LabelStore using a caller-supplied factory.

function _readLabelFor(
    IStoreFactory factory,
    uint256 tokenId,
    address holder
)
    private
    view
    returns (string memory fullName);

_readLabel

Reads the full name for tokenId from holder's LabelStore via fresh lookups.

Used by external view functions where caching the factory is not yet established; the hot transfer path uses @custom:function _readLabelFor with a cached factory.

function _readLabel(
    uint256 tokenId,
    address holder
)
    private
    view
    returns (string memory fullName);

_escrow

Resolves the configured name escrow address from the protocol registry.

function _escrow() private view returns (address escrow);

_popRules

Resolves the configured PoP rules contract from the protocol registry.

function _popRules() private view returns (IPopRules rules);

_storeFactory

Resolves the configured store factory from the protocol registry.

function _storeFactory() private view returns (IStoreFactory factory);

_writeOwnerLabel

Writes the canonical full name into owner's LabelStore keyed by bytes32(tokenId).

Caller (@custom:function register) is responsible for short-circuiting on empty label; the factory is a protocol-critical dependency and is assumed non-zero (a zero return from the registry would have already broken every other call site).

function _writeOwnerLabel(address owner, uint256 tokenId, string calldata label) private;

_quoteTransferFee

Quotes the friction fee required for a transfer.

Required fee is the name's own price returned by @custom:function PopRules.transferFloor. It is paid by the sender on every downward or cross-reach transfer and settles to the protocol fee pot. Any prior deposit travels with the NFT: the escrow rebinds the position to the new holder rather than refunding the sender, so transferring a funded name forfeits the locked deposit to the recipient. Self-transfers and escrow-touching transfers return zero.

function _quoteTransferFee(
    address from,
    address to,
    uint256 tokenId
)
    private
    view
    returns (address escrow, uint256 transferFee, uint256 requiredFee);

_quoteTransferFeeFor

Quotes the transfer floor reusing a caller-cached registry and store factory.

Hot-path variant used by @custom:function _update. Returns (0, 0) for any escrow-touching move or when the sender holds no label entry; otherwise reads the canonical label and delegates to @custom:function PopRules.transferFloor.

function _quoteTransferFeeFor(
    IDotnsProtocolRegistry registry,
    IStoreFactory factory,
    bool isEscrowTouching,
    address from,
    address to,
    uint256 tokenId
)
    private
    view
    returns (uint256 transferFee, uint256 requiredFee);

_authorizeUpgrade

Function that should revert when msg.sender is not authorized to upgrade the contract. Called by {upgradeToAndCall}. Normally, this function will use an xref:access.adoc[access control] modifier such as {Ownable-onlyOwner}.

function _authorizeUpgrade(address) internal onlyOwner {}

function _authorizeUpgrade(address newImplementation) internal override onlyOwner;

DotnsRegistrarController

Git Source

Inherits: Initializable, UUPSUpgradeable, DotnsRoleManager, ReentrancyGuardTransient, IDotnsRegistrarController

Title: Dotns Registrar Controller

Allocates top-level labels using a commit reveal scheme.

Orchestrates allocation, PoP validation, pricing enforcement, forward registry wiring, default reverse resolution, and immutable store writing. Tokenisation: the minted ERC721 tokenId is uint256(node), where node = namehash(tldNode, labelhash). The registry stores a sentinel owner (address(0)) for tokenised nodes and derives ownership from the ERC721 registrar for authorisation.

Note: security-contact: admin@parity.io

Constants

MAX_ALLOWED_COMMITMENT_AGE

Upper bound for commitment validity to cap storage griefing risk.

uint256 public constant MAX_ALLOWED_COMMITMENT_AGE = 7 days

State Variables

minCommitmentAge

Minimum age a commitment must reach before reveal.

uint256 public minCommitmentAge

maxCommitmentAge

Maximum age after which a commitment expires.

uint256 public maxCommitmentAge

commitments

Stores Mapping of commitment hashes to timestamp committed.

mapping(bytes32 hash => uint256 timestamp) public commitments

committedPricingVersion

Cost-model version stamped on a commitment at commit time.

Recorded from the registry's current version when commit runs, so the reveal can bind a registration to the version that was current then. A caller cannot commit against an arbitrary earlier, cheaper version: the reveal rejects a pricingVersion that differs from this stamp.

mapping(bytes32 hash => uint256 version) public committedPricingVersion

whiteList

Whitelist for addresses allowed to call registerReserved.

mapping(address user => bool isWhiteListed) public whiteList

protocolRegistry

Protocol-level address registry for all DotNS contracts.

IDotnsProtocolRegistry public protocolRegistry

__gap

Reserved storage space to allow for layout changes in the future.

uint256[49] private __gap

Functions

onlyWhiteListedOrOwner

Restricts calls to whitelisted addresses or the owner.

Used to gate registerReserved, which allows registering reserved names without PoP checks or payment. Necessary so the owner (or a whitelisted operator) can seed reserved names on behalf of users who are already known and verified and do not need PoP checks.

modifier onlyWhiteListedOrOwner() ;

onlyWhitelistOperatorOrOwner

modifier onlyWhitelistOperatorOrOwner() ;

constructor

Note: oz-upgrades-unsafe-allow: constructor

constructor() ;

initialize

Initialises the registrar controller.

Callable once through the UUPS proxy; direct calls on the implementation revert with @custom:reverts InvalidInitialization, and any nested call outside an active initialiser scope reverts with @custom:reverts NotInitializing. Validates the commitment window bounds: minAge must be strictly positive (otherwise

Notes:

• reverts: MinCommitmentAgeZero) so a reveal cannot land in the same block as its commit; maxAge must exceed minAge (otherwise

• reverts: MaxCommitmentAgeTooLow) and must stay within MAX_ALLOWED_COMMITMENT_AGE (otherwise @custom:reverts MaxCommitmentAgeTooHigh) before wiring the protocol registry.

function initialize(
    IDotnsProtocolRegistry registry,
    uint256 minAge,
    uint256 maxAge
)
    external
    initializer;

available

Returns whether a label is available for registration.

Validates the canonical DNS-label shape (otherwise @custom:reverts InvalidLabel) and rejects labels below the minimum-length policy with

Note: reverts: LabelTooShort before checking ERC721 availability on the registrar.

function available(string calldata label) public view override returns (bool);

makeCommitment

Computes the commitment hash for a registration.

Uses abi.encode so the variable-width label is length-prefixed and the boundary between label and the fixed-width owner, secret, reserved, maxPrice, and pricingVersion fields is unambiguous, binding the commitment to the exact tuple. The price ceiling and cost-model version are part of that tuple, so neither can be altered between commit and reveal.

function makeCommitment(Registration calldata registration)
    public
    pure
    override
    returns (bytes32 commitment);

commit

Submits a commitment for a future registration.

Idempotent over expiry: re-committing an unexpired hash reverts with

Note: reverts: UnexpiredCommitmentExists (front-running guard); a hash whose stored timestamp has passed maxCommitmentAge overwrites the slot so storage cannot be permanently griefed. The expiry boundary is inclusive on the commit side (committedAt + maxCommitmentAge <= block.timestamp overwrites) and exclusive on the reveal side (register rejects at the same instant with @custom:reverts CommitmentTooOld), so the slot is overwritable from exactly the timestamp at which reveal begins rejecting it. Stamps the cost model's current version on the commitment, so the reveal binds to the version live now and rejects a pricingVersion bound to an earlier one with @custom:reverts PricingVersionMismatch. Emits @custom:emits NameCommitted on success.

function commit(bytes32 commitment) external override;

_currentPricingVersion

Reads the cost model's current version through the protocol registry.

Resolved at commit time so the stamp binds the version live then, not at reveal.

function _currentPricingVersion() internal view returns (uint256 pricingVersion);

Returns

register

Registers a name after the commitment delay.

Validates the label shape (otherwise @custom:reverts InvalidLabel), rejects labels below the minimum length policy (@custom:reverts LabelTooShort), and ERC721 availability (otherwise @custom:reverts NameNotAvailable), then consumes the prior commitment, which fails with @custom:reverts CommitmentNotFound when no commitment exists for the supplied registration, @custom:reverts CommitmentTooNew before minCommitmentAge, and

Note: reverts: CommitmentTooOld past maxCommitmentAge, and finally resolves the configured escrow address from the protocol registry (otherwise

function register(Registration calldata registration) external payable override nonReentrant;

_settleEscrow

Settles every escrow side-effect of a successful registration.

Extracted to keep register under the stack-depth ceiling. On a direct registration the full chargeAmount lands in the refundable deposit position keyed to nameOwner. On a cross-payer registration the deposit position is seeded with a zero amount so the release lifecycle stays reachable, and the same chargeAmount routes to the protocol fee pot via depositProtocolFee keyed to msg.sender as the payer.

function _settleEscrow(
    address escrow,
    uint256 tokenId,
    address nameOwner,
    bool isDirect,
    uint256 chargeAmount
)
    internal;

isWhiteListed

Checks if the given address is whitelisted to call registerReserved.

function isWhiteListed(address who) external view override returns (bool);

whiteListAddress

Adds or removes an address from the whitelist for registerReserved.

Callable by the owner or an account holding DotnsConstants.WHITELIST_OPERATOR_ROLE; any other caller reverts with @custom:reverts IDotnsRoleManager.NotRoleOrOwner. Emits

Note: emits: WhiteListed on success.

function whiteListAddress(
    address who,
    bool whiteListStatus
)
    external
    override
    onlyWhitelistOperatorOrOwner;

registerReserved

Registers a name after the commitment delay.

Whitelisted issuance path used to seed reserved labels at zero base cost: skips the PoP price check and the escrow deposit, but reuses the same commit-reveal pipeline so the same anti-front-running guarantees apply. Restricted to whitelisted callers and the owner (otherwise @custom:reverts NotWhiteListedOrOwner). Validates the label shape (otherwise @custom:reverts InvalidLabel) and ERC721 availability (otherwise

Notes:

• reverts: NameNotAvailable), then consumes the prior commitment, which fails with

• emits: NameRegistered on success.

function registerReserved(Registration calldata registration)
    external
    override
    onlyWhiteListedOrOwner
    nonReentrant;

supportsInterface

Returns true if this contract implements the interface defined by interfaceId. See the corresponding https://eips.ethereum.org/EIPS/eip-165#how-interfaces-are-identified[ERC section] to learn more about how these ids are created. This function call must use less than 30 000 gas.

function supportsInterface(bytes4 interfaceId)
    public
    view
    override(DotnsRoleManager, IERC165)
    returns (bool);

_validatedLabelNode

Validates label shape and derives (labelhash, node).

Delegates hashing to @custom:contract LabelUtils so the assembly sequence lives in exactly one place across the codebase. Error ownership stays on this interface: shape violations revert with InvalidLabel(); labels below the minimum length revert with LabelTooShort(label) so off-chain consumers can distinguish "shape-valid but below the policy minimum" from "shape-valid but already minted".

function _validatedLabelNode(string calldata label)
    internal
    view
    returns (bytes32 labelhash, bytes32 node);

_requireAvailableLabel

function _requireAvailableLabel(string calldata label)
    internal
    view
    returns (IDotnsRegistrar registrar, bytes32 labelhash, bytes32 node);

_consumeCommitment

function _consumeCommitment(Registration calldata registration) internal;

_completeRegistration

Completes a commit-reveal registration: mints (or skips when reclaiming), wires forward registry, optionally sets the reverse record, and writes the owner's Store.

On a fresh mint the triad of mint + forward-registry + store-write is delegated to @custom:function RegistrationUtils.registerAndStore, the single canonical implementation shared across every DotNS registration flow. On a reclaim the mint step is skipped (the escrow has already moved custody) and only the registry wiring and store write run. Reverse-record setting and the priced-registration event stay here because they are commit-reveal-specific policy.

function _completeRegistration(
    Registration calldata registration,
    bytes32 labelhash,
    bytes32 node,
    uint256 baseCost,
    bool setReverseRecord,
    IDotnsReverseResolver reverse,
    bool isReclaim
)
    internal;

_escrow

Returns the configured name escrow from the protocol registry.

function _escrow() internal view returns (address escrow);

version

Returns implementation version.

function version() external pure virtual returns (string memory versionString);

Returns

_onlyWhiteListedOrOwner

Internal check enforcing whitelist-or-owner access.

function _onlyWhiteListedOrOwner() internal view;

_isSupportedRole

function _isSupportedRole(bytes32 role) internal view override returns (bool supported);

_authorizeUpgrade

Function that should revert when msg.sender is not authorized to upgrade the contract. Called by {upgradeToAndCall}. Normally, this function will use an xref:access.adoc[access control] modifier such as {Ownable-onlyOwner}.

function _authorizeUpgrade(address) internal onlyOwner {}

function _authorizeUpgrade(address newImplementation) internal override onlyOwner;

IDotnsController

Git Source

Inherits: IERC165

Title: IDotnsController

Baseline interface implemented by every controller authorised on DotnsRegistrar.

Marker interface that types DotnsRegistrar.controllers so every authorised caller (public commit-reveal, PoP gateway, any future privileged flow) fits the same mapping and the same addController / removeController signatures without forcing a common call surface. Extending @custom:contract IERC165 lets the registrar (or any observer) runtime-check which concrete controller interface a given address implements.

Note: security-contact: admin@parity.io

IDotnsPopController