zcashname-sdk 0.8.1 → 0.8.3

package/dist/zns.cjs

@@ -35,7 +35,8 @@ __export(zns_exports, {
   LIST_COMMISSION: () => LIST_COMMISSION,
   MAINNET_UIVK: () => MAINNET_UIVK,
   TESTNET_UIVK: () => TESTNET_UIVK,
-  ZNS: () => ZNS
+  ZNS: () => ZNS,
+  ZNS_ACTIONS: () => ZNS_ACTIONS
 });
 module.exports = __toCommonJS(zns_exports);
 var ed25519 = __toESM(require("@noble/ed25519"), 1);
@@ -54,7 +55,14 @@ var REGISTRY_ADDRESSES = {
   testnet: "utest1f32kn6c4zvn54xr8wfsnxmj9hzpu2mwgtxzpzwcw34906tdccdvzs0z2dx38lly7tpan77x6udt8pjczqm22ymsdhlz9j0tk5yq664nl",
   mainnet: "u1k0evt0ahj5qdt6y9ftsxndl8lrkm4ff6rp00u04cjpmqj6hxl9t8hfsxftmn3ht34e03lljh89czn2h8qn67rwrs8x0hm3lsxsucp9q9"
 };
+var ZNS_ACTIONS = ["CLAIM", "BUY", "UPDATE", "LIST", "DELIST", "RELEASE"];
 var NAME_RE = /^[a-z0-9]{1,62}$/;
+function isWholeNumber(value) {
+  return /^\d+$/.test(value) && !value.startsWith("0") || value === "0";
+}
+function mk(level, action, canonical, message) {
+  return { valid: level === "valid", action, canonicalAction: canonical, message, level };
+}
 var ZNS = class {
   /**
    * Creates a new ZNS client.
@@ -182,6 +190,120 @@ var ZNS = class {
   isValidName(name) {
     return NAME_RE.test(name);
   }
+  /**
+   * Validate a signing payload string against the ZNS memo format spec.
+   *
+   * This is the single source of truth for payload format validation —
+   * it mirrors the Rust indexer's `parse_memo` and `signing_payload` logic.
+   *
+   * Does NOT validate the signature (see {@link verifyEd25519} for that).
+   * Does NOT validate the name against the blockchain (see {@link isAvailable} for that).
+   *
+   * @param payload - Raw payload string, e.g. `CLAIM:foo:u1abc`
+   * @returns Validation result with level and human-readable message
+   *
+   * @example
+   * ```ts
+   * const result = zns.validatePayload("CLAIM:alice:u1qvs2...");
+   * if (!result.valid) {
+   *   console.error(result.message);
+   * }
+   * ```
+   */
+  validatePayload(payload) {
+    const raw = String(payload ?? "").trim();
+    if (!raw) {
+      return {
+        valid: false,
+        action: "",
+        canonicalAction: null,
+        message: "Empty payload.",
+        level: "invalid"
+      };
+    }
+    const colonIdx = raw.indexOf(":");
+    if (colonIdx === -1) {
+      return {
+        valid: false,
+        action: raw.toUpperCase(),
+        canonicalAction: null,
+        message: "Missing colon separator. Expected format: ACTION:field1:field2:...",
+        level: "invalid"
+      };
+    }
+    const actionUpper = raw.slice(0, colonIdx).toUpperCase();
+    const actionLower = raw.slice(0, colonIdx).toLowerCase();
+    const rest = raw.slice(colonIdx + 1);
+    const parts = rest.split(":");
+    switch (actionLower) {
+      case "claim": {
+        if (parts.length !== 2)
+          return mk("invalid", actionUpper, "claim", `Expected CLAIM:<name>:<ua>.`);
+        if (!NAME_RE.test(parts[0]))
+          return mk("invalid", actionUpper, "claim", `Invalid name. Use lowercase a-z and 0-9, 1 to 62 chars.`);
+        if (!this.isValidUnifiedAddress(parts[1]))
+          return mk("invalid", actionUpper, "claim", `Invalid unified address: "${parts[1]}".`);
+        return mk("valid", actionUpper, "claim", "Valid CLAIM payload.");
+      }
+      case "buy": {
+        if (parts.length !== 2)
+          return mk("invalid", actionUpper, "buy", `Expected BUY:<name>:<buyer_ua>.`);
+        if (!NAME_RE.test(parts[0]))
+          return mk("invalid", actionUpper, "buy", `Invalid name. Use lowercase a-z and 0-9, 1 to 62 chars.`);
+        if (!this.isValidUnifiedAddress(parts[1]))
+          return mk("invalid", actionUpper, "buy", `Invalid unified address: "${parts[1]}".`);
+        return mk("valid", actionUpper, "buy", "Valid BUY payload.");
+      }
+      case "update": {
+        if (parts.length !== 3)
+          return mk("invalid", actionUpper, "update", `Expected UPDATE:<name>:<ua>:<nonce>.`);
+        if (!NAME_RE.test(parts[0]))
+          return mk("invalid", actionUpper, "update", `Invalid name. Use lowercase a-z and 0-9, 1 to 62 chars.`);
+        if (!this.isValidUnifiedAddress(parts[1]))
+          return mk("invalid", actionUpper, "update", `Invalid unified address: "${parts[1]}".`);
+        if (!isWholeNumber(parts[2]))
+          return mk("invalid", actionUpper, "update", `Nonce must be a whole number.`);
+        return mk("valid", actionUpper, "update", "Valid UPDATE payload.");
+      }
+      case "list": {
+        if (parts.length !== 4)
+          return mk("invalid", actionUpper, "list", `Expected LIST:<name>:<price_zats>:<pay_taddr>:<nonce>.`);
+        if (!NAME_RE.test(parts[0]))
+          return mk("invalid", actionUpper, "list", `Invalid name. Use lowercase a-z and 0-9, 1 to 62 chars.`);
+        if (!isWholeNumber(parts[1]) || Number(parts[1]) <= 0)
+          return mk("invalid", actionUpper, "list", `Price must be a positive whole number in zats.`);
+        if (!isWholeNumber(parts[3]))
+          return mk("invalid", actionUpper, "list", `Nonce must be a whole number.`);
+        return mk("valid", actionUpper, "list", "Valid LIST payload.");
+      }
+      case "delist": {
+        if (parts.length !== 2)
+          return mk("invalid", actionUpper, "delist", `Expected DELIST:<name>:<nonce>.`);
+        if (!NAME_RE.test(parts[0]))
+          return mk("invalid", actionUpper, "delist", `Invalid name. Use lowercase a-z and 0-9, 1 to 62 chars.`);
+        if (!isWholeNumber(parts[1]))
+          return mk("invalid", actionUpper, "delist", `Nonce must be a whole number.`);
+        return mk("valid", actionUpper, "delist", "Valid DELIST payload.");
+      }
+      case "release": {
+        if (parts.length !== 2)
+          return mk("invalid", actionUpper, "release", `Expected RELEASE:<name>:<nonce>.`);
+        if (!NAME_RE.test(parts[0]))
+          return mk("invalid", actionUpper, "release", `Invalid name. Use lowercase a-z and 0-9, 1 to 62 chars.`);
+        if (!isWholeNumber(parts[1]))
+          return mk("invalid", actionUpper, "release", `Nonce must be a whole number.`);
+        return mk("valid", actionUpper, "release", "Valid RELEASE payload.");
+      }
+      default:
+        return {
+          valid: false,
+          action: actionUpper,
+          canonicalAction: null,
+          message: `Unrecognized action "${actionUpper}". Valid actions: ${ZNS_ACTIONS.join(", ")}.`,
+          level: "unrecognized"
+        };
+    }
+  }
   /**
    * Get the claim cost in zatoshis for a name of given length.
    * @param nameLength The length of the name (1-62)
@@ -416,5 +538,6 @@ var ZNS = class {
   LIST_COMMISSION,
   MAINNET_UIVK,
   TESTNET_UIVK,
-  ZNS
+  ZNS,
+  ZNS_ACTIONS
 });

package/dist/zns.d.cts

@@ -133,10 +133,29 @@ interface PreparedSetPrice extends PreparedAction {
     readonly prices: readonly Zats[];
     readonly nonce: number;
 }
+/** Validation result for a signing payload.
+ *  Mirrors the Rust indexer's parse_memo format validation.
+ *  @see https://github.com/zcashme/ZNS/blob/main/src/memo.rs */
+type PayloadValidationLevel = "valid" | "invalid" | "unrecognized";
+interface PayloadValidationResult {
+    /** Whether the payload is valid for signing. */
+    readonly valid: boolean;
+    /** Parsed action name (uppercase), e.g. "CLAIM", "LIST" */
+    readonly action: string;
+    /** Canonical action used internally (lowercase), e.g. "claim", "list" */
+    readonly canonicalAction: string | null;
+    /** Human-readable validation message */
+    readonly message: string;
+    /** Validation level: valid | invalid | unrecognized */
+    readonly level: PayloadValidationLevel;
+}
 
 declare const DEFAULT_URL = "https://light.zcash.me/zns-testnet";
 declare const TESTNET_UIVK = "uivktest1hzw7wyadutvzfgpna80yftsk5l7jeyu2p5me5quvp28tytxueta00cx4068wnlzcv7tx9n3t3gfhsy83pe4y6jrhxtzaq0hj6xtg5zrk2dn7zen3vns2a5pgs4fxdjlletmqrhfa42";
 declare const MAINNET_UIVK = "uivk1gl26qy0xjja7lqhyg3pf0x4j4j66kqwewrjkdcg28eqq4wgtzjmujpee7x9cs2ec9xhnlgrm8ptlw8z80j2aryw8nqtssser2ys778a0s00uvgkdjnfr58sndhfvc3f4zqjs6ywva6";
+/** Actions accepted by {@link validatePayload}. Exposed for consumers who need
+ *  to build action selectors or dynamic validation. */
+declare const ZNS_ACTIONS: readonly ["CLAIM", "BUY", "UPDATE", "LIST", "DELIST", "RELEASE"];
 type Network = "testnet" | "mainnet";
 declare class ZNS {
     private url;
@@ -201,6 +220,27 @@ declare class ZNS {
     verifyRegistration(reg: Registration, adminPubkey: string): Promise<boolean>;
     /** Check if a name is valid format (lowercase alphanumeric, 1-62 chars). */
     isValidName(name: string): boolean;
+    /**
+     * Validate a signing payload string against the ZNS memo format spec.
+     *
+     * This is the single source of truth for payload format validation —
+     * it mirrors the Rust indexer's `parse_memo` and `signing_payload` logic.
+     *
+     * Does NOT validate the signature (see {@link verifyEd25519} for that).
+     * Does NOT validate the name against the blockchain (see {@link isAvailable} for that).
+     *
+     * @param payload - Raw payload string, e.g. `CLAIM:foo:u1abc`
+     * @returns Validation result with level and human-readable message
+     *
+     * @example
+     * ```ts
+     * const result = zns.validatePayload("CLAIM:alice:u1qvs2...");
+     * if (!result.valid) {
+     *   console.error(result.message);
+     * }
+     * ```
+     */
+    validatePayload(payload: string): PayloadValidationResult;
     /**
      * Get the claim cost in zatoshis for a name of given length.
      * @param nameLength The length of the name (1-62)
@@ -246,4 +286,4 @@ declare class ZNS {
     private rpc;
 }
 
-export { BUY_COMMISSION, type CompletedAction, DEFAULT_URL, type Event, type EventAction, type EventsFilter, type EventsResult, LIST_COMMISSION, type LastAction, type Listing, MAINNET_UIVK, type Network, type PendingBuy, type PreparedBuy, type PreparedClaim, type PreparedDelist, type PreparedList, type PreparedRelease, type PreparedSetPrice, type PreparedUpdate, type Pricing, type Registration, type Status, TESTNET_UIVK, ZNS, type Zats };
+export { BUY_COMMISSION, type CompletedAction, DEFAULT_URL, type Event, type EventAction, type EventsFilter, type EventsResult, LIST_COMMISSION, type LastAction, type Listing, MAINNET_UIVK, type Network, type PayloadValidationLevel, type PayloadValidationResult, type PendingBuy, type PreparedBuy, type PreparedClaim, type PreparedDelist, type PreparedList, type PreparedRelease, type PreparedSetPrice, type PreparedUpdate, type Pricing, type Registration, type Status, TESTNET_UIVK, ZNS, ZNS_ACTIONS, type Zats };

package/dist/zns.d.ts

@@ -133,10 +133,29 @@ interface PreparedSetPrice extends PreparedAction {
     readonly prices: readonly Zats[];
     readonly nonce: number;
 }
+/** Validation result for a signing payload.
+ *  Mirrors the Rust indexer's parse_memo format validation.
+ *  @see https://github.com/zcashme/ZNS/blob/main/src/memo.rs */
+type PayloadValidationLevel = "valid" | "invalid" | "unrecognized";
+interface PayloadValidationResult {
+    /** Whether the payload is valid for signing. */
+    readonly valid: boolean;
+    /** Parsed action name (uppercase), e.g. "CLAIM", "LIST" */
+    readonly action: string;
+    /** Canonical action used internally (lowercase), e.g. "claim", "list" */
+    readonly canonicalAction: string | null;
+    /** Human-readable validation message */
+    readonly message: string;
+    /** Validation level: valid | invalid | unrecognized */
+    readonly level: PayloadValidationLevel;
+}
 
 declare const DEFAULT_URL = "https://light.zcash.me/zns-testnet";
 declare const TESTNET_UIVK = "uivktest1hzw7wyadutvzfgpna80yftsk5l7jeyu2p5me5quvp28tytxueta00cx4068wnlzcv7tx9n3t3gfhsy83pe4y6jrhxtzaq0hj6xtg5zrk2dn7zen3vns2a5pgs4fxdjlletmqrhfa42";
 declare const MAINNET_UIVK = "uivk1gl26qy0xjja7lqhyg3pf0x4j4j66kqwewrjkdcg28eqq4wgtzjmujpee7x9cs2ec9xhnlgrm8ptlw8z80j2aryw8nqtssser2ys778a0s00uvgkdjnfr58sndhfvc3f4zqjs6ywva6";
+/** Actions accepted by {@link validatePayload}. Exposed for consumers who need
+ *  to build action selectors or dynamic validation. */
+declare const ZNS_ACTIONS: readonly ["CLAIM", "BUY", "UPDATE", "LIST", "DELIST", "RELEASE"];
 type Network = "testnet" | "mainnet";
 declare class ZNS {
     private url;
@@ -201,6 +220,27 @@ declare class ZNS {
     verifyRegistration(reg: Registration, adminPubkey: string): Promise<boolean>;
     /** Check if a name is valid format (lowercase alphanumeric, 1-62 chars). */
     isValidName(name: string): boolean;
+    /**
+     * Validate a signing payload string against the ZNS memo format spec.
+     *
+     * This is the single source of truth for payload format validation —
+     * it mirrors the Rust indexer's `parse_memo` and `signing_payload` logic.
+     *
+     * Does NOT validate the signature (see {@link verifyEd25519} for that).
+     * Does NOT validate the name against the blockchain (see {@link isAvailable} for that).
+     *
+     * @param payload - Raw payload string, e.g. `CLAIM:foo:u1abc`
+     * @returns Validation result with level and human-readable message
+     *
+     * @example
+     * ```ts
+     * const result = zns.validatePayload("CLAIM:alice:u1qvs2...");
+     * if (!result.valid) {
+     *   console.error(result.message);
+     * }
+     * ```
+     */
+    validatePayload(payload: string): PayloadValidationResult;
     /**
      * Get the claim cost in zatoshis for a name of given length.
      * @param nameLength The length of the name (1-62)
@@ -246,4 +286,4 @@ declare class ZNS {
     private rpc;
 }
 
-export { BUY_COMMISSION, type CompletedAction, DEFAULT_URL, type Event, type EventAction, type EventsFilter, type EventsResult, LIST_COMMISSION, type LastAction, type Listing, MAINNET_UIVK, type Network, type PendingBuy, type PreparedBuy, type PreparedClaim, type PreparedDelist, type PreparedList, type PreparedRelease, type PreparedSetPrice, type PreparedUpdate, type Pricing, type Registration, type Status, TESTNET_UIVK, ZNS, type Zats };
+export { BUY_COMMISSION, type CompletedAction, DEFAULT_URL, type Event, type EventAction, type EventsFilter, type EventsResult, LIST_COMMISSION, type LastAction, type Listing, MAINNET_UIVK, type Network, type PayloadValidationLevel, type PayloadValidationResult, type PendingBuy, type PreparedBuy, type PreparedClaim, type PreparedDelist, type PreparedList, type PreparedRelease, type PreparedSetPrice, type PreparedUpdate, type Pricing, type Registration, type Status, TESTNET_UIVK, ZNS, ZNS_ACTIONS, type Zats };

package/dist/zns.js

@@ -15,7 +15,14 @@ var REGISTRY_ADDRESSES = {
   testnet: "utest1f32kn6c4zvn54xr8wfsnxmj9hzpu2mwgtxzpzwcw34906tdccdvzs0z2dx38lly7tpan77x6udt8pjczqm22ymsdhlz9j0tk5yq664nl",
   mainnet: "u1k0evt0ahj5qdt6y9ftsxndl8lrkm4ff6rp00u04cjpmqj6hxl9t8hfsxftmn3ht34e03lljh89czn2h8qn67rwrs8x0hm3lsxsucp9q9"
 };
+var ZNS_ACTIONS = ["CLAIM", "BUY", "UPDATE", "LIST", "DELIST", "RELEASE"];
 var NAME_RE = /^[a-z0-9]{1,62}$/;
+function isWholeNumber(value) {
+  return /^\d+$/.test(value) && !value.startsWith("0") || value === "0";
+}
+function mk(level, action, canonical, message) {
+  return { valid: level === "valid", action, canonicalAction: canonical, message, level };
+}
 var ZNS = class {
   /**
    * Creates a new ZNS client.
@@ -143,6 +150,120 @@ var ZNS = class {
   isValidName(name) {
     return NAME_RE.test(name);
   }
+  /**
+   * Validate a signing payload string against the ZNS memo format spec.
+   *
+   * This is the single source of truth for payload format validation —
+   * it mirrors the Rust indexer's `parse_memo` and `signing_payload` logic.
+   *
+   * Does NOT validate the signature (see {@link verifyEd25519} for that).
+   * Does NOT validate the name against the blockchain (see {@link isAvailable} for that).
+   *
+   * @param payload - Raw payload string, e.g. `CLAIM:foo:u1abc`
+   * @returns Validation result with level and human-readable message
+   *
+   * @example
+   * ```ts
+   * const result = zns.validatePayload("CLAIM:alice:u1qvs2...");
+   * if (!result.valid) {
+   *   console.error(result.message);
+   * }
+   * ```
+   */
+  validatePayload(payload) {
+    const raw = String(payload ?? "").trim();
+    if (!raw) {
+      return {
+        valid: false,
+        action: "",
+        canonicalAction: null,
+        message: "Empty payload.",
+        level: "invalid"
+      };
+    }
+    const colonIdx = raw.indexOf(":");
+    if (colonIdx === -1) {
+      return {
+        valid: false,
+        action: raw.toUpperCase(),
+        canonicalAction: null,
+        message: "Missing colon separator. Expected format: ACTION:field1:field2:...",
+        level: "invalid"
+      };
+    }
+    const actionUpper = raw.slice(0, colonIdx).toUpperCase();
+    const actionLower = raw.slice(0, colonIdx).toLowerCase();
+    const rest = raw.slice(colonIdx + 1);
+    const parts = rest.split(":");
+    switch (actionLower) {
+      case "claim": {
+        if (parts.length !== 2)
+          return mk("invalid", actionUpper, "claim", `Expected CLAIM:<name>:<ua>.`);
+        if (!NAME_RE.test(parts[0]))
+          return mk("invalid", actionUpper, "claim", `Invalid name. Use lowercase a-z and 0-9, 1 to 62 chars.`);
+        if (!this.isValidUnifiedAddress(parts[1]))
+          return mk("invalid", actionUpper, "claim", `Invalid unified address: "${parts[1]}".`);
+        return mk("valid", actionUpper, "claim", "Valid CLAIM payload.");
+      }
+      case "buy": {
+        if (parts.length !== 2)
+          return mk("invalid", actionUpper, "buy", `Expected BUY:<name>:<buyer_ua>.`);
+        if (!NAME_RE.test(parts[0]))
+          return mk("invalid", actionUpper, "buy", `Invalid name. Use lowercase a-z and 0-9, 1 to 62 chars.`);
+        if (!this.isValidUnifiedAddress(parts[1]))
+          return mk("invalid", actionUpper, "buy", `Invalid unified address: "${parts[1]}".`);
+        return mk("valid", actionUpper, "buy", "Valid BUY payload.");
+      }
+      case "update": {
+        if (parts.length !== 3)
+          return mk("invalid", actionUpper, "update", `Expected UPDATE:<name>:<ua>:<nonce>.`);
+        if (!NAME_RE.test(parts[0]))
+          return mk("invalid", actionUpper, "update", `Invalid name. Use lowercase a-z and 0-9, 1 to 62 chars.`);
+        if (!this.isValidUnifiedAddress(parts[1]))
+          return mk("invalid", actionUpper, "update", `Invalid unified address: "${parts[1]}".`);
+        if (!isWholeNumber(parts[2]))
+          return mk("invalid", actionUpper, "update", `Nonce must be a whole number.`);
+        return mk("valid", actionUpper, "update", "Valid UPDATE payload.");
+      }
+      case "list": {
+        if (parts.length !== 4)
+          return mk("invalid", actionUpper, "list", `Expected LIST:<name>:<price_zats>:<pay_taddr>:<nonce>.`);
+        if (!NAME_RE.test(parts[0]))
+          return mk("invalid", actionUpper, "list", `Invalid name. Use lowercase a-z and 0-9, 1 to 62 chars.`);
+        if (!isWholeNumber(parts[1]) || Number(parts[1]) <= 0)
+          return mk("invalid", actionUpper, "list", `Price must be a positive whole number in zats.`);
+        if (!isWholeNumber(parts[3]))
+          return mk("invalid", actionUpper, "list", `Nonce must be a whole number.`);
+        return mk("valid", actionUpper, "list", "Valid LIST payload.");
+      }
+      case "delist": {
+        if (parts.length !== 2)
+          return mk("invalid", actionUpper, "delist", `Expected DELIST:<name>:<nonce>.`);
+        if (!NAME_RE.test(parts[0]))
+          return mk("invalid", actionUpper, "delist", `Invalid name. Use lowercase a-z and 0-9, 1 to 62 chars.`);
+        if (!isWholeNumber(parts[1]))
+          return mk("invalid", actionUpper, "delist", `Nonce must be a whole number.`);
+        return mk("valid", actionUpper, "delist", "Valid DELIST payload.");
+      }
+      case "release": {
+        if (parts.length !== 2)
+          return mk("invalid", actionUpper, "release", `Expected RELEASE:<name>:<nonce>.`);
+        if (!NAME_RE.test(parts[0]))
+          return mk("invalid", actionUpper, "release", `Invalid name. Use lowercase a-z and 0-9, 1 to 62 chars.`);
+        if (!isWholeNumber(parts[1]))
+          return mk("invalid", actionUpper, "release", `Nonce must be a whole number.`);
+        return mk("valid", actionUpper, "release", "Valid RELEASE payload.");
+      }
+      default:
+        return {
+          valid: false,
+          action: actionUpper,
+          canonicalAction: null,
+          message: `Unrecognized action "${actionUpper}". Valid actions: ${ZNS_ACTIONS.join(", ")}.`,
+          level: "unrecognized"
+        };
+    }
+  }
   /**
    * Get the claim cost in zatoshis for a name of given length.
    * @param nameLength The length of the name (1-62)
@@ -376,5 +497,6 @@ export {
   LIST_COMMISSION,
   MAINNET_UIVK,
   TESTNET_UIVK,
-  ZNS
+  ZNS,
+  ZNS_ACTIONS
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zcashname-sdk",
-  "version": "0.8.1",
+  "version": "0.8.3",
   "type": "module",
   "description": "TypeScript SDK for the Zcash Name System (ZNS)",
   "main": "dist/zns.cjs",