NFDomains SDK

This monorepo contains the NFDomains SDK for direct on-chain interaction with NFDomains (NFD) on the Algorand blockchain, as well as integration with the NFD API for some operations (e.g. batch lookups and searches). The repository also includes example projects demonstrating its usage.

Versioning

This SDK is in early development (pre-1.0.0) and may introduce breaking changes despite our best efforts to avoid them. We recommend pinning the version in your package.json:

{
  "dependencies": {
    "@txnlab/nfd-sdk": "0.1.2"
  }
}

Instead of using caret versioning:

{
  "dependencies": {
    "@txnlab/nfd-sdk": "^0.1.2"
  }
}

Once we reach v1.0.0 with all planned features, breaking changes will only be introduced via major version bumps following semantic versioning.

Installation

# npm
npm install @txnlab/nfd-sdk

# yarn
yarn add @txnlab/nfd-sdk

# pnpm
pnpm add @txnlab/nfd-sdk

Quick Start

import { NfdClient } from '@txnlab/nfd-sdk'

// Create a client instance (MainNet by default)
const nfd = new NfdClient()

// Resolve an NFD by name
const nfdData = await nfd.resolve('alice.algo')
console.log(nfdData)

Usage Examples

Resolving an NFD

import { NfdClient } from '@txnlab/nfd-sdk'

// Create a client instance for TestNet
const nfd = NfdClient.testNet()

// Resolve an NFD by name with 'brief' view
const nfdData = await nfd.resolve('alice.algo', { view: 'brief' })

// Resolve an NFD by application ID
const nfdDataById = await nfd.resolve('123456789')

Searching for NFDs

import { NfdClient } from '@txnlab/nfd-sdk'

const nfd = NfdClient.testNet()

// Search for NFDs containing 'foo' in their name
const searchResults = await nfd.api.search({ substring: 'foo', limit: 10 })

// Search with multiple filters
const filteredResults = await nfd.api.search({
  category: ['premium'],
  state: ['owned'],
  limit: 20,
  offset: 0,
})

Minting an NFD

import { NfdClient } from '@txnlab/nfd-sdk'

const nfd = NfdClient.testNet()

// Get a price quote for minting an NFD
const quote = await nfd.getMintQuote('example.algo', {
  buyer: 'ALGORAND_ADDRESS',
  years: 5,
})

// Mint the NFD using the quote
const mintedNfd = await nfd
  .setSigner(activeAddress, transactionSigner)
  .mint(quote.nfdName, {
    buyer: quote.buyer,
    years: quote.years,
  })

Managing an NFD

import { NfdClient } from '@txnlab/nfd-sdk'

const nfd = NfdClient.testNet()

// Link an address to an NFD
const updatedNfd = await nfd
  .setSigner(activeAddress, transactionSigner)
  .manage('example.algo')
  .linkAddress('ALGORAND_ADDRESS_TO_LINK')

// Set metadata for an NFD
const updatedNfd2 = await nfd
  .setSigner(activeAddress, transactionSigner)
  .manage('example.algo')
  .setMetadata({
    website: 'https://example.com',
    twitter: '@example',
  })

Client Initialization Options

The NFD client can be instantiated in several ways:

// Default constructor (MainNet)
const nfd = new NfdClient()

// Using static methods
const mainNetNfd = NfdClient.mainNet() // define MainNet explicitly
const testNetNfd = NfdClient.testNet() // define TestNet explicitly

// Using custom AlgorandClient and explicit NFD registry ID
import { NfdClient, NfdRegistryId } from '@txnlab/nfd-sdk'
import { AlgorandClient } from '@algorandfoundation/algokit-utils'

const algorand = AlgorandClient.mainNet()
const customNfd = new NfdClient({
  algorand,
  registryId: NfdRegistryId.MAINNET,
})

Examples

Check out the examples directory for complete working examples of various SDK features:

• Resolve: Demonstrates how to resolve NFD names and application IDs
• API Search: Demonstrates how to use the API client to search for NFDs
• Reverse Lookup: Demonstrates how to look up NFDs by wallet address
• Mint: Demonstrates how to mint NFDs
• Link Address: Demonstrates how to link addresses to NFDs
• Set Metadata: Demonstrates how to set metadata for NFDs

Package

• @txnlab/nfd-sdk - Core SDK package for NFDomains

Development

This project uses PNPM workspaces. To get started:

# Install dependencies
pnpm install

# Build all packages
pnpm build

# Run tests
pnpm test

# Lint code
pnpm lint

# Format code
pnpm format

Contributing

Please see our Contributing Guidelines for more details on how to get involved.

1. Fork the repository
2. Create your feature branch (git checkout -b feat/amazing-feature)
3. Commit your changes following our commit message guidelines
4. Push to the branch (git push origin feat/amazing-feature)
5. Open a Pull Request

License

MIT License