Skip to main content

Using an ICRC-1 ledger

Intermediate
Tutorial

There are three primary methods used to interact with an ICRC-1 ledger:

  • dfx canister: The generic canister call from dfx used to call a canister's methods.

  • ic-cdk: Inter-canister calls for the ICRC-1 ledger.

  • ledger-icrc-js: A library for interfacing with an ICRC-1 ledger on the Internet Computer.

Interact with an ICRC-1 canister using dfx canister call​

ICRC-1​

Use the following command syntax to interact with an ICRC-1 ledger via dfx canister:

dfx canister call <canister-id> <method-name> <arguments>

For example, to fetch the token symbol of an ICRC-1 ledger, call the icrc1_symbol method:

dfx canister call ss2fx-dyaaa-aaaar-qacoq-cai icrc1_symbol '()'

Whether your ICRC-1 ledger will have all available methods enabled will depend on if you choose to support any of the extensions of ICRC-1 (ICRC-2, ICRC-3,...).

You can always check which standards are supported by a certain ICRC-1 ledger by calling:

dfx canister call <canister-id> icrc1_supported_standards '()'

You can find all available methods for your ICRC-1 ledger within the ICRC-1 ledger canister's Candid file or, if your ICRC-1 ledger has been deployed to the mainnet, view your ICRC-1 ledger canister on the dashboard. An example of an ICRC-1 ledger deployed on the mainnet that you can reference is the ckETH ledger canister.

View the dfx canister call documentation for more information on calling canister methods.

ICRC-2​

For ledgers that support ICRC-2, you can call ICRC-2 methods. ICRC-2 methods include those for approve workflows. For specifics, see the ICRC-2 standard.

View the dfx canister call documentation for more information on calling canister methods.

Interacting with an ICRC-1 ledger from your web application (ledger-icrc-js)​

View specifications and examples on how to use the ledger-icrc-js library to interact with ICRC-1 ledgers.

Interacting with an ICRC-1 ledger from another canister (inter-canister calls via ic-cdk)​

View the [inter-canister call documentation] (/docs/developer-docs/backend/rust/intercanister) to see how you can call one canister from within another.

Here is an example of how to fetch the token name from the ICP ledger using Rust and the ic-cdk library from within a canister:

// You will need the canister ID of the ICRC ledger.

let ledger_id = Principal::from_text("ss2fx-dyaaa-aaaar-qacoq-cai").unwrap();

// The request object of the `icrc1_name` endpoint is empty.

    let req = ();
    let (res,): (String,) =
        ic_cdk::call(ledger_id, "icrc1_name", (req,))
            .await.unwrap();

You can find all available methods for your ICRC-1 ledger within the ICRC-1 ledger canister's Candid file or, if your ICRC-1 ledger has been deployed to the mainnet, view your ICRC-1 ledger canister on the dashboard. An example of an ICRC-1 ledger deployed on the mainnet that you can reference is the ckETH ledger canister.

icrc-ledger-types Rust crate​

To interact with the ICRC-1 and ICRC-2 endpoints, the Rust crate icrc-ledger-types can be used. This is true for the ICP ledger as well as any other canister that supports ICRC-1 or any of the ICRC-1 extension standards (i.e., ICRC-2, ICRC-3,...).

The crate can be installed with the command:

cargo add icrc-ledger-types

Or, it can be added to the Cargo.toml file:

icrc-ledger-types = "0.1.1"

View the documentation for this crate.