IDotnsNameWhitelist

Title: IDotnsNameWhitelist

Interface for the pre-launch name whitelist that binds a name to the single address permitted to register it, tracking each name from request to decision.

The contract never accepts a caller-supplied hash. Every entry point takes the bare label and derives the node itself from the TLD held in the protocol registry, the same derivation the controllers use, so a malformed or mismatched hash cannot be smuggled in. Every entry keeps its bare label, request and decision timestamps, and status, and the node set is enumerable, so the whole whitelist is reviewable on-chain and by event log. Operator appointment and removal, and upgrades, are owner-gated through

Notes:

contract: DotnsRoleManager.
security-contact: admin@parity.io

Functions

setWindow

Sets the request window relative to the current time.

Restricted to the owner. The window opens at block.timestamp + startsIn and stays open for duration, so it can never open in the past. Reverts with

Note: reverts: BadWindow when duration is zero. Emits @custom:emits WindowSet with the resolved absolute timestamps.

function setWindow(uint64 startsIn, uint64 duration) external;

Parameters

Name	Type	Description
`startsIn`	`uint64`	Seconds from now until requests start being accepted.
`duration`	`uint64`	Seconds the window stays open.

requestName

Requests label for the caller.

Records a Requested entry bound to the caller. Reverts with

Notes:

reverts: WindowClosed outside the open window, with
reverts: AlreadyExists when the name already has a live entry, and with
reverts: InvalidLabel when label is not a canonical single label. Emits
emits: NameRequested.

function requestName(string calldata label) external;

Parameters

Name	Type	Description
`label`	`string`	Bare label to request.

accept

Accepts the pending request on label.

Restricted to an operator or the owner. Moves a Requested entry to Accepted and stamps the decision. Reverts with @custom:reverts NotRequested when the name is not pending. Emits @custom:emits NameAccepted.

function accept(string calldata label) external;

Parameters

Name	Type	Description
`label`	`string`	Bare label to accept.

reject

Rejects the pending request on label.

Restricted to an operator or the owner. Moves a Requested entry to Rejected and stamps the decision; the entry is kept for review. Reverts with

Notes:

reverts: NotRequested when the name is not pending. Emits
emits: NameRejected.

function reject(string calldata label) external;

Parameters

Name	Type	Description
`label`	`string`	Bare label to reject.

grantName

Grants label to grantee directly, without a prior request.

Restricted to an operator or the owner, and independent of the request window by design, so operators can provision names whether or not requests are open. Writes an Accepted entry with the request and decision timestamps set to now, for provisioning names to a chosen address. Reverts with @custom:reverts AlreadyExists when the name already has a live entry, with @custom:reverts ZeroGrantee on a zero grantee, and with

Notes:

reverts: InvalidLabel when label is not a canonical single label. Emits
emits: NameAccepted.

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

Parameters

Name	Type	Description
`label`	`string`	Bare label to grant.
`grantee`	`address`	Address permitted to register the name.

grantNames

Grants several labels to one grantee directly.

Restricted to an operator or the owner. Applies the same rules as

Note: function: grantName to each entry.

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

Parameters

Name	Type	Description
`labels`	`string[]`	Bare labels to grant.
`grantee`	`address`	Address permitted to register each name.

revokeName

Clears the entry on label, whatever its status.

Restricted to an operator or the owner. Reverts with @custom:reverts NotGranted when the name holds no entry. Emits @custom:emits NameRevoked.

function revokeName(string calldata label) external;

Parameters

Name	Type	Description
`label`	`string`	Bare label to clear.

consume

Removes the accepted grant on label as registrant registers it.

Restricted to the registrar controllers resolved through the protocol registry, so the entry is consumed exactly when its grantee registers the name. Reverts with

Note: reverts: NotController for any other caller and @custom:reverts NotGrantee when label is not accepted for registrant. Emits @custom:emits NameConsumed.

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

Parameters

Name	Type	Description
`label`	`string`	Bare label being registered.
`registrant`	`address`	Address registering the name.

granteeOf

Returns the address label is accepted for, or the zero address otherwise.

Non-zero only for an Accepted entry, so a pending or rejected name does not reserve.

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

Parameters

Name	Type	Description
`label`	`string`	Bare label to look up.

Returns

Name	Type	Description
`grantee`	`address`	Address permitted to register the name.

isGrantedTo

Returns whether account holds an accepted grant for 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

Name	Type	Description
`label`	`string`	Bare label to look up.
`account`	`address`	Address to test against the grant.

Returns

Name	Type	Description
`granted`	`bool`	True when `account` is the accepted grantee.

grantOf

Returns the full entry for label, including status and timestamps.

function grantOf(string calldata label) external view returns (Grant memory grant);

Parameters

Name	Type	Description
`label`	`string`	Bare label to look up.

Returns

Name	Type	Description
`grant`	`Grant`	The stored entry; a zeroed struct with `None` status when absent.

grantCount

Returns the number of entries, of any status.

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

Returns

Name	Type	Description
`count`	`uint256`	Entry count.

grants

Returns a page of entries for review.

Reads the canonical offset and limit window. An offset at or beyond

Note: function: grantCount returns an empty page; limit is clamped to the remaining entries. Iteration order is not stable across revokes.

function grants(uint256 offset, uint256 limit) external view returns (Grant[] memory page);

Parameters

Name	Type	Description
`offset`	`uint256`	Index of the first entry to return.
`limit`	`uint256`	Maximum number of entries to return.

Returns

Name	Type	Description
`page`	`Grant[]`	Entries in the window.

window

Returns the request window.

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

Returns

Name	Type	Description
`openAt`	`uint64`	Timestamp requests start being accepted.
`closeAt`	`uint64`	Timestamp requests stop being accepted.

isWindowOpen

Returns whether requests are currently accepted.

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

Returns

Name	Type	Description
`open`	`bool`	True when the current time is within the window.

Events

NameRequested

Emitted when a name is requested.

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

Parameters

Name	Type	Description
`node`	`bytes32`	Namehash of the label under the active TLD.
`grantee`	`address`	Address that requested the name.
`label`	`string`	Bare label requested.

NameAccepted

Emitted when a request is accepted, including an operator direct grant.

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

Parameters

Name	Type	Description
`node`	`bytes32`	Namehash of the label under the active TLD.
`grantee`	`address`	Address permitted to register the name.
`label`	`string`	Bare label accepted.

NameRejected

Emitted when a request is rejected.

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

Parameters

Name	Type	Description
`node`	`bytes32`	Namehash of the label under the active TLD.
`grantee`	`address`	Address whose request was rejected.
`label`	`string`	Bare label rejected.

NameRevoked

Emitted when an entry is cleared.

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

Parameters

Name	Type	Description
`node`	`bytes32`	Namehash of the label under the active TLD.
`grantee`	`address`	Address whose entry was cleared.
`label`	`string`	Bare label cleared.

NameConsumed

Emitted when a grantee registers their name and the entry is consumed.

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

Parameters

Name	Type	Description
`node`	`bytes32`	Namehash of the label under the active TLD.
`grantee`	`address`	Address that registered the name.
`label`	`string`	Bare label consumed.

WindowSet

Emitted when the request window is set.

event WindowSet(uint64 openAt, uint64 closeAt);

Parameters

Name	Type	Description
`openAt`	`uint64`	Timestamp requests start being accepted.
`closeAt`	`uint64`	Timestamp requests stop being accepted.

Errors

ZeroGrantee

Thrown when a grant is issued to the zero address.

error ZeroGrantee();

InvalidLabel

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

error InvalidLabel();

AlreadyExists

Thrown when requesting or granting a name that already has a live entry.

error AlreadyExists(bytes32 node);

Parameters

Name	Type	Description
`node`	`bytes32`	Namehash of the label under the active TLD.

NotRequested

Thrown when accepting or rejecting a name that is not in the Requested status.

error NotRequested(bytes32 node);

Parameters

Name	Type	Description
`node`	`bytes32`	Namehash of the label under the active TLD.

NotGranted

Thrown when clearing a name that holds no entry.

error NotGranted(bytes32 node);

Parameters

Name	Type	Description
`node`	`bytes32`	Namehash of the label under the active TLD.

NotController

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

error NotController(address caller);

Parameters

Name	Type	Description
`caller`	`address`	Rejected caller.

NotGrantee

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

error NotGrantee(address registrant, bytes32 node);

Parameters

Name	Type	Description
`registrant`	`address`	Address attempting to register the name.
`node`	`bytes32`	Namehash of the label under the active TLD.

BadWindow

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

error BadWindow();

WindowClosed

Thrown when a request is made outside the open window.

error WindowClosed();

Structs

Grant

A whitelist entry and its request-to-decision lifecycle.

grantee, requestedAt and status co-locate in one storage slot (20 + 8 + 1 bytes); decidedAt spills to the next; the dynamic label is stored separately.

struct Grant {
    address grantee;
    uint64 requestedAt;
    GrantStatus status;
    uint64 decidedAt;
    string label;
}

Properties

Name	Type	Description
`grantee`	`address`	Address permitted to register the name once accepted.
`requestedAt`	`uint64`	Timestamp the entry was requested.
`status`	`GrantStatus`	Lifecycle status; see GrantStatus.
`decidedAt`	`uint64`	Timestamp the entry was accepted or rejected; zero while `Requested`.
`label`	`string`	Bare label, kept for on-chain review.

Enums

GrantStatus

Lifecycle status of a whitelist entry.

None is the zero-value default of an absent entry, so a missing node reads as None rather than as a live status. Accepted is the only status the controllers admit for registration; Requested and Rejected do not reserve the name.

enum GrantStatus {
    None,
    Requested,
    Accepted,
    Rejected
}