@parity/product-sdk 0.21.0 → 0.23.0

package/src/identity/dotns-addresses.ts

@@ -0,0 +1,320 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Where the DotNS contract addresses come from.
+ *
+ * Every entry point in `./dotns-registry.js` asks {@link resolveDotNsAddresses}
+ * rather than reaching for a constant, so "which address do I call?" has one
+ * answer and the gateway walk can plug in behind it without touching them.
+ */
+import {
+    type AbiEntry,
+    type ContractRuntime,
+    QUERY_FALLBACK_ORIGIN,
+    createContract,
+} from "@parity/product-sdk-contracts";
+import { type Result, err, ok } from "@parity/result";
+import {
+    DOTNS_ADDRESSES,
+    DOTNS_POP_CONTROLLER_ABI,
+    DOTNS_PROTOCOL_REGISTRY_ABI,
+    DOTNS_ROOT_GATEWAY_DISPATCHER_ABI,
+} from "./dotns-abis.js";
+import { DotNsError } from "./dotns-errors.js";
+import type { SS58String } from "polkadot-api";
+import type { DotNsClientOptions } from "./dotns-registry.js";
+
+type HexString = `0x${string}`;
+
+export interface DotNsAddresses {
+    registry: HexString;
+    reverseResolver: HexString;
+    resolver: HexString;
+    registrarController: HexString;
+    popRules: HexString;
+    protocolRegistry: HexString;
+}
+
+/**
+ * The `DotnsProtocolRegistry.get(bytes32)` key each role answers under, from
+ * `DotnsConstants`. Solidity's `bytes32("name")` is the UTF-8 bytes
+ * right-padded with zeros, which is what these literals are.
+ *
+ * Two are not the name you would guess, and guessing wrong is silent: `get`
+ * answers with a live address for the contract you did not want, and it
+ * surfaces much later as a revert. `registrarController` is the commit-reveal
+ * controller, key `controller` — `registrar` is the ERC-721 holding name
+ * ownership. `resolver` is the forward address resolver — `contentResolver`
+ * holds contenthash and text records, which nothing here calls.
+ *
+ * `protocolRegistry` has no key at all, so it cannot be looked up in the
+ * registry it is. The walk reaches it via `popController.protocolRegistry()`.
+ */
+export const DOTNS_REGISTRY_KEYS = {
+    registry: "0x7265676973747279000000000000000000000000000000000000000000000000",
+    registrarController: "0x636f6e74726f6c6c657200000000000000000000000000000000000000000000",
+    reverseResolver: "0x726576657273655265736f6c7665720000000000000000000000000000000000",
+    resolver: "0x7265736f6c766572000000000000000000000000000000000000000000000000",
+    popRules: "0x706f7052756c6573000000000000000000000000000000000000000000000000",
+} as const satisfies Record<Exclude<keyof DotNsAddresses, "protocolRegistry">, HexString>;
+
+export const ZERO_ADDRESS = "0x0000000000000000000000000000000000000000";
+
+export function isZero(addr: unknown): boolean {
+    return typeof addr === "string" && addr.toLowerCase() === ZERO_ADDRESS;
+}
+
+/** viem checksums every decoded `address`, so a read is EIP-55 whatever the chain sent. */
+export function sameAddress(a: unknown, b: unknown): boolean {
+    return typeof a === "string" && typeof b === "string" && a.toLowerCase() === b.toLowerCase();
+}
+
+/** A per-runtime, per-key cache of chain reads that cannot change under us. */
+export type RuntimeCache<T> = WeakMap<ContractRuntime, Map<string, Promise<Result<T, DotNsError>>>>;
+
+/**
+ * Read `key` once per runtime and hand every later caller the same answer.
+ *
+ * Stores the in-flight promise rather than the resolved value, so concurrent
+ * first calls share one read instead of racing. A failed read is dropped from
+ * the cache: those are usually the RPC blinking rather than the deployment
+ * moving, and keeping one would strand the client for the life of the runtime.
+ */
+export function cachedPerRuntime<T>(
+    cache: RuntimeCache<T>,
+    runtime: ContractRuntime,
+    key: string,
+    load: () => Promise<Result<T, DotNsError>>,
+): Promise<Result<T, DotNsError>> {
+    let byKey = cache.get(runtime);
+    if (!byKey) {
+        byKey = new Map();
+        cache.set(runtime, byKey);
+    }
+    const cached = byKey.get(key);
+    if (cached) return cached;
+
+    const pending = load();
+    byKey.set(key, pending);
+    pending.then((result) => {
+        if (!result.ok) byKey?.delete(key);
+    });
+    return pending;
+}
+
+function withOverrides(base: DotNsAddresses, opts: DotNsClientOptions): DotNsAddresses {
+    return {
+        registry: opts.registryAddress ?? base.registry,
+        reverseResolver: opts.reverseResolverAddress ?? base.reverseResolver,
+        resolver: opts.resolverAddress ?? base.resolver,
+        registrarController: opts.registrarControllerAddress ?? base.registrarController,
+        popRules: opts.popRulesAddress ?? base.popRules,
+        protocolRegistry: opts.protocolRegistryAddress ?? base.protocolRegistry,
+    };
+}
+
+/**
+ * Async because the discovered source reads the chain. The pinned source does
+ * no IO, so a caller that only validates a name still pays nothing for it.
+ */
+const walkCache: RuntimeCache<DotNsAddresses> = new WeakMap();
+
+/**
+ * Constant, unlike the TLD cache which keys on the protocol registry address.
+ * Nothing else selects the deployment: `gatewayApi` is required to describe the
+ * same chain as `runtime`, and the walk derives every address from there.
+ */
+const WALK_KEY = "discovered";
+
+export async function resolveDotNsAddresses(
+    opts: DotNsClientOptions,
+): Promise<Result<DotNsAddresses, DotNsError>> {
+    if (opts.addressSource !== "discovered") return ok(withOverrides(DOTNS_ADDRESSES, opts));
+
+    // Cache the walk, not the merged set: two callers differing only in their
+    // overrides must share one walk and still each get their own answer.
+    const walked = await cachedPerRuntime(walkCache, opts.runtime, WALK_KEY, () =>
+        discoverDotNsAddresses(opts),
+    );
+    return walked.ok ? ok(withOverrides(walked.value, opts)) : walked;
+}
+
+/**
+ * Reads `DotnsGateway.DispatcherAddress`, the pallet storage the walk starts
+ * from. Structural because `ContractRuntime` does not declare it.
+ */
+export type DotNsGatewayQueryApi = {
+    query: {
+        DotnsGateway: {
+            DispatcherAddress: {
+                getValue: () => Promise<{ asHex(): string } | string | undefined>;
+            };
+        };
+    };
+};
+
+const discoveryFailed = (step: string, cause?: unknown) =>
+    err(new DotNsError("AddressDiscovery", `DotNS address discovery failed: ${step}`, { cause }));
+
+/**
+ * `createContract` is generic over a typed ABI def; these minimal literal ABIs
+ * are called by name via `.query()`, so the handle is untyped by construction.
+ */
+export function contractOf(runtime: ContractRuntime, address: HexString, abi: AbiEntry[]) {
+    return createContract(runtime, address, abi as any) as any;
+}
+
+/**
+ * Origin for a read. Passing the fallback explicitly rather than letting the
+ * contracts layer substitute it keeps each query from logging a warning.
+ */
+export function readOrigin(opts: DotNsClientOptions): SS58String {
+    return opts.origin ?? QUERY_FALLBACK_ORIGIN;
+}
+
+async function readAddress(
+    contract: {
+        [m: string]: { query: (o: object) => Promise<{ success: boolean; value: unknown }> };
+    },
+    method: string,
+    origin: string,
+): Promise<Result<HexString, DotNsError>> {
+    const res = await contract[method].query({ origin });
+    if (!res.success) return discoveryFailed(`${method}() failed`, res.value);
+    const value = res.value;
+    if (typeof value !== "string" || isZero(value)) {
+        return discoveryFailed(`${method}() returned no address`);
+    }
+    return ok(value as HexString);
+}
+
+/** PAPI hands back H160 as a wrapper or a hex string depending on the major. */
+function asH160(value: unknown): HexString | null {
+    if (typeof value === "string") return value as HexString;
+    if (value && typeof (value as { asHex?: unknown }).asHex === "function") {
+        return (value as { asHex(): string }).asHex() as HexString;
+    }
+    return null;
+}
+
+function gatewayOf(opts: DotNsClientOptions): DotNsGatewayQueryApi | null {
+    if (opts.gatewayApi) return opts.gatewayApi;
+    const api = opts.runtime?.api as unknown as Partial<DotNsGatewayQueryApi> | undefined;
+    const getValue = api?.query?.DotnsGateway?.DispatcherAddress?.getValue;
+    return typeof getValue === "function" ? (api as DotNsGatewayQueryApi) : null;
+}
+
+/**
+ * Locate the live deployment from chain state, trusting nothing pinned here.
+ *
+ * Pallet -> `dispatcher.TARGET()` -> `popController.protocolRegistry()` ->
+ * `get(key)` per role. The first three are sequential because each answer is
+ * the next call's address; the role reads are not, so they go together.
+ *
+ * A failed or zero read is always an error: falling back to the pinned table
+ * would recreate the situation this exists to detect, and hide it better.
+ */
+export async function discoverDotNsAddresses(
+    opts: DotNsClientOptions,
+): Promise<Result<DotNsAddresses, DotNsError>> {
+    try {
+        const gateway = gatewayOf(opts);
+        if (!gateway) {
+            return discoveryFailed(
+                "no DotnsGateway.DispatcherAddress storage on this runtime; pass opts.gatewayApi",
+            );
+        }
+        const dispatcher = asH160(await gateway.query.DotnsGateway.DispatcherAddress.getValue());
+        if (!dispatcher || isZero(dispatcher)) {
+            return discoveryFailed("DotnsGateway.DispatcherAddress is unset");
+        }
+
+        const origin = readOrigin(opts);
+        const target = await readAddress(
+            contractOf(opts.runtime, dispatcher, DOTNS_ROOT_GATEWAY_DISPATCHER_ABI),
+            "TARGET",
+            origin,
+        );
+        if (!target.ok) return target;
+
+        const protocolRegistry = await readAddress(
+            contractOf(opts.runtime, target.value, DOTNS_POP_CONTROLLER_ABI),
+            "protocolRegistry",
+            origin,
+        );
+        if (!protocolRegistry.ok) return protocolRegistry;
+
+        const registry = contractOf(
+            opts.runtime,
+            protocolRegistry.value,
+            DOTNS_PROTOCOL_REGISTRY_ABI,
+        );
+        const roles = Object.entries(DOTNS_REGISTRY_KEYS) as [
+            keyof typeof DOTNS_REGISTRY_KEYS,
+            HexString,
+        ][];
+        // Not readAddress: that calls the method with no arguments, and these
+        // need the role name in the error rather than the method name, since
+        // every one of them is the same `get`.
+        const found = await Promise.all(
+            roles.map(async ([role, key]) => {
+                const res = await registry.get.query(key, { origin });
+                if (!res.success) return discoveryFailed(`get(${role}) failed`, res.value);
+                const value = res.value;
+                // A wrong key is not an error on chain: it returns address(0),
+                // so the role name is the only clue the caller gets.
+                if (typeof value !== "string" || isZero(value)) {
+                    return discoveryFailed(`${role} is unset on the protocol registry`);
+                }
+                return ok([role, value as HexString] as const);
+            }),
+        );
+        const failed = found.find((r) => !r.ok);
+        if (failed && !failed.ok) return failed;
+
+        const byRole = Object.fromEntries(found.flatMap((r) => (r.ok ? [r.value] : []))) as Omit<
+            DotNsAddresses,
+            "protocolRegistry"
+        >;
+        return ok({ ...byRole, protocolRegistry: protocolRegistry.value });
+    } catch (cause) {
+        return discoveryFailed("unexpected error", cause);
+    }
+}
+
+/**
+ * Walk the gateway and report every role whose live address differs from the
+ * one this client would call. Meant for startup: it fails loudly once, rather
+ * than making every later read pay for the check.
+ */
+export async function verifyDotNsAddresses(
+    opts: DotNsClientOptions,
+): Promise<Result<DotNsAddresses, DotNsError>> {
+    // Through the cache, so verifying at startup and then using the client is
+    // one walk rather than two.
+    const discovered = await cachedPerRuntime(walkCache, opts.runtime, WALK_KEY, () =>
+        discoverDotNsAddresses(opts),
+    );
+    if (!discovered.ok) return discovered;
+
+    // Compare what this client actually calls, which is the pinned table or the
+    // walk depending on the source, with the caller's overrides on top either
+    // way. A discovered client can still drift, through an override that
+    // disagrees with the chain; it is only the pinned base that cannot apply.
+    const inUse = withOverrides(
+        opts.addressSource === "discovered" ? discovered.value : DOTNS_ADDRESSES,
+        opts,
+    );
+    const drift = (Object.keys(inUse) as (keyof DotNsAddresses)[])
+        .filter((role) => !sameAddress(inUse[role], discovered.value[role]))
+        .map((role) => `${role}: using ${inUse[role]}, chain says ${discovered.value[role]}`);
+
+    return drift.length
+        ? err(
+              new DotNsError(
+                  "AddressMismatch",
+                  `DotNS addresses disagree with the deployment — ${drift.join("; ")}`,
+              ),
+          )
+        : ok(inUse);
+}

package/src/identity/dotns-errors.ts

@@ -0,0 +1,36 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+import type { SdkError } from "@parity/product-sdk-errors";
+
+/**
+ * Error on the `Err` channel of a DotNS registry read/write. Implements the
+ * cross-package {@link SdkError} marker so `isSdkError(e)` recognizes it.
+ *
+ * `reason` distinguishes the failure kind so callers can branch without string
+ * matching.
+ */
+export type DotNsErrorReason =
+    | "InvalidName" // name failed isValidDotNsName
+    | "InvalidTld" // the deployment reported a TLD we cannot use, or the caller supplied an inconsistent one
+    | "TldMismatch" // a well-formed name, but rooted at another deployment's TLD
+    | "MissingOrigin" // a write was requested without the submitting account
+    | "InvalidOrigin" // the submitting account was supplied, but is not a decodable SS58 address
+    | "NameUnavailable" // already registered
+    | "NameReserved" // governance-held, or a base stem held by another user
+    | "OwnerStatusInsufficient" // the owner lacks the personhood tier the label requires
+    | "AddressDiscovery" // the gateway walk could not locate the deployment
+    | "AddressMismatch" // a discovered address disagrees with the one in use
+    | "RegistryCall" // the on-chain contract call failed
+    | "Decode"; // the contract returned something we couldn't decode
+
+export class DotNsError extends Error implements SdkError {
+    readonly isSdkError = true as const;
+    readonly source = "dotns";
+    readonly reason: DotNsErrorReason;
+
+    constructor(reason: DotNsErrorReason, message: string, options?: ErrorOptions) {
+        super(message, options);
+        this.name = "DotNsError";
+        this.reason = reason;
+    }
+}

package/src/identity/dotns-namehash.test.ts

@@ -0,0 +1,155 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+import { bytesToHex, keccak256 } from "@parity/product-sdk-crypto";
+import { describe, expect, test } from "vitest";
+import { DOT_NODE, DOT_TLD, dotNsTld, isConsistentDotNsTld, namehash } from "./dotns-namehash.js";
+
+// Independent reference implementation of the same algorithm, so the test
+// pins behaviour rather than restating the code.
+function hexBytes(hex: string): Uint8Array {
+    const pairs = hex.slice(2).match(/.{2}/g) ?? [];
+    return Uint8Array.from(pairs.map((b) => Number.parseInt(b, 16)));
+}
+
+function refNamehash(name: string, suffix: string, root: string): string {
+    const trimmed = name.endsWith(suffix) ? name.slice(0, -suffix.length) : name;
+    const labels = trimmed === "" ? [] : trimmed.split(".");
+    let node = hexBytes(root);
+    for (let i = labels.length - 1; i >= 0; i--) {
+        const lh = keccak256(new TextEncoder().encode(labels[i]));
+        const combined = new Uint8Array(64);
+        combined.set(node, 0);
+        combined.set(lh, 32);
+        node = keccak256(combined);
+    }
+    return `0x${bytesToHex(node)}`;
+}
+
+/**
+ * The `.paseo` TLD node, as `DotnsProtocolRegistry.tldNode()` reports it on
+ * Paseo Asset Hub Next V2.
+ *
+ * Pinned as an observed literal on purpose: it is the one value that proves our
+ * derivation matches what the contract computed at initialisation. Deriving it
+ * here instead would make the test agree with the code by construction.
+ *
+ * Needs no re-verification — it is `keccak256(0x00…00 ‖ keccak256("paseo"))`,
+ * so it is fixed by the label alone, not by any deployment's current state.
+ */
+const PASEO_NODE_FROM_CHAIN = "0x096b436ee9a398429fe33ad4b359bad4398dd74b412ec1dd043c93dfbf581874";
+
+const PASEO_TLD = dotNsTld(".paseo");
+
+describe("dotns namehash", () => {
+    test("DOT_NODE is keccak256(zeros32 || keccak256('dot'))", () => {
+        // The only hardcoded value in the module: every node hash derives from
+        // it, and namehash(".dot") returning it is a tautology, since an empty
+        // label list skips the loop. Derive it instead.
+        const labelhash = keccak256(new TextEncoder().encode("dot"));
+        const combined = new Uint8Array(64); // leading 32 bytes are the zero root
+        combined.set(labelhash, 32);
+        expect(`0x${bytesToHex(keccak256(combined))}`).toBe(DOT_NODE);
+    });
+
+    test("bare .dot hashes to the DOT_NODE constant", () => {
+        expect(namehash(".dot", DOT_TLD)).toBe(DOT_NODE);
+        expect(namehash("", DOT_TLD)).toBe(DOT_NODE);
+    });
+
+    test("normalizes the same with or without the .dot suffix", () => {
+        expect(namehash("alice.dot", DOT_TLD)).toBe(namehash("alice", DOT_TLD));
+    });
+
+    test("matches the reference algorithm for single + sub labels", () => {
+        expect(namehash("alice.dot", DOT_TLD)).toBe(refNamehash("alice.dot", ".dot", DOT_NODE));
+        expect(namehash("bob.alice.dot", DOT_TLD)).toBe(
+            refNamehash("bob.alice.dot", ".dot", DOT_NODE),
+        );
+    });
+
+    test("distinct names produce distinct nodes", () => {
+        expect(namehash("alice.dot", DOT_TLD)).not.toBe(namehash("bob.dot", DOT_TLD));
+    });
+
+    test("returns a 32-byte 0x-hex string", () => {
+        expect(namehash("alice.dot", DOT_TLD)).toMatch(/^0x[0-9a-f]{64}$/);
+    });
+
+    test("roots at the TLD it is given, matching the reference algorithm", () => {
+        expect(namehash("alice.paseo", PASEO_TLD)).toBe(
+            refNamehash("alice.paseo", ".paseo", PASEO_NODE_FROM_CHAIN),
+        );
+        expect(namehash("bob.alice.paseo", PASEO_TLD)).toBe(
+            refNamehash("bob.alice.paseo", ".paseo", PASEO_NODE_FROM_CHAIN),
+        );
+    });
+
+    test("the same label under two TLDs gives two different nodes", () => {
+        // The bug this whole change exists for, in one assertion: `dim2` is
+        // owned on paseo-asset-hub-next under `.paseo` and unowned under `.dot`.
+        expect(namehash("alice.paseo", PASEO_TLD)).not.toBe(namehash("alice.dot", DOT_TLD));
+    });
+
+    test("strips the suffix by length, not by a hardcoded 4", () => {
+        // `slice(0, -4)` would leave the label `alice.pa`, which hashes as the
+        // subname `pa` under `alice`.
+        const wrong = refNamehash("alice.pa", ".paseo", PASEO_NODE_FROM_CHAIN);
+        expect(namehash("alice.paseo", PASEO_TLD)).not.toBe(wrong);
+        expect(namehash("alice.paseo", PASEO_TLD)).toBe(namehash("alice", PASEO_TLD));
+    });
+});
+
+describe("dotNsTld", () => {
+    test("derives the .paseo node the contract computed at initialisation", () => {
+        // `DotnsProtocolRegistry.initialize` sets
+        // `_tldNode = namehashUnder(0, labelhash(tldLabel))`, so the node is a
+        // pure function of the suffix and we never need to read `tldNode()`.
+        expect(dotNsTld(".paseo").node).toBe(PASEO_NODE_FROM_CHAIN);
+    });
+
+    test("derives DOT_NODE for .dot, tying the helper to the constant", () => {
+        expect(dotNsTld(".dot").node).toBe(DOT_NODE);
+        expect(dotNsTld(".dot")).toEqual(DOT_TLD);
+    });
+
+    test("keeps the suffix verbatim, including its leading dot", () => {
+        expect(dotNsTld(".paseo").suffix).toBe(".paseo");
+    });
+
+    test("accepts a bare label as well as a dotted suffix", () => {
+        // `tld()` returns ".paseo" but the deploy pipeline and `initialize`
+        // both speak the bare label, so accept either spelling.
+        expect(dotNsTld("paseo")).toEqual(dotNsTld(".paseo"));
+    });
+});
+
+describe("isConsistentDotNsTld", () => {
+    test("accepts a pair whose node is the derivation of its suffix", () => {
+        expect(isConsistentDotNsTld(DOT_TLD)).toBe(true);
+        expect(isConsistentDotNsTld(PASEO_TLD)).toBe(true);
+    });
+
+    test("rejects a suffix paired with another TLD's node", () => {
+        // The override-path form of the original bug: `.paseo` names rooted at
+        // the `.dot` node resolve to nodes nobody owns.
+        expect(isConsistentDotNsTld({ suffix: ".paseo", node: DOT_NODE })).toBe(false);
+    });
+
+    test("rejects an empty suffix and a zero node", () => {
+        // What a pre-b4096968 proxy upgraded without a reinitializer reports:
+        // `_tld` is "" and `_tldNode` is 0x00…0, and both getters succeed.
+        expect(isConsistentDotNsTld({ suffix: "", node: DOT_NODE })).toBe(false);
+        expect(isConsistentDotNsTld({ suffix: ".", node: DOT_NODE })).toBe(false);
+        expect(
+            isConsistentDotNsTld({
+                suffix: ".paseo",
+                node: `0x${"00".repeat(32)}`,
+            }),
+        ).toBe(false);
+    });
+
+    test("rejects a multi-label suffix, which no deployment can have", () => {
+        // `initialize` requires `tldLabel.isSingleLabel()`.
+        expect(isConsistentDotNsTld({ suffix: ".a.b", node: dotNsTld(".a.b").node })).toBe(false);
+    });
+});

package/src/identity/dotns-namehash.ts

@@ -0,0 +1,149 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * DotNS namehash.
+ *
+ * ENS-style recursive hashing, but rooted at the network's TLD node rather than
+ * the empty root — matching `DotnsRegistry` (`contracts/registry/DotnsRegistry.sol`
+ * `_namehash`) and `LabelUtils.namehashUnder`.
+ *
+ *   labelhash(l) = keccak256(utf8(l))
+ *   node(parent, l) = keccak256(parent ‖ labelhash(l))
+ *   node("alice.paseo") = node(tldNode, "alice")
+ *   node("bob.alice.paseo") = node(node(tldNode, "alice"), "bob")
+ *
+ * The root is **per network**, not a constant. `DotnsProtocolRegistry.initialize`
+ * fixes it once from a deploy-time label — `.dot` on Paseo Asset Hub Previewnet,
+ * `.paseo` on Next V2 — and publishes it as `tld()` / `tldNode()`. Hashing under
+ * the wrong root yields a node the chain has never written to, so every lookup
+ * reports "unregistered" with no error anywhere. That is why {@link namehash}
+ * takes the root rather than assuming one; `resolveTld` in `./dotns-registry.js`
+ * is what asks the chain for it.
+ */
+import { bytesToHex, hexToBytes, keccak256 } from "@parity/product-sdk-crypto";
+
+/**
+ * A network's DotNS top-level domain: the suffix names are spelled with, and
+ * the node every one of its names hashes onto.
+ *
+ * The two must agree — `node` is `namehash(0, labelhash(label))` of `suffix`'s
+ * label — so build one with {@link dotNsTld} rather than by hand, and check an
+ * externally supplied pair with {@link isConsistentDotNsTld}. A `.paseo` suffix
+ * carrying the `.dot` node is exactly the defect this type exists to prevent.
+ */
+export interface DotNsTld {
+    /** Suffix including the leading dot, as `protocolRegistry.tld()` returns it. */
+    suffix: string;
+    /** Namehash of the TLD label, as `protocolRegistry.tldNode()` returns it. */
+    node: `0x${string}`;
+}
+
+/** The `.dot` TLD node. Mirrors the `DotnsConstants.DOT_NODE` the contracts removed in `b4096968`. */
+export const DOT_NODE = "0x3fce7d1364a893e213bc4212792b517ffc88f5b13b86c8ef9c8d390c3a1370ce";
+
+const ZERO_NODE = `0x${"00".repeat(32)}`;
+
+const utf8 = (s: string): Uint8Array => new TextEncoder().encode(s);
+
+/** `keccak256(parent ‖ labelhash(label))`, the one hash step every node is built from. */
+function nodeUnder(parent: Uint8Array, label: string): Uint8Array {
+    const combined = new Uint8Array(64);
+    combined.set(parent, 0);
+    combined.set(keccak256(utf8(label)), 32);
+    return keccak256(combined);
+}
+
+/**
+ * Build a {@link DotNsTld} from a TLD suffix, deriving the node the same way the
+ * contract does.
+ *
+ * Mirrors `DotnsProtocolRegistry.initialize`, which sets
+ * `_tldNode = namehashUnder(bytes32(0), labelhash(tldLabel))`. Because the node
+ * is a pure function of the label, a client only ever needs the suffix — reading
+ * `tldNode()` is a cross-check, never the source.
+ *
+ * Accepts `".paseo"` or `"paseo"`: `tld()` returns the dotted form while
+ * `initialize` and the deploy pipeline speak the bare label.
+ */
+export function dotNsTld(suffix: string): DotNsTld {
+    const label = suffix.startsWith(".") ? suffix.slice(1) : suffix;
+    return {
+        suffix: `.${label}`,
+        node: `0x${bytesToHex(nodeUnder(hexToBytes(ZERO_NODE.slice(2)), label))}`,
+    };
+}
+
+/**
+ * Whether a {@link DotNsTld} could have come from a real deployment.
+ *
+ * Three ways a pair fails, all of which produce silently wrong nodes rather
+ * than errors if they reach {@link namehash}:
+ *
+ *   - the node is not the derivation of the suffix (a caller mixing `.paseo`
+ *     with `DOT_NODE`);
+ *   - the suffix is empty, or the node is zero — what a pre-`b4096968` registry
+ *     proxy reports after an upgrade with no reinitializer, since `_tld` and
+ *     `_tldNode` are then still at their defaults and *both getters succeed*;
+ *   - the suffix is not a single label, which `initialize` rejects outright.
+ *
+ * Returns a boolean rather than a `Result` to keep this module free of the
+ * error type; callers with an error channel (`resolveTld`) map `false` to an
+ * `err` carrying the offending value.
+ */
+export function isConsistentDotNsTld(tld: DotNsTld): boolean {
+    const label = tld.suffix.startsWith(".") ? tld.suffix.slice(1) : tld.suffix;
+    if (label.length === 0 || label.includes(".")) return false;
+    if (tld.node.toLowerCase() === ZERO_NODE) return false;
+    return dotNsTld(label).node.toLowerCase() === tld.node.toLowerCase();
+}
+
+/** The `.dot` TLD, for a deployment that uses it. Not a default: pass it explicitly. */
+export const DOT_TLD: DotNsTld = { suffix: ".dot", node: DOT_NODE };
+
+/**
+ * Drop `suffix` from the end of `name`, leaving the labels beneath it.
+ *
+ * Strips by the suffix's own length, which is the whole point: the same logic
+ * written as `slice(0, -4)` turns `alice.paseo` into `alice.pa`, and every
+ * lookup for that name then asks about a subname nobody registered. A name that
+ * does not carry the suffix is returned unchanged, so a foreign suffix stays
+ * visible to whatever validates next.
+ *
+ * Lives here rather than in `./dotns.js` so the one copy is reachable from this
+ * module without pulling its heavier imports in.
+ */
+export function stripSuffix(name: string, suffix: string): string {
+    return name.endsWith(suffix) ? name.slice(0, -suffix.length) : name;
+}
+
+/**
+ * Compute the DotNS node hash for a name like `"alice.paseo"` or
+ * `"bob.alice.paseo"`, rooted at `tld`.
+ *
+ * The trailing suffix is the TLD (folded into `tld.node`); remaining labels are
+ * hashed most-significant-last, so `bob.alice.paseo` layers `bob` on top of
+ * `alice` on top of the TLD. Input is used as-is — normalize with
+ * `normalizeDotNsName` first if needed.
+ *
+ * `tld` is required rather than defaulted, because a default that is correct on
+ * one deployment is the defect this module was fixed for. It is also not
+ * validated here: a name whose suffix belongs to another deployment hashes to a
+ * node under `tld` instead of being refused, since this function returns a hash
+ * and has nowhere to report a complaint. The entry points in
+ * `./dotns-registry.js` do that check, where there is an error channel.
+ *
+ * @returns the 32-byte node as a `0x`-prefixed hex string.
+ */
+export function namehash(name: string, tld: DotNsTld): `0x${string}` {
+    const trimmed = stripSuffix(name, tld.suffix);
+    // "" → the bare TLD node; otherwise split into labels.
+    const labels = trimmed === "" ? [] : trimmed.split(".");
+    // Layer from the TLD outward: labels are given left-most-first
+    // (bob.alice), but must be applied right-to-left onto the parent.
+    // Annotated: hexToBytes yields ArrayBufferLike, keccak256 yields ArrayBuffer.
+    let node: Uint8Array = hexToBytes(tld.node.slice(2));
+    for (let i = labels.length - 1; i >= 0; i--) {
+        node = nodeUnder(node, labels[i]);
+    }
+    return `0x${bytesToHex(node)}`;
+}