@parity/product-sdk 0.0.0-dev.312.0

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

@@ -0,0 +1,43 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+//
+// Guards on the transcribed deployment table. These check the shape of the
+// table, not that it names the live deployment: only a diff against
+// `paritytech/dotns` `deployments/paseo-assethub/420420417.json` can do that,
+// and it is a network fetch. See the comment on DOTNS_ADDRESSES for the
+// commit the values were copied from, and re-check it when bumping.
+import { isValidH160 } from "@parity/product-sdk-address";
+import { describe, expect, test } from "vitest";
+import { DOTNS_ADDRESSES } from "./dotns-abis.js";
+
+describe("DOTNS_ADDRESSES", () => {
+    test("every entry is a well-formed H160", () => {
+        for (const [name, address] of Object.entries(DOTNS_ADDRESSES)) {
+            expect(isValidH160(address), `${name} = ${address}`).toBe(true);
+        }
+    });
+
+    test("no two entries share an address", () => {
+        // Six addresses transcribed by hand: a duplicated paste is the
+        // transcription error most likely to go unnoticed, because the wrong
+        // contract still answers and only the decode looks odd.
+        const entries = Object.entries(DOTNS_ADDRESSES);
+        const seen = new Map<string, string>();
+        for (const [name, address] of entries) {
+            const key = address.toLowerCase();
+            expect(seen.get(key), `${name} duplicates ${seen.get(key)}`).toBeUndefined();
+            seen.set(key, name);
+        }
+        expect(seen.size).toBe(entries.length);
+    });
+
+    test("the resolver and the reverse resolver are different contracts", () => {
+        // Load-bearing beyond general distinctness: resolveDotNs decides whether
+        // a node has a forward record by comparing the registry's resolver
+        // pointer against the reverse resolver, so collapsing these two would
+        // make every registered name look resolvable.
+        expect(DOTNS_ADDRESSES.resolver.toLowerCase()).not.toBe(
+            DOTNS_ADDRESSES.reverseResolver.toLowerCase(),
+        );
+    });
+});

package/src/identity/dotns-abis.ts

@@ -0,0 +1,274 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Minimal ABIs for the DotNS contracts: the read and write methods this module
+ * calls, and nothing else. Sourced from `paritytech/dotns` (`contracts/registry`,
+ * `contracts/resolvers`, `contracts/registrars`, `contracts/pop`).
+ */
+import type { AbiEntry } from "@parity/product-sdk-contracts";
+
+/**
+ * `DotnsRegistry` — node → resolver / owner, plus the owner-gated pointer write.
+ *
+ * `setResolver` is needed because registration parks `records[node].resolver` on
+ * the reverse resolver, so the pointer must be moved once before any address
+ * record is readable.
+ */
+export const DOTNS_REGISTRY_ABI: AbiEntry[] = [
+    {
+        type: "function",
+        name: "resolver",
+        inputs: [{ name: "node", type: "bytes32" }],
+        outputs: [{ name: "", type: "address" }],
+        stateMutability: "view",
+    },
+    {
+        type: "function",
+        name: "owner",
+        inputs: [{ name: "node", type: "bytes32" }],
+        outputs: [{ name: "", type: "address" }],
+        stateMutability: "view",
+    },
+    {
+        type: "function",
+        name: "setResolver",
+        inputs: [
+            { name: "node", type: "bytes32" },
+            { name: "resolverAddr", type: "address" },
+        ],
+        outputs: [],
+        stateMutability: "nonpayable",
+    },
+];
+
+/** `DotnsResolver` — node → resolved address. */
+export const DOTNS_RESOLVER_ABI: AbiEntry[] = [
+    {
+        type: "function",
+        name: "addressOf",
+        inputs: [{ name: "node", type: "bytes32" }],
+        outputs: [{ name: "value", type: "address" }],
+        stateMutability: "view",
+    },
+];
+
+/** `DotnsReverseResolver` — account → primary name. */
+export const DOTNS_REVERSE_RESOLVER_ABI: AbiEntry[] = [
+    {
+        type: "function",
+        name: "nameOf",
+        inputs: [{ name: "addr", type: "address" }],
+        outputs: [{ name: "name", type: "string" }],
+        stateMutability: "view",
+    },
+];
+
+/** `DotnsResolver` write — set a node's resolved address (owner-gated). */
+export const DOTNS_RESOLVER_WRITE_ABI: AbiEntry[] = [
+    {
+        type: "function",
+        name: "setAddress",
+        inputs: [
+            { name: "node", type: "bytes32" },
+            { name: "value", type: "address" },
+        ],
+        outputs: [],
+        stateMutability: "nonpayable",
+    },
+];
+
+/**
+ * `DotnsRegistrarController` — the commit-reveal registration flow. `register`
+ * is payable; the value is the price from {@link DOTNS_POP_RULES_ABI}.
+ * `Registration` = (label, owner, secret, reserved).
+ */
+export const DOTNS_REGISTRAR_CONTROLLER_ABI: AbiEntry[] = [
+    {
+        type: "function",
+        name: "available",
+        inputs: [{ name: "label", type: "string" }],
+        outputs: [{ name: "isAvailable", type: "bool" }],
+        stateMutability: "view",
+    },
+    {
+        type: "function",
+        name: "minCommitmentAge",
+        inputs: [],
+        outputs: [{ name: "", type: "uint256" }],
+        stateMutability: "view",
+    },
+    {
+        type: "function",
+        name: "maxCommitmentAge",
+        inputs: [],
+        outputs: [{ name: "", type: "uint256" }],
+        stateMutability: "view",
+    },
+    {
+        type: "function",
+        name: "makeCommitment",
+        inputs: [
+            {
+                name: "registration",
+                type: "tuple",
+                components: [
+                    { name: "label", type: "string" },
+                    { name: "owner", type: "address" },
+                    { name: "secret", type: "bytes32" },
+                    { name: "reserved", type: "bool" },
+                ],
+            },
+        ],
+        outputs: [{ name: "commitment", type: "bytes32" }],
+        stateMutability: "pure",
+    },
+    {
+        type: "function",
+        name: "commit",
+        inputs: [{ name: "commitment", type: "bytes32" }],
+        outputs: [],
+        stateMutability: "nonpayable",
+    },
+    {
+        type: "function",
+        name: "register",
+        inputs: [
+            {
+                name: "registration",
+                type: "tuple",
+                components: [
+                    { name: "label", type: "string" },
+                    { name: "owner", type: "address" },
+                    { name: "secret", type: "bytes32" },
+                    { name: "reserved", type: "bool" },
+                ],
+            },
+        ],
+        outputs: [],
+        stateMutability: "payable",
+    },
+];
+
+/**
+ * `PopRules` — registration pricing.
+ *
+ * `price` is the label-only cost and runs no eligibility rules, so it is not
+ * what `register` charges. `register` uses the owner-aware variants and adds
+ * `transferFloor` when the payer is not the owner:
+ * `max(priceWithoutCheck(label, owner).price, transferFloor(label, payer, owner))`.
+ *
+ * `PopStatus` encodes as `uint8`: 0 NoStatus, 1 PopLite, 2 PopFull, 3 Reserved.
+ */
+export const DOTNS_POP_RULES_ABI: AbiEntry[] = [
+    {
+        type: "function",
+        name: "price",
+        inputs: [{ name: "name", type: "string" }],
+        outputs: [{ name: "cost", type: "uint256" }],
+        stateMutability: "view",
+    },
+    {
+        type: "function",
+        name: "priceWithoutCheck",
+        inputs: [
+            { name: "name", type: "string" },
+            { name: "userAddress", type: "address" },
+        ],
+        outputs: [
+            {
+                name: "metadata",
+                type: "tuple",
+                components: [
+                    { name: "price", type: "uint256" },
+                    { name: "status", type: "uint8" },
+                    { name: "userStatus", type: "uint8" },
+                    { name: "message", type: "string" },
+                ],
+            },
+        ],
+        stateMutability: "view",
+    },
+    {
+        type: "function",
+        name: "classifyName",
+        inputs: [{ name: "name", type: "string" }],
+        outputs: [
+            { name: "requirement", type: "uint8" },
+            { name: "message", type: "string" },
+        ],
+        stateMutability: "pure",
+    },
+    {
+        type: "function",
+        name: "transferFloor",
+        inputs: [
+            { name: "name", type: "string" },
+            { name: "from", type: "address" },
+            { name: "to", type: "address" },
+        ],
+        outputs: [{ name: "floor", type: "uint256" }],
+        stateMutability: "view",
+    },
+];
+
+/**
+ * `IDotnsProtocolRegistry`, the two TLD getters.
+ *
+ * The TLD is per network: `initialize(tldLabel)` fixes it once at deployment
+ * and there is no setter, so these are immutable for the life of a deployment.
+ * `tld()` returns the suffix with its leading dot (`".paseo"`); `tldNode()`
+ * returns `namehash(0, labelhash(label))`, which is derivable from the suffix
+ * and so is read only as a cross-check.
+ *
+ * Deployments predating `dotns` `b4096968` have neither getter — the TLD was a
+ * compile-time constant there — and revert with an empty payload.
+ */
+export const DOTNS_PROTOCOL_REGISTRY_ABI: AbiEntry[] = [
+    {
+        type: "function",
+        name: "tld",
+        inputs: [],
+        outputs: [{ name: "suffix", type: "string" }],
+        stateMutability: "view",
+    },
+    {
+        type: "function",
+        name: "tldNode",
+        inputs: [],
+        outputs: [{ name: "node", type: "bytes32" }],
+        stateMutability: "view",
+    },
+];
+
+/** `IPopRules.PopStatus`. Ordering is meaningful: a user meets a tier when `userStatus >= status`. */
+export const POP_STATUS = { NoStatus: 0, PopLite: 1, PopFull: 2, Reserved: 3 } as const;
+
+/**
+ * The deployed DotNS addresses. The same on every network.
+ *
+ * Not a per-network table, despite what the old name (`PASEO_ASSETHUB_DOTNS`)
+ * implied: every DotNS network is deployed through the same CREATE3 factory, so
+ * the addresses are identical everywhere and **only the TLD differs**. Verified
+ * on both Paseo Asset Hub Next V2 and Previewnet — `protocolRegistry.get(...)`
+ * returns the same registry on each, and all six addresses hold contracts on
+ * both. `paritytech/dotns` `DEPLOYMENTS.md` states the mechanism, and
+ * `preview-net-v1` confirms it from the deploy side: the TLD is passed only as
+ * registry init calldata, so it moves no address.
+ *
+ * So extending this module to another network means resolving its TLD, which
+ * `resolveTld` already does — not adding a second address table.
+ *
+ * Each address answers `DotnsProtocolRegistry.get(bytes32)` under its
+ * `DotnsConstants` key (the name below, right-padded to 32 bytes) and has a
+ * `Revive.AccountInfoOf` entry. They are pinned rather than resolved at runtime,
+ * so re-verify after a redeploy; `protocolRegistry` is the address to walk from
+ * if we ever resolve the rest dynamically.
+ */
+export const DOTNS_ADDRESSES = {
+    registry: "0xf34054fd76BbF85f216cf9908226D5f0A72E50CA",
+    reverseResolver: "0xee3883d7eB60Ee9BCD7F3bcD8f2f05302A9Cc035",
+    resolver: "0xbd1165E549DF96F083c0A16f61590927bC187009",
+    registrarController: "0xBdaA01bD1bA67d709F2b1fF286Da0d854977EA30",
+    popRules: "0x747B456bE03aec0b42bd85C51513730FBD45DA31",
+    protocolRegistry: "0xD19e3D0C97CF501125a04A97405e3e6592fa846E",
+} as const;

package/src/identity/dotns-errors.ts

@@ -0,0 +1,34 @@
+// 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
+    | "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)}`;
+}