Utility (Native API example)

Send extrinsics as a batch, and decode a batch error. Reference: utility pallet.

Copied from Futureverse’s futureversecom/trn-examples, deleted with its GitHub organisation, at commit 44c9e16 of 2024-10-31. Apache-2.0: license. Before you run it, read Running the examples.

Offline destinations

Some places this page points to did not answer when last checked:

• docs-beta.therootnetwork.com — does not resolve (checked 2026-10-18)
• stackblitz.com/github/futureversecom — StackBlitz loads these projects from the deleted futureversecom organisation on GitHub (checked 2026-10-18)

Run in StackBlitz (repository deleted, checked 2026-10-18) · Pallet Documentation (offline, checked 2026-10-18)

IMPORTANT

Ensure the following ENV vars are available before running the examples

• CALLER_PRIVATE_KEY - Private key of an account that submits the transaction. Follow this guide to create and fund an account with some test tokens on Porcini (testnet) if you don't have one yet.

Examples

# change your working directory to this example first
cd examples/substrate/use-utility

# export all required environments
export CALLER_PRIVATE_KEY=

# use `utility.batch` to dispatch a group of extrinsic
pnpm call:batchExtrinsics

# use `registry.findMetaError` to decode batch error
pnpm call:decodeBatchError

Source files

src/batchExtrinsics.ts

import { filterExtrinsicEvents } from "@trne/utils/filterExtrinsicEvents";
import { formatEventData } from "@trne/utils/formatEventData";
import { sendExtrinsic } from "@trne/utils/sendExtrinsic";
import { withChainApi } from "@trne/utils/withChainApi";

/**
 * Use `utility.batch` extrinsic to dispatch a group of extrinsics, potentially saving gas cost.
 *
 * Assumes the caller has XRP to pay for gas.
 */
withChainApi("porcini", async (api, caller, logger) => {
	const calls = new Array(10).fill(1).map((n, i) => api.tx.system.remark(`Call ${n + i}`));

	logger.info(
		{
			parameters: [...calls],
		},
		`create a "utility.batch" extrinsic`
	);
	const extrinsic = api.tx.utility.batch(calls);

	logger.info(`dispatch extrinsic from caller="${caller.address}"`);
	const { result, extrinsicId } = await sendExtrinsic(extrinsic, caller, { log: logger });
	const [batchEvent] = filterExtrinsicEvents(result.events, ["Utility.BatchCompleted"]);

	logger.info(
		{
			result: {
				extrinsicId,
				blockNumber: result.blockNumber,
				batchEvent: formatEventData(batchEvent.event),
			},
		},
		"receive result"
	);
});

src/decodeBatchError.ts

import { BN, hexToU8a } from "@polkadot/util";
import { filterExtrinsicEvents } from "@trne/utils/filterExtrinsicEvents";
import { formatEventData } from "@trne/utils/formatEventData";
import { sendExtrinsic } from "@trne/utils/sendExtrinsic";
import { withChainApi } from "@trne/utils/withChainApi";

/**
 * Use `utility.batch` extrinsic to dispatch a group of extrinsics with one set to failed
 * deliberately to demostrate how to extract and decode the error.
 *
 * Assumes the caller has XRP to pay for gas.
 */
withChainApi("porcini", async (api, caller, logger) => {
	const calls = new Array(10).fill(1).map((n, i) => {
		// Force error as Asset ID 3 does not exist
		if (i === 6) return api.tx.assets.transfer(3, caller.address, 1);
		return api.tx.system.remark(`Call ${n + i}`);
	});

	logger.info(
		{
			parameters: [...calls],
		},
		`create a "utility.batch" extrinsic`
	);
	const extrinsic = api.tx.utility.batch(calls);

	logger.info(`dispatch extrinsic from caller="${caller.address}"`);
	const { result, extrinsicId } = await sendExtrinsic(extrinsic, caller, { log: logger });
	const [interrupptedEvent] = filterExtrinsicEvents(result.events, ["Utility.BatchInterrupted"]);

	const {
		event: {
			data: [index, err],
		},
	} = interrupptedEvent.toJSON() as {
		event: {
			data: [
				number,
				{
					module: {
						index: number;
						error: `0x${string}`;
					};
				}
			];
		};
	};

	const { section, name, docs } = api.registry.findMetaError({
		index: new BN(err.module.index),
		error: hexToU8a(err.module.error),
	});

	logger.info(
		{
			error: {
				index,
				code: `${section}.${name}`,
				docs,
			},
		},
		`batch interrupted`
	);

	logger.info(
		{
			result: {
				extrinsicId,
				blockNumber: result.blockNumber,
				interrupptedEvent: formatEventData(interrupptedEvent.event),
			},
		},
		"receive result"
	);
});

package.json

{
  "scripts": {
    "call": "tsx --tsconfig ../../../tsconfig.json",
    "call:batchExtrinsics": "pnpm call src/batchExtrinsics.ts",
    "call:decodeBatchError": "pnpm call src/decodeBatchError.ts"
  },
  "dependencies": {
    "@polkadot/util": "^12.3.2"
  }
}

Source: futureversecom/trn-examples, examples/substrate/use-utility (deleted) · commit 44c9e16, 2024-10-31 · Apache-2.0, license · part of Code examples