@parity/product-sdk 0.1.0

package/src/identity/product-account.ts

@@ -0,0 +1,158 @@
+/**
+ * Product account derivation
+ *
+ * Derives product-scoped accounts from a parent account
+ */
+
+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 { ProductAccountInfo, AnonymousAliasInfo, RingLocation } from "./types.js";
+
+const log = createLogger("identity");
+
+/**
+ * Derive a product-scoped account from a parent account
+ *
+ * The product account is deterministically derived using:
+ * productPublicKey = hash(parentPublicKey || productName)
+ *
+ * @param parentAddress - Parent account SS58 address
+ * @param productName - Product name for derivation
+ * @param ss58Prefix - SS58 prefix (default: 42)
+ * @returns Product account info
+ *
+ * @example
+ * ```ts
+ * const productAccount = deriveProductAccount(
+ *   '5GrwvaEF5zXb26Fz9rcQpDWS57CtERHpNehXCPcNoHGKutQY',
+ *   'my-app'
+ * );
+ * console.log('Product address:', productAccount.address);
+ * ```
+ */
+export function deriveProductAccount(
+    parentAddress: string,
+    productName: string,
+    ss58Prefix = 42,
+): ProductAccountInfo {
+    const { publicKey: parentPublicKey } = ss58Decode(parentAddress);
+
+    // Derive product public key: blake2b-256(parentPublicKey || productName)
+    const productNameBytes = new TextEncoder().encode(productName);
+    const combined = new Uint8Array(parentPublicKey.length + productNameBytes.length);
+    combined.set(parentPublicKey, 0);
+    combined.set(productNameBytes, parentPublicKey.length);
+
+    const productPublicKey = blake2b256(combined);
+    const address = ss58Encode(productPublicKey, ss58Prefix);
+    const h160Address = deriveH160(productPublicKey);
+
+    log.debug("Derived product account", {
+        parentAddress,
+        productName,
+        address,
+    });
+
+    return {
+        address,
+        h160Address,
+        parentAddress,
+        productName,
+    };
+}
+
+/**
+ * Verify that a product account was derived from a parent account
+ *
+ * @param productAddress - Product account address
+ * @param parentAddress - Claimed parent address
+ * @param productName - Product name
+ * @returns True if derivation is valid
+ */
+export function verifyProductAccount(
+    productAddress: string,
+    parentAddress: string,
+    productName: string,
+): boolean {
+    try {
+        const derived = deriveProductAccount(parentAddress, productName);
+        const { publicKey: productKey } = ss58Decode(productAddress);
+        const { publicKey: derivedKey } = ss58Decode(derived.address);
+
+        // Compare public keys
+        if (productKey.length !== derivedKey.length) return false;
+        for (let i = 0; i < productKey.length; i++) {
+            if (productKey[i] !== derivedKey[i]) return false;
+        }
+        return true;
+    } catch {
+        return false;
+    }
+}
+
+/**
+ * Derive an anonymous alias using Ring VRF
+ *
+ * This creates a context-specific alias that cannot be linked
+ * back to the original identity without the ring proof.
+ *
+ * @param context - Context for alias derivation (e.g., "voting-round-1")
+ * @param ringLocation - Ring location for proof generation
+ * @returns Anonymous alias info
+ */
+export function deriveAnonymousAlias(
+    context: string,
+    ringLocation: RingLocation,
+): AnonymousAliasInfo {
+    log.debug("Deriving anonymous alias", { context, ringLocation });
+
+    // TODO: Implement Ring VRF alias derivation
+    // This requires the Ring VRF implementation from TruAPI
+    throw new Error(
+        "deriveAnonymousAlias() is not yet implemented. " +
+            "This requires container mode with Ring VRF support.",
+    );
+}
+
+/**
+ * Create a Ring VRF proof for a message
+ *
+ * @param message - Message to prove
+ * @param ringLocation - Ring location
+ * @returns Proof bytes
+ */
+export async function createRingProof(
+    message: Uint8Array,
+    ringLocation: RingLocation,
+): Promise<Uint8Array> {
+    log.debug("Creating ring proof", { ringLocation });
+
+    // TODO: Implement Ring VRF proof creation via TruAPI
+    throw new Error(
+        "createRingProof() is not yet implemented. " +
+            "This requires container mode with Ring VRF support.",
+    );
+}
+
+/**
+ * Verify a Ring VRF proof
+ *
+ * @param message - Original message
+ * @param proof - Proof bytes
+ * @param alias - Expected alias
+ * @returns True if proof is valid
+ */
+export async function verifyRingProof(
+    message: Uint8Array,
+    proof: Uint8Array,
+    alias: string,
+): Promise<boolean> {
+    log.debug("Verifying ring proof");
+
+    // TODO: Implement Ring VRF proof verification
+    throw new Error(
+        "verifyRingProof() is not yet implemented. " +
+            "This requires container mode with Ring VRF support.",
+    );
+}

package/src/identity/types.ts

@@ -0,0 +1,75 @@
+/**
+ * Identity module types
+ *
+ * Types for DotNS name resolution and product account derivation
+ */
+
+/** DotNS name resolution result */
+export interface DotNsRecord {
+    /** Resolved SS58 address */
+    address: string;
+    /** Name that was resolved */
+    name: string;
+    /** Owner address */
+    owner: string;
+    /** Expiration timestamp (if applicable) */
+    expiresAt?: number;
+}
+
+/** Product account info */
+export interface ProductAccountInfo {
+    /** Product-scoped SS58 address */
+    address: string;
+    /** H160 EVM address */
+    h160Address: `0x${string}`;
+    /** Parent account address */
+    parentAddress: string;
+    /** Product name used for derivation */
+    productName: string;
+}
+
+/** Ring VRF alias info */
+export interface AnonymousAliasInfo {
+    /** Anonymous alias identifier */
+    alias: string;
+    /** Ring location for proof generation */
+    ringLocation: RingLocation;
+    /** Context used for alias derivation */
+    context: string;
+}
+
+/** Ring location for VRF proofs */
+export interface RingLocation {
+    /** Ring index */
+    ringIndex: number;
+    /** Member index within ring */
+    memberIndex: number;
+}
+
+/** 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,49 @@
+/**
+ * @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.storage.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,
+    StorageApi,
+    ChainApi,
+    BulletinApi,
+    Account,
+    ChainClient,
+    ChainDefinition,
+    TypedApi,
+    PolkadotClient,
+} from "./core/types.js";
+export type { LogEntry, LogHandler, LoggerConfig, Logger } from "./core/logger.js";
+
+// 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 { createKvStore } from "@parity/product-sdk-storage";
+export { BulletinClient, computeCid } from "@parity/product-sdk-bulletin";

package/src/react/context.ts

@@ -0,0 +1,33 @@
+/**
+ * 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.storage, 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,41 @@
+/**
+ * @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, useStorage } from '@parity/product-sdk/react';
+ *
+ * function App() {
+ *   return (
+ *     <ProductSDKProvider name="my-app">
+ *       <MyApp />
+ *     </ProductSDKProvider>
+ *   );
+ * }
+ *
+ * function MyApp() {
+ *   const { isConnected, connect, accounts } = useWallet();
+ *   const [theme, setTheme] = useStorage('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 { useStorage, useStorageString } from "./useStorage.js";
+
+export { useChain } from "./useChain.js";

package/src/react/provider.tsx

@@ -0,0 +1,76 @@
+/**
+ * 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,33 @@
+/**
+ * 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/useStorage.ts

@@ -0,0 +1,125 @@
+/**
+ * useStorage 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 }] = useStorage('theme', 'light');
+ *
+ *   if (loading) return <div>Loading...</div>;
+ *
+ *   return (
+ *     <button onClick={() => setTheme(theme === 'light' ? 'dark' : 'light')}>
+ *       Current: {theme}
+ *     </button>
+ *   );
+ * }
+ * ```
+ */
+export function useStorage<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.storage.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.storage.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 useStorageString(
+    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.storage.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.storage.set(key, newValue);
+            setValue(newValue);
+        },
+        [app, key],
+    );
+
+    return [value, setStoredValue, { loading }];
+}