Deploying Registrar Contracts, Fuses, and TTLs

[seanmanik]

By Team ZkScholar

Suggestion: Improve Documentation for Creating a Subname Registrar

Creating a Subname Registrar opens up a world of possibilities, such as offering subnames to users on your on-chain social media platform. The current documentation for deploying registrar contracts can be found here: Deploying a Subname Registrar.

While the page provides useful information, there are several areas where more clarity would enhance the user experience. Below are some suggestions on how the documentation can be improved.

---

1. Clarify Argument Descriptions for setSubnodeRecord

The function setSubnodeRecord is essential, but understanding the exact values to input can be confusing for beginners. The provided example is as follows:

NameWrapper.setSubnodeRecord(bytes32 parentNode, string label, address owner, address resolver, uint64 ttl, uint32 fuses, uint64 expiry)

setSubnodeRecord(
    0x6cbc..., // The namehash of the parent node, e.g. "myname.eth"
    "sub", // The label of the subname to create
    0x1234..., // The address you want to assign ownership of the subname
    0x5678..., // The resolver address for the new subname
    0, // The TTL (Time to Live) for the subname
    65536, // The fuse bits to burn, combined using OR
    2021232060 // The expiry time for the subname
)

Several key concepts could benefit from further explanation:

namehash: What hashing mechanism is used to derive the namehash?

Example:
The namehash is a keccak-256 (also known as SHA-3) hash of a domain name. It is used to convert human-readable domain names into a format that can be stored and processed on the blockchain.

For the name myname.eth, you can derive the namehash as follows:

Name: myname.eth
Namehash: 0x6cbc4d3b285f2fa3c2c478e7b68ed0c75d89b2f2a85d5899918f9eb7b6765ad3

ttl: What is TTL, and what are the implications of setting it to 0?

Example:
TTL (Time to Live) refers to the lifespan of DNS records in seconds, dictating how long they can be cached by clients before they need to fetch updated data. Setting TTL to 0 means that the records must always be re-fetched and cannot be cached.

If you set TTL to 3600, the record can be cached for 1 hour:

expiry: In what format or units should this value be entered?

Example:
TTL (Time to Live) refers to the lifespan of DNS records in seconds, dictating how long they can be cached by clients before they need to fetch updated data. Setting TTL to 0 means that the records must always be re-fetched and cannot be cached.

The expiry is typically a Unix timestamp, which represents the number of seconds that have passed since January 1, 1970 (UTC). This timestamp indicates when the subname will expire.

Example: For an expiry date of January 1, 2025, you would convert it to a Unix timestamp:

Expiry Date: January 1, 2025
Unix Timestamp: 1735689600

This means that the subname will expire on January 1, 2025, at midnight UTC.

2. Provide an Example for Generating the fuses Argument

The fuses argument, described as being derived from the selected fuse bits combined using a bitwise OR, is crucial but lacks sufficient examples for beginners. Although there is a use case link explaining which fuses to burn, it would be extremely helpful to include a clear example of how to generate the fuses value.

For instance, the documentation mentions that "typically 65536 is used for an emancipated rental subname, or 327680 for an emancipated 'forever' name." Providing an example that illustrates:

• Which fuse bits correspond to each scenario
• How the OR operation is applied to arrive at these numbers

Example of OR Operation to Generate fuses Value:

Suppose we have the following fuse bits:

• Bit 16: 65536 (corresponds to "Cannot be emancipated")
• Bit 18: 262144 (corresponds to "Cannot be transferred")

To calculate the fuses value for an emancipated "forever" name (327680), we apply a bitwise OR on these values:

Bit 16:  00000000 00000001 00000000 00000000  (65536)
Bit 18:  00000000 00000100 00000000 00000000  (262144)
------------------------------------------------------
Result:  00000000 00000101 00000000 00000000  (327680)

Such an explanation would make it far easier for users to understand the process of generating the correct fuses value.

By expanding on these areas, the documentation will become more accessible to new users who wish to explore the potential of setting up Subname registrars.