@dfinity/ledger-icrc

ledger-icrc-js

A library for interfacing with ICRC ledger on the Internet Computer.

Table of contents

• Installation
• Usage
• Features
• Resources

Installation

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

npm i @dfinity/ledger-icrc

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

npm i @icp-sdk/core @dfinity/utils

Usage

The features are available through the class IcrcLedgerCanister. It has to be instantiated with a canister ID.

e.g. fetching a token metadata.

import { IcrcLedgerCanister } from "@dfinity/ledger-icrc";
import { createAgent } from "@dfinity/utils";

const agent = await createAgent({
  identity,
  host: HOST,
});

const { metadata } = IcrcLedgerCanister.create({
  agent,
  canisterId: MY_LEDGER_CANISTER_ID,
});

const data = await metadata({});

Features

ledger-icrc-js implements following features:

:toolbox: Functions

• encodeIcrcAccount
• decodeIcrcAccount
• mapTokenMetadata
• decodePayment

:gear: encodeIcrcAccount

Encodes an Icrc-1 account compatible into a string. Formatting Reference: https://github.com/dfinity/ICRC-1/blob/main/standards/ICRC-1/TextualEncoding.md

Function	Type
encodeIcrcAccount	({ owner, subaccount, }: IcrcAccount) => string

Parameters:

• account: : Principal, subaccount?: Uint8Array }

Returns:

string

:link: Source

:gear: decodeIcrcAccount

Decodes a string into an Icrc-1 compatible account. Formatting Reference: https://github.com/dfinity/ICRC-1/blob/main/standards/ICRC-1/TextualEncoding.md

Function	Type
decodeIcrcAccount	(accountString: string) => IcrcAccount

Parameters:

• accountString: string

Returns:

IcrcAccount { owner: Principal, subaccount?: Uint8Array }

:link: Source

:gear: mapTokenMetadata

Maps the token metadata information from a ledger response into a structured record.

This utility processes an array of metadata key-value pairs provided by the ledger and extracts specific fields, such as symbol, name, fee, decimals, and logo. It then constructs a IcrcTokenMetadata record. If any required fields are missing, the function returns undefined.

Function	Type
mapTokenMetadata	(response: IcrcTokenMetadataResponse) => IcrcTokenMetadata or undefined

Parameters:

• response: - An array of key-value pairs representing token metadata.

Returns:

• A structured metadata record or undefined if required fields are missing.

:link: Source

:gear: decodePayment

👀 This feature is currently in draft. You can find more information about it at https://github.com/dfinity/ICRC/issues/22.

A naive implementation of a payment parser. Given a code, the function attempts to extract a token name, account identifier (textual representation), and an optional amount.

If the code doesn't match the expected pattern, undefined is returned for simplicity. Similarly, if an optional amount is provided but it's not a valid number, the parser will not throw an exception and returns undefined.

Please note that this function doesn't perform any validity checks on the extracted information. It does not verify if the token is known or if the identifier is a valid address.

urn            = token ":" address [ "?" params]
token         = [ ckbtc / icp / chat / bitcoin / ethereum ... ]
address       = STRING
params        = param [ "&" params ]
param         = [ amountparam ]
amountparam   = "amount=" *digit [ "." *digit ]

Function	Type
decodePayment	(code: string) => { token: string; identifier: string; amount?: number or undefined; } or undefined

Parameters:

• code: string

Returns:

: string; identifier: string; amount?: number } | undefined

:link: Source

:factory: IcrcCanister

:link: Source

Methods

• balance

:gear: balance

Returns the balance for a given account provided as owner and with optional subaccount.

Method	Type
balance	(params: BalanceParams) => Promise<bigint>

Parameters:

• params: The parameters to get the balance of an account.

Returns:

The balance of the given account.

:link: Source

:factory: IcrcLedgerCanister

:link: Source

Static Methods

• create

:gear: create

Method	Type
create	(options: IcrcLedgerCanisterOptions<_SERVICE>) => IcrcLedgerCanister

:link: Source

Methods

• metadata
• transactionFee
• balance
• transfer
• totalTokensSupply
• transferFrom
• approve
• allowance
• consentMessage
• getBlocks
• getIndexPrincipal
• icrc1SupportedStandards
• icrc10SupportedStandards
• getMintingAccount

:gear: metadata

The token metadata (name, symbol, etc.).

Method	Type
metadata	(params: QueryParams) => Promise<IcrcTokenMetadataResponse>

:link: Source

:gear: transactionFee

The ledger transaction fees.

Method	Type
transactionFee	(params: QueryParams) => Promise<bigint>

Returns:

The ledger transaction fees in Tokens

:link: Source

:gear: balance

Returns the balance for a given account provided as owner and with optional subaccount.

Method	Type
balance	(params: BalanceParams) => Promise<bigint>

Parameters:

• params: The parameters to get the balance of an account.

Returns:

The balance of the given account.

:link: Source

:gear: transfer

Transfers tokens from the sender to the given account.

Method	Type
transfer	(params: TransferParams) => Promise<bigint>

Parameters:

• params: The parameters to transfer tokens.

:link: Source

:gear: totalTokensSupply

Returns the total supply of tokens.

Method	Type
totalTokensSupply	(params: QueryParams) => Promise<bigint>

:link: Source

:gear: transferFrom

Transfers a token amount from the from account to the to account using the allowance of the spender's account (SpenderAccount = { owner = caller; subaccount = spender_subaccount }). The ledger draws the fees from the from account.

Reference: https://github.com/dfinity/ICRC-1/blob/main/standards/ICRC-2/README.md#icrc2_transfer_from

Method	Type
transferFrom	(params: TransferFromParams) => Promise<bigint>

Parameters:

• params: The parameters to transfer tokens from to.

:link: Source

:gear: approve

This method entitles the spender to transfer token amount on behalf of the caller from account { owner = caller; subaccount = from_subaccount }.

Reference: https://github.com/dfinity/ICRC-1/blob/main/standards/ICRC-2/README.md#icrc2_approve

Method	Type
approve	(params: ApproveParams) => Promise<bigint>

Parameters:

• params: The parameters to approve.

:link: Source

:gear: allowance

Returns the token allowance that the spender account can transfer from the specified account, and the expiration time for that allowance, if any.

Reference: https://github.com/dfinity/ICRC-1/blob/main/standards/ICRC-2/README.md#icrc2_allowance

Method	Type
allowance	(params: AllowanceParams) => Promise<Allowance>

Parameters:

• params: The parameters to call the allowance.

Returns:

The token allowance. If there is no active approval, the ledger MUST return { allowance = 0; expires_at = null }.

:link: Source

:gear: consentMessage

Fetches the consent message for a specified canister call, intended to provide a human-readable message that helps users make informed decisions.

Method	Type
consentMessage	(params: Icrc21ConsentMessageParams) => Promise<icrc21_consent_info>

Parameters:

• params: - The request parameters containing the method name, arguments, and consent preferences (e.g., language).

Returns:

• A promise that resolves to the consent message response, which includes the consent message in the specified language and other related information.

:link: Source

:gear: getBlocks

Fetches the blocks information from the ledger canister,

Method	Type
getBlocks	(params: GetBlocksParams) => Promise<GetBlocksResult>

Parameters:

• params: The parameters to get the blocks.

Returns:

The list of blocks.

:link: Source

:gear: getIndexPrincipal

Returns the principal of the index canister for the ledger, if one was defined as such.

Method	Type
getIndexPrincipal	(params: QueryParams) => Promise<Principal>

Returns:

The principal of the index canister.

:link: Source

:gear: icrc1SupportedStandards

Returns the list of standards this ledger supports by using icrc1_supported_standards.

Method	Type
icrc1SupportedStandards	(params: QueryParams) => Promise<StandardRecord[]>

Returns:

The list of standards.

:link: Source

:gear: icrc10SupportedStandards

Returns the list of standards this ledger supports by using icrc10_supported_standards.

Method	Type
icrc10SupportedStandards	(params: QueryParams) => Promise<{ url: string; name: string; }[]>

Returns:

The list of standards.

:link: Source

:gear: getMintingAccount

Returns the minting account of the Ledger canister.

Method	Type
getMintingAccount	(params: QueryParams) => Promise<Nullable<Account>>

Returns:

The minting account as a Nullable object.

:link: Source

:factory: IcrcIndexCanister

:link: Source

Static Methods

• create

:gear: create

Method	Type
create	(options: IcrcLedgerCanisterOptions<_SERVICE>) => IcrcIndexCanister

:link: Source

Methods

• getTransactions
• ledgerId

:gear: getTransactions

Get the transactions of an account

Always certified. get_account_transactions needs to be called with an update because the index canisters makes a call to the ledger canister to get the transaction data. Index Canister only holds the transactions ids in state, not the whole transaction data.

Method	Type
getTransactions	(params: GetAccountTransactionsParams) => Promise<GetTransactions>

:link: Source

:gear: ledgerId

Returns the ledger canister ID related to the index canister.

Method	Type
ledgerId	(params: QueryParams) => Promise<Principal>

:link: Source

:factory: IcrcIndexNgCanister

:link: Source

Static Methods

• create

:gear: create

Method	Type
create	(options: IcrcLedgerCanisterOptions<_SERVICE>) => IcrcIndexNgCanister

:link: Source

Methods

• getTransactions
• ledgerId
• status
• listSubaccounts

:gear: getTransactions

Get the transactions of an account.

Method	Type
getTransactions	({ certified, ...rest }: GetIndexNgAccountTransactionsParams) => Promise<GetTransactions>

Parameters:

• params: The parameters to get the transactions of an account.

Returns:

The list of transactions and further related information of the given account.

:link: Source

:gear: ledgerId

Returns the ledger canister ID related to the index canister.

Method	Type
ledgerId	(params: QueryParams) => Promise<Principal>

:link: Source

:gear: status

Returns the status of the index canister.

Method	Type
status	(params: QueryParams) => Promise<Status>

Parameters:

• params: The parameters to get the status of the index canister.

Returns:

The status of the index canister.

:link: Source

:gear: listSubaccounts

Returns the list of subaccounts for a given owner.

Method	Type
listSubaccounts	({ certified, ...rest }: ListSubaccountsParams) => Promise<SubAccount[]>

Parameters:

• params: The parameters to get the list of subaccounts.

Returns:

The list of subaccounts.

:link: Source

Resources

• Ledger & Tokenization Working Group Standards
• ICRC-1 Ledger