@parity/product-sdk-signer 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,558 @@
+import * as polkadot_api from 'polkadot-api';
+import { PolkadotSigner } from 'polkadot-api';
+import { SS58String } from '@parity/product-sdk-address';
+
+/** Function that unsubscribes a listener when called. */
+type Unsubscribe = () => void;
+/**
+ * Interface that all signer providers must implement.
+ *
+ * Providers are responsible for discovering accounts and creating signers
+ * from a specific source (Host API or dev accounts).
+ */
+interface SignerProvider {
+    /** Unique identifier for this provider type. */
+    readonly type: ProviderType;
+    /**
+     * Attempt to connect and discover accounts.
+     *
+     * @param signal - Optional AbortSignal to cancel the connection attempt.
+     * @returns Accounts on success, typed error on failure.
+     */
+    connect(signal?: AbortSignal): Promise<Result<SignerAccount[], SignerError>>;
+    /**
+     * Disconnect and clean up resources.
+     * Safe to call multiple times.
+     */
+    disconnect(): void;
+    /**
+     * Subscribe to connection status changes.
+     *
+     * Not all providers emit status changes — for example, dev accounts
+     * are always "connected" and never emit.
+     *
+     * @returns Unsubscribe function.
+     */
+    onStatusChange(callback: (status: ConnectionStatus) => void): Unsubscribe;
+    /**
+     * Subscribe to account list changes.
+     *
+     * Emitted when the set of available accounts changes (e.g., user
+     * connects/disconnects in the host wallet).
+     *
+     * @returns Unsubscribe function.
+     */
+    onAccountsChange(callback: (accounts: SignerAccount[]) => void): Unsubscribe;
+}
+
+/** Connection status for a signer provider. */
+type ConnectionStatus = "disconnected" | "connecting" | "connected";
+/**
+ * Identifies the source of an account.
+ *
+ * - `"host"`: Host API provider (Polkadot Desktop / Mobile) — the primary provider
+ * - `"dev"`: Development accounts (Alice, Bob, etc.) — for testing only
+ */
+type ProviderType = "host" | "dev";
+/** A signing-capable account from any provider. */
+interface SignerAccount {
+    /** SS58 address (generic prefix 42 by default). */
+    address: SS58String;
+    /**
+     * H160 EVM address derived from the public key.
+     *
+     * For native Substrate accounts: keccak256(publicKey), last 20 bytes.
+     * For EVM-derived accounts: strips the 0xEE padding.
+     * Used for pallet-revive / Asset Hub EVM contract interactions.
+     */
+    h160Address: `0x${string}`;
+    /** Raw public key (32 bytes). May be sr25519, ed25519, or ecdsa depending on the provider. */
+    publicKey: Uint8Array;
+    /** Human-readable name if available from the provider. */
+    name: string | null;
+    /** Which provider supplied this account. */
+    source: ProviderType;
+    /** Get the PolkadotSigner for this account. */
+    getSigner(): PolkadotSigner;
+}
+/** Full state snapshot emitted to subscribers. */
+interface SignerState {
+    /** Current connection status. */
+    status: ConnectionStatus;
+    /** All available accounts across all connected providers. */
+    accounts: readonly SignerAccount[];
+    /** Currently selected account (null if none selected). */
+    selectedAccount: SignerAccount | null;
+    /** Which provider is active (null if disconnected). */
+    activeProvider: ProviderType | null;
+    /** Last error (null if no error). */
+    error: SignerError | null;
+}
+/** Lightweight Result type for operations that can fail expectedly. */
+type Result<T, E> = {
+    ok: true;
+    value: T;
+} | {
+    ok: false;
+    error: E;
+};
+/** Create a successful Result. */
+declare function ok<T>(value: T): Result<T, never>;
+/** Create a failed Result. */
+declare function err<E>(error: E): Result<never, E>;
+/** Factory function that creates a SignerProvider for a given type. */
+type ProviderFactory = (type: ProviderType) => SignerProvider;
+/**
+ * Adapter for persisting the selected account address across sessions.
+ *
+ * `globalThis.localStorage` satisfies this interface. Pass a custom
+ * implementation for container environments (e.g., hostLocalStorage)
+ * or for testing.
+ */
+interface AccountPersistence {
+    getItem(key: string): string | null | Promise<string | null>;
+    setItem(key: string, value: string): void | Promise<void>;
+    removeItem(key: string): void | Promise<void>;
+}
+/** Options for SignerManager construction. */
+interface SignerManagerOptions {
+    /** SS58 prefix for address encoding. Default: 42 */
+    ss58Prefix?: number;
+    /**
+     * Maximum time in ms to wait for the Host API.
+     * Applied as an AbortSignal timeout on the host provider connection.
+     * Default: 10_000
+     */
+    hostTimeout?: number;
+    /** Maximum retry attempts for provider connection. Default: 3 */
+    maxRetries?: number;
+    /** Custom provider factory. Override to inject test doubles or custom providers. */
+    createProvider?: ProviderFactory;
+    /**
+     * App name used for storage key namespacing. Default: "product-sdk"
+     * The selected account is persisted under `product-sdk:signer:{dappName}:selectedAccount`.
+     */
+    dappName?: string;
+    /**
+     * Storage adapter for persisting selected account.
+     * Uses host localStorage when inside a container.
+     * Set to `null` to disable persistence entirely.
+     */
+    persistence?: AccountPersistence | null;
+}
+
+/** Base class for all signer errors. Use `instanceof SignerError` to catch any signer-related error. */
+declare class SignerError extends Error {
+    constructor(message: string, options?: ErrorOptions);
+}
+/** The Host API is not available (product-sdk not installed or not inside a container). */
+declare class HostUnavailableError extends SignerError {
+    constructor(message?: string);
+}
+/** The host rejected the account or signing request. */
+declare class HostRejectedError extends SignerError {
+    constructor(message?: string);
+}
+/** The host connection was lost. */
+declare class HostDisconnectedError extends SignerError {
+    constructor(message?: string);
+}
+/** A signing operation failed. */
+declare class SigningFailedError extends SignerError {
+    constructor(cause: unknown, message?: string);
+}
+/** No accounts available from the provider. */
+declare class NoAccountsError extends SignerError {
+    readonly provider: ProviderType;
+    constructor(provider: ProviderType, message?: string);
+}
+/** An operation timed out. */
+declare class TimeoutError extends SignerError {
+    readonly operation: string;
+    readonly ms: number;
+    constructor(operation: string, ms: number);
+}
+/** An account was not found by address. */
+declare class AccountNotFoundError extends SignerError {
+    readonly address: string;
+    constructor(address: string);
+}
+/** The SignerManager has been destroyed and is no longer usable. */
+declare class DestroyedError extends SignerError {
+    constructor();
+}
+/** Check if a SignerError is a host-related error. */
+declare function isHostError(e: SignerError): e is HostUnavailableError | HostRejectedError | HostDisconnectedError;
+
+/** Options for the Host API provider. */
+interface HostProviderOptions {
+    /** SS58 prefix for address encoding. Default: 42 */
+    ss58Prefix?: number;
+    /** Max retry attempts for initial connection. Default: 3 */
+    maxRetries?: number;
+    /** Initial retry delay in ms. Default: 500 */
+    retryDelay?: number;
+    /**
+     * Custom SDK loader. Defaults to `import("@novasamatech/product-sdk")`.
+     * Override this for testing or custom SDK setups.
+     * @internal
+     */
+    loadSdk?: () => Promise<ProductSdkModule>;
+    /**
+     * Custom loader for `@novasamatech/host-api` (used to construct the
+     * `TransactionSubmit` permission request). Defaults to dynamic import.
+     * @internal
+     */
+    loadHostApiEnum?: () => Promise<HostApiEnumHelper>;
+    /**
+     * Whether to request the host's `TransactionSubmit` permission after a
+     * successful `connect()`. Without this, subsequent signing requests are
+     * rejected by the host with `PermissionDenied`. Default: `true`.
+     *
+     * Set to `false` if your app needs to defer the permission prompt or
+     * drives it manually.
+     */
+    requestTransactionSubmitPermission?: boolean;
+}
+/**
+ * A product account — an app-scoped derived account managed by the host wallet.
+ *
+ * The host derives a unique keypair for each app (identified by `dotNsIdentifier`)
+ * so apps get their own account that the user controls but is scoped to the app.
+ */
+interface ProductAccount {
+    /** App identifier (e.g., "mark3t.dot"). */
+    dotNsIdentifier: string;
+    /** Derivation index within the app scope. Default: 0 */
+    derivationIndex: number;
+    /** Raw public key (32 bytes). */
+    publicKey: Uint8Array;
+}
+/**
+ * A contextual alias obtained from Ring VRF.
+ *
+ * Proves account membership in a ring without revealing which account.
+ */
+interface ContextualAlias {
+    /** Ring context (32 bytes). */
+    context: Uint8Array;
+    /** The Ring VRF alias bytes. */
+    alias: Uint8Array;
+}
+/**
+ * Location of a Ring VRF ring on-chain.
+ *
+ * Matches the product-sdk's `RingLocation` codec shape.
+ */
+interface RingLocation {
+    genesisHash: string;
+    ringRootHash: string;
+    hints?: {
+        palletInstance?: number;
+    } | undefined;
+}
+interface RawAccount {
+    publicKey: Uint8Array;
+    name?: string | undefined;
+}
+interface NeverthrowResultAsync<T, E> {
+    match: <A, B = A>(ok: (t: T) => A, err: (e: E) => B) => Promise<A | B>;
+}
+/** @internal */
+interface AccountsProvider {
+    getNonProductAccounts: () => NeverthrowResultAsync<RawAccount[], unknown>;
+    getNonProductAccountSigner: (account: ProductAccount) => polkadot_api.PolkadotSigner;
+    getProductAccount: (dotNsIdentifier: string, derivationIndex?: number) => NeverthrowResultAsync<RawAccount, unknown>;
+    getProductAccountSigner: (account: ProductAccount) => polkadot_api.PolkadotSigner;
+    getProductAccountAlias: (dotNsIdentifier: string, derivationIndex?: number) => NeverthrowResultAsync<ContextualAlias, unknown>;
+    createRingVRFProof: (dotNsIdentifier: string, derivationIndex: number, location: unknown, message: Uint8Array) => NeverthrowResultAsync<Uint8Array, unknown>;
+    subscribeAccountConnectionStatus: (callback: (status: string) => void) => {
+        unsubscribe: () => void;
+    } | (() => void);
+}
+/** @internal */
+interface HostApiPermissionBridge {
+    /**
+     * Request a Host API permission. Product-sdk's `hostApi.permission(...)`
+     * takes a tagged enum like `enumValue("v1", { tag: "TransactionSubmit" })`
+     * and returns a neverthrow ResultAsync.
+     */
+    permission: (request: unknown) => NeverthrowResultAsync<unknown, unknown>;
+}
+/** @internal */
+interface HostApiEnumHelper {
+    enumValue: (version: string, value: {
+        tag: string;
+        value?: unknown;
+    }) => unknown;
+}
+/** @internal */
+interface ProductSdkModule {
+    createAccountsProvider: () => AccountsProvider;
+    /** Present from product-sdk ≥ 0.6; used to request TransactionSubmit. */
+    hostApi?: HostApiPermissionBridge;
+}
+/**
+ * Provider for the Host API (Polkadot Desktop / Android).
+ *
+ * Dynamically imports `@novasamatech/product-sdk` at runtime so it remains
+ * an optional peer dependency. Apps running outside a host container will
+ * gracefully get a `HOST_UNAVAILABLE` error.
+ *
+ * Supports both non-product accounts (user's external wallets) and product
+ * accounts (app-scoped derived accounts managed by the host).
+ */
+declare class HostProvider implements SignerProvider {
+    readonly type: ProviderType;
+    private readonly ss58Prefix;
+    private readonly maxRetries;
+    private readonly retryDelay;
+    private readonly loadSdk;
+    private readonly loadHostApiEnum;
+    private readonly requestTxPermission;
+    private accountsProvider;
+    private statusCleanup;
+    private statusListeners;
+    private accountListeners;
+    constructor(options?: HostProviderOptions);
+    connect(signal?: AbortSignal): Promise<Result<SignerAccount[], SignerError>>;
+    disconnect(): void;
+    onStatusChange(callback: (status: ConnectionStatus) => void): Unsubscribe;
+    onAccountsChange(callback: (accounts: SignerAccount[]) => void): Unsubscribe;
+    /**
+     * Get an app-scoped product account from the host.
+     *
+     * Product accounts are derived by the host wallet for each app, identified
+     * by `dotNsIdentifier` (e.g., "mark3t.dot"). The user controls these accounts
+     * but they are scoped to the requesting app.
+     *
+     * Requires a prior successful `connect()` call.
+     */
+    getProductAccount(dotNsIdentifier: string, derivationIndex?: number): Promise<Result<SignerAccount, SignerError>>;
+    /**
+     * Get a PolkadotSigner for a product account.
+     *
+     * Convenience method for when you already have the product account details.
+     * Requires a prior successful `connect()` call.
+     */
+    getProductAccountSigner(account: ProductAccount): polkadot_api.PolkadotSigner;
+    /**
+     * Get a contextual alias for a product account via Ring VRF.
+     *
+     * Aliases prove account membership in a ring without revealing which
+     * account produced the alias.
+     *
+     * Requires a prior successful `connect()` call.
+     */
+    getProductAccountAlias(dotNsIdentifier: string, derivationIndex?: number): Promise<Result<ContextualAlias, SignerError>>;
+    /**
+     * Create a Ring VRF proof for anonymous operations.
+     *
+     * Proves that the signer is a member of the ring at the given location
+     * without revealing which member. Used for privacy-preserving protocols.
+     *
+     * Requires a prior successful `connect()` call.
+     */
+    createRingVRFProof(dotNsIdentifier: string, derivationIndex: number, location: RingLocation, message: Uint8Array): Promise<Result<Uint8Array, SignerError>>;
+    private tryConnect;
+    private mapAccounts;
+}
+
+/**
+ * Core orchestrator for signer management.
+ *
+ * Manages account discovery and signer creation via the Host API.
+ * Framework-agnostic — use the subscribe() pattern to integrate with
+ * React, Vue, or any framework.
+ *
+ * @example
+ * ```ts
+ * const manager = new SignerManager();
+ * manager.subscribe(state => console.log(state.status));
+ *
+ * // Connect to the host provider
+ * await manager.connect();
+ *
+ * // Or use dev accounts for testing
+ * await manager.connect("dev");
+ *
+ * // Select account and get signer
+ * manager.selectAccount("5GrwvaEF...");
+ * const signer = manager.getSigner();
+ * ```
+ */
+declare class SignerManager {
+    private state;
+    private provider;
+    private subscribers;
+    private cleanups;
+    private isDestroyed;
+    private reconnectController;
+    private connectController;
+    private readonly ss58Prefix;
+    private readonly hostTimeout;
+    private readonly maxRetries;
+    private readonly providerFactory;
+    private readonly dappName;
+    private readonly persistenceOption;
+    private resolvedPersistence;
+    constructor(options?: SignerManagerOptions);
+    private getPersistence;
+    /** Get a snapshot of the current state. */
+    getState(): SignerState;
+    /**
+     * Subscribe to state changes. The callback fires on every state mutation.
+     * Returns an unsubscribe function.
+     */
+    subscribe(callback: (state: SignerState) => void): () => void;
+    /**
+     * Connect to a provider.
+     *
+     * If no provider type is specified, connects to the Host API.
+     * The SDK is designed to run exclusively inside a host container.
+     *
+     * When connecting to a specific provider type:
+     * - `"host"`: Connect to the Host API (default, recommended)
+     * - `"dev"`: Connect using dev accounts (for testing)
+     */
+    connect(providerType?: ProviderType): Promise<Result<SignerAccount[], SignerError>>;
+    /** Disconnect from the current provider and reset state. */
+    disconnect(): void;
+    /**
+     * Select an account by address.
+     * Returns the account on success, or ACCOUNT_NOT_FOUND error.
+     */
+    selectAccount(address: string): Result<SignerAccount, SignerError>;
+    /**
+     * Get the PolkadotSigner for the currently selected account.
+     * Returns null if no account is selected or manager is disconnected.
+     */
+    getSigner(): PolkadotSigner | null;
+    /**
+     * Sign arbitrary bytes with the currently selected account.
+     *
+     * Convenience wrapper around `PolkadotSigner.signBytes` — useful for
+     * master key derivation, message signing, and proof generation without
+     * constructing a full transaction.
+     *
+     * Returns a SIGNING_FAILED error if no account is selected or signing fails.
+     */
+    signRaw(data: Uint8Array): Promise<Result<Uint8Array, SignerError>>;
+    /**
+     * Get an app-scoped product account from the host.
+     *
+     * Product accounts are derived by the host wallet for each app, identified
+     * by `dotNsIdentifier` (e.g., "mark3t.dot"). Only available when connected
+     * via the host provider — returns HOST_UNAVAILABLE otherwise.
+     *
+     * @example
+     * ```ts
+     * const result = await manager.getProductAccount("myapp.dot");
+     * if (result.ok) {
+     *   const signer = result.value.getSigner();
+     * }
+     * ```
+     */
+    getProductAccount(dotNsIdentifier: string, derivationIndex?: number): Promise<Result<SignerAccount, SignerError>>;
+    /**
+     * Get a contextual alias for a product account via Ring VRF.
+     *
+     * Aliases prove account membership in a ring without revealing which
+     * account produced the alias. Only available when connected via the host
+     * provider — returns HOST_UNAVAILABLE otherwise.
+     */
+    getProductAccountAlias(dotNsIdentifier: string, derivationIndex?: number): Promise<Result<ContextualAlias, SignerError>>;
+    /**
+     * Create a Ring VRF proof for anonymous operations.
+     *
+     * Proves that the signer is a member of the ring at the given location
+     * without revealing which member. Only available when connected via the
+     * host provider — returns HOST_UNAVAILABLE otherwise.
+     */
+    createRingVRFProof(dotNsIdentifier: string, derivationIndex: number, location: RingLocation, message: Uint8Array): Promise<Result<Uint8Array, SignerError>>;
+    /**
+     * Destroy the manager and release all resources.
+     * After calling destroy(), the manager is unusable.
+     */
+    destroy(): void;
+    private connectToProvider;
+    private createProvider;
+    private handleProviderStatusChange;
+    private attemptReconnect;
+    /** Returns the underlying HostProvider if connected via host, or null otherwise. */
+    private getHostProvider;
+    private cancelConnect;
+    private cancelReconnect;
+    private disconnectInternal;
+    private persistAccount;
+    private loadPersistedAccount;
+    private setState;
+}
+
+/**
+ * Sleep for a given duration, cancellable via AbortSignal.
+ *
+ * Resolves immediately if the signal is already aborted.
+ * Cleans up the abort listener when the timer fires naturally
+ * to prevent listener accumulation in retry loops.
+ */
+declare function sleep(ms: number, signal?: AbortSignal): Promise<void>;
+
+/** Options for retry with exponential backoff. */
+interface RetryOptions {
+    /** Maximum number of attempts. Default: 3 */
+    maxAttempts?: number;
+    /** Initial delay in ms before first retry. Default: 500 */
+    initialDelay?: number;
+    /** Multiplier applied to delay after each attempt. Default: 2 */
+    backoffMultiplier?: number;
+    /** Maximum delay cap in ms. Default: 10_000 */
+    maxDelay?: number;
+    /** AbortSignal to cancel retries early. */
+    signal?: AbortSignal;
+}
+/**
+ * Retry an async operation with exponential backoff.
+ *
+ * Calls `fn` up to `maxAttempts` times. If `fn` returns an error result,
+ * waits with exponential backoff before the next attempt. Returns the first
+ * successful result or the last error.
+ */
+declare function withRetry<T, E>(fn: (attempt: number) => Promise<Result<T, E>>, options?: RetryOptions): Promise<Result<T, E>>;
+
+/** Standard Substrate dev account names. */
+declare const DEFAULT_DEV_NAMES: readonly ["Alice", "Bob", "Charlie", "Dave", "Eve", "Ferdie"];
+type DevAccountName = (typeof DEFAULT_DEV_NAMES)[number];
+/** Supported key types for dev account derivation. */
+type DevKeyType = "sr25519" | "ed25519";
+/** Options for the dev account provider. */
+interface DevProviderOptions {
+    /** Which dev accounts to create. Default: all 6 standard accounts. */
+    names?: readonly string[];
+    /** Custom mnemonic phrase instead of DEV_PHRASE. */
+    mnemonic?: string;
+    /** SS58 prefix for address encoding. Default: 42 */
+    ss58Prefix?: number;
+    /** Key type for account derivation. Default: "sr25519" */
+    keyType?: DevKeyType;
+}
+/**
+ * Provider for Substrate development accounts.
+ *
+ * Uses the well-known DEV_PHRASE with hard derivation paths (`//Alice`, `//Bob`, etc.)
+ * to create deterministic accounts for local development and testing.
+ */
+declare class DevProvider implements SignerProvider {
+    readonly type: "dev";
+    private readonly names;
+    private readonly mnemonic;
+    private readonly ss58Prefix;
+    private readonly keyType;
+    constructor(options?: DevProviderOptions);
+    connect(): Promise<Result<SignerAccount[], SignerError>>;
+    disconnect(): void;
+    onStatusChange(_callback: (status: "disconnected" | "connecting" | "connected") => void): Unsubscribe;
+    onAccountsChange(_callback: (accounts: SignerAccount[]) => void): Unsubscribe;
+}
+
+export { AccountNotFoundError, type AccountPersistence, type ConnectionStatus, type ContextualAlias, DestroyedError, type DevAccountName, type DevKeyType, DevProvider, type DevProviderOptions, HostDisconnectedError, HostProvider, type HostProviderOptions, HostRejectedError, HostUnavailableError, NoAccountsError, type ProductAccount, type ProviderFactory, type ProviderType, type Result, type RetryOptions, type RingLocation, type SignerAccount, SignerError, SignerManager, type SignerManagerOptions, type SignerProvider, type SignerState, SigningFailedError, TimeoutError, type Unsubscribe, err, isHostError, ok, sleep, withRetry };