utils-js

A collection of utilities and constants for NNS/SNS projects.

Table of contents

• Installation
• Features

Installation

You can use utils-js by installing it in your project.

npm i @dfinity/utils

The bundle needs peer dependencies, be sure that following resources are available in your project as well.

npm i @dfinity/agent @dfinity/candid @dfinity/principal

Features

utils-js implements following features:

:toolbox: Functions

• convertStringToE8s
• isNullish
• nonNullish
• notEmptyString
• isEmptyString
• queryAndUpdate
• defaultAgent
• createAgent
• createServices
• assertNonNullish
• asNonNullish
• assertPercentageNumber
• uint8ArrayToBigInt
• bigIntToUint8Array
• numberToUint8Array
• arrayBufferToUint8Array
• uint8ArrayToArrayOfNumber
• arrayOfNumberToUint8Array
• asciiStringToByteArray
• hexStringToUint8Array
• uint8ArrayToHexString
• candidNumberArrayToBigInt
• encodeBase32
• decodeBase32
• uint8ArrayToBase64
• base64ToUint8Array
• bigEndianCrc32
• jsonReplacer
• jsonReviver
• hashObject
• hashText
• secondsToDuration
• nowInBigIntNanoSeconds
• toBigIntNanoSeconds
• debounce
• toNullable
• fromNullable
• fromDefinedNullable
• fromNullishNullable
• principalToSubAccount
• smallerVersion

:gear: convertStringToE8s

Receives a string representing a number and returns the big int or error.

Parameters:

• amount: - in string format

:link: Source

:gear: isNullish

Checks if a given argument is null or undefined.

Parameters:

• argument: - The argument to check.

:link: Source

:gear: nonNullish

Checks if a given argument is neither null nor undefined.

Parameters:

• argument: - The argument to check.

:link: Source

:gear: notEmptyString

Checks if a given value is not null, not undefined, and not an empty string.

Parameters:

• value: - The value to check.

:link: Source

:gear: isEmptyString

Checks if a given value is null, undefined, or an empty string.

Parameters:

• value: - The value to check.

:link: Source

:gear: queryAndUpdate

This service performs a query (not-certified) call and/or an update (certified) call, and handles the results.

It is useful because it can do both type of calls for security reasons. For example, malicious nodes can forge transactions and balance when calling an Index canister, if no update is performed to certify the results.

Furthermore, it can handle the results of the calls in different ways:

• query only performs a query call.
• update only performs an update call.
• query_and_update performs both calls.

The resolution can be:

• all_settled waits for all calls to settle.
• race waits for the first call to settle (typically, query is the fastest one).

Once the call(s) are done, the response is handled by the onLoad callback. However, if an error occurs, it is handled by the error callbacks, if provided: one for the query call and one for the update call.

Parameters:

• params: The parameters to perform the request.
• params.request: The request to perform.
• params.onLoad: The callback to handle the response of the request.
• params.onQueryError: The callback to handle the error of the query request.
• params.onUpdateError: The callback to handle the error of the update request.
• params.strategy: The strategy to use. Default is query_and_update.
• params.identity: The identity to use for the request.
• params.resolution: The resolution to use. Default is race.

:link: Source

:gear: defaultAgent

Get a default agent that connects to mainnet with the anonymous identity.

:link: Source

:gear: createAgent

Create an agent for a given identity

Parameters:

• params: The parameters to create a new HTTP agent
• params.identity: A mandatory identity to use for the agent
• params.host: An optional host to connect to, particularly useful for local development
• params.fetchRootKey: Fetch root key for certificate validation during local development or on testnet
• params.verifyQuerySignatures: Check for signatures in the state tree signed by the node that replies to queries - i.e. certify responses.
• params.retryTimes: Set the number of retries the agent should perform before error.

:link: Source

:gear: createServices

:link: Source

:gear: assertNonNullish

:link: Source

:gear: asNonNullish

:link: Source

:gear: assertPercentageNumber

:link: Source

:gear: uint8ArrayToBigInt

:link: Source

:gear: bigIntToUint8Array

:link: Source

:gear: numberToUint8Array

:link: Source

:gear: arrayBufferToUint8Array

:link: Source

:gear: uint8ArrayToArrayOfNumber

:link: Source

:gear: arrayOfNumberToUint8Array

:link: Source

:gear: asciiStringToByteArray

:link: Source

:gear: hexStringToUint8Array

:link: Source

:gear: uint8ArrayToHexString

:link: Source

:gear: candidNumberArrayToBigInt

:link: Source

:gear: encodeBase32

Encode an Uint8Array to a base32 string.

Parameters:

• input: The input array to encode.

:link: Source

:gear: decodeBase32

Decode a base32 string to Uint8Array.

Parameters:

• input: The input string to decode.
• input: The base32 encoded string to decode.

:link: Source

:gear: uint8ArrayToBase64

Converts a Uint8Array (binary data) to a base64 encoded string.

Parameters:

• uint8Array: - The Uint8Array containing binary data to be encoded.

:link: Source

:gear: base64ToUint8Array

Converts a base64 encoded string to a Uint8Array (binary data).

Parameters:

• base64String: - The base64 encoded string to be decoded.

:link: Source

:gear: bigEndianCrc32

:link: Source

:gear: jsonReplacer

A custom replacer for JSON.stringify that converts specific types not natively supported by the API into JSON-compatible formats.

Supported conversions:

• BigInt → { "__bigint__": string }
• Principal → { "__principal__": string }
• Uint8Array → { "__uint8array__": number[] }

Parameters:

• _key: - Ignored. Only provided for API compatibility.
• value: - The value to transform before stringification.

:link: Source

:gear: jsonReviver

A custom reviver for JSON.parse that reconstructs specific types from their JSON-encoded representations.

This reverses the transformations applied by jsonReplacer, restoring the original types.

Supported conversions:

• { "__bigint__": string } → BigInt
• { "__principal__": string } → Principal
• { "__uint8array__": number[] } → Uint8Array

Parameters:

• _key: - Ignored but provided for API compatibility.
• value: - The parsed value to transform.

:link: Source

:gear: hashObject

Generates a SHA-256 hash from the given object.

The object is first stringified using a custom jsonReplacer, then hashed using the SubtleCrypto API. The resulting hash is returned as a hex string.

Parameters:

• params: - The object to hash.

:link: Source

:gear: hashText

Generates a SHA-256 hash from a plain text string.

The string is UTF-8 encoded and hashed using the SubtleCrypto API. The resulting hash is returned as a hexadecimal string.

Parameters:

• text: - The text to hash.

:link: Source

:gear: secondsToDuration

Convert seconds to a human-readable duration, such as "6 days, 10 hours."

Parameters:

• options: - The options object.
• options.seconds: - The number of seconds to convert.
• options.i18n: - The i18n object for customizing language and units. Defaults to English.

:link: Source

:gear: nowInBigIntNanoSeconds

Returns the current timestamp in nanoseconds as a bigint.

:link: Source

:gear: toBigIntNanoSeconds

Converts a given Date object to a timestamp in nanoseconds as a bigint.

Parameters:

• date: - The Date object to convert.

:link: Source

:gear: debounce

Creates a debounced version of the provided function.

The debounced function postpones its execution until after a certain amount of time has elapsed since the last time it was invoked. This is useful for limiting the rate at which a function is called (e.g. in response to user input or events).

Parameters:

• func: - The function to debounce. It will only be called after no new calls happen within the specified timeout.
• timeout: - The debounce delay in milliseconds. Defaults to 300ms if not provided or invalid.

:link: Source

:gear: toNullable

Converts a value into a Candid-style variant representation of an optional value.

Parameters:

• value: - The value to convert into a Candid-style variant.

:link: Source

:gear: fromNullable

Extracts the value from a Candid-style variant representation of an optional value.

Parameters:

• value: - A Candid-style variant representing an optional value.

:link: Source

:gear: fromDefinedNullable

Extracts the value from a Candid-style variant representation of an optional value, ensuring the value is defined. Throws an error if the array is empty or the value is nullish.

Parameters:

• value: - A Candid-style variant representing an optional value.

:link: Source

:gear: fromNullishNullable

Extracts the value from a nullish Candid-style variant representation.

Parameters:

• value: - A Candid-style variant or undefined.

:link: Source

:gear: principalToSubAccount

Convert a principal to a Uint8Array 32 length. e.g. Useful to convert a canister ID when topping up cycles with the Cmc canister

Parameters:

• principal: The principal that needs to be converted to Subaccount

:link: Source

:gear: smallerVersion

Returns true if the current version is smaller than the minVersion, false if equal or bigger. Tags after patch version are ignored, e.g. 1.0.0-beta.1 is considered equal to 1.0.0.

Parameters:

• params.minVersion: Ex: "1.0.0"
• params.currentVersion: Ex: "2.0.0"

:link: Source

:wrench: Constants

• E8S_PER_TOKEN
• ICPToken

:gear: E8S_PER_TOKEN

:link: Source

:gear: ICPToken

:link: Source

:factory: TokenAmount

Deprecated. Use TokenAmountV2 instead which supports decimals !== 8.

Represents an amount of tokens.

:link: Source

Static Methods

• fromE8s
• fromString
• fromNumber

:gear: fromE8s

Initialize from a bigint. Bigint are considered e8s.

Parameters:

• params.amount: The amount in bigint format.
• params.token: The token type.

:link: Source

:gear: fromString

Initialize from a string. Accepted formats:

1234567.8901 1'234'567.8901 1,234,567.8901

Parameters:

• params.amount: The amount in string format.
• params.token: The token type.

:link: Source

:gear: fromNumber

Initialize from a number.

1 integer is considered E8S_PER_TOKEN

Parameters:

• params.amount: The amount in number format.
• params.token: The token type.

:link: Source

Methods

• toE8s

:gear: toE8s

:link: Source

:factory: TokenAmountV2

Represents an amount of tokens.

:link: Source

Static Methods

• fromUlps
• fromString
• fromNumber

:gear: fromUlps

Initialize from a bigint. Bigint are considered ulps.

Parameters:

• params.amount: The amount in bigint format.
• params.token: The token type.

:link: Source

:gear: fromString

Initialize from a string. Accepted formats:

1234567.8901 1'234'567.8901 1,234,567.8901

Parameters:

• params.amount: The amount in string format.
• params.token: The token type.

:link: Source

:gear: fromNumber

Initialize from a number.

1 integer is considered 10^{token.decimals} ulps

Parameters:

• params.amount: The amount in number format.
• params.token: The token type.

:link: Source

Methods

• toUlps
• toE8s

:gear: toUlps

:link: Source

:gear: toE8s

:link: Source

:factory: Canister

:link: Source

:factory: AgentManager

AgentManager class manages HttpAgent instances for different identities.

It caches agents by identity to optimise resource usage and avoid unnecessary agent creation. Provides functionality to create new agents, retrieve cached agents, and clear the cache when needed.

:link: Source

Static Methods

• create

:gear: create

Static factory method to create a new AgentManager instance.

This method serves as an alternative to directly using the private constructor, making it more convenient to create instances of AgentManager using a simple and clear method.

Parameters:

• config: - Configuration options for the AgentManager instance.
• config.fetchRootKey: - Whether to fetch the root key for certificate validation.
• config.host: - The host to connect to.

:link: Source

Methods

• getAgent
• clearAgents

:gear: getAgent

Get or create an HTTP agent for a given identity.

If the agent for the specified identity has been created and cached, it is retrieved from the cache. If no agent exists for the identity, a new one is created, cached, and then returned.

Parameters:

• identity: - The identity to be used to create the agent.

:link: Source

:gear: clearAgents

Clear the cache of HTTP agents.

This method removes all cached agents, forcing new agent creation on the next request for any identity. Useful when identities have changed or if you want to reset all active connections.

:link: Source

:factory: InvalidPercentageError

:link: Source

:factory: NullishError

:link: Source

:nut_and_bolt: Enum

• FromStringToTokenError

:gear: FromStringToTokenError

v70

Overview

Breaking Changes

• Assert checksum when parsing ICP AccountIdentifier from hex. (*).
• Assert length equals 32 bytes when parsing ICP AccountIdentifier from hex. (*)
• Modify the ICP SubAccount.fromBytes to throw an error instead of returning one when the input length is invalid. (**)
• Migrate @dfinity/zod-schemas to zod/v4.

(*) This fix is not a breaking change per se, but applications that previously accepted invalid account identifiers will now fail. Since that behavior was incorrect, we decided to proceed with the change anyway. If this impacts you, feel free to reach out!

(**) Returning an error was likely a historical artifact. For consistency, we decided to align this behavior with other similar functions.

Features

• Expose method listSubaccounts in class IcrcIndexNgCanister.
• Extend the transform function to support provisional_create_canister_with_cycles when used with PocketIC.
• Add validation to decodeIcrcAccount to reject account strings with more than one . separator.

v69

Overview

Features

• Updated @dfinity/sns to add support for filtering SNS proposals by topics.
• Removed (unused) topic_followee_index in NNS Governance Candid type.
• Added hashObject and hashText utilities to generate a SHA-256 hash from the given object.

Chore

• Upgraded GitHub actions runners to ubuntu-24.04.

v68

Overview

Features

• Add utility isIcpAccountIdentifier to check if a string is a valid ICP account identifier.
• Utility notEmptyString to use a type predicate, ensuring that the input is a string type when it returns true.
• Support disburseMaturity in @dfinity/nns.
• Update @dfinity/ic-management to support optional new setting wasm_memory_threshold and return the new memory_metrics.
• Add neuronMinimumDissolveDelayToVoteSeconds to nns VotingPowerEconomics.
• Expose method status in class IcrcIndexNgCanister.
• Expose method icrc3_get_blocks in class IcrcLedgerCanister.
• Add setFollowing to sns governance canister.
• New service util queryAndUpdate that aids in executing a request and handling the results, for both type of calls.
• Added type predicate to narrow value to undefined, null, or empty string in type guards in util isEmptyString.

2025.03.10-1330Z

Overview

Features

• Add utility toBigIntNanoSeconds to convert Date object to timestamp in nanoseconds bigint.
• Add support to a new type of action SetTopicsForCustomProposals in sns.
• Update Candid files for @dfinity/sns.

2025.02.21-1530Z

Overview

Features

• Support topic and list_topics in @dfinity/sns.

2025.02.19-1030Z

Overview

Features

• Make methods of AgentManager usable after deconstruction.
• Implement pagination for the list_neurons endpoint.
• Update all Candid files to their latest versions.

Build

• Bump esbuild to v0.25.0.

Chore

• Add the zod-schemas library to the list of next versions.

Docs

• Review JSDoc types for Icrc2ApproveRequest.

2025.01.30-0730Z

Overview

Breaking Changes

• Default getIcpToCyclesConversionRate to an update call while providing a certified parameter for queries.

Features

• Support NervousSystemParameters.automatically_advance_target_version in @dfinity/sns.
• Add converters to encode or decode base64 string into Uint8Array.
• Support neuron_subaccounts in list_neurons from @dfinity/nns.

2025.01.20-1800Z

Overview

The current status of the libraries at the time of the release is as follows:

Features

• Support CanisterSettings.wasm_memory_threshold in @dfinity/nns.
• Support UpgradeSnsControlledCanister.chunked_canister_wasm in @dfinity/sns.
• Add utility fromNullishNullable extracts the value from a nullish Candid-style variant representation.

2025.01.20-1030Z

Overview

The current status of the libraries at the time of the release is as follows:

Features

• Expose types IcrcApproveError and IcrcTransferFromError in @dfinity/ledger-icrc.
• Expose few additional did types in @dfinity/ledger-icp.
• Introduce a new zod-schemas library to provide a collection of reusable Zod schemas and validators for common data patterns in ICP applications.
• Api get network economics parameters.
• Update old_list_neurons_service.certified.idl.js.

Fix

• Typo in renamed exposed type IcrcTransferVariatError.

2024.12.23-1215Z

Overview

The current status of the libraries at the time of the release is as follows:

Features

• Support RefreshVotingPower in @dfinity/nns.
• Remove optional field last_deposit_with_subaccount_scraped_block_number from ckETH minter information.
• Add optional field deposit_with_subaccount_helper_contract_address and last_deposit_with_subaccount_scraped_block_number in ckETH minter information.
• Expose a few additional types related to snapshots in ic-management.
• Add support for get_subnet_types_to_subnets to @dfinity/cmc.
• Support VotingPowerEconomics, potential_voting_power and deciding_voting_power in @dfinity/nns.
• Add utility isEmptyString (the opposite of existing notEmptyString).
• Add utility mapTokenMetadata in @dfinity/ledger-icrc to map the token metadata information from a ledger response into a structured record.

2024.11.27-1230Z

Overview

The current status of the libraries at the time of the release is as follows:

Features

• Added definition for AdvanceSnsTargetVersion to the SNS governance DID Action declarations.

Fix

• The IC management function install_chunked_code failed on mainnet because the target_canister was not mapped as effective_canister_id, as defined by the IC specification.

Chore

• Enable eslint for tests.
• Allow linter to permit underscore prefixes.

2024.11.22-1600Z

Overview

The current status of the libraries at the time of the release is as follows:

Breaking changes

• Inherits canister installation code arguments from Candid.

2024.11.21-1600Z

Overview

The current status of the libraries at the time of the release is as follows:

Breaking changes

• Remove stakeNeuronIcrc1.

Features

• Added memoToNeuronSubaccount and memoToNeuronAccountIdentifier.
• Support new neuron field voting_power_refreshed_timestamp_seconds.
• Add support for fetching the canister logs in @dfinity@ic-management.
• Add support for snapshot features in @dfinity@ic-management.
• Add nowInBigIntNanoSeconds to @dfinity/utils, a trivial function that is actually used across all our dapps.

Build

• Update the dev dependencies of the ic-js workspace.

2024.10.29-1130Z

Overview

The current status of the libraries at the time of the release is as follows:

Breaking Changes

• For consistency, the CMCCanister.create function now requires the canisterId option to be provided exclusively as a Principal.

Features

• Add support for get_default_subnets to @dfinity/cmc.
• Add class AgentManager in @dfinity/utils which caches HttpAgent instances for different identities.

Docs

• Rename DFINITY LLC to DFINITY Stiftung in licences.

2024.10.09-1140Z

Overview

The current status of the libraries at the time of the release is as follows:

Build

• Downgrade Agent-js to ^2.0.0 to let consumers pick the compatible version they wish to use.

2024.09.30-1100Z

Overview

The current status of the libraries at the time of the release is as follows:

Breaking changes

• Removed deprecated OpenSnsTokenSwap, SetSnsTokenSwapOpenTimeWindow, and SetDefaultFollowees from ProposalActionRequest.

Features

• Add support for icrc21_canister_call_consent_message to @dfinity/ledger-icp and @dfinity/ledger-icrc.
• Add support for "regtest" in BitcoinNetwork.
• Expose ledger-converters utility modules in @dfinity/ledger-icp and @dfinity/ledger-icrc.

Build

• Incorporate Agent-js patch v2.1.2.

2024.09.02-0830Z

Overview

The current status of the libraries at the time of the release is as follows:

Breaking changes

• Rename values of enum Topic and NnsFunction to match the backend values.
• Use different request/response types for NNS Governance proposals, and different fields for InstallCode proposals.
• The getUtxos parameter filter.min_confirmations has been renamed to filter.minConfirmations for consistency with the general naming conventions used in @dfinity/ckbtc.
• Only queries to getUtxos of the Bitcoin canister can be executed by external users — i.e., update calls can only be performed by the canister. This is why getUtxos now only supports non-certified calls and has been renamed to getUtxosQuery.

Features

• Provide a new utility to convert Candid Nat to BigInt. This utility is useful for interpreting the fees provided by the SNS Aggregator.
• Support conversion of InstallCode, StopOrStartCanister and UpdateCanisterSettings actions, SetVisibility neuron operation, and Neuron::visibility attribute.
• Add function getBalanceQuery to BitcoinCanister object of package @dfinity/ckbtc, that implements the bitcoin_get_balance_query method of the IC Bitcoin API.

Build

• Upgrade agent-js dependencies to v2.0.0.

2024.07.22-0645Z

Overview

The current status of the libraries at the time of the release is as follows:

Features

• Add support for wasm_memory_limit in the canister settings.
• Add optional includeEmptyNeurons parameter to listNeurons.
• Extend eip1559TransactionPrice for Erc20.
• Add "Protocol Canister Management" and "Service Nervous System Management" topics support.
• Add asNonNullish function, like assertNonNullish but returns the value.

Fix

• updateNeuron to not change the neuron subaccount.
• list_neurons to use old ListNeurons type for hardware wallet compatibility.

Build

• Upgrade agent-js dependencies to v1.4.0.

2024.06.11-1630Z

Overview

The current status of the libraries at the time of the release is as follows:

Features

• Update ckETH Candid definition.

Build

• Bump braces.

2024.06.05-0835Z

Overview

The current status of the libraries at the time of the release is as follows:

Breaking changes

• bitcoinGetUtxos and bitcoinGetUtxosQuery have been removed from the @dfinity/ic-management library. Instead, use getUtxos from the new Bitcoin canister exposed in @dfinity/ckbtc to access similar data.

Features

• Support for getUtxos endpoint in the new Bitcoin canister from @dfinity/ckbtc.
• Canister status response extended with query statistics.
• Add metadata function to ledger ICP.
• Add optional parameters to ICP ledger transactionFee.
• Add support for icrc2_approve on the ICP ledger canister in @dfinity/ledger-icp.

2024.05.14-0630Z

Overview

The current status of the libraries at the time of the release is as follows:

Breaking changes

• @dfinity/ic-management function canisterInfo removed because users cannot call this method ( see documentation).
• @dfinity/nns-proto was updated with the most recent proto types, some of which were not backwards compatible.
• The size of the nns-proto-js library has noticeably increased, as it now exposes all types instead of just a manually picked subset.

Features

• Update Candid definition in ckBTC, ckETH, CMC, ICP and ICRC Ledgers, Nns and Sns.
• Add "Subnet Rental" to the list of NnsFunction and to topic support.

Fix

• Fixed TokenAmountV2.fromNumber for tokens with fewer than 8 decimals.

Build

• Upgrade agent-js dependencies to v1.3.0 and revert the default retry times value to 10, given that the issue is fixed.

2024.04.29-0930Z

Overview

The current status of the libraries at the time of the release is as follows:

Breaking changes

• Protocol buffers for hardware wallet transactions are no longer supported. Internet Computer Ledger app 2.4.9 or later is now required.
• GovernanceCanister.listNeurons no longer throws an error when called with certified: false for hardware wallet transactions.
• Potential errors thrown by withdrawEth provide now unparsed details.

Features

• ICP transactions, as provided by the Index canister, have been extended to include their block timestamp information.
• When no fee is specified when making an ICP transaction, use the mandatory fee of 10000 e8s (0.0001 ICP) instead of fetching the fee from the network.
• Remove hardware wallet specific code paths from @dfinity/ledger-icp.
• Remove hardware wallet specific options from LedgerCanister.
• Remove dependency on @dfinity/nns-proto from @dfinity/ledger-icp.
• Remove hardware wallet specific code and @dfinity/nns-proto dependency from @dfinity/nns.
• Add support for withdrawErc20.
• Additional fields related to ERC20 have been added to ckETH minterInfo.
• Expose the function ledger_id for Index canister in the ledger-icrc library.
• Set number of retries to 10 (as opposed to default 3) in createAgent utility to make the agent more resilient against watermark check failures.

Build

• Upgrade agent-js dependencies to v1.2.1. Note that it is advised to set the number of retries of the agent to 10 to prevent the potential issue Timestamp failed to pass the watermark after retrying the configured 3 times. We cannot guarantee the integrity of the response since it could be a replay attack. ( see thread on the forum).
• Upgrade didc to 0.3.7 that converts candid files into JS and TS.

2024.03.25-1430Z

Overview

The current status of the libraries at the time of the release is as follows:

Fix

• Incorrect import path to utils in ic-management: @dfinity/utils/src.

2024.03.25-1345Z

Overview

The current status of the libraries at the time of the release is as follows:

Features

• Support for the installation of large canisters with chunked code of the Wasm module in @dfinity/ic-management.
• Update most recent did files for ledgers (new optional field for initialization) and ckETH (new optional field in event).
• Expose Utxo types in @dfinity/ckbtc.

Build

• Bump dev dependencies including esbuild and TypeScript.

Documentation

• Bump tsdoc-markdown to parse optional result into READMEs.

2024.03.05-1100Z

Overview

The current status of the libraries at the time of the release is as follows:

Breaking Changes

• Fix typo in ic-management interfaces (senderCanisterVerion -> senderCanisterVersion).
• ckETH eip1559TransactionPrice expect a parameters which can optionally be set to execute a query (new) or update call.

Features

• Support for new ckETH endpoint get_minter_info which returns internal minter parameters such as the minimal withdrawal amount, the last observed block number, etc.
• Add support for bitcoin_get_utxos and bitcoin_get_utxos_query features to @dfinity/ic-management library.
• Support for new ckBTC endpoint get_known_utxos which returns UTXOs of the given account known by the minter.
• New IndexNgCanister in @dfinity/ledger-icrc, which can be used to interact with the newer version of the ICRC Index canister, notably exposing getTransactions as a query function.

2024.02.21-0835Z

Overview

The current status of the libraries at the time of the release is as follows:

Breaking changes

• Update listProposals return type in sns governance canister.

Build

• Bump agent-js v1.0.1 to hook on their semantic versioning, adopt last improvements and rollout a security patch

2024.02.14-1600Z

Overview

The current status of the libraries at the time of the release is as follows:

Breaking changes

• Replace duplicate string type AccountIdentifier in @dfinity/nns with AccountIdentifierHex of @dfinity/ledger-icp.

Features

• Extend ckBTC retrieveBtcStatusV2ByAccount with optional account parameter.
• Remove unused Uint8Array type SubAccount in @dfinity/nns.
• Modify the @dfinity/ledger-icp package's SubAccount.formID function to support more than 256 subaccounts, enabling it to handle larger numbers.

Build

• Bump all dev dependencies of the ic-js workspace.

2024.01.30-1600Z

Overview

The current status of the libraries at the time of the release is as follows:

Breaking changes

• Upgrade candid files for cmc canister with new fields subnet_selection and settings.

Features

• Add support for converting ckETH to ETH through the withdrawEth function and integrate useful features such as eip1559TransactionPrice, encodePrincipalToEthAddress, and retrieve_eth_status.
• Upgrade candid files for ic-management canister and support new field reserved_cycles_limit.
• Add "API Boundary Node Management" topic support.
• Add optional field logo to Token type.
• Update sns-js candid files with new fields in sns canisters.
• Add public method toE8s to TokenAmountV2.

Fix

• Various certified Candid IDL functions had their names trimmed of the keyword "query".

Build

• Fixed script to generate certified IDL factory files to respect the keyword "query" when used in functions' names.

2024.01.09-1115Z

Overview

The current status of the libraries at the time of the release is as follows:

Fix

• When @dfinity/ledger-icp is bundled with Rollup v4, it leads to an incompatibility issue with iOS 15.

2024.01.03-1115Z

Overview

The current status of the libraries at the time of the release is as follows:

Features

• Introduces an early first version of @dfinity/cketh, which is meant to provide functions for interfacing with ckETH. The library doesn't do much at the moment, but we're releasing it to integrate it into our pipelines, and features will be added iteratively as required.

2023.12.20-1000Z

Overview

The current status of the libraries at the time of the release is as follows:

Breaking changes

• decimals mandatory field in Token.
• TokenAmount rejects tokens with decimals !== 8.

Features

• Substitute ? fields with Option fields in the converters related to NNS proposals.
• Add retrieveBtcStatus to ckbtc minter canister.
• Add retrieveBtcStatusV2ByAccount to ckbtc minter canister.
• Make uint8ArrayToHexString also accept number[] as input.
• Add a new type TokenAmountV2 which supports decimals !== 8.
• Fix issue when converting token amount from small numbers with TokenAmountV2.
• Bump agent-js to v0.20.2 in a non-breaking manner by introducing verifyQuerySignatures as an opt-in feature (for the time being).
• Replace https://ic0.app by https://icp-api.io as the default host for the default anonymous agent provided by defaultAgent.

Fix

• Utilize ICP Index accountBalance and getTransactions with account identifier hex directly, eliminating the need for conversion with Buffer and resolving usage in non-polyfilled environments.

Operations

• Add a cron job to periodically update IC candid files and typescript bindings.

2023.11.21-1400Z

Overview

The current status of the libraries at the time of the release is as follows:

Features

• Include timestamp and tags in the candid provenance record.
• Update ckbtc candid to ic commit 4de99bc27be74048f80d13200f3c75cf2a43438c.
• Include pending UTXOs in MinterNoNewUtxosError.
• Upgrade didc to 0.3.5 that converts candid files into JS and TS.

2023.10.15-0600Z

Overview

The current status of the libraries at the time of the release is as follows:

Features

• add support for ICP Index canister to library @dfinity/ledger-icp. New IndexCanister functions: accountBalance and getTransactions
• expose few types - notably BlockHeight - for library @dfinity/ledger-icp
• support new fields from swap canister response types: min_direct_participation_icp_e8s, max_direct_participation_icp_e8s and neurons_fund_participation
• support new fields in the CreateServiceNervousSystem proposal action: maximum_direct_participation_icp, minimum_direct_participation_icp and neurons_fund_participation
• support new filter field omit_large_fields in list_proposals
• add support for retrieve_btc_with_approval in @dfinity/ckbtc
• new utility to convert seconds to a human-readable duration
• update @dfinity/ledger-icrc did files
• update @dfinity/sns did files

2023.10.02-1515Z

Overview

The current status of the libraries at the time of the release is as follows:

Release

• ckbtc v1.0.1
• ledger-icp v1.0.0
• ledger-icrc v1.0.0
• nns v2.0.0
• sns v1.0.1

Breaking Changes ⚠️

• ICP ledger-related features have been relocated from @dfinity/nns to a new dedicated library called @dfinity/ledger-icp
• ICRC ledger-related features have been moved as well. The library @dfinity/ledger has been deprecated, renamed, and replaced by @dfinity/ledger-icrc
• remove the ICP class, which was deprecated a long time ago, from @dfinity/nns. Instead, utilize the token parsers from @dfinity/utils

Build

• @dfinity/sns inherits the changes and now requires @dfinity/ledger-icrc as a peer dependency
• @dfinity/nns inherits the changes and now requires @dfinity/ledger-icp as a peer dependency

Chore

• minter params Subaccount declared as Uint8Array instead of inheriting a type

1.0.0 (2023-10-02)

Release

• nns v1.0.0
• sns v1.0.0
• cmc v1.0.0
• ledger v1.0.0
• ckBTC v1.0.0
• ic-management v1.0.0
• utils v1.0.0
• nns-proto v1.0.0

Features

• add support for icrc2_transfer_from, icrc2_approve and icrc2_allowance in @dfinity/ledger
• update index did definitions in ledger which provides more information in the transactions
• add support for icrc1_transfer on the ICP ledger canister in @dfinity/nns

Build

• bump did files in Cmc
• starting from this version, we commit to adhering to semantic versioning for any libraries published in ic-js

0.18.4 (2023-09-05)

Release

• nns v0.16.7
• sns v0.0.22
• cmc v0.0.18
• ledger v0.0.15
• ckBTC v0.0.11
• ic-management v0.0.8
• utils v0.0.22
• nns-proto v0.0.8

Features

• replaces the js-sha256 library with @noble/hashes

0.18.3 (2023-09-04)

Release

• nns v0.16.6
• sns v0.0.21
• cmc v0.0.17
• ledger v0.0.14
• ckBTC v0.0.10
• ic-management v0.0.7
• utils v0.0.21
• nns-proto v0.0.7

Fix

• bump agent-js v0.19.2 to fix evaluation of subdomain when host is not specified

Build

• remove unused dependencies in @dfinity/ic-management

0.18.2 (2023-08-24)

Release

• nns v0.16.5
• sns v0.0.20
• cmc v0.0.16
• ledger v0.0.13
• ckBTC v0.0.9
• ic-management v0.0.6
• utils v0.0.20
• nns-proto v0.0.6

Features

• Reviver and replacer to interpret BigInt, Principal, and Uint8Array in JSON.stringify|parse
• Add Sns disburse maturity function

Build

• bump agent-js v0.19.1

0.18.1 (2023-08-07)

Release

• nns v0.16.4
• sns v0.0.19
• cmc v0.0.15
• ledger v0.0.12
• ckBTC v0.0.8
• ic-management v0.0.5
• utils v0.0.19
• nns-proto v0.0.5

Features

• update nns/governance.did and sns_wasm.did for 1-proposal
• update ic.did for @dfinity/ic-management
• update icrc1_ledger.did

Build

• bump agent-js v0.18.1

Docs

• add mention that ICRC-22 is currently a draft

0.18.0 (2023-07-03)

Release

• nns v0.16.3
• sns v0.0.18
• cmc v0.0.14
• ledger v0.0.11
• ckBTC v0.0.7
• ic-management v0.0.4
• utils v0.0.18
• nns-proto v0.0.4

Breaking Changes

• move convertStringToE8s and TokenAmount from Nns package to @dfinity/utils
• retire TokenAmount.toProto()

Features

• add a new utils function decodePayment to the @dfinity/ledger library. Useful to decode payment through QR code that contains target address and amount
• add provisional create canister with cycles method
• CreateServiceNervousSystem <-> RawCreateServiceNervousSystem transformations for Nns proposal
• decode payment code (early support and not yet specified. see ICRC-22)

Build

• bump semver

0.17.2 (2023-06-21)

Release

• ic-management v0.0.3

Build

No particular changes. Resolve a version conflicts in npmjs.

0.17.1 (2023-06-21)

Release

• nns v0.16.2
• sns v0.0.17
• cmc v0.0.13
• ledger v0.0.10
• ckBTC v0.0.6
• ic-management v0.0.2
• utils v0.0.17
• nns-proto v0.0.3

Fix

• redo global polyfill for the browser
• expose more types in new library ic-management-js

Build

• fix ic-management-js next dependencies and version

Docs

• various improvements in READMEs

0.17.0 (2023-06-20)

Release

• nns v0.16.1
• sns v0.0.16
• cmc v0.0.12
• ledger v0.0.9
• ckBTC v0.0.5
• ic-management v0.0.1
• utils v0.0.16
• nns-proto v0.0.2

Breaking Changes

• ckBTC getDepositFee has been deprecated. Instead, use the new feature getMinterInfo

Features

• introducing @dfinity/ic-management — a new library for interfacing with IC management canister
• add getMinterInfo for ckBTC which returns internal minter parameters such as the minimal amount to retrieve BTC, minimal number of confirmations or KYT fee
• add fee to nns stake neuron method
• expose Sns index canister id in wrapper
• add simulateMergeNeurons to Nns governance

Refactor

• use isNullish and fromNullable utils in Nns governance.canister.ts

Build

• remove global polyfill for the browser and add worker conditions to bundle
• improve docs generation in the CI
• update Candid types in Nns

Docs

• improve Sns README
• generate README docs for BTC utils

0.16.0 (2023-05-24)

Release

• nns v0.16.0
• sns v0.0.15
• cmc v0.0.11
• ledger v0.0.8
• ckBTC v0.0.4
• utils v0.0.15
• nns-proto v0.0.1

Breaking Changes

• the protobuf dependencies of @dfinity/nns have been extracted to a new peer dependency called @dfinity/nns-proto. In the NNS-dapp, we manually chunk the libraries. This change enables the dapp to load the required code of the hardware wallet only when necessary.

Features

• update sns-js and nns-js candid definitions
• add BitcoinSetConfig to enum NnsFunction
• expose some more Sns types

Build

• publish provenance to npm
• do not run size checker on main branch

Docs

• fix sample in nns-js README

0.15.1 (2023-04-18)

Release

• nns v0.15.1
• sns v0.0.14
• cmc v0.0.10
• ledger v0.0.7
• ckBTC v0.0.3
• utils v0.0.14

Fix

• correct absolute utils import in ledger library

0.15.0 (2023-04-18)

Release

• nns v0.15.0
• sns v0.0.13
• cmc v0.0.9
• ledger v0.0.6
• ckBTC v0.0.2
• utils v0.0.13

Features

• new utils moved from NNS-dapp: isNullish, nonNullish, notEmptyString and debounce
• added ckBTC updateBalance, getWithdrawalAccount, retrieveBtc, estimateWithdrawalFee and getDepositFee functions
• parse and validate bitcoin address
• review textual encoding for ICRC-1 account as in dfinity/ICRC-1#98
• add SNS action converters
• get latest reward event NNS Governance
• extend nnsFuncton enum with UpdateElectedReplicaVersions
• add total tokens supply endpoint
• new utils to convert hex to/from uint8array, crc and base32

Build

• bump agent-js v0.15.4
• bump all dev dependencies
• hook size limit plugin to check the size of the libraries with the CI

0.14.0 (2023-02-07)

Release

• nns v0.14.0
• sns v0.0.12
• cmc v0.0.8
• ledger v0.0.5
• ckBTC v0.0.1
• utils v0.0.12

Breaking changes

• index canister moved from @dfinity/sns to @dfinity/ledger
• related classes and types renamed from Sns... to Icrc...

Features

• new @dfinity/ckbtc library for interfacing with ckBTC on the Internet Computer
• export a constant for the Icrc1 metadata logo
• move and expose assertPercentageNumber to lib @dfinity/utils
• register Sns vote

Build

• fix utils as peer dependency for cmc
• fix sns using nns dependencies
• bump all dev dependencies
• bump Nns dependencies
• dependabot patch for json5 v1.0.2

0.13.0 (2023-01-28)

Release

• nns v0.13.0
• sns v0.0.11
• cmc v0.0.7
• ledger v0.0.4
• utils v0.0.11

Features

• add fee as param in SNS Stake neuron
• extend NnsFunction enum with InsertSnsWasmUpgradePathEntries

Fix

• encode ICRC-1 accounts

0.12.1 (2023-01-24)

Release

• nns v0.12.1
• sns v0.0.10
• cmc v0.0.6
• ledger v0.0.3
• utils v0.0.10

Fix

• utils was wrongly referenced as a dependency instead of peer-dependency in last release of cmc

0.12.0 (2023-01-24)

Release

• nns v0.12.0
• sns v0.0.9
• cmc v0.0.5
• ledger v0.0.1
• utils v0.0.8

Breaking Changes

Introducing @dfinity/ledger — A library for interfacing with ICRC ledgers on the Internet Computer.

An ICRC-1 ledger is not only used in Sns projects but, in ckBTC too. It can also be integrated in various other scenario need by developers on the IC.

That's why we are launching this new library and why we refactored Sns ledger related features to create this new library.

De facto, @dfinity/ledger becomes a peer dependency of @dfinity/sns.

Features

• enable merge neurons for HW controlled neurons

0.11.0 (2023-01-23)

Release

• nns v0.11.0
• sns v0.0.8
• cmc v0.0.4
• utils v0.0.7

Features

• new Sns features: increase stake neuron, split neuron, list and get proposals
• add support for the param to_account when disbursing Sns neuron
• add createAt param for Nns ledger transfers
• more Sns voting permissions

Build

• bump agent-js peer dependencies to v0.15.1
• bump Nns (crc and google-protobuf) dependencies
• bump dev dependencies

0.10.0 (2022-12-06)

Release

• nns v0.10.0
• sns v0.0.7
• cmc v0.0.3
• utils v0.0.6

Features

• various neuron features for Sns - e.g. stake neuron, list and set followees, set dissolve delay, stake maturity etc.
• array utilities bigIntToUint8Array and numberToUint8Array
• semantic version comparator smallerVersion

Fix

• rounding conversion from number to Token

0.9.0 (2022-10-31)

Release

• nns v0.9.0
• sns v0.0.6
• cmc v0.0.2
• utils v0.0.5

Breaking changes

• token param in TokenAmount factory methods is mandatory instead of using ICPToken as default.
• TokenAmount.fromNumber does not return FromStringToTokenError, only TokenAmount.

Features

• new NNS governance features: stakeMaturity and autoStakeMaturity
• various additional new NNS functions and proposal types
• new SNS index canister
• new SNS ledger and wrapper feature: transfer and transactionFee
• SNS did files updated with most recent commit in IC repo
• support join community fund for neurons controlled by Hardware Wallet.

Build

• bump dev dependencies
• bump agent-js peer dependencies v0.14.0

Docs

• refreshed HACKING.md

0.8.0 (2022-09-26)

Release

• nns v0.8.1
• sns v0.0.5
• cmc v0.0.1
• utils v0.0.4

Breaking changes

• the development dependency didc has been bumped which leads to some types having to be converted from number[] to Uint8Array
• new fields stakedMaturityE8sEquivalent and autoStakeMaturity in Neuron

Features

• new library @dfinity/cmc
• new nns governance commands and actions: ChangeAutoStakeMaturity, SetSnsTokenSwapOpenTimeWindow and OpenSnsTokenSwap
• some new utilities added to transform arrays from various format to Uint8Array
• new Sns utilities to encode and decode accounts to and from strings
• disburse Sns neurons
• createAgent and principalToSubAccount added to utils

0.7.0 (2022-09-19)

Release

• nns v0.7.0
• sns v0.0.3
• utils v0.0.2

Breaking changes

• agent-js dependencies set as peerDependencies
• Sns canisters' classes renamed with prefix Sns
• enums renamed with Pascal case for consistency reason

Features

• new library @dfinity/utils
• more Sns related features: notifyParticipation, getUserCommitment, some Sns neurons related features and governance metadata
• new nns governance features: setDissolveDelay and setNodeProviderAccount
• new generic interface Token and class TokenAmount
• class ICP set as deprecated

Build

• bump agent-js v0.13.1
• publish next instead of nightly-build working versions
• add manual trigger to GitHub Actions for npm publish

0.6.0 (2022-07-20)

Release

• nns v0.6.0
• sns v0.0.2

Breaking Changes

• nns library esm canisters chunks renamed with suffix .canister

Features

• new library @dfinity/sns
• add SetSnsTokenSwapOpenTimeWindow proposal action support to request and response converters
• add new property in Neuron type: spawn_at_timestamp_seconds
• use the governance canister id of the class in converters. This allows to also have proper conversion on testnets.
• add leaveCommunityFund functionality to governance canister in @dfinity/nns.
• map deadline_timestamp_seconds to proposal object
• new NNS proposal topic SnsDecentralizationSale

Fix

• fix how the neuron account was converted to a string for proto.

Build

• bump dependencies including agent-js v0.12.0
• rename repo from nns-js to ic-js
• transform repo into a mono-repo for packages nns, sns and in the future more libraries

0.5.0 (2022-06-23)

Breaking

• Change "fromSubAccountId: string" param to "fromSubAccount: number[]"

Features

• Remove payload, payloadBytes and nnsFunctionName fields from proposal of type ExecuteNnsFunction action (moved to nns-dapp)
• Use Candid interface by default for ledger canister and proto for hardware wallet
• New function transactionFee to query the current transaction fee

0.4.3 (2022-06-01)

Features

• update most recent candid payloads

Build

• bump agent-js v0.11.3 with setBigUint64 for iOS < v15

0.4.1 - 0.4.2 (2022-05-23)

Features

• new methods disburse, mergeMaturity and spawnNeuron
• expose account utilities
• expose account identifier utilities
• update most recent candid payloads
• remove principal toJSON workaround
• Hardware wallet compatibility with protobuf
• add support for GenesisTokenCanister::claim_neurons

Build

• bump dependencies

0.4.0 (2022-04-22)

Breaking Changes

• Replace notVotedNeurons with votableNeurons [#77]
• Serialize Principal rather than a byte array in JSON.
• Allow neurons with zero stake to pass through the filter.

Features

• New methods splitNeuron, mergeNeurons, addHotkey and removeHotkey in Governance Service.
• Add options memo and fee to ledger transfer function for hardware wallet compatibility.
• Add votableNeurons(..) utility function.
• Update dependencies and stop using now deprecated functions.

0.3.0 (2022-04-07)

Breaking Changes

• variant return types dropped - i.e. functions now return effective result and throw errors in case of issues [#59]
• governance function getNeurons to listNeurons renamed [#55]
• governance functions getNeurons and listNeurons change signature [#69]
• Drop isCurrentUserController property from Neuron type [#69]
• remove some converters that were not use internally [#62]

Features

• governance new functions:
  • getProposal
  • stakeNeuron
  • registerVote
  • increaseDissolveDelay
  • getNeuron
  • setFollowees
• ledger transfer enhanced with support for subaccount
• new utils to filter voted neurons and proposals
• export common types

Build

• nns-dapp canister types removed
• nightly build job

Tests

• add test for protobuf files