DotnsNameWhitelist

Git Source

Inherits: Initializable, UUPSUpgradeable, DotnsRoleManager, IDotnsNameWhitelist

Title: DotnsNameWhitelist

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

Lives behind its own UUPS proxy with its own storage. Callers pass bare labels only; the contract derives the node from the label and the TLD held in the protocol registry, the same derivation the controllers use, so a caller can never supply a mismatched hash. Each entry keeps its label, request and decision timestamps, and status, and the node set is enumerable, so the whitelist is reviewable on-chain. Requests are user-facing; accepting, rejecting, direct granting, batch granting and revoking are operator or owner actions through the inherited @custom:contract DotnsRoleManager, with the owner appointing and removing @custom:function DotnsConstants.WHITELIST_OPERATOR_ROLE holders and keeping super-user access. The public and PoP controllers read the whitelist at mint time and never write to it. Entries are keyed by the node under the active TLD, which the deployment holds immutable for the whitelist's lifetime; a TLD change would strand existing entries under their old node.

Note: security-contact: admin@parity.io

State Variables

protocolRegistry

Protocol-level address registry for all DotNS contracts.

IDotnsProtocolRegistry public protocolRegistry

_grants

Entries keyed by the label's namehash under the active TLD.

mapping(bytes32 node => Grant grant) private _grants

_grantedNodes

Nodes with a live entry, kept enumerable so the whitelist can be reviewed.

EnumerableSet.Bytes32Set private _grantedNodes

_requestOpen

Timestamp requests start being accepted.

uint64 private _requestOpen

_requestClose

Timestamp requests stop being accepted.

uint64 private _requestClose

__gap

Reserved storage space to allow for layout changes in the future.

uint256[50] private __gap

Functions

onlyOperatorOrOwner

Restricts a call to an operator or the owner.

modifier onlyOperatorOrOwner() ;

onlyController

Restricts a call to a registrar controller resolved through the registry.

modifier onlyController() ;

constructor

Note: oz-upgrades-unsafe-allow: constructor

constructor() ;

initialize

Initialises the whitelist.

Callable once through the UUPS proxy; direct calls on the implementation revert with

Note: reverts: InvalidInitialization. Sets the deployer as owner and wires the protocol registry the node derivation reads the TLD from.

function initialize(IDotnsProtocolRegistry registry) external initializer;

Parameters

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 override onlyOwner;

Parameters

requestName

Requests label for the caller.

Records a Requested entry bound to the caller. Reverts with

Notes:

• reverts: WindowClosed outside the open window, with

• emits: NameRequested.

function requestName(string calldata label) external override;

Parameters

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 override onlyOperatorOrOwner;

Parameters

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 override onlyOperatorOrOwner;

Parameters

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
    override
    onlyOperatorOrOwner;

Parameters

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
    override
    onlyOperatorOrOwner;

Parameters

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 override onlyOperatorOrOwner;

Parameters

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 override onlyController;

Parameters

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 override returns (address grantee);

Parameters

Returns

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
    override
    returns (bool granted);

Parameters

Returns

grantOf

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

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

Parameters

Returns

grantCount

Returns the number of entries, of any status.

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

Returns

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
    override
    returns (Grant[] memory page);

Parameters

Returns

window

Returns the request window.

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

Returns

isWindowOpen

Returns whether requests are currently accepted.

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

Returns

_grant

Writes an Accepted entry for grantee, rejecting a name that already exists.

function _grant(string calldata label, address grantee) internal;

_decide

Moves a pending request to a terminal decision and stamps the decision time.

function _decide(
    string calldata label,
    GrantStatus decision
)
    internal
    returns (bytes32 node, address grantee);

_validateNew

Validates a canonical, unused label and returns its node.

function _validateNew(string calldata label) internal view returns (bytes32 node);

_nodeOf

Derives the namehash of label under the active TLD read from the registry.

function _nodeOf(string calldata label) internal view returns (bytes32 node);

_isWindowOpen

Returns whether the current time is within the open window.

function _isWindowOpen() internal view returns (bool open);

_clear

Removes an entry from both the map and the enumerable set.

function _clear(bytes32 node) internal;

_isSupportedRole

Returns whether role is recognised by the consuming contract.

Implemented by each consuming contract so unsupported role identifiers fail closed.

function _isSupportedRole(bytes32 role) internal pure override returns (bool supported);

_authorizeUpgrade

Restricts upgrades to the owner.

function _authorizeUpgrade(address newImplementation) internal override onlyOwner;