MCNS - Multi-Chain Name Service

A lightweight JavaScript/TypeScript library for resolving blockchain addresses from DNS TXT records. MCNS enables domain owners to publish their cryptocurrency addresses using simple DNS records, making it easy to send crypto to human-readable addresses.

Features

• Simple DNS-based resolution - No blockchain queries needed, just DNS
• Multi-chain support - Works with any blockchain (Ethereum, Bitcoin, MultiversX, Sui, etc.)
• User-specific addresses - Support for blockchain.username.domain format
• Email-like syntax - Resolve addresses using bitcoin@example.com format
• Lightweight - Only one dependency (axios)
• TypeScript support - Full type definitions included
• Customizable - Configure DNS resolver and timeout

Installation

npm install mcns

Quick Start

import { getChainAddress, resolveAddress } from 'mcns';

// Resolve an Ethereum address for a domain
const ethAddress = await getChainAddress('ethereum', 'example.com');

// Resolve using email-like format
const btcAddress = await resolveAddress('bitcoin@example.com');

// Resolve a user-specific address
const userAddress = await resolveAddress('ethereum.alice@example.com');

How It Works

MCNS queries DNS TXT records in a specific format to retrieve blockchain addresses:

Format	DNS Query	Use Case
blockchain.domain	ethereum.example.com	Domain-level address
blockchain.username.domain	bitcoin.alice.example.com	User-specific address

Setting Up DNS Records

Add TXT records to your domain's DNS configuration:

ethereum.example.com     TXT    "0x742d35Cc6634C0532925a3b844Bc9e7595f..."
bitcoin.example.com      TXT    "bc1qar0srrr7xfkvy5l643lydnw9re59gtzzwf5mdq"
bitcoin.alice.example.com TXT   "bc1qaliceaddress..."

API Reference

getChainAddress(blockchain, domain, [username], [options])

Resolves a blockchain address from a DNS TXT record.

Parameters:

• blockchain (string) - The blockchain name (e.g., 'ethereum', 'bitcoin')
• domain (string) - The domain name (e.g., 'example.com')
• username (string, optional) - Username for user-specific addresses
• options (object, optional):
  • dnsResolver (string) - DNS-over-HTTPS resolver URL (default: 'https://dns.google/resolve')
  • timeout (number) - Request timeout in milliseconds (default: 5000)

Returns: Promise<string> - The blockchain address

// Domain-level address
const address = await getChainAddress('ethereum', 'example.com');

// User-specific address
const userAddress = await getChainAddress('bitcoin', 'example.com', 'alice');

// With custom options
const address = await getChainAddress('ethereum', 'example.com', {
  timeout: 10000,
  dnsResolver: 'https://cloudflare-dns.com/dns-query'
});

resolveAddress(address, [options])

Resolves a blockchain address using email-like format.

Parameters:

• address (string) - Email-like address (e.g., 'bitcoin@example.com' or 'bitcoin.alice@example.com')
• options (object, optional) - Same as getChainAddress

Returns: Promise<string> - The blockchain address

// Domain-level
const address = await resolveAddress('ethereum@example.com');

// User-specific
const userAddress = await resolveAddress('bitcoin.alice@example.com');

getMultipleChainAddresses(queries, [options])

Resolves multiple blockchain addresses in parallel.

Parameters:

• queries (Array) - Array of { blockchain, domain, username? } objects
• options (object, optional) - Same as getChainAddress

Returns: Promise<Record<string, string>> - Map of addresses keyed by full query name

const addresses = await getMultipleChainAddresses([
  { blockchain: 'ethereum', domain: 'example.com' },
  { blockchain: 'bitcoin', domain: 'example.com' },
  { blockchain: 'bitcoin', domain: 'example.com', username: 'alice' }
]);

// Result:
// {
//   'ethereum.example.com': '0x...',
//   'bitcoin.example.com': 'bc1q...',
//   'bitcoin.alice.example.com': 'bc1q...'
// }

Error Handling

import { getChainAddress } from 'mcns';

try {
  const address = await getChainAddress('ethereum', 'example.com');
  console.log(address);
} catch (error) {
  if (error.message.includes('No TXT record found')) {
    console.error('DNS record does not exist');
  } else if (error.message.includes('timeout')) {
    console.error('DNS lookup timed out');
  } else if (error.message.includes('Invalid address format')) {
    console.error('Invalid email-like address format');
  } else {
    console.error('Error:', error.message);
  }
}

Using Alternative DNS Resolvers

By default, MCNS uses Google's DNS-over-HTTPS service. You can use other resolvers:

// Cloudflare DNS
const address = await getChainAddress('ethereum', 'example.com', {
  dnsResolver: 'https://cloudflare-dns.com/dns-query'
});

TypeScript

Full TypeScript support with exported types:

import {
  getChainAddress,
  resolveAddress,
  getMultipleChainAddresses,
  GetChainAddressOptions
} from 'mcns';

const options: GetChainAddressOptions = {
  timeout: 10000,
  dnsResolver: 'https://dns.google/resolve'
};

const address: string = await getChainAddress('ethereum', 'example.com', options);

License

MIT