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
}