Integration Guide
Frontend-level

Frontend-level resolving

Resolving either domains to wallet addresses or vice versa in a JS/TS-based project is straightforward with our resolver library (opens in a new tab). It can be used either in a frontend project or in a server-side environment. On top, we also offer a specialized React-based library with multiple hooks for an even easier integration.

To test your integration, we recommend using our Aleph Zero testnet deployments & frontend. Please see our testnet documentation for details.

Examples

In the azero-id/resolver monorepo, we provide two running examples to better understand how to use our library:

Step undefined

Installation

Prerequisites

If you're setting up a new project, make sure to install the following requirements upfront:

Vanilla

bun add @azns/resolver-core
Peer dependencies

Depending on your package manager's setup, you might need to install the following peer dependencies as well: @polkadot/api @polkadot/api-contract @polkadot/util

React/Next.js

bun add @azns/resolver-core @azns/resolver-react
Peer dependencies

Depending on your package manager's setup, you might need to install the following peer dependencies as well: @azns/resolver-core @polkadot/api @polkadot/api-contract @polkadot/util loglevel

Step undefined

Resolving

The process of resolving either domains or wallet addresses is done by querying our Router contract via polkadot{.js} internally.

Vanilla

If we want to convert a domain name into a wallet address bound to that domain name, we can do the following by calling resolveDomainToAddress (opens in a new tab):

Resolve: Domain → Wallet address
import { SupportedChainId, resolveDomainToAddress } from '@azns/resolver-core'
 
const { address, error } = await resolveDomainToAddress('domains.tzero', {
  chainId: SupportedChainId.AlephZeroTestnet,
})
 
// Print result
if (error) console.log(error.message)
else console.log(address)

If we want to convert the wallet address to a registered primary domain name, we can do the following by calling resolveAddressToDomain (opens in a new tab):

Resolve: Wallet address → Primary domain
import { SupportedChainId, resolveAddressToDomain } from '@azns/resolver-core'
 
const { primaryDomain, error } = await resolveAddressToDomain(
  '5EeBxqQ7Kz6hcchEgkBn9ybBS4UaqGggi2Rq5weNyEZ9DjAK',
  {
    chainId: SupportedChainId.AlephZeroTestnet,
  },
)
 
// Print result
if (error) console.log(error.message)
else console.log(primaryDomain)

React/Next.js

If we want to convert a domain name into a wallet address bound to that domain name, we can do the following by calling useResolveDomainToAddress (opens in a new tab):

Resolve: Domain → Wallet address
import { SupportedChainId } from '@azns/resolver-core'
import { useResolveDomainToAddress } from '@azns/resolver-react'
 
// …
 
const { address, error } = useResolveDomainToAddress('domains.tzero', {
  chainId: SupportedChainId.AlephZeroTestnet,
})

If we want to convert the wallet address to a registered primary domain name, we can do the following by calling useResolveAddressToDomain (opens in a new tab):

Resolve: Wallet address → Primary domain
import { SupportedChainId } from '@azns/resolver-core'
import { useResolveAddressToDomain } from '@azns/resolver-react'
 
// …
 
const { primaryDomain, error } = useResolveAddressToDomain(
  '5EeBxqQ7Kz6hcchEgkBn9ybBS4UaqGggi2Rq5weNyEZ9DjAK',
  {
    chainId: SupportedChainId.AlephZeroTestnet,
  },
)

Options

All resolving functions take an options object as the second parameter, inheriting from the BaseResolveOptions (opens in a new tab) type:

/**
 * Custom options for `resolveAddressToDomain` and `resolveDomainToAddress`.
 * @param chainId Chain ID to use (default: `alephzero`, available: `alephzero`, `alephzero-testnet`, `development`).
 * @param customApi Custom API instance to use instead of creating the default one (faster and more memory efficient, if you already have an API instance)
 * @param customContractAddresses Custom contract addresses to overwrite the default ones. Mandatory for `development` network.
 * @param debug Enable debug logging.
 */
type BaseResolveOptions = {
  chainId: SupportedChainIds
  customApi?: ApiPromise
  customContractAddresses?: ContractAddresses
  debug?: boolean
}
 
/**
 * @param ignoreAddressPrefix If true, the current chain ss58 prefix will be ignored and the address will be decoded with any prefix
 */
type ResolveAddressOptions = BaseResolveOptions & {
  ignoreAddressPrefix?: boolean
}
 
/**
 * @param skipSanitization Uses the exact given domain w/o sanitization like lowercasing (default: false)
 */
type ResolveDomainOptions = BaseResolveOptions & {
  skipSanitization?: boolean
}
⚡

Performance tip: If you already have a polkadot{.js} API instance, pass it to the resolver as customApi as part of the options object.

IntroductionContract-level