Skip to main content

ICRC-1 ledger local setup

Intermediate
Tutorial

Overview​

This guide will show you how to deploy an ICRC-1 ledger locally and on the mainnet. ICRC-1 is a token standard. 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. This guide aims at showing you how to setup an existing ICRC-1 ledger implementation rather than how to build an ICRC-1 ledger yourself.

Deploying the ledger locally​

Step 1: Make sure you use a recent version of the IC SDK.​

If you don’t have the IC SDK installed, follow instructions on the installing the IC SDK section to install it.

Step 2: Create a new dfx project with the command:​

dfx new icrc1_ledger_canister
cd icrc1_ledger_canister

If using dfx version 0.17.1 or newer, choose 'Motoko' for the backend language, and 'No frontend canister' for the frontend language.

Step 3: Determine ledger file locations.​

Go to the releases overview and copy the latest replica binary revision. At the time of writing, this is aba60ffbc46acfc8990bf4d5685c1360bd7026b9.

The URL for the ledger Wasm module is https://download.dfinity.systems/ic/<REVISION>/canisters/ic-icrc1-ledger.wasm.gz, so with the above revision it would be https://download.dfinity.systems/ic/aba60ffbc46acfc8990bf4d5685c1360bd7026b9/canisters/ic-icrc1-ledger.wasm.gz.

The URL for the ledger .did file is https://raw.githubusercontent.com/dfinity/ic/<REVISION>/rs/ledger_suite/icrc1/ledger/ledger.did, so with the above revision it would be https://raw.githubusercontent.com/dfinity/ic/aba60ffbc46acfc8990bf4d5685c1360bd7026b9/rs/ledger_suite/icrc1/ledger/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:

curl -o download_latest_icrc1_ledger.sh "https://raw.githubusercontent.com/dfinity/ic/aba60ffbc46acfc8990bf4d5685c1360bd7026b9/rs/rosetta-api/scripts/download_latest_icrc1_ledger.sh"
chmod +x download_latest_icrc1_ledger.sh
./download_latest_icrc1_ledger.sh

These files will be used by the dfx.json file as described in the next step.

Step 4: Configure the dfx.json file.​

Open the dfx.json file in your project's directory. Replace the existing content with the following and make sure you replace <REVISION> in the candid and wasm URLs as shown in step 3:

{
  "canisters": {
    "icrc1_ledger_canister": {
      "type": "custom",
      "candid": "https://raw.githubusercontent.com/dfinity/ic/<REVISION>/rs/ledger_suite/icrc1/ledger/ledger.did",
      "wasm": "https://download.dfinity.systems/ic/<REVISION>/canisters/ic-icrc1-ledger.wasm.gz"
    }
  },
  "defaults": {
    "build": {
      "args": "",
      "packtool": ""
    }
  },
  "output_env_file": ".env",
  "version": 1
}

If you chose to download the ICRC-1 ledger files with the script, you need to replace the Candid and Wasm file entries with the path to the files:

...
"candid": "icrc1_ledger.did",
"wasm" : "icrc1_ledger.wasm.gz"
  ...

In an existing project you would only need to add the icrc1_ledger_canister canister to the canisters section instead of replacing the entire content of dfx.json.

Ledger test suite​

There is a test suite available to test ICRC-1 ledgers. If you are building your own ICRC-1 repository, it might be helpful to run this test suite against your locally deployed ICRC-1 ledger, or import the test suite directly through a Rust crate and add the tests to your repository. You can find a reference implementation of integrating the test suite to your repo.

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.