@nadnameservice/nns-wagmi-hooks

A TypeScript library for interacting with the Nad Name Service (NNS) protocol using React Hooks, based on Wagmi. This library provides convenient wrapper hooks around the NNS smart contract, enabling seamless operations related to name resolution, address mapping, and managing name attributes.

About Nad Name Service

Nad Name Service (NNS) is a web3 name service built natively on Monad. NNS maps human-readable names like 'salmo.nad' to machine-readable identifiers such as cryptocurrency addresses, metadata, and more.

More information:

Website
Documents
Monad

Table of Contents

• Features
• Prerequisites
• Installation
• Usage
  • Examples
• API Reference
  • Hooks
• Contributing
• License

Features

• Name Resolution: Resolve .nad domain names to Ethereum addresses.
• Address Mapping: Retrieve primary names associated with wallet addresses.
• Batch queries: Retrive resolved addresses, profiles, primary names,...
• Attribute Management: Get and set custom attributes for names.
• Avatar Integration: Fetch avatar URLs associated with names.
• And many more...

Prerequisites

• Node.js: Ensure you have Node.js installed (v12 or higher recommended).
• TypeScript
• Wagmi This library depends on Wagmi for blockchain interactions.
• Viem: Used by Wagmi
• React Query: Used by Wagmi

Installation

Install the library and dependentcies via npm:

npm install wagmi [email protected] @tanstack/react-query @nadnameservice/nns-wagmi-hooks

Or using yarn:

yarn add wagmi [email protected] @tanstack/react-query @nadnameservice/nns-wagmi-hooks

Usage

Examples

Get profile include primary name + avatar of an address

const { profile, isLoading } = useGetProfile(
  '0xabc...123',
  {
    query: {
      enabled: !isLoading,
    },
  }
)
// => {
//    primaryName: 'salmo.nad';
//    avatar: 'https://...';
//}

Get profiles for multiple address

const { profile, isLoading } = useGetProfiles([
  '0x771CdA7e3786979d8fDed8d4c22Cd42F7B576dD4',
  '0x88eecAcDfaC29ab77aa5E185f34CF8481127FB0E',
  '0xf020798E2D29C0e26d400EE12A1b100Da46bfB3C',
])

/*[
  {
    primaryName: 'nnsfaucet.nad',
    avatar: undefined,
    addr: '0x771CdA7e3786979d8fDed8d4c22Cd42F7B576dD4'
  },
  {
    primaryName: 'tungtungtungsahur69.nad',
    avatar: 'https://play-lh.googleusercontent.com/QrCjJRpiwcFZcwey7VYGtTLPM-iohNDa6ktQfRJNvr7meX3eeTSnyvW6Fe7fHh7Kjwc=w240-h480-rw',
    addr: '0x88eecAcDfaC29ab77aa5E185f34CF8481127FB0E'
  },
  {
    primaryName: 'hihihaha1234.nad',
    avatar: 'https://cdn.discordapp.com/avatars/789141581155795004/a43f791724b7a61334c2f2b01ea82ddd.png',
    addr: '0xf020798E2D29C0e26d400EE12A1b100Da46bfB3C'
  }
]*/

Get resolved address of a .nad name

const {
  resolvedAddress,
  isError,
  isLoading: isLoadingResolvedAddress,
} = useGetResolvedAddress('salmo.nad')
// 0xabc...123

Get resolved addresses for a list of name

const resolveAddresses = await useGetResolvedAddresses([
  'mo.nad',
  'keone.nad',
  'joe69.nad',
  '0xchine.nad',
  '💜.nad',
  '0x771CdA7e3786979d8fDed8d4c22Cd42F7B576dD4',
  '123%^&',
])

/*[
  {
    name: 'joe69.nad',
    resolvedAddress: '0x88eecAcDfaC29ab77aa5E185f34CF8481127FB0E'
  },
  {
    name: '0xchine.nad',
    resolvedAddress: '0x76C5851cE22e476F3513eD31DD77840B4d9DB34C'
  },
  {
    name: '💜.nad',
    resolvedAddress: '0x0A28c04667686A7F2182a9A2488998c61029289E'
  },
  {
    name: '0x771CdA7e3786979d8fDed8d4c22Cd42F7B576dD4',
    resolvedAddress: undefined
  },
  { name: '123%^&', resolvedAddress: undefined }
]*/

Get the primary .nad name of an address

const {
  primaryName,
  isError,
  isLoading: isLoadingPrimaryName,
} = useGetPrimaryNameForAddress('0xabc...123')
// test.nad

Get the primary .nad name for multiple address

const primaryNames = await useGetPrimaryNameForAddresses([
  '0x771CdA7e3786979d8fDed8d4c22Cd42F7B576dD4',
  '0x88eecAcDfaC29ab77aa5E185f34CF8481127FB0E',
  zeroAddress,
])

/*[
  {
    addr: '0x771CdA7e3786979d8fDed8d4c22Cd42F7B576dD4',
    primaryName: 'nnsfaucet.nad'
  },
  {
    addr: '0x88eecAcDfaC29ab77aa5E185f34CF8481127FB0E',
    primaryName: 'tungtungtungsahur69.nad'
  },
  {
    addr: '0x0000000000000000000000000000000000000000',
    primaryName: undefined
  }
]*/

Get an attribute of name

const { value: avatar } = useGetNameAttribute(
  'salmo.nad',
  'avatar',
  {
    query: {
      enabled: !isLoadingPrimaryName,
    },
  }
)

// https://...

Get attributes of name

const { attributes } = useGetNameAttributes('salmo.nad', [
  'attr1',
  'attr2',
])

// [
//   {
//     key: 'attr1',
//     value: 'value1',
//   },
//   {
//     key: 'attr2',
//     value: 'value2',
//   }
// ]

API Reference

Hooks:

useGetProfile(address: Address, config?: UseReadContractConfig)

Fetches the profile associated with a given wallet address, including the primary name and avatar, by querying the NNS smart contract.

• Input:

  • address: The wallet address (Address) whose profile is to be retrieved.
  • config: Optional configuration extending Wagmi's UseReadContractParameters, excluding abi, functionName, and args.

• Output:

  • profile: An object of type Profile containing:
    • primaryName: The primary name (string) associated with the wallet address, suffixed with the top-level domain (TLD), or undefined if no name is found or the name is empty.
    • avatar: The avatar URL (string) associated with the profile, or undefined if no avatar is set or the value is empty.
  • All other properties from Wagmi's UseReadContractReturnType, excluding the data field.

useGetProfiles(addrs: Address[], config?: UseReadContractConfig)

Fetches list of profiles associated with a given list of wallet addresses, including the primary name and avatar, by querying the NNS smart contract.

• Input:

  • addrs: The list of wallet addresses (Address[])
  • config: Optional configuration extending Wagmi's UseReadContractParameters, excluding abi, functionName, and args.

• Output:

  • profiles: An list of objects of type Profile[] containing:
    • addr: The wallet address
    • primaryName: The primary name (string) associated with the wallet address, suffixed with the top-level domain (TLD), or undefined if no name is found or the name is empty.
    • avatar: The avatar URL (string) associated with the profile, or undefined if no avatar is set or the value is empty.
  • All other properties from Wagmi's UseReadContractReturnType, excluding the data field.

useGetPrimaryNameForAddress(address: Address, config?: UseReadContractConfig)

Fetches the primary name associated with a given wallet address.

• Input:

  • address: The wallet address (Address) whose primary name is being queried.
  • config: Optional configuration based on Wagmi's UseReadContractParameters, excluding abi, functionName, and args.

• Output:

  • primaryName: The primary name (string) associated with the provided address, or undefined if no name is found.
  • All other properties from Wagmi's UseReadContractReturnType, excluding the data field, providing additional details about the contract read operation.

useGetPrimaryNameForAddresses(addrs: Address[], config?: UseReadContractConfig)

Fetches primary names, each associated with a given wallet address from a list of wallet addresses.

• Input:

  • addrs: The list of wallet addresses (Address[]).
  • config: Optional configuration based on Wagmi's UseReadContractParameters, excluding abi, functionName, and args.

• Output:

  • primaryNames: An list of objects of type PrimaryNameItem[] containing:
    • primaryName: The primary name (string) associated with the wallet address, suffixed with the top-level domain (TLD), or undefined if no name is found or the name is empty.
    • addr: The wallet address
  • All other properties from Wagmi's UseReadContractReturnType, excluding the data field, providing additional details about the contract read operation.

useGetResolvedAddress(name: string, config?: UseReadContractConfig)

Resolves a given name to its associated wallet address by querying the NNS smart contract.

• Input:

  • name: The name (string) to be resolved into a wallet address.
  • config: Optional configuration extending Wagmi's UseReadContractParameters, excluding abi, functionName, and args.

• Output:

  • resolvedAddress: The resolved wallet address (Address) corresponding to the input name.
  • All other properties from Wagmi's UseReadContractReturnType, excluding the data field.

useGetResolvedAddresses(names: string[], config?: UseReadContractConfig)

Get resolved address for each name in the list

• Input:

  • names: The list of names (string)
  • config: Optional configuration extending Wagmi's UseReadContractParameters, excluding abi, functionName, and args.

• Output:

  • resolvedAddresses: An list of objects of type ResolvedAddressItem[] containing:
    • resolvedAddress: The resolved address associated with the name, or undefined if no name is found or the name is empty.
    • name: The name
  • All other properties from Wagmi's UseReadContractReturnType, excluding the data field.

useGetNameAttribute(name: string, key: string, config?: UseReadContractConfig)

Fetches a specific attribute value for a given name by querying the NNS smart contract.

• Input:

  • name: The name (string) for which the attribute value is being queried.
  • key: The key (string) of the attribute to retrieve.
  • config: Optional configuration extending Wagmi's UseReadContractParameters, excluding abi, functionName, and args.

• Output:

  • value: The value of the specified attribute (string) for the given name, or undefined if no value is found.
  • All other properties from Wagmi's UseReadContractReturnType, excluding the data field.

useGetNameAttributes(name: string, keys: string[], config?: UseReadContractConfig)

Retrieves multiple attribute key-value pairs for a given name by querying the NNS smart contract.

• Input:

  • name: The name (string) for which the attributes are being queried.
  • keys: An array of keys (string[]) representing the attributes to retrieve.
  • config: Optional configuration extending Wagmi's UseReadContractParameters, excluding abi, functionName, and args.

• Output:

  • attributes: An array of objects of type Attribute, each containing:
    • key: The key of the attribute.
    • value: The value of the attribute. If no attributes are found, returns undefined.
  • All other properties from Wagmi's UseReadContractReturnType, excluding the data field.

Contributing

Contributions are welcome! If you would like to contribute to this project, please follow these steps:

1. Fork the repository.
2. Create a new branch for your feature or bug fix.
3. Make your changes and commit them with descriptive messages.
4. Push your changes to your forked repository.
5. Open a pull request detailing your changes and why they should be merged.

License

This project is licensed under the MIT License. See the LICENSE file for details.