@parity/product-sdk 0.0.0-dev.312.0

package/src/identity/types.ts

@@ -0,0 +1,87 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Identity module types
+ *
+ * Types for DotNS name resolution and context-alias derivation
+ */
+
+/** DotNS name resolution result */
+export interface DotNsRecord {
+    /**
+     * 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.
+ */
+export interface ContextAliasInfo {
+    /** Alias SS58 address */
+    address: string;
+    /** H160 EVM address */
+    h160Address: `0x${string}`;
+    /** Parent account address */
+    parentAddress: string;
+    /** Context string used for derivation */
+    context: string;
+}
+
+/** Identity verification result */
+export interface VerificationResult {
+    /** Whether identity is verified */
+    verified: boolean;
+    /** Verification method used */
+    method: "on-chain" | "judgement" | "social";
+    /** Verification details */
+    details?: Record<string, unknown>;
+}
+
+/** On-chain identity info */
+export 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]>;
+}

package/src/index.ts

@@ -0,0 +1,61 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * @parity/product-sdk
+ *
+ * Unified SDK for building products on the Polkadot ecosystem.
+ *
+ * @example
+ * ```ts
+ * import { createApp } from '@parity/product-sdk';
+ *
+ * const app = createApp({
+ *   name: 'my-app',
+ *   logLevel: 'info',
+ * });
+ *
+ * // Connect wallet
+ * const { accounts } = await app.wallet.connect();
+ *
+ * // Use storage
+ * await app.localStorage.set('key', 'value');
+ * ```
+ *
+ * @packageDocumentation
+ */
+
+// Core exports
+export { createApp } from "./core/createApp.js";
+export { configure, createLogger } from "./core/logger.js";
+export type {
+    App,
+    AppConfig,
+    LogLevel,
+    WalletApi,
+    LocalStorageApi,
+    ChainApi,
+    CloudStorageApi,
+    Account,
+    DotNsIdentitySignature,
+    SignMessageWithDotNsIdentityArgs,
+    ChainClient,
+    ChainDefinition,
+    TypedApi,
+    PolkadotClient,
+} from "./core/types.js";
+export type { LogEntry, LogHandler, LoggerConfig, Logger } from "./core/logger.js";
+
+// The throw→Result model. Every fallible SDK operation returns `Result<T, E>`.
+// `Result`/`ok`/`err`/`isErrorOf` come from the generic `@parity/result`; the
+// cross-package `SdkError` marker (`isSdkError` recognizes any error raised by
+// an `@parity/product-sdk-*` package) lives in `@parity/product-sdk-errors`.
+export { ok, err, isErrorOf } from "@parity/result";
+export type { Result } from "@parity/result";
+export { type SdkError, isSdkError } from "@parity/product-sdk-errors";
+
+// Re-export common utilities from leaf packages
+export { isInsideContainer, isInsideContainerSync } from "@parity/product-sdk-host";
+export { createChainClient } from "@parity/product-sdk-chain-client";
+export { SignerManager } from "@parity/product-sdk-signer";
+export { createLocalKvStore } from "@parity/product-sdk-local-storage";
+export { CloudStorageClient, calculateCid } from "@parity/product-sdk-cloud-storage";

package/src/individuality/contract.test.ts

@@ -0,0 +1,135 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Compile-time guard for the chain contract in `@parity/product-sdk-individuality`.
+ *
+ * That package types its chain parameter structurally, listing the storage
+ * entries it needs rather than naming a descriptor. That keeps it free of a
+ * chain-client dependency and lets its tests use a plain double, at the cost that
+ * the contract can drift from the real chain silently, since the double satisfies
+ * it by construction.
+ *
+ * This file closes that gap: if a descriptor regeneration changes a key or a
+ * value type, `pnpm typecheck` fails here. It guards both of that package's
+ * chain contracts, `IndividualityChain` for the personhood batch and
+ * `ConsumersChain` for the account to username read.
+ *
+ * **It checks the built `dist`, not the sibling's `src`.** The contracts resolve
+ * through `@parity/product-sdk-individuality`'s `types` field, so editing a
+ * contract and running this typecheck without rebuilding that package asserts
+ * against the previous build. Run `pnpm -r build` first, or the guard silently
+ * checks stale types. Verified 2026-08-19 by mutating a contract and watching
+ * the typecheck pass until the sibling was rebuilt.
+ *
+ * **It lives in the umbrella package deliberately.** Inside the individuality
+ * package the same assertion is vacuous, passing even against a contract that
+ * demands a pallet the chain does not have, because the descriptor types do not
+ * fully resolve through that package's dependency graph. Here, where both
+ * `chain-client` and the individuality package are direct dependencies, it
+ * correctly rejects a bogus contract. The negative control below keeps that
+ * property honest: if `IndividualityChain` ever stopped constraining, the
+ * `@ts-expect-error` would report as unused and this file would fail.
+ */
+import type { getChainAPI } from "@parity/product-sdk-chain-client";
+import type { RingVRFProof as HostRingVRFProof } from "@parity/product-sdk-host";
+import type {
+    ConsumersChain,
+    IndividualityChain,
+    RingVRFProof as AsPersonRingVRFProof,
+} from "@parity/product-sdk-individuality";
+import { expect, test } from "vitest";
+
+// The false branch must be `false`, not `never`. `never` is assignable to
+// `true`, so a `never` branch would make the assertion unfalsifiable.
+type Assert<T extends true> = T;
+
+type PaseoClient = Awaited<ReturnType<typeof getChainAPI<"paseo">>>;
+type DevnetClient = Awaited<ReturnType<typeof getChainAPI<"devnet">>>;
+
+// These four aliases are the test. Each fails to typecheck if its condition
+// breaks, so they need no export and no runtime reference.
+type PaseoSatisfiesContract = Assert<PaseoClient extends IndividualityChain ? true : false>;
+type DevnetSatisfiesContract = Assert<DevnetClient extends IndividualityChain ? true : false>;
+
+// `ConsumersChain` needs this more than the batch contract does: its value shape
+// was derived from the pallet and the codegen rather than read off the emitted
+// descriptor, so these two lines are what make that derivation a checked fact.
+type PaseoSatisfiesConsumers = Assert<PaseoClient extends ConsumersChain ? true : false>;
+type DevnetSatisfiesConsumers = Assert<DevnetClient extends ConsumersChain ? true : false>;
+
+// Negative control, kept type-only so it emits no runtime code. If
+// `IndividualityChain` ever stopped constraining, this flips to `false` and the
+// file fails to typecheck, which is what keeps the assertions above honest.
+type ClientWithoutIndividuality = {
+    assetHub: unknown;
+    raw: { assetHub: unknown };
+    destroy(): void;
+};
+type RejectsBogusClient = Assert<
+    ClientWithoutIndividuality extends IndividualityChain ? false : true
+>;
+type RejectsBogusConsumersClient = Assert<
+    ClientWithoutIndividuality extends ConsumersChain ? false : true
+>;
+
+// The write half declares its own `RingVRFProof` rather than importing the
+// host's, for the same reason `IndividualityChain` is structural: it keeps the
+// individuality package free of a dependency on `@parity/product-sdk-host`. The
+// cost is that a field rename on the host side would go unnoticed there, since
+// nothing in that package resolves the host type. Here both are direct
+// dependencies, so this is where the two can be tied together.
+type HostProofSatisfiesLocal = Assert<HostRingVRFProof extends AsPersonRingVRFProof ? true : false>;
+
+// Negative control for the same assertion. If `AsPersonRingVRFProof` ever
+// stopped constraining, this flips to `false` and the file fails to typecheck.
+type ProofWithoutRingIndex = {
+    proof: Uint8Array;
+    contextualAlias: { context: Uint8Array; alias: Uint8Array };
+    ringRevision: number;
+};
+type RejectsProofMissingRingIndex = Assert<
+    ProofWithoutRingIndex extends AsPersonRingVRFProof ? false : true
+>;
+
+// `AliasWithProof` is only ever accepted for `People.set_alias_account`, so the
+// call has to exist on the real chain with the two arguments the extension's
+// validation reads. A descriptor regeneration that renames either fails here.
+type PeopleTx = PaseoClient["individuality"]["tx"]["People"];
+type SetAliasAccountExists = Assert<"set_alias_account" extends keyof PeopleTx ? true : false>;
+type SetAliasAccountArgs = Parameters<PeopleTx["set_alias_account"]>[0];
+type SetAliasAccountTakesAccountAndValidAt = Assert<
+    "account" extends keyof SetAliasAccountArgs
+        ? "call_valid_at" extends keyof SetAliasAccountArgs
+            ? true
+            : false
+        : false
+>;
+
+// The JSDoc examples in the individuality package submit
+// `Game.sign_up_with_alias` under a person origin. A person origin supplies only
+// the origin, never the call arguments, so those snippets go stale the moment
+// this call's parameters change — and nothing else in the repo compiles them.
+type GameTx = PaseoClient["individuality"]["tx"]["Game"];
+type SignUpWithAliasExists = Assert<"sign_up_with_alias" extends keyof GameTx ? true : false>;
+type SignUpWithAliasArgs = Parameters<GameTx["sign_up_with_alias"]>[0];
+type SignUpWithAliasTakesTheDocumentedArgs = Assert<
+    "identifier_key" extends keyof SignUpWithAliasArgs
+        ? "statement_account" extends keyof SignUpWithAliasArgs
+            ? "sig" extends keyof SignUpWithAliasArgs
+                ? true
+                : false
+            : false
+        : false
+>;
+
+// Negative control for the assertion above. The `extends keyof` chain would pass
+// vacuously if `SignUpWithAliasArgs` ever resolved to something permissive such
+// as `any`, so this pins a shape that is missing `sig` and requires it to fail.
+type SignUpArgsWithoutSig = Pick<SignUpWithAliasArgs, "identifier_key" | "statement_account">;
+type RejectsSignUpArgsMissingSig = Assert<"sig" extends keyof SignUpArgsWithoutSig ? false : true>;
+
+test("the individuality chain contract is asserted at compile time", () => {
+    // The type assertions above are the test. This keeps vitest from reporting
+    // the file as an empty suite.
+    expect(true).toBe(true);
+});

package/src/individuality/index.ts

@@ -0,0 +1,8 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * @parity/product-sdk/individuality
+ *
+ * Re-exports from @parity/product-sdk-individuality.
+ */
+export * from "@parity/product-sdk-individuality";

package/src/local-storage/index.ts

@@ -0,0 +1,8 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * @parity/product-sdk/local-storage
+ *
+ * Re-exports from @parity/product-sdk-local-storage.
+ */
+export * from "@parity/product-sdk-local-storage";

package/src/react/context.ts

@@ -0,0 +1,35 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * React context for Product SDK
+ */
+
+import { createContext, useContext } from "react";
+import type { App } from "../core/types.js";
+
+/** Context for the Product SDK app instance */
+export const ProductSDKContext = createContext<App | null>(null);
+
+/**
+ * Hook to access the Product SDK app instance
+ *
+ * @throws If used outside of ProductSDKProvider
+ *
+ * @example
+ * ```tsx
+ * function MyComponent() {
+ *   const app = useProductSDK();
+ *   // Use app.wallet, app.localStorage, etc.
+ * }
+ * ```
+ */
+export function useProductSDK(): App {
+    const app = useContext(ProductSDKContext);
+    if (!app) {
+        throw new Error(
+            "useProductSDK must be used within a ProductSDKProvider. " +
+                'Wrap your app with <ProductSDKProvider name="your-app">.',
+        );
+    }
+    return app;
+}

package/src/react/index.ts

@@ -0,0 +1,43 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * @parity/product-sdk/react
+ *
+ * React bindings for the Product SDK.
+ * Provides hooks and components for wallet connection, storage, and chain interaction.
+ *
+ * @example
+ * ```tsx
+ * import { ProductSDKProvider, useWallet, useLocalStorage } from '@parity/product-sdk/react';
+ *
+ * function App() {
+ *   return (
+ *     <ProductSDKProvider name="my-app">
+ *       <MyApp />
+ *     </ProductSDKProvider>
+ *   );
+ * }
+ *
+ * function MyApp() {
+ *   const { isConnected, connect, accounts } = useWallet();
+ *   const [theme, setTheme] = useLocalStorage('theme', 'light');
+ *
+ *   // ...
+ * }
+ * ```
+ */
+
+// Provider
+export { ProductSDKProvider } from "./provider.js";
+export type { ProductSDKProviderProps } from "./provider.js";
+
+// Context
+export { ProductSDKContext, useProductSDK } from "./context.js";
+
+// Hooks
+export { useWallet } from "./useWallet.js";
+export type { UseWalletState, UseWalletActions, UseWalletReturn } from "./useWallet.js";
+
+export { useLocalStorage, useLocalStorageString } from "./useLocalStorage.js";
+
+export { useChain } from "./useChain.js";

package/src/react/provider.tsx

@@ -0,0 +1,78 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * ProductSDKProvider component
+ */
+
+import React, { useEffect, useState, type ReactNode } from "react";
+import { ProductSDKContext } from "./context.js";
+import { createApp } from "../core/createApp.js";
+import type { App, LogLevel } from "../core/types.js";
+
+/** Props for ProductSDKProvider */
+export interface ProductSDKProviderProps {
+    /** Application name - used for storage namespacing and product account derivation */
+    name: string;
+    /** Log level (default: 'info') */
+    logLevel?: LogLevel;
+    /** Child components */
+    children: ReactNode;
+    /** Fallback to show while loading */
+    fallback?: ReactNode;
+}
+
+/**
+ * Provider component that initializes the Product SDK
+ *
+ * @example
+ * ```tsx
+ * import { ProductSDKProvider } from '@parity/product-sdk/react';
+ *
+ * function App() {
+ *   return (
+ *     <ProductSDKProvider name="my-app" fallback={<Loading />}>
+ *       <MyApp />
+ *     </ProductSDKProvider>
+ *   );
+ * }
+ * ```
+ */
+export function ProductSDKProvider({
+    name,
+    logLevel = "info",
+    children,
+    fallback = null,
+}: ProductSDKProviderProps) {
+    const [app, setApp] = useState<App | null>(null);
+    const [error, setError] = useState<Error | null>(null);
+
+    useEffect(() => {
+        let mounted = true;
+
+        createApp({ name, logLevel })
+            .then((createdApp) => {
+                if (mounted) {
+                    setApp(createdApp);
+                }
+            })
+            .catch((e) => {
+                if (mounted) {
+                    setError(e instanceof Error ? e : new Error(String(e)));
+                }
+            });
+
+        return () => {
+            mounted = false;
+        };
+    }, [name, logLevel]);
+
+    if (error) {
+        throw error;
+    }
+
+    if (!app) {
+        return <>{fallback}</>;
+    }
+
+    return <ProductSDKContext.Provider value={app}>{children}</ProductSDKContext.Provider>;
+}

package/src/react/useChain.ts

@@ -0,0 +1,35 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * useChain hook
+ */
+
+import { useMemo } from "react";
+import { useProductSDK } from "./context.js";
+import type { ChainDefinition, TypedApi } from "../core/types.js";
+
+/**
+ * Hook to get a typed chain client
+ *
+ * @param chain - Chain descriptor (PAPI ChainDefinition)
+ *
+ * @example
+ * ```tsx
+ * import { paseo_asset_hub } from '@parity/product-sdk-descriptors/paseo-asset-hub';
+ * import { useChain } from '@parity/product-sdk/react';
+ *
+ * function AssetHubBalance() {
+ *   const assetHub = useChain(paseo_asset_hub);
+ *
+ *   // assetHub is typed for Asset Hub queries
+ *   const balance = await assetHub.query.System.Account.getValue(address);
+ * }
+ * ```
+ */
+export function useChain<T extends ChainDefinition>(chain: T): TypedApi<T> {
+    const app = useProductSDK();
+
+    return useMemo(() => {
+        return app.chain.getClient(chain);
+    }, [app, chain]);
+}

package/src/react/useLocalStorage.ts

@@ -0,0 +1,127 @@
+// Copyright 2026 Parity Technologies (UK) Ltd.
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * useLocalStorage hook
+ */
+
+import { useState, useEffect, useCallback } from "react";
+import { useProductSDK } from "./context.js";
+
+/**
+ * Hook for key-value storage operations
+ *
+ * @param key - Storage key
+ * @param defaultValue - Default value if key doesn't exist
+ *
+ * @example
+ * ```tsx
+ * function ThemeToggle() {
+ *   const [theme, setTheme, { loading }] = useLocalStorage('theme', 'light');
+ *
+ *   if (loading) return <div>Loading...</div>;
+ *
+ *   return (
+ *     <button onClick={() => setTheme(theme === 'light' ? 'dark' : 'light')}>
+ *       Current: {theme}
+ *     </button>
+ *   );
+ * }
+ * ```
+ */
+export function useLocalStorage<T = string>(
+    key: string,
+    defaultValue?: T,
+): [T | null, (value: T) => Promise<void>, { loading: boolean; error: Error | null }] {
+    const app = useProductSDK();
+
+    const [value, setValue] = useState<T | null>(null);
+    const [loading, setLoading] = useState(true);
+    const [error, setError] = useState<Error | null>(null);
+
+    // Load initial value
+    useEffect(() => {
+        let mounted = true;
+
+        const loadValue = async () => {
+            try {
+                setLoading(true);
+                const stored = await app.localStorage.getJSON<T>(key);
+                if (mounted) {
+                    setValue(stored ?? defaultValue ?? null);
+                    setLoading(false);
+                }
+            } catch (e) {
+                if (mounted) {
+                    setError(e instanceof Error ? e : new Error(String(e)));
+                    setLoading(false);
+                }
+            }
+        };
+
+        loadValue();
+
+        return () => {
+            mounted = false;
+        };
+    }, [app, key, defaultValue]);
+
+    const setStoredValue = useCallback(
+        async (newValue: T) => {
+            try {
+                setError(null);
+                await app.localStorage.setJSON(key, newValue);
+                setValue(newValue);
+            } catch (e) {
+                setError(e instanceof Error ? e : new Error(String(e)));
+                throw e;
+            }
+        },
+        [app, key],
+    );
+
+    return [value, setStoredValue, { loading, error }];
+}
+
+/**
+ * Hook for string storage (simpler API)
+ *
+ * @param key - Storage key
+ * @param defaultValue - Default value
+ */
+export function useLocalStorageString(
+    key: string,
+    defaultValue?: string,
+): [string | null, (value: string) => Promise<void>, { loading: boolean }] {
+    const app = useProductSDK();
+
+    const [value, setValue] = useState<string | null>(null);
+    const [loading, setLoading] = useState(true);
+
+    useEffect(() => {
+        let mounted = true;
+
+        const loadValue = async () => {
+            const stored = await app.localStorage.get(key);
+            if (mounted) {
+                setValue(stored ?? defaultValue ?? null);
+                setLoading(false);
+            }
+        };
+
+        loadValue();
+
+        return () => {
+            mounted = false;
+        };
+    }, [app, key, defaultValue]);
+
+    const setStoredValue = useCallback(
+        async (newValue: string) => {
+            await app.localStorage.set(key, newValue);
+            setValue(newValue);
+        },
+        [app, key],
+    );
+
+    return [value, setStoredValue, { loading }];
+}