ZNS SDK

TypeScript SDK for the Zcash Name System. Register names, manage listings, and resolve addresses on Zcash.

npm install zcashname-sdk

Quick Start

import { ZNS } from "zcashname-sdk";

// Create client (synchronous, no network calls)
const zns = new ZNS();

// Resolve a name to get its Zcash address
const reg = await zns.resolveName("alice");
if (reg) console.log(`alice.zcash → ${reg.address}`);

// Check availability
const available = await zns.isAvailable("bob");

// Verify server identity (optional but recommended)
await zns.verify();

Actions Flow

Every state-changing action follows the same pattern: prepare → sign → complete.

import * as ed25519 from "@noble/ed25519";

// 1. Fetch status to get current pricing
const status = await zns.status();
const cost = zns.claimCost(5, status.pricing);

// 2. Prepare the action
const claim = zns.prepareClaim("myname", "u1qqlzrf9...", status.address, cost);

// 3. Sign the payload with your Ed25519 private key
const privateKey = ed25519.utils.randomPrivateKey();
const signature = await ed25519.signAsync(
  new TextEncoder().encode(claim.payload),
  privateKey
);

// 4. Complete and get the payment URI
const { memo, uri } = claim.complete(
  Buffer.from(signature).toString("base64"),
  Buffer.from(ed25519.getPublicKey(privateKey)).toString("base64")
);

// 5. Send the transaction using your Zcash wallet
console.log("Payment URI:", uri);
console.log("Memo:", memo);

Available Actions

| Action | Description | |--------|-------------| | prepareClaim(name, address, registryAddress, cost) | Register a new name | | prepareList(name, price, nonce, registryAddress) | List name for sale | | prepareDelist(name, nonce, registryAddress) | Remove listing | | prepareUpdate(name, newAddress, nonce, registryAddress) | Change address | | prepareBuy(name, buyerAddress, registryAddress) | Buy a listed name | | prepareRelease(name, nonce, registryAddress) | Release name (burn) | | prepareSetPrice(prices, nonce, registryAddress) | Admin: set pricing tiers |

Reading Data

// Resolve name → address (single lookup)
const reg = await zns.resolveName("alice");

// Resolve address → names (reverse lookup) - supports pagination
const names = await zns.resolveAddress("u1qqlzrf9...");

// Paginated address lookup (get next 50 names starting from position 50)
const namesPage2 = await zns.resolveAddress("u1qqlzrf9...", 50, 50);

// List all registered names (paginated) - useful for explorers
const allNames = await zns.listAllRegistrations();

// Paginated list (first 100 registrations)
const first100 = await zns.listAllRegistrations(100, 0);

// Check availability
const available = await zns.isAvailable("bob");

// Get marketplace listings - supports pagination
const listings = await zns.listings();

// Paginated listings (get 50 listings starting from position 100)
const listingsPage3 = await zns.listings(50, 100);

// Query events with pagination
const { events, total } = await zns.events({ action: "CLAIM", limit: 10 });

// Next page of events
const nextPage = await zns.events({ action: "CLAIM", limit: 10, offset: 10 });

// Get current pricing from status
const status = await zns.status();
const cost = zns.claimCost(5, status.pricing); // cost for 5-char name

Server Verification (Optional)

For security-sensitive applications, verify the server identity:

const zns = new ZNS({ url: "https://your-indexer.com/zns" });

// Verify this is a legitimate ZNS instance
await zns.verify();
console.log("Verified:", zns.verified); // true

// Now proceed with operations
const status = await zns.status();

Validation & Utilities

// Validate a Zcash Unified Address
const valid = zns.isValidUnifiedAddress("u1qqlzrf9..."); // true/false

// Validate a ZNS name
const validName = zns.isValidName("alice"); // true
const invalid = zns.isValidName("Alice");   // false (uppercase)

// Parse ZIP-321 URI
const parts = zns.parseZip321Uri("zcash:u1...?amount=1&memo=...");
// { address: "u1...", amount: "1", memoRaw: "...", memoDecoded: "..." }

Signature Verification

// Get admin pubkey from status
const status = await zns.status();

// Verify a listing signature
const listing = await zns.listings().then(l => l[0]);
const valid = await zns.verifyListing(listing, status.admin_pubkey);

// Verify a registration
const reg = await zns.resolveName("alice");
const validReg = await zns.verifyRegistration(reg, status.admin_pubkey);

Configuration

// Custom endpoint
const zns = new ZNS({ url: "https://your-indexer.com/zns" });

// Optional: verify server identity
await zns.verify(); // throws if not a known ZNS instance

// Access current status
const status = await zns.status();
console.log(status.admin_pubkey);  // Registry admin pubkey
console.log(status.pricing);       // Current pricing tiers
console.log(status.address);       // Registry payment address

Constants

import { DEFAULT_URL, TESTNET_UIVK, MAINNET_UIVK } from "zcashname-sdk";

console.log(DEFAULT_URL);  // "https://light.zcash.me/zns-testnet"

CLI Example

See examples/cli/ for a working command-line interface:

# Resolve a name
npx tsx src/index.ts resolve alice

# Check availability
npx tsx src/index.ts available bob

# List all names for sale
npx tsx src/index.ts listings

# Prepare a claim (outputs payload to sign)
npx tsx src/index.ts prepare-claim myname u1qqlzrf9...

# Sign and complete with a private key
npx tsx src/index.ts sign-claim myname u1qqlzrf9... --key-file ./key.txt

Types

type Zats = number; // 1 ZEC = 100,000,000 zats

interface Registration {
  name: string;
  address: string;
  txid: string;
  height: number;
  nonce: number;
  signature: string | null;
  last_action: "CLAIM" | "BUY" | "UPDATE" | "DELIST" | "RELEASE";
  pubkey: string | null;    // null = admin-registered
  listing: Listing | null;
}

interface Listing {
  name: string;
  price: Zats;
  nonce: number;
  txid: string;
  height: number;
  signature: string;
  pubkey: string | null;
}

interface Status {
  synced_height: number;
  admin_pubkey: string;
  uivk: string;
  address: string;
  registered: number;
  listed: number;
  pricing: Pricing;
}

interface Pricing {
  nonce: number;
  height: number;
  tiers: Zats[]; // cost for names of length 1, 2, 3...
}

interface PreparedClaim {
  readonly name: string;
  readonly address: string;
  readonly cost: Zats;
  readonly payload: string;  // sign this
  complete(signature: string, userPubkey?: string): CompletedAction;
}

interface CompletedAction {
  memo: string;  // ZNS:CLAIM:name:address:sig:pubkey
  uri: string;   // zcash:addr?amount=...&memo=...
}

License

MIT