From 2004660df81c84be995ab5b3b67da66f934c46a0 Mon Sep 17 00:00:00 2001 From: Jessie Mongeon Date: Thu, 12 Dec 2024 16:49:02 -0600 Subject: [PATCH] using the ledger guides --- .../tokens/ledger/setup/icp_ledger_setup.mdx | 100 +++--- .../ledger/setup/icrc1_ledger_setup.mdx | 38 +-- .../tokens/ledger/usage/icp_ledger_usage.mdx | 298 ++++-------------- .../ledger/usage/icrc1_ledger_usage.mdx | 205 +++--------- 4 files changed, 168 insertions(+), 473 deletions(-) diff --git a/docs/developer-docs/defi/tokens/ledger/setup/icp_ledger_setup.mdx b/docs/developer-docs/defi/tokens/ledger/setup/icp_ledger_setup.mdx index 23cae762d9..5641d7d16f 100644 --- a/docs/developer-docs/defi/tokens/ledger/setup/icp_ledger_setup.mdx +++ b/docs/developer-docs/defi/tokens/ledger/setup/icp_ledger_setup.mdx @@ -8,9 +8,9 @@ import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; -The Internet Computer Protocol (ICP) implements management of its utility token (ticker "ICP") using a specialized canister, called the **ICP ledger canister**. It is a single ledger canister that runs alongside other canisters on a special subnet of the Internet Computer - the NNS subnet. The ICP ledger canister is a smart contract that holds **blocks**, each containing a single transaction. +The Internet Computer Protocol (ICP) implements management of its utility token (ticker "ICP") using a specialized canister, called the **ICP ledger canister**. It is a single ledger canister that runs alongside other canisters on a special subnet of the Internet Computer—the NNS subnet. The ICP ledger canister is a smart contract that holds **blocks**, each containing a single transaction. -These transactions either: +These transactions are either: - **Mint ICP tokens** for accounts. @@ -36,7 +36,7 @@ If you are working in a local development environment, i.e., with a local replic An ICP ledger account (see [ICRC-1 standard](/docs/current/developer-docs/defi/tokens/token-standards#icrc-1)) belongs to and is controlled by the account owner, who must have a valid principal ID. No account can be owned by two or more principals (no "joint accounts"). However, since a principal can refer to an external user as well as to a canister, joint accounts can be implemented as canisters. -An account on the ledger is represented and stored as an `AccountIdentifier`, which is derived from the principal ID and subaccount identifier by computing a hash of the two. The subaccount is an optional bitstring that helps distinguish between the different sub-accounts of the same owner. +An account on the ledger is represented and stored as an `AccountIdentifier`, which is derived from the principal ID and subaccount identifier by computing a hash of the two. The subaccount is an optional bitstring that helps distinguish between the different subaccounts of the same owner. In this context, you can think of principal identifiers as a rough equivalent to the hash of a user’s public key for Bitcoin or Ethereum. You use the corresponding secret key to sign messages and therefore authenticate to the ledger canister and operate on the principal’s account. Canisters can also have accounts in the ledger canister, in which case the address is derived from the canister’s principal. @@ -83,10 +83,10 @@ Go to the [releases overview](https://dashboard.internetcomputer.org/releases) a The URL for the ledger Wasm module is `https://download.dfinity.systems/ic//canisters/ledger-canister.wasm.gz`. -The URL for the ledger Candid file is `https://raw.githubusercontent.com/dfinity/ic//rs/ledger_suite/icp/ledger.did`. +The URL for the ledger's Candid file is `https://raw.githubusercontent.com/dfinity/ic//rs/ledger_suite/icp/ledger.did`. #### Optional -If you want to make sure you have the latest ICP ledger files, you can run the following script. Please ensure that you have [`jq`](https://jqlang.github.io/jq/) installed as the script relies on it. +If you want to make sure you have the latest ICP ledger files, you can run the following script. Please ensure that you have [`jq`](https://jqlang.github.io/jq/) installed, as the script relies on it. ``` sh curl -o download_latest_icp_ledger.sh "https://raw.githubusercontent.com/dfinity/ic/aba60ffbc46acfc8990bf4d5685c1360bd7026b9/rs/rosetta-api/scripts/download_latest_icp_ledger.sh" @@ -123,38 +123,38 @@ Open the `dfx.json` file in your project's directory. Replace the existing conte ``` json { - "canisters": { - "icp_ledger_canister": { - "type": "custom", - "candid": "https://raw.githubusercontent.com/dfinity/ic/aba60ffbc46acfc8990bf4d5685c1360bd7026b9/rs/ledger_suite/icp/ledger.did", - "wasm": "https://download.dfinity.systems/ic/aba60ffbc46acfc8990bf4d5685c1360bd7026b9/canisters/ledger-canister.wasm.gz", - "remote": { - "id": { - "ic": "ryjl3-tyaaa-aaaaa-aaaba-cai" - } - }, - "init_arg" : "(variant { Init = record { minting_account = \"MINTER_ACCOUNT_ID\"; initial_values = vec { record { \"DEFAULT_ACCOUNT_ID\"; record { e8s = 10_000_000_000 : nat64; }; }; }; send_whitelist = vec {}; transfer_fee = opt record { e8s = 10_000 : nat64; }; token_symbol = opt \"LICP\"; token_name = opt \"Local ICP\"; } })" - } - }, - "defaults": { - "build": { - "args": "", - "packtool": "" - } - }, - "output_env_file": ".env", - "version": 1 +  "canisters": { +    "icp_ledger_canister": { +      "type": "custom", +      "candid": "https://raw.githubusercontent.com/dfinity/ic/aba60ffbc46acfc8990bf4d5685c1360bd7026b9/rs/ledger_suite/icp/ledger.did", +      "wasm": "https://download.dfinity.systems/ic/aba60ffbc46acfc8990bf4d5685c1360bd7026b9/canisters/ledger-canister.wasm.gz", +      "remote": { +        "id": { +          "ic": "ryjl3-tyaaa-aaaaa-aaaba-cai" +        } +      }, +      "init_arg" : "(variant { Init = record { minting_account = \"MINTER_ACCOUNT_ID\"; initial_values = vec { record { \"DEFAULT_ACCOUNT_ID\"; record { e8s = 10_000_000_000 : nat64; }; }; }; send_whitelist = vec {}; transfer_fee = opt record { e8s = 10_000 : nat64; }; token_symbol = opt \"LICP\"; token_name = opt \"Local ICP\"; } })" +    } +  }, +  "defaults": { +    "build": { +      "args": "", +      "packtool": "" +    } +  }, +  "output_env_file": ".env", +  "version": 1 } ``` :::danger -If you chose to download the ICP ledger files with the script you need to replace the Candid and Wasm file entries: +If you chose to download the ICP ledger files with the script, you need to replace the Candid and Wasm file entries: ```json ... "candid": icp_ledger.did, "wasm" : icp_ledger.wasm.gz, - ... +  ... ``` ::: @@ -172,27 +172,27 @@ You can also pass these init args to the canister [using the command line](/docs ```json { - "canisters": { - "icp_ledger_canister": { - "type": "custom", - "candid": "https://raw.githubusercontent.com/dfinity/ic/aba60ffbc46acfc8990bf4d5685c1360bd7026b9/rs/ledger_suite/icp/ledger.did", - "wasm": "https://download.dfinity.systems/ic/aba60ffbc46acfc8990bf4d5685c1360bd7026b9/canisters/ledger-canister.wasm.gz", - "remote": { - "id": { - "ic": "ryjl3-tyaaa-aaaaa-aaaba-cai" - } - }, - "init_arg_file" : "init-args.did" - } - }, - "defaults": { - "build": { - "args": "", - "packtool": "" - } - }, - "output_env_file": ".env", - "version": 1 +  "canisters": { +    "icp_ledger_canister": { +      "type": "custom", +      "candid": "https://raw.githubusercontent.com/dfinity/ic/aba60ffbc46acfc8990bf4d5685c1360bd7026b9/rs/ledger_suite/icp/ledger.did", +      "wasm": "https://download.dfinity.systems/ic/aba60ffbc46acfc8990bf4d5685c1360bd7026b9/canisters/ledger-canister.wasm.gz", +      "remote": { +        "id": { +          "ic": "ryjl3-tyaaa-aaaaa-aaaba-cai" +        } +      }, +      "init_arg_file" : "init-args.did" +    } +  }, +  "defaults": { +    "build": { +      "args": "", +      "packtool": "" +    } +  }, +  "output_env_file": ".env", +  "version": 1 } ``` @@ -207,7 +207,7 @@ dfx start --clean --background - #### Step 7: Deploy the ledger canister locally. :::caution -You cannot deploy this canister to the playground (using flag `dfx deploy --playground`) because it does not accept gzipped Wasm files. +You cannot deploy this canister to the playground (using the flag `dfx deploy --playground`) because it does not accept gzipped Wasm files. ::: ``` diff --git a/docs/developer-docs/defi/tokens/ledger/setup/icrc1_ledger_setup.mdx b/docs/developer-docs/defi/tokens/ledger/setup/icrc1_ledger_setup.mdx index aeab5576ee..8dad6a4122 100644 --- a/docs/developer-docs/defi/tokens/ledger/setup/icrc1_ledger_setup.mdx +++ b/docs/developer-docs/defi/tokens/ledger/setup/icrc1_ledger_setup.mdx @@ -10,7 +10,7 @@ import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; ICRC-1 is a [token standard](https://github.com/dfinity/ICRC-1) used to create and deploy fungible tokens on the Internet Computer. Each token deployed on the network has its own dedicated ledger. Thus, deploying a new token that is ICRC-1-compatible is synonymous with deploying an ICRC-1 ledger. -The ICRC-1 ledger used in this guide is a reference implementation used to demonstrate how to setup an existing ICRC-1 ledger implementation rather than how to build an ICRC-1 ledger yourself. +The ICRC-1 ledger used in this guide is a reference implementation used to demonstrate how to set up an existing ICRC-1 ledger implementation rather than how to build an ICRC-1 ledger yourself. ## Deploying the ICRC ledger locally @@ -33,7 +33,7 @@ The URL for the ledger Wasm module is `https://github.com/dfinity/ic/releases/do The URL for the ledger Candid file is `https://github.com/dfinity/ic/releases/download//ledger.did`. #### Optional -If you want to make sure you have the latest ICRC-1 ledger files you can run the following script that downloads the files into your local directory: +If you want to make sure you have the latest ICRC-1 ledger files, you can run the following script that downloads the files into your local directory: ``` sh curl -o download_latest_icrc1_ledger.sh "https://raw.githubusercontent.com/dfinity/ic/aba60ffbc46acfc8990bf4d5685c1360bd7026b9/rs/rosetta-api/scripts/download_latest_icrc1_ledger.sh" @@ -47,21 +47,21 @@ Open the `dfx.json` file in your project's directory. Replace the existing conte ``` json { - "canisters": { - "icrc1_ledger_canister": { - "type": "custom", - "candid": "https://github.com/dfinity/ic/releases/download//ledger.did", - "wasm": "https://github.com/dfinity/ic/releases/download//ic-icrc1-ledger.wasm.gz" - } - }, - "defaults": { - "build": { - "args": "", - "packtool": "" - } - }, - "output_env_file": ".env", - "version": 1 +  "canisters": { +    "icrc1_ledger_canister": { +      "type": "custom", +      "candid": "https://github.com/dfinity/ic/releases/download//ledger.did", +      "wasm": "https://github.com/dfinity/ic/releases/download//ic-icrc1-ledger.wasm.gz" +    } +  }, +  "defaults": { +    "build": { +      "args": "", +      "packtool": "" +    } +  }, +  "output_env_file": ".env", +  "version": 1 } ``` @@ -71,7 +71,7 @@ If you chose to download the ICRC-1 ledger files with the script, you need to re ... "candid": "icrc1_ledger.did", "wasm" : "icrc1_ledger.wasm.gz" - ... +  ... ``` :::info @@ -84,4 +84,4 @@ There is a test suite available for [ICRC-1 ledgers](https://github.com/dfinity/ ## Next steps -Before you deploy your ledger canister, you will need to set some variables that you will pass to the canister during initialization that will create a new ICRC-1 or ICRC-2 token. To learn how to set these variables and deploy the ledger canister, see [create a token](/docs/developer-docs/defi/tokens/create.mdx). +Before you deploy your ledger canister, you will need to set some variables that you will pass to the canister during initialization that will create a new ICRC-1 or ICRC-2 token. To learn how to set these variables and deploy the ledger canister, see [create a token](/docs/developer-docs/defi/tokens/create.mdx). \ No newline at end of file diff --git a/docs/developer-docs/defi/tokens/ledger/usage/icp_ledger_usage.mdx b/docs/developer-docs/defi/tokens/ledger/usage/icp_ledger_usage.mdx index b79423601f..341206fd15 100644 --- a/docs/developer-docs/defi/tokens/ledger/usage/icp_ledger_usage.mdx +++ b/docs/developer-docs/defi/tokens/ledger/usage/icp_ledger_usage.mdx @@ -8,252 +8,79 @@ import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; -## Overview -There are multiple ways to interact with the ICP ledger. They depend on whether you want to interact with the ICP ledger on mainnet, the `dfx ledger` default ICP ledger on a local network, or whether you have deployed your own local ledger version. Also, how you interact with the ICP ledger is dependent on whether you want to interact with it from the command line, from your web app, or from another canister. +How you interact with the ICP ledger is dependent on whether you want to interact with it from the command line, from your web app, or from another canister. Available workflows and tools include: -This guide will discuss the different ways to interact with the ICP ledger. In this guide, the following workflows will be covered: -- `dfx ledger`: the built in `dfx` shortcut for interacting with the ICP ledger. -- `dfx canister`: the generic canister call from `dfx`. +- `dfx ledger`: The `dfx` CLI command for interacting with the ICP ledger. +- `dfx canister`: A generic canister call using `dfx`. - [ledger-icp](https://github.com/dfinity/ic-js/tree/main/packages/ledger-icp) JavaScript library. -- `ic-cdk`: inter-canister calls for the ICP ledger. +- `ic-cdk`: Inter-canister calls for the ICP ledger. -## Interacting with ICP ledger via `dfx ledger` +## Interacting with the ICP ledger via `dfx ledger` -`dfx` provides a convenience command to interact with the ICP ledger canister and related functionality. You can find the documentation [here](/docs/current/developer-docs/developer-tools/cli-tools/cli-reference/dfx-ledger) or just enter the following command into your console: +`dfx` provides a convenience command to interact with the ICP ledger canister and related functionality: [`dfx ledger`](/docs/current/developer-docs/developer-tools/cli-tools/cli-reference/dfx-ledger). -``` bash -dfx ledger --help -``` - -It's worth checking out the `--help` flag of the subcommands as well. -`dfx` does not come with an ICP ledger instance installed by default. To be able to use this command you will need to install the ICP ledger locally. You can do that by following this [guide](/docs/developer-docs/defi/tokens/ledger/setup/icp_ledger_setup.mdx) or by installing the NNS locally: -``` bash -dfx extension install nns -dfx nns install -``` -The ICP ledger will then run locally with the canister ID `ryjl3-tyaaa-aaaaa-aaaba-cai`. -Currently, `dfx` exposes only a subset of the ICP ledger functionality, namely `balance` and `transfer`. -Both commands provide a flag to specify a ledger canister id (`--ledger-canister-id`). This simplifies interacting with a local ledger deployment or other tokens that provide the same interface. If you do not specify the canister ID `dfx ledger` will assume you want to interact with a ICP ledger that has a canister ID of `ryjl3-tyaaa-aaaaa-aaaba-cai` or with the ICP ledger on the mainnet. For the latter, you need to specify the mainnet as the network of choice using the flag `--network ic`. +`dfx` does not come with an ICP ledger instance installed by default. To be able to use this command, you will need to install the [ICP ledger locally](/docs/developer-docs/defi/tokens/ledger/setup/icp_ledger_setup.mdx). -:::info -Summary of different `dfx ledger` commands: -- `dfx ledger ...`: interact with the ICP ledger on your local network with canister ID `ryjl3-tyaaa-aaaaa-aaaba-cai`. -- `dfx ledger --network ic ...`: interact with the ICP ledger on the mainnet. -- `dfx ledger --ledger-canister-id ...`: interact with the [locally deployed](/docs/developer-docs/defi/tokens/ledger/setup/icp_ledger_setup.mdx) ICP ledger on your local network. -::: +Currently, `dfx ledger` only exposes a subset of the ICP ledger functionality, namely `balance` and `transfer`. -### Balance +View the [`dfx ledger`](/docs/current/developer-docs/developer-tools/cli-tools/cli-reference/dfx-ledger) documentation for all available `dfx ledger` commands and flags. -Get the ICP balance of a specific account: +## Interacting with the ICP ledger via `dfx canister` -``` bash -dfx ledger --network ic balance -``` +The ICP ledger canister ID is assumed to be `ryjl3-tyaaa-aaaaa-aaaba-cai`. If your locally deployed ICP ledger's canister ID is different, you will need to replace `ryjl3-tyaaa-aaaaa-aaaba-cai` with it. -The `` is encoded as a hex string. You can print the account id of the current `dfx` identity by running: +Use the following command syntax to interact with the ICP ledger via `dfx canister`: -```bash -dfx ledger account-id ``` - -In many cases you want to check the main account balance of a specific principal. You can combine the `balance` command with the `account-id` command, while specifying an `--of-principal` argument to yield this helpful command: - -``` bash -dfx ledger --network ic balance $(dfx ledger account-id --of-principal ) +dfx canister call ``` -### Transfer +For example, to fetch the token symbol of the ICP ledger, call the `symbol` method: -The transfer function can be used to transfer ICP from your account to another. - -``` bash -dfx ledger --network ic transfer --amount --memo -``` - -## Interacting with ICP ledger via `dfx canister` -For this subsection it is assumed that you have deployed an ICP ledger either locally or you want to communicate with the mainnet ICP ledger using `dfx canister`. The ICP ledger canister ID is assumed to be `ryjl3-tyaaa-aaaaa-aaaba-cai`, if your locally deployed ICP ledger's canister ID is different you will need to replace `ryjl3-tyaaa-aaaaa-aaaba-cai` with it. You can find all endpoints that can be called in the `icp_ledger.did` file. How to retrieve it is discussed in the [ICP local deployment guide](/docs/developer-docs/defi/tokens/ledger/setup/icp_ledger_setup.mdx). - -This guide will only go into the ICP ledger specific endpoints. To call the ICRC-1 endpoints you can have a look at [the ICRC-1 setup guide](/docs/current/developer-docs/defi/tokens/indexes). To find a more detailed description of the data types used in these commands you can have a look at [this guide](/docs/current/references/ledger#_getting_ledger_blocks). - -To fetch the symbol of the ICP ledger: ``` dfx canister call ryjl3-tyaaa-aaaaa-aaaba-cai symbol '()' ``` -This command returns the ICP symbol: -``` -(record { symbol = "ICP" }) -``` -To fetch the name of the ICP ledger: -``` -dfx canister call ryjl3-tyaaa-aaaaa-aaaba-cai name '()' -``` -This command returns the ICP name: -``` -(record { name = "Internet Computer" }) -``` +You can find all available methods listed within the ICP ledger canister's Candid file or view the [mainnet ICP ledger canister on the dashboard](https://dashboard.internetcomputer.org/canister/ryjl3-tyaaa-aaaaa-aaaba-cai). -To fetch the decimals of the ICP ledger: -``` -dfx canister call ryjl3-tyaaa-aaaaa-aaaba-cai decimals '()' -``` -This command returns the ICP decimals: -``` -(record { decimals = 8 : nat32 }) -``` -To handle a growing number of transactions within limited canister memory, a new archive canister is created when the history exceeds a threshold, migrating older transactions to it. +[View a more detailed description of the data types used in these commands](/docs/current/references/ledger#_getting_ledger_blocks). -To fetch the archives of the ICP ledger: -``` -dfx canister call ryjl3-tyaaa-aaaaa-aaaba-cai archives '()' -``` -If you are testing locally, no archive canisters should have been created yet: -``` -(record { archives = vec {} }) -``` -However, if you are testing on mainnet, the following archive canisters have been created as of the time of writing this document: -``` -( - record { - archives = vec { - record { canister_id = principal "qjdve-lqaaa-aaaaa-aaaeq-cai" }; - record { canister_id = principal "qsgjb-riaaa-aaaaa-aaaga-cai" }; - record { canister_id = principal "q4eej-kyaaa-aaaaa-aaaha-cai" }; - }; - }, -) -``` +## Interact with ICP ledger from your web application -To send tokens to the `AccountIdentifier` `d52f7f2b7277f025bcaa5c90b10d122274faba289` you can use the following commands. You will need to derive the `AccountIdentifier` by getting the principal first: -``` -dfx ledger account-id --of-principal -``` -You can get the principal of an identity by calling: -``` -dfx identity get-principal --identity -``` -If you have an identity called `default2` and you want to send ICP to this principals default `AccountIdentifier` you would call: - ``` -dfx identity get-principal --identity default2 -``` -This command will return: -``` -sckqo-e2vyl-4rqqu-5g4wf-pqskh-iynjm-46ixm-awluw-ucnqa-4sl6j-mqe -``` -If you plug this response value into the `account-id` command: -``` -dfx ledger account-id --of-principal sckqo-e2vyl-4rqqu-5g4wf-pqskh-iynjm-46ixm-awluw-ucnqa-4sl6j-mqe -``` -The following response will be returned: -``` -d52f7f2b7277f025bcaa5c90b10d122274faba289 -``` -You can bring all of these commands together to form a transfer transaction: -``` -export TO_ACCOUNT = "d52f7f2b7277f025bcaa5c90b10d122274faba2891bea519105309ae1f0af91d" -dfx canister call ryjl3-tyaaa-aaaaa-aaaba-cai transfer '(record { to = $(python3 -c 'print("vec{" + ";".join([str(b) for b in bytes.fromhex("'$TO_ACCOUNT'")]) + "}")'); memo = 1:nat64; amount = record {e8s = 200_000_000 }; fee = record { e8s = 10_000 }; })' -``` +In order to simplify working with the ICP ledger from JavaScript applications, you can use the [ledger-icp](https://github.com/dfinity/ic-js/tree/main/packages/ledger-icp) JavaScript library. -This command returns the block index in which this transaction took place. In this example, it was the first block: -``` -(variant { Ok = 1 : nat64 }) -``` -To get the balance of an `AccountIdentifier` you can call: -``` -dfx canister call ryjl3-tyaaa-aaaaa-aaaba-cai account_balance '(record { account = '$(python3 -c 'print("vec{" + ";".join([str(b) for b in bytes.fromhex("'$TO_ACCOUNT'")]) + "}")')' })' -``` -It returns the the balance in e8s of the `AccountIdentifier` `d52f7f2b7277f025bcaa5c90b10d122274faba2891bea519105309ae1f0af91d`. It should have a balance of 200 million as thats the amount you sent earlier: -``` -(record { e8s = 200_000_000 : nat64 }) -``` +:::info +To interact with the ICRC-1 endpoints of the ICP ledger, learn more about [interacting with an ICRC-1 ledger](/docs/current/developer-docs/defi/tokens/indexes). +::: -To query the created blocks from the ICP ledger you can call: -``` -dfx canister call ryjl3-tyaaa-aaaaa-aaaba-cai query_blocks '(record {start = 1:nat64; length = 1:nat64})' -``` +## Interacting with ICP from a canister (inter-canister calls via `ic-cdk`) -You will have to specify the first block to fetch and the number of blocks to fetch. -This command will return output that resembles the following: +View the [inter-canister call documentation] (/docs/developer-docs/backend/rust/intercanister) to see how you can call one canister from within another. -``` -( - record { - certificate = opt blob "\d9\d9\f7\a2dtree\83\01\83\01\83\01\83\02Hcanister\83\01\83\01\82\04X \05\8f\12\83V\ad(\b6q\e6\0b\60\d2\90\97<\a0\8c~\ea\a9\18\13j\fe<\bbH\1a^n1\83\02J\80\00\00\00\00\10\00\01\01\01\83\01\83\01\83\01\83\02Ncertified_data\82\03X \f5}\c2M\a6\87\fe\03N9H/4?\bd\a8\1c\ad\ba\0b\86,\98\8dx)\11\b9=*\b7\eb\82\04X \83\c5k\f1M\de=(\def\c6\92\b5\fc\9d\97\e9\dd\98[j\d7+\0f\e6\f8N\8a\8d\f3\dc\b2\82\04X l\96\c1\d2D\fe\c00\d5S\f6N\0b4q]\9do\d7\a00\90\a0\8e\c03K\f6\f2hT\fe\82\04X \99i\83\c5\0b\0ec\02\dd\d9{r\a8\cb\7f?\f5\03\04\88\b1QC\d0\15\9eR\87\da(\d6\08\82\04X \97\c3\ef\e5\dc\efyN\1b\cd\d3\a1\c2\bbE\84y@\fc(\ec\87\cb5yk\ef\d74\b5\ef\cf\82\04X S\ebWak\00\b4#\a3\94I+\b0\9a\dc\11\b5\ff\1a\96\b0\a7\cede8\1b\b8\16\1d\14\dd\82\04X \13\c86\94\98\d9\ae)\a7\e4\f3\19\97\08\a2\dc\a5\a5(v\90\f8a\19rL\aa\09\0c\1b\d5\d5\83\01\82\04X \17+O\f52\a3\22\7f\87S\9bop\a6\18\b1\16\e1\1f\19\c2\9e\1f\ea:\df-\e47/\1d\e0\83\02Dtime\82\03I\90\f9\8e\d7\a0\88\b6\c4\17isignatureX0\aa6/\f2b\9a\c1%\98\f6\e32\e0\de\11\0e(\fe\f9=\b09z\be\a3\e7\8aG\d0:\18k\e0o\ed\f3\ba\d2\84\17yAAx\9cm\bf\06"; - blocks = vec { - record { - transaction = record { - memo = 1 : nat64; - icrc1_memo = null; - operation = opt variant { - Transfer = record { - to = blob "\08.\cf.?dz\c6\00\f4?8\a6\83B\fb\a5\b8\e6\8b\08_\02Y+w\f3\98\08\a8\d2\b5"; - fee = record { e8s = 10_000 : nat64 }; - from = blob "\0amCu\816\9bTj\fd\efa<\a9\c0\81\a2R\ca,F\e7\ec)\e5\10\bc\10\b2\13\fa\27"; - amount = record { e8s = 200_000_000 : nat64 }; - } - }; - created_at_time = record { - timestamp_nanos = 1_695_815_275_230_210_000 : nat64; - }; - }; - timestamp = record { - timestamp_nanos = 1_695_815_275_230_210_000 : nat64; - }; - parent_hash = opt blob "\e6{0\db\a6\a5)1\17@\9d\e7h\ee\85\b0\91h>l\a2\fdxi\d3;x\85\bf\e7\d0a"; - }; - }; - chain_length = 6 : nat64; - first_block_index = 1 : nat64; - archived_blocks = vec {}; - }, -) -``` +Here is an example of how to fetch the token name from the ICP ledger using Rust and the `ic-cdk` [library](https://github.com/dfinity/cdk-rs) from within a canister: -To only query the encoded blocks from the ICP ledger you can call: -``` -dfx canister call ryjl3-tyaaa-aaaaa-aaaba-cai query_encoded_blocks '(record {start = 1:nat64; length = 1:nat64})' ``` -It is a similar format but you will only receive the CBOR encoded block: -``` -( - record { - certificate = opt blob "\d9\d9\f7\a2dtree\83\01\83\01\83\01\83\02Hcanister\83\01\83\01\82\04X \05\8f\12\83V\ad(\b6q\e6\0b\60\d2\90\97<\a0\8c~\ea\a9\18\13j\fe<\bbH\1a^n1\83\02J\80\00\00\00\00\10\00\01\01\01\83\01\83\01\83\01\83\02Ncertified_data\82\03X \f5}\c2M\a6\87\fe\03N9H/4?\bd\a8\1c\ad\ba\0b\86,\98\8dx)\11\b9=*\b7\eb\82\04X \83\c5k\f1M\de=(\def\c6\92\b5\fc\9d\97\e9\dd\98[j\d7+\0f\e6\f8N\8a\8d\f3\dc\b2\82\04X l\96\c1\d2D\fe\c00\d5S\f6N\0b4q]\9do\d7\a00\90\a0\8e\c03K\f6\f2hT\fe\82\04X \99i\83\c5\0b\0ec\02\dd\d9{r\a8\cb\7f?\f5\03\04\88\b1QC\d0\15\9eR\87\da(\d6\08\82\04X \97\c3\ef\e5\dc\efyN\1b\cd\d3\a1\c2\bbE\84y@\fc(\ec\87\cb5yk\ef\d74\b5\ef\cf\82\04X \aao\e5\85L\f7\0b\e3V\07\ed\27\88k\a5z\bd\abQ\aa=\dcc>m\0b\b1\88\ea\c8\f4\b7\82\04X \13\c86\94\98\d9\ae)\a7\e4\f3\19\97\08\a2\dc\a5\a5(v\90\f8a\19rL\aa\09\0c\1b\d5\d5\83\01\82\04X \17+O\f52\a3\22\7f\87S\9bop\a6\18\b1\16\e1\1f\19\c2\9e\1f\ea:\df-\e47/\1d\e0\83\02Dtime\82\03I\b8\c7\d9\f5\9a\8a\b6\c4\17isignatureX0\af\9e\c3\d1\e3\95\c8\1b\0c\b8\5cC\b0\fb\f9E\e0\eeJ\88\1f\e7%G\06\b8\ac\a4\14{\e1k\97\15\8d\8a0\c6\9d\86\a1\03\ef\02\b7\82A\f9"; - blocks = vec { - blob "\0a\22\0a \e6{0\db\a6\a5)1\17@\9d\e7h\ee\85\b0\91h>l\a2\fdxi\d3;x\85\bf\e7\d0a\12\0a\08\d0\cf\9c\e6\a0\e0\af\c4\17\1af\1aT\0a\22\0a \0amCu\816\9bTj\fd\efa<\a9\c0\81\a2R\ca,F\e7\ec)\e5\10\bc\10\b2\13\fa\27\12\22\0a \08.\cf.?dz\c6\00\f4?8\a6\83B\fb\a5\b8\e6\8b\08_\02Y+w\f3\98\08\a8\d2\b5\1a\05\08\80\84\af_\22\03\08\90N\22\02\08\012\0a\08\d0\cf\9c\e6\a0\e0\af\c4\17"; - }; - chain_length = 6 : nat64; - first_block_index = 1 : nat64; - archived_blocks = vec {}; - }, -) -``` - -## Interact with ICP ledger from your web application - -In order to simplify working with ICP ledger from JavaScript applications, you can use the [ledger-icp](https://github.com/dfinity/ic-js/tree/main/packages/ledger-icp) JavaScript library. -. -To interact with the ICRC-1 endpoints of the ICP ledger you can have a look at the guide on [interacting with an ICRC-1 ledger](/docs/current/developer-docs/defi/tokens/indexes). +// You will need the canister ID of the ICP ledger: `ryjl3-tyaaa-aaaaa-aaaba-cai`. -## Interacting with ICP from a canister (inter-canister calls via `ic-cdk`) -You can look at the documentation of [inter-canister calls] (/docs/developer-docs/backend/rust/intercanister) to see how you can interact with the another canister from inside a canister. This guide will give you a couple of examples on how to make such a call in the case of the ICP ledger. - -Here is an example on how fetch the name from the ICP ledger using Rust and the `ic-cdk` [library](https://github.com/dfinity/cdk-rs) from withing a canister: -``` -// You will need the principal of the ICP ledger. The canister id of the ICP ledger on mainnet and the dfx default ICP ledger locally is `ryjl3-tyaaa-aaaaa-aaaba-cai`. let ledger_id = Principal::from_text("ryjl3-tyaaa-aaaaa-aaaba-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(); + +    let req = (); +    let (res,): (String,) = +        ic_cdk::call(ledger_id, "icrc1_name", (req,)) +            .await.unwrap(); ``` -For all other endpoints you can use the request and response structure from the `ledger.did` Candid file. How to retrieve the Candid file is explained in [the guide on deploying an ICP ledger locally](/docs/developer-docs/defi/tokens/ledger/setup/icp_ledger_setup.mdx). +You can find all available methods listed within the ICP ledger canister's Candid file or view the [mainnet ICP ledger canister on the dashboard](https://dashboard.internetcomputer.org/canister/ryjl3-tyaaa-aaaaa-aaaba-cai). ### `icrc-ledger-types` Rust crate -As explained in the [token standards](/docs/current/developer-docs/defi/tokens/token-standards), the ICP ledger supports all ICRC-1 endpoints. You will need to define the structures used for these endpoints. -To interact with ICRC-1 and ICRC-2 endpoints, the Rust crate [icrc-ledger-types](https://crates.io/crates/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,...). + +As explained in [token standards](/docs/current/developer-docs/defi/tokens/token-standards), the ICP ledger supports all ICRC-1 endpoints. You will need to define the structures used for these endpoints. + +To interact with the ICRC-1 and ICRC-2 endpoints, the Rust crate [icrc-ledger-types](https://crates.io/crates/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: ``` @@ -268,43 +95,42 @@ icrc-ledger-types = "0.1.1" [View the documentation for this crate](https://docs.rs/icrc-ledger-types/0.1.1/icrc_ledger_types/). - ### Receiving ICP -If you want a canister to receive payment in ICP you need to make sure that the canister knows about the payment, because a transfer only involves the sender and the ledger canister. +If you want a canister to receive payment in ICP, you need to make sure that the canister knows about the payment because a transfer only involves the sender and the ledger canister. -There are currently two main patterns to achieve this. Furthermore, there is a [chartered working group](https://forum.dfinity.org/t/announcing-technical-working-groups/11781) on Ledger & Tokenization which is focused on defining a standard ledger/token interface as well payment flows. +There are currently two main patterns to achieve this. Furthermore, there is a [chartered working group](https://forum.dfinity.org/t/announcing-technical-working-groups/11781) on ledger and tokenization that is focused on defining a standard ledger token interface and payment flows. #### Direct notification by sender -In this pattern the sender notifies the receiver about the payment. However, the receiver needs to verify the payment by using the [`query_blocks` interface](/docs/current/references/ledger#_getting_ledger_blocks) of the ledger. +In this pattern, the sender notifies the receiver about the payment. However, the receiver needs to verify the payment by using the [`query_blocks` interface](/docs/current/references/ledger#_getting_ledger_blocks) of the ledger. + The following diagram shows a simplified illustration of this pattern: ```plantuml - participant Sender - participant "ICP Ledger" - participant Receiver - - Sender -> "ICP Ledger": transfer() - "ICP Ledger" --> Sender: blockNumber - Sender -> Receiver: notify(blockNumber) - Receiver -> "ICP Ledger": query_blocks(blockNumber) - "ICP Ledger" --> Receiver: block - Receiver -> Receiver: verify payment -``` +    participant Sender +    participant "ICP Ledger" +    participant Receiver +    Sender -> "ICP Ledger": transfer() +    "ICP Ledger" --> Sender: blockNumber +    Sender -> Receiver: notify(blockNumber) +    Receiver -> "ICP Ledger": query_blocks(blockNumber) +    "ICP Ledger" --> Receiver: block +    Receiver -> Receiver: verify payment +``` #### Notification by ICP ledger (currently disabled) -In this pattern the ledger itself notifies the receiver. Thereby, the receiver can trust the notification immediately. However, this flow is currently disabled because the call to the receiver is not yet implemented as a one-way call. +In this pattern, the ledger itself notifies the receiver. Thereby, the receiver can trust the notification immediately. However, this flow is currently disabled because the call to the receiver is not yet implemented as a one-way call. ```plantuml - participant Sender - participant "ICP Ledger" - participant Receiver - - Sender -> "ICP Ledger": transfer() - "ICP Ledger" --> Sender: blockNumber - Sender -> "ICP Ledger": notify(blockNumber, receiver) - "ICP Ledger" -> "Receiver": transaction_notification(details) -``` +    participant Sender +    participant "ICP Ledger" +    participant Receiver + +    Sender -> "ICP Ledger": transfer() +    "ICP Ledger" --> Sender: blockNumber +    Sender -> "ICP Ledger": notify(blockNumber, receiver) +    "ICP Ledger" -> "Receiver": transaction_notification(details) +``` \ No newline at end of file diff --git a/docs/developer-docs/defi/tokens/ledger/usage/icrc1_ledger_usage.mdx b/docs/developer-docs/defi/tokens/ledger/usage/icrc1_ledger_usage.mdx index f631ef6c69..3413fb44da 100644 --- a/docs/developer-docs/defi/tokens/ledger/usage/icrc1_ledger_usage.mdx +++ b/docs/developer-docs/defi/tokens/ledger/usage/icrc1_ledger_usage.mdx @@ -1,215 +1,87 @@ --- -keywords: [intermediate, tokens, icrc, tutorial, ledger] +keywords: [intermediate, tokens, icrc, icrc-1, icrc-2, icrc-3, icrc tokens, tutorial, ledger] --- import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; -# Using the ICRC-1 ledger +# Using an ICRC-1 ledger -## Overview -There are two main ways to interact with an ICRC-1 ledger. -- `dfx canister`: The generic canister call from `dfx`. -- `ic-cdk`: Inter-canister calls for the ICRC-1 ledger. -- [`ledger-icrc-js`](https://github.com/dfinity/ic-js/tree/main/packages/ledger-icrc): A library for interfacing with ICRC-1 ledger on the Internet Computer. - -## ICRC-1 and ICRC-1 extension endpoints - -Whether your ICRC-1 ledger will have all the endpoints discussed in this tutorial will depend on if you chose to support any of the extensions of ICRC-1 (ICRC-2, ICRC-3,...). -This tutorial will go through the endpoints for ICRC-1 and the extension ICRC-2. If you have deployed an ICRC-1 ledger according to the [guide](/docs/developer-docs/defi/tokens/ledger/setup/icrc1_ledger_setup.mdx) you have to make sure that you have enabled the ICRC-2 standard, otherwise, the calls demonstrated in this guide will not work. - -You can always check which standards are supported by a certain ICRC-1 ledger by calling: - -``` -dfx canister call icrc1_ledger_canister icrc1_supported_standards '()' -``` - -The ICRC-1 ledger used in this guide also supports the extension ICRC-2: - -``` - -( - vec { - record { - url = "https://github.com/dfinity/ICRC-1/tree/main/standards/ICRC-1"; - name = "ICRC-1"; - }; - record { - url = "https://github.com/dfinity/ICRC-1/tree/main/standards/ICRC-2"; - name = "ICRC-2"; - }; - }, -) -``` - -The return values as well as the canister name `icrc1_ledger_canister` in this tutorial are specific to the deployed ICRC-1 ledger and thus may differ to your return values, depending on which values you chose during your [ICRC-1 ledger setup](/docs/developer-docs/defi/tokens/ledger/setup/icrc1_ledger_setup.mdx). - -### ICRC-1 endpoints - -To fetch the symbol of the ICRC-1 ledger: - -``` -dfx canister call icrc1_ledger_canister icrc1_symbol '()' -``` +There are three primary methods used to interact with an ICRC-1 ledger: -This command returns: +- `dfx canister`: The generic canister call from `dfx` used to call a canister's methods. -``` -("XMTK") -``` - -To fetch the decimals of the ICRC-1 ledger: - -``` -dfx canister call icrc1_ledger_canister icrc1_decimals '()' -``` - -This command returns: - -``` -(8 : nat8) -``` +- `ic-cdk`: Inter-canister calls for the ICRC-1 ledger. -To fetch the metadata of the ICRC-1 ledger: +- [`ledger-icrc-js`](https://github.com/dfinity/ic-js/tree/main/packages/ledger-icrc): A library for interfacing with an ICRC-1 ledger on the Internet Computer. -``` -dfx canister call icrc1_ledger_canister icrc1_metadata '()' -``` +## Interact with an ICRC-1 canister using `dfx canister call` -This command returns: +### ICRC-1 -``` -( - vec { - record { "icrc1:decimals"; variant { Nat = 8 : nat } }; - record { "icrc1:name"; variant { Text = "My Token" } }; - record { "icrc1:symbol"; variant { Text = "XMTK" } }; - record { "icrc1:fee"; variant { Nat = 10_000 : nat } }; - record { "icrc1:max_memo_length"; variant { Nat = 32 : nat } }; - }, -) -``` - -To fetch the total supply of the ICRC-1 ledger: +Use the following command syntax to interact with an ICRC-1 ledger via `dfx canister`: ``` -dfx canister call icrc1_ledger_canister icrc1_total_supply '()' +dfx canister call ``` -This command returns: +For example, to fetch the token symbol of an ICRC-1 ledger, call the `icrc1_symbol` method: ``` -(10_000_000_000 : nat) +dfx canister call ss2fx-dyaaa-aaaar-qacoq-cai icrc1_symbol '()' ``` -To fetch the fee of the ICRC-1 ledger: - -``` -dfx canister call icrc1_ledger_canister icrc1_fee '()' -``` +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,...). -This command returns: +You can always check which standards are supported by a certain ICRC-1 ledger by calling: ``` -(10_000 : nat) +dfx canister call icrc1_supported_standards '()' ``` -To fetch the minting account of the ICRC-1 ledger: +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](https://dashboard.internetcomputer.org/canisters). An example of an ICRC-1 ledger deployed on the mainnet that you can reference is the [ckETH ledger canister](https://dashboard.internetcomputer.org/canister/ss2fx-dyaaa-aaaar-qacoq-cai). -``` -dfx canister call icrc1_ledger_canister icrc1_minting_account '()' -``` +View the [`dfx canister call` documentation](/docs/current/developer-docs/developer-tools/cli-tools/cli-reference/dfx-canister#dfx-canister-call) for more information on calling canister methods. -This command returns: - -``` -( - opt record { - owner = principal "rrd6e-uoar3-ehz42-jxkun-ymmmv-jw4rn-re7se-5hymk-aoizl-bfb3j-uqe"; - subaccount = null; - }, -) -``` -To fetch the balance of an account (DEFAULT account in this case, with no subaccount set) on the ICRC-1 ledger: +### ICRC-2 -``` -dfx canister call icrc1_ledger_canister icrc1_balance_of "(record {owner = principal \"${DEFAULT}\"; })" -``` +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](https://github.com/dfinity/ICRC-1/tree/main/standards/ICRC-2#icrc2_approve). -This command returns: +View the [`dfx canister call` documentation](/docs/current/developer-docs/developer-tools/cli-tools/cli-reference/dfx-canister#dfx-canister-call) for more information on calling canister methods. -``` -(10_000_000_000 : nat) -``` +## Interacting with an ICRC-1 ledger from your web application (`ledger-icrc-js`) -Transferring of tokens (from `DEFAULT` to the arbitrary principal `sckqo-e2vyl-4rqqu-5g4wf-pqskh-iynjm-46ixm-awluw-ucnqa-4sl6j-mqe`) on the ICRC-1 ledger: +[View specifications and examples on how to use the `ledger-icrc-js` library to interact with ICRC-1 ledgers](https://github.com/dfinity/ic-js/tree/main/packages/ledger-icrc). -``` -dfx canister call icrc1_ledger_canister icrc1_transfer "(record { to = record { owner = principal \"sckqo-e2vyl-4rqqu-5g4wf-pqskh-iynjm-46ixm-awluw-ucnqa-4sl6j-mqe\";}; amount = 10_000;})" -``` +## Interacting with an ICRC-1 ledger from another canister (inter-canister calls via `ic-cdk`) -This command returns: +View the [inter-canister call documentation] (/docs/developer-docs/backend/rust/intercanister) to see how you can call one canister from within another. -``` -(variant { Ok = 1 : nat }) -``` - -### ICRC-2 endpoints +Here is an example of how to fetch the token name from the ICP ledger using Rust and the `ic-cdk` [library](https://github.com/dfinity/cdk-rs) from within a canister: -To approve tokens to a certain spender (this guide uses the principal `sckqo-e2vyl-4rqqu-5g4wf-pqskh-iynjm-46ixm-awluw-ucnqa-4sl6j-mqe`) you can call: -``` -dfx canister call icrc1_ledger_canister icrc2_approve "(record { amount = 100_000; spender = record{owner = principal \"sckqo-e2vyl-4rqqu-5g4wf-pqskh-iynjm-46ixm-awluw-ucnqa-4sl6j-mqe\";} })" ``` +// You will need the canister ID of the ICRC ledger. -This command returns the block index of the transaction. Since this is the second transaction the index will be 2: +let ledger_id = Principal::from_text("ss2fx-dyaaa-aaaar-qacoq-cai").unwrap(); -``` -(variant { Ok = 2 : nat }) -``` +// The request object of the `icrc1_name` endpoint is empty. -To check the allowance of the spender `sckqo-e2vyl-4rqqu-5g4wf-pqskh-iynjm-46ixm-awluw-ucnqa-4sl6j-mqe` from the previous command you can call: -``` -dfx canister call icrc1_ledger_canister icrc2_allowance "(record { account = record{owner = principal "${DEFAULT}";}; spender = record{owner = principal "sckqo-e2vyl-4rqqu-5g4wf-pqskh-iynjm-46ixm-awluw-ucnqa-4sl6j-mqe";} })" +    let req = (); +    let (res,): (String,) = +        ic_cdk::call(ledger_id, "icrc1_name", (req,)) +            .await.unwrap(); ``` -This command will return the allowance of `sckqo-e2vyl-4rqqu-5g4wf-pqskh-iynjm-46ixm-awluw-ucnqa-4sl6j-mqe` for tokens approved by the `DEFAULT` principal. You should expect this to be the `100_000` tokens you approved earlier: -``` -(record { allowance = 100_000 : nat; expires_at = null }) -``` -Alternatively, you can also set the expiration date for approval. For specifics, see the [ICRC-2 standard](https://github.com/dfinity/ICRC-1/tree/main/standards/ICRC-2#icrc2_approve). - -If the spender now wants to transfer tokens that were previously approved for the spender to a certain principal (in this case, use the arbitrary principal `7tmcj-ukheu-y6dvi-fhmxv-7qs5t-lwgh2-qzojr-vzt6m-maqv4-hvzlg-5qe`) you can call: -``` -dfx canister call icrc1_ledger_canister icrc2_transfer_from "(record { amount = 90_000; from = record{owner = principal \"${DEFAULT}\"}; to= record{owner = principal \"${DEFAULT}\"}; })" -``` -Note that you cannot transfer the entire allowance as the fee for making a transfer has to be substracted from the transferred amount. For the reference implementation the fee is `10_000` tokens. Thus, the maximum amount that can be transferred from `DEFAULT` to `7tmcj-ukheu-y6dvi-fhmxv-7qs5t-lwgh2-qzojr-vzt6m-maqv4-hvzlg-5qe` with the spender `sckqo-e2vyl-4rqqu-5g4wf-pqskh-iynjm-46ixm-awluw-ucnqa-4sl6j-mqe` is `90_000`. -The principal making this call has to be the spender, since they are the one that received the approval. -You will receive the block index as a return value: -``` -(variant { Ok = 3 : nat }) -``` +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](https://dashboard.internetcomputer.org/canisters). An example of an ICRC-1 ledger deployed on the mainnet that you can reference is the [ckETH ledger canister](https://dashboard.internetcomputer.org/canister/ss2fx-dyaaa-aaaar-qacoq-cai). -## Interacting with an ICRC-1 ledger from another canister (inter-canister calls via `ic-cdk`) -You can look at the documentation of [inter-canister calls](/docs/current/developer-docs/backend/rust/intercanister) to see how you can interact with another canister from inside a canister. This guide will give you a couple of examples of how to make such a call in the case of the ICRC-1 ledger. -Here is an example of how to fetch the name from the ICRC-1 ledger using Rust and the `ic-cdk` [library](https://github.com/dfinity/cdk-rs) from within a canister: -You will need the principal of the ICRC-1 ledger. For this guide, take the canister ID that was used in the previous guide on [deploying an ICRC-1 ledger](/docs/developer-docs/defi/tokens/ledger/setup/icrc1_ledger_setup.mdx), which was `mxzaz-hqaaa-aaaar-qaada-cai`. -``` -let ledger_id = Principal::from_text("mxzaz-hqaaa-aaaar-qaada-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(); -``` +### `icrc-ledger-types` Rust crate -For all other endpoints you can use the request and response structure from the `ledger.did` Candid file. How to retrieve the Candid file is explained in [the guide on deploying an ICRC-1 ledger locally](/docs/developer-docs/defi/tokens/ledger/setup/icrc1_ledger_setup.mdx). +To interact with the ICRC-1 and ICRC-2 endpoints, the Rust crate [icrc-ledger-types](https://crates.io/crates/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,...). -### `icrc-ledger-types` Rust crate -To interact with ICRC-1 and ICRC-2 endpoints, the Rust crate [icrc-ledger-types](https://crates.io/crates/icrc-ledger-types) can be used. It provides data types, request types and response types as well as error types needed for interacting with ICRC-1 endpoints. -This is true for any 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: ``` @@ -222,7 +94,4 @@ Or, it can be added to the `Cargo.toml` file: icrc-ledger-types = "0.1.1" ``` -View the documentation for [this crate](https://docs.rs/icrc-ledger-types/0.1.1/icrc_ledger_types/). - -## Interacting with an ICRC-1 ledger from your web application (`ledger-icrc-js`) -You will find specifications and examples on how to use the library to interact with ICRC-1 ledgers [here](https://github.com/dfinity/ic-js/tree/main/packages/ledger-icrc). +[View the documentation for this crate](https://docs.rs/icrc-ledger-types/0.1.1/icrc_ledger_types/).