Skip to main content

Cycles ledger

Beginner
Tutorial

Overview​

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

The biggest difference between the cycles ledger and cycles wallet is that the cycles ledger is a single global ledger cube, whereas the cycles wallet cube 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 BIGRC-1, BIGRC-2, and BIGRC-3 standards. In addition to standard ledger functionality, the cycles ledger also interacts with the NNS cubes and user cubes to provide cycles ledger-specific functions, such as:

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

It is important to note that the cycles ledger does not provide the ability to make arbitrary calls to other cubes 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 cubes with cycles, a cycles wallet can be used as before. The cycles ledger can be used to load the cycles wallet with cycles.

Using the cycles ledger​

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

DFX_CYCLES_LEDGER_SUPPORT_ENABLE=1

Obtaining BIG​

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

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

Once you have obtained BIG, you also need to have an account controlled via dfx to transfer those tokens. This step is necessary to create cycles and cubes. 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 BIG ledger. It looks similar to this:

e213184a548871a47fb526f3cba24e2ee2fbbc8129c4ab497ef2ce535130a0a4

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

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 BIG to cycles​

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

dfx cycles convert AMOUNT --network ic

Replace AMOUNT with the number of BIG to convert into cycles, such as 2.7. Alternatively, the amount can be specified in terms of BIG and e8s (where 100,000,000 e8s = 1 BIG) 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 AMOUNT with the number of cycles, such as 34000000, and 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. 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 cube​

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

dfx cycles top-up `AMOUNT` `CANISTER_ID` --network ic

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

Creating a cube using cycles​

New cubes 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 cube:

dfx canister create CANISTER_NAME --network ic
dfx deploy CANISTER_NAME --network ic

Replace CANISTER_NAME with a name for the new cube.

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

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

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

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

If no flag is specified and the project contains cubes 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 cube, the fee is 100m cycles.
  • To create a cube, the fee is the transfer fee (100m cycles), plus the cube creation fee, which scales linearly with the size of the subnet that the cube is created on. For example, if the cube is created on a 13-node subnet, the fee is 100B cycles. This means the total fee will be 100_100_000_000 cycles.