Difference between revisions of "Cycles Ledger"

Revision as of 12:52, 22 March 2024

Overview

The cycles ledger is a canister that simplifies the management of cycles.

Instead of creating one or more cycles wallets, which the developer controls and manages, the cycles ledger is a global ledger under the control of the NNS. That is, the burden of managing cycles wallets themselves is lifted.

The cycles ledger complies with the IRCR-1, ICRC-2, and (the upcoming) ICRC-3 standards. As a result, the cycles ledger can also be integrated into applications and services that work ICRC tokens.

The cycles ledger (canister ID: um5iw-rqaaa-aaaaq-qaaba-cai) runs on the uzr34 system subnet.

Architecture

The following figure depicts the involved components and their interactions at a high level.

High-level overview of the cycles ledger architecture.

In addition to the standard ICRC ledger functionality, the cycles ledger interacts with the cycles minting canister of the NNS and user canisters to provide the cycles ledger-specific functionality, such as transferring cycles as well as creating canisters with cycles. Concretely, it provides the following functionality:

deposit credits the sent cycles to the given principal ID.
withdraw sends the given number of cycles to the given canister.
withdraw_from sends the given number of cycles to the given canister taking the funds from a given account.
create_canister creates a new canister using cycles.
create_canister_from creates a new canister using cycles taken from a given account.

The cycles balance of an account on the cycles ledger can be increased in the following ways:

Calling deposit with cycles attached.
Calling notify_mint_cycles on the cycles minting canister (CMC) after having deposited ICP in a user-specific subaccount of the CMC's account on the ICP ledger.
Calling icrc1_transfer or icrc2_transfer_from on the cycles ledger to transfer cycles.

Due to the tight interaction with the NNS, in particular the CMC, the cycles ledger is to be controlled by the NNS root canister.

It is important to point out that the cycles ledger does not provide the functionality to call arbitrary other canisters with cycles (unlike cycles wallets). The reason is that open call contexts may cause the cycles ledger to become stuck.

If this functionality is needed, a developer can still spin up a cycles wallet - and load it with cycles using the cycles ledger.

@@ Line 1: / Line 1: @@
 == Overview ==
+The cycles ledger is a canister that simplifies the management of cycles.
+Instead of creating one or more cycles wallets, which the developer controls and manages, the cycles ledger is a global ledger under the control of the NNS. That is, the burden of managing cycles wallets themselves is lifted.
+The cycles ledger complies with the [https://github.com/dfinity/ICRC-1/blob/main/standards/ICRC-1/README.md IRCR-1], [https://github.com/dfinity/ICRC-1/blob/main/standards/ICRC-2/README.md ICRC-2], and (the upcoming) ICRC-3 standards. As a result, the cycles ledger can also be integrated into applications and services that work ICRC tokens.
+The cycles ledger (canister ID: <code>um5iw-rqaaa-aaaaq-qaaba-cai</code>) runs on the [https://dashboard.internetcomputer.org/subnet/uzr34-akd3s-xrdag-3ql62-ocgoh-ld2ao-tamcv-54e7j-krwgb-2gm4z-oqe uzr34 system subnet].
+== Architecture ==
+The following figure depicts the involved components and their interactions at a high level.
+[[File:Cycles Ledger - Diagrams - Overview.png|center|thumb|600x600px|High-level overview of the cycles ledger architecture.]]
+In addition to the standard ICRC ledger functionality, the cycles ledger interacts with the cycles minting canister of the NNS and user canisters to provide the cycles ledger-specific functionality, such as transferring cycles as well as creating canisters with cycles. Concretely, it provides the following functionality:
+# <code>deposit</code> credits the sent cycles to the given principal ID.
+# <code>withdraw</code> sends the given number of cycles to the given canister.
+# <code>withdraw_from</code> sends the given number of cycles to the given canister taking the funds from a given account.
+# <code>create_canister</code> creates a new canister using cycles.
+# <code>create_canister_from</code> creates a new canister using cycles taken from a given account.
+The cycles balance of an account on the cycles ledger can be increased in the following ways:
+# Calling <code>deposit</code> with cycles attached.
+# Calling <code>notify_mint_cycles</code> on the cycles minting canister (CMC) after having deposited ICP in a user-specific subaccount of the CMC's account on the ICP ledger.
+# Calling <code>icrc1_transfer</code> or <code>icrc2_transfer_from</code> on the cycles ledger to transfer cycles.
+Due to the tight interaction with the NNS, in particular the CMC, the cycles ledger is to be controlled by the NNS root canister.
+It is important to point out that the cycles ledger does not provide the functionality to call arbitrary other canisters with cycles (unlike cycles wallets). The reason is that open call contexts may cause the cycles ledger to become stuck.
+If this functionality is needed, a developer can still spin up a cycles wallet - and load it with cycles using the cycles ledger.
 == See also ==