A library for interfacing with ICRC ledger on the Internet Computer.
You can use ledger-icrc-js by installing it in your project.
npm i @dfinity/ledger-icrcThe 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/utilsThe 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({});ledger-icrc-js implements following features:
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 }
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
👀 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 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.
| Method | Type |
|---|---|
create |
(options: IcrcLedgerCanisterOptions<_SERVICE>) => IcrcLedgerCanister |
The token metadata (name, symbol, etc.).
| Method | Type |
|---|---|
metadata |
(params: QueryParams) => Promise<IcrcTokenMetadataResponse> |
The ledger transaction fees.
| Method | Type |
|---|---|
transactionFee |
(params: QueryParams) => Promise<bigint> |
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.
Transfers tokens from the sender to the given account.
| Method | Type |
|---|---|
transfer |
(params: TransferParams) => Promise<bigint> |
Parameters:
-
params: The parameters to transfer tokens.
Returns the total supply of tokens.
| Method | Type |
|---|---|
totalTokensSupply |
(params: QueryParams) => Promise<bigint> |
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.
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.
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.
| Method | Type |
|---|---|
create |
(options: IcrcLedgerCanisterOptions<_SERVICE>) => IcrcIndexCanister |
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> |
| Method | Type |
|---|---|
create |
(options: IcrcLedgerCanisterOptions<_SERVICE>) => IcrcIndexNgCanister |
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.