@parity/product-sdk 0.0.0-dev.312.0

package/dist/identity/index.d.ts

@@ -0,0 +1,491 @@
+export { P as PeopleUsernameChain, a as PeopleUsernameQueryApi, b as accountIdHexToBytes, c as accountIdToHex, i as isResolvableDotNsName, d as isValidDotNsName, n as normalizeDotNsName, r as resolvePeopleUsernameOwner } from '../dotns-bswWAmR2.js';
+import { Result } from '@parity/result';
+import { ContractRuntime, BatchableCall } from '@parity/product-sdk-contracts';
+import { SS58String } from 'polkadot-api';
+import { 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.
+ */
+type DotNsErrorReason = "InvalidName" | "InvalidTld" | "TldMismatch" | "MissingOrigin" | "InvalidOrigin" | "NameUnavailable" | "NameReserved" | "OwnerStatusInsufficient" | "RegistryCall" | "Decode";
+declare class DotNsError extends Error implements SdkError {
+    readonly isSdkError: true;
+    readonly source = "dotns";
+    readonly reason: DotNsErrorReason;
+    constructor(reason: DotNsErrorReason, message: string, options?: ErrorOptions);
+}
+
+/**
+ * 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.
+ */
+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`. */
+declare const DOT_NODE = "0x3fce7d1364a893e213bc4212792b517ffc88f5b13b86c8ef9c8d390c3a1370ce";
+/**
+ * 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.
+ */
+declare function dotNsTld(suffix: string): DotNsTld;
+/**
+ * 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.
+ */
+declare function isConsistentDotNsTld(tld: DotNsTld): boolean;
+/** The `.dot` TLD, for a deployment that uses it. Not a default: pass it explicitly. */
+declare const DOT_TLD: DotNsTld;
+/**
+ * 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.
+ */
+declare function stripSuffix(name: string, suffix: string): string;
+/**
+ * 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.
+ */
+declare function namehash(name: string, tld: DotNsTld): `0x${string}`;
+
+/**
+ * Identity module types
+ *
+ * Types for DotNS name resolution and context-alias derivation
+ */
+/** DotNS name resolution result */
+interface DotNsRecord {
+    /**
+     * 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;
+    /** 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.
+ */
+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 */
+interface VerificationResult {
+    /** Whether identity is verified */
+    verified: boolean;
+    /** Verification method used */
+    method: "on-chain" | "judgement" | "social";
+    /** Verification details */
+    details?: Record<string, unknown>;
+}
+/** On-chain identity info */
+interface OnChainIdentity {
+    /** Display name */
+    display?: string;
+    /** Legal name */
+    legal?: string;
+    /** Web URL */
+    web?: string;
+    /** Email */
+    email?: string;
+    /** Twitter handle */
+    twitter?: string;
+    /** Riot/Matrix handle */
+    riot?: string;
+    /** Additional fields */
+    additional: Array<[string, string]>;
+}
+
+/**
+ * DotNS registry reads and writes.
+ *
+ * DotNS is an ENS-style system on Asset Hub: a `DotnsRegistry` maps a node
+ * (namehash) to a resolver + owner, a `DotnsResolver` maps a node to an
+ * address, and a `DotnsReverseResolver` maps an account back to its name. All
+ * are Revive contracts, reached via `@parity/product-sdk-contracts`'
+ * `createContract(...).<method>.query(...)`. Contract source:
+ * https://github.com/paritytech/dotns
+ *
+ * **Names are rooted at the network's TLD, which is per deployment.** It is
+ * fixed when `DotnsProtocolRegistry.initialize` runs, has no setter, and is
+ * published as `tld()`. `.paseo` on Paseo Asset Hub Next V2, `.dot` on
+ * Previewnet, and operators can choose others. Every entry point that hashes a
+ * name therefore asks the chain first, through {@link resolveTld}, and callers
+ * can supply `opts.tld` to skip the read. Hashing under the wrong root returns a
+ * node the chain never wrote to, so the failure looks exactly like an
+ * unregistered name — which is why nothing here assumes a root.
+ *
+ * **A node's resolver pointer is not necessarily a forward resolver.** The
+ * deployment has several — forward, reverse, content, PoP — and only the forward
+ * one answers `addressOf`. `resolveDotNs` therefore calls it only when the
+ * pointer *is* the forward resolver, and reports every other pointer as
+ * "registered, no forward record". The content resolver is the common case for a
+ * product name.
+ *
+ * A rule this module holds to throughout: **a failed read must never become a
+ * plausible value.** The one deliberate exception is documented on
+ * {@link resolveTld}, where a missing getter identifies a deployment whose TLD
+ * could only have been `.dot`.
+ *
+ * Reads (`resolveDotNs` / `reverseDotNs` / `isDotNsAvailable`) query chain.
+ * Writes return prepared calls the caller submits with their own signer:
+ * `setDotNsRecord` (the resolver pointer, when it needs moving, plus the
+ * record) and `prepareDotNsRegistration` (the commit call plus a thunk for the
+ * register call, which cannot be built until the commitment is on chain).
+ *
+ * Note: this deployment has no name-expiry concept (the registrar exposes no
+ * expiry getter), so `DotNsRecord.expiresAt` is always omitted.
+ */
+
+type HexString = `0x${string}`;
+/** Shared inputs for a DotNS registry call. */
+interface DotNsClientOptions {
+    /** A contract runtime for the chain hosting DotNS (Asset Hub). */
+    runtime: ContractRuntime;
+    /**
+     * SS58 account that will submit the prepared calls.
+     *
+     * Required by the write helpers, which dry-run against it: `setAddress` and
+     * `setResolver` are owner-gated, so a dry-run from anyone else reverts.
+     * Optional for reads, which fall back to the pallet-revive query account.
+     *
+     * Must be SS58, not the account's H160. pallet-revive derives `msg.sender`
+     * from it; convert with `h160ToSs58` from `@parity/product-sdk-address`.
+     */
+    origin?: SS58String;
+    /** `DotnsRegistry` address. Defaults to the deployed set, which is the same on every network. */
+    registryAddress?: HexString;
+    /** `DotnsReverseResolver` address. Defaults to the deployed set. */
+    reverseResolverAddress?: HexString;
+    /** `DotnsResolver` address (writes: setDotNsRecord). Defaults to Paseo AH. */
+    resolverAddress?: HexString;
+    /** `DotnsRegistrarController` address (registration). Defaults to Paseo AH. */
+    registrarControllerAddress?: HexString;
+    /** `PopRules` address (registration price). Defaults to Paseo AH. */
+    popRulesAddress?: HexString;
+    /**
+     * `DotnsProtocolRegistry` address, the contract holding this network's TLD.
+     * Defaults to Paseo AH — and the address is the same on every network, since
+     * the whole set is CREATE3-deterministic.
+     */
+    protocolRegistryAddress?: HexString;
+    /**
+     * The deployment's TLD, when you already know it.
+     *
+     * Omit it and the client reads `protocolRegistry.tld()` once per runtime and
+     * caches it, which is the correct default: the TLD is per network and only
+     * the chain knows which one is in play. Supply it to skip the read for
+     * offline or test use, or to pin a deployment deliberately. Build it with
+     * `dotNsTld(".paseo")` rather than by hand — a suffix paired with the wrong
+     * node is rejected, because that pairing is the defect this option could
+     * otherwise reintroduce.
+     */
+    tld?: DotNsTld;
+}
+/** Arguments for {@link prepareDotNsRegistration}. */
+interface RegisterDotNsArgs {
+    /** The name to register, e.g. `"alice.paseo"` — or the bare label `"alice"`. */
+    name: string;
+    /**
+     * The account that will own the registered name: an H160, `0x` and 20
+     * bytes. Not SS58 — DotNS is a set of Revive contracts, and the registrar
+     * takes the owner as an ABI `address`. Convert with `ss58ToH160` from
+     * `@parity/product-sdk-address` if you hold a Substrate-shaped address.
+     *
+     * Typed `string` rather than `` `0x${string}` `` so callers need no cast,
+     * which means the compiler will not catch an SS58 address here: it reaches
+     * the contract and reverts on chain.
+     */
+    owner: string;
+    /** Reserved-name registration (default `false`). */
+    reserved?: boolean;
+}
+/** Arguments for {@link setDotNsRecord}. */
+interface SetRecordArgs {
+    /** The name whose resolver record is being set. */
+    name: string;
+    /**
+     * The address the name should resolve to: an H160, `0x` and 20 bytes. It is
+     * written straight into `resolver.setAddress` as an ABI `address`, so SS58
+     * is not accepted — convert with `ss58ToH160` from
+     * `@parity/product-sdk-address` first. Unenforced by the type, as with
+     * {@link RegisterDotNsArgs.owner}.
+     */
+    address: string;
+}
+/**
+ * Resolve a DotNS name. `expiresAt` is omitted (no on-chain expiry here).
+ *
+ * Three outcomes, because the registry's resolver pointer is configuration, not
+ * proof of existence:
+ *
+ *   - `ok(null)` — unregistered (`registry.owner` is zero).
+ *   - `ok({ name, owner })` — registered, no forward record yet.
+ *   - `ok({ name, owner, address })` — resolves.
+ */
+declare function resolveDotNs(name: string, opts: DotNsClientOptions): Promise<Result<DotNsRecord | null, DotNsError>>;
+/**
+ * Reverse-resolve an account to its primary DotNS name.
+ *
+ * Single call: `reverseResolver.nameOf(account)`. `ok(null)` when no primary
+ * name is set (empty string on-chain).
+ */
+declare function reverseDotNs(address: string, opts: DotNsClientOptions): Promise<Result<string | null, DotNsError>>;
+/**
+ * Whether a DotNS name is available to claim.
+ *
+ * Two reads, because "not minted" and "claimable" are different questions:
+ *
+ *   - `registrarController.available(label)`, the predicate `register` enforces
+ *     through `_requireAvailableLabel`. Deliberately not inferred from
+ *     resolution: a registered name has no forward record until its owner sets
+ *     one, so that would report owned names as free.
+ *   - `PopRules.classifyName(label)`, which is pure and owner-independent.
+ *     Labels of 5 base characters or fewer are reserved for governance and can
+ *     never be claimed, though the registrar still reports them as unminted.
+ *
+ * `ok(true)` means the name can be registered by someone. It does not mean the
+ * caller can register it: labels of 6 to 8 characters additionally require a
+ * personhood tier, which depends on the owner and is checked by
+ * {@link prepareDotNsRegistration}.
+ *
+ * Validated first because both reads revert on labels we already reject.
+ */
+declare function isDotNsAvailable(name: string, opts: DotNsClientOptions): Promise<Result<boolean, DotNsError>>;
+/**
+ * Prepare the calls binding a name to an address. Submit them in order with the
+ * owner's signer via `batchSubmitAndWatch`; both are owner-gated.
+ *
+ * Returns two calls when the node still points at the reverse resolver (the
+ * post-registration default): `registry.setResolver` first, or the record
+ * written by `setAddress` is real but unreadable. One call once it is pointed.
+ */
+declare function setDotNsRecord(args: SetRecordArgs, opts: DotNsClientOptions): Promise<Result<BatchableCall[], DotNsError>>;
+/** The prepared pieces of a DotNS registration. */
+interface DotNsRegistration {
+    /** The random secret bound into both commit and register. */
+    secret: HexString;
+    /** The commitment hash (also encoded inside `commitCall`). */
+    commitment: HexString;
+    /** Submit first, with the owner's signer. */
+    commitCall: BatchableCall;
+    /** Seconds to wait after `commit` before `register` is accepted. */
+    minCommitmentAge: bigint;
+    /** Seconds after which the commitment expires and `register` is rejected. */
+    maxCommitmentAge: bigint;
+    /** Quote at prepare time, for display. The submitted value is re-read below. */
+    price: bigint;
+    /**
+     * Build the register call, once `minCommitmentAge` has elapsed.
+     *
+     * Deferred rather than returned up front: `register` consumes the
+     * commitment, so dry-running it before `commitCall` lands reverts with
+     * `CommitmentNotFound` and no call could be built at all. Deferring also
+     * prices and sizes it against the state it will actually execute in.
+     */
+    prepareRegisterCall: () => Promise<Result<BatchableCall, DotNsError>>;
+}
+/**
+ * Prepare a DotNS registration: the commit call, the shared secret, the timing
+ * window, and a thunk that builds the register call afterwards.
+ *
+ *   1. submit `commitCall`
+ *   2. wait `minCommitmentAge`, and register before `maxCommitmentAge`
+ *   3. `await prepareRegisterCall()`, then submit what it returns
+ *
+ * Eligibility is checked here, before the caller pays for the commit: a
+ * governance-reserved label, or an owner below the tier the label requires,
+ * fails now rather than on the second transaction.
+ */
+declare function prepareDotNsRegistration(args: RegisterDotNsArgs, opts: DotNsClientOptions): Promise<Result<DotNsRegistration, DotNsError>>;
+
+/**
+ * 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`).
+ */
+
+/** `IPopRules.PopStatus`. Ordering is meaningful: a user meets a tier when `userStatus >= status`. */
+declare const POP_STATUS: {
+    readonly NoStatus: 0;
+    readonly PopLite: 1;
+    readonly PopFull: 2;
+    readonly Reserved: 3;
+};
+/**
+ * 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.
+ */
+declare const DOTNS_ADDRESSES: {
+    readonly registry: "0xf34054fd76BbF85f216cf9908226D5f0A72E50CA";
+    readonly reverseResolver: "0xee3883d7eB60Ee9BCD7F3bcD8f2f05302A9Cc035";
+    readonly resolver: "0xbd1165E549DF96F083c0A16f61590927bC187009";
+    readonly registrarController: "0xBdaA01bD1bA67d709F2b1fF286Da0d854977EA30";
+    readonly popRules: "0x747B456bE03aec0b42bd85C51513730FBD45DA31";
+    readonly protocolRegistry: "0xD19e3D0C97CF501125a04A97405e3e6592fa846E";
+};
+
+/**
+ * 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`.
+ */
+
+/**
+ * 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
+ */
+declare function deriveContextAlias(parentAddress: string, context: string, ss58Prefix?: number): ContextAliasInfo;
+/**
+ * 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
+ */
+declare function verifyContextAlias(aliasAddress: string, parentAddress: string, context: string): boolean;
+
+export { type ContextAliasInfo, DOTNS_ADDRESSES, DOT_NODE, DOT_TLD, type DotNsClientOptions, DotNsError, type DotNsErrorReason, type DotNsRecord, type DotNsRegistration, type DotNsTld, type OnChainIdentity, POP_STATUS, type RegisterDotNsArgs, type SetRecordArgs, type VerificationResult, deriveContextAlias, dotNsTld, isConsistentDotNsTld, isDotNsAvailable, namehash, prepareDotNsRegistration, resolveDotNs, reverseDotNs, setDotNsRecord, stripSuffix, verifyContextAlias };