Skip to main content

1.4 Acquiring and using cycles

Beginner
Tutorial

Overview​

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 will also require principals to be configured to act as custodians, which are principals that have permission to 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 using a cycles coupon​

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.

For new developers, a free cycles coupon can be obtained and redeemed for 10T free cycles that can be used to get started with dapp deployment. For this developer journey, you'll be obtaining and using that free cycles coupon.

This coupon is good for new developers since it doesn't require that you transfer ICP tokens into cycles, and doesn't require a purchase of tokens to get started.

First, navigate to the website https://faucet.dfinity.org.

To obtain a coupon code to use the cycles faucet, you need to put in a written request for the coupon via the DFINITY dev official Discord server.

Click on the REQUEST CYCLES button on the faucet web page to join the Discord server.

Getting Coupon

Once inside the Discord server, navigate into the #cycles-faucet channel.

Cycles-faucet

In this channel, execute the following slash command:

/request

This command will make a call to the IC Cycles Faucet Bot. This bot will prompt you to fill out a survey in the channel.

Once the survey has been completed, our team will review your submission. If accepted, the faucet bot will send you a private message with a coupon code.

Please ensure that your Discord settings are set to allow direct messages from other users. If you do not have this setting enabled, you will not receive a direct message from the faucet bot.

Head back to the https://faucet.dfinity.org webpage.

Now, click NEXT STEP to continue.

Now that you have a coupon code, enter your coupon code within the faucet UI.

Enter Coupon

Click NEXT STEP to continue.

Return to your terminal window. If you closed the window in the process, run the following commands to start dfx and use your previously created identity:

dfx start --clean --background
dfx identity use DevJourney

This workflow utilizes the cycles ledger feature. If you'd like to use the cycles wallet instead, view the cycles wallet documentation.

To use the cycles ledger, you will need dfx version 0.19.0, and you will need to set the following environmental variable with the command:

export DFX_CYCLES_LEDGER_SUPPORT_ENABLE=1

Then, redeem your coupon with the command:

dfx cycles --network ic redeem-faucet-coupon COUPON_CODE

Replace COUPON_CODE with the cycles coupon code sent to you by the DFINITY faucet bot.

Verify your cycles balance with the command:

dfx cycles --network ic balance

This should return an output showing 10T cycles associated with your identity.

Converting ICP tokens to cycles​

If you've already redeemed a cycles coupon in the past, or if you've already used the cycles from your coupon, you can convert ICP tokens into cycles.

Before you can convert ICP tokens into cycles, first you need to obtain ICP tokens. ICP tokens can be purchased through a crypto exchange, or they can be received through other activities such as participating in the NNS governance and receiving grants from the DFINITY foundation.

To get your account ID so you know where to send your ICP tokens, run the command:

dfx ledger account-id

This will display your account number on the ICP ledger, which will resemble the following:

e213184a548871a47fb526f3cba24e2ee2fbbc8129c4ab497ef2ce535130a0a4

Once you have sent some ICP to this account ID, you can verify that they were received by checking the balance with the command:

dfx ledger --network ic balance

This will output something like this:

12.49840000 ICP

Once you have your ICP tokens ready, you will need to convert them into cycles. To convert ICP into cycles using the cycles ledger, use the command:

dfx cycles convert AMOUNT --network ic

This workflow utilizes the cycles ledger feature. If you'd like to use the cycles wallet instead, view the cycles wallet documentation.

Please note that the cycles wallet will be removed from dfx in a future release.

Replace the AMOUNT with the number of ICP to convert into cycles.

To verify that your ICP was converted into cycles properly, query the balance of the wallet with the command:

dfx cycles balance --network ic

This should return your balance in cycles:

6.951 TC (trillion cycles).

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.