A collection of useful utilities for @polkadot
Various useful utility functions that are used across all projects in the @polkadot namespace. It provides utility functions with additional safety checks, allowing not only for consistent coding, but also reducing the general boilerplate.
Installation -
polkadot-jsyarn add @polkadot/utilFunctions can be imported directly from the package, e.g.
import { isHex } from '@polkadot/util';Changes:
Changes:
Changes:
Changes:
Changes:
Contributed:
Changes:
Changes:
Changes:
Changes:
Contributed:
Changes:
Changes:
Changes:
Changes:
Changes:
verifyMultisig (#1973)Changes:
getSeparator which fixes toLocaleString (#1965)Contributed:
Changes:
Contributed:
Changes:
Contributed:
Changes:
Contributed:
HydraDx - Hydration Rebrand Thanks to (https://github.com/jak-pan) (#1923)
Changes:
genericLedgerApps and prevLedgerRecord objects. They both combine into ledgerApps in hw-ledger/defaults.Contributed:
Breaking Changes:
class Ledger in favor of class LedgerGenericChanges:
Changes:
@polkadot/wasm-cryptoContributed:
Changes:
process.envisRiscV helper to check for PVM\0 bytesContributed:
isRiskV helper (Thanks to https://github.com/peetzweg)Changes:
Changes:
u8aTo{BigInt, Bn, Number} for non-negative i{8, 16, 32...} inputsu8aToBuffer with hasBuffer checkChanges:
signRaw, as exposed by lower-level?. shortcuts where appropriateu8aToBuffer & isBuffer typings to not require Bufferstringify/import.meta.url helpers in specsChanges:
SubstrateNetwork typing with HexString genesisHashConstructor<T> type (deprecated, replaced with Class<T>)Changes:
Changes:
for (...) loops@types/* dev dependenciesChanges:
u8aToBigInt tests with u8aToBnu8aToBigIntmodule to package.json export map (ESM-only)Changes:
isChildClass & Constructor usageChanges:
identity & noop functionsBuffer | Uint8Array types (as used) to base-only Uint8Arrayreadonly specifiers to private class fields where applicable__internal__ class fieldsutilContributed:
Changes:
@noble/curves@noble/curvestweetnacl secretbox usage with slimmer local versionisCodec helper with closer API alignmentgetRandomValues supportContributed:
Changes:
/*#__PURE__*/ annotationsChanges:
@polkadot/hw-ledger with specific per-method JSDocContributed:
Changes:
Changes:
.js imports in source files (TS moduleResolution)@polkadot/wasm-crypto 7.0.3Changes:
@polkadot/x-ws to use ws package (previous: websocket)/*#__PURE__*/ annotations for @polkadot/x-* packagesnode:test runner (ESM variants)cryptoWaitReady() top-level in test files@polkadot/wasm-crypto 7.0.1Contributed:
Changes:
u8aToU8a correctly unwraps Buffer value (check ordering)Contributed:
Changes:
isClass helper (checks if input is actual Class Constructor)isChildClass to rely on new isClassContributed:
Changes:
arrayChunk testsbigint constants to match with those in BNUint8Array instad of Array<number>Changes:
console.error log (it really is Friday 13th)Changes:
formatBalance (forceUnit) with BN inputs where output is less than 0Changes:
withAll (default false) flag to formatBalance to format to max decimalswithZero (default true) flags to formatBalance to retain trailing zerosChanges:
isBuffer check on xglobal (no auto-polyfill detection on eg. parcel)Contributed:
Changes:
Contributed:
Changes:
has{Buffer, Process} now checks on globalThis (helps bundlers with auto-injection)/*#__PURE__*/ annotations for specific export const something = someFunction(...)@polkadot/wasm-crypto 6.4.1Changes:
Contributed:
Changes:
Changes:
Changes:
Changes:
{bn, n, number}ToHex(0) always respects bitLengthContributed:
Changes:
Contributed:
Changes:
Changes:
Changes:
nextTick with greater care for browser loopsChanges:
ledgerApps to use new @zondax/ledger-substrate interfacesContributed:
Changes:
Changes:
arrayFlatten caseas casting)Changes:
Changes:
arrayUnzip as reverse of arrayZipobjectSpread to natively handle Map entries spreadsisAscii check to disallow \t, \n, & \r charactersnobody zero-key pair with pre-computed addressobjectProperty & lazyMethod call signatures (backwards compatible)Changes:
x-fetch to be Jest-friendlybnToHex, bnToU8a, formatBalance, hexToBn or u8aToBn, please update and only pass through an options object as the second parameter.Contributed:
Changes:
bnToHex, bnToU8a, formatBalance, hexToBn, u8aToBnn* (BigInt) functions with bn* (BN)@types/node installed@polkadot/wasm-crypto 6.2.3Changes:
@polkadot/wasm-crypto 6.2.2Changes:
readonly arrays are used@polkadot/wasm-crypto 6.2.1Changes:
hexToU8a where 0x is not correctly convertedChanges:
floatToU8a and u8aToFloat (both 32 & 64-bit, le & be)isUndefined check (local variable available)assert, isUndefined & isNullContributed:
Changes:
u8aToNumber (limited, <= 48 bits) function~~ as bitwise/faster Math.floor replacementobjectSpread option expansionshexToU8a operationsstringCamelCase operationsu8aToBn operationsChanges:
nextTick to @polkadot/util to defer execution to the queueContributed:
Changes:
u8aToU8a checks with better isU8a shortcutstring{Camel, Pascal}Case with loop (no map)compactFromU8aLim variant with Uint8Array-only inputsu8aConcatStrict variant with Uint8Array-only inputsContributed:
Changes:
u8aToHex with direct (non-hex) conversion.substr(...) to .substring(...)cryptoWaitReady()@polkadot/wasm-crypto 6.1.1Contributed:
Changes:
detectPackageisHex performance test*Options structuresChanges:
@polkadot/util-crypto re-exports from @polkadot/networkscjs/** root@polkadot/wasm-crypto 6.0.1Changes:
cryptoWaitReady lazyBN & BigInt negative conversions@polkadot/wasm-crypto 5.1.1Important This contains an upgraded version of @polkadot/wasm-crypto. For users of asm.js, e.g. React Native, there are some additional upgrade instructions in the release notes for this version https://github.com/polkadot-js/wasm/releases/tag/v5.0.1
Contributed:
Changes:
@polkadot/networks@polkadot/wasm-crypto 5.0.1Changes:
import.meta.url is undefinedChanges:
@substrate/ss58-registry (instead of duplicating here)micro-base to @scure/base (same package, audited)bn.js library to latest 5.2.0 (has impact on e.g. API)Changes:
Changes:
Changes:
util-crypto bundle generation (adjust x-randomvalues)detectPackage now uses optional path & type (esm or cjs) info@noble/* to latest known tested integrated versionsContributed:
Changes:
isPromise check utility functionassertUnreachable for codepaths that should not be followedstringCamelCasex-* fallbacks via x-global/extractGlobalbip39 wordlists@noble packagesChanges:
string{Camel, Pascal}CaseContributed:
Changes:
secp256k1 from @polkadot/wasm-cryptoisBigInt to not do instanceof checkstringCamelCase are lowercased@polkadot/x-bigint for BigInt constructor@noble/hashes fork into x-noble-hashes@noble/secp256k1 fork into x-noble-secp256k1, replaces ellipticChanges:
BigInt availabilityChanges:
stringCamelCase with leading _Changes:
Buffer usage in x-randomvaluesstringCamelCase for all-caps partsChanges:
Important In the 8.0 version the hashing utilities have been consolidated around an optimized and audited version from @noble/hashes. As in the past the WASM hashing will be used by default if the environment is initialized.
Breaking change The schnorrkel* functions have been renamed to sr25519*. Likewise the ed25519 operations have been renamed from nacl* to ed25519*. Additionally the {ed, sr, secp256k1}25519KeyPairFrom* functions have been renamed to {ed, sr, secp256k1}25519PairFrom*.
Changes:
ed25519* & sr25519* functions@noble/hashesxxhashBigInt utility exports (with capability detection)bi* functions renamed to n*Changes:
base* typeshmacShaAsU8aContributed:
Changes:
object{Entries, Keys, Values} utilities{hex, u8a}ToBigInt utilitiesbi* utilities for bigint operations (mirror of bn*)stringPascalCase utilityisCodec to check for Codec-like structureshas* detection shortcuts (e.g. hasWasm or hasBuffer)sha256AsU8a util (& replace use internally)hexToU8a and u8aToHex functionsu8aEq to use DataView for comparesbase{32, 58, 64}* around (audited) micro-baseChanges:
isArray checkobject{Property, Properties} from api repoContributed:
Changes:
objectClear and objectSpread utility functionslazyMethod & lazyMethods utility functionsContributed:
Changes:
arrayZip to combine a key + value array into entries-likechainCode inputs to derive*, protecting against misuse@polkadot/networksfor vs reduce/mapChanges:
xxhash* to only use Uint8Array internally, no BufferisAscii to check against original string codepoints (when provided)paritytech/ss58-registryContributed:
blake2AsU8a (Thanks to https://github.com/tomokazukozuma)Changes:
MAX_SAFE_INTEGER unsigned valuesChanges:
u8aWrapBytes & u8aUnwrapBytes (originally from @polkadot/extension-dapp)isHex return to 0x${string} under TypeScriptx-global yields undefinedContributed:
Changes:
schnorrkelAgreement (as exposed by new wasm-crypto)schnorrkel* functions allows hex inputs@polkadot/wasm-crypto 4.2.1Contributed:
bigint type to indicate instance (Thanks to https://github.com/ntduan)Changes:
u8aEmpty helper check, all 0 or no lengthChanges:
@polkadot/util-crypto doesn't re-export packageInfo from @polkadot/networks@polkadot/x-bundleContributed:
Changes:
Changes:
Changes:
isCompact utility for check on compact-like types@polkadot/x-rxjs package has been removed. In rxjs 7.2.0 the compatibility issues at the base layer has been solved.@polkadot/networks has been changedContributed:
Changes:
@polkadot/networks to fully-descriptive exports@polkadot/x-rxjs, direct import from rxjs >= 7.2.0 requiredChanges:
@polkadot/x-globalContributed:
Changes:
isHex(value) will now check for only string types (No String classes)arrayShuffle(array) to shuffle an array into a new output{describe|it}.each where applicableChanges:
u8aCmp(a, b) to do sorting comparesarrayRange(size, startAt = 0) to create a range of numbersContributed:
naclSeal doc types (Thanks to https://github.com/agustinustheo)Changes:
BN in @polkadot/utilChanges:
Gerald key for MoonbeamChanges:
Changes:
Contributed:
Changes:
setSS58FormatChanges:
stringify util to correctly handle JSON.stringify with BigInt valuesu8aToU8a@polkadot/x-global to return globalThis as availableengines config to package.jsonContributed:
Changes:
isAddress and validateAddress functions (the latter will throw if invalid)@polkadot/hw-ledger against @polkadot/networks for discrepancies (test-only)Contributed:
@polkadot/networks (Thanks to https://github.com/adamdossa)@polkadot/util logger for +/-/* compat (Thanks to https://github.com/Lezek123)@polkadot/util detect messaging (Thanks to https://github.com/amphineko)Changes:
@polkadot/networks code duplication, manages data via script from upstreamChanges:
@polkadot/x-rxjs in Node CJS environments (no Node-specific import)Contributed:
Changes:
Changes:
Changes:
@polkadot/x-rxjs ESM exports for Node environments (now different due to the ESM conversion)Important In the 6.0 version the default package type has been changed to ESM modules by default. This should not affect usage, however since the output formats changed, a new major version is required.
Contributed:
Changes:
{add, create}FromPairChanges:
@polkadot/networks (no dependencies)Changes:
detectPackage with optional param allowing checks for monorepo versionsformat function directly as loggerFormathdValidatePathhdEthereum class-based approach, simplify@polkadot/x- packagespackageInfo from the rootContributed:
Changes:
@polkadot/wasm-crypto 3.2.4Breaking change The signature of pair.verify now requires the signer public key as a parameter. If using pair.verify pass the publicKey (hex or Uint8Array) of the signer.
Changes:
.verify now explicitly requires the publicKey of the signer. Previously it only verified against an own public key.Contributed:
Changes:
unlock(password) to keypair (less confusing than only having decodePkcs8, equivalent to lock())detectPackage to use packageInfo.ts@polkadot/wasm-crypto 3.2.3Changes:
@polkadot/networks now filters the new upstream-introduced null networksContributed:
@polkadot/x-global (Thanks to https://github.com/raoulmillais)Changes:
bnSqrt when value <= MAX_SAFE_INTEGERBuffer.from usages, prefer Uint8Array where possiblevrf{Sign, Verify}@polkadot/networks with latest ss58 registryChanges:
BN_{MILLION, BILLION} constants (in addition to 2-9)Changes:
hdLedger to util-crypto for Ledger-compatible bip32+ed25519 derivationhmac{Sha256, 512} to util-cryptoslip44 indices for Ledger into @polkadot/networksmodule entry in package.json (only rely on exports map)global object, use @polkadot/x-global@ledgerhq dependencies to latestContributed:
Changes:
number[] & symbol as string[] in balanceFormat defaultsschnorrkelVrf{Sign, Verify} to @polkadot/util-cryptovrf{Sign, Verify} on keyring interface@polkadot/x-rxjs packages from the api repo@polkadot/networks with Substrate master@polkadot/wasm-crypto 3.2.1Important For users of the @polkadot/ledger package, it is now included in this repo (since it is a general utility) and renamed to @polkadot/hw-ledger
Contributed:
Changes:
@polkadot/ledger packages into common@polkadot/networks to align with latest Substrate ss58-registryChanges:
arrayFlatten to merge a series of arrays into a singlearrayChunk to chunk an array into multiples of defined sizebitLength param (allowed 256, 512) to keccakAs{Hex, U8a}@polkadot/networks with Substrate masterChanges:
detectPackage now can take a path-retrieval callback as second argumentblake2js imports to consistently cater for esm & cjs usagedetectPackage usage as having side-effects@polkadot/networks with Substrate master@polkadot/wasm-crypto 3.1.1Important While this package contains no external interface changes, it now compiles and ships both cjs and esm modules. This means that modern bundlers will have more information for tree-shaking available. Additionally when using Node with .mjs extensions, the esm version imports will be used on recent Node versions. Adding an export map, as here, may have some impacts so a major semver bump is advised. There may be (small) dragons hiding in the dark corners...
Changes:
import type { ... } form for all type importsNODE_ENV, but rather DEBUG=<type,type,...> (* logs all)DEBUG_MAX=<number> value, trimming when passedmemoize util, allowing for function memoization (as used in the API)@polkadot/networks with Substrate master@polkadot/wasm-crypto 3.0.1Changes:
@polkadot/util)Contributed:
Changes:
Changes:
Array.fill, String.padStart, String.padEnd as well as Object.setPrototypeOf. These should be provided by the actual user of the libraries if so required.@polkadot/wasm-crypto library (under-the-hood cleanups)@polkadot/wasm-crypto)@polkadot/x-randomvalues (for use in @polkadot/wasm-crypto)Changes:
chalk (logger) for less overall dependenciesstring* utilities now also allows String (class) inputs@polkadot/networks@polkadot/x-{fetch,textdecoder,textencoder,ws} into common repoContributed:
@polkadot/util-crypto (Thanks to https://github.com/jnaviask)Changes:
mnemonicToBip39 to mnemonicToLegacySeed (used in non-Substrate compatible fashion)@polkadot/networks for a list of known networks and their identifying informationContributed:
Changes:
isBase{32, 58, 64} to @polkadot/util-cryptobase64{Pad, Trim} to add/remove padding characterscreateFromJson(json) to keyring (create pair without adding)Changes:
mnemonicToBip39 call (used for Ethereum-compatible keypairs)isWasm utility to check for valid WASM headers@polkadot/wasm-crypto 1.4.1Changes:
addressRaw to Keyring interface (if address encoding is different to publicKey)Changes:
mnemonicToBip39 seed creation functionChanges:
deriveAddress(<address>, '/<soft>/<soft-b>') via sr25519 softscrypt from WASM as available (JS fallback in place)base32{Encode, Decode} utilities (IPFS-compatible alphabet)@polkadot/wasm-crypto 1.3.1Contributed:
Changes:
Changes:
base64{Decode, Encode, Validate} as crypto utilsbase58Validate from base58 decode checksisAscii to allow detection of printable ASCII sequences (including tab, newline)isUtf8 to allow detection of valid Utf8 sequencesChanges:
encode{Derived, Multi}Address to encode derived/multi addressesnumberToU8aChanges:
addressCheck and encodeAddress function to check for valid base58 alphabets (better error reporting)createKeySub to createKeyDerived based on changed in Substrate (sub keys now named derived)Changes:
Contributed:
extractTime utility conversion (Thanks to https://github.com/kwingram25)Changes:
bnToHex signature with bnToU8a (with old/new style)bnTo{Hex,U8a} to take any value with .toBn() signaturesChanges:
isFunction signature to assert FunctionmnemonicToSeed, it is only for bip39, use mnemonicToMiniSecret for the Substrate variantChanges:
u8aEq to compare two Uint8Array or hex values for an exact matchaddressEq to compare two addresses (ss58, Uint8array or hex) for an exact match{nacl,schnorrkel}Verify on invalid input lengthsu8aToHex & u8aConcatChanges:
Contributed:
Changes:
TextEncoder polyfill handle non-compliant Buffer implementations (newer versions of Jest)DeriveJunction now also allows for BigInt values (aligning with number types elsewhere)Contributed:
Changes:
createKeyMulti & createKeySub to create utility sub & multi keysu8aSorted to sort Uint8ArrayssortAddresses to sort addresses based on their internal representationChanges:
isDevelopment regex to cater for chains such as Westend DevelopmentChanges:
bnSqrt to calculate the integer sqrt via Newton iteration@polkadot/util-crypto/noWasm@polkadot/wasm was updated to 1.1+. sr25510 now only verifies 0.8+ signatures, closing the loop on dropping Substrate 1.x-era supportChanges:
signatureVerify (message: Uint8Array | string, signature: Uint8Array | string, addressOrPublicKey: Uint8Array | string): VerifyResult to verify any signature, regardless of type. Returns validity & detected crypto type.cryptoIsReady (): boolean function to check status of initializationaddressCheckChecksum (decoded: Uint8Array) as an helper to extract and verify the ss58 checksum*.d.ts files now contain TypeScript 3.8 features, #private, which is not usable in older versionsChanges:
isBigInt(value) to allow BigInt checks. Also add support in bnToBn as well as number conversion utilsisChildClass(Parent, Child?) to check if a class extends the parent, asserting Child is Parent#<field> instead of private _<field> for private class variablesChanges:
formatBalance does not apply unit overrides apply when no SI is applicableformatBalance(<balance>, <options>) to take expanded withUnit: string | boolean option where string is an actual unit, e.g. KSMdecimals option to formatBalance should now be passed as part of the options (previous last-param deprecated).setSS58Format on keyring will now just operate on pairs created on the keyring, not globally. The global setSS58Format in @polkadot/util-crypto will be deprecated.addressPrefix option to keyring has been belatedly removed (Use ss58Format rather)Contributed:
formatDate function (Thanks to https://github.com/AndreasGassmann)@types/* to dev deps (Thanks to https://github.com/AndreasGassmann)Changes:
@polkadot/wasm-crypto 1.0Changes:
Changes:
detectPackage(<package.json>, __dirname?) with calling folderChanges:
chainspec, db, trie-codec, trie-db and trie-hash packages (moved to client)assertSingletonPackage to detectPackage with inclusion of version listingContributed:
Changes:
formatBalance signature now allows to force unit displayspair.derive(...)assert now acts like a real asserts, with no return - signature adapted for new TS 3.7Changes:
pair.sign(message) now takes an optional second options?: SignOptions parameter, where SignOptions is currently defined as { withType: boolean }. Here withType instructs the signing to prepend the type of signature (ed2551, sr25519 or ecdsa). This is used for the new Polkadot/Substrate MultiSignature format.Changes:
ss58Format, you should now use setSS58Format as opposed to the old setAddressPrefixChanges:
keyring.setAddressPrefix to keyring.setSS58FormataddressPrefix on the keyring options, added the ss58Format as a replacement (aligning with chain properties - the old version is still accepted)stringToHex and hexToString conversion utilities to @polkadot/utilChanges:
ExtError class, always prefer the standard JS Error object for errors. This would bre a breaking change for any applications using ExtErrorChanges:
addFromAddress can now be used to store external accounts, for example those provided by external signersChanges:
assertSingletonPackage now warns via console.warn, but does not throw. This does allow the info to come accross while still allowing the app developers using multiple libraries time to fix.Changes:
formatBalance now allows for Compact inputsformaBalance now allows correct formatting of very large decimalsChanges:
checkAddress(address, prefix) to @polkadot/util-crypto that validates an ss-58 addressasm.js fallback for the React Native environment (via @polkadot/wasm-crypto)Changes:
getMeta use the meta getter, i.e. console.log(pair.meta.name)address use the address getter, i.e. console.log(pair.address)publicKey use the publicKey getter, i.e. console.log(pair.publicKey)Move decodeAddress, encodeAddress & setAddressPrefix functions into @polkadot/util-crypto from @polkadot/keyring. External interfaces should not be affected at this point since it is also (still) exported and exposed on keyringChanges:
formatBalanceformatBalance, formatDecimal & formatNumber to cater for negative numbersChanges:
@polkadot/wasm to include a maintenance bump for the w3f/schnorrkel librariesChanges:
Changes:
addFromMnemonic to generate using new-style derivation.formatBalance, formatDecimal, formatElapsed, formatNumber, calcSi, findSi & isTestChain utility functions from the originals in @polkadot/ui-utilwasm-schnorrkel & wasm-ed25519 for combined version with wasm-cryptotransactionAsync (client-only changes)Changes:
Changes:
assertSingletonPackage to utilChanges:
Changes:
Changes:
@poladkot/wasm-crypto with a fallback to the pure JS versionsChanges:
Changes:
Changes:
fromUri to keyring along with hard & soft key derivation.Changes:
syncify function, not exported by the package (with binary dependency for Node)Changes:
ed25519or sr25519 string to denote the type, i.e. new Keyring({ type: 'sr25519' })