DotnsNameWhitelist

Git Source

Inherits: Initializable, UUPSUpgradeable, DotnsRoleManager, IDotnsNameWhitelist

Title: DotnsNameWhitelist

Pre-launch name whitelist. A name is Open until governance 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.

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 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 on a user's behalf and the name binds to that user. All state is on-chain and queryable through views; no event indexing is required. A name holds at most maxClaimants live claims, which bounds the loop that clears them on resolution. Resolving a name deletes its claims, refunding their storage deposit, so only reserved or won names persist. Governance is Root or the owner. Substrate Root has no address, so the governance gates check SystemUtils.originIsRoot, which is true through the proxy's delegatecall frame, before reading msg.sender. Operators are signed role holders for day-to-day approvals; the public and PoP controllers hold only the consume hook. Entries are keyed by the node under the active TLD, which the deployment holds immutable for the whitelist's lifetime.

Note: security-contact: admin@parity.io

State Variables

protocolRegistry

Protocol-level address registry for all DotNS contracts.

IDotnsProtocolRegistry public protocolRegistry

maxClaimants

Live-claim cap per name, tunable by governance within DotnsConstants.WHITELIST_MAX_CLAIMANTS_LIMIT.

uint16 public maxClaimants

maxGrantBatch

Cap on labels per grantNames call, tunable by governance within DotnsConstants.WHITELIST_MAX_GRANT_BATCH_LIMIT.

uint16 public maxGrantBatch

maxReasonBytes

Reason byte cap, tunable by governance within DotnsConstants.WHITELIST_MAX_REASON_LIMIT.

uint256 public maxReasonBytes

_names

Resolved state per name.

mapping(bytes32 node => NameRecord record) private _names

_claims

Claims per name, keyed by beneficiary.

mapping(bytes32 node => mapping(address user => Claim claim)) private _claims

_claimants

Beneficiaries with a live claim per name.

mapping(bytes32 node => EnumerableSet.AddressSet claimants) private _claimants

_activeNodes

Names holding reserved, claimed or claim-holding state, kept enumerable for review.

EnumerableSet.Bytes32Set private _activeNodes

_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

onlyGovernance

Restricts a call to Root or the owner.

Checks Root first so msg.sender, which traps under a Root origin, is read only for a signed caller.

modifier onlyGovernance() ;

onlyOperatorOrGovernance

Restricts a call to Root, the owner, or an operator.

modifier onlyOperatorOrGovernance() ;

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

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

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

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

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

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

Parameters

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,

• emits: NameRequested.

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

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

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

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

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

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

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

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

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

Parameters

statusOf

Returns the status of label.

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

Parameters

Returns

isReserved

Returns whether label is reserved.

function isReserved(string calldata label) external view override 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 override 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
    override
    returns (bool granted);

Parameters

Returns

claimOf

Returns user's claim on label.

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

Parameters

Returns

claimantCount

Returns the number of live claims on label.

function claimantCount(string calldata label) external view override 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
    override
    returns (Claim[] memory page);

Parameters

Returns

nameCount

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

function nameCount() external view override 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
    override
    returns (NameView[] 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

supportsInterface

function supportsInterface(bytes4 interfaceId)
    public
    view
    override(DotnsRoleManager)
    returns (bool supported);

_grant

Grants label to user directly, clearing any pending claims.

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

Parameters

_settle

Marks a name claimed for winner and clears its claims, rejecting the losers.

function _settle(bytes32 node, address winner, string calldata label) internal;

Parameters

_clearClaimants

Deletes every claim on a name, rejecting each claimant that is not winner.

function _clearClaimants(bytes32 node, address winner, string calldata label) internal;

Parameters

_activate

Records a name as active and stores its label the first time it is seen.

function _activate(bytes32 node, string calldata label) internal;

Parameters

_deactivate

Drops a name from the active set once it is Open with no claims.

function _deactivate(bytes32 node) internal;

Parameters

_nodeOf

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

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

Parameters

Returns

_isWindowOpen

Returns whether the current time is within the open window.

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

Returns

_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

Function that should revert when msg.sender is not authorized to upgrade the contract. Called by {upgradeToAndCall}. Normally, this function will use an xref:access.adoc[access control] modifier such as {Ownable-onlyOwner}.

function _authorizeUpgrade(address) internal onlyOwner {}

function _authorizeUpgrade(address newImplementation) internal override onlyOwner;