IDotnsNameWhitelist

Git Source

Title: IDotnsNameWhitelist

Interface for the pre-launch name whitelist. A name is Open until governance either reserves it or a claim is accepted for it. Several beneficiaries may claim the same Open name, each with a reason, and governance accepts one as the winner.

Callers never supply a hash. Every entry point takes the bare label and derives the node from the label and the TLD in the protocol registry, so a caller cannot supply a mismatched hash. Claims are keyed by the beneficiary user, not the submitter, so a relayer or a cross-chain sovereign account can submit a claim on a user's behalf and the name still binds to that user. All state is on-chain and queryable through views; no event indexing is required. Governance is Root or the owner. Substrate Root has no address, so the governance gates check originIsRoot before reading msg.sender. Operators are signed role holders for day-to-day approvals; the controllers hold only the consume hook.

Note: security-contact: admin@parity.io

Functions

requestName

Claims label for user.

Permissionless within the window; the submitter may differ from user. Requires the name Open, the window open, user non-zero, a canonical label, user without an existing claim, and fewer than maxClaimants claims on the name.

Notes:

• reverts: WindowClosed, @custom:reverts NameNotOpen, @custom:reverts ZeroUser,

• reverts: InvalidLabel, @custom:reverts ReasonTooLong,

• reverts: AlreadyClaimed, or @custom:reverts TooManyClaimants.

• emits: NameRequested.

function requestName(string calldata label, string calldata reason, address user) external;

Parameters

accept

Accepts user's claim as the winner of label.

Restricted to an operator, the owner, or Root. Requires user's claim Requested. Sets the name Claimed with user the winner and clears every claim on the name, rejecting the losers. @custom:reverts NotRequested. @custom:emits NameAccepted for the winner and

Note: emits: NameRejected for each loser.

function accept(string calldata label, address user) external;

Parameters

reject

Rejects user's pending claim on label without resolving the name.

Restricted to an operator, the owner, or Root. Requires the claim Requested.

Note: reverts: NotRequested. @custom:emits NameRejected.

function reject(string calldata label, address user) external;

Parameters

grantName

Grants label to user directly, without a prior claim.

Restricted to an operator, the owner, or Root. Requires the name Open, user non-zero and a canonical label. Sets the name Claimed with user the winner and clears any pending claims. @custom:reverts NameNotOpen, @custom:reverts ZeroUser or

Notes:

• reverts: InvalidLabel. @custom:emits NameAccepted, and

• emits: NameRejected for each cleared claim.

function grantName(string calldata label, address user) external;

Parameters

grantNames

Grants several labels to one user directly.

Restricted to an operator, the owner, or Root. Applies @custom:function grantName to each, at most maxGrantBatch labels per call.

Note: reverts: TooManyLabels when labels exceeds the batch cap.

function grantNames(string[] calldata labels, address user) external;

Parameters

revokeName

Resets label to Open, clearing any winner and claims.

Restricted to an operator, the owner, or Root. Resolves a Claimed or claim-holding name; a Reserved name is released through @custom:function setReserved, not here.

Notes:

• reverts: NothingToRevoke when the name is not Claimed and holds no claims.

• emits: NameRevoked, and @custom:emits NameRejected for each cleared claim.

function revokeName(string calldata label) external;

Parameters

setReserved

Reserves or releases label.

Restricted to Root or the owner. Reserving requires the name Open and clears any pending claims, rejecting each; releasing requires it Reserved. @custom:reverts NameNotOpen or @custom:reverts NotReserved. @custom:emits NameReserved or @custom:emits NameUnreserved. @param label Bare label.

function setReserved(string calldata label, bool reserved) external;

Parameters

consume

Removes the win on label as registrant registers it.

Restricted to the registrar controllers resolved through the protocol registry. Resets the name to Open. @custom:reverts NotController for any other caller and

Notes:

• reverts: NotWinner when label is not won by registrant.

• emits: NameConsumed.

function consume(string calldata label, address registrant) external;

Parameters

setWindow

Sets the request window relative to the current time.

Restricted to Root or the owner. Opens at block.timestamp + startsIn for duration.

Note: reverts: BadWindow when duration is zero. @custom:emits WindowSet.

function setWindow(uint64 startsIn, uint64 duration) external;

Parameters

setOperator

Grants or revokes the operator role for account.

Restricted to Root or the owner. Root has no address, so governance uses this rather than the owner-only role-admin path. @custom:emits IAccessControl.RoleGranted on grant and @custom:emits IAccessControl.RoleRevoked on revoke.

function setOperator(address account, bool enabled) external;

Parameters

setMaxClaimants

Sets the live-claim cap per name.

Restricted to Root or the owner. The cap is bounded by DotnsConstants.WHITELIST_MAX_CLAIMANTS_LIMIT, which bounds the resolution clear-loop.

Notes:

• reverts: MaxClaimantsOutOfRange when newMax is zero or above the ceiling.

• emits: MaxClaimantsSet.

function setMaxClaimants(uint16 newMax) external;

Parameters

setMaxReasonBytes

Sets the reason byte cap.

Restricted to Root or the owner, bounded by DotnsConstants.WHITELIST_MAX_REASON_LIMIT. @custom:reverts MaxReasonBytesOutOfRange when newMax is zero or above the ceiling. @custom:emits MaxReasonBytesSet.

function setMaxReasonBytes(uint256 newMax) external;

Parameters

setMaxGrantBatch

Sets the cap on labels per grantNames call.

Restricted to Root or the owner, bounded by DotnsConstants.WHITELIST_MAX_GRANT_BATCH_LIMIT. @custom:reverts MaxGrantBatchOutOfRange when newMax is zero or above the ceiling. @custom:emits MaxGrantBatchSet.

function setMaxGrantBatch(uint16 newMax) external;

Parameters

maxClaimants

Returns the live-claim cap per name.

function maxClaimants() external view returns (uint16 cap);

Returns

maxReasonBytes

Returns the reason byte cap.

function maxReasonBytes() external view returns (uint256 cap);

Returns

maxGrantBatch

Returns the cap on labels per grantNames call.

function maxGrantBatch() external view returns (uint16 cap);

Returns

statusOf

Returns the status of label.

function statusOf(string calldata label) external view returns (NameStatus status);

Parameters

Returns

isReserved

Returns whether label is reserved.

function isReserved(string calldata label) external view returns (bool reserved);

Parameters

Returns

granteeOf

Returns the winner of label, or the zero address when not Claimed.

function granteeOf(string calldata label) external view returns (address winner);

Parameters

Returns

isGrantedTo

Returns whether account won label.

The pair check the controllers use to admit a registrant. False for the zero address.

function isGrantedTo(
    string calldata label,
    address account
)
    external
    view
    returns (bool granted);

Parameters

Returns

claimOf

Returns user's claim on label.

function claimOf(string calldata label, address user) external view returns (Claim memory claim);

Parameters

Returns

claimantCount

Returns the number of live claims on label.

function claimantCount(string calldata label) external view returns (uint256 count);

Parameters

Returns

claims

Returns a page of claims on label for review.

Reads the canonical offset and limit window.

function claims(
    string calldata label,
    uint256 offset,
    uint256 limit
)
    external
    view
    returns (Claim[] memory page);

Parameters

Returns

nameCount

Returns the number of names with reserved, claimed or claim-holding state.

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

Returns

names

Returns a page of active names for review.

Reads the canonical offset and limit window. Iteration order is not stable.

function names(uint256 offset, uint256 limit) external view returns (NameView[] memory page);

Parameters

Returns

window

Returns the request window.

function window() external view returns (uint64 openAt, uint64 closeAt);

Returns

isWindowOpen

Returns whether requests are currently accepted.

function isWindowOpen() external view returns (bool open);

Returns

Events

NameRequested

Emitted when a beneficiary claims a name.

event NameRequested(bytes32 indexed node, address indexed user, string label, string reason);

NameAccepted

Emitted when a claim wins a name, including an operator direct grant.

event NameAccepted(bytes32 indexed node, address indexed user, string label);

NameRejected

Emitted when a claim is cleared without winning.

event NameRejected(bytes32 indexed node, address indexed user, string label);

NameRevoked

Emitted when a name is reset to Open by governance.

event NameRevoked(bytes32 indexed node, address indexed winner, string label);

NameConsumed

Emitted when a winner registers the name and its entry is consumed.

event NameConsumed(bytes32 indexed node, address indexed user, string label);

NameReserved

Emitted when governance withholds a name from claiming.

event NameReserved(bytes32 indexed node, string label);

NameUnreserved

Emitted when governance releases a reserved name back to Open.

event NameUnreserved(bytes32 indexed node, string label);

WindowSet

Emitted when the request window is set.

event WindowSet(uint64 openAt, uint64 closeAt);

Parameters

MaxClaimantsSet

Emitted when the live-claim cap is set.

event MaxClaimantsSet(uint16 maxClaimants);

Parameters

MaxReasonBytesSet

Emitted when the reason byte cap is set.

event MaxReasonBytesSet(uint256 maxReasonBytes);

Parameters

MaxGrantBatchSet

Emitted when the grant-batch cap is set.

event MaxGrantBatchSet(uint16 maxGrantBatch);

Parameters

Errors

ZeroUser

Thrown when a claim names the zero-address beneficiary.

error ZeroUser();

InvalidLabel

Thrown when a label is not a canonical single DNS label.

error InvalidLabel();

ReasonTooLong

Thrown when a reason exceeds maxReasonBytes.

error ReasonTooLong();

NameNotOpen

Thrown when a name is not Open and the action requires it.

error NameNotOpen(bytes32 node);

Parameters

AlreadyClaimed

Thrown when user already holds a claim on the name.

error AlreadyClaimed(bytes32 node, address user);

Parameters

TooManyClaimants

Thrown when a name already holds maxClaimants claims.

error TooManyClaimants(bytes32 node);

Parameters

MaxClaimantsOutOfRange

Thrown when the claim cap is set to zero or above DotnsConstants.WHITELIST_MAX_CLAIMANTS_LIMIT.

error MaxClaimantsOutOfRange();

MaxReasonBytesOutOfRange

Thrown when the reason cap is set to zero or above DotnsConstants.WHITELIST_MAX_REASON_LIMIT.

error MaxReasonBytesOutOfRange();

MaxGrantBatchOutOfRange

Thrown when the grant-batch cap is set to zero or above DotnsConstants.WHITELIST_MAX_GRANT_BATCH_LIMIT.

error MaxGrantBatchOutOfRange();

NotRequested

Thrown when a claim is not in the Requested status.

error NotRequested(bytes32 node, address user);

Parameters

NotReserved

Thrown when releasing a name that is not reserved.

error NotReserved(bytes32 node);

Parameters

NothingToRevoke

Thrown when revoking a name that is not Claimed and holds no claims.

error NothingToRevoke(bytes32 node);

Parameters

NotController

Thrown when consume is called by any address other than a registrar controller.

error NotController(address caller);

Parameters

NotWinner

Thrown when consume is called for a name not won by the registrant.

error NotWinner(address registrant, bytes32 node);

Parameters

BadWindow

Thrown when the request window is set with a zero duration.

error BadWindow();

WindowClosed

Thrown when a claim is made outside the open window.

error WindowClosed();

TooManyLabels

Thrown when grantNames is passed more than maxGrantBatch labels.

error TooManyLabels();

Structs

Claim

A claim by one beneficiary on one name.

user, status and requestedAt co-locate in one storage slot; submitter takes the next, and the dynamic reason is stored separately.

struct Claim {
    address user;
    ClaimStatus status;
    uint64 requestedAt;
    address submitter;
    string reason;
}

Properties

NameView

A name and its resolved state, for review.

struct NameView {
    bytes32 node;
    string label;
    NameStatus status;
    address winner;
}

Properties

NameRecord

Stored resolved state of a name.

status and winner are ordered first so the 1-byte enum and 20-byte address share one storage slot; the dynamic label is stored separately.

struct NameRecord {
    NameStatus status;
    address winner;
    string label;
}

Properties

Enums

NameStatus

Status of a name.

Open is the zero-value default: claimable, not reserved, not won. Reserved is withheld by governance. Claimed has a single winner.

enum NameStatus {
    Open,
    Reserved,
    Claimed
}

ClaimStatus

Status of a single claim on a name.

None is the zero-value default of an absent claim. Rejected is sticky: it is kept only when the beneficiary filed the claim themselves, so they cannot re-request; a claim filed on their behalf is deleted on rejection and does not bind them.

enum ClaimStatus {
    None,
    Requested,
    Rejected
}