Skip to main content

ICRC-1 ledger local setup

Intermediate
Tutorial

ICRC-1 is a token standard 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 set up an existing ICRC-1 ledger implementation rather than how to build an ICRC-1 ledger yourself.

Deploying the ICRC ledger locally​

Install the IC SDK.

  • Step 1: Create a new dfx project or open an existing project.​

  • Step 2: Obtain the latest ledger Wasm and Candid files.​

Search for ledger-suite-icrc releases and select the latest ICRC ledger suite release.

The URL for the ledger Wasm module is https://github.com/dfinity/ic/releases/download/<RELEASE>/ic-icrc1-ledger.wasm.gz.

The URL for the ledger Candid file is https://github.com/dfinity/ic/releases/download/<RELEASE>/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

  • 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 <RELEASE> in the candid and wasm URLs as shown in the previous step:

{
  "canisters": {
    "icrc1_ledger_canister": {
      "type": "custom",
      "candid": "https://github.com/dfinity/ic/releases/download/<RELEASE>/ledger.did",
      "wasm": "https://github.com/dfinity/ic/releases/download/<RELEASE>/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 for 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.