wns-utils

Utilities for the Wei Name Service (WNS). Resolve .wei names to Ethereum addresses, reverse resolve addresses to names, and more.

Zero runtime dependencies. Works in Node.js, browsers, and edge runtimes.

Install

npm install wns-utils

Usage

import { createWnsClient } from 'wns-utils'

const wns = createWnsClient()

// Resolve a .wei name to an address
const addr = await wns.resolve('name.wei')
// => '0x...' or null

// Reverse resolve an address to its primary .wei name
const name = await wns.reverseResolve('0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045')
// => 'name.wei' or null

// Smart resolve — passes addresses through, resolves .wei names
const result = await wns.resolveAny('name.wei')
const same = await wns.resolveAny('0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045')

The .wei suffix is optional — wns.resolve('name') and wns.resolve('name.wei') are equivalent.

Custom RPC

By default, the client uses free public RPC endpoints with automatic fallback. You can provide your own:

// Single RPC
const wns = createWnsClient({ rpc: 'https://my-paid-rpc.com' })

// Multiple RPCs — tries in order, falls back on failure
const wns = createWnsClient({
  rpc: ['https://primary-rpc.com', 'https://fallback-rpc.com']
})

Helpers

Standalone utility functions that don't make any RPC calls:

import { isWei, isAddress, normalizeName, parseLabel } from 'wns-utils'

isWei('alice.wei')       // true
isWei('alice.eth')       // false

isAddress('0xd8dA...')   // true

normalizeName('Alice')   // 'alice.wei'
normalizeName('ALICE.WEI') // 'alice.wei'

parseLabel('alice.wei')  // 'alice'

Constants

import { WNS_CONTRACT, BASE_PORTAL, wnsAbi } from 'wns-utils'

WNS_CONTRACT // '0x0000000000696760E15f265e828DB644A0c242EB'
BASE_PORTAL  // '0x49048044D57e1C92A77f79988d21Fa8fAF74E97e'

The full contract ABI is exported as wnsAbi for use with viem, ethers, wagmi, or any other web3 library:

import { wnsAbi, WNS_CONTRACT } from 'wns-utils'
import { createPublicClient, http } from 'viem'
import { mainnet } from 'viem/chains'

const client = createPublicClient({ chain: mainnet, transport: http() })

const owner = await client.readContract({
  address: WNS_CONTRACT,
  abi: wnsAbi,
  functionName: 'ownerOf',
  args: [tokenId],
})

API

createWnsClient(config?)

Creates a WNS client instance.

Option	Type	Description
rpc	string | string[]	Custom RPC endpoint(s). Defaults to free public endpoints with fallback.
contract	`0x${string}`	Override the WNS contract address. Defaults to WNS_CONTRACT.

Returns a WnsClient with the following methods:

Method	Returns	Description
resolve(name)	Promise<\0x${string}` | null>`	Resolve a .wei name to an address.
reverseResolve(address)	Promise<string | null>	Reverse resolve an address to its primary .wei name.
resolveAny(input)	Promise<\0x${string}` | null>`	Smart resolve — addresses pass through, .wei names get resolved.

License

MIT