Controller

This section documents the parts of the ETHRegistrarController relevant to implementers of tools that interact with it. Functionality exclusive to the registrar owner is omitted for brevity.

The controller works exclusively with plaintext labels (eg, 'stefano' for 'stefano.dfi').

To prevent frontrunning, the ETHRegistrarController requires a commit/reveal process for new name registrations (but not for renewals). To register a name, the user must:

1. Generate a commitment hash from the name they want to register and a secret value.

2. Submit the commitment hash from #1 to the controller.

3. Wait for at least 1 minute, but no longer than 24 hours.

4. Submit a registration request for the name, along with the secret value from #1.

This process ensures that registrations cannot be frontrun unless the attacker is able to censor the user's transactions for at least 1 minute.

Read Operations

Get Minimum Commitment Age

uint constant public MIN_COMMITMENT_AGE;

This public constant provides the minimum commitment age, in seconds. A commitment can only be revealed after at least this many seconds have passed since it was mined.

DApps should fetch this constant rather than hardcoding the current value, as it's possible it will change with future releases.

Get Maximum Commitment Age

uint constant public MAX_COMMITMENT_AGE;

This public constant provides the maximum commitment age, in seconds. A commitment that was mined more than this number of seconds ago is no longer valid, and cannot be used to register a name.

DApps should fetch this constant rather than hardcoding the current value, as it's possible it will change with future releases.

Get Commitment Timestamp

mapping(bytes32=>uint) public commitments;

commitments stores a mapping from each submitted to commitment to the timestamp at which it was made. Callers wishing to validate that a commitment is valid before submitting a registration transaction should check this map first.

Get Registration Price

function price(string name, uint duration) view public returns(uint);

price returns the cost, in wei, to register or renew the provided name. Callers should note that this price may vary over time, particularly if the pricing oracle is relying on a fiat price conversion.

Callers should use this function to obtain registration costs to display to the user rather than calculating them internally, as future changes to the pricing may result in different pricing schemes, with registration cost depending on name length, or other variables.

Check Name Validity

function valid(string name) public view returns(bool);

valid returns true iff name is valid for registration with this controller (eg, it meets length requirements).

Check Name Availability

function available(string name) public view returns(bool);

available returns true iff the name is both valid and available for registration by this controller. Under the hood, this call uses the valid function (above) and the available function on the registrar contract, which checks for availability in both the legacy Defichain Domain registrar and current Defichain Domain registrar.

Callers should use this function to check if a name is available for registration, rather than the available function on the registrar contract, which does not check name length.

Calculate Commitment Hash

function makeCommitment(string name, address owner, bytes32 secret) pure public returns(bytes32);

makeCommitment generates and returns a commitment hash from a name label (eg, 'myname', not 'myname.dfi') owner, and secret value.

Write Operations

Submit Commitment

function commit(bytes32 commitment) public;

commit submits a pre-commitment generated by calling makeCommitment.

Register Name

function register(string name, address owner, bytes32 secret) public payable;

register registers a name. A valid registration request must meet the following criteria:

1. available(name) == true.

2. secret identifies a valid commitment (eg, commitments[makeCommitment(name, secret)] exists and is between 1 minute and 24 hours old.

3. msg.value >= price(name).

Emits the following event on a successful call:

event NameRegistered(string name, bytes32 indexed label, address indexed owner, uint cost);

A successful call also results in the Registrar emitting a Name Registered Event, and the Defichain Domain registry emitting a New Owner Event.