@dfinity/ledger-icrc v2.6.2

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 @dfinity/agent @dfinity/candid @dfinity/principal @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
• 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

Parameters:

• account: : Principal, subaccount?: Uint8Array }

: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

Parameters:

• accountString: string

: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 ]

Parameters:

• code: string

:link: Source

:factory: IcrcCanister

:link: Source

Methods

• balance

:gear: balance

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

Parameters:

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

:link: Source

:factory: IcrcLedgerCanister

:link: Source

Methods

• create
• metadata
• transactionFee
• balance
• transfer
• totalTokensSupply
• transferFrom
• approve
• allowance
• consentMessage

:gear: create

:link: Source

:gear: metadata

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

:link: Source

:gear: transactionFee

The ledger transaction fees.

:link: Source

:gear: balance

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

Parameters:

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

:link: Source

:gear: transfer

Transfers tokens from the sender to the given account.

Parameters:

• params: The parameters to transfer tokens.

:link: Source

:gear: totalTokensSupply

Returns the total supply of tokens.

: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

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

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

Parameters:

• params: The parameters to call the allowance.

: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.

Parameters:

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

:link: Source

:factory: IcrcIndexCanister

:link: Source

Methods

• create
• getTransactions
• ledgerId

:gear: create

:link: Source

: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.

:link: Source

:gear: ledgerId

Returns the ledger canister ID related to the index canister.

:link: Source

:factory: IcrcIndexNgCanister

:link: Source

Methods

• create
• getTransactions
• ledgerId

:gear: create

:link: Source

:gear: getTransactions

Get the transactions of an account.

Parameters:

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

:link: Source

:gear: ledgerId

Returns the ledger canister ID related to the index canister.

:link: Source

Resources

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