@parity/product-sdk 0.0.0-dev.312.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

@@ -0,0 +1,221 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * DotNS (Polkadot Name Service) utilities
+ *
+ * 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 { stripSuffix } from "./dotns-namehash.js";
+import type {
+    ChainDefinition,
+    PalletsTypedef,
+    PlainDescriptor,
+    RuntimeDescriptor,
+    SS58String,
+    StorageDescriptor,
+    TxDescriptor,
+} from "polkadot-api";
+
+type AnyDescriptorEntry<T> = Record<string, Record<string, T>>;
+
+type PeopleUsernameStorage = {
+    Resources: {
+        UsernameOwnerOf: StorageDescriptor<[Uint8Array], SS58String, true, never>;
+    };
+};
+
+type PeopleUsernamePallets = PalletsTypedef<
+    PeopleUsernameStorage,
+    AnyDescriptorEntry<TxDescriptor<any>>,
+    AnyDescriptorEntry<PlainDescriptor<any>>,
+    AnyDescriptorEntry<PlainDescriptor<any>>,
+    AnyDescriptorEntry<PlainDescriptor<any>>,
+    AnyDescriptorEntry<RuntimeDescriptor<any, any>>
+>;
+
+/**
+ * Descriptor narrowed to "any chain that exposes `Resources.UsernameOwnerOf`".
+ *
+ * Used as the input to `signMessageWithDotNsIdentity` so the SDK doesn't pin
+ * a specific People-chain genesis — anything with the right storage shape
+ * (paseo-individuality today, future People Lite, etc.) is accepted.
+ */
+export type PeopleUsernameChain = ChainDefinition & {
+    descriptors: Promise<unknown> & {
+        pallets: PeopleUsernamePallets;
+    };
+};
+
+/**
+ * Minimal typed-api shape required to resolve a username on a People chain.
+ *
+ * This is a narrow structural type — anything with the right
+ * `query.Resources.UsernameOwnerOf.getValue` shape works, including a real
+ * `TypedApi<PeopleUsernameChain>` slice of a `ChainClient` or a hand-rolled
+ * test double.
+ */
+export type PeopleUsernameQueryApi = {
+    query: {
+        Resources: {
+            UsernameOwnerOf: {
+                getValue: (key: Uint8Array) => Promise<SS58String | undefined>;
+            };
+        };
+    };
+};
+
+/**
+ * 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, already normalized by {@link normalizeDotNsName}
+ * @param suffix - The deployment's TLD suffix, e.g. `".paseo"`
+ */
+export function isValidDotNsName(name: string, suffix: string): boolean {
+    if (!name.endsWith(suffix)) return false;
+    return isValidLabel(stripSuffix(name, suffix));
+}
+
+/**
+ * One canonical DNS label, matching the on-chain rule.
+ *
+ * `StringUtils.isSingleLabel` allows lowercase ASCII, digits and non-edge
+ * hyphens up to 63 characters, and the registrar additionally requires 3.
+ */
+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);
+}
+
+/**
+ * Whether a name can be resolved: one or more valid labels under `suffix`.
+ *
+ * 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 - Name to check, already normalized by {@link normalizeDotNsName}
+ * @param suffix - The deployment's TLD suffix, e.g. `".paseo"`
+ */
+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);
+}
+
+/**
+ * Normalize a DotNS name for the deployment identified by `suffix`.
+ *
+ * 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.
+ *
+ * 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.
+ *
+ * **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.
+ *
+ * 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 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 account.
+ *
+ * Queries `Resources.UsernameOwnerOf` on the caller-supplied typed-api fragment.
+ * 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).
+ *
+ * @internal Exposed for unit testing. Consumers should use
+ *   `wallet.signMessageWithDotNsIdentity` instead, which orchestrates the
+ *   chain-connection lifecycle.
+ */
+export async function resolvePeopleUsernameOwner(
+    username: string,
+    peopleApi: PeopleUsernameQueryApi,
+): Promise<SS58String | null> {
+    const owner = await peopleApi.query.Resources.UsernameOwnerOf.getValue(
+        new TextEncoder().encode(username),
+    );
+    return owner ?? null;
+}
+
+function assertHex(value: string): `0x${string}` {
+    if (!/^0x[0-9a-fA-F]*$/.test(value)) {
+        throw new Error(`Expected 0x-prefixed hex string, got ${value}`);
+    }
+    return value as `0x${string}`;
+}
+
+export function accountIdHexToBytes(accountId: `0x${string}`): Uint8Array {
+    const bytes = hexToBytes(assertHex(accountId).slice(2));
+    if (bytes.length !== 32) {
+        throw new Error(`Expected 32-byte AccountId, got ${bytes.length} bytes`);
+    }
+    return bytes;
+}
+
+/** 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.ts

@@ -0,0 +1,61 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * @parity/product-sdk/identity
+ *
+ * Identity utilities: DotNS name resolution, plus the deprecated context-alias
+ * helpers.
+ *
+ * For real Ring VRF aliases and proofs, use `SignerManager`'s
+ * `getProductAccountAlias` and `createRingVRFProof` from
+ * `@parity/product-sdk-signer`.
+ */
+
+// DotNS utilities (pure helpers + People-chain username path)
+export {
+    isValidDotNsName,
+    isResolvableDotNsName,
+    normalizeDotNsName,
+    accountIdHexToBytes,
+    accountIdToHex,
+    resolvePeopleUsernameOwner,
+} from "./dotns.js";
+export type { PeopleUsernameChain, PeopleUsernameQueryApi } from "./dotns.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";
+
+// Context alias utilities (deprecated)
+export { deriveContextAlias, verifyContextAlias } from "./product-account.js";
+
+// Types
+export type {
+    DotNsRecord,
+    ContextAliasInfo,
+    VerificationResult,
+    OnChainIdentity,
+} from "./types.js";

package/src/identity/product-account.test.ts

@@ -0,0 +1,130 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Frozen vectors for the deprecated context-alias helpers.
+ *
+ * These pin current behaviour so the deprecation cannot silently alter the
+ * derivation. Never re-derive: a caller may use the value as a plain
+ * identifier, where different output bytes would be a silent break.
+ */
+import { ss58Decode, ss58Encode } from "@parity/product-sdk-address";
+import { blake2b256 } from "@parity/product-sdk-crypto";
+import { describe, expect, it } from "vitest";
+import * as identity from "./index.js";
+import { deriveContextAlias, verifyContextAlias } from "./product-account.js";
+
+const ALICE = "5GrwvaEF5zXb26Fz9rcQpDWS57CtERHpNehXCPcNoHGKutQY";
+const CONTEXT = "voting-round-1";
+
+/** Recomputes the documented formula from primitives, independent of the implementation. */
+function expectedAliasPublicKey(parentAddress: string, context: string): Uint8Array {
+    const { publicKey } = ss58Decode(parentAddress);
+    const contextBytes = new TextEncoder().encode(context);
+    const combined = new Uint8Array(publicKey.length + contextBytes.length);
+    combined.set(publicKey, 0);
+    combined.set(contextBytes, publicKey.length);
+    return blake2b256(combined);
+}
+
+describe("deriveContextAlias", () => {
+    it("returns blake2b256(parentPublicKey || context), encoded at the given prefix", () => {
+        const alias = deriveContextAlias(ALICE, CONTEXT);
+        const expected = expectedAliasPublicKey(ALICE, CONTEXT);
+
+        expect(alias.address).toBe(ss58Encode(expected, 42));
+    });
+
+    it("matches a frozen vector for a known parent and context", () => {
+        const alias = deriveContextAlias(ALICE, CONTEXT);
+
+        expect(alias.address).toBe("5GPTdhxkG9wNKhCSN1vZrCwrf3fwvAf4j487vqrkVzvRMH6F");
+        expect(alias.h160Address).toBe("0x93d10a91de267ba79b27fbec373e5a3b2e86a283");
+        expect(alias.parentAddress).toBe(ALICE);
+        expect(alias.context).toBe(CONTEXT);
+    });
+
+    it("defaults to ss58 prefix 42", () => {
+        expect(deriveContextAlias(ALICE, CONTEXT).address).toBe(
+            deriveContextAlias(ALICE, CONTEXT, 42).address,
+        );
+    });
+
+    it("changes only the encoding when the ss58 prefix changes, not the key", () => {
+        const at42 = deriveContextAlias(ALICE, CONTEXT, 42);
+        const at0 = deriveContextAlias(ALICE, CONTEXT, 0);
+
+        expect(at0.address).not.toBe(at42.address);
+        expect(Array.from(ss58Decode(at0.address).publicKey)).toEqual(
+            Array.from(ss58Decode(at42.address).publicKey),
+        );
+    });
+
+    it("derives a different alias for a different context", () => {
+        expect(deriveContextAlias(ALICE, "round-1").address).not.toBe(
+            deriveContextAlias(ALICE, "round-2").address,
+        );
+    });
+});
+
+describe("verifyContextAlias", () => {
+    it("accepts an alias derived from the same parent and context", () => {
+        const alias = deriveContextAlias(ALICE, CONTEXT);
+
+        expect(verifyContextAlias(alias.address, ALICE, CONTEXT)).toBe(true);
+    });
+
+    it("rejects a different context", () => {
+        const alias = deriveContextAlias(ALICE, CONTEXT);
+
+        expect(verifyContextAlias(alias.address, ALICE, "voting-round-2")).toBe(false);
+    });
+
+    it("rejects a different parent", () => {
+        const alias = deriveContextAlias(ALICE, CONTEXT);
+        const bob = "5FHneW46xGXgs5mUiveU4sbTyGBzmstUspZC92UhjJM694ty";
+
+        expect(verifyContextAlias(alias.address, bob, CONTEXT)).toBe(false);
+    });
+
+    it("returns false rather than throwing on an undecodable address", () => {
+        expect(verifyContextAlias("not-an-address", ALICE, CONTEXT)).toBe(false);
+    });
+
+    // Guards the byte-level comparison: `addressesEqual` from
+    // @parity/product-sdk-address compares SS58 strings exactly and would
+    // return false here, silently narrowing behaviour.
+    it("compares public keys, so it accepts an alias encoded at another prefix", () => {
+        const alias = deriveContextAlias(ALICE, CONTEXT, 42);
+        const reencoded = ss58Encode(ss58Decode(alias.address).publicKey, 0);
+
+        expect(reencoded).not.toBe(alias.address);
+        expect(verifyContextAlias(reencoded, ALICE, CONTEXT)).toBe(true);
+    });
+});
+
+describe("the identity export surface", () => {
+    // These threw on every call, so no working consumer could exist. Deleting
+    // turns a guaranteed runtime throw into a compile error.
+    it("no longer exports the unimplemented ring helpers", () => {
+        for (const name of ["deriveAnonymousAlias", "createRingProof", "verifyRingProof"]) {
+            expect(name in identity).toBe(false);
+        }
+    });
+
+    it("still exports the DotNS helpers and the deprecated context-alias pair", () => {
+        for (const name of [
+            "resolveDotNs",
+            "reverseDotNs",
+            "isDotNsAvailable",
+            "resolvePeopleUsernameOwner",
+            "isValidDotNsName",
+            "normalizeDotNsName",
+            "accountIdHexToBytes",
+            "accountIdToHex",
+            "deriveContextAlias",
+            "verifyContextAlias",
+        ]) {
+            expect(name in identity).toBe(true);
+        }
+    });
+});

package/src/identity/product-account.ts

@@ -0,0 +1,115 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Context alias derivation (deprecated, removal in 0.23.0)
+ *
+ * Derives a deterministic, context-bound alias from a parent account using blake2b-256.
+ *
+ * The output is a hash, not a key, so no signing key exists for the addresses
+ * returned here. See the notes on each function for what to use instead.
+ *
+ * NOTE: this is NOT the canonical sr25519 product-account derivation used by
+ * mobile, desktop, and dotli hosts. For that, use
+ * `@parity/product-sdk-keys::deriveProductAccountPublicKey`.
+ */
+
+import { createLogger } from "@parity/product-sdk-logger";
+import { blake2b256 } from "@parity/product-sdk-crypto";
+import { ss58Encode, ss58Decode, deriveH160 } from "@parity/product-sdk-address";
+import type { ContextAliasInfo } from "./types.js";
+
+const log = createLogger("identity");
+
+/**
+ * Derive a context-bound alias from a parent account.
+ *
+ * The alias is deterministically derived using:
+ * aliasPublicKey = blake2b256(parentPublicKey || context)
+ *
+ * @deprecated Returns addresses that no key can spend. The alias public key is a
+ *   blake2b-256 hash rather than a derived key, so no secret corresponds to the
+ *   SS58 address or to the H160: both can receive value and neither can ever
+ *   send it. Removal: `@parity/product-sdk` 0.23.0. Replace by intent:
+ *
+ *   - An account that holds or spends value:
+ *     `SignerManager.getProductAccount(dotNsIdentifier, index)` from
+ *     `@parity/product-sdk-signer`. Host-backed and actually signable.
+ *   - The address offline, with no host: `deriveProductAccountPublicKey` from
+ *     `@parity/product-sdk-keys`, the canonical sr25519 soft derivation.
+ *   - An unlinkable per-context alias: select a registered ring-VRF key, then call
+ *     `SignerManager.getProductAccountAlias(keyHandle, context, location)` or
+ *     `createRingVRFProof(keyHandle, context, location, message)`.
+ *   - A context-scoped identifier, never used as an account: `blake2b256` from
+ *     `@parity/product-sdk/crypto`. Same bytes, without address packaging that
+ *     invites the mistake.
+ *
+ * @param parentAddress - Parent account SS58 address
+ * @param context - Context string for derivation (e.g. an app id or scope label)
+ * @param ss58Prefix - SS58 prefix (default: 42)
+ * @returns Context alias info
+ */
+export function deriveContextAlias(
+    parentAddress: string,
+    context: string,
+    ss58Prefix = 42,
+): ContextAliasInfo {
+    const { publicKey: parentPublicKey } = ss58Decode(parentAddress);
+
+    // Derive alias public key: blake2b-256(parentPublicKey || context)
+    const contextBytes = new TextEncoder().encode(context);
+    const combined = new Uint8Array(parentPublicKey.length + contextBytes.length);
+    combined.set(parentPublicKey, 0);
+    combined.set(contextBytes, parentPublicKey.length);
+
+    const aliasPublicKey = blake2b256(combined);
+    const address = ss58Encode(aliasPublicKey, ss58Prefix);
+    const h160Address = deriveH160(aliasPublicKey);
+
+    log.debug("Derived context alias", {
+        parentAddress,
+        context,
+        address,
+    });
+
+    return {
+        address,
+        h160Address,
+        parentAddress,
+        context,
+    };
+}
+
+/**
+ * Verify that a context alias was derived from a parent account.
+ *
+ * @deprecated Recomputes {@link deriveContextAlias} from two public values and
+ *   compares the result, so it confirms a derivation relationship and nothing
+ *   more. No secret enters the operation at any point, which means there is
+ *   nothing here to authenticate: a passing result does not show that anyone
+ *   controls either account. Removal: `@parity/product-sdk` 0.23.0.
+ *
+ * @param aliasAddress - Context alias SS58 address
+ * @param parentAddress - Claimed parent address
+ * @param context - Context string used for derivation
+ * @returns True if derivation is valid
+ */
+export function verifyContextAlias(
+    aliasAddress: string,
+    parentAddress: string,
+    context: string,
+): boolean {
+    try {
+        const derived = deriveContextAlias(parentAddress, context);
+        const { publicKey: aliasKey } = ss58Decode(aliasAddress);
+        const { publicKey: derivedKey } = ss58Decode(derived.address);
+
+        // Compare public keys
+        if (aliasKey.length !== derivedKey.length) return false;
+        for (let i = 0; i < aliasKey.length; i++) {
+            if (aliasKey[i] !== derivedKey[i]) return false;
+        }
+        return true;
+    } catch {
+        return false;
+    }
+}