ledger-js
A library for interfacing with ICRC ledger on the Internet Computer.
Table of contents
Installation
You can use ledger-js
by installing it in your project.
npm i @dfinity/ledger
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 LedgerCanister
. It has to be instantiated with a canister ID.
e.g. fetching a token metadata.
import { IcrcLedgerCanister } from "@dfinity/ledger";
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-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 }
⚙️ 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
⚙️ 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; } |
Parameters:
-
code
: string
🏭 IcrcLedgerCanister
Methods
⚙️ create
Method | Type |
---|---|
create |
(options: IcrcLedgerCanisterOptions<_SERVICE>) => IcrcLedgerCanister |
⚙️ metadata
The token metadata (name, symbol, etc.).
Method | Type |
---|---|
metadata |
(params: QueryParams) => Promise<IcrcTokenMetadataResponse> |
⚙️ transactionFee
The ledger transaction fees.
Method | Type |
---|---|
transactionFee |
(params: QueryParams) => Promise<bigint> |
⚙️ 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.
⚙️ transfer
Transfers tokens from the sender to the given account.
Method | Type |
---|---|
transfer |
(params: TransferParams) => Promise<bigint> |
Parameters:
-
params
: The parameters to transfer tokens.
⚙️ totalTokensSupply
Returns the total supply of tokens.
Method | Type |
---|---|
totalTokensSupply |
(params: QueryParams) => Promise<bigint> |
⚙️ 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.
⚙️ 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.
⚙️ 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.
🏭 IcrcIndexCanister
Methods
⚙️ create
Method | Type |
---|---|
create |
(options: IcrcLedgerCanisterOptions<_SERVICE>) => IcrcIndexCanister |
⚙️ 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> |