Abstract Names SDK

React SDK for interacting with Abstract Names contracts. Provides simple hooks for name resolution, reverse resolution, and profile data.

WARNING: NOT PRODUCTION READY YET

This project is ongoing development. Please wait before the first major version before using this in production environments.

Installation

# npm
npm install @abstract-names/sdk

# yarn
yarn add @abstract-names/sdk

# pnpm
pnpm add @abstract-names/sdk

# bun
bun add @abstract-names/sdk

Prerequisites

This SDK requires the following peer dependencies:

• react (^18.0.0 or ^19.0.0)
• wagmi (^2.0.0)
• viem (^2.0.0)

Make sure you have wagmi configured in your application.

Quick Start

import { useResolve, useReverseResolve, useProfile } from '@abstract-names/sdk';

function MyComponent() {
  // Resolve name to address
  const { data: address } = useResolve({
    name: 'vitalik.abs'
  });

  // Reverse resolve address to name
  const { data: name } = useReverseResolve({
    address: '0x1234...'
  });

  // Get complete profile
  const { data: profile, getTextRecord } = useProfile({
    nameOrAddress: 'vitalik.abs'
  });

  const twitter = getTextRecord('com.x');

  return (
    <div>
      <p>Address: {address}</p>
      <p>Name: {name}</p>
      <p>Twitter: {twitter}</p>
    </div>
  );
}

Features

• ✅ Auto-Detection - Automatically uses the active chain from wagmi
• ✅ Comprehensive - 15 hooks covering read, write, validation, and pricing
• ✅ Structured Errors - User-friendly error messages for better UX
• ✅ TypeScript First - Full type safety with TypeScript
• ✅ wagmi Integration - Built on wagmi v2 with TanStack Query v5
• ✅ Tree Shakeable - Import only what you need (sideEffects: false)
• ✅ Performance Optimized - Debounced validation, minimal re-renders
• ✅ Works with Any Wallet - Compatible with RainbowKit, Privy, Dynamic, WalletConnect, or native implementations

Available Hooks

Resolution:

• useResolve - Resolve name to address
• useReverseResolve - Get primary name for address
• useProfile - Get complete profile data including text records

Validation:

• useValidateName - Contract-based name validation (Unicode support)
• useValidateNameDebounced - Debounced validation (reduces RPC calls ~70%)

Write Operations:

• useSetTextRecord - Set individual text records
• useBatchSetText - Gas-efficient batch updates
• useSetPrimaryName - Set/unset primary names (with fee)
• useSetAddress - Set resolved address

Pricing & Phases:

• useNamePrice - Tier-based pricing info
• useMintPhase - Current phase detection

Utilities:

• useNameAvailability - Check if name is available
• useNameExpiry - Expiration info with days until expiry
• useTextRecord - Fetch individual text records
• useAllowedTextKeys - Get supported text record keys

How It Works

Automatic Chain Detection

The SDK automatically detects the active chain from wagmi - no need to pass chain parameters to each hook:

// Example with AbstractWalletProvider
import { AbstractWalletProvider } from "@abstract-foundation/agw-react";
import { abstractTestnet } from "viem/chains";

function App() {
  return (
    <AbstractWalletProvider chain={abstractTestnet}>
      <YourApp />
    </AbstractWalletProvider>
  );
}

// In your components - no chain parameter needed!
import { useResolve } from "@abstract-names/sdk";

function YourComponent() {
  const { data } = useResolve({
    name: "vitalik.abs"
  });
  // Auto-detects abstractTestnet from wagmi
}

Works with RainbowKit, Privy, Dynamic, or any wagmi setup - the SDK automatically uses your active chain!

Optional: Override Chain with Provider

Need to query a different chain than the active one? Use the AbstractNamesProvider:

import { AbstractNamesProvider } from "@abstract-names/sdk";
import { abstractTestnet } from "viem/chains";

function App() {
  return (
    <AbstractNamesProvider chainId={abstractTestnet.id}>
      <YourApp />
      {/* All hooks inside will use abstractTestnet */}
    </AbstractNamesProvider>
  );
}

Documentation

For complete documentation, examples, and guides:

📖 General Documentation: https://abstractnames.gitbook.io/docs

🎣 React Hooks Guide: https://abstractnames.gitbook.io/docs/documentation/build/react

License

MIT