chore: migrate motoko/hello_cycles to icp-cli (#1381)

Author: marc0olo

.github/workflows/hello_cycles.yml

@@ -0,0 +1,28 @@
+name: hello_cycles
+
+on:
+  push:
+    branches: [master]
+  pull_request:
+    paths:
+      - motoko/hello_cycles/**
+      - .github/workflows/hello_cycles.yml
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  motoko-hello_cycles:
+    runs-on: ubuntu-24.04
+    container: ghcr.io/dfinity/icp-dev-env-motoko:0.3.2
+    env:
+      ICP_CLI_GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
+      - name: Deploy and test
+        working-directory: motoko/hello_cycles
+        run: |
+          icp network start -d
+          icp deploy
+          make test

.github/workflows/motoko-hello_cycles-example.yaml

@@ -1,46 +1,32 @@
-.PHONY: all
-all: build
-
-.PHONY: build
-.SILENT: build
-build:
-	dfx canister create hello_cycles
-	dfx build
+.PHONY: test
 
-.PHONY: install
-.SILENT: install
-install: build
-	dfx canister install hello_cycles
+test:
+	@echo "=== Test 1: getBalance returns the canister's cycle balance ==="
+	@result=$$(icp canister call --query backend getBalance '()') && \
+	  echo "$$result" && \
+	  echo "$$result" | grep -qE '^\([0-9][0-9_]* : nat\)$$' && \
+	  echo "PASS" || (echo "FAIL" && exit 1)
 
-.PHONY: upgrade
-.SILENT: upgrade
-upgrade: build
-	dfx canister install hello_cycles --mode=upgrade
+	@echo "=== Test 2: acceptCycles accepts 1M cycles sent via the proxy canister ==="
+	@PROXY=$$(icp network status --json | jq -r .proxy_canister_principal) && \
+	  result=$$(icp canister call backend acceptCycles '()' --proxy "$$PROXY" --cycles 1_000_000) && \
+	  echo "$$result" && \
+	  echo "$$result" | grep -qE 'accepted = [1-9]' && \
+	  echo "PASS" || (echo "FAIL" && exit 1)
 
-.PHONY: test
-.SILENT: test
-test: install
-	$(eval WALLET := $(shell dfx identity get-wallet))
-	$(eval HELLO_CYCLES := $(shell dfx canister id hello_cycles))
-	echo "dfx version: $(shell dfx --version)"
-	echo "wallet: $(WALLET)"
-	echo "hello_cycles: $(HELLO_CYCLES)"
-	echo "$(dfx canister call hello_cycles wallet_balance)"
-	# canister has just above 2.9T cycles, so output start with '(2_9'
-	dfx canister call hello_cycles wallet_balance \
-		| grep '(2_9' && echo 'PASS'
-	dfx canister status hello_cycles
-	dfx canister call $(WALLET) wallet_send '(record { canister = principal "$(HELLO_CYCLES)"; amount = (2000000000000:nat64); } )'
-	# 2T cycles added, now contains just above 4.9T
-	dfx canister call hello_cycles wallet_balance \
-		| grep '(4_9' && echo 'PASS'
-	echo  '(func "$(WALLET)"."wallet_receive", 5000000)'
-	dfx canister call hello_cycles transfer '(func "$(WALLET)"."wallet_receive", 5000000)' \
-		| grep '0' && echo 'PASS'
-	dfx canister call hello_cycles wallet_balance \
-	 	| grep '(4_9' && echo 'PASS'
+	@echo "=== Test 3: sendCycles forwards 5M to itself — within limit, refunded = 0 ==="
+	@# The canister calls its own acceptCycles as receiver (inter-canister self-call).
+	@# 5M offered < 10M limit, so all cycles are accepted and none are refunded.
+	@BACKEND_ID=$$(icp canister status backend -i) && \
+	  result=$$(icp canister call backend sendCycles "(func \"$$BACKEND_ID\".\"acceptCycles\", 5_000_000)") && \
+	  echo "$$result" && \
+	  echo "$$result" | grep -q 'refunded = 0' && \
+	  echo "PASS" || (echo "FAIL" && exit 1)
 
-.PHONY: clean
-.SILENT: clean
-clean:
-	rm -fr .dfx
+	@echo "=== Test 4: sendCycles forwards 15M to itself — over limit, refunded = 5_000_000 ==="
+	@# 15M offered > 10M limit, so 10M are accepted and exactly 5M are refunded.
+	@BACKEND_ID=$$(icp canister status backend -i) && \
+	  result=$$(icp canister call backend sendCycles "(func \"$$BACKEND_ID\".\"acceptCycles\", 15_000_000)") && \
+	  echo "$$result" && \
+	  echo "$$result" | grep -q 'refunded = 5_000_000' && \
+	  echo "PASS" || (echo "FAIL" && exit 1)

motoko/hello_cycles/Makefile

@@ -1,40 +1,51 @@
 # Hello, cycles!
 
-The `hello_cycles` sample project provides a simple example to illustrate how you might add functions to receive cycles, transfer cycles, and check your cycle balance with a simple Motoko actor (canister).
+On the Internet Computer, canisters pay for computation and storage with cycles. This example demonstrates the three fundamental cycle management operations in Motoko:
 
-This sample project assumes that you are using the default cycles wallet canister that is created for you.
+1. **Inspect the balance** — read how many cycles the canister currently holds.
+2. **Accept incoming cycles** — when a caller attaches cycles to a call, the canister must explicitly claim them. Unclaimed cycles are automatically refunded to the caller.
+3. **Send cycles to another canister** — attach cycles to an outgoing inter-canister call and learn how many were refunded (not accepted by the receiver).
 
-This example consists of the following functions (see `src/hello_cycles/main.mo`):
+Operations 2 and 3 are two perspectives on the same transaction:
+- The **receiver** calls `Cycles.accept()` and returns how many it took (`accepted`).
+- The **sender** reads `Cycles.refunded()` after the call returns to learn how many cycles came back.
 
-- The `wallet_balance : () -> async Nat`: enables you to check the current cycle balance for the canister.
+## Functions
 
-- The `wallet_receive : () -> { amount : Nat64 }`: enables the program to accept cycles that are sent to the canister from a wallet. Both the name and type of this function are dictated by the wallet's implementation (so don't mess with them).
+- `getBalance()` — returns the canister's current cycle balance as `Nat`.
+- `acceptCycles()` — accepts up to 10 million cycles from the caller; returns `{ accepted : Nat64 }`. Any excess is refunded automatically.
+- `sendCycles(receiver, amount)` — forwards `amount` cycles from this canister's balance to `receiver`; returns `{ refunded : Nat }`. A non-zero `refunded` means the receiver did not accept all of the offered cycles.
 
-- The `transfer : (shared () -> (), Nat) -> async { refunded : Nat }`: enables the program to transfer cycles to any shared function with candid signature `"() -> ()"` (assuming it accepts cycles). One example is the wallet's own `wallet_receive : () -> ()` function.
+## Build and deploy from the command line
 
-:::caution
-The wallet's `wallet_receive` return type differs from hello_cycle's `wallet_receive`.
-:::
+### Prerequisites
 
-## Deploying from ICP Ninja
+- Node.js
+- icp-cli: `npm install -g @icp-sdk/icp-cli @icp-sdk/ic-wasm`
+- ic-mops: `npm install -g ic-mops`
+- jq (used in `make test` to read the proxy canister principal)
 
-[![](https://icp.ninja/assets/open.svg)](https://icp.ninja/editor?g=https://github.com/dfinity/examples/tree/master/motoko/hello_cycles)
+### Install
 
-## Build and deploy from the command-line
-
-### 1. [Download and install the IC SDK.](https://internetcomputer.org/docs/building-apps/getting-started/install)
+```bash
+git clone https://github.com/dfinity/examples
+cd examples/motoko/hello_cycles
+```
 
-### 2. Download your project from ICP Ninja using the 'Download files' button on the upper left corner, or [clone the GitHub examples repository.](https://github.com/dfinity/examples/)
+### Deploy and test
 
-### 3. Navigate into the project's directory.
+```bash
+icp network start -d
+icp deploy
+make test
+icp network stop
+```
 
-### 4. Deploy the project to your local environment:
+The tests cover both perspectives:
 
-```
-dfx start --background --clean && dfx deploy
-```
+- **Test 2 (receiver side)**: calls `acceptCycles` through the local [proxy canister](https://cli.internetcomputer.org/0.3/guides/proxy-canister/) with 1M attached cycles — verifies `accepted > 0`. External callers cannot attach cycles directly; icp-cli routes the cycles via the proxy, which is automatically deployed on the local network.
+- **Tests 3 & 4 (sender side)**: calls `sendCycles` with the canister's **own** `acceptCycles` as the receiver (an inter-canister self-call — no second canister needed). The 5M/15M cycles leave the canister via `sendCycles` and arrive at `acceptCycles`, which accepts up to the 10M limit. Test 3 sends 5M → `refunded = 0` (within limit). Test 4 sends 15M → `refunded = 5_000_000` (5M over the limit). In practice, `sendCycles` would target a different canister.
 
 ## Security considerations and best practices
 
-If you base your application on this example, it is recommended that you familiarize yourself with and adhere to the [security best practices](https://internetcomputer.org/docs/building-apps/security/overview) for developing on ICP. This example may not implement all the best practices.
-
+Refer to the [security best practices](https://docs.internetcomputer.org/guides/security/overview) for information on security and best practices for your ICP app.

motoko/hello_cycles/README.md

@@ -0,0 +1,40 @@
+import Nat "mo:core/Nat";
+import Nat64 "mo:core/Nat64";
+import Cycles "mo:core/Cycles";
+
+actor HelloCycles {
+
+  /// Maximum cycles this canister accepts per call.
+  let limit = 10_000_000;
+
+  /// Returns the canister's current cycle balance.
+  public query func getBalance() : async Nat {
+    Cycles.balance();
+  };
+
+  /// Accepts cycles that the caller attached to this call, up to `limit`.
+  /// The remainder is automatically refunded to the caller.
+  /// Returns how many cycles were actually accepted.
+  ///
+  /// This is the RECEIVER perspective: the canister decides how much to keep.
+  public func acceptCycles() : async { accepted : Nat64 } {
+    let available = Cycles.available(); // total cycles the caller attached
+    let accepted = Cycles.accept<system>(Nat.min(available, limit)); // claim up to limit
+    { accepted = Nat64.fromNat(accepted) };
+  };
+
+  /// Sends `amount` cycles from this canister's balance to `receiver`.
+  /// Returns how many cycles were refunded (not accepted by the receiver).
+  ///
+  /// `receiver` is typed as `shared () -> async {}` (returning the empty record).
+  /// Because `{ accepted : Nat64 } <: {}` in Motoko's structural record typing,
+  /// `acceptCycles` is a valid argument even though it returns a non-empty record.
+  ///
+  /// This is the SENDER perspective: the canister spends from its own
+  /// balance and learns how many cycles came back unused.
+  public func sendCycles(receiver : shared () -> async {}, amount : Nat) : async { refunded : Nat } {
+    ignore await (with cycles = amount) receiver(); // attach `amount`; ignore return value
+    { refunded = Cycles.refunded() };               // how many the receiver did not accept
+  };
+
+};

motoko/hello_cycles/backend/app.mo

@@ -0,0 +1,4 @@
+canisters:
+  - name: backend
+    recipe:
+      type: "@dfinity/motoko@v5.0.0"

motoko/hello_cycles/dfx.json

@@ -1,13 +1,14 @@
-# Motoko dependencies (https://mops.one/)
-
 [toolchain]
-moc = "1.5.1"
+moc = "1.9.0"
 
 [dependencies]
-core = "2.4.0"
+core = "2.5.0"
 
 [moc]
-# M0236: use context dot notation (e.g. map.get(k) instead of Map.get(map, compare, k))
-# M0237: redundant explicit implicit arguments (e.g. Nat.compare is inferred automatically)
-# M0223: redundant type instantiation (e.g. Array.tabulate instead of Array.tabulate<T>)
-args = ["-W=M0236,M0237,M0223"]
+# M0236: use context dot notation
+# M0237: redundant explicit implicit arguments
+# M0223: redundant type instantiation
+args = ["--default-persistent-actors", "-W=M0236,M0237,M0223"]
+
+[canisters.backend]
+main = "backend/app.mo"