@parity/product-sdk-tx 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,538 @@
+import { PolkadotSigner } from 'polkadot-api';
+
+/** Transaction lifecycle status for UI callbacks. */
+type TxStatus = "signing" | "broadcasting" | "in-block" | "finalized" | "error";
+/** When to resolve the submission promise. */
+type WaitFor = "best-block" | "finalized";
+/** Successful transaction result. */
+interface TxResult {
+    /** Transaction hash. */
+    txHash: string;
+    /** Whether the on-chain dispatch succeeded. */
+    ok: boolean;
+    /** Block where the transaction was included. */
+    block: {
+        hash: string;
+        number: number;
+        index: number;
+    };
+    /** Raw events emitted by the transaction. */
+    events: unknown[];
+    /** Dispatch error details when ok is false. */
+    dispatchError?: unknown;
+}
+/** Options for {@link submitAndWatch}. */
+interface SubmitOptions {
+    /** When to resolve the promise. Default: `"best-block"`. */
+    waitFor?: WaitFor;
+    /** Timeout in milliseconds. Default: `300_000` (5 minutes). */
+    timeoutMs?: number;
+    /** Mortality period in blocks. Default: `256` (~43 minutes on Polkadot). */
+    mortalityPeriod?: number;
+    /** Called on each lifecycle transition for UI progress indicators. */
+    onStatus?: (status: TxStatus) => void;
+}
+/** Options for {@link withRetry}. */
+interface RetryOptions {
+    /** Total attempts including the first. Default: `3`. */
+    maxAttempts?: number;
+    /** Base delay in ms for exponential backoff. Default: `1_000`. */
+    baseDelayMs?: number;
+    /** Maximum delay in ms. Default: `15_000`. */
+    maxDelayMs?: number;
+}
+/**
+ * Substrate weight representing computational and storage resources.
+ *
+ * Matches the shape returned by `ReviveApi.call` and `ReviveApi.eth_transact`
+ * dry-run results in the `weight_required` field.
+ */
+interface Weight {
+    /** Reference time component in picoseconds. */
+    ref_time: bigint;
+    /** Proof size component in bytes. */
+    proof_size: bigint;
+}
+/** Standard Substrate dev account names. */
+type DevAccountName = "Alice" | "Bob" | "Charlie" | "Dave" | "Eve" | "Ferdie";
+/**
+ * Structural type for any transaction object that supports Observable-based
+ * sign-submit-and-watch. Works with raw PAPI transactions and Ink SDK
+ * resolved transactions.
+ */
+interface SubmittableTransaction {
+    signSubmitAndWatch: (signer: PolkadotSigner, options?: {
+        mortality?: {
+            mortal: boolean;
+            period: number;
+        };
+    }) => {
+        subscribe: (handlers: {
+            next: (event: TxEvent) => void;
+            error: (error: Error) => void;
+        }) => {
+            unsubscribe: () => void;
+        };
+    };
+    /** Present on Ink SDK AsyncTransaction wrappers. */
+    waited?: Promise<SubmittableTransaction>;
+    /** The decoded call data. Present on PAPI transactions. */
+    decodedCall?: unknown;
+}
+/** Batch execution mode corresponding to Substrate's Utility pallet. */
+type BatchMode = "batch_all" | "batch" | "force_batch";
+/**
+ * A transaction or decoded call that can be included in a batch.
+ *
+ * Accepts:
+ * - A {@link SubmittableTransaction} (has `.decodedCall`)
+ * - An Ink SDK AsyncTransaction (has `.waited` that resolves to one with `.decodedCall`)
+ * - A raw decoded call object (passed through as `Record<string, unknown>`)
+ *
+ * The `Record<string, unknown>` variant is intentionally broad because PAPI decoded
+ * calls are chain-specific enum types that cannot be imported without chain descriptors.
+ * Runtime validation in `resolveDecodedCall` rejects null, undefined, and primitives.
+ */
+type BatchableCall = SubmittableTransaction | {
+    decodedCall: unknown;
+} | Record<string, unknown>;
+/** Options for {@link batchSubmitAndWatch}. Extends {@link SubmitOptions} with batch mode. */
+interface BatchSubmitOptions extends SubmitOptions {
+    /**
+     * Batch execution mode. Default: `"batch_all"` (atomic, all-or-nothing).
+     *
+     * - `"batch_all"` — Atomic. Reverts all calls if any single call fails.
+     * - `"batch"` — Best-effort. Stops at first failure but earlier successful calls are not reverted.
+     * - `"force_batch"` — Like `batch` but continues executing remaining calls after failures (never aborts early).
+     */
+    mode?: BatchMode;
+}
+/**
+ * Minimal structural type for a PAPI typed API with the Utility pallet.
+ *
+ * Structural so it works with any chain that has the Utility pallet, without
+ * importing chain-specific descriptors.
+ */
+interface BatchApi {
+    tx: {
+        Utility: {
+            batch(args: {
+                calls: unknown[];
+            }): SubmittableTransaction;
+            batch_all(args: {
+                calls: unknown[];
+            }): SubmittableTransaction;
+            force_batch(args: {
+                calls: unknown[];
+            }): SubmittableTransaction;
+        };
+    };
+}
+/** PAPI transaction event (discriminated union). */
+type TxEvent = {
+    type: "signed";
+    txHash: string;
+} | {
+    type: "broadcasted";
+    txHash: string;
+} | {
+    type: "txBestBlocksState";
+    txHash: string;
+    found: boolean;
+    ok?: boolean;
+    events?: unknown[];
+    block?: {
+        hash: string;
+        number: number;
+        index: number;
+    };
+    dispatchError?: unknown;
+} | {
+    type: "finalized";
+    txHash: string;
+    ok: boolean;
+    events: unknown[];
+    block: {
+        hash: string;
+        number: number;
+        index: number;
+    };
+    dispatchError?: unknown;
+};
+
+/**
+ * Submit a transaction and watch its lifecycle through signing, broadcasting,
+ * block inclusion, and (optionally) finalization.
+ *
+ * @param tx - A transaction object with `signSubmitAndWatch`. Works with raw PAPI
+ *   transactions and Ink SDK `AsyncTransaction` wrappers (resolved automatically).
+ * @param signer - The signer to use. Can come from a wallet extension, Host API
+ *   (`getProductAccountSigner`), or {@link createDevSigner}.
+ * @param options - Submission options (waitFor, timeout, mortality, status callback).
+ * @returns The transaction result once included/finalized.
+ *
+ * @throws {TxTimeoutError} If the transaction does not reach the target state within `timeoutMs`.
+ * @throws {TxDispatchError} If the on-chain dispatch fails (e.g., insufficient balance, contract revert).
+ * @throws {TxSigningRejectedError} If the user rejects signing in their wallet.
+ */
+declare function submitAndWatch(tx: SubmittableTransaction, signer: PolkadotSigner, options?: SubmitOptions): Promise<TxResult>;
+
+/**
+ * Batch multiple transactions into a single Substrate Utility batch and submit.
+ *
+ * Extracts `.decodedCall` from each transaction (handling Ink SDK `AsyncTransaction`
+ * wrappers), wraps them in `Utility.batch_all` (or `batch`/`force_batch` via the
+ * `mode` option), and submits via {@link submitAndWatch} with full lifecycle tracking.
+ *
+ * @param calls - Array of transactions, AsyncTransactions, or raw decoded calls to batch.
+ * @param api - A typed API with `tx.Utility.batch_all/batch/force_batch`. Works with any
+ *   chain that has the Utility pallet — no chain-specific imports required.
+ *   **All calls must target the same chain as this API.** Do not mix decoded calls
+ *   from different chains (e.g., Asset Hub and Bulletin) in a single batch.
+ * @param signer - The signer to use. Can come from a wallet extension, Host API
+ *   (`getProductAccountSigner`), or {@link createDevSigner}.
+ * @param options - Optional {@link BatchSubmitOptions} (extends `SubmitOptions` with `mode`).
+ * @returns The transaction result from the batch submission.
+ *
+ * @throws {TxBatchError} If `calls` is empty.
+ * @throws {TxBatchError} If an AsyncTransaction resolves without a `.decodedCall` property.
+ * @throws {TxTimeoutError} If the batch transaction does not reach the target state within `timeoutMs`.
+ * @throws {TxDispatchError} If the on-chain dispatch fails.
+ * @throws {TxSigningRejectedError} If the user rejects signing in their wallet.
+ *
+ * @example
+ * ```ts
+ * import { batchSubmitAndWatch } from "@parity/product-sdk-tx";
+ *
+ * const tx1 = api.tx.Balances.transfer_keep_alive({ dest: addr1, value: 1_000n });
+ * const tx2 = api.tx.Balances.transfer_keep_alive({ dest: addr2, value: 2_000n });
+ *
+ * const result = await batchSubmitAndWatch([tx1, tx2], api, signer, {
+ *   onStatus: (status) => console.log(status),
+ * });
+ * ```
+ */
+declare function batchSubmitAndWatch(calls: BatchableCall[], api: BatchApi, signer: PolkadotSigner, options?: BatchSubmitOptions): Promise<TxResult>;
+
+/**
+ * Calculate delay with exponential backoff and jitter.
+ *
+ * Jitter prevents thundering-herd when multiple clients retry simultaneously.
+ * The delay is `min(baseDelay * 2^attempt, maxDelay) * random(0.5, 1.0)`.
+ */
+declare function calculateDelay(attempt: number, baseDelayMs: number, maxDelayMs: number): number;
+/**
+ * Wrap an async function with retry logic and exponential backoff.
+ *
+ * Only retries transient errors (network disconnects, temporary RPC failures).
+ * Deterministic errors ({@link TxDispatchError}, {@link TxBatchError}), user
+ * rejections ({@link TxSigningRejectedError}), and timeouts ({@link TxTimeoutError})
+ * are rethrown immediately without retry.
+ *
+ * @param fn - The async function to retry.
+ * @param options - Retry configuration.
+ * @returns The result of the first successful call.
+ *
+ * @example
+ * ```ts
+ * const result = await withRetry(
+ *     () => submitAndWatch(tx, signer),
+ *     { maxAttempts: 3, baseDelayMs: 1_000 },
+ * );
+ * ```
+ */
+declare function withRetry<T>(fn: () => Promise<T>, options?: RetryOptions): Promise<T>;
+
+/**
+ * Create a PolkadotSigner for a standard Substrate dev account.
+ *
+ * Dev accounts use the well-known Substrate dev mnemonic (`DEV_PHRASE`) with
+ * Sr25519 key derivation at the path `//{Name}`. These accounts have known
+ * private keys and are pre-funded on dev/test chains.
+ *
+ * Only for local development, scripts, and testing. Never use in production.
+ *
+ * @param name - Dev account name ("Alice", "Bob", "Charlie", "Dave", "Eve", or "Ferdie").
+ * @returns A PolkadotSigner that can sign transactions.
+ *
+ * @example
+ * ```ts
+ * import { createDevSigner } from "@parity/product-sdk-tx";
+ *
+ * const alice = createDevSigner("Alice");
+ * const result = await submitAndWatch(tx, alice);
+ * ```
+ */
+declare function createDevSigner(name: DevAccountName): PolkadotSigner;
+/**
+ * Get the public key bytes for a dev account.
+ *
+ * Useful for address derivation or identity checks in tests without
+ * needing the full signer.
+ *
+ * @param name - Dev account name.
+ * @returns 32-byte Sr25519 public key.
+ */
+declare function getDevPublicKey(name: DevAccountName): Uint8Array;
+
+/**
+ * Validate an Ink SDK dry-run result and extract the submittable transaction.
+ *
+ * Replaces the 5-10 line boilerplate that every contract interaction repeats:
+ * check `success`, parse the error, verify `send()` exists, and call it.
+ *
+ * Works with any object whose shape matches the Ink SDK contract query result
+ * (typed structurally — no Ink SDK import required):
+ *
+ * - `contract.query("method", { origin, data })` (Ink SDK)
+ * - `contract.write("method", args, origin)` (patched SDK wrappers)
+ * - Any object with `{ success: boolean; value?: { send?(): ... } }`
+ *
+ * @param result - The dry-run result from a contract query or write simulation.
+ * @returns The submittable transaction, ready to pass to {@link submitAndWatch}.
+ * @throws {TxDryRunError} If the dry run failed or the result has no `send()`.
+ *
+ * @example
+ * ```ts
+ * import { extractTransaction, submitAndWatch, createDevSigner } from "@parity/product-sdk-tx";
+ *
+ * const dryRun = await contract.query("createItem", { origin, data: { name, price } });
+ * const tx = extractTransaction(dryRun);
+ * const result = await submitAndWatch(tx, createDevSigner("Alice"));
+ * ```
+ *
+ * @example Composing with retry logic:
+ * ```ts
+ * const tx = extractTransaction(await contract.query("transfer", { origin, data }));
+ * const result = await withRetry(() => submitAndWatch(tx, signer));
+ * ```
+ */
+declare function extractTransaction(result: {
+    success: boolean;
+    value?: unknown;
+    error?: unknown;
+}): SubmittableTransaction;
+/**
+ * Apply a safety buffer to weight estimates from a dry-run result.
+ *
+ * Dry-run weight estimates reflect the exact execution cost at the time of
+ * simulation. On-chain conditions can change between dry-run and actual
+ * submission (storage growth, state changes by other transactions), so a
+ * buffer prevents unexpected `OutOfGas` failures.
+ *
+ * The default 25% buffer matches the convention used across Polkadot
+ * ecosystem tooling.
+ *
+ * @param weight - The `weight_required` from a `ReviveApi.call` or `ReviveApi.eth_transact` dry-run.
+ * @param options - Override the buffer percentage (default: 25%).
+ * @returns A new weight with both components scaled up.
+ *
+ * @example Basic usage with ReviveApi dry-run:
+ * ```ts
+ * const dryRun = await api.apis.ReviveApi.call(origin, dest, value, undefined, undefined, data);
+ *
+ * const tx = api.tx.Revive.call({
+ *   dest, value, data,
+ *   weight_limit: applyWeightBuffer(dryRun.weight_required),
+ *   storage_deposit_limit: dryRun.storage_deposit.value,
+ * });
+ * ```
+ *
+ * @example Custom buffer for latency-sensitive operations:
+ * ```ts
+ * applyWeightBuffer(dryRun.weight_required, { percent: 50 });
+ * ```
+ */
+declare function applyWeightBuffer(weight: Weight, options?: {
+    percent?: number;
+}): Weight;
+
+/**
+ * Error thrown when account mapping fails.
+ */
+declare class TxAccountMappingError extends Error {
+    constructor(message: string, options?: ErrorOptions);
+}
+/**
+ * Minimal interface for checking if an address is mapped on-chain.
+ *
+ * The Ink SDK's `createInkSdk(client)` returns an object with this method.
+ * We accept it structurally to avoid importing `@polkadot-api/sdk-ink`.
+ */
+interface MappingChecker {
+    addressIsMapped(address: string): Promise<boolean>;
+}
+/**
+ * Minimal typed API shape for `Revive.map_account()`.
+ *
+ * Accepted structurally so this module works with any PAPI typed API
+ * that has the Revive pallet, without importing chain-specific descriptors.
+ */
+interface ReviveApi {
+    tx: {
+        Revive: {
+            map_account(): SubmittableTransaction;
+        };
+    };
+}
+/** Options for {@link ensureAccountMapped}. */
+interface EnsureAccountMappedOptions {
+    /** Timeout in ms for the map_account transaction. Default: 60_000 (1 minute). */
+    timeoutMs?: number;
+    /** Called on mapping transaction status changes. */
+    onStatus?: (status: "checking" | "mapping" | "mapped" | "already-mapped") => void;
+}
+/**
+ * Ensure an account's SS58 address is mapped to its H160 EVM address on-chain.
+ *
+ * Account mapping is a prerequisite for any EVM contract interaction on Asset Hub.
+ * This function checks the on-chain mapping status and, if unmapped, submits a
+ * `Revive.map_account()` transaction and waits for inclusion.
+ *
+ * Idempotent — safe to call multiple times. Returns immediately if already mapped.
+ *
+ * @param address - The SS58 address to check/map.
+ * @param signer - The signer for the account (must match the address).
+ * @param checker - An object with `addressIsMapped()` (e.g., from `createInkSdk(client)`).
+ * @param api - A typed API with `tx.Revive.map_account()`.
+ * @param options - Optional timeout and status callback.
+ * @returns The transaction result if mapping was performed, or `null` if already mapped.
+ *
+ * @throws {TxAccountMappingError} If the mapping check or transaction fails.
+ * @throws {TxDispatchError} If the map_account transaction fails on-chain.
+ * @throws {TxTimeoutError} If the mapping transaction times out.
+ *
+ * @example
+ * ```ts
+ * import { ensureAccountMapped } from "@parity/product-sdk-tx";
+ * import { createInkSdk } from "@polkadot-api/sdk-ink";
+ *
+ * const inkSdk = createInkSdk(client);
+ * const api = client.getTypedApi(descriptor);
+ *
+ * await ensureAccountMapped(address, signer, inkSdk, api);
+ * // Account is now mapped — safe to call EVM contracts
+ * ```
+ */
+declare function ensureAccountMapped(address: string, signer: PolkadotSigner, checker: MappingChecker, api: ReviveApi, options?: EnsureAccountMappedOptions): Promise<TxResult | null>;
+/**
+ * Check if an address is mapped on-chain.
+ *
+ * Convenience wrapper around `checker.addressIsMapped()` with error handling.
+ */
+declare function isAccountMapped(address: string, checker: MappingChecker): Promise<boolean>;
+
+/** Base class for all transaction errors. Use `instanceof TxError` to catch any tx-related error. */
+declare class TxError extends Error {
+    constructor(message: string, options?: ErrorOptions);
+}
+/** The transaction did not finalize within the configured timeout. It may still be processing on-chain. */
+declare class TxTimeoutError extends TxError {
+    readonly timeoutMs: number;
+    constructor(timeoutMs: number);
+}
+/** The transaction was included on-chain but the dispatch failed. */
+declare class TxDispatchError extends TxError {
+    /** Raw dispatch error from polkadot-api. */
+    readonly dispatchError: unknown;
+    /** Human-readable error string (e.g., "Revive.ContractReverted"). */
+    readonly formatted: string;
+    constructor(dispatchError: unknown, formatted: string);
+}
+/** The user rejected the signing request in their wallet. */
+declare class TxSigningRejectedError extends TxError {
+    constructor();
+}
+/**
+ * Extract a human-readable error from a transaction result's dispatch error.
+ *
+ * PAPI dispatch errors for pallet modules are nested:
+ *   `{ type: "Module", value: { type: "Revive", value: { type: "ContractReverted" } } }`
+ *
+ * This walks the chain to build a string like `"Revive.ContractReverted"`.
+ *
+ * @param result - A transaction result with `ok` and optional `dispatchError`.
+ * @returns A human-readable error string, or `""` if the result is ok, or `"unknown error"` if
+ *   the dispatch error cannot be decoded.
+ */
+declare function formatDispatchError(result: {
+    ok: boolean;
+    dispatchError?: unknown;
+}): string;
+/** Error specific to batch transaction construction (e.g., empty calls array). */
+declare class TxBatchError extends TxError {
+    constructor(message: string);
+}
+/**
+ * A dry-run simulation failed before the transaction was submitted on-chain.
+ *
+ * Thrown by {@link extractTransaction} when the dry-run result indicates failure.
+ * Carries structured error information so callers can distinguish revert reasons
+ * from dispatch errors programmatically.
+ *
+ * @example
+ * ```ts
+ * try {
+ *   const tx = extractTransaction(await contract.query("mint", { origin, data }));
+ * } catch (e) {
+ *   if (e instanceof TxDryRunError) {
+ *     console.log(e.revertReason); // "InsufficientBalance" (if contract provided one)
+ *     console.log(e.formatted);    // "Revive.StorageDepositNotEnoughFunds"
+ *   }
+ * }
+ * ```
+ */
+declare class TxDryRunError extends TxError {
+    /** The raw dry-run result for programmatic inspection. */
+    readonly raw: unknown;
+    /** Human-readable error string derived from the dry-run result. */
+    readonly formatted: string;
+    /** Solidity revert reason, if the contract provided one. */
+    readonly revertReason?: string;
+    constructor(raw: unknown, formatted: string, revertReason?: string);
+}
+/**
+ * Extract a human-readable error from a failed dry-run result.
+ *
+ * Handles every error shape found across the Polkadot contract ecosystem:
+ *
+ * 1. **Revert reason** (Ink SDK patched results / EVM contracts):
+ *    `{ value: { revertReason: "InsufficientBalance" } }`
+ *
+ * 2. **Nested dispatch errors** (raw Ink SDK / pallet errors):
+ *    `{ value: { type: "Module", value: { type: "Revive", value: { type: "StorageDepositNotEnoughFunds" } } } }`
+ *    Delegates to {@link formatDispatchError} for the Module.Pallet.Error chain.
+ *
+ * 3. **ReviveApi runtime messages** (`eth_transact` / `ReviveApi.call`):
+ *    `{ value: { type: "Message", value: "Insufficient balance for gas * price + value" } }`
+ *
+ * 4. **ReviveApi contract revert data**:
+ *    `{ value: { type: "Data", value: "0x08c379a0..." } }`
+ *
+ * 5. **Wrapped raw errors** (patched SDK wrappers):
+ *    `{ value: { raw: { type: "Message", value: "..." } } }`
+ *
+ * 6. **Generic error field**:
+ *    `{ error: { type: "ContractTrapped" } }` or `{ error: { name: "..." } }`
+ *
+ * @param result - A dry-run result with at least `success`, and optionally `value` / `error`.
+ * @returns A human-readable error string, or `""` if the result succeeded.
+ */
+declare function formatDryRunError(result: {
+    success?: boolean;
+    value?: unknown;
+    error?: unknown;
+}): string;
+/**
+ * Check if an error looks like a user-rejected signing request.
+ *
+ * Different wallets use different error messages when the user rejects signing:
+ * "Cancelled", "Rejected", "User rejected", "denied". This checks for common
+ * patterns as a best-effort heuristic. Non-Error values always return false.
+ *
+ * @param error - The error to check.
+ * @returns `true` if the error message matches a known rejection pattern.
+ */
+declare function isSigningRejection(error: unknown): boolean;
+
+export { type BatchApi, type BatchMode, type BatchSubmitOptions, type BatchableCall, type DevAccountName, type EnsureAccountMappedOptions, type MappingChecker, type RetryOptions, type ReviveApi, type SubmitOptions, type SubmittableTransaction, TxAccountMappingError, TxBatchError, TxDispatchError, TxDryRunError, TxError, type TxEvent, type TxResult, TxSigningRejectedError, type TxStatus, TxTimeoutError, type WaitFor, type Weight, applyWeightBuffer, batchSubmitAndWatch, calculateDelay, createDevSigner, ensureAccountMapped, extractTransaction, formatDispatchError, formatDryRunError, getDevPublicKey, isAccountMapped, isSigningRejection, submitAndWatch, withRetry };