@polkadot-apps/utils 0.2.1 → 0.4.0

package/README.md

@@ -23,6 +23,23 @@ const text = utf8ToBytes("hello"); // Uint8Array [104, 101, 108, 108, 111]
 const combined = concatBytes(header, payload);
 ```
 
+### Hashing
+
+Deterministic 32-byte hash functions used across the Polkadot ecosystem.
+
+```typescript
+import { blake2b256, sha256, keccak256, bytesToHex } from "@polkadot-apps/utils";
+
+const hash = blake2b256(new TextEncoder().encode("hello"));
+console.log(bytesToHex(hash)); // 64-char hex string
+
+// SHA2-256 (bulletin-deploy default)
+const sha = sha256(data);
+
+// Keccak-256 (Ethereum compatibility)
+const kek = keccak256(data);
+```
+
 ### Token formatting
 
 Convert between raw planck values (the smallest indivisible token unit on Substrate chains) and human-readable decimal strings.
@@ -45,6 +62,37 @@ formatPlanck(1_000_000_000_000n, 12); // "1.0"
 parseToPlanck("1.0", 12);             // 1_000_000_000_000n
 ```
 
+### Display formatting
+
+Format planck values for display with locale-aware thousand separators, configurable decimal precision, and optional token symbol.
+
+```typescript
+import { formatBalance } from "@polkadot-apps/utils";
+
+formatBalance(10_000_000_000n);                              // "1"
+formatBalance(15_000_000_000n, { symbol: "DOT" });           // "1.5 DOT"
+formatBalance(10_000_000_000_000n, { symbol: "DOT" });       // "1,000 DOT"
+formatBalance(12_345_678_900n, { maxDecimals: 2 });          // "1.23"
+formatBalance(0n, { symbol: "DOT" });                        // "0 DOT"
+
+// Custom chain decimals and locale
+formatBalance(1_000_000_000_000n, { decimals: 12, symbol: "KSM", locale: "de-DE" });
+```
+
+Unlike the `Number()` approach used in some apps, `formatBalance` preserves full BigInt precision for balances of any size.
+
+### Balance querying
+
+Query on-chain balances with a typed convenience wrapper. Works with any PAPI typed API via structural typing — no extra dependencies.
+
+```typescript
+import { getBalance, formatBalance } from "@polkadot-apps/utils";
+
+const balance = await getBalance(api.assetHub, aliceAddress);
+console.log(formatBalance(balance.free, { symbol: "DOT" }));       // "1,000.5 DOT"
+console.log(formatBalance(balance.reserved, { symbol: "DOT" }));   // "50 DOT"
+```
+
 ## API
 
 ### Encoding
@@ -56,12 +104,27 @@ parseToPlanck("1.0", 12);             // 1_000_000_000_000n
 | `utf8ToBytes` | `(str: string)` | `Uint8Array` |
 | `concatBytes` | `(...arrays: Uint8Array[])` | `Uint8Array` |
 
+### Hashing
+
+| Function | Signature | Returns | Description |
+|---|---|---|---|
+| `blake2b256` | `(data: Uint8Array)` | `Uint8Array` (32 bytes) | BLAKE2b-256 — Polkadot default |
+| `sha256` | `(data: Uint8Array)` | `Uint8Array` (32 bytes) | SHA2-256 — bulletin-deploy default |
+| `keccak256` | `(data: Uint8Array)` | `Uint8Array` (32 bytes) | Keccak-256 — Ethereum compatibility |
+
 ### Token formatting
 
 | Function | Signature | Returns |
 |---|---|---|
 | `formatPlanck` | `(planck: bigint, decimals?: number)` | `string` |
 | `parseToPlanck` | `(amount: string, decimals?: number)` | `bigint` |
+| `formatBalance` | `(planck: bigint, options?: FormatBalanceOptions)` | `string` |
+
+### Balance querying
+
+| Function | Signature | Returns |
+|---|---|---|
+| `getBalance` | `(api: BalanceApi, address: string)` | `Promise<AccountBalance>` |
 
 **`formatPlanck(planck, decimals = 10)`**
 
@@ -77,11 +140,25 @@ Parse a decimal string into its planck bigint representation. If the fractional
 - Throws `Error` if `amount` is empty or contains invalid characters.
 - Throws `RangeError` if `amount` is negative or `decimals` is invalid.
 
+**`formatBalance(planck, options?)`**
+
+Format a planck value for display with locale-aware thousand separators. Builds on `formatPlanck` for BigInt precision.
+
+Options: `{ decimals?: number, maxDecimals?: number, symbol?: string, locale?: string }`. Defaults: `decimals = 10`, `maxDecimals = 4`, no symbol, user's locale.
+
+- Throws `RangeError` if `planck < 0n` or `decimals` is invalid (delegated to `formatPlanck`).
+
+**`getBalance(api, address): Promise<AccountBalance>`**
+
+Query the free, reserved, and frozen balances for an address. Returns `{ free: bigint, reserved: bigint, frozen: bigint }`. Uses structural typing — works with any PAPI typed API that has `System.Account`.
+
 ## Common mistakes
 
 - **Passing a `0x`-prefixed string to `hexToBytes`.** The `@noble/hashes` implementation expects raw hex without a prefix. Strip it first: `hexToBytes(hex.slice(2))`.
 - **Using `formatPlanck` with the wrong `decimals` for a chain.** DOT uses 10, KSM uses 12, many parachains use 18. Always check the chain's token metadata.
 - **Assuming `parseToPlanck` rounds excess decimals.** It truncates, not rounds. `parseToPlanck("1.999999999999", 10)` gives the same result as `parseToPlanck("1.9999999999", 10)`.
+- **Using `Number()` to format large balances.** `Number(raw) / 10**decimals` loses precision for values > 2^53 planck (~900 DOT). Use `formatBalance` which preserves full BigInt precision.
+- **Passing the ChainAPI wrapper to `getBalance`.** Pass the chain-specific TypedApi (e.g., `api.assetHub`), not the multi-chain `ChainAPI` object.
 
 ## License
 

package/dist/balance.d.ts

@@ -0,0 +1,52 @@
+/** Balance breakdown from a Substrate `System.Account` query. */
+export interface AccountBalance {
+    /** Available (transferable) balance in planck. */
+    free: bigint;
+    /** Reserved (locked by governance, staking, etc.) balance in planck. */
+    reserved: bigint;
+    /** Frozen (non-transferable but still counted) balance in planck. */
+    frozen: bigint;
+}
+/**
+ * Minimal structural type for a PAPI typed API with `System.Account`.
+ *
+ * Structural so it works with any chain that has the System pallet, without
+ * importing chain-specific descriptors.
+ */
+export interface BalanceApi {
+    query: {
+        System: {
+            Account: {
+                getValue(address: string): Promise<{
+                    data: {
+                        free: bigint;
+                        reserved: bigint;
+                        frozen: bigint;
+                    };
+                }>;
+            };
+        };
+    };
+}
+/**
+ * Query the free, reserved, and frozen balances for an on-chain address.
+ *
+ * Thin typed wrapper around `System.Account.getValue` that returns a clean
+ * {@link AccountBalance} object. Uses structural typing so it works with any
+ * PAPI typed API that has the System pallet — no chain-specific imports needed.
+ *
+ * @param api - A PAPI typed API with `query.System.Account`. Pass the chain-specific
+ *   API (e.g., `api.assetHub`), not the multi-chain `ChainAPI` wrapper.
+ * @param address - The SS58 address to query.
+ * @returns The account's balance breakdown.
+ *
+ * @example
+ * ```ts
+ * import { getBalance } from "@polkadot-apps/utils";
+ * import { formatBalance } from "@polkadot-apps/utils";
+ *
+ * const balance = await getBalance(api.assetHub, aliceAddress);
+ * console.log(formatBalance(balance.free, { symbol: "DOT" })); // "1,000.5 DOT"
+ * ```
+ */
+export declare function getBalance(api: BalanceApi, address: string): Promise<AccountBalance>;

package/dist/balance.js

@@ -0,0 +1,77 @@
+/**
+ * Query the free, reserved, and frozen balances for an on-chain address.
+ *
+ * Thin typed wrapper around `System.Account.getValue` that returns a clean
+ * {@link AccountBalance} object. Uses structural typing so it works with any
+ * PAPI typed API that has the System pallet — no chain-specific imports needed.
+ *
+ * @param api - A PAPI typed API with `query.System.Account`. Pass the chain-specific
+ *   API (e.g., `api.assetHub`), not the multi-chain `ChainAPI` wrapper.
+ * @param address - The SS58 address to query.
+ * @returns The account's balance breakdown.
+ *
+ * @example
+ * ```ts
+ * import { getBalance } from "@polkadot-apps/utils";
+ * import { formatBalance } from "@polkadot-apps/utils";
+ *
+ * const balance = await getBalance(api.assetHub, aliceAddress);
+ * console.log(formatBalance(balance.free, { symbol: "DOT" })); // "1,000.5 DOT"
+ * ```
+ */
+export async function getBalance(api, address) {
+    const account = await api.query.System.Account.getValue(address);
+    return {
+        free: account.data.free,
+        reserved: account.data.reserved,
+        frozen: account.data.frozen,
+    };
+}
+if (import.meta.vitest) {
+    const { describe, test, expect } = import.meta.vitest;
+    function createMockApi(data) {
+        return {
+            query: {
+                System: {
+                    Account: {
+                        getValue: async () => ({ data }),
+                    },
+                },
+            },
+        };
+    }
+    describe("getBalance", () => {
+        test("returns correct AccountBalance from API", async () => {
+            const api = createMockApi({
+                free: 10000000000n,
+                reserved: 5000000000n,
+                frozen: 1000000000n,
+            });
+            const balance = await getBalance(api, "5GrwvaEF5zXb26Fz9rcQpDWS57CtERHpNehXCPcNoHGKutQY");
+            expect(balance.free).toBe(10000000000n);
+            expect(balance.reserved).toBe(5000000000n);
+            expect(balance.frozen).toBe(1000000000n);
+        });
+        test("propagates errors from getValue", async () => {
+            const api = {
+                query: {
+                    System: {
+                        Account: {
+                            getValue: async () => {
+                                throw new Error("RPC connection failed");
+                            },
+                        },
+                    },
+                },
+            };
+            await expect(getBalance(api, "5GrwvaEF...")).rejects.toThrow("RPC connection failed");
+        });
+        test("works with zero balances", async () => {
+            const api = createMockApi({ free: 0n, reserved: 0n, frozen: 0n });
+            const balance = await getBalance(api, "5GrwvaEF...");
+            expect(balance.free).toBe(0n);
+            expect(balance.reserved).toBe(0n);
+            expect(balance.frozen).toBe(0n);
+        });
+    });
+}

package/dist/hashing.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Compute a 32-byte BLAKE2b-256 hash.
+ *
+ * This is the default hash algorithm used by the Polkadot ecosystem and the
+ * Bulletin Chain. Deterministic: same input always produces the same output.
+ *
+ * @param data - Arbitrary bytes to hash.
+ * @returns 32-byte BLAKE2b-256 digest.
+ *
+ * @example
+ * ```ts
+ * import { blake2b256, bytesToHex } from "@polkadot-apps/utils";
+ *
+ * const hash = blake2b256(new TextEncoder().encode("hello"));
+ * console.log(bytesToHex(hash)); // 64-char hex string
+ * ```
+ */
+export declare function blake2b256(data: Uint8Array): Uint8Array;
+/**
+ * Compute a 32-byte SHA2-256 hash.
+ *
+ * Used by bulletin-deploy and supported by the Bulletin Chain as an
+ * alternative hashing algorithm.
+ *
+ * @param data - Arbitrary bytes to hash.
+ * @returns 32-byte SHA2-256 digest.
+ *
+ * @example
+ * ```ts
+ * import { sha256, bytesToHex } from "@polkadot-apps/utils";
+ *
+ * const hash = sha256(new TextEncoder().encode("hello"));
+ * console.log(bytesToHex(hash)); // 64-char hex string
+ * ```
+ */
+export declare function sha256(data: Uint8Array): Uint8Array;
+/**
+ * Compute a 32-byte Keccak-256 hash.
+ *
+ * Used for Ethereum-compatible operations (address derivation, EVM function
+ * selectors) and supported by the Bulletin Chain for cross-chain compatibility.
+ *
+ * @param data - Arbitrary bytes to hash.
+ * @returns 32-byte Keccak-256 digest.
+ *
+ * @example
+ * ```ts
+ * import { keccak256, bytesToHex } from "@polkadot-apps/utils";
+ *
+ * const hash = keccak256(new TextEncoder().encode("hello"));
+ * console.log(bytesToHex(hash)); // 64-char hex string
+ * ```
+ */
+export declare function keccak256(data: Uint8Array): Uint8Array;

package/dist/hashing.js

@@ -0,0 +1,149 @@
+import { blake2b } from "@noble/hashes/blake2.js";
+import { sha256 as _sha256 } from "@noble/hashes/sha2.js";
+import { bytesToHex as _bytesToHex } from "@noble/hashes/utils.js";
+import { keccak_256 } from "@noble/hashes/sha3.js";
+/**
+ * Compute a 32-byte BLAKE2b-256 hash.
+ *
+ * This is the default hash algorithm used by the Polkadot ecosystem and the
+ * Bulletin Chain. Deterministic: same input always produces the same output.
+ *
+ * @param data - Arbitrary bytes to hash.
+ * @returns 32-byte BLAKE2b-256 digest.
+ *
+ * @example
+ * ```ts
+ * import { blake2b256, bytesToHex } from "@polkadot-apps/utils";
+ *
+ * const hash = blake2b256(new TextEncoder().encode("hello"));
+ * console.log(bytesToHex(hash)); // 64-char hex string
+ * ```
+ */
+export function blake2b256(data) {
+    return blake2b(data, { dkLen: 32 });
+}
+/**
+ * Compute a 32-byte SHA2-256 hash.
+ *
+ * Used by bulletin-deploy and supported by the Bulletin Chain as an
+ * alternative hashing algorithm.
+ *
+ * @param data - Arbitrary bytes to hash.
+ * @returns 32-byte SHA2-256 digest.
+ *
+ * @example
+ * ```ts
+ * import { sha256, bytesToHex } from "@polkadot-apps/utils";
+ *
+ * const hash = sha256(new TextEncoder().encode("hello"));
+ * console.log(bytesToHex(hash)); // 64-char hex string
+ * ```
+ */
+export function sha256(data) {
+    return _sha256(data);
+}
+/**
+ * Compute a 32-byte Keccak-256 hash.
+ *
+ * Used for Ethereum-compatible operations (address derivation, EVM function
+ * selectors) and supported by the Bulletin Chain for cross-chain compatibility.
+ *
+ * @param data - Arbitrary bytes to hash.
+ * @returns 32-byte Keccak-256 digest.
+ *
+ * @example
+ * ```ts
+ * import { keccak256, bytesToHex } from "@polkadot-apps/utils";
+ *
+ * const hash = keccak256(new TextEncoder().encode("hello"));
+ * console.log(bytesToHex(hash)); // 64-char hex string
+ * ```
+ */
+export function keccak256(data) {
+    return keccak_256(data);
+}
+if (import.meta.vitest) {
+    const { describe, test, expect } = import.meta.vitest;
+    describe("blake2b256", () => {
+        test("produces a 32-byte hash", () => {
+            const hash = blake2b256(new TextEncoder().encode("hello"));
+            expect(hash).toBeInstanceOf(Uint8Array);
+            expect(hash.length).toBe(32);
+        });
+        test("deterministic — same input, same output", () => {
+            const data = new TextEncoder().encode("test");
+            expect(blake2b256(data)).toEqual(blake2b256(data));
+        });
+        test("different inputs produce different hashes", () => {
+            const a = blake2b256(new Uint8Array([1]));
+            const b = blake2b256(new Uint8Array([2]));
+            expect(a).not.toEqual(b);
+        });
+        test("empty input produces valid 32-byte hash", () => {
+            const hash = blake2b256(new Uint8Array(0));
+            expect(hash.length).toBe(32);
+        });
+        test("matches direct @noble/hashes import", () => {
+            const data = new TextEncoder().encode("wrapper transparency check");
+            const direct = blake2b(data, { dkLen: 32 });
+            expect(blake2b256(data)).toEqual(direct);
+        });
+    });
+    describe("sha256", () => {
+        test("produces a 32-byte hash", () => {
+            const hash = sha256(new TextEncoder().encode("hello"));
+            expect(hash).toBeInstanceOf(Uint8Array);
+            expect(hash.length).toBe(32);
+        });
+        test("deterministic — same input, same output", () => {
+            const data = new TextEncoder().encode("test");
+            expect(sha256(data)).toEqual(sha256(data));
+        });
+        test("different inputs produce different hashes", () => {
+            const a = sha256(new Uint8Array([1]));
+            const b = sha256(new Uint8Array([2]));
+            expect(a).not.toEqual(b);
+        });
+        test("empty input produces valid 32-byte hash", () => {
+            const hash = sha256(new Uint8Array(0));
+            expect(hash.length).toBe(32);
+        });
+        test("differs from blake2b256 for same input", () => {
+            const data = new TextEncoder().encode("cross-check");
+            expect(sha256(data)).not.toEqual(blake2b256(data));
+        });
+        test("matches known SHA-256 test vector", () => {
+            const hash = sha256(new TextEncoder().encode("hello"));
+            expect(_bytesToHex(hash)).toBe("2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824");
+        });
+    });
+    describe("keccak256", () => {
+        test("produces a 32-byte hash", () => {
+            const hash = keccak256(new TextEncoder().encode("hello"));
+            expect(hash).toBeInstanceOf(Uint8Array);
+            expect(hash.length).toBe(32);
+        });
+        test("deterministic — same input, same output", () => {
+            const data = new TextEncoder().encode("test");
+            expect(keccak256(data)).toEqual(keccak256(data));
+        });
+        test("different inputs produce different hashes", () => {
+            const a = keccak256(new Uint8Array([1]));
+            const b = keccak256(new Uint8Array([2]));
+            expect(a).not.toEqual(b);
+        });
+        test("empty input produces valid 32-byte hash", () => {
+            const hash = keccak256(new Uint8Array(0));
+            expect(hash.length).toBe(32);
+        });
+        test("differs from sha256 and blake2b256 for same input", () => {
+            const data = new TextEncoder().encode("cross-check");
+            expect(keccak256(data)).not.toEqual(sha256(data));
+            expect(keccak256(data)).not.toEqual(blake2b256(data));
+        });
+        test("matches known Keccak-256 test vector", () => {
+            const hash = keccak256(new TextEncoder().encode("hello"));
+            expect(_bytesToHex(hash)).toBe("1c8aff950685c2ed4bc3174f3472287b56d9517b9c948127319a09a7a36deac8");
+        });
+    });
+}

package/dist/index.d.ts

@@ -1,11 +1,15 @@
 /**
- * @polkadot-apps/utils — Encoding utilities and token formatting for the Polkadot app ecosystem.
+ * @polkadot-apps/utils — Encoding, hashing, token formatting, and balance querying for the Polkadot app ecosystem.
  *
  * Provides general-purpose byte encoding/decoding (`bytesToHex`, `hexToBytes`, `utf8ToBytes`,
- * `concatBytes`) and Substrate token formatting (`formatPlanck`, `parseToPlanck`).
- * All functions are synchronous and framework-agnostic.
+ * `concatBytes`), 32-byte hash functions (`blake2b256`, `sha256`, `keccak256`),
+ * Substrate token formatting (`formatPlanck`, `parseToPlanck`, `formatBalance`),
+ * and typed balance queries (`getBalance`).
+ * All functions are framework-agnostic.
  *
  * @packageDocumentation
  */
 export * from "./encoding.js";
+export * from "./hashing.js";
 export * from "./planck.js";
+export * from "./balance.js";

package/dist/index.js

@@ -1,11 +1,15 @@
 /**
- * @polkadot-apps/utils — Encoding utilities and token formatting for the Polkadot app ecosystem.
+ * @polkadot-apps/utils — Encoding, hashing, token formatting, and balance querying for the Polkadot app ecosystem.
  *
  * Provides general-purpose byte encoding/decoding (`bytesToHex`, `hexToBytes`, `utf8ToBytes`,
- * `concatBytes`) and Substrate token formatting (`formatPlanck`, `parseToPlanck`).
- * All functions are synchronous and framework-agnostic.
+ * `concatBytes`), 32-byte hash functions (`blake2b256`, `sha256`, `keccak256`),
+ * Substrate token formatting (`formatPlanck`, `parseToPlanck`, `formatBalance`),
+ * and typed balance queries (`getBalance`).
+ * All functions are framework-agnostic.
  *
  * @packageDocumentation
  */
 export * from "./encoding.js";
+export * from "./hashing.js";
 export * from "./planck.js";
+export * from "./balance.js";

package/dist/planck.d.ts

@@ -45,3 +45,39 @@ export declare function formatPlanck(planck: bigint, decimals?: number): string;
  * ```
  */
 export declare function parseToPlanck(amount: string, decimals?: number): bigint;
+/** Options for {@link formatBalance}. */
+export interface FormatBalanceOptions {
+    /** Token decimals. Default: 10 (DOT). */
+    decimals?: number;
+    /** Maximum fraction digits to display. Default: 4. */
+    maxDecimals?: number;
+    /** Token symbol to append (e.g., `"DOT"`, `"PAS"`). Omitted by default. */
+    symbol?: string;
+    /** BCP 47 locale tag for grouping and decimal separators (e.g., `"en-US"` → `","` grouping + `"."` decimal, `"de-DE"` → `"."` grouping + `","` decimal). Default: user's locale. */
+    locale?: string;
+}
+/**
+ * Format a planck value for display with locale-aware thousand separators,
+ * decimal truncation, and an optional token symbol.
+ *
+ * Builds on {@link formatPlanck} for BigInt-safe conversion, then applies
+ * presentation formatting. Unlike {@link formatPlanck}, trailing `.0` is
+ * omitted — display values show `"1,000"` not `"1,000.0"`.
+ *
+ * @param planck - The raw planck value as a bigint. Must be non-negative.
+ * @param options - Formatting options.
+ * @returns A display-ready string (e.g. `"1,000.5 DOT"`).
+ * @throws {RangeError} If `planck` is negative or `decimals` is invalid (delegated to {@link formatPlanck}).
+ *
+ * @example
+ * ```ts
+ * import { formatBalance } from "@polkadot-apps/utils";
+ *
+ * formatBalance(10_000_000_000n);                              // "1"
+ * formatBalance(15_000_000_000n, { symbol: "DOT" });           // "1.5 DOT"
+ * formatBalance(10_000_000_000_000n, { symbol: "DOT" });       // "1,000 DOT"
+ * formatBalance(12_345_678_900n, { maxDecimals: 2 });          // "1.23"
+ * formatBalance(0n, { symbol: "DOT" });                        // "0 DOT"
+ * ```
+ */
+export declare function formatBalance(planck: bigint, options?: FormatBalanceOptions): string;

package/dist/planck.js

@@ -104,6 +104,54 @@ export function parseToPlanck(amount, decimals = 10) {
     const fraction = decimals > 0 ? BigInt(paddedFraction) : 0n;
     return whole + fraction;
 }
+/**
+ * Format a planck value for display with locale-aware thousand separators,
+ * decimal truncation, and an optional token symbol.
+ *
+ * Builds on {@link formatPlanck} for BigInt-safe conversion, then applies
+ * presentation formatting. Unlike {@link formatPlanck}, trailing `.0` is
+ * omitted — display values show `"1,000"` not `"1,000.0"`.
+ *
+ * @param planck - The raw planck value as a bigint. Must be non-negative.
+ * @param options - Formatting options.
+ * @returns A display-ready string (e.g. `"1,000.5 DOT"`).
+ * @throws {RangeError} If `planck` is negative or `decimals` is invalid (delegated to {@link formatPlanck}).
+ *
+ * @example
+ * ```ts
+ * import { formatBalance } from "@polkadot-apps/utils";
+ *
+ * formatBalance(10_000_000_000n);                              // "1"
+ * formatBalance(15_000_000_000n, { symbol: "DOT" });           // "1.5 DOT"
+ * formatBalance(10_000_000_000_000n, { symbol: "DOT" });       // "1,000 DOT"
+ * formatBalance(12_345_678_900n, { maxDecimals: 2 });          // "1.23"
+ * formatBalance(0n, { symbol: "DOT" });                        // "0 DOT"
+ * ```
+ */
+export function formatBalance(planck, options) {
+    const decimals = options?.decimals ?? 10;
+    const maxDecimals = options?.maxDecimals ?? 4;
+    const symbol = options?.symbol;
+    const locale = options?.locale;
+    if (maxDecimals < 0 || !Number.isInteger(maxDecimals)) {
+        throw new RangeError(`maxDecimals must be a non-negative integer, got ${maxDecimals}`);
+    }
+    const raw = formatPlanck(planck, decimals);
+    const dotIndex = raw.indexOf(".");
+    const wholePart = dotIndex === -1 ? raw : raw.slice(0, dotIndex);
+    const fractionPart = dotIndex === -1 ? "" : raw.slice(dotIndex + 1);
+    const formatter = new Intl.NumberFormat(locale, { useGrouping: true });
+    // Format whole part with locale-aware grouping (BigInt overload avoids precision loss)
+    const formattedWhole = formatter.format(BigInt(wholePart));
+    // Extract the locale's decimal separator (e.g., "." for en-US, "," for de-DE)
+    const decimalSep = formatter.formatToParts(1.1).find((p) => p.type === "decimal")?.value ?? ".";
+    // Truncate fraction to maxDecimals, trim trailing zeros
+    const truncated = fractionPart.slice(0, maxDecimals);
+    const trimmed = truncated.replace(/0+$/, "");
+    const fractionSuffix = trimmed ? `${decimalSep}${trimmed}` : "";
+    const symbolSuffix = symbol ? ` ${symbol}` : "";
+    return `${formattedWhole}${fractionSuffix}${symbolSuffix}`;
+}
 if (import.meta.vitest) {
     const { describe, test, expect } = import.meta.vitest;
     describe("formatPlanck", () => {
@@ -191,4 +239,66 @@ if (import.meta.vitest) {
             expect(parseToPlanck(formatted)).toBe(original);
         });
     });
+    describe("formatBalance", () => {
+        test("formats with default options (no symbol, max 4 decimals)", () => {
+            expect(formatBalance(15000000000n)).toBe("1.5");
+            expect(formatBalance(12345678900n)).toBe("1.2345");
+        });
+        test("applies thousand separators", () => {
+            expect(formatBalance(10000000000000n, { locale: "en-US" })).toBe("1,000");
+            expect(formatBalance(1234567000000000n, { locale: "en-US", symbol: "DOT" })).toBe("123,456.7 DOT");
+        });
+        test("truncates fraction to maxDecimals", () => {
+            expect(formatBalance(12345678900n, { maxDecimals: 2 })).toBe("1.23");
+            expect(formatBalance(12345678900n, { maxDecimals: 8 })).toBe("1.23456789");
+        });
+        test("appends symbol", () => {
+            expect(formatBalance(15000000000n, { symbol: "DOT" })).toBe("1.5 DOT");
+            expect(formatBalance(15000000000n, { symbol: "PAS" })).toBe("1.5 PAS");
+        });
+        test("omits fraction when all zeros after truncation", () => {
+            expect(formatBalance(10000000000n)).toBe("1");
+            expect(formatBalance(20000000000n, { symbol: "DOT" })).toBe("2 DOT");
+        });
+        test("respects maxDecimals: 0", () => {
+            expect(formatBalance(15000000000n, { maxDecimals: 0 })).toBe("1");
+            expect(formatBalance(19999999999n, { maxDecimals: 0, symbol: "DOT" })).toBe("1 DOT");
+        });
+        test("handles zero", () => {
+            expect(formatBalance(0n)).toBe("0");
+            expect(formatBalance(0n, { symbol: "DOT" })).toBe("0 DOT");
+        });
+        test("handles sub-unit amounts", () => {
+            // 1 planck is below 4-decimal display threshold → shows "0"
+            expect(formatBalance(1n)).toBe("0");
+            // 0.0001 DOT is exactly at the threshold
+            expect(formatBalance(1000000n)).toBe("0.0001");
+            // With more maxDecimals, sub-unit amounts become visible
+            expect(formatBalance(1n, { maxDecimals: 10 })).toBe("0.0000000001");
+        });
+        test("uses locale-correct decimal separator", () => {
+            // German uses . for grouping and , for decimal
+            expect(formatBalance(15000000000n, { locale: "de-DE" })).toBe("1,5");
+            expect(formatBalance(10000000000000n, { locale: "de-DE" })).toBe("1.000");
+            // With fraction
+            expect(formatBalance(10005000000000n, { locale: "de-DE" })).toBe("1.000,5");
+        });
+        test("preserves BigInt precision for large amounts", () => {
+            // 2^53 + 1 in planck — would lose precision with Number()
+            const largePlanck = 90071992547409920000n; // ~9 billion DOT
+            const result = formatBalance(largePlanck, { locale: "en-US", symbol: "DOT" });
+            expect(result).toContain("9,007,199,254");
+            expect(result).toContain("DOT");
+        });
+        test("throws on negative planck (delegates to formatPlanck)", () => {
+            expect(() => formatBalance(-1n)).toThrow(RangeError);
+        });
+        test("throws on invalid decimals (delegates to formatPlanck)", () => {
+            expect(() => formatBalance(0n, { decimals: -1 })).toThrow(RangeError);
+        });
+        test("throws on invalid maxDecimals", () => {
+            expect(() => formatBalance(0n, { maxDecimals: -1 })).toThrow(RangeError);
+            expect(() => formatBalance(0n, { maxDecimals: 1.5 })).toThrow(RangeError);
+        });
+    });
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@polkadot-apps/utils",
   "description": "Encoding utilities and token formatting for the @polkadot-apps ecosystem",
-  "version": "0.2.1",
+  "version": "0.4.0",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",