Skip to content

Latest commit

 

History

History

ledger-icrc

Folders and files

NameName
Last commit message
Last commit date

parent directory

..
candid
candid
 
 
src
src
 
 
LICENSE
LICENSE
 
 
README.md
README.md
 
 
esbuild.mjs
esbuild.mjs
 
 
jest.config.js
jest.config.js
 
 
package.json
package.json
 
 
tsconfig.json
tsconfig.json
 
 

README.md

ledger-icrc-js

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

npm version GitHub license

Table of contents

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:

🧰 Functions

⚙️ 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 }

🔗 Source

⚙️ 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

🔗 Source

⚙️ decodePayment

👀 This feature is currently in draft. You can find more information about it at dfinity/ICRC#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

🔗 Source

🏭 IcrcCanister

🔗 Source

Methods

⚙️ 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.

🔗 Source

🏭 IcrcLedgerCanister

🔗 Source

Methods

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

🔗 Source

⚙️ metadata

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

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

🔗 Source

⚙️ transactionFee

The ledger transaction fees.

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

🔗 Source

⚙️ 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.

🔗 Source

⚙️ transfer

Transfers tokens from the sender to the given account.

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

Parameters:

  • params: The parameters to transfer tokens.

🔗 Source

⚙️ totalTokensSupply

Returns the total supply of tokens.

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

🔗 Source

⚙️ 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.

🔗 Source

⚙️ 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.

🔗 Source

⚙️ 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.

🔗 Source

⚙️ 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).

🔗 Source

🏭 IcrcIndexCanister

🔗 Source

Methods

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

🔗 Source

⚙️ 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>

🔗 Source

⚙️ ledgerId

Returns the ledger canister ID related to the index canister.

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

🔗 Source

🏭 IcrcIndexNgCanister

🔗 Source

Methods

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

🔗 Source

⚙️ 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.

🔗 Source

⚙️ ledgerId

Returns the ledger canister ID related to the index canister.

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

🔗 Source

Resources