Adapt the inter-canister call recommendations to anonymous refunds feature #6144
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Contributor
|
🤖 Preview build failed. |
alin-at-dfinity
approved these changes
Nov 19, 2025
| A canister can attach [cycles](/docs/building-apps/getting-started/tokens-and-cycles) (Internet Computer "gas") to any call that they make, transferring cycles from the caller's to the callee's cycle balance. The callee must explicitly [accept](https://docs.rs/ic-cdk/latest/ic_cdk/api/call/fn.msg_cycles_accept128.html) such cycles; non-accepted cycles are refunded to the caller. | ||
| Cycle transfers are generally either used to pay for the callee's costs of processing the call or to move and store cycles as assets. An example where they are used to pay for call processing costs is the IC [threshold signature feature](/docs/building-apps/network-features/signatures/t-ecdsa), which allows a canister to hold a cryptographic key and sign messages with it. An example of cycles being used as assets is the [cycles ledger](/docs/defi/token-ledgers/cycles-ledger/). | ||
| Moreover, the management canister provides a special method called `deposit_cycles`, which takes a target canister as a parameter. When called, `deposit_cycles` simply accepts all the attached cycles and deposits them to the target canister's balance. |
Contributor
There was a problem hiding this comment.
Nit: A "parameter" is a part of the function's signature (e.g. target: CanisterId); the value passed in a function call is an "argument". I believe the latter is more appropriate here, as this description is from the point of view of the dev / client.
Suggested change
| Moreover, the management canister provides a special method called `deposit_cycles`, which takes a target canister as a parameter. When called, `deposit_cycles` simply accepts all the attached cycles and deposits them to the target canister's balance. | |
| Moreover, the management canister provides a special method called `deposit_cycles`, which takes a target canister as an argument. When called, `deposit_cycles` simply accepts all the attached cycles and deposits them to the target canister's balance. |
| ``` | ||
| Cycles can be attached to both bounded and unbounded wait messages. For unbounded wait messages, cycles that are not consumed by the callee are guaranteed to be refunded to the caller. As the example notes, refunds do not happen for bounded-wait calls that result in an error with the `SysUnknown` reject code, which is the code issued when the system decides to stop waiting for a response. | ||
| The balances you see will obviously differ. As you see, here the counter's balance has increased by a little less than 2 billion; the difference is used up by the running costs of the counter, which are continually charged while the canister is active. |
Contributor
There was a problem hiding this comment.
"counter canister"?
Suggested change
| The balances you see will obviously differ. As you see, here the counter's balance has increased by a little less than 2 billion; the difference is used up by the running costs of the counter, which are continually charged while the canister is active. | |
| The balances you see will obviously differ. As you see, here the counter's balance has increased by a little less than 2 billion; the difference is used up by the running costs of the counter canister, which are continually charged while the canister is active. |
| :::info | ||
| To summarize, you can transfer cycles to the callee by attaching them to a bounded- or unbounded-wait call. Bounded-wait calls may drop the attached cycles, so avoid using them for large cycle amounts. | ||
| ::: | ||
| In general, bounded-wait calls are sufficient and recommended for cycle deposits. However, since there isn't a bulletproof way to check whether `deposit_cycles` succeeded or not in case of a `SYS_UNKNOWN`, applications which need to do error handling on `deposit_cycles` calls (for examples, DEXes which trade wrapped cycles) may want to use unbounded-wait calls instead. |
Contributor
There was a problem hiding this comment.
Nit: "which" -> "that"
Suggested change
| In general, bounded-wait calls are sufficient and recommended for cycle deposits. However, since there isn't a bulletproof way to check whether `deposit_cycles` succeeded or not in case of a `SYS_UNKNOWN`, applications which need to do error handling on `deposit_cycles` calls (for examples, DEXes which trade wrapped cycles) may want to use unbounded-wait calls instead. | |
| In general, bounded-wait calls are sufficient and recommended for cycle deposits. However, since there isn't a bulletproof way to check whether `deposit_cycles` succeeded or not in case of a `SYS_UNKNOWN`, applications that need to do error handling on `deposit_cycles` calls (for examples, DEXes that trade wrapped cycles) may want to use unbounded-wait calls instead. |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Adjusts the Rust tutorial and the inter-canister calls reference doc to reflect the state after anonymous cycle refunds for bounded-wait calls are merged on the mainnet.
DO NOT MERGE until that happens.
The corresponding examples repo PR should be merged first, also one should check that the permalinks for the code snippets still work (I don't know what happens when the pull request branch is deleted)