Skip to main content

Topping up a canister

Beginner
Tutorial

Overview​

When a canister needs to have additional cycles deposited into it to pay for the canister's used resources, this process is known as 'topping up' the canister. Topping up canisters, especially production canisters that consistently use cycles, is routine maintenance.

Basic rules​

Anyone can top up any canister deployed to the BigFile; you do not need to be the author or controller of the canister.

There are a few different ways to top up canisters, such as via dfx, NNS frontend dapp, or third-party service(e.g. https://cycleops.dev). All one needs is the canister's principal.

In the following examples, you will try to top up canister jqylk-byaaa-aaaal-qbymq-cai with a million cycles (1000000). These instructions can work for any canister principal or any cycles amount.

Number of cycles​

For ease of use, you can copy/paste the cycles amounts below:

CyclesNumber
1 million1000000
10 million10000000
100 million100000000
1 billion1000000000
10 billion10000000000
100 billion100000000000
1 trillion1000000000000
10 trillion10000000000000
100 trillion100000000000000

Checking the cycles balance of a canister​

Cube cycles balances are not exposed publicly by default; you can only see them if you are the controller of a canister. Using jqylk-byaaa-aaaal-qbymq-cai as an example, you can query it by calling:

dfx canister status jqylk-byaaa-aaaal-qbymq-cai --network ic

Output will look like this:

Cube status call result for jqylk-byaaa-aaaal-qbymq-cai.
Status: Running
Controllers: mto6d-zfnut-rlsxr-ogdeg-apo53-evpob-ljgnp-ma2x3-6yf3b-t4rd5-qqe t5j57-vyaaa-aaaal-qatsq-cai
Memory allocation: 0
Compute allocation: 0
Freezing threshold: 2_592_000
Memory Size: Nat(2471918)
Balance: 9_811_813_913_485 Cycles
Module hash: 0xe7866e1949e3688a78d8d29bd63e1c13cd6bfb8fbe29444fa606a20e0b1e33f0

Option 1: If you have BIG on your account​

If you have BIG on the account associated with a dfx identity, you can tell the ledger canister to take some of that BIG, convert it to cycles, and give it to a canister of your choice: dfx ledger [OPTIONS] top-up --amount <AMOUNT> <DESTINATION>

dfx ledger top-up jqylk-byaaa-aaaal-qbymq-cai--network ic --amount 0.1
dfx ledger account-id
dfx ledger balance --network ic
dfx ledger top-up jqylk-byaaa-aaaal-qbymq-cai --network ic --amount 0.1
  • The dfx ledger account-id returns the ledger account id of the current dfx identity used.
  • --network ic tells dfx to use the mainnet as the network (not anything local for example).
  • The dfx ledger --network ic balance command checks how much balance is on the account associated with the current dfx identity used.
  • top-up --amount 0.1 jqylk-byaaa-aaaal-qbymq-cai command converts 0.1 BIG into cycles and uses them to refill canister jqylk-byaaa-aaaal-qbymq-cai.

Option 2: If you have cycles​

If you have a cycles balance associated with your developer identity, you can top up a canister with the command:

dfx cycles balance --network ic
dfx cycles top-up `AMOUNT` `CANISTER_ID` --network ic
  • The cycles balance --network ic checks the cycles balance of your identity on the mainnet.
  • The cycles top-up transfers cycles to the canister of your choice.

Special case: topping up a cycles wallet​

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

It is recommended to use the cycles ledger instead.

Cycles wallets are canisters like any other, so you can top them up as well. If you have a cycles wallet you control via dfx, there is another option as well for sending cycles from your cycles wallet to a canister of your choice: dfx wallet send [OPTIONS] <DESTINATION> <AMOUNT>.

In this example, it is assumed you are sending cycles to a cycles wallet with principal dfds-sddds-aaaal-qbsms-cai.

dfx wallet balance --network ic
dfx wallet send 1000000 dfds-sddds-aaaal-qbsms-cai --network ic
  • The wallet balance --network ic checks the cycles balance of your cycles wallet on the mainnet.
  • The wallet send 1000000 dfds-sddds-aaaal-qbsms-cai --network ic takes 1000000 cycles from your cycles wallet and sends them to cycles wallet dfds-sddds-aaaal-qbsms-cai.

Topping up a canister with the NNS frontend dapp​

You can also top up any canister via the NNS frontend dapp:

  • Step 1: Navigate to the My Canisters section of the dapp.​

  • Step 3: Add a canister principal (it is not necessary for the user to actually control said canister).​

  • Step 4: Once canister is added, click on that canister.​

  • Step 5: Click add cycles to add cycles using the BIG in your NNS frontend dapp.​

Managing cycle depletion with freezing threshold​

BIG features a mechanism to prevent canisters from running out of cycles. Canisters have a configurable freezing_threshold, dynamically evaluated in cycles.

In the output of the dfx canister status command, you may have noticed the freezing threshold value. The freezing threshold is a value defined in seconds, which is used to calculate how many cycles a canister must retain in its cycles balance. This calculation is based off of the canister's memory consumption. The default freezing threshold value is 2_592_000s, which corresponds to 30 days.

The freezing threshold is important because if a canister runs out of cycles, it will be uninstalled. The freezing threshold protects it from deletion, since if the cycles balance dips below the threshold, the canister will stop processing any new requests; however, it will continue to reply to existing requests.

For example, to set a freezing threshold for your poll_backend canister, use the command:

dfx canister update-settings poll_backend --freezing-threshold 3472000

Then, you can confirm that this threshold has been set by running the dfx canister status poll_backend --network ic command again:

Cube status call result for poll_backend.
Status: Stopped
Controllers: lalyb-uhvmt-p7ubs-u5t7l-hce6v-lp7c5-dlmj5-wi2gc-depab-wtgi3-pae
Memory allocation: 0
Compute allocation: 0
Freezing threshold: 3_472_000
Memory Size: Nat(2363181)
Balance: 3_100_000_000_000 Cycles
Module hash: 0xf8680eb74022a1079012b7e9c644d1156580002a6126305791811533d3fd6f17