@polkadot-apps/tx 0.2.5 → 0.2.6

package/README.md

@@ -0,0 +1,259 @@
+# @polkadot-apps/tx
+
+Transaction submission, lifecycle watching, and dev signers for Polkadot chains.
+
+## Install
+
+```bash
+pnpm add @polkadot-apps/tx
+```
+
+**Peer dependency**: `polkadot-api` must be installed in your project.
+
+```bash
+pnpm add polkadot-api
+```
+
+## Quick start
+
+```typescript
+import { submitAndWatch, createDevSigner } from "@polkadot-apps/tx";
+
+const signer = createDevSigner("Alice");
+
+const result = await submitAndWatch(tx, signer, {
+  waitFor: "finalized",
+  onStatus: (status) => console.log(status),
+});
+
+console.log(result.txHash, result.ok);
+```
+
+## Transaction lifecycle
+
+`submitAndWatch` drives a transaction through its full lifecycle: signing, broadcasting, block inclusion, and optional finalization. You choose when to resolve the returned promise with the `waitFor` option.
+
+```typescript
+import { submitAndWatch } from "@polkadot-apps/tx";
+
+const result = await submitAndWatch(tx, signer, {
+  waitFor: "best-block",   // resolve at best-block inclusion (default)
+  timeoutMs: 300_000,      // 5-minute timeout (default)
+  mortalityPeriod: 256,    // ~43 minutes on Polkadot (default)
+  onStatus: (status) => {
+    // "signing" -> "broadcasting" -> "in-block" -> "finalized"
+    updateUI(status);
+  },
+});
+
+if (!result.ok) {
+  console.error("Dispatch failed:", result.dispatchError);
+}
+```
+
+The function accepts both raw PAPI transactions and Ink SDK `AsyncTransaction` wrappers. Ink SDK wrappers are resolved automatically via the `.waited` promise.
+
+## Dev signers
+
+Create signers from the well-known Substrate dev mnemonic for local testing. All keys derive at `//Name` using sr25519.
+
+```typescript
+import { createDevSigner, getDevPublicKey } from "@polkadot-apps/tx";
+
+const alice = createDevSigner("Alice");
+const bobPubKey = getDevPublicKey("Bob"); // Uint8Array (32 bytes)
+```
+
+Available names: `"Alice"`, `"Bob"`, `"Charlie"`, `"Dave"`, `"Eve"`, `"Ferdie"`.
+
+## Dry-run and weight buffers
+
+Extract a submittable transaction from an Ink SDK dry-run result and apply a safety buffer to weight estimates before submission.
+
+```typescript
+import { extractTransaction, applyWeightBuffer } from "@polkadot-apps/tx";
+
+const dryRunResult = await contract.query.myMethod(args);
+const tx = extractTransaction(dryRunResult);
+
+const buffered = applyWeightBuffer(dryRunResult.weight_required, {
+  bufferPercent: 25, // default: 25%
+});
+```
+
+## Account mapping
+
+Map an SS58 address to an H160 address on Asset Hub. The operation is idempotent -- it returns `null` when the account is already mapped.
+
+```typescript
+import { ensureAccountMapped, isAccountMapped } from "@polkadot-apps/tx";
+
+const mapped = await isAccountMapped(address, checker);
+
+if (!mapped) {
+  const result = await ensureAccountMapped(address, signer, checker, api);
+  // result is TxResult or null (if already mapped)
+}
+```
+
+## Retry logic
+
+`withRetry` wraps any async function with exponential backoff and jitter. It does **not** retry `TxDispatchError`, `TxSigningRejectedError`, or `TxTimeoutError` -- these represent terminal conditions that retrying cannot fix.
+
+```typescript
+import { withRetry, calculateDelay } from "@polkadot-apps/tx";
+
+const result = await withRetry(() => submitAndWatch(tx, signer), {
+  maxAttempts: 3,     // total attempts including the first (default)
+  baseDelayMs: 1_000, // initial backoff (default)
+  maxDelayMs: 15_000, // backoff cap (default)
+});
+
+// Calculate delay directly for custom retry strategies
+const delay = calculateDelay(2, 1_000, 15_000);
+```
+
+## Error handling
+
+All errors extend a common `TxError` base class. Use the specific error types and utility functions to handle failures precisely.
+
+```typescript
+import {
+  TxTimeoutError,
+  TxDispatchError,
+  TxSigningRejectedError,
+  TxDryRunError,
+  TxAccountMappingError,
+  formatDispatchError,
+  formatDryRunError,
+  isSigningRejection,
+} from "@polkadot-apps/tx";
+
+try {
+  await submitAndWatch(tx, signer);
+} catch (error) {
+  if (isSigningRejection(error)) {
+    console.log("User cancelled signing");
+  } else if (error instanceof TxDispatchError) {
+    console.error(error.formatted, error.dispatchError);
+  } else if (error instanceof TxTimeoutError) {
+    console.error(`Timed out after ${error.timeoutMs}ms`);
+  } else if (error instanceof TxDryRunError) {
+    console.error(error.formatted, error.revertReason);
+  }
+}
+```
+
+## API
+
+### `submitAndWatch(tx, signer, options?): Promise<TxResult>`
+
+Submit a transaction and watch its lifecycle through to inclusion or finalization.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `tx` | `SubmittableTransaction` | Transaction with `signSubmitAndWatch`. Raw PAPI or Ink SDK. |
+| `signer` | `PolkadotSigner` | Signer from a wallet, Host API, or `createDevSigner`. |
+| `options` | `SubmitOptions` | Optional. See below. |
+
+**Throws**: `TxTimeoutError`, `TxDispatchError`, `TxSigningRejectedError`.
+
+### `createDevSigner(name): PolkadotSigner`
+
+Create a signer from the well-known dev mnemonic at `//Name` (sr25519).
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `name` | `DevAccountName` | One of `"Alice"`, `"Bob"`, `"Charlie"`, `"Dave"`, `"Eve"`, `"Ferdie"`. |
+
+### `getDevPublicKey(name): Uint8Array`
+
+Return the 32-byte public key for a dev account.
+
+### `withRetry<T>(fn, options?): Promise<T>`
+
+Retry an async function with exponential backoff and jitter. Does not retry `TxDispatchError`, `TxSigningRejectedError`, or `TxTimeoutError`.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `fn` | `() => Promise<T>` | Async function to retry. |
+| `options` | `RetryOptions` | Optional retry configuration. |
+
+### `calculateDelay(attempt, baseDelayMs, maxDelayMs): number`
+
+Compute the backoff delay for a given attempt number, with jitter.
+
+### `extractTransaction(result): SubmittableTransaction`
+
+Extract a submittable transaction from an Ink SDK dry-run result.
+
+### `applyWeightBuffer(weight, options?): Weight`
+
+Apply a percentage safety buffer to a weight estimate. Default buffer is 25%.
+
+### `ensureAccountMapped(address, signer, checker, api, options?): Promise<TxResult | null>`
+
+Map an SS58 address to H160 on Asset Hub. Returns `null` if the account is already mapped.
+
+### `isAccountMapped(address, checker): Promise<boolean>`
+
+Check whether an SS58 address is already mapped to an H160 address.
+
+### Error utilities
+
+| Function | Signature | Description |
+|----------|-----------|-------------|
+| `formatDispatchError` | `(result) => string` | Format a dispatch error into a readable string. |
+| `formatDryRunError` | `(result) => string` | Format a dry-run error into a readable string. |
+| `isSigningRejection` | `(error) => boolean` | Check if an error is a signing rejection. |
+
+## Types
+
+```typescript
+type TxStatus = "signing" | "broadcasting" | "in-block" | "finalized" | "error";
+
+type WaitFor = "best-block" | "finalized";
+
+interface TxResult {
+  txHash: string;
+  ok: boolean;
+  block: { hash: string; number: number; index: number };
+  events: unknown[];
+  dispatchError?: unknown;
+}
+
+interface SubmitOptions {
+  waitFor?: WaitFor;          // default: "best-block"
+  timeoutMs?: number;         // default: 300_000
+  mortalityPeriod?: number;   // default: 256
+  onStatus?: (status: TxStatus) => void;
+}
+
+interface RetryOptions {
+  maxAttempts?: number;   // default: 3
+  baseDelayMs?: number;   // default: 1_000
+  maxDelayMs?: number;    // default: 15_000
+}
+
+type DevAccountName = "Alice" | "Bob" | "Charlie" | "Dave" | "Eve" | "Ferdie";
+
+interface Weight {
+  ref_time: bigint;
+  proof_size: bigint;
+}
+```
+
+### Error classes
+
+| Class | Extends | Key properties |
+|-------|---------|---------------|
+| `TxError` | `Error` | Base class for all tx errors. |
+| `TxTimeoutError` | `TxError` | `timeoutMs: number` |
+| `TxDispatchError` | `TxError` | `dispatchError: unknown`, `formatted: string` |
+| `TxSigningRejectedError` | `TxError` | User rejected signing. |
+| `TxDryRunError` | `TxError` | `raw: unknown`, `formatted: string`, `revertReason?: string` |
+| `TxAccountMappingError` | `TxError` | Account mapping failed. |
+
+## License
+
+Apache-2.0

package/package.json

@@ -1,6 +1,7 @@
 {
   "name": "@polkadot-apps/tx",
-  "version": "0.2.5",
+  "description": "Transaction submission, lifecycle watching, and dev signers for Polkadot chains",
+  "version": "0.2.6",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -19,8 +20,8 @@
   "dependencies": {
     "polkadot-api": "^1.23.3",
     "@polkadot-labs/hdkd-helpers": "^0.0.27",
-    "@polkadot-apps/keys": "0.3.2",
-    "@polkadot-apps/logger": "0.1.3"
+    "@polkadot-apps/keys": "0.3.3",
+    "@polkadot-apps/logger": "0.1.4"
   },
   "devDependencies": {
     "typescript": "^5.9.3"