Onchain subname architecture

The Namespace App lets ENS name owners activate a parent name and configure how other users can mint its subnames. Configuration options include:

• Base and custom pricing
• Reserved subnames
• Whitelists
• Token-gated access
• Deadline

Namespace supports issuing onchain subnames on Ethereum mainnet and L2 chains (currently Base and Optimism).

​

ENS name activation

The activation process differs depending on whether the ENS name owner chooses to issue subnames on Ethereum or an L2 chain.

​

Activation on Ethereum

Activating subnames on Ethereum involves four main steps:

1. Create Activation Configuration: The List Manager backend generates the activation configuration for the subname.
2. Approve Mint Controller: The owner grants approval to the Mint Controller smart contract. This is a one-time approval and does not need to be repeated for future names.
3. Wrap the Name: If the parent name is not yet wrapped, it must be wrapped before activation can proceed.
4. Verify Activation: The backend validates that all onchain steps (approval and wrapping) have been executed correctly.

​

Activation on L2 chains

Activating subnames on an L2 chain follows four key steps:

1. Create activation configuration: The List Manager backend generates the rules for the subname minting flow.
2. Deploy ERC-721 Registry: An ERC-721 registry contract is deployed on the chosen L2 chain to manage ownership of subnames.
3. Configure Resolver: A resolver supporting ENSIP-10 wildcard resolution is set and configured to enable flexible, scalable name resolution.
4. Verify Activation: The backend validates that all onchain steps (registry deployment and resolver setup) have been completed correctly.

​

Minting process

Mint preparation happens offchain, while ownership changes happen in an onchain transaction. The minter requests signed parameters from the Mint Manager service and uses them to call the configured mint contract on Ethereum or the listing’s L2 chain.

• Flexible listing rules: The service can evaluate reservations, allowlists, token requirements, deadlines, and pricing before signing parameters.
• Configuration updates: Listing rules can change without redeploying the mint contract, subject to the activated name’s onchain configuration.
• Onchain verification: The mint contract validates the signed parameters when the user submits the transaction.

​

Resolution process

​

Resolution on Ethereum

Since onchain subnames on Ethereum are part of the existing ENS contracts on mainnet, they resolve just like any other ENS name:

1. Fetch Resolver: Call getResolver on the ENS Registry to retrieve the resolver contract for namehash(name.eth).
2. Resolve Records: Call the required resolver function (addr, text, contenthash, etc.) on the resolver contract.

​

Resolution on L2 chains

Resolution on L2 chains relies on CCIP Read with ENSIP-10 wildcard resolution. ENSIP-10 defines a workflow that allows resolving subnames of a parent name, even if those subnames don’t technically exist on Ethereum. The process works as follows:

1. Query ENS Registry: The client queries the ENS Registry contract for the resolver address of the subname.
2. Fallback to Parent: If the resolver address is the zero address, the client strips the leftmost label and queries the Registry again for the parent name’s resolver.
3. Call Resolve: Once a resolver is found, the client calls resolve(name, data), where:
   • name is the DNS-encoded subname.
   • data is the encoded resolver function call.
4. Offchain Lookup Trigger: The resolver reverts with an OffchainLookup error (per [EIP-3668, CCIP-Read]), providing:
   • One or more URLs to query off-chain.
   • The call data required for resolution.
   • The address of the resolver contract to callback.
5. Offchain Data Fetch: The client performs an HTTPS request to the specified resolution gateway server.
6. Response Returned: The server processes the request offchain and returns signed resolution data with a callback function.
7. Callback Onchain: The client submits the signed response back to the resolver contract via the designated callback function.
8. Final Resolution: The resolver verifies the signature and returns the final resolved record (e.g., addr, text, or contenthash).

​

Next steps