Internet Computer Identity — a Journey of Discovery
This article responds to the question: “Why is the Internet Computer (IC) identity important for a developer?’’
When I started to develop with the IC, I did not pay attention to where and what my IC identity is. As a result, it caused a lot of confusion and put at risk of losing control of the running canisters on the IC mainnet. This article is written from the perspective of an IC developer who would like to get back self control over the deployed canisters.
The Importance of the IC Identity
If a developer gets rid of the IC identity he/she can lose control over the deployed canisters by losing the ability to give the canister more cycles. This causes either the freeze of the canisters or the canisters cannot be updated anymore. Both options are not desirable. The current threshold limit for a running canister is around 2.592.000 cycles. Especially in a production scenario it is very important to keep an eye on having control over the canisters.
In this article I wrap up my learnings and findings about the importance of the IC identity. The diagram below outlines a typical development and deployment constellation. I will cover the development and deployment constellation in the following descriptions.
Explanation of the IC Identity
When you start with the IC development you will receive a so-called identity. This identity will be created automatically through several dfx actions. At the end, there will be an identity named default. This identity should not be confused with IC identity itself. The IC identity is an anonymous blockchain authentication framework supported by the IC.
To make the difference clear, in this article I introduce the Developer Identity (DI). This DI stands for a unique representation. It is needed as an identifier to deploy and upgrade the canisters and also to top-up the canisters with cycles — the fuel of the IC.
Cycles reflect the operational cost of communication, computation, and storage that canisters consume. It is worth to note that — unlike the Internet Computer Protocol (ICP) tokens — cycles are only associated with canisters through the cycles wallet and not to the user or developer principals identifier.
The DI is basically represented by a private key pem file on the machine. This key file is NOT located in the IC projects folder structure as one might guess. It lives under the $HOME folder of the machine. This is good to know!
Furthermore, as you can see in the graph below there are three elements which belong to an identity:
- Name; The name is simply a name on the local machine and has no further use.
- Principal Identifier; The principal identifier represents a unique identifier for the particular identity. This identifier will be visible for the developer and represents the current user. It can also be seen as the public key in a special hash format.
- Account Identifier; The account identifier is the link to the ledger canister. This identifier is needed to get some ICPs for the cycle conversion.
At this point it is worth noting that you should always make a backup of your identity files!
One of my surprising observations was that there is no direct public key file available. The public key is derived from the private key file and is used by request authentication. The following picture describes a typical structure of a request call. For instance, when a function call is done the request will have the following envelope. The request content will be extended by the signature and the public key of the identity. With these payload data the receiver can do some checks and finally authenticate the request.
The dfx tool will create a so-called default identity if the identity is checked for the first time. This can be done with the following command:
On the local machine you can have as many identities you want. You can find all local identities located under the following folder:
Check it with a tree command as follows:
You can also use a dedicated dfx command to get all available identities on your machine:
As a developer you can switch between different identities for test scenarios. Later, you will see that there is a so-called cycles wallet. This cycles wallet is associated with the identity. In practice, if you would like to have one cycles wallet per project you need different identities per project.
Furthermore, you can use the principal identifier associated with the caller of a function to implement a basic form of access-control in your program as well.
There are some more useful commands for the identity management. You can find these commands in the official dfx identity documentation.
To switch between different identities use the following command:
To display the principal identifier from the currently used identity take:
A typical principal identifier looks like that:
ryea5–3kfon-…..-k3j2g-3xpkb-twaet-jqe
Although this identity is part of the local system it has a link to the IC mainnet. This link is called account identifier. This account identifier is a direct representation of the particular identity on the IC mainnet. It is used for converting ICP to cycles.
As you can see in the visualisation above, the identity named default has its own principal identifier and a corresponding account identifier.
Like the textual representation of the identity principal identifier, the account identifier is also derived from the private key and used to represent the identity in the IC mainnet ledger canister. Query your account identifier with the following command:
A typical account identifier looks like that:
93476a7623bb27…489a6aa3d…930a9a7cd1e5ec98
The DI can be used for pre-build roles like controllers and custodians as well. This is shown in the next section.
Controller and Custodian Roles
A user principal or a canister principal can be assigned to a canister as a controller or custodian role. According to the official documentation a controller is the most privileged role and a principal assigned to the controller role can perform privileged tasks, including the following:
- Add and remove other principals as controllers;
- Authorise and deauthorize other principals as custodians;
- Add entries to the cycles wallet address book;
- Access the cycles wallet balance and all other wallet-related information;
- Send cycles to other canisters;
- Accept receipt of cycles from other canisters;
- Rename the cycleswallet;
- Create canisters and additional cycles wallets.
On the other hand, a principal assigned to the custodian role can only perform a subset of cycles wallet management tasks, including the following:
- Access the cycles wallet balance and all other wallet-related information;
- Send cycles to other canisters;
- Accept receipt of cycles from other canisters;
- Create canisters.
Furthermore, an identity can also be associated with a cycles wallet. When you deploy a canister to the IC mainnet you need these cycles. The predetermined way to do that is visualised in the following section.
Cycles Wallet
A cycles wallet is a special type of canister. The cycles wallet holds the cycles required to perform operations such as creating new canisters or other operations associated with the canister. Different operations need a different amount of cycles. Here you can get a first impression about the Computation-and-storage-costs.
At this point, it is worth to note again that these operations are executed by using the canister principal for the cycles wallet instead of the user principal.
Before you can deploy a canister to the IC mainnet or do some other operations you need enough cycles. The high-level visualisation below shows the conversion of ICPs to cycles.
The essentials of the cycles wallet can be summarised as follows:
- There are two possibilities to get some ICPs. Either you buy some ICPs on an exchange of your choice or you swap existing coins to ICP.
- With ICPs you can use the account identifier to convert some cycles and deposit them into a cycles wallet.
- The cycles wallet can supply the canister with enough cycles to operate properly. One cycles wallet can be used for different projects.
To check the balance of the cycles wallet there are two possibilities. Firstly, you can check the cycles wallet balance using the dfx cli tool. And secondly, you can access the wallet using a graphical user interface (GUI) provided directly by the cycles wallet itself. In both cases you need the cycles wallet canister identifier to check the balance.
To check the balance switch into the deployed project folder. It is also possible to call the following commands outside of that folder.
Use the dfx identity get-wallet command to display the canister identifier for the wallet associated with the current identity principal.
Another way to get the wallets canister identifiers is to inspect the wallets.json file on the machine. Execute the following command to print the content of the wallets.json file in the terminal.
After knowing the canister identifier the balance of the wallet can be checked. There are three options for that:
- Use the dfx wallet command.
- Use the dfx canister command.
- Use the canisters GUI.
Check the cycles balance with the dfx wallet command.
Check the cycles balance with the dfx canister command.
Check the cycles balance with the built-in canister GUI. If you take this option you can open a browser and use the following Link https://[canister Id].ic0.app. In this case you have to authorise yourself with a valid IC identity identifier. As a result you will see the webpage to manage the cycles.
The cycles wallet is controlled by the associated principal identifier. Each associated principal identifier can have different roles. For knowing which principal identifier has which role you can use the following commands.
List current principals that have full control over the cycles wallet in the current project by running the following command:
To do the same for the custodians use the following command:
As already mentioned, these roles can interact with the cycles canister according to the rights described above.
As you can see in the table below, you can use one cycles wallet to maintain different projects.
Key Findings
In this article you have discovered the IC identity from a developer perspective. Let me summarise, finally, the key findings:
- Always make a backup of the identity folder.
- The principal identifier represents the textual representation of the private key and can also be seen as the public key.
- The account identifier is the link to the IC mainnet ledger.
- Be careful who you assign to the controllers and custodian roles.
- Watch the account balance of the canisters to avoid falling below the threshold limit.
- Use different identities for different projects in the case you work for different clients.
