Skip to content

Commit

Permalink
update ledger info and docs
Browse files Browse the repository at this point in the history
  • Loading branch information
@jessiemongeon1
jessiemongeon1 committed Dec 12, 2024
1 parent abda20a commit fcd8dd4
Show file tree
Hide file tree
Showing 2 changed files with 96 additions and 80 deletions.
129 changes: 76 additions & 53 deletions docs/developer-docs/defi/tokens/ledger/setup/icp_ledger_setup.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -8,8 +8,6 @@ import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow";

<MarkdownChipRow labels={["Intermediate" , "Tutorial"]} />

## Overview

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:
Expand Down Expand Up @@ -47,77 +45,77 @@ In this context, you can think of principal identifiers as a rough equivalent to
The main reason for introducing accounts was to allow a principal to control multiple accounts. While this could be abstracted away for a user by the wallet software, this is not possible for canisters.
:::


## Deploying the ledger locally

There are two ways of deploying an ICP ledger locally.
- Use [dfx-nns](/docs/current/developer-docs/developer-tools/cli-tools/cli-reference/dfx-nns) to deploy the entire NNS locally. Since the ICP ledger is part of the NNS, this command will also install an ICP ledger with canister ID `ryjl3-tyaaa-aaaaa-aaaba-cai`. This solution is fast and straightforward, but also more heavyweight.
- Deploy the ICP ledger `wasm` locally. This method is discussed and demonstrated in this guide, as it gives you more control over the deployment and is lightweight.
There are two ways of deploying an ICP ledger locally:

Deploying an ICP ledger locally gives you certain advantages over the default ledger from `dfx` that is installed with `dfx nns install`. For instance, you can define the `minting account`, you have control over the initialization arguments and you have control over which `wasm` version of the ICP ledger you want to interact with.
1. Use [`dfx nns`](/docs/current/developer-docs/developer-tools/cli-tools/cli-reference/dfx-nns) to deploy the entire NNS locally. Since the ICP ledger is part of the NNS, this command will also install an ICP ledger with canister ID `ryjl3-tyaaa-aaaaa-aaaba-cai`. This solution is fast and straightforward, but also more heavyweight.

The ICP ledger only exists on the mainnet and the `wasm` that is running on the mainnet is not meant to be used for other token deployments. It needs to be backward compatible and thus contains a lot of legacy code that should not be used when deploying a new ledger.
2. Deploy the ICP ledger locally using the canister's Wasm file. This method is discussed and demonstrated in this guide, as it gives you more control over the deployment and is lightweight.

If you want to deploy your own token or build an ICRC-1 ledger, have a look at the [guide on setting up an ICRC-1 ledger](/docs/current/developer-docs/defi/tokens/ledger/setup/icrc1_ledger_setup).
Deploying an ICP ledger locally using the Wasm or `.did` files gives you certain advantages over the default ledger from `dfx` that is installed with `dfx nns install`. For instance, you can define the `minting account`, you have control over the initialization arguments, and you have control over which Wasm version of the ICP ledger you want to interact with.

Follow the steps below to deploy your copy of the ledger canister to a local replica.
:::danger
The ICP ledger is not meant to be used for other token deployments because it needs to be backwards compatible and thus contains a lot of legacy code that should not be used when deploying a new ledger.

### Step 1: Make sure you use a recent version of the [IC SDK](/docs/current/developer-docs/getting-started/install).
If you don’t have the IC SDK installed, follow the instructions on the [installing the IC SDK](/docs/current/developer-docs/getting-started/install) section to install it.
If you want to deploy your own token, read the [guide on setting up an ICRC-1 ledger](/docs/current/developer-docs/defi/tokens/ledger/setup/icrc1_ledger_setup).
:::

### Step 2: Create a new dfx project with the command:
## Using `dfx nns install`

```
dfx new icp_ledger_canister
cd icp_ledger_canister
```
The [`dfx nns install`](/docs/current/developer-docs/developer-tools/cli-tools/cli-reference/dfx-nns) command can be used to deploy an instance of the entire NNS locally. The NNS includes the ICP ledger canister with canister ID `ryjl3-tyaaa-aaaaa-aaaba-cai`.

:::caution
## Using the most recent ICP ledger Wasm file

If using `dfx` version 0.17.1 or newer, choose 'Motoko' for the backend language, and 'No frontend canister' for the frontend language.
<Tabs>
<TabItem value="prereq" label="Prerequisites" default>

:::
<input type="checkbox"/> <a href="/docs/current/developer-docs/getting-started/install">Install the IC SDK.</a>

### Step 3: Determine the ledger file locations.
</TabItem>
</Tabs>

Go to the [releases overview](https://dashboard.internetcomputer.org/releases) and copy the latest replica binary revision. At the time of writing, this is `aba60ffbc46acfc8990bf4d5685c1360bd7026b9`.
- #### Step 1: Create a new `dfx` project or open an existing project.

The URL for the ledger Wasm module is `https://download.dfinity.systems/ic/<REVISION>/canisters/ledger-canister.wasm.gz`, so with the above revision it would be `https://download.dfinity.systems/ic/aba60ffbc46acfc8990bf4d5685c1360bd7026b9/canisters/ledger-canister.wasm.gz`.
- #### Step 2: Obtain the latest ledger Wasm and Candid files.

The URL for the ledger.did file is `https://raw.githubusercontent.com/dfinity/ic/<REVISION>/rs/ledger_suite/icp/ledger.did`, so with the above revision it would be `https://raw.githubusercontent.com/dfinity/ic/aba60ffbc46acfc8990bf4d5685c1360bd7026b9/rs/ledger_suite/icp/ledger.did`.
Go to the [releases overview](https://dashboard.internetcomputer.org/releases) and copy the latest replica binary revision.

The URL for the ledger Wasm module is `https://download.dfinity.systems/ic/<REVISION>/canisters/ledger-canister.wasm.gz`.

The URL for the ledger Candid file is `https://raw.githubusercontent.com/dfinity/ic/<REVISION>/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.

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

### Step 4: Create a new identity that will work as a minting account:
- #### Step 3: Create a new identity that will work as a minting account.

``` sh
dfx identity new minter
dfx identity use minter
echo $(dfx ledger account-id)
```

Record the output of these commands as your minting account ID.

Transfers from the minting account will create `Mint` transactions. Transfers to the minting account will create `Burn` transactions.
Record the output of these commands as your minting account ID. Transfers from the minting account will create `Mint` transactions. Transfers to the minting account will create `Burn` transactions.

### Step 5: Switch back to your default identity and record its ledger account identifier.
- #### Step 4: Switch back to your primary developer identity and record its ledger account identifier.

``` sh
dfx identity use default
dfx identity use MyIdentity
echo $(dfx ledger account-id)
```

Record the output of these commands as your default account ID.
Record the output of these commands as your developer account ID.

### Step 6: Configure the `dfx.json` file.
- #### Step 5: Configure the `dfx.json` file.

Open the `dfx.json` file in your project's directory. Replace the existing content with the following, updating the values of `MINTER_ACCOUNT_ID` and `DEFAULT_ACCOUNT_ID` with the values obtained in the previous steps:
Open the `dfx.json` file in your project's directory. Replace the existing content with the following, updating the values of `MINTER_ACCOUNT_ID` and `DEVELOPER_ACCOUNT_ID` with the values obtained in the previous steps:

:::info
`dfx.json` does not support referring to values through environment variables. Values must be hardcoded in plain text.
Expand Down Expand Up @@ -149,6 +147,7 @@ Open the `dfx.json` file in your project's directory. Replace the existing conte
}
```

:::danger
If you chose to download the ICP ledger files with the script you need to replace the Candid and Wasm file entries:

```json
Expand All @@ -158,55 +157,79 @@ If you chose to download the ICP ledger files with the script you need to replac
...
```

This `dfx.json` file also defines the init arguments for the ledger canister:
:::

This `dfx.json` file defines the init arguments for the ledger canister:

- Sets the minting account to the account identifier you saved in a previous step (`MINTER_ACCOUNT_ID`).
- Mints 100 ICP tokens to the `DEFAULT_ACCOUNT_ID` (1 ICP is equal to 10^8 e8s).
- Sets the transfer fee to 0.0001 ICP.
- Names the token `Local ICP / LICP`.

You can also pass these init args to the canister using the command line. [Learn more about init args](/docs/current/developer-docs/developer-tools/cli-tools/advanced-dfx/init-args/).
### Init arguments

### Step 7: Start a local replica.
You can also pass these init args to the canister [using the command line](/docs/current/developer-docs/developer-tools/cli-tools/advanced-dfx/init-args/#using-init_arg) or by [storing them in a file](/docs/current/developer-docs/developer-tools/cli-tools/advanced-dfx/init-args/#using-an-init_arg_file), then referencing that file in your `dfx.json` configuration:

```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
}
```

[Learn more about init args](/docs/current/developer-docs/developer-tools/cli-tools/advanced-dfx/init-args/).

- #### Step 6: Start a local replica.

``` sh
dfx start --clean --background
```

### Step 8: Deploy the ledger canister locally:
- #### Step 7: Deploy the ledger canister locally.

:::caution
In this workflow, 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 flag `dfx deploy --playground`) because it does not accept gzipped Wasm files.
:::

```
dfx deploy --specified-id ryjl3-tyaaa-aaaaa-aaaba-cai icp_ledger_canister
```

Take a moment to read the details of the call made above. Not only are you deploying the ICP ledger canister, you are also deploying the canister to the same canister ID as the mainnet ledger canister. This is to make it easier to switch between local and mainnet deployments.
:::info
You are deploying the local ICP ledger canister to the same canister ID as the mainnet ledger canister. This is to facilitate switching between local and mainnet deployments.
:::

Your local ICP ledger canister is up and running. You can now deploy other canisters that need to communicate with the ledger canister.

### Step 9: Interact with the canister.
- #### Step 8: Interact with the canister.

You can interact with the canister by running CLI commands, such as:

```
dfx canister call icp_ledger_canister name
```

This command will return the token's name, such as:

```
("Local ICP")
```

Or, you can interact with it using the Candid UI by navigating to the URL provided when the canister was deployed, such as:

```
http://127.0.0.1:4943/?canisterId=bnz7o-iuaaa-aaaaa-qaaaa-cai&id=ryjl3-tyaaa-aaaaa-aaaba-cai
```

After navigating to this URL in a web browser, the Candid UI will resemble the following:

![Candid UI](../../../_attachments/CandidUI.png)

Your local ICP ledger canister is up and running. You can now deploy other canisters that need to communicate with the ledger canister.
```
47 changes: 20 additions & 27 deletions docs/developer-docs/defi/tokens/ledger/setup/icrc1_ledger_setup.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -8,50 +8,42 @@ import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow";

<MarkdownChipRow labels={["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](https://github.com/dfinity/ICRC-1). 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.
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.

## Deploying the ledger locally
## Deploying the ICRC ledger locally

### Step 1: Make sure you use a recent version of the [IC SDK](/docs/current/developer-docs/getting-started/install).
If you don’t have the IC SDK installed, follow instructions on the [installing the IC SDK](/docs/current/developer-docs/getting-started/install) section to install it.
<Tabs>
<TabItem value="prereq" label="Prerequisites" default>

### Step 2: Create a new dfx project with the command:
<input type="checkbox"/> <a href="/docs/current/developer-docs/getting-started/install">Install the IC SDK.</a>

```
dfx new icrc1_ledger_canister
cd icrc1_ledger_canister
```

:::caution
</TabItem>
</Tabs>

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

:::
- #### Step 1: Create a new `dfx` project or open an existing project.

### Step 3: Determine ledger file locations.
- #### Step 2: Obtain the latest ledger Wasm and Candid files.

Search for [ledger-suite-icrc releases](https://github.com/dfinity/ic/releases?q=ledger-suite-icrc&expanded=false) and select the latest ICRC ledger suite release. At the time of writing, this is [`ledger-suite-icrc-2024-11-28`](https://github.com/dfinity/ic/releases/tag/ledger-suite-icrc-2024-11-28).
Search for [ledger-suite-icrc releases](https://github.com/dfinity/ic/releases?q=ledger-suite-icrc&expanded=false) 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`, so with the above release it would be `https://github.com/dfinity/ic/releases/download/ledger-suite-icrc-2024-11-28/ic-icrc1-ledger.wasm.gz`.
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 .did file is `https://github.com/dfinity/ic/releases/download/<RELEASE>/ledger.did`, so with the above release it would be `https://github.com/dfinity/ic/releases/download/ledger-suite-icrc-2024-11-28/ledger.did`.
The URL for the ledger Candid file is `https://github.com/dfinity/ic/releases/download/<RELEASE>/ledger.did`.


#### Optional:
#### 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:

``` sh
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.

### 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 step 3:
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:

``` json
{
Expand Down Expand Up @@ -82,12 +74,13 @@ If you chose to download the ICRC-1 ledger files with the script, you need to re
...
```

:::info
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](https://github.com/dfinity/ICRC-1/tree/main/test). 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](https://github.com/dfinity/ICRC-1/tree/main/test/ref).

There is a test suite available for [ICRC-1 ledgers](https://github.com/dfinity/ICRC-1/tree/main/test). 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](https://github.com/dfinity/ICRC-1/tree/main/test/ref).

## Next steps

Expand Down

0 comments on commit fcd8dd4

Please sign in to comment.