Integrating Web3 Domain Registration: A Guide for Partners

SPACE ID offers a streamlined solution for partners to integrate .bnb, .arb, and .eth domain name registrations into their platforms. By leveraging the web3-name-sdk, you can design custom front-end interfaces that enable users to seamlessly acquire unique web3 domain names. Eligible partners may also earn commission fees for .arb and .bnb domains registered through their integrated portals.

Installation Process

To begin, install the web3-name-sdk alongside ethers v5 using npm or yarn. Ethers v6 introduces breaking changes and has limited adoption, so ethers v5 is recommended for compatibility.

Using npm:

npm install @web3-name-sdk/register [email protected]

Using yarn:

yarn add @web3-name-sdk/register [email protected]

For next.js projects, add the following configuration to next.config.js to transpile commonjs dependencies:

const nextConfig = {
  transpilePackages: ['@web3-name-sdk/register'],
}

Domain Registration Workflow

The registration process involves three key steps:

Availability Check: Verify if a desired domain is valid and available.
Fee Query: Determine the registration cost based on domain length and duration.
Registration Execution: Initiate the registration function with required parameters and fees.

Implementation Examples

BNB Domain Registration

import SIDRegister from '@web3-name-sdk/register'
import { providers } from 'ethers'

async function registerDomain(label: String) {
  if (window.ethereum) {
    const provider = new providers.Web3Provider(window.ethereum)
    await provider.send('wallet_switchEthereumChain', [{ chainId: '0x38' }])
    await provider.send('eth_requestAccounts', [])
    const signer = provider.getSigner()
    const address = await signer.getAddress()
    const register = new SIDRegister({ signer, chainId: 56 })
    const available = await register.getAvailable(label)
    const price = await register.getRentPrice(label, 1)
    await register.register(label, address, 1, {
      setPrimaryName: true,
      referrer: 'test.bnb'
    })
  }
}

ARB Domain Registration

import SIDRegister from '@web3-name-sdk/register'
import { providers } from 'ethers'

async function registerDomain(label: String) {
  if (window.ethereum) {
    const provider = new providers.Web3Provider(window.ethereum)
    await provider.send('wallet_switchEthereumChain', [{ chainId: '0xA4B1' }])
    await provider.send('eth_requestAccounts', [])
    const signer = provider.getSigner()
    const address = await signer.getAddress()
    const register = new SIDRegister({ signer, chainId: 42161 })
    const available = await register.getAvailable(label)
    const price = await register.getRentPrice(label, 1, {
      setPrimaryName: true,
      referrer: 'test.bnb'
    })
    await register.register(label, address, 1)
  }
}

Key Notes for BNB & ARB:

Label: The domain name without its TLD suffix (e.g., test for test.bnb).
Chain IDs: Use 56 for BNB and 42161 for ARB.
Primary Name: This is the name displayed in dapps using our name-resolving SDK. The setPrimaryName parameter defaults to false.
Referrer: The domain name of the referrer. Commission fees are sent to the address this domain resolves to. Ensure the domain has a set primary name and resolving address before use.

ETH Domain Registration

import SIDRegister from '@web3-name-sdk/register'
import { providers } from 'ethers'

async function registerEthDomain(label: String) {
  if (window.ethereum) {
    const provider = new providers.Web3Provider(window.ethereum)
    await provider.send('wallet_switchEthereumChain', [{ chainId: '0x1' }])
    await provider.send('eth_requestAccounts', [])
    const signer = provider.getSigner()
    const address = await signer.getAddress()
    const register = new SIDRegister({ signer, chainId: 1 })
    const available = await register.getAvailable(label)
    const price = await register.getRentPrice(label, 1)
    await register.register(label, address, 1, {
      onCommitSuccess: (waitTime) => {
        return new Promise(resolve => {
          setTimeout(resolve, waitTime * 1000)
        })
      }
    })
  }
}

Key Notes for ETH:

Label: The domain name without its TLD suffix.
Chain ID: Use 1 for the Ethereum mainnet.
Referrer & Primary Name: These features are not applicable to .eth registrations.
Commitment Step: .eth registration requires an additional commit transaction. The SDK handles this with a callback function, introducing a mandatory ~60-second wait after the initial commit before registration can complete.

For comprehensive technical details, always refer to the official npm package documentation.

Frequently Asked Questions

What is a Web3 domain name?
A Web3 domain name is a human-readable identifier that simplifies cryptocurrency transactions by replacing complex wallet addresses. It can also represent a digital identity across decentralized applications.

How do commission fees work for partners?
Partners integrating .arb and .bnb registrations can earn commissions by setting a referrer domain. The commission is automatically sent to the wallet address that the referrer domain name resolves to.

What does 'set as primary name' mean?
Setting a domain as a primary name means it will be the default identifier displayed for a user's wallet address in any dapp that integrates SPACE ID's name-resolution services. 👉 Explore more strategies for user engagement with primary names.

Why is there a wait time for .eth registrations?
The Ethereum Name Service (ENS) uses a commit-reveal scheme to prevent front-running and ensure fair domain registration. The ~60-second delay is a security feature of the protocol itself.

Can I integrate multiple domain types simultaneously?
Yes, the SDK supports integration for .bnb, .arb, and .eth domains. You will need to handle the appropriate chain switches and parameters for each network within your application's logic.

What are the common issues during integration?
Common issues often involve incorrect chain ID configuration, not properly handling the async commitment step for .eth, or misconfiguring the referrer domain. Always ensure your provider object and signer are correctly instantiated.