@polkadot-apps/tx 0.2.12 → 0.3.0

package/README.md

@@ -29,6 +29,49 @@ const result = await submitAndWatch(tx, signer, {
 console.log(result.txHash, result.ok);
 ```
 
+## Batch transactions
+
+Submit multiple transactions as a single atomic batch. Uses Substrate's `Utility.batch_all` by default (all-or-nothing).
+
+```typescript
+import { batchSubmitAndWatch } from "@polkadot-apps/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 tx3 = api.tx.System.remark({ remark: Binary.fromText("hello") });
+
+const result = await batchSubmitAndWatch([tx1, tx2, tx3], api, signer, {
+  onStatus: (status) => console.log(status),
+});
+```
+
+Three batch modes are available:
+
+| Mode | Behavior |
+|------|----------|
+| `"batch_all"` (default) | 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 after failures (never aborts early). |
+
+```typescript
+// Non-atomic: some calls may fail while others succeed
+const result = await batchSubmitAndWatch(calls, api, signer, { mode: "batch" });
+```
+
+> **WARNING:** In `"batch"` and `"force_batch"` modes, `result.ok` is `true` even when individual calls fail. Inspect `result.events` for `Utility.ItemFailed` events to detect individual failures. Only `"batch_all"` guarantees that `result.ok === false` when any call fails.
+
+Calls can be PAPI transactions (`.decodedCall` extracted automatically), Ink SDK `AsyncTransaction` wrappers (`.waited` resolved automatically), or raw decoded calls.
+
+```typescript
+// Mix of raw decoded calls and transactions
+const calls = [
+  api.tx.Balances.transfer_keep_alive({ dest, value: 1_000n }),     // PAPI tx
+  extractTransaction(await contract.query("mint", { origin, data })), // Ink SDK
+  someDecodedCallObject,                                              // raw
+];
+const result = await batchSubmitAndWatch(calls, api, signer);
+```
+
 ## 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.
@@ -77,7 +120,7 @@ const dryRunResult = await contract.query.myMethod(args);
 const tx = extractTransaction(dryRunResult);
 
 const buffered = applyWeightBuffer(dryRunResult.weight_required, {
-  bufferPercent: 25, // default: 25%
+  percent: 25, // default: 25%
 });
 ```
 
@@ -98,7 +141,7 @@ if (!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.
+`withRetry` wraps any async function with exponential backoff and jitter. It does **not** retry `TxDispatchError`, `TxBatchError`, `TxSigningRejectedError`, or `TxTimeoutError` -- these represent terminal conditions that retrying cannot fix.
 
 ```typescript
 import { withRetry, calculateDelay } from "@polkadot-apps/tx";
@@ -158,6 +201,19 @@ Submit a transaction and watch its lifecycle through to inclusion or finalizatio
 
 **Throws**: `TxTimeoutError`, `TxDispatchError`, `TxSigningRejectedError`.
 
+### `batchSubmitAndWatch(calls, api, signer, options?): Promise<TxResult>`
+
+Batch multiple transactions into a single Substrate Utility batch and submit with lifecycle tracking.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `calls` | `BatchableCall[]` | Transactions, AsyncTransactions, or raw decoded calls. |
+| `api` | `BatchApi` | Typed API with `tx.Utility.batch_all/batch/force_batch`. |
+| `signer` | `PolkadotSigner` | Signer from a wallet, Host API, or `createDevSigner`. |
+| `options` | `BatchSubmitOptions` | Optional. Extends `SubmitOptions` with `mode`. |
+
+**Throws**: `TxBatchError` (empty calls), `TxTimeoutError`, `TxDispatchError`, `TxSigningRejectedError`.
+
 ### `createDevSigner(name): PolkadotSigner`
 
 Create a signer from the well-known dev mnemonic at `//Name` (sr25519).
@@ -172,7 +228,7 @@ 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`.
+Retry an async function with exponential backoff and jitter. Does not retry `TxBatchError`, `TxDispatchError`, `TxSigningRejectedError`, or `TxTimeoutError`.
 
 | Parameter | Type | Description |
 |-----------|------|-------------|
@@ -241,6 +297,22 @@ interface Weight {
   ref_time: bigint;
   proof_size: bigint;
 }
+
+type BatchMode = "batch_all" | "batch" | "force_batch";
+
+interface BatchSubmitOptions extends SubmitOptions {
+  mode?: BatchMode;  // default: "batch_all"
+}
+
+interface BatchApi {
+  tx: {
+    Utility: {
+      batch(args: { calls: unknown[] }): SubmittableTransaction;
+      batch_all(args: { calls: unknown[] }): SubmittableTransaction;
+      force_batch(args: { calls: unknown[] }): SubmittableTransaction;
+    };
+  };
+}
 ```
 
 ### Error classes
@@ -252,6 +324,7 @@ interface Weight {
 | `TxDispatchError` | `TxError` | `dispatchError: unknown`, `formatted: string` |
 | `TxSigningRejectedError` | `TxError` | User rejected signing. |
 | `TxDryRunError` | `TxError` | `raw: unknown`, `formatted: string`, `revertReason?: string` |
+| `TxBatchError` | `TxError` | Batch construction failed (e.g., empty calls). |
 | `TxAccountMappingError` | `TxError` | Account mapping failed. |
 
 ## License

package/dist/batch.d.ts

@@ -0,0 +1,38 @@
+import type { PolkadotSigner } from "polkadot-api";
+import type { BatchApi, BatchSubmitOptions, BatchableCall, TxResult } from "./types.js";
+/**
+ * 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 "@polkadot-apps/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),
+ * });
+ * ```
+ */
+export declare function batchSubmitAndWatch(calls: BatchableCall[], api: BatchApi, signer: PolkadotSigner, options?: BatchSubmitOptions): Promise<TxResult>;

package/dist/batch.js

@@ -0,0 +1,313 @@
+import { createLogger } from "@polkadot-apps/logger";
+import { TxBatchError } from "./errors.js";
+import { submitAndWatch } from "./submit.js";
+const log = createLogger("tx:batch");
+/**
+ * Resolve a single call to its decoded call data.
+ *
+ * Handles three shapes:
+ * 1. Ink SDK AsyncTransaction — has `.waited` Promise that resolves to a tx with `.decodedCall`
+ * 2. PAPI transaction or object with `.decodedCall` — extract directly
+ * 3. Raw decoded call — pass through as-is
+ */
+async function resolveDecodedCall(call) {
+    if (call != null && typeof call === "object") {
+        const obj = call;
+        // Handle Ink SDK AsyncTransaction: resolve .waited first
+        if ("waited" in obj &&
+            obj.waited &&
+            typeof obj.waited.then === "function") {
+            log.debug("Resolving Ink SDK AsyncTransaction in batch");
+            const resolved = (await obj.waited);
+            if (resolved.decodedCall !== undefined)
+                return resolved.decodedCall;
+            throw new TxBatchError("Resolved AsyncTransaction has no decodedCall property");
+        }
+        // Handle SubmittableTransaction or object with decodedCall
+        if ("decodedCall" in obj && obj.decodedCall !== undefined) {
+            return obj.decodedCall;
+        }
+    }
+    // Reject null, undefined, and primitives — they will cause cryptic codec errors on-chain
+    if (call == null || typeof call !== "object") {
+        throw new TxBatchError(`Invalid batch call: expected a transaction or decoded call object, got ${call === null ? "null" : typeof call}`);
+    }
+    // Raw decoded call object — pass through
+    return call;
+}
+/**
+ * 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 "@polkadot-apps/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),
+ * });
+ * ```
+ */
+export async function batchSubmitAndWatch(calls, api, signer, options) {
+    if (calls.length === 0) {
+        throw new TxBatchError("Cannot batch zero calls");
+    }
+    const mode = options?.mode ?? "batch_all";
+    log.info("Resolving batch calls", { count: calls.length, mode });
+    const decodedCalls = await Promise.all(calls.map(resolveDecodedCall));
+    log.info("Constructing batch transaction", { mode, callCount: decodedCalls.length });
+    const batchTx = api.tx.Utility[mode]({ calls: decodedCalls });
+    return submitAndWatch(batchTx, signer, options);
+}
+if (import.meta.vitest) {
+    const { describe, test, expect, vi, beforeEach } = import.meta.vitest;
+    const { configure } = await import("@polkadot-apps/logger");
+    const { TxDispatchError, TxSigningRejectedError } = await import("./errors.js");
+    // Silence logger during tests
+    beforeEach(() => {
+        configure({ handler: () => { } });
+    });
+    function createMockTx(emitFn, decodedCall) {
+        return {
+            signSubmitAndWatch: (_signer, _options) => ({
+                subscribe: (handlers) => {
+                    const unsub = vi.fn();
+                    queueMicrotask(() => emitFn(handlers));
+                    return { unsubscribe: unsub };
+                },
+            }),
+            decodedCall,
+        };
+    }
+    const mockSigner = {};
+    const signedEvent = { type: "signed", txHash: "0xbatch" };
+    const bestBlockOk = {
+        type: "txBestBlocksState",
+        txHash: "0xbatch",
+        found: true,
+        ok: true,
+        events: [{ id: 1 }],
+        block: { hash: "0xblock1", number: 100, index: 0 },
+    };
+    function createMockBatchApi(emitFn) {
+        const capturedCalls = [];
+        const api = {
+            tx: {
+                Utility: {
+                    batch: vi.fn((args) => {
+                        capturedCalls.push(args.calls);
+                        return createMockTx(emitFn);
+                    }),
+                    batch_all: vi.fn((args) => {
+                        capturedCalls.push(args.calls);
+                        return createMockTx(emitFn);
+                    }),
+                    force_batch: vi.fn((args) => {
+                        capturedCalls.push(args.calls);
+                        return createMockTx(emitFn);
+                    }),
+                },
+            },
+        };
+        return { api, getCapturedCalls: () => capturedCalls };
+    }
+    const successEmit = (h) => {
+        h.next(signedEvent);
+        h.next(bestBlockOk);
+    };
+    describe("batchSubmitAndWatch", () => {
+        test("batches multiple transactions with decodedCall", async () => {
+            const { api, getCapturedCalls } = createMockBatchApi(successEmit);
+            const calls = [
+                { decodedCall: { pallet: "Balances", method: "transfer", args: { value: 1 } } },
+                { decodedCall: { pallet: "Balances", method: "transfer", args: { value: 2 } } },
+            ];
+            const result = await batchSubmitAndWatch(calls, api, mockSigner);
+            expect(result.ok).toBe(true);
+            expect(getCapturedCalls()).toHaveLength(1);
+            expect(getCapturedCalls()[0]).toEqual([
+                { pallet: "Balances", method: "transfer", args: { value: 1 } },
+                { pallet: "Balances", method: "transfer", args: { value: 2 } },
+            ]);
+            expect(api.tx.Utility.batch_all).toHaveBeenCalledOnce();
+        });
+        test("handles Ink SDK AsyncTransaction wrappers", async () => {
+            const { api, getCapturedCalls } = createMockBatchApi(successEmit);
+            const asyncCall = {
+                waited: Promise.resolve({ decodedCall: { pallet: "Contracts", method: "call" } }),
+                signSubmitAndWatch: () => {
+                    throw new Error("Should not be called");
+                },
+            };
+            const result = await batchSubmitAndWatch([asyncCall], api, mockSigner);
+            expect(result.ok).toBe(true);
+            expect(getCapturedCalls()[0]).toEqual([{ pallet: "Contracts", method: "call" }]);
+        });
+        test("accepts raw decoded calls (pass-through)", async () => {
+            const { api, getCapturedCalls } = createMockBatchApi(successEmit);
+            const rawCall = { pallet: "System", method: "remark" };
+            const result = await batchSubmitAndWatch([rawCall], api, mockSigner);
+            expect(result.ok).toBe(true);
+            expect(getCapturedCalls()[0]).toEqual([{ pallet: "System", method: "remark" }]);
+        });
+        test("mixes transaction types in a single batch", async () => {
+            const { api, getCapturedCalls } = createMockBatchApi(successEmit);
+            const txWithDecoded = { decodedCall: "call1" };
+            const asyncTx = {
+                waited: Promise.resolve({ decodedCall: "call2" }),
+                signSubmitAndWatch: () => {
+                    throw new Error("Should not be called");
+                },
+            };
+            const rawCall = { pallet: "System", method: "remark" };
+            const result = await batchSubmitAndWatch([txWithDecoded, asyncTx, rawCall], api, mockSigner);
+            expect(result.ok).toBe(true);
+            expect(getCapturedCalls()[0]).toEqual([
+                "call1",
+                "call2",
+                { pallet: "System", method: "remark" },
+            ]);
+        });
+        test("throws TxBatchError for empty calls array", async () => {
+            const { api } = createMockBatchApi(successEmit);
+            await expect(batchSubmitAndWatch([], api, mockSigner)).rejects.toThrow(TxBatchError);
+            await expect(batchSubmitAndWatch([], api, mockSigner)).rejects.toThrow("Cannot batch zero calls");
+        });
+        test("throws TxBatchError when AsyncTransaction resolves without decodedCall", async () => {
+            const { api } = createMockBatchApi(successEmit);
+            const badAsync = {
+                waited: Promise.resolve({ noDecodedCall: true }),
+                signSubmitAndWatch: () => {
+                    throw new Error("Should not be called");
+                },
+            };
+            await expect(batchSubmitAndWatch([badAsync], api, mockSigner)).rejects.toThrow(TxBatchError);
+        });
+        test("throws TxBatchError for null call", async () => {
+            const { api } = createMockBatchApi(successEmit);
+            await expect(batchSubmitAndWatch([null], api, mockSigner)).rejects.toThrow(TxBatchError);
+            await expect(batchSubmitAndWatch([null], api, mockSigner)).rejects.toThrow("Invalid batch call");
+        });
+        test("throws TxBatchError for primitive call", async () => {
+            const { api } = createMockBatchApi(successEmit);
+            await expect(batchSubmitAndWatch([42], api, mockSigner)).rejects.toThrow(TxBatchError);
+            await expect(batchSubmitAndWatch(["oops"], api, mockSigner)).rejects.toThrow("Invalid batch call");
+        });
+        test("treats { decodedCall: undefined } as raw pass-through object", async () => {
+            const { api, getCapturedCalls } = createMockBatchApi(successEmit);
+            const edgeCase = { decodedCall: undefined, other: "data" };
+            const result = await batchSubmitAndWatch([edgeCase], api, mockSigner);
+            expect(result.ok).toBe(true);
+            // decodedCall is undefined so it falls through to raw pass-through
+            expect(getCapturedCalls()[0]).toEqual([{ decodedCall: undefined, other: "data" }]);
+        });
+        test("defaults to batch_all mode", async () => {
+            const { api } = createMockBatchApi(successEmit);
+            await batchSubmitAndWatch([{ decodedCall: "call1" }], api, mockSigner);
+            expect(api.tx.Utility.batch_all).toHaveBeenCalledOnce();
+            expect(api.tx.Utility.batch).not.toHaveBeenCalled();
+            expect(api.tx.Utility.force_batch).not.toHaveBeenCalled();
+        });
+        test("respects mode: batch", async () => {
+            const { api } = createMockBatchApi(successEmit);
+            await batchSubmitAndWatch([{ decodedCall: "call1" }], api, mockSigner, {
+                mode: "batch",
+            });
+            expect(api.tx.Utility.batch).toHaveBeenCalledOnce();
+            expect(api.tx.Utility.batch_all).not.toHaveBeenCalled();
+        });
+        test("respects mode: force_batch", async () => {
+            const { api } = createMockBatchApi(successEmit);
+            await batchSubmitAndWatch([{ decodedCall: "call1" }], api, mockSigner, {
+                mode: "force_batch",
+            });
+            expect(api.tx.Utility.force_batch).toHaveBeenCalledOnce();
+            expect(api.tx.Utility.batch_all).not.toHaveBeenCalled();
+        });
+        test("forwards SubmitOptions to submitAndWatch", async () => {
+            const statuses = [];
+            const { api } = createMockBatchApi(successEmit);
+            await batchSubmitAndWatch([{ decodedCall: "call1" }], api, mockSigner, {
+                onStatus: (s) => statuses.push(s),
+            });
+            expect(statuses).toContain("signing");
+            expect(statuses).toContain("in-block");
+        });
+        test("propagates TxDispatchError", async () => {
+            const { api } = createMockBatchApi((h) => {
+                h.next(signedEvent);
+                h.next({
+                    type: "txBestBlocksState",
+                    txHash: "0xbatch",
+                    found: true,
+                    ok: false,
+                    events: [],
+                    block: { hash: "0xblock1", number: 100, index: 0 },
+                    dispatchError: {
+                        type: "Module",
+                        value: { type: "Utility", value: { type: "TooManyCalls" } },
+                    },
+                });
+            });
+            await expect(batchSubmitAndWatch([{ decodedCall: "call1" }], api, mockSigner)).rejects.toThrow(TxDispatchError);
+        });
+        test("propagates TxSigningRejectedError", async () => {
+            const { api } = createMockBatchApi((h) => {
+                h.error(new Error("User rejected the request"));
+            });
+            await expect(batchSubmitAndWatch([{ decodedCall: "call1" }], api, mockSigner)).rejects.toThrow(TxSigningRejectedError);
+        });
+        test("resolves all calls in parallel", async () => {
+            const { api } = createMockBatchApi(successEmit);
+            const resolveOrder = [];
+            const asyncCall1 = {
+                waited: new Promise((resolve) => {
+                    setTimeout(() => {
+                        resolveOrder.push(1);
+                        resolve({ decodedCall: "call1" });
+                    }, 10);
+                }),
+                signSubmitAndWatch: () => {
+                    throw new Error("Should not be called");
+                },
+            };
+            const asyncCall2 = {
+                waited: new Promise((resolve) => {
+                    setTimeout(() => {
+                        resolveOrder.push(2);
+                        resolve({ decodedCall: "call2" });
+                    }, 5); // Resolves faster
+                }),
+                signSubmitAndWatch: () => {
+                    throw new Error("Should not be called");
+                },
+            };
+            await batchSubmitAndWatch([asyncCall1, asyncCall2], api, mockSigner);
+            // Both should have resolved (order depends on timing, but both are present)
+            expect(resolveOrder).toContain(1);
+            expect(resolveOrder).toContain(2);
+        });
+    });
+}

package/dist/errors.d.ts

@@ -35,6 +35,10 @@ export declare function formatDispatchError(result: {
     ok: boolean;
     dispatchError?: unknown;
 }): string;
+/** Error specific to batch transaction construction (e.g., empty calls array). */
+export declare class TxBatchError extends TxError {
+    constructor(message: string);
+}
 /**
  * A dry-run simulation failed before the transaction was submitted on-chain.
  *

package/dist/errors.js

@@ -71,6 +71,13 @@ export function formatDispatchError(result) {
         return "unknown error";
     }
 }
+/** Error specific to batch transaction construction (e.g., empty calls array). */
+export class TxBatchError extends TxError {
+    constructor(message) {
+        super(message);
+        this.name = "TxBatchError";
+    }
+}
 /**
  * A dry-run simulation failed before the transaction was submitted on-chain.
  *
@@ -238,6 +245,13 @@ if (import.meta.vitest) {
             expect(err).toBeInstanceOf(TxError);
             expect(err.name).toBe("TxSigningRejectedError");
         });
+        test("TxBatchError", () => {
+            const err = new TxBatchError("Cannot batch zero calls");
+            expect(err).toBeInstanceOf(TxError);
+            expect(err).toBeInstanceOf(Error);
+            expect(err.name).toBe("TxBatchError");
+            expect(err.message).toBe("Cannot batch zero calls");
+        });
     });
     describe("formatDispatchError", () => {
         test("returns empty string for ok result", () => {

package/dist/index.d.ts

@@ -1,8 +1,9 @@
 export { submitAndWatch } from "./submit.js";
+export { batchSubmitAndWatch } from "./batch.js";
 export { withRetry, calculateDelay } from "./retry.js";
 export { createDevSigner, getDevPublicKey } from "./dev-signers.js";
 export { extractTransaction, applyWeightBuffer } from "./dry-run.js";
 export { ensureAccountMapped, isAccountMapped, TxAccountMappingError } from "./account-mapping.js";
 export type { MappingChecker, ReviveApi, EnsureAccountMappedOptions, } from "./account-mapping.js";
-export { TxError, TxTimeoutError, TxDispatchError, TxDryRunError, TxSigningRejectedError, formatDispatchError, formatDryRunError, isSigningRejection, } from "./errors.js";
-export type { TxStatus, WaitFor, TxResult, SubmitOptions, RetryOptions, DevAccountName, Weight, SubmittableTransaction, TxEvent, } from "./types.js";
+export { TxError, TxTimeoutError, TxDispatchError, TxDryRunError, TxSigningRejectedError, TxBatchError, formatDispatchError, formatDryRunError, isSigningRejection, } from "./errors.js";
+export type { TxStatus, WaitFor, TxResult, SubmitOptions, RetryOptions, DevAccountName, Weight, SubmittableTransaction, TxEvent, BatchMode, BatchableCall, BatchSubmitOptions, BatchApi, } from "./types.js";

package/dist/index.js

@@ -1,6 +1,7 @@
 export { submitAndWatch } from "./submit.js";
+export { batchSubmitAndWatch } from "./batch.js";
 export { withRetry, calculateDelay } from "./retry.js";
 export { createDevSigner, getDevPublicKey } from "./dev-signers.js";
 export { extractTransaction, applyWeightBuffer } from "./dry-run.js";
 export { ensureAccountMapped, isAccountMapped, TxAccountMappingError } from "./account-mapping.js";
-export { TxError, TxTimeoutError, TxDispatchError, TxDryRunError, TxSigningRejectedError, formatDispatchError, formatDryRunError, isSigningRejection, } from "./errors.js";
+export { TxError, TxTimeoutError, TxDispatchError, TxDryRunError, TxSigningRejectedError, TxBatchError, formatDispatchError, formatDryRunError, isSigningRejection, } from "./errors.js";

package/dist/retry.d.ts

@@ -10,9 +10,9 @@ export declare function calculateDelay(attempt: number, baseDelayMs: number, max
  * Wrap an async function with retry logic and exponential backoff.
  *
  * Only retries transient errors (network disconnects, temporary RPC failures).
- * Deterministic errors ({@link TxDispatchError}), user rejections
- * ({@link TxSigningRejectedError}), and timeouts ({@link TxTimeoutError}) are
- * rethrown immediately without retry.
+ * 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.

package/dist/retry.js

@@ -1,5 +1,5 @@
 import { createLogger } from "@polkadot-apps/logger";
-import { TxDispatchError, TxSigningRejectedError, TxTimeoutError } from "./errors.js";
+import { TxBatchError, TxDispatchError, TxSigningRejectedError, TxTimeoutError } from "./errors.js";
 const log = createLogger("tx:retry");
 function sleep(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));
@@ -7,13 +7,15 @@ function sleep(ms) {
 /**
  * Whether an error is deterministic and should not be retried.
  *
+ * - Batch errors are deterministic input validation failures (e.g., empty calls array).
  * - Dispatch errors are on-chain failures (e.g., insufficient balance) that will
  *   produce the same result on retry.
  * - Signing rejections are explicit user intent.
  * - Timeouts mean we already waited the full duration; retrying would double the wait.
  */
 function isNonRetryable(error) {
-    return (error instanceof TxDispatchError ||
+    return (error instanceof TxBatchError ||
+        error instanceof TxDispatchError ||
         error instanceof TxSigningRejectedError ||
         error instanceof TxTimeoutError);
 }
@@ -32,9 +34,9 @@ export function calculateDelay(attempt, baseDelayMs, maxDelayMs) {
  * Wrap an async function with retry logic and exponential backoff.
  *
  * Only retries transient errors (network disconnects, temporary RPC failures).
- * Deterministic errors ({@link TxDispatchError}), user rejections
- * ({@link TxSigningRejectedError}), and timeouts ({@link TxTimeoutError}) are
- * rethrown immediately without retry.
+ * 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.
@@ -121,6 +123,14 @@ if (import.meta.vitest) {
             }, { maxAttempts: 3, baseDelayMs: 1 })).rejects.toThrow(TxSigningRejectedError);
             expect(calls).toBe(1);
         });
+        test("does NOT retry TxBatchError", async () => {
+            let calls = 0;
+            await expect(withRetry(() => {
+                calls++;
+                return Promise.reject(new TxBatchError("Cannot batch zero calls"));
+            }, { maxAttempts: 3, baseDelayMs: 1 })).rejects.toThrow(TxBatchError);
+            expect(calls).toBe(1);
+        });
         test("does NOT retry TxTimeoutError", async () => {
             let calls = 0;
             await expect(withRetry(() => {

package/dist/types.d.ts

@@ -75,6 +75,57 @@ export interface SubmittableTransaction {
     };
     /** 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. */
+export 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.
+ */
+export type BatchableCall = SubmittableTransaction | {
+    decodedCall: unknown;
+} | Record<string, unknown>;
+/** Options for {@link batchSubmitAndWatch}. Extends {@link SubmitOptions} with batch mode. */
+export 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.
+ */
+export 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). */
 export type TxEvent = {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@polkadot-apps/tx",
   "description": "Transaction submission, lifecycle watching, and dev signers for Polkadot chains",
-  "version": "0.2.12",
+  "version": "0.3.0",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",