Resolving .xrpl Domains with ZNS

Audience: Developers building wallets, dApps, or tools that need to resolve human-readable .xrpl domain names to Ethereum addresses.
Key fact: The ZNS Registry on XRPL EVM provides on-chain domain resolution, reverse lookup, and caching strategies for optimal performance.
Registry Address: 0xf180136DdC9e4F8c9b5A9FE59e2b1f07265C5D4D (Mainnet)

Why use .xrpl domains?

Traditional flow	.xrpl domain flow
Copy/paste 42-character hex addresses	Type alice.xrpl → resolve
Risk of typos and phishing	Human-readable, verifiable names
No reverse lookup	Address → primary domain lookup

.xrpl domains make your dApp more user-friendly and reduce errors when sending transactions.

Overview

The ZNS Registry is a smart contract that maps .xrpl domain names to Ethereum addresses. It provides:

Forward resolution: domain name → address
Reverse resolution: address → primary domain name
Token-based ownership: Each domain is an NFT (ERC-721)
Expiration tracking: Domains have expiration dates

Key concepts

Domain names are stored without the .xrpl suffix in the registry
Each domain has a unique token ID
Users can set a primary domain for reverse lookups
Domains can expire and need renewal

Quick-start code (TypeScript + Viem)

Prerequisites

npm install viem

Basic setup

import { createPublicClient, http, getAddress } from 'viem';

// Define XRPL EVM chain config
const XRPL_EVM = {
  id: 1440000,
  name: 'XRPL EVM Sidechain',
  nativeCurrency: { name: 'XRP', symbol: 'XRP', decimals: 18 },
  rpcUrls: {
    default: { http: ['https://rpc.xrplevm.org'] },
  },
};

// ZNS Registry address (verified on mainnet)
export const ZNS_REGISTRY = '0xf180136DdC9e4F8c9b5A9FE59e2b1f07265C5D4D';

// Create a public client for read operations
export const publicClient = createPublicClient({
  chain: XRPL_EVM,
  transport: http(XRPL_EVM.rpcUrls.default.http[0]),
});

Forward resolution: domain → address

// ABI for domain lookup (returns token ID)
const ABI_DOMAIN_LOOKUP = [
  {
    inputs: [{ name: '', type: 'string' }],
    name: 'domainLookup',
    outputs: [{ name: '', type: 'uint256' }],
    stateMutability: 'view',
    type: 'function',
  },
] as const;

// ABI for registry lookup by token ID
const ABI_REGISTRY_LOOKUP_BY_ID = [
  {
    inputs: [{ name: 'tokenId', type: 'uint256' }],
    name: 'registryLookupById',
    outputs: [
      {
        name: '',
        type: 'tuple',
        components: [
          { name: 'owner', type: 'address' },
          { name: 'domainName', type: 'string' },
          { name: 'lengthOfDomain', type: 'uint16' },
          { name: 'expirationDate', type: 'uint256' },
        ],
      },
    ],
    stateMutability: 'view',
    type: 'function',
  },
] as const;

async function resolveXrplDomain(name: string): Promise<string | null> {
  if (!name.toLowerCase().endsWith('.xrpl')) return null;
  
  // Strip .xrpl suffix (registry stores names without it)
  const nameWithoutTld = name.toLowerCase().replace(/\.xrpl$/, '');
  
  try {
    // Step 1: Get token ID for the domain
    const tokenId = await publicClient.readContract({
      address: ZNS_REGISTRY,
      abi: ABI_DOMAIN_LOOKUP,
      functionName: 'domainLookup',
      args: [nameWithoutTld],
    }) as bigint;
    
    if (!tokenId || tokenId === BigInt(0)) return null;
    
    // Step 2: Get registry data including owner address
    const registryData = await publicClient.readContract({
      address: ZNS_REGISTRY,
      abi: ABI_REGISTRY_LOOKUP_BY_ID,
      functionName: 'registryLookupById',
      args: [tokenId],
    }) as {
      owner: `0x${string}`;
      domainName: string;
      lengthOfDomain: number;
      expirationDate: bigint;
    };
    
    // Return checksummed address
    if (registryData?.owner && registryData.owner !== '0x0000000000000000000000000000000000000000') {
      return getAddress(registryData.owner);
    }
  } catch (error) {
    console.error('Domain resolution failed:', error);
  }
  
  return null;
}

// Usage
const address = await resolveXrplDomain('alice.xrpl');
console.log(address); // 0x1234...

Reverse resolution: address → domain

// ABI for user lookup by address
const ABI_USER_LOOKUP = [
  {
    inputs: [{ name: 'user', type: 'address' }],
    name: 'userLookupByAddress',
    outputs: [
      {
        name: '',
        type: 'tuple',
        components: [
          { name: 'primaryDomain', type: 'uint256' },
          { name: 'allOwnedDomains', type: 'uint256[]' },
          { name: 'numberOfReferrals', type: 'uint256' },
          { name: 'totalEarnings', type: 'uint256' },
        ],
      },
    ],
    stateMutability: 'view',
    type: 'function',
  },
] as const;

async function resolveAddressToDomain(address: string): Promise<string | null> {
  // Validate address format
  if (!/^0x[a-fA-F0-9]{40}$/.test(address)) return null;
  
  try {
    // Step 1: Get user config (includes primary domain token ID)
    const userConfig = await publicClient.readContract({
      address: ZNS_REGISTRY,
      abi: ABI_USER_LOOKUP,
      functionName: 'userLookupByAddress',
      args: [address as `0x${string}`],
    }) as {
      primaryDomain: bigint;
      allOwnedDomains: readonly bigint[];
      numberOfReferrals: bigint;
      totalEarnings: bigint;
    };
    
    if (!userConfig.primaryDomain || userConfig.primaryDomain === BigInt(0)) {
      return null; // No primary domain set
    }
    
    // Step 2: Get domain name from token ID
    const registryData = await publicClient.readContract({
      address: ZNS_REGISTRY,
      abi: ABI_REGISTRY_LOOKUP_BY_ID,
      functionName: 'registryLookupById',
      args: [userConfig.primaryDomain],
    }) as {
      owner: `0x${string}`;
      domainName: string;
      lengthOfDomain: number;
      expirationDate: bigint;
    };
    
    if (registryData?.domainName) {
      // Add .xrpl suffix if not present
      return registryData.domainName.toLowerCase().endsWith('.xrpl')
        ? registryData.domainName
        : `${registryData.domainName}.xrpl`;
    }
  } catch (error) {
    console.error('Reverse lookup failed:', error);
  }
  
  return null;
}

// Usage
const domain = await resolveAddressToDomain('0x1234...');
console.log(domain); // alice.xrpl

Performance optimization with caching

Since blockchain reads can be slow, implement a simple in-memory cache:

// Simple cache with 5-minute TTL
const resolutionCache = new Map<string, { 
  address: string | null; 
  timestamp: number 
}>();

const CACHE_DURATION = 5 * 60 * 1000; // 5 minutes

// Clear expired entries periodically
setInterval(() => {
  const now = Date.now();
  for (const [key, value] of resolutionCache.entries()) {
    if (now - value.timestamp > CACHE_DURATION) {
      resolutionCache.delete(key);
    }
  }
}, CACHE_DURATION);

async function resolveXrplDomainCached(name: string): Promise<string | null> {
  const nameWithoutTld = name.toLowerCase().replace(/\.xrpl$/, '');
  
  // Check cache first
  const cached = resolutionCache.get(nameWithoutTld);
  if (cached && (Date.now() - cached.timestamp) < CACHE_DURATION) {
    return cached.address;
  }
  
  // Perform resolution (implementation from section 3)
  const address = await resolveXrplDomain(name);
  
  // Cache result (including null to avoid repeated failed lookups)
  resolutionCache.set(nameWithoutTld, {
    address,
    timestamp: Date.now()
  });
  
  return address;
}

Tip: For production apps, consider using Redis or another distributed cache for better scalability.

Alternative resolution method

The ZNS Registry also provides registryLookupByName for direct name-to-owner lookup:

const ABI_REGISTRY_LOOKUP_BY_NAME = [
  {
    inputs: [{ name: 'domainName', type: 'string' }],
    name: 'registryLookupByName',
    outputs: [
      {
        name: '',
        type: 'tuple',
        components: [
          { name: 'owner', type: 'address' },
          { name: 'domainName', type: 'string' },
          { name: 'lengthOfDomain', type: 'uint16' },
          { name: 'expirationDate', type: 'uint256' },
        ],
      },
    ],
    stateMutability: 'view',
    type: 'function',
  },
] as const;

async function resolveDirectly(name: string): Promise<string | null> {
  const nameWithoutTld = name.toLowerCase().replace(/\.xrpl$/, '');
  
  try {
    const info = await publicClient.readContract({
      address: ZNS_REGISTRY,
      abi: ABI_REGISTRY_LOOKUP_BY_NAME,
      functionName: 'registryLookupByName',
      args: [nameWithoutTld],
    }) as {
      owner: `0x${string}`;
      domainName: string;
      lengthOfDomain: number;
      expirationDate: bigint;
    };
    
    if (info?.owner && info.owner !== '0x0000000000000000000000000000000000000000') {
      return getAddress(info.owner);
    }
  } catch (error) {
    console.error('Direct lookup failed:', error);
  }
  
  return null;
}

Note: The domainLookup → registryLookupById approach is typically faster as it uses indexed token IDs.

Complete implementation with fallbacks

Here's a production-ready implementation combining all strategies:

import { createPublicClient, http, getAddress } from 'viem';

export const ZNS_REGISTRY = '0xf180136DdC9e4F8c9b5A9FE59e2b1f07265C5D4D';

// In-memory cache
const resolutionCache = new Map<string, { 
  address: `0x${string}` | null; 
  timestamp: number 
}>();
const CACHE_DURATION = 5 * 60 * 1000;

// ABIs (from sections above)
const ABI_DOMAIN_LOOKUP = [/* ... */];
const ABI_REGISTRY_LOOKUP_BY_ID = [/* ... */];
const ABI_REGISTRY_LOOKUP_BY_NAME = [/* ... */];

export const publicClient = createPublicClient({
  chain: {
    id: 1440000,
    name: 'XRPL EVM Sidechain',
    nativeCurrency: { name: 'XRP', symbol: 'XRP', decimals: 18 },
    rpcUrls: {
      default: { http: ['https://rpc.xrplevm.org'] },
    },
  },
  transport: http('https://rpc.xrplevm.org'),
});

export async function resolveXrplNameToAddress(
  name: string
): Promise<`0x${string}` | null> {
  if (!name.toLowerCase().endsWith('.xrpl')) return null;
  
  const nameWithoutTld = name.toLowerCase().replace(/\.xrpl$/, '');
  if (!nameWithoutTld.trim()) return null;
  
  // Check cache
  const cached = resolutionCache.get(nameWithoutTld);
  if (cached && (Date.now() - cached.timestamp) < CACHE_DURATION) {
    return cached.address;
  }
  
  let resolvedAddress: `0x${string}` | null = null;
  
  // Method 1: domainLookup + registryLookupById (faster)
  try {
    const tokenId = await publicClient.readContract({
      address: ZNS_REGISTRY,
      abi: ABI_DOMAIN_LOOKUP,
      functionName: 'domainLookup',
      args: [nameWithoutTld],
    }) as bigint;
    
    if (tokenId && tokenId > BigInt(0)) {
      const registryData = await publicClient.readContract({
        address: ZNS_REGISTRY,
        abi: ABI_REGISTRY_LOOKUP_BY_ID,
        functionName: 'registryLookupById',
        args: [tokenId],
      }) as any;
      
      if (registryData?.owner && 
          registryData.owner !== '0x0000000000000000000000000000000000000000') {
        resolvedAddress = getAddress(registryData.owner);
      }
    }
  } catch (error) {
    console.debug('Primary resolution failed, trying fallback:', error);
  }
  
  // Method 2: registryLookupByName (fallback)
  if (!resolvedAddress) {
    try {
      const info = await publicClient.readContract({
        address: ZNS_REGISTRY,
        abi: ABI_REGISTRY_LOOKUP_BY_NAME,
        functionName: 'registryLookupByName',
        args: [nameWithoutTld],
      }) as any;
      
      if (info?.owner && 
          info.owner !== '0x0000000000000000000000000000000000000000') {
        resolvedAddress = getAddress(info.owner);
      }
    } catch (error) {
      console.debug('Fallback resolution failed:', error);
    }
  }
  
  // Cache result
  resolutionCache.set(nameWithoutTld, {
    address: resolvedAddress,
    timestamp: Date.now()
  });
  
  return resolvedAddress;
}

export function isValidAddress(address: string): boolean {
  return /^0x[a-fA-F0-9]{40}$/.test(address);
}

export async function resolveAddressToXrplName(
  address: string
): Promise<string | null> {
  if (!isValidAddress(address)) return null;
  
  try {
    const userConfig = await publicClient.readContract({
      address: ZNS_REGISTRY,
      abi: ABI_USER_LOOKUP,
      functionName: 'userLookupByAddress',
      args: [address as `0x${string}`],
    }) as any;
    
    if (!userConfig.primaryDomain || userConfig.primaryDomain === BigInt(0)) {
      return null;
    }
    
    const registryData = await publicClient.readContract({
      address: ZNS_REGISTRY,
      abi: ABI_REGISTRY_LOOKUP_BY_ID,
      functionName: 'registryLookupById',
      args: [userConfig.primaryDomain],
    }) as any;
    
    if (registryData?.domainName) {
      return registryData.domainName.toLowerCase().endsWith('.xrpl')
        ? registryData.domainName
        : `${registryData.domainName}.xrpl`;
    }
  } catch (error) {
    console.debug('Reverse lookup failed:', error);
  }
  
  return null;
}

Integration checklist

Install viem dependency
Configure XRPL EVM chain in your app
Implement forward resolution for wallet/dApp inputs
Add reverse resolution for displaying user identities
Implement caching strategy (in-memory or distributed)
Handle edge cases (expired domains, unset primary domains)
Test on testnet before mainnet deployment
Add error handling for network failures

Common patterns

Wallet integration

// Accept both addresses and .xrpl domains in send forms
async function validateRecipient(input: string): Promise<string | null> {
  // Check if it's already a valid address
  if (isValidAddress(input)) {
    return input;
  }
  
  // Try resolving as .xrpl domain
  if (input.toLowerCase().endsWith('.xrpl')) {
    return await resolveXrplNameToAddress(input);
  }
  
  return null;
}

Display user-friendly names

// Show domain instead of address when available
async function formatAddress(address: string): Promise<string> {
  const domain = await resolveAddressToXrplName(address);
  return domain || `${address.slice(0, 6)}...${address.slice(-4)}`;
}

Batch resolution

// Resolve multiple domains in parallel
async function resolveBatch(names: string[]): Promise<Map<string, string | null>> {
  const results = await Promise.all(
    names.map(async (name) => ({
      name,
      address: await resolveXrplNameToAddress(name),
    }))
  );
  
  return new Map(results.map(r => [r.name, r.address]));
}

FAQ

Q: Do I need to deploy my own registry contract? A: No, use the existing ZNS Registry at 0xf180136DdC9e4F8c9b5A9FE59e2b1f07265C5D4D.

Q: What if a domain has expired? A: The registry will still return the owner, but you should check the expirationDate field if freshness matters.

Q: Can I use this with ethers.js instead of viem? A: Yes! The contract addresses and ABIs are the same—just adapt the client initialization and contract call syntax.

Q: How do I register a .xrpl domain? A: Visit the official ZNS platform or use their registration contract (not covered in this guide).

Q: Does the registry support subdomains (e.g., wallet.alice.xrpl)? A: Check the ZNS documentation for subdomain support—this guide covers primary domain resolution.

Need help?

Discord: https://discord.gg/xrplevm

ZNS Registry Contract: 0xf180136DdC9e4F8c9b5A9FE59e2b1f07265C5D4D

ZNS Buy Domain https://zns.bio/

Transfer to .xrpl domain ens.xrplevm.org

Happy building! 🚀