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. The entire admin surface is substrate Root: the gates check originIsRoot and read no msg.sender, so Root's lack of an address is not a problem, and no signed account grants, revokes, reserves, or retunes a cap. 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 a substrate Root dispatch. 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 a substrate Root dispatch. 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 a substrate Root dispatch. 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 a substrate Root dispatch. 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 a substrate Root dispatch. 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 a substrate Root dispatch. 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 a substrate Root dispatch. Opens at block.timestamp + startsIn for duration. @custom:reverts BadWindow when duration is zero. @custom:emits WindowSet.

function setWindow(uint64 startsIn, uint64 duration) external;

Parameters

setMaxClaimants

Sets the live-claim cap per name.

Restricted to a substrate Root dispatch. 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 a substrate Root dispatch, 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 a substrate Root dispatch, 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 a direct governance 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

NotGovernance

Thrown when a governance-gated call is not a substrate Root dispatch.

The whitelist's whole admin surface is Root-only: no signed account, owner included, grants, revokes, reserves, or retunes a cap.

error NotGovernance();

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
}