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 d87954601e4b22972899e9957e800406a0a6b929.

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/d87954601e4b22972899e9957e800406a0a6b929/canisters/ic-icrc1-ledger.wasm.gz.

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

{
"canisters": {
"icrc1_ledger_canister": {
"type": "custom",
"candid": "https://raw.githubusercontent.com/dfinity/ic/d87954601e4b22972899e9957e800406a0a6b929/rs/rosetta-api/icrc1/ledger/ledger.did",
"wasm": "https://download.dfinity.systems/ic/d87954601e4b22972899e9957e800406a0a6b929/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:

...
"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.

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.