zcashname-sdk 0.4.0 → 0.5.1

package/README.md

@@ -0,0 +1,93 @@
+# Zcash Name System (ZNS) SDK
+
+TypeScript SDK for interacting with the Zcash Name System — a decentralized naming system built on Zcash.
+
+## Install
+
+```bash
+npm install zcashname-sdk
+```
+
+## Quick Start
+
+```ts
+import { ZNS } from "zcashname-sdk";
+
+const zns = await ZNS.create();
+
+const name = "alice";
+const resolved = await zns.resolve(name);
+if (resolved === null) {
+  console.log(`${name} is available`);
+} else {
+  console.log(`${name} resolves to ${resolved.address}`);
+}
+```
+
+## API
+
+### `ZNS.create(options?)`
+Create a new ZNS instance connected to the default testnet endpoint.
+
+```ts
+const zns = await ZNS.create();
+const znsMainnet = await ZNS.create({ url: "https://light.zcash.me/zns-mainnet" });
+```
+
+### `zns.resolve(query)`
+Resolve a name to its registered address. Returns `null` if the name is available.
+
+```ts
+const result = await zns.resolve("alice");
+```
+
+### `zns.isAvailable(name)`
+Check if a name is available for registration.
+
+```ts
+const available = await zns.isAvailable("bob");
+```
+
+### `zns.listings()`
+Get all names currently listed for sale.
+
+```ts
+const listings = await zns.listings();
+```
+
+### `zns.events(filter?)`
+Query blockchain events (claims, buys, lists, delists, updates, releases).
+
+```ts
+const { events } = await zns.events({ action: "CLAIM", limit: 50 });
+```
+
+### Action Helpers
+
+The SDK provides prepare/complete pairs for all ZNS actions:
+
+- `zns.prepareClaim(name, address)` / `zns.completeClaim(...)` — claim a name
+- `zns.prepareList(name, price, nonce)` / `zns.completeList(...)` — list a name for sale
+- `zns.prepareDelist(name, nonce)` / `zns.completeDelist(...)` — delist a name
+- `zns.prepareUpdate(name, newAddress, nonce)` / `zns.completeUpdate(...)` — update a name's address
+- `zns.prepareBuy(name, buyerAddress)` / `zns.completeBuy(...)` — buy a name
+- `zns.prepareRelease(name, nonce)` / `zns.completeRelease(...)` — release a name
+
+Each `complete*` method returns a `{ memo, uri }` object suitable for constructing a ZIP 321 URI.
+
+### `zns.parseZip321Uri(uri)`
+Parse a ZIP 321 URI into its components.
+
+```ts
+const parsed = zns.parseZip321Uri("zcash:addr?amount=0.1&memo=...");
+```
+
+## Constants
+
+- `DEFAULT_URL` — default testnet endpoint
+- `TESTNET_UIVK` — expected testnet UIVK for verification
+- `MAINNET_UIVK` — expected mainnet UIVK for verification
+
+## License
+
+MIT

package/dist/zns.cjs

@@ -0,0 +1,333 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/zns.ts
+var zns_exports = {};
+__export(zns_exports, {
+  DEFAULT_URL: () => DEFAULT_URL,
+  MAINNET_UIVK: () => MAINNET_UIVK,
+  TESTNET_UIVK: () => TESTNET_UIVK,
+  ZNS: () => ZNS
+});
+module.exports = __toCommonJS(zns_exports);
+var DEFAULT_URL = "https://light.zcash.me/zns-testnet";
+var TESTNET_UIVK = "uivktest1hzw7wyadutvzfgpna80yftsk5l7jeyu2p5me5quvp28tytxueta00cx4068wnlzcv7tx9n3t3gfhsy83pe4y6jrhxtzaq0hj6xtg5zrk2dn7zen3vns2a5pgs4fxdjlletmqrhfa42";
+var MAINNET_UIVK = "uivk1gl26qy0xjja7lqhyg3pf0x4j4j66kqwewrjkdcg28eqq4wgtzjmujpee7x9cs2ec9xhnlgrm8ptlw8z80j2aryw8nqtssser2ys778a0s00uvgkdjnfr58sndhfvc3f4zqjs6ywva6";
+var KNOWN_UIVKS = [TESTNET_UIVK, MAINNET_UIVK];
+var NAME_RE = /^[a-z0-9]{1,62}$/;
+var ZNS = class _ZNS {
+  constructor(url) {
+    this.rpcId = 0;
+    this._adminPubkey = null;
+    this._pricing = null;
+    this._registryAddress = null;
+    this._verified = false;
+    this.url = url;
+  }
+  static async create(options) {
+    const url = options?.url ?? DEFAULT_URL;
+    const zns = new _ZNS(url);
+    const status = await zns.rpc("status");
+    if (!options?.skipVerify) {
+      if (!KNOWN_UIVKS.includes(status.uivk)) {
+        throw new Error(
+          `UIVK mismatch: indexer returned "${status.uivk.slice(0, 20)}..." which is not a known ZNS instance`
+        );
+      }
+      zns._verified = true;
+    }
+    zns.pinStatus(status);
+    return zns;
+  }
+  pinStatus(status) {
+    this._adminPubkey = status.admin_pubkey;
+    this._pricing = status.pricing;
+    this._registryAddress = status.address;
+  }
+  get verified() {
+    return this._verified;
+  }
+  get adminPubkey() {
+    return this._adminPubkey;
+  }
+  get pricing() {
+    return this._pricing;
+  }
+  get registryAddress() {
+    return this._registryAddress;
+  }
+  async resolve(query) {
+    const raw = await this.rpc("resolve", { query });
+    if (raw === null) return null;
+    if (Array.isArray(raw)) {
+      const results = [];
+      for (const r of raw) results.push(await this.enrichRegistration(r));
+      return results;
+    }
+    return this.enrichRegistration(raw);
+  }
+  async isAvailable(name) {
+    const result = await this.resolve(name);
+    return result === null;
+  }
+  async listings() {
+    const result = await this.rpc("list_for_sale");
+    const enriched = [];
+    for (const l of result.listings) enriched.push(await this.enrichListing(l));
+    return enriched;
+  }
+  async status() {
+    return this.rpc("status");
+  }
+  async events(filter) {
+    const result = await this.rpc("events", filter ?? {});
+    const enriched = [];
+    for (const e of result.events) enriched.push(await this.enrichEvent(e));
+    return { events: enriched, total: result.total };
+  }
+  prepareClaim(name, address) {
+    this.requireValidName(name);
+    const payload = `CLAIM:${name}:${address}`;
+    const cost = this.claimCost(name.length);
+    const uri = cost != null && this._registryAddress ? this.buildZcashUri(this._registryAddress, cost / 1e8) : void 0;
+    return { payload, cost: cost ?? void 0, uri };
+  }
+  completeClaim(name, address, signature, userPubkey) {
+    this.requireValidName(name);
+    const memo = userPubkey ? `ZNS:CLAIM:${name}:${address}:${signature}:${userPubkey}` : `ZNS:CLAIM:${name}:${address}:${signature}`;
+    const cost = this.claimCost(name.length);
+    const uri = this.buildZcashUri(this._registryAddress ?? "", cost != null ? cost / 1e8 : void 0, memo);
+    return { memo, uri };
+  }
+  prepareList(name, price, nonce) {
+    this.requireValidName(name);
+    return { payload: `LIST:${name}:${price}:${nonce}` };
+  }
+  completeList(name, price, nonce, signature, userPubkey) {
+    this.requireValidName(name);
+    const memo = userPubkey ? `ZNS:LIST:${name}:${price}:${nonce}:${signature}:${userPubkey}` : `ZNS:LIST:${name}:${price}:${nonce}:${signature}`;
+    return { memo, uri: this.memoUri(memo) };
+  }
+  prepareDelist(name, nonce) {
+    this.requireValidName(name);
+    return { payload: `DELIST:${name}:${nonce}` };
+  }
+  completeDelist(name, nonce, signature, userPubkey) {
+    this.requireValidName(name);
+    const memo = userPubkey ? `ZNS:DELIST:${name}:${nonce}:${signature}:${userPubkey}` : `ZNS:DELIST:${name}:${nonce}:${signature}`;
+    return { memo, uri: this.memoUri(memo) };
+  }
+  prepareUpdate(name, newAddress, nonce) {
+    this.requireValidName(name);
+    return { payload: `UPDATE:${name}:${newAddress}:${nonce}` };
+  }
+  completeUpdate(name, newAddress, nonce, signature, userPubkey) {
+    this.requireValidName(name);
+    const memo = userPubkey ? `ZNS:UPDATE:${name}:${newAddress}:${nonce}:${signature}:${userPubkey}` : `ZNS:UPDATE:${name}:${newAddress}:${nonce}:${signature}`;
+    return { memo, uri: this.memoUri(memo) };
+  }
+  prepareBuy(name, buyerAddress) {
+    this.requireValidName(name);
+    return { payload: `BUY:${name}:${buyerAddress}` };
+  }
+  completeBuy(name, buyerAddress, signature, userPubkey) {
+    this.requireValidName(name);
+    const memo = userPubkey ? `ZNS:BUY:${name}:${buyerAddress}:${signature}:${userPubkey}` : `ZNS:BUY:${name}:${buyerAddress}:${signature}`;
+    return { memo, uri: this.memoUri(memo) };
+  }
+  prepareRelease(name, nonce) {
+    this.requireValidName(name);
+    return { payload: `RELEASE:${name}:${nonce}` };
+  }
+  completeRelease(name, nonce, signature, userPubkey) {
+    this.requireValidName(name);
+    const memo = userPubkey ? `ZNS:RELEASE:${name}:${nonce}:${signature}:${userPubkey}` : `ZNS:RELEASE:${name}:${nonce}:${signature}`;
+    return { memo, uri: this.memoUri(memo) };
+  }
+  prepareSetPrice(prices, nonce) {
+    return { payload: `SETPRICE:${prices.length}:${prices.join(":")}:${nonce}` };
+  }
+  completeSetPrice(prices, nonce, signature) {
+    const memo = `ZNS:SETPRICE:${prices.length}:${prices.join(":")}:${nonce}:${signature}`;
+    return { memo, uri: this.memoUri(memo) };
+  }
+  isValidName(name) {
+    return NAME_RE.test(name);
+  }
+  claimCost(nameLength) {
+    if (!this._pricing || this._pricing.tiers.length === 0) return null;
+    const idx = Math.min(Math.max(nameLength - 1, 0), this._pricing.tiers.length - 1);
+    return this._pricing.tiers[idx];
+  }
+  parseZip321Uri(uri) {
+    const withoutScheme = String(uri ?? "").replace(/^zcash:/i, "");
+    const [addressPart, queryPart = ""] = withoutScheme.split("?");
+    const address = addressPart.trim();
+    const params = new URLSearchParams(queryPart);
+    const amount = String(params.get("amount") ?? "").trim();
+    const memoRaw = String(params.get("memo") ?? "").trim();
+    const memoDecoded = memoRaw ? this.decodeBase64Url(memoRaw) : "";
+    return { address, amount, memoRaw, memoDecoded };
+  }
+  async enrichRegistration(raw) {
+    const { listing: rawListing, ...reg } = raw;
+    const sovereign = reg.pubkey != null && reg.pubkey !== this._adminPubkey;
+    const verified = await this.verifyRegistration(reg, sovereign);
+    const listing = rawListing ? await this.verifyListing(rawListing) : null;
+    return { ...reg, listing, verified, sovereign };
+  }
+  async verifyRegistration(reg, sovereign) {
+    if (!reg.signature || !this._adminPubkey) return false;
+    const payload = this.registrationPayload(reg);
+    if (!payload) return false;
+    const pubkey = sovereign ? reg.pubkey : this._adminPubkey;
+    return this.verifyEd25519(payload, reg.signature, pubkey);
+  }
+  async verifyListing(listing) {
+    const verified = this._adminPubkey ? await this.verifyEd25519(this.listingPayload(listing), listing.signature, this._adminPubkey) : false;
+    return { ...listing, verified };
+  }
+  async enrichListing(listing) {
+    let verified = false;
+    if (this._adminPubkey) {
+      const payload = this.listingPayload(listing);
+      verified = await this.verifyEd25519(payload, listing.signature, this._adminPubkey);
+    }
+    return { ...listing, verified };
+  }
+  async enrichEvent(event) {
+    if (!event.signature || !this._adminPubkey) return { ...event, verified: false };
+    const payload = this.eventPayload(event);
+    if (!payload) return { ...event, verified: false };
+    const pubkey = event.pubkey ?? this._adminPubkey;
+    const verified = await this.verifyEd25519(payload, event.signature, pubkey);
+    return { ...event, verified };
+  }
+  registrationPayload(reg) {
+    switch (reg.last_action) {
+      case "CLAIM":
+        return `CLAIM:${reg.name}:${reg.address}`;
+      case "BUY":
+        return `BUY:${reg.name}:${reg.address}`;
+      case "UPDATE":
+        return `UPDATE:${reg.name}:${reg.address}:${reg.nonce}`;
+      case "DELIST":
+        return `DELIST:${reg.name}:${reg.nonce}`;
+      case "RELEASE":
+        return `RELEASE:${reg.name}:${reg.nonce}`;
+      default:
+        return "";
+    }
+  }
+  listingPayload(l) {
+    return `LIST:${l.name}:${l.price}:${l.nonce}`;
+  }
+  eventPayload(e) {
+    switch (e.action) {
+      case "CLAIM":
+        return e.ua ? `CLAIM:${e.name}:${e.ua}` : "";
+      case "BUY":
+        return e.ua ? `BUY:${e.name}:${e.ua}` : "";
+      case "LIST":
+        return e.price != null && e.nonce != null ? `LIST:${e.name}:${e.price}:${e.nonce}` : "";
+      case "DELIST":
+        return e.nonce != null ? `DELIST:${e.name}:${e.nonce}` : "";
+      case "RELEASE":
+        return e.nonce != null ? `RELEASE:${e.name}:${e.nonce}` : "";
+      case "UPDATE":
+        return e.ua && e.nonce != null ? `UPDATE:${e.name}:${e.ua}:${e.nonce}` : "";
+      default:
+        return "";
+    }
+  }
+  async verifyEd25519(payload, signatureB64, pubkeyB64) {
+    const sigBytes = this.decodeBase64(signatureB64);
+    const pkBytes = this.decodeBase64(pubkeyB64);
+    if (sigBytes.length !== 64 || pkBytes.length !== 32) return false;
+    try {
+      const key = await crypto.subtle.importKey("raw", pkBytes.buffer, { name: "Ed25519" }, false, ["verify"]);
+      return crypto.subtle.verify("Ed25519", key, sigBytes.buffer, new TextEncoder().encode(payload));
+    } catch {
+      return false;
+    }
+  }
+  requireValidName(name) {
+    if (!NAME_RE.test(name)) throw new Error(`Invalid ZNS name: ${name}`);
+  }
+  memoUri(memo) {
+    return this._registryAddress ? this.buildZcashUri(this._registryAddress, void 0, memo) : `zcash:?memo=${this.toBase64Url(memo)}`;
+  }
+  buildZcashUri(address, amount, memo) {
+    if (!address) return "";
+    const base = `zcash:${address}`;
+    const params = [];
+    if (amount !== void 0 && amount > 0) params.push(`amount=${amount}`);
+    if (memo) params.push(`memo=${this.toBase64Url(memo)}`);
+    return params.length ? `${base}?${params.join("&")}` : base;
+  }
+  toBase64Url(text) {
+    try {
+      return btoa(unescape(encodeURIComponent(text))).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+    } catch {
+      return "";
+    }
+  }
+  decodeBase64Url(value) {
+    try {
+      const normalized = String(value).replace(/-/g, "+").replace(/_/g, "/");
+      const padLen = normalized.length % 4 === 0 ? 0 : 4 - normalized.length % 4;
+      const padded = normalized + "=".repeat(padLen);
+      const binary = atob(padded);
+      const bytes = Uint8Array.from(binary, (c) => c.charCodeAt(0));
+      return new TextDecoder().decode(bytes);
+    } catch {
+      return "";
+    }
+  }
+  decodeBase64(s) {
+    const bin = atob(s);
+    const bytes = new Uint8Array(bin.length);
+    for (let i = 0; i < bin.length; i++) bytes[i] = bin.charCodeAt(i);
+    return bytes;
+  }
+  async rpc(method, params = {}) {
+    const id = ++this.rpcId;
+    const body = JSON.stringify({ jsonrpc: "2.0", id, method, params });
+    const res = await fetch(this.url, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body
+    });
+    if (!res.ok) {
+      throw new Error(`ZNS HTTP ${res.status}: ${res.statusText}`);
+    }
+    const json = await res.json();
+    if (json.error) {
+      throw new Error(`ZNS RPC error ${json.error.code}: ${json.error.message}`);
+    }
+    return json.result;
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  DEFAULT_URL,
+  MAINNET_UIVK,
+  TESTNET_UIVK,
+  ZNS
+});

package/dist/zns.d.cts

@@ -0,0 +1,142 @@
+interface Registration {
+    name: string;
+    address: string;
+    txid: string;
+    height: number;
+    nonce: number;
+    signature: string | null;
+    last_action: LastAction;
+    pubkey: string | null;
+}
+type LastAction = "CLAIM" | "BUY" | "UPDATE" | "DELIST" | "RELEASE";
+interface Listing {
+    name: string;
+    price: number;
+    nonce: number;
+    txid: string;
+    height: number;
+    signature: string;
+}
+interface ResolveResult extends Registration {
+    listing: VerifiedListing | null;
+    verified: boolean;
+    sovereign: boolean;
+}
+interface VerifiedListing extends Listing {
+    verified: boolean;
+}
+interface Pricing {
+    nonce: number;
+    height: number;
+    tiers: number[];
+}
+interface StatusResult {
+    synced_height: number;
+    admin_pubkey: string;
+    uivk: string;
+    address: string;
+    registered: number;
+    listed: number;
+    pricing: Pricing | null;
+}
+interface Event {
+    id: number;
+    name: string;
+    action: Action;
+    txid: string;
+    height: number;
+    ua: string | null;
+    price: number | null;
+    nonce: number | null;
+    signature: string | null;
+    pubkey: string | null;
+    verified?: boolean;
+}
+type Action = "CLAIM" | "LIST" | "DELIST" | "RELEASE" | "UPDATE" | "BUY" | "SETPRICE";
+interface EventsFilter {
+    name?: string;
+    action?: string;
+    since_height?: number;
+    limit?: number;
+    offset?: number;
+}
+interface EventsResult {
+    events: Event[];
+    total: number;
+}
+interface PreparedAction {
+    payload: string;
+    cost?: number;
+    uri?: string;
+}
+interface CompletedAction {
+    memo: string;
+    uri: string;
+}
+
+declare const DEFAULT_URL = "https://light.zcash.me/zns-testnet";
+declare const TESTNET_UIVK = "uivktest1hzw7wyadutvzfgpna80yftsk5l7jeyu2p5me5quvp28tytxueta00cx4068wnlzcv7tx9n3t3gfhsy83pe4y6jrhxtzaq0hj6xtg5zrk2dn7zen3vns2a5pgs4fxdjlletmqrhfa42";
+declare const MAINNET_UIVK = "uivk1gl26qy0xjja7lqhyg3pf0x4j4j66kqwewrjkdcg28eqq4wgtzjmujpee7x9cs2ec9xhnlgrm8ptlw8z80j2aryw8nqtssser2ys778a0s00uvgkdjnfr58sndhfvc3f4zqjs6ywva6";
+declare class ZNS {
+    private url;
+    private rpcId;
+    private _adminPubkey;
+    private _pricing;
+    private _registryAddress;
+    private _verified;
+    private constructor();
+    static create(options?: {
+        url?: string;
+        skipVerify?: boolean;
+    }): Promise<ZNS>;
+    private pinStatus;
+    get verified(): boolean;
+    get adminPubkey(): string | null;
+    get pricing(): Pricing | null;
+    get registryAddress(): string | null;
+    resolve(query: string): Promise<ResolveResult | ResolveResult[] | null>;
+    isAvailable(name: string): Promise<boolean>;
+    listings(): Promise<VerifiedListing[]>;
+    status(): Promise<StatusResult>;
+    events(filter?: EventsFilter): Promise<EventsResult>;
+    prepareClaim(name: string, address: string): PreparedAction;
+    completeClaim(name: string, address: string, signature: string, userPubkey?: string): CompletedAction;
+    prepareList(name: string, price: number, nonce: number): PreparedAction;
+    completeList(name: string, price: number, nonce: number, signature: string, userPubkey?: string): CompletedAction;
+    prepareDelist(name: string, nonce: number): PreparedAction;
+    completeDelist(name: string, nonce: number, signature: string, userPubkey?: string): CompletedAction;
+    prepareUpdate(name: string, newAddress: string, nonce: number): PreparedAction;
+    completeUpdate(name: string, newAddress: string, nonce: number, signature: string, userPubkey?: string): CompletedAction;
+    prepareBuy(name: string, buyerAddress: string): PreparedAction;
+    completeBuy(name: string, buyerAddress: string, signature: string, userPubkey?: string): CompletedAction;
+    prepareRelease(name: string, nonce: number): PreparedAction;
+    completeRelease(name: string, nonce: number, signature: string, userPubkey?: string): CompletedAction;
+    prepareSetPrice(prices: number[], nonce: number): PreparedAction;
+    completeSetPrice(prices: number[], nonce: number, signature: string): CompletedAction;
+    isValidName(name: string): boolean;
+    claimCost(nameLength: number): number | null;
+    parseZip321Uri(uri: string): {
+        address: string;
+        amount: string;
+        memoRaw: string;
+        memoDecoded: string;
+    };
+    private enrichRegistration;
+    private verifyRegistration;
+    private verifyListing;
+    private enrichListing;
+    private enrichEvent;
+    private registrationPayload;
+    private listingPayload;
+    private eventPayload;
+    private verifyEd25519;
+    private requireValidName;
+    private memoUri;
+    private buildZcashUri;
+    private toBase64Url;
+    private decodeBase64Url;
+    private decodeBase64;
+    private rpc;
+}
+
+export { type Action, type CompletedAction, DEFAULT_URL, type Event, type EventsFilter, type EventsResult, type LastAction, type Listing, MAINNET_UIVK, type PreparedAction, type Pricing, type Registration, type ResolveResult, type StatusResult, TESTNET_UIVK, type VerifiedListing, ZNS };