`@parity/product-sdk-utils`

Encoding, hashing, token formatting, and balance querying for the Polkadot app ecosystem.

Provides general-purpose byte encoding/decoding (bytesToHex, hexToBytes, utf8ToBytes, concatBytes), 32-byte hash functions (blake2b256, sha256, keccak256), Substrate token formatting (formatPlanck, parseToPlanck, formatBalance), and typed balance queries (getBalance). All functions are framework-agnostic.


npm install @parity/product-sdk-utils


pnpm add @parity/product-sdk-utils


yarn add @parity/product-sdk-utils


bun add @parity/product-sdk-utils

Exports

Functions

Name	Summary
`blake2b256()`	Compute a 32-byte BLAKE2b-256 hash.
`bytesToHex()`	Convert a `Uint8Array` to its lowercase hexadecimal string representation.
`concatBytes()`	Concatenate multiple `Uint8Array` instances into a single `Uint8Array`.
`formatBalance()`	Format a planck value for display with locale-aware thousand separators,
`formatPlanck()`	Convert a planck (smallest indivisible token unit) value to a human-readable decimal string.
`getBalance()`	Query the free, reserved, and frozen balances for an on-chain address.
`hexToBytes()`	Decode a hexadecimal string into a `Uint8Array`.
`keccak256()`	Compute a 32-byte Keccak-256 hash.
`parseToPlanck()`	Parse a human-readable decimal token amount into its planck (smallest unit) representation.
`sha256()`	Compute a 32-byte SHA2-256 hash.
`utf8ToBytes()`	Encode a UTF-8 string into a `Uint8Array`.

Interfaces

Name	Summary
`AccountBalance`	Balance breakdown from a Substrate `System.Account` query.
`BalanceApi`	Minimal structural type for a PAPI typed API with `System.Account`.
`FormatBalanceOptions`	Options for `formatBalance`.

Functions

`blake2b256()`

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.


blake2b256(data: Uint8Array): Uint8Array

Parameters

data: Arbitrary bytes to hash.

Returns

32-byte BLAKE2b-256 digest.

Examples


import { blake2b256, bytesToHex } from "@parity/product-sdk-utils";
 
const hash = blake2b256(new TextEncoder().encode("hello"));
console.log(bytesToHex(hash)); // 64-char hex string

`bytesToHex()`

Convert byte array to hex string. Uses the built-in function when available and assumes it matches the tested fallback semantics.


bytesToHex(bytes: TArg<Uint8Array<ArrayBufferLike>>): string

Parameters

bytes: bytes to encode

Returns

Lowercase hexadecimal string.

Throws

On wrong argument types. TypeError

Examples

Convert bytes to lowercase hexadecimal.


bytesToHex(Uint8Array.from([0xca, 0xfe, 0x01, 0x23])); // 'cafe0123'

`concatBytes()`

Copies several Uint8Arrays into one.


concatBytes(...arrays: TArg<Uint8Array<ArrayBufferLike>[]>): Uint8Array<ArrayBufferLike> & Uint8Array<ArrayBuffer>

Parameters

arrays: arrays to concatenate

Returns

Concatenated byte array.

Throws

On wrong argument types. TypeError

Examples

Concatenate multiple byte arrays.


concatBytes(new Uint8Array([1]), new Uint8Array([2]));

`formatBalance()`

Format a planck value for display with locale-aware thousand separators, decimal truncation, and an optional token symbol.

Builds on formatPlanck for BigInt-safe conversion, then applies presentation formatting. Unlike formatPlanck, trailing .0 is omitted — display values show "1,000" not "1,000.0".


formatBalance(planck: bigint, options?: FormatBalanceOptions): string

Parameters

planck: The raw planck value as a bigint. Must be non-negative.
options: Formatting options.

Returns

A display-ready string (e.g. "1,000.5 DOT").

Throws

If planck is negative or decimals is invalid (delegated to formatPlanck).

Examples


import { formatBalance } from "@parity/product-sdk-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"

`formatPlanck()`

Convert a planck (smallest indivisible token unit) value to a human-readable decimal string.

Substrate chains store all token amounts as integer planck values. This function converts them to human-readable form (e.g. 10_000_000_000n → "1.0" for DOT with 10 decimals). Trailing zeros are trimmed but at least one fractional digit is always shown.


formatPlanck(planck: bigint, decimals: number = 10): string

Parameters

planck: The raw planck value as a bigint. Must be non-negative.
decimals: Number of decimal places for the token (default: 10 for DOT).

Returns

A decimal string representation (e.g. "1.5", "0.0001").

Throws

If planck is negative or decimals is invalid.

Examples


import { formatPlanck } from "@parity/product-sdk-utils";
 
formatPlanck(10_000_000_000n);       // "1.0"       (10 decimals, DOT default)
formatPlanck(15_000_000_000n);       // "1.5"
formatPlanck(1_000_000_000_000n, 12); // "1.0"      (12 decimals, e.g. Polkadot relay)
formatPlanck(0n);                     // "0.0"

`getBalance()`

Query the free, reserved, and frozen balances for an on-chain address.

Thin typed wrapper around System.Account.getValue that returns a clean AccountBalance object. Uses structural typing so it works with any PAPI typed API that has the System pallet — no chain-specific imports needed.


getBalance(api: BalanceApi, address: string): Promise<AccountBalance>

Parameters

api: A PAPI typed API with query.System.Account. Pass the chain-specific API (e.g., client.assetHub), not the multi-chain ChainClient wrapper.
address: The SS58 address to query.

Returns

The account’s balance breakdown.

Examples


import { getBalance } from "@parity/product-sdk-utils";
import { formatBalance } from "@parity/product-sdk-utils";
 
const balance = await getBalance(api.assetHub, aliceAddress);
console.log(formatBalance(balance.free, { symbol: "DOT" })); // "1,000.5 DOT"

`hexToBytes()`

Convert hex string to byte array. Uses built-in function, when available.


hexToBytes(hex: string): Uint8Array<ArrayBufferLike> & Uint8Array<ArrayBuffer>

Parameters

hex: hexadecimal string to decode

Returns

Decoded bytes.

Throws

On wrong argument types. TypeError
On wrong argument ranges or values. RangeError

Examples

Decode lowercase hexadecimal into bytes.


hexToBytes('cafe0123'); // Uint8Array.from([0xca, 0xfe, 0x01, 0x23])

`keccak256()`

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.


keccak256(data: Uint8Array): Uint8Array

Parameters

data: Arbitrary bytes to hash.

Returns

32-byte Keccak-256 digest.

Examples


import { keccak256, bytesToHex } from "@parity/product-sdk-utils";
 
const hash = keccak256(new TextEncoder().encode("hello"));
console.log(bytesToHex(hash)); // 64-char hex string

`parseToPlanck()`

Parse a human-readable decimal token amount into its planck (smallest unit) representation.

Converts a string like "1.5" into the corresponding bigint planck value (e.g. 15_000_000_000n for 10 decimals). If the input has more fractional digits than decimals, excess digits are silently truncated with a warning log.


parseToPlanck(amount: string, decimals: number = 10): bigint

Parameters

amount: A non-negative decimal string (e.g. "1.5", "100", "0.001").
decimals: Number of decimal places for the token (default: 10 for DOT).

Returns

The planck value as a bigint.

Throws

If amount is empty, negative, or contains invalid characters.
If decimals is invalid.

Examples


import { parseToPlanck } from "@parity/product-sdk-utils";
 
parseToPlanck("1.5");        // 15_000_000_000n   (10 decimals, DOT default)
parseToPlanck("100");        // 1_000_000_000_000n
parseToPlanck("0.001", 12);  // 1_000_000_000n    (12 decimals)

`sha256()`

Compute a 32-byte SHA2-256 hash.

Used by bulletin-deploy and supported by the Bulletin Chain as an alternative hashing algorithm.


sha256(data: Uint8Array): Uint8Array

Parameters

data: Arbitrary bytes to hash.

Returns

32-byte SHA2-256 digest.

Examples


import { sha256, bytesToHex } from "@parity/product-sdk-utils";
 
const hash = sha256(new TextEncoder().encode("hello"));
console.log(bytesToHex(hash)); // 64-char hex string

`utf8ToBytes()`

Converts string to bytes using UTF8 encoding. Built-in doesn’t validate input to be string: we do the check. Non-ASCII details are delegated to the platform TextEncoder.


utf8ToBytes(str: string): Uint8Array<ArrayBufferLike> & Uint8Array<ArrayBuffer>

Parameters

str: string to encode

Returns

UTF-8 encoded bytes.

Throws

On wrong argument types. TypeError

Examples

Encode a string as UTF-8 bytes.


utf8ToBytes('abc'); // Uint8Array.from([97, 98, 99])

Interfaces

`interface AccountBalance`

Balance breakdown from a Substrate System.Account query.

Properties

`free`

propertybigint

Available (transferable) balance in planck.

`frozen`

propertybigint

Frozen (non-transferable but still counted) balance in planck.

`reserved`

propertybigint

Reserved (locked by governance, staking, etc.) balance in planck.

`interface BalanceApi`

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.

Properties

`query`

property{ System: { Account: { getValue: unknown } } }

`interface FormatBalanceOptions`

Options for formatBalance.

Properties

`decimals`

propertyoptionalnumber

Token decimals. Default: 10 (DOT).

`locale`

propertyoptionalstring

BCP 47 locale tag for grouping and decimal separators (e.g., "en-US" → "," grouping + "." decimal, "de-DE" → "." grouping + "," decimal). Default: user’s locale.

`maxDecimals`

propertyoptionalnumber

Maximum fraction digits to display. Default: 4.

`symbol`

propertyoptionalstring

Token symbol to append (e.g., "DOT", "PAS"). Omitted by default.