@parity/product-sdk 0.22.0 → 0.23.0

package/src/identity/dotns.test.ts

@@ -0,0 +1,128 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+import { describe, expect, test } from "vitest";
+import { stripSuffix } from "./dotns-namehash.js";
+import { isResolvableDotNsName, isValidDotNsName, normalizeDotNsName } from "./dotns.js";
+
+// The two deployments these helpers actually have to serve. Every case below
+// runs against `.paseo` as well as `.dot`, because a helper that only behaves
+// on a four-character suffix is the defect being fixed.
+const DOT = ".dot";
+const PASEO = ".paseo";
+
+describe("stripSuffix", () => {
+    test("removes the suffix by its own length", () => {
+        expect(stripSuffix("alice.paseo", PASEO)).toBe("alice");
+        expect(stripSuffix("alice.dot", DOT)).toBe("alice");
+    });
+
+    test("a six-character suffix does not lose two characters to a hardcoded 4", () => {
+        // `slice(0, -4)` returns "alice.pa" here, which then hashes and queries
+        // as the subname `pa` under `alice`.
+        expect(stripSuffix("alice.paseo", PASEO)).not.toBe("alice.pa");
+    });
+
+    test("leaves a name that does not carry the suffix untouched", () => {
+        expect(stripSuffix("alice", PASEO)).toBe("alice");
+        expect(stripSuffix("alice.dot", PASEO)).toBe("alice.dot");
+    });
+
+    test("keeps subname structure", () => {
+        expect(stripSuffix("bob.alice.paseo", PASEO)).toBe("bob.alice");
+    });
+
+    test("a bare suffix strips to the empty label", () => {
+        expect(stripSuffix(".paseo", PASEO)).toBe("");
+    });
+});
+
+describe("normalizeDotNsName", () => {
+    test("appends the deployment's suffix to a bare label", () => {
+        expect(normalizeDotNsName("alice", PASEO)).toBe("alice.paseo");
+        expect(normalizeDotNsName("alice", DOT)).toBe("alice.dot");
+    });
+
+    test("is idempotent for a name that already carries the suffix", () => {
+        expect(normalizeDotNsName("alice.paseo", PASEO)).toBe("alice.paseo");
+    });
+
+    test("leaves a foreign suffix alone instead of burying it", () => {
+        // The rule this pins: appending only when there is no dot at all means
+        // `alice.dot` survives to be refused by validation. The `endsWith`
+        // rule would produce `alice.dot.paseo`, which is a well-formed subname
+        // and would resolve silently to a node nobody owns.
+        expect(normalizeDotNsName("alice.dot", PASEO)).toBe("alice.dot");
+        expect(normalizeDotNsName("alice.dot", PASEO)).not.toBe("alice.dot.paseo");
+    });
+
+    test("leaves a bare multi-label name alone", () => {
+        // Recorded behaviour change: this used to become `bob.alice.dot` and
+        // resolve. It is now left as-is and refused by validation, because
+        // telling `bob.alice` from `alice.dot` needs a list of known TLDs.
+        expect(normalizeDotNsName("bob.alice", PASEO)).toBe("bob.alice");
+    });
+
+    test("lowercases, trims, and drops a single trailing root dot", () => {
+        // Matches `normalize_host` in truapi-server, so a name arriving from a
+        // URL keys the same way here as it does in the host.
+        expect(normalizeDotNsName("  Alice.PASEO.  ", PASEO)).toBe("alice.paseo");
+        expect(normalizeDotNsName("ALICE", PASEO)).toBe("alice.paseo");
+    });
+
+    test("drops only one trailing dot, so a doubled dot stays visible", () => {
+        // `alice.paseo..` is malformed and must reach validation as such
+        // rather than being quietly repaired into a valid name.
+        expect(normalizeDotNsName("alice.paseo..", PASEO)).toBe("alice.paseo.");
+    });
+});
+
+describe("isValidDotNsName", () => {
+    test("accepts one label under the deployment's suffix", () => {
+        expect(isValidDotNsName("alice.paseo", PASEO)).toBe(true);
+        expect(isValidDotNsName("alice.dot", DOT)).toBe(true);
+    });
+
+    test("refuses another deployment's suffix", () => {
+        expect(isValidDotNsName("alice.dot", PASEO)).toBe(false);
+        expect(isValidDotNsName("alice.paseo", DOT)).toBe(false);
+    });
+
+    test("refuses a subname, which the registrar cannot mint", () => {
+        expect(isValidDotNsName("bob.alice.paseo", PASEO)).toBe(false);
+    });
+
+    test("applies the label rule to the label, not to the suffix's length", () => {
+        // With a hardcoded `slice(0, -4)` the label here would be `dim2.pa`,
+        // which fails the label regex and would reject a registrable name.
+        expect(isValidDotNsName("dim2.paseo", PASEO)).toBe(true);
+    });
+
+    test("keeps the on-chain label rules", () => {
+        expect(isValidDotNsName("ab.paseo", PASEO)).toBe(false); // under 3 chars
+        expect(isValidDotNsName("-alice.paseo", PASEO)).toBe(false); // edge hyphen
+        expect(isValidDotNsName("al ice.paseo", PASEO)).toBe(false); // space
+        expect(isValidDotNsName(`${"a".repeat(64)}.paseo`, PASEO)).toBe(false); // over 63
+    });
+});
+
+describe("isResolvableDotNsName", () => {
+    test("accepts a subname, which the registry supports even though the registrar does not", () => {
+        expect(isResolvableDotNsName("bob.alice.paseo", PASEO)).toBe(true);
+        expect(isResolvableDotNsName("alice.paseo", PASEO)).toBe(true);
+    });
+
+    test("refuses another deployment's suffix", () => {
+        expect(isResolvableDotNsName("bob.alice.dot", PASEO)).toBe(false);
+    });
+
+    test("extracts the labels by suffix length, not by a constant 4", () => {
+        // `slice(0, -4)` would split `dim2.pa` into ["dim2", "pa"] and reject
+        // it on the 3-character minimum.
+        expect(isResolvableDotNsName("dim2.paseo", PASEO)).toBe(true);
+    });
+
+    test("refuses an empty label anywhere in the chain", () => {
+        expect(isResolvableDotNsName("bob..alice.paseo", PASEO)).toBe(false);
+        expect(isResolvableDotNsName(".paseo", PASEO)).toBe(false);
+    });
+});

package/src/identity/dotns.ts

@@ -3,12 +3,16 @@
 /**
  * DotNS (Polkadot Name Service) utilities
  *
- * Provides name resolution for .dot domains
+ * Name validation and normalization. Every helper here takes the deployment's
+ * TLD suffix rather than assuming `.dot`: the TLD is fixed per network when the
+ * contracts initialise, so the same string is a valid name on one deployment
+ * and meaningless on another. `resolveTld` in `./dotns-registry.js` is what
+ * asks the chain which suffix is in play.
  */
 
 import { accountIdBytes } from "@parity/product-sdk-address";
 import { bytesToHex, hexToBytes } from "@parity/product-sdk-crypto";
-import { createLogger } from "@parity/product-sdk-logger";
+import { stripSuffix } from "./dotns-namehash.js";
 import type {
     ChainDefinition,
     PalletsTypedef,
@@ -18,9 +22,6 @@ import type {
     StorageDescriptor,
     TxDescriptor,
 } from "polkadot-api";
-import type { DotNsRecord } from "./types.js";
-
-const log = createLogger("identity");
 
 type AnyDescriptorEntry<T> = Record<string, Record<string, T>>;
 
@@ -71,100 +72,103 @@ export type PeopleUsernameQueryApi = {
 };
 
 /**
- * Check if a string is a valid DotNS name
+ * Whether `name` is a single registrable label under `suffix`.
+ *
+ * `suffix` is the deployment's own TLD, including its leading dot, as
+ * `resolveTld` reports it — `".dot"` on Paseo Asset Hub Previewnet, `".paseo"`
+ * on Next V2. It is required rather than defaulted, because a name is only
+ * valid *relative to a deployment*: `alice.dot` is registrable on one network
+ * and meaningless on the other, and a default would silently pick one.
  *
- * @param name - Name to validate
- * @returns True if valid DotNS name
+ * @param name - Name to validate, already normalized by {@link normalizeDotNsName}
+ * @param suffix - The deployment's TLD suffix, e.g. `".paseo"`
  */
-export function isValidDotNsName(name: string): boolean {
-    // Basic validation: alphanumeric, hyphens, ends with .dot
-    if (!name.endsWith(".dot")) return false;
-    const label = name.slice(0, -4);
-    if (label.length < 3 || label.length > 63) return false;
-    return /^[a-z0-9]([a-z0-9-]*[a-z0-9])?$/.test(label);
+export function isValidDotNsName(name: string, suffix: string): boolean {
+    if (!name.endsWith(suffix)) return false;
+    return isValidLabel(stripSuffix(name, suffix));
 }
 
 /**
- * Normalize a DotNS name (lowercase, trim whitespace)
+ * One canonical DNS label, matching the on-chain rule.
  *
- * @param name - Name to normalize
- * @returns Normalized name
+ * `StringUtils.isSingleLabel` allows lowercase ASCII, digits and non-edge
+ * hyphens up to 63 characters, and the registrar additionally requires 3.
  */
-export function normalizeDotNsName(name: string): string {
-    let normalized = name.toLowerCase().trim();
-    if (!normalized.endsWith(".dot")) {
-        normalized += ".dot";
-    }
-    return normalized;
+function isValidLabel(label: string): boolean {
+    if (label.length < 3 || label.length > 63) return false;
+    return /^[a-z0-9]([a-z0-9-]*[a-z0-9])?$/.test(label);
 }
 
 /**
- * Resolve a DotNS name to an address.
+ * Whether a name can be resolved: one or more valid labels under `suffix`.
  *
- * @deprecated Not implemented — throws at runtime. Use
- *   `wallet.signMessageWithDotNsIdentity({ peopleChain, username })` (which
- *   internally calls {@link resolvePeopleUsernameOwner}) for the supported
- *   People-chain username flow.
+ * Broader than {@link isValidDotNsName} on purpose. The registrar only mints
+ * single labels, so registration keeps the stricter rule, but the registry
+ * supports subnodes and `namehash` hashes them, so `bob.alice.paseo` is
+ * resolvable even though it is not registrable.
  *
- * @param name - DotNS name (e.g., "alice.dot")
- * @returns Resolved record or null if not found
+ * @param name - Name to check, already normalized by {@link normalizeDotNsName}
+ * @param suffix - The deployment's TLD suffix, e.g. `".paseo"`
  */
-export async function resolveDotNs(name: string): Promise<DotNsRecord | null> {
-    const normalized = normalizeDotNsName(name);
-
-    if (!isValidDotNsName(normalized)) {
-        log.warn("Invalid DotNS name", { name });
-        return null;
-    }
-
-    log.debug("Resolving DotNS name", { name: normalized });
-
-    // TODO: Implement via PAPI query to DotNS pallet
-    throw new Error(
-        "resolveDotNs() is not yet implemented. " +
-            "This is a skeleton for the Product SDK structure.",
-    );
+export function isResolvableDotNsName(name: string, suffix: string): boolean {
+    if (!name.endsWith(suffix)) return false;
+    const labels = stripSuffix(name, suffix).split(".");
+    return labels.length > 0 && labels.every(isValidLabel);
 }
 
 /**
- * Reverse resolve an address to a DotNS name.
+ * Normalize a DotNS name for the deployment identified by `suffix`.
  *
- * @deprecated Not implemented — throws at runtime. Reverse lookup will land
- *   alongside future identity work; for now resolve forward via
- *   `wallet.signMessageWithDotNsIdentity`.
+ * Case-folds, applies NFC, trims surrounding whitespace, and drops a single
+ * trailing root dot, so `Alice.PASEO.` keys the same as `alice.paseo`. This
+ * mirrors `normalize_host` in truapi-server, which is what turns a URL into a
+ * dotNS identifier — a name arriving from navigation has to key identically
+ * here or the two layers disagree about the same input.
  *
- * @param address - SS58 address
- * @returns Primary name or null if none set
- */
-export async function reverseDotNs(address: string): Promise<string | null> {
-    log.debug("Reverse resolving address", { address });
-
-    // TODO: Implement via PAPI query to DotNS pallet
-    throw new Error(
-        "reverseDotNs() is not yet implemented. " +
-            "This is a skeleton for the Product SDK structure.",
-    );
-}
-
-/**
- * Check if a DotNS name is available for registration.
+ * The NFC step is defensive only: {@link isValidLabel} and the on-chain
+ * `StringUtils.isSingleLabel` both allow lowercase ASCII alone, so no name that
+ * survives validation can differ between its composed and decomposed spellings.
+ * It costs nothing and it keeps this function honest if the label rule ever
+ * widens.
  *
- * @deprecated Not implemented — depends on {@link resolveDotNs} which throws.
+ * **The suffix is appended only when `name` contains no dot at all.** A bare
+ * label is the friendly path and gets the deployment's suffix; anything already
+ * carrying a dot is left exactly as written, so a name from another deployment
+ * survives to be refused by validation rather than being buried under our own
+ * suffix. Appending on `!endsWith(suffix)` instead would turn `alice.dot` into
+ * `alice.dot.paseo`, which is a well-formed subname and would resolve silently
+ * to a node nobody owns.
  *
- * @param name - Name to check
- * @returns True if available
+ * The cost of that rule: a bare multi-label name such as `bob.alice` is no
+ * longer completed to `bob.alice.paseo`. Distinguishing it from `alice.dot`
+ * would require a hardcoded list of every network's TLD, and there are already
+ * more TLDs deployed than any such list contains.
+ *
+ * @param name - Name to normalize
+ * @param suffix - The deployment's TLD suffix, e.g. `".paseo"`
  */
-export async function isDotNsAvailable(name: string): Promise<boolean> {
-    const record = await resolveDotNs(name).catch(() => null);
-    return record === null;
+export function normalizeDotNsName(name: string, suffix: string): string {
+    const folded = name.trim().normalize("NFC").toLowerCase();
+    const normalized = folded.endsWith(".") ? folded.slice(0, -1) : folded;
+    return normalized.includes(".") ? normalized : normalized + suffix;
 }
 
+// `resolveDotNs` / `reverseDotNs` / `isDotNsAvailable` now live in
+// `./dotns-registry.ts` (real `Result`-returning registry calls), replacing the
+// throwing skeletons that used to sit here. See that module + the design doc.
+
 /**
- * Resolve a People / People Lite username to its owning `AccountId32`.
+ * Resolve a People / People Lite username to its owning account.
  *
  * Queries `Resources.UsernameOwnerOf` on the caller-supplied typed-api fragment.
- * The returned value is the raw 32-byte account id as a `0x`-prefixed hex
- * string, or `null` when no owner is registered for that username.
+ * The returned value is the SS58 address the storage yields, or `null` when no
+ * owner is registered for that username.
+ *
+ * Returns SS58 rather than hex because that is both the form the storage yields
+ * and the form `Resources.Consumers` is keyed by, so reading an account's
+ * usernames from this result needs no conversion. Callers that want the raw
+ * 32-byte key use `accountIdBytes` from `@parity/product-sdk-address`, and
+ * {@link accountIdToHex} for the hex form.
  *
  * The `username` is UTF-8 encoded as-is — no normalization is applied. Pass
  * the exact byte string the chain stores (typically with the `.dot` suffix).
@@ -176,13 +180,11 @@ export async function isDotNsAvailable(name: string): Promise<boolean> {
 export async function resolvePeopleUsernameOwner(
     username: string,
     peopleApi: PeopleUsernameQueryApi,
-): Promise<`0x${string}` | null> {
+): Promise<SS58String | null> {
     const owner = await peopleApi.query.Resources.UsernameOwnerOf.getValue(
         new TextEncoder().encode(username),
     );
-    if (!owner) return null;
-
-    return accountIdBytesToHex(accountIdBytes(owner));
+    return owner ?? null;
 }
 
 function assertHex(value: string): `0x${string}` {
@@ -200,9 +202,20 @@ export function accountIdHexToBytes(accountId: `0x${string}`): Uint8Array {
     return bytes;
 }
 
-function accountIdBytesToHex(bytes: Uint8Array): `0x${string}` {
+/** Throws on any input that is not exactly 32 bytes, rather than padding it. */
+export function accountIdBytesToHex(bytes: Uint8Array): `0x${string}` {
     if (bytes.length !== 32) {
         throw new Error(`Expected 32-byte AccountId, got ${bytes.length} bytes`);
     }
     return `0x${bytesToHex(bytes)}`;
 }
+
+/**
+ * The inverse of {@link accountIdHexToBytes}.
+ *
+ * No in-repo caller: this is the migration path for consumers, after
+ * `resolvePeopleUsernameOwner` changed from hex to SS58. Not dead code.
+ */
+export function accountIdToHex(address: string): `0x${string}` {
+    return accountIdBytesToHex(accountIdBytes(address));
+}

package/src/identity/index.test.ts

@@ -0,0 +1,43 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Guards the identity export surface: what must be there, and what must stay gone.
+ */
+import { describe, expect, it } from "vitest";
+import * as identity from "./index.js";
+
+// The check below is a runtime one, so it cannot see a removed type. If this
+// type comes back, the suppression goes unused and typecheck fails.
+// @ts-expect-error must stay removed
+import type { ContextAliasInfo } from "./types.js";
+
+describe("the identity export surface", () => {
+    // Both sets threw or misled on every call, so no working consumer could
+    // exist. Deleting turns a runtime problem into a compile error.
+    it("no longer exports the ring stubs or the context-alias helpers", () => {
+        for (const name of [
+            "deriveAnonymousAlias",
+            "createRingProof",
+            "verifyRingProof",
+            "deriveContextAlias",
+            "verifyContextAlias",
+        ]) {
+            expect(name in identity).toBe(false);
+        }
+    });
+
+    it("still exports the DotNS helpers", () => {
+        for (const name of [
+            "resolveDotNs",
+            "reverseDotNs",
+            "isDotNsAvailable",
+            "resolvePeopleUsernameOwner",
+            "isValidDotNsName",
+            "normalizeDotNsName",
+            "accountIdHexToBytes",
+            "accountIdToHex",
+        ]) {
+            expect(name in identity).toBe(true);
+        }
+    });
+});

package/src/identity/index.ts

@@ -3,33 +3,63 @@
 /**
  * @parity/product-sdk/identity
  *
- * Identity utilities: DotNS name resolution, plus the deprecated context-alias
- * helpers.
+ * Identity utilities: DotNS name resolution and registry access.
  *
- * For real Ring VRF aliases and proofs, use `SignerManager`'s
+ * For Ring VRF aliases and proofs, use `SignerManager`'s
  * `getProductAccountAlias` and `createRingVRFProof` from
  * `@parity/product-sdk-signer`.
  */
 
-// DotNS utilities
+// DotNS utilities (pure helpers + People-chain username path)
 export {
     isValidDotNsName,
+    isResolvableDotNsName,
     normalizeDotNsName,
-    resolveDotNs,
-    reverseDotNs,
-    isDotNsAvailable,
     accountIdHexToBytes,
+    accountIdToHex,
     resolvePeopleUsernameOwner,
 } from "./dotns.js";
 export type { PeopleUsernameChain, PeopleUsernameQueryApi } from "./dotns.js";
 
-// Context alias utilities (deprecated)
-export { deriveContextAlias, verifyContextAlias } from "./product-account.js";
+// DotNS registry reads + writes (Revive contract)
+export {
+    resolveDotNs,
+    reverseDotNs,
+    isDotNsAvailable,
+    setDotNsRecord,
+    prepareDotNsRegistration,
+} from "./dotns-registry.js";
+export type {
+    DotNsClientOptions,
+    RegisterDotNsArgs,
+    SetRecordArgs,
+    DotNsRegistration,
+} from "./dotns-registry.js";
+export { DotNsError } from "./dotns-errors.js";
+export type { DotNsErrorReason } from "./dotns-errors.js";
+export {
+    namehash,
+    dotNsTld,
+    isConsistentDotNsTld,
+    stripSuffix,
+    DOT_NODE,
+    DOT_TLD,
+} from "./dotns-namehash.js";
+export type { DotNsTld } from "./dotns-namehash.js";
+export { POP_STATUS, DOTNS_ADDRESSES } from "./dotns-abis.js";
+
+// Where those addresses come from: the pinned table, or the gateway walk.
+export {
+    DOTNS_REGISTRY_KEYS,
+    discoverDotNsAddresses,
+    resolveDotNsAddresses,
+    verifyDotNsAddresses,
+} from "./dotns-addresses.js";
+export type { DotNsAddresses, DotNsGatewayQueryApi } from "./dotns-addresses.js";
 
 // Types
 export type {
     DotNsRecord,
-    ContextAliasInfo,
     VerificationResult,
     OnChainIdentity,
 } from "./types.js";

package/src/identity/types.ts

@@ -2,39 +2,43 @@
 // SPDX-License-Identifier: Apache-2.0
 /**
  * Identity module types
- *
- * Types for DotNS name resolution and context-alias derivation
  */
 
 /** DotNS name resolution result */
 export interface DotNsRecord {
-    /** Resolved SS58 address */
-    address: string;
-    /** Name that was resolved */
+    /**
+     * H160 the name resolves to, `0x` and 20 bytes. Not SS58: DotNS is a set of
+     * Revive contracts and both address fields come back as EVM addresses.
+     * Convert with `h160ToSs58` from `@parity/product-sdk-address` if a
+     * Substrate-shaped address is needed.
+     *
+     * Absent when the name is registered but has no forward record yet, the
+     * state of every name just after registration. An unregistered name is
+     * `null` from `resolveDotNs`, not a record.
+     */
+    address?: `0x${string}`;
+    /**
+     * Name that was resolved, normalized: lowercased, and carrying the
+     * deployment's own TLD suffix — `.paseo` on Paseo Asset Hub Next V2, `.dot`
+     * on Previewnet. A bare label passed in comes back suffixed.
+     *
+     * Note for a **lite-person** registrant: the registry stores their label
+     * flattened, so `alice.42` is registered as `alice42` and this field reads
+     * `alice42.paseo`. Pass the flattened spelling when resolving; the dotted
+     * one derives a different node and finds nothing.
+     */
     name: string;
-    /** Owner address */
-    owner: string;
-    /** Expiration timestamp (if applicable) */
+    /** H160 of the node's owner. Not SS58, same as {@link DotNsRecord.address}. */
+    owner: `0x${string}`;
+    /**
+     * Expiration timestamp, if the deployment has one.
+     *
+     * Always absent today: the Paseo Asset Hub registrar exposes no expiry
+     * getter, so nothing populates this.
+     */
     expiresAt?: number;
 }
 
-/**
- * Context alias info: a deterministic, context-bound alias derived from a parent account
- *
- * @deprecated Returned by `deriveContextAlias`, whose addresses no key can spend.
- *   Removal: `@parity/product-sdk` 0.23.0.
- */
-export interface ContextAliasInfo {
-    /** Alias SS58 address */
-    address: string;
-    /** H160 EVM address */
-    h160Address: `0x${string}`;
-    /** Parent account address */
-    parentAddress: string;
-    /** Context string used for derivation */
-    context: string;
-}
-
 /** Identity verification result */
 export interface VerificationResult {
     /** Whether identity is verified */