03 — External canisters

Ledger and Identity canisters

In this chapter we will walk you through the deployment and usage of the Ledger and Identity canisters and explain a few things that are happening in the background. Be sure your local dfx network is running and let's dive in!

Identity Canister

On the Internet Computer, authentication is performed via the Internet Identity canister. When authenticating against any kind of web application on the IC:

• The user gets redirected to the Internet Identity application
• The user follows the steps for a proper authentication
• The internet identity stores data related to user identity in the browser, then redirects them to the application

This is comparable to "Login with Google", or "Login with Facebook", but in a decentralized and more secure way.

On the mainnet, the Internet Identity canister is already deployed, but in local development we will have to do it ourselves. In order to do that, we will clone and build the canister directly from the GitHub repository.

Open the Makefile and take a look at the download-identity instruction. We can see that it executes scripts/download-identity.sh. Let's open that file! We can see that all it does is clone from the repo in an external directory and then install the required dependencies.

Clone the repo:

make download-identity

To build and deploy the canister take a look at the identity instruction in the Makefile. It executes scripts/deploy-identity.sh. Open that script and take a look at the following command:

II_FETCH_ROOT_KEY=1 dfx deploy --no-wallet --argument '(null)'

This command builds and deploys the canister to our network. Let's dissect it:

• II_FETCH_ROOT_KEY=1 - This is required internally by the canister in order to run properly on a local network.
• dfx deploy - The command used to build and deploy our canister based on the configuration found in dfx.json. In this case, the command is using the dfx.json inside the internet-identity directory.
• --no-wallet - Indicates that we want to use our own identity as the owner of the canister, not the identity of the wallet canister.
• --argument '(null)' - The Internet Identity is declared as an actor class and thus requires some arguments during deployment.

Now let's run:

make identity

The compilation may take some time during the first run so now it's the perfect moment to get up and stretch a little bit!

The canister should now be deployed to the local network. We will use it later when interacting with the frontend.

Ledger Canister

The Ledger canister is responsible for ICP mint and transfer on the Internet Computer. It exposes a set of functions that allow us to transfer currency from one account to another.

On the mainnet, the Internet Identity canister is already deployed, but in local development we will have to do it ourselves. In order to do that, we will use the ledger.private.did that we already have in our project root. We will also show you how to generate the candid interfaces and the WASM file yourself.

The ledger canister has 2 candid interfaces:

• ledger.private.did - exposes functions that allow deployment and management of the canister by the admin principal.
• ledger.public.did - allows access to functions like transfer and account_balance.

Deployment

Before deploying the canister, we require a new account, so run the following command:

dfx identity new minter

Now open dfx.json and (on line 6) change ledger.public.did to ledger.private.did. Be sure to save the file and run:

make identity

Change ledger.private.did back to ledger.public.did.

The canister should now be deployed and running!

Let's open Makefile and see what happens behind the curtains. We can see that it runs scripts/deploy-identity.sh. Open that file and take a look at the commands. First we store the default account ids of minter and default principals, then we deploy the canister with the following command:

dfx deploy ledger --argument '(record {minting_account = "'${MINT_ACC}'"; initial_values = vec { record { "'${LEDGER_ACC}'"; record { e8s=100_000_000_000 } }; }; send_whitelist = vec {}})'

Let's dissect the command once again:

• dfx deploy ledger - looks at the canister named ledger in our dfx.json and deploys the canister based on that configuration.
• --argument '...' - provides the required argument to the ledger
  actor class. The argument is a record that contains the following data:
  • minting_account - used to specify the minting account.
  • initial_values - in our case we use it to give some currency to the default account on initialization.

Usage

In order to transfer some currency from the default account to some other account we have to:

dfx identity use default
dfx canister call ledger transfer '(record { to = blob "\d2EP?\27~\7f\83\fc2o\1b\fbu8\c5\0b\8d\ee\83\11\be\8c\06C{\9c\d6!\af\b3e"; memo = 1; amount = record { e8s = 2_00_000_000 }; fee = record { e8s = 10_000 }; })'

This is an example of how to call the transfer method defined in the ledger actor from command line. We'll see more practical usage later on in the tutorial.

Building from Repo (optional)

If you want to build the ledger candid interfaces and wasm by yourself, run the following command:

make download-ledger

This may take some time, but after you will have all the required files in the root directory.

This instruction executes scripts/download-ledger.sh. That script clones the ic repo, builds the ledger wasm and interfaces, then copies them to our project's root directory.