Cycles ledger

Beginner

Tutorial

When developing and deploying canisters on the Internet Computer, developers need to have cycles to pay for the resources used by their canisters. The cycles ledger canister has been developed as an alternative to the cycles wallet canister for cycles management.

The biggest difference between the cycles ledger and cycles wallet is that the cycles ledger is a single global ledger canister, whereas the cycles wallet canister must be deployed separately for every developer to be used. Additionally, the cycles wallet has some downsides that the cycles ledger remedies. Some of these are:

• Cycles wallets are a complex solution to associate cycles with principal IDs.
• Cycles wallets consume cycles themselves, meaning developers need to pay cycles to store cycles.
• If a cycles wallet canister ID is lost, the cycles in that cycles wallet canister are also lost.

In short, the cycles ledger simplifies cycle management by providing the ability for principal IDs to hold cycles.

The cycles ledger currently complies with the ICRC-1, ICRC-2, and ICRC-3 standards. In addition to standard ledger functionality, the cycles ledger also interacts with the NNS canisters and user canisters to provide cycles ledger-specific functions, such as:

• Accepting incoming cycles sent from other canisters.
• Sending cycles to other canisters.
• Creating new canisters using cycles.

It is important to note that the cycles ledger does not provide the ability to make arbitrary calls to other canisters with cycles, while the cycles wallet can. This is because open call contexts may cause complications with the cycles ledger.

If you need to make arbitrary calls to other canisters with cycles, a cycles wallet can be used as before. The cycles ledger can be used to load the cycles wallet with cycles.

Canister IDs

Canister name	Canister ID	Dashboard link
Cycles ledger	um5iw-rqaaa-aaaaq-qaaba-cai	https://dashboard.internetcomputer.org/canister/um5iw-rqaaa-aaaaq-qaaba-cai
Cycles ledger index	ul4oc-4iaaa-aaaaq-qaabq-cai	https://dashboard.internetcomputer.org/canister/ul4oc-4iaaa-aaaaq-qaabq-cai

Using the cycles ledger

The cycles ledger is supported by default in dfx version 0.22.0 and newer.

Obtaining ICP

To use the cycles ledger, first, you need ICP tokens. There are a few different ways to obtain ICP tokens, such as:

• Purchasing ICP tokens directly through an exchange that lists ICP tokens available for trade. To see all available places to purchase ICP tokens, check out this page.
• Trading other tokens for ICP on a decentralized exchange.
• Receiving tokens as rewards for participating in the governance of the Internet Computer.
• Receiving a grant of tokens through the Internet Computer Association (ICA) or the DFINITY Foundation.
• Receiving tokens as remuneration for providing computing capacity as a node provider.

Once you have obtained ICP, you also need to have an account controlled via dfx to transfer those tokens. This step is necessary to create cycles and canisters. To get an account ID for an account controlled via dfx, first determine which dfx identity you are using with the command:

dfx identity whoami

If you're using the default identity, you should create a new identity with the command:

dfx identity new IDENTITY_NAME

Replace IDENTITY_NAME with the identity name of your choice, such as 'MyIdentity`.

Your identity's seed phrase will be returned. Be sure to save this in a secure location. Then, set this identity to be used by the current session:

dfx identity use IDENTITY_NAME

Then, to get the account ID for this identity, use the command:

dfx ledger account-id

This will display your account ID on the ICP ledger. It looks similar to this:

e213184a548871a47fb526f3cba24e2ee2fbbc8129c4ab497ef2ce535130a0a4

This account ID will be where you need to send your ICP tokens to create cycles and canisters.

Then, to return the principal ID associated with your identity, run the command:

dfx identity get-principal

Your cycles on the cycles ledger will be stored under this principal ID.

Checking your cycles balance

To check the cycles balance of your user principal ID, use the command:

dfx cycles balance --network ic

Converting ICP to cycles

To convert ICP into cycles using the cycles ledger, use the command:

dfx cycles convert --amount AMOUNT --network ic

Replace AMOUNT with the number of ICP to convert into cycles, such as 2.7. Alternatively, the amount can be specified in terms of ICP and e8s (where 100,000,000 e8s = 1 ICP) using the options --icp and --e8s. For example, 2.7 would be expressed as --icp 2 --e8s 70_000_000.

Transferring cycles to a principal

To transfer cycles to another principal ID, use the command:

dfx cycles transfer AMOUNT PRINCIPAL_ID (--subaccount [SUBACCOUNT]) --network ic

Replace PRINCIPAL_ID with the principal ID you'd like to transfer the cycles to, such as tsqwz-udeik-5migd-ehrev-pvoqv-szx2g-akh5s-fkyqc-zy6q7-snav6-uqe and AMOUNT with the number of cycles, such as 34000000. Optionally, a subaccount can be provided, in which case the recipient will receive the funds in the provided subaccount.

Using suffixes such as 500k or 5TC is supported. View the full list of suffix options.

Topping up a canister

To transfer cycles into a canister to top it up, use the command:

dfx cycles top-up CANISTER_ID AMOUNT --network ic

Replace CANISTER_ID with the canister ID you'd like to transfer the cycles to, such as gastn-uqaaa-aaaae-aaafq-cai, and AMOUNT with the number of cycles, such as 100000000.

Creating a canister using cycles

New canisters can be created using the cycles ledger by using the dfx canister create and dfx deploy commands.

Both of these commands have the following options and syntax to create a new canister:

dfx canister create CANISTER_NAME --with-cycles AMOUNT --network ic
dfx deploy CANISTER_NAME --network ic

Replace CANISTER_NAME with a name for the new canister and AMOUNT with the number of cycles to deposit into the canister's cycles balance.

With these two commands, there are two optional flags that can be used:

• dfx create canister CANISTER_NAME --next-to CANISTER_ID: --network ic The new canister will be installed on the same subnet as the canister provided.
• dfx create canister CANISTER_NAME --subnet SUBNET_ID --network ic: The new canister will be installed on the given subnet.

If no flag is specified and there aren't any canisters that exist in the project, a random subnet is used.

If no flag is specified and the project contains canisters on a single subnet, then that subnet is used.

If no flag is specified and the project contains canisters on multiple subnets, dfx will prompt you to specify a subnet.

Fees

Most functions of the cycle ledger incur a fee. The full breakdown of fees can be found below:

• To transfer cycles between different principal IDs using the cycles ledger, the transfer fee is 100M cycles per transaction.
• To send cycles from the cycles ledger to another canister, the fee is 100M cycles.
• To create a canister, the fee is the transfer fee (100M cycles), plus the canister creation fee, which scales linearly with the size of the subnet that the canister is created on. For example, if the canister is created on a 13-node subnet, the fee is 100B cycles. This means the total fee will be 100_100_000_000 cycles.

Switching from the cycles wallet to cycles ledger

To help transition from the commands and workflows you may be accustomed to using with the cycles wallet, the table below provides a translation from cycles wallet to cycles ledger commands.

All commands shown below are for workflows involving mainnet development. For local development, omit the --network ic flag.

Function	Cycles wallet command	Cycles ledger command
Checking the cycles balance	dfx wallet balance --network ic	dfx cycles balance --network ic
Converting ICP tokens into cycles	dfx ledger create-canister PRINCIPAL_ID --amount AMOUNT --network ic	dfx cycles convert --amount AMOUNT --network ic
Transferring cycles	dfx wallet send PRINCIPAL_ID AMOUNT --network ic	dfx cycles transfer AMOUNT PRINCIPAL_ID (--subaccount [SUBACCOUNT]) --network ic
Redeeming a cycles coupon	dfx wallet redeem-faucet-coupon 'ABCDE-ABCDE-ABCDE'	dfx cycles redeem-faucet-coupon ABCDE-ABCDE-ABCDE --network ic
Topping up a canister	dfx wallet send PRINCIPAL_ID AMOUNT --network ic	dfx cycles top-up CANISTER_ID AMOUNT --network ic
Creating a canister with cycles	dfx canister call CYCLES_WALLET_CANISTER_ID wallet_create_canister '(record { cycles = 5000000000000 : nat64; controller = principal "PRINCIPAL_ID"})' --network ic	dfx canister create CANISTER_NAME --with-cycles AMOUNT --network ic