Skip to main content

1.4 Acquiring and using cycles

Beginner
Tutorial

If you recall from the previous module, Internet Computer terminology, cycles are used to measure the resources, such as memory, storage, and compute power, that are used by a canister. When a canister is deployed on the mainnet, cycles are 'charged' for every action that a canister performs.

To obtain cycles, the Internet Computer Protocol's utility token, ICP, can be converted into cycles and transferred into a canister to be used to pay for that canister's consumed resources. Cycles have a fixed price in XDR in order to make canister costs predictable and independent of the price of ICP. One trillion cycles always correspond to one XDR.

Since cycles are not a currency and are only used to pay for a canister's consumed resources, developers manage the distribution of cycles through a system canister called the cycles ledger. The cycles ledger provides functionality for developers to convert ICP into cycles, accept incoming cycles, send cycles to other canister, and create canisters with cycles.

A developer's cycles balance is associated with the principal identity.

Recall that a principal is an entity that can be authenticated by ICP.

Canisters each have their own cycles balance, and don't use cycles associated with your identity. When you need to call a method that requires cycles, if the canister doesn't have enough cycles in it's balance or if you're creating a new canister, you will need to proxy the call through the cycles ledger in order to attach the required cycles. To assure canisters have a cycles balance, you need to deposit cycles into the canister's cycles balance, known as 'topping up' the canister.

For local canister execution, operations performed using cycles are done in the background. In a production environment with canisters deployed on the mainnet, canisters will need to have cycles explicitly registered and transferred into them. Production canisters can also have principals configured to act as custodians, which have permission to access the cycles wallet balance, wallet information, and send and receive cycles for the canister.

In this tutorial, you'll learn how to obtain cycles. Then, in the next tutorial you'll deploy a canister to the mainnet using those cycles.

Prerequisites​

Before you start, verify that you have set up your developer environment according to the instructions in 0.3 Developer environment setup.

Creating a developer identity​

When you initially use dfx, a default developer identity is created. This identity is a principal data type, often referred to as your principal identifier. This identity is similar to a Bitcoin or Ethereum wallet address that you would use to interact with those ecosystems.

However, your developer identity principal is not the same as your account identifier that is specified in the ledger. Your identity principal and your account identifier are related, but they use different formats.

Your developer identity is a private/public key pair, while your principal identity is derived from the public key.

Each principal can control multiple accounts in the ICP (and other) ledgers.

You can learn more in the IC specification.

In this tutorial, you'll create a new identity principal with dfx, which you'll use to obtain and manage cycles.

First, assure that dfx is running; if not, use the following command to start it:

dfx start --clean --background

Next you will create a new developer identity with the command:

dfx identity new DevJourney

This command will return a seed phrase, which will be required to recover your identity if you ever need to. This seed phrase should be backed up, so that any cycles associated with your identity are not lost.

Set this identity as the one to be used by dfx in the current terminal session with the command:

dfx identity use DevJourney

You can get the principal ID of this identity with the command:

dfx identity get-principal

The principal will resemble the following format:

tsqwz-udeik-5migd-ehrev-pvoqv-szx2g-akh5s-fkyqc-zy6q7-snav6-uqe

Acquiring cycles​

Cycles are required to deploy to the mainnet. If you only plan to deploy to your local environment for testing, cycles are not required. The following tutorials will focus on local deployment to assure anyone can complete this tutorial series.

You may skip this tutorial if you do not plan to deploy to the mainnet.

Cycles can be obtained by converting ICP tokens into cycles. There are a few ways to obtain ICP tokens, such as:

  • Purchasing ICP tokens directly through a crypto exchange.
  • Receiving ICP tokens as a reward for participating in the NNS governance.
  • Receiving a grant of ICP tokens through the DFINITY Foundation.
  • Receiving ICP tokens in return for providing resources as a node provider.

You need to obtain ICP tokens, then convert them into cycles using dfx. However, when participating at DFINITY events like hackathons or working on a developer grant, you will receive a coupon which you can redeem to claim free cycles from the cycles faucet.

Each developer identity has both a principal and a ledger account identifier.

A principal has the format itk7v-ihlxk-ktdrh-fcnst-vkoou-orj77-52ogl-jqwj5-zpfdv-az3lr-xqe and is used for canister ownership, management, and holding cycles.

A ledger account identifier has the format e213184a548871a47fb526f3cba24e2ee2fbbc8129c4ab497ef2ce535130a0a4 and is used to send and receive tokens like ICP.

First, get your account's ledger account ID:

dfx ledger account-id

Then, send ICP tokens to this ledger account ID. You can obtain ICP tokens from an exchange or through a developer grant. If you are using an exchange, initiate a withdrawal transaction, then enter the ledger account ID as the "destination" address to send ICP tokens to.

After you have sent ICP tokens to your ledger account, check the ICP balance.

dfx ledger balance --network=ic

Converting ICP to cycles is done through the cycles ledger, a ledger canister that enables developer identities to convert, hold, send, and receive cycles.

The price of cycles is fixed against the price of XDR, where 1 trillion cycles equals 1 XDR.

Cycles are measured in very large numbers, such as billions and trillions. When you talk about cycle transfers and replenishment, you will usually operate with trillions of cycles.

These commands must be run with the --network=ic flag. The cycles ledger is not necessary for local development and therefore not part of the local replica.

Next, convert ICP into cycles. Replace AMOUNT with the number of ICP tokens you want to convert into cycles.

dfx cycles convert --amount AMOUNT --network=ic
Calculating how many cycles you need

The amount of cycles that your canister will use depends on a variety of factors. Cycles are charged for storage, compute, update messages, special features, and more. To get an approximation, you can view the detailed cycles cost table or use the cycles pricing calculator.

Lastly, confirm that the ICP was properly converted into cycles by checking the cycles balance.

dfx cycles balance --network=ic

Resources​

To further explore cycle management please see the following articles:

Need help?​

Did you get stuck somewhere in this tutorial, or feel like you need additional help understanding some of the concepts? The ICP community has several resources available for developers, like working groups and bootcamps, along with our Discord community, forum, and events such as hackathons. Here are a few to check out:

Next steps​

In this tutorial, you set up our identity and acquired free cycles from the cycles faucet. Now that you have cycles, you can deploy your first dapp on the mainnet.