IDotnsPopController

Git Source

Inherits: IDotnsController

Title: IDotnsPopController

Interface for the dedicated PoP controller orchestrating lite-person and full-person username issuance on behalf of the PoP gateway.

Deliberately disjoint from @custom:contract IDotnsRegistrarController. The two controllers coexist on @custom:contract DotnsRegistrar via its multi-controller affordance and neither imports the other. A full-person username collides through the registrar's ERC721 availability check (first-to-mint wins); a lite username is not a token, so it collides through

Notes:

• function: IDotnsRegistry.recordExists at its stem-under-container node (@custom:reverts LiteNameAlreadyIssued). Reservation queuing for reservedBaseLabel mirrors its live head into PopRules, so a queued stem also blocks the public commit-reveal flow, which reads that slot when it prices a name. Label formats: Lite-person usernames (first argument to @custom:function reserveBaseName and the liteLabel of a LinkKind.LiteUsername link) are a stem of lowercase ASCII letters, a separator, then exactly two digits (e.g. joseph.42) per

• function: StringUtils.isLitePersonLabel. The stem is stricter than a DNS label because the name a person chooses is restricted to letters; a stem short enough to be governance-reserved is rejected by classification, not by the shape. The label is stored in the form the gateway sends, which is the canonical form of the name, so nothing here normalises it. Full-person usernames (the label of @custom:function registerBaseName and the optional reservedBaseLabel of @custom:function reserveBaseName) are lowercase ASCII letters only, per @custom:function StringUtils.isPersonLabel (e.g. alice). That is the same rule a lite stem follows and is stricter than a DNS label: no hyphens and no interior digits, because a full-person name is also a name a person chose. A separator marks a lite label and is rejected everywhere else, so only the gateway can create a dotted name; a digit suffix on its own is not exclusive, since a public label may carry one directly. Cross-flow priority on the base stem is arbitrated by

• function: IPopRules.reserveBaseNameForPop.

• security-contact: admin@parity.io

Functions

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 Root origin (otherwise @custom:reverts NotRoot). The lite leg validates the stem.NN shape and requires the label to classify outside the governance-reserved tier (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 requires a letters-only person label, which is therefore also a true base label (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;

Parameters

reserveBaseNameOnly

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

Callable only under a 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, is not lowercase ASCII letters (so a hyphen or any digit rejects it), or is 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;

Parameters

reserveLiteName

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

Callable only under a Root origin (otherwise @custom:reverts NotRoot). The supplied label must satisfy the stem.NN shape and must classify outside the governance-reserved tier (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. A username that has already been issued reverts @custom:reverts LiteNameAlreadyIssued. On a warm-path mint

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

• emits: NameRegistered deferred to @custom:function settlePendingClaims when the claim settles. Cross-chain callers pass the ABI-encoded lite-registration tuple as the call's payload, which Solidity decodes directly.

function reserveLiteName(LiteRegistration calldata params) external;

Parameters

isPopIssued

Whether this controller issued label as a PoP identity.

Keyed by text, so it answers about a name rather than about a node. A lite label is issued as a subname (joseph beneath its numeric container 42) and a full-person label as a second-level name, so a caller holding a node must check that the node is the one label resolves to under those rules before reading this answer as being about what it holds; node identity is what names the object. Set at mint and never cleared, so it is unaffected by a name later becoming transferable; the soulbound flag is a transfer rule and cannot stand in for it.

function isPopIssued(string calldata label) external view returns (bool issued);

Parameters

Returns

registerBaseName

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

Callable only under a Root origin (otherwise @custom:reverts NotRoot). The base label must be a letters-only person label, and therefore a true base label, (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 (this controller's prior queue head, or a sibling controller's write), 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 stem.NN 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

• emits: BaseNameClaimed or @custom:emits StandaloneNameRegistered, then

• emits: LiteToFullLinked when applicable. On a cold-path mint

• emits: PendingClaimStashed replaces the initial @custom:emits NameRegistered; the deferred @custom:emits NameRegistered fires later from @custom:function settlePendingClaims. Cross-chain callers pass the ABI-encoded full-registration tuple as the call's payload, which Solidity decodes directly.

function registerBaseName(FullRegistration calldata params) external;

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 reservedBaseLabel as a letters-only person label (otherwise

Notes:

• reverts: InvalidBaseLabel) and @custom:emits ReservationExpired for every expired entry reaped from the head. A label carrying a digit or a hyphen is not a person label and

• reverts: InvalidBaseLabel, as does a lite label, since a separator is not one either. Only a letters-only label reaches the queue, and one that was never reserved resolves to an empty queue so the call is a no-op.

function expireReservation(string calldata reservedBaseLabel) external;

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;

isReservedForClaim

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

Validates reservedBaseLabel as a letters-only person label (otherwise

Note: reverts: InvalidBaseLabel) before inspecting the queue.

function isReservedForClaim(string calldata reservedBaseLabel)
    external
    view
    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;

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 use it to enumerate live queue state without scanning storage.

function reservationMeta(bytes32 labelhash) external view 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
    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
    returns (UserReservation memory reservation);

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 returns (string memory baseLabel);

Parameters

Returns

reservationDuration

Returns the window, in seconds, after which a queue or pending-claim entry lapses.

Governance-configurable via @custom:function setReservationDuration. Read by the lens to compute each pending claim's settlement deadline.

function reservationDuration() external view returns (uint64 duration);

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 is charged 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
    returns (uint256 settledCount, bool moreRemaining);

Parameters

Returns

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: settlePendingClaims.

function claimLabelStore() external returns (bool moreRemaining);

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
    returns (PendingClaim[] memory claims);

Parameters

Returns

pendingClaimCountOf

Returns the number of pending claims currently staged for user.

function pendingClaimCountOf(address user) external view 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 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
    returns (address[] memory users);

Parameters

Returns

Events

LiteNameReserved

Emitted when a lite-person username is registered via the PoP gateway.

event LiteNameReserved(bytes32 indexed labelhash, address indexed user, string label);

BaseNameClaimed

Emitted when a full-person username is claimed out of an existing reservation.

event BaseNameClaimed(bytes32 indexed labelhash, address indexed user, string label);

StandaloneNameRegistered

Emitted when a standalone full-person username is registered via the PoP gateway.

event StandaloneNameRegistered(bytes32 indexed labelhash, address indexed user, string label);

ReservationQueued

Emitted when a reservation entry is added to the queue for a base name.

event ReservationQueued(
    bytes32 indexed reservedLabelhash, address indexed user, uint64 position
);

Parameters

ReservationExpired

Emitted when a reservation entry is removed due to expiry.

event ReservationExpired(bytes32 indexed reservedLabelhash, address indexed user);

ReservationRelinquished

Emitted when a user voluntarily relinquishes their reservation.

event ReservationRelinquished(bytes32 indexed reservedLabelhash, address indexed user);

LiteToFullLinked

Emitted when a full-person username is linked to a lite-person username.

event LiteToFullLinked(bytes32 indexed fullLabelhash, bytes32 indexed liteLabelhash);

ReservationDurationSet

Emitted when the reservation duration is updated.

event ReservationDurationSet(uint64 duration);

NameRegistered

Emitted when a name is successfully registered via the PoP controller.

event NameRegistered(
    string indexed label, bytes32 indexed labelhash, address indexed owner, address store
);

Parameters

PendingClaimStashed

Emitted when a gateway-path mint defers its LabelStore write into the pending-claim mapping because the user has no store yet.

event PendingClaimStashed(address indexed user, bytes32 indexed labelhash, string label);

PendingClaimSettled

Emitted when a pending claim is written into a LabelStore.

Fires once per settled entry from @custom:function settlePendingClaims. settledBy is the caller: it equals user for a self-settlement and is any other address for a third-party settlement, so consumers can tell the two apart from the log alone.

event PendingClaimSettled(
    address indexed user, bytes32 indexed labelhash, address store, address indexed settledBy
);

Parameters

ReservationHeadAdvanced

Emitted when a reservation queue's head transitions to a new user, either via expiry of the prior head or via the explicit relinquish path.

event ReservationHeadAdvanced(bytes32 indexed labelhash, address indexed newHead);

Parameters

Errors

NotRoot

Thrown when a gated entrypoint is reached without a Root origin.

Carries no caller parameter: a Root origin has no account to report, and reading msg.sender under one traps.

error NotRoot();

InvalidLiteLabel

Thrown when a supplied lite-person label does not match stem.NN.

error InvalidLiteLabel();

InvalidBaseLabel

Thrown when a supplied base label is not a canonical DNS label.

error InvalidBaseLabel();

BaseNameAlreadyRegistered

Thrown when a reserved base label already has an owner on the registrar, so the queued reservation could never be redeemed at mint time.

error BaseNameAlreadyRegistered();

LiteNameAlreadyIssued

Thrown when a lite username is issued again while its subname already exists.

A lite name is issued once; re-issuing it would rehome the identity to a new owner and overwrite its records, so an existing subname is rejected rather than reassigned.

error LiteNameAlreadyIssued();

InvalidChatKey

Thrown when a supplied chat key is non-empty and not exactly 65 bytes long.

Mirrors the resolver's InvalidChatKeyLength so the controller surfaces a controller-local error before the mint runs.

error InvalidChatKey(uint256 length);

Parameters

NoActiveReservation

Thrown when a user tries to claim or relinquish a reservation that they do not hold.

error NoActiveReservation(address user);

QueueFull

Thrown when a reservation queue has reached its capacity.

error QueueFull(bytes32 labelhash);

AlreadyReserved

Thrown when attempting to enqueue a user who already has an active reservation.

error AlreadyReserved(address user, bytes32 labelhash);

NotHolder

Thrown when someone tries to mint a base label in standalone mode while another user holds the live head-of-queue reservation.

error NotHolder(address user, bytes32 labelhash);

LiteLabelNotOwnedByUser

Thrown when a lite-link inheritance does not match the registrar-side owner of the lite label.

Prevents identity hijack by ensuring the registrant on the full-name leg actually holds the prior lite identity whose chat key is being inherited.

error LiteLabelNotOwnedByUser(address user, bytes32 liteLabelhash);

Parameters

ReservationDurationTooLow

Thrown when @custom:function setReservationDuration is called with a value below the protocol minimum.

error ReservationDurationTooLow(uint64 duration);

Parameters

Structs

Link

Tagged union selecting the chat-key source for a full-person registration.

struct Link {
    LinkKind kind;
    string liteLabel;
    bytes chatKey;
}

Properties

UserReservation

Per-user reservation pointer: which queue the user sits in and where.

struct UserReservation {
    bytes32 labelhash;
    uint64 index;
}

Properties

ReservationEntry

Reservation queue entry: a user and the timestamp they joined the queue.

Packs into a single storage slot (20 + 8 bytes).

struct ReservationEntry {
    address owner;
    uint64 joinedAt;
}

ReservationQueueMeta

Metadata describing the occupied range of a reservation queue.

Uses monotonically increasing indices. Active entries occupy [head, tail); length = tail - head. Slots past head are deleted as the head advances so garbage never accumulates.

struct ReservationQueueMeta {
    uint64 head;
    uint64 tail;
}

PendingClaim

Deferred per-user binding of a freshly minted name to its LabelStore.

Recorded by the gateway path when the user has no LabelStore. The binding later settles via @custom:function settlePendingClaims, which deploys the store from a signed origin and writes the stashed label. PoP-resolver records (chat key, lite link) are persisted eagerly at mint time on @custom:contract IDotnsPopResolver, not at settlement, so the resolver carries the full identity record regardless of whether the user has settled their Store. A user accumulates one entry per deferred name: the Root gateway path cannot deploy a LabelStore (contract creation is forbidden from the Root origin), so it keeps stashing entries until a signed-origin @custom:function settlePendingClaims deploys the store and settles the entries. Each entry's deadline is measured from its own mintedAt against reservationDuration.

struct PendingClaim {
    string label;
    uint64 mintedAt;
}

Properties

LiteRegistration

Lite-person registration payload.

Single struct so the gateway can ABI-encode one tuple as the cross-chain payload and the contract decodes it directly out of msg.data. All fields are required; chatKey may be empty bytes to skip the resolver write.

struct LiteRegistration {
    string liteLabel;
    address user;
    bytes chatKey;
}

Properties

BaseReservation

Lite-person registration combined with an optional base-name reservation.

BaseReservation is a @custom:struct LiteRegistration plus a base-label reservation slot, expressed as composition rather than duplicated fields so internal helpers can consume the lite leg via params.lite without unpacking. The lite leg always runs; the reservation leg only runs when reservedBaseLabel is non-empty.

struct BaseReservation {
    LiteRegistration lite;
    string reservedBaseLabel;
}

Properties

BaseNameReservation

Base-name reservation payload for the split gateway flow.

This is the reservation-only primitive. The lite username mint is handled by

Notes:

• function: reserveLiteName, and LabelStore settlement is handled by

• function: settlePendingClaims.

struct BaseNameReservation {
    address user;
    string reservedBaseLabel;
}

Properties

FullRegistration

Full-person registration payload.

struct FullRegistration {
    string label;
    address user;
    Link link;
}

Properties

Enums

LinkKind

Discriminant for the Link union supplied to registerBaseName.

Selects the chat-key source for the full-person username. Orthogonal to whether the registration is a claim or standalone; that is derived from on-chain reservation state. None means the caller supplies a fresh chat key in link.chatKey. LiteUsername means the full-person username is linked to a prior lite-person username (link.liteLabel) and inherits its chat key.

enum LinkKind {
    None,
    LiteUsername
}