chore: migrate motoko/composite_query to icp-cli (#1382)

Author: marc0olo

.github/workflows/composite_query.yml

@@ -0,0 +1,28 @@
+name: composite_query
+
+on:
+  push:
+    branches: [master]
+  pull_request:
+    paths:
+      - motoko/composite_query/**
+      - .github/workflows/composite_query.yml
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  motoko-composite_query:
+    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/composite_query
+        run: |
+          icp network start -d
+          icp deploy --cycles 30t
+          make test

.github/workflows/motoko-composite-query-example.yaml

@@ -1,30 +1,45 @@
-.PHONY: all
-all: build
+.PHONY: test topup
 
-.PHONY: build
-.SILENT: build
-build:
-	dfx canister create --all --no-wallet
-	dfx build
+topup:
+	icp canister top-up --amount 30t backend
 
-.PHONY: install
-.SILENT: install
-install: build
-	dfx canister install --all
+test:
+	@echo "=== Test 1: put inserts a key-value pair ==="
+	@icp canister call backend put '(0, "zero")' && \
+	  echo "PASS" || (echo "FAIL" && exit 1)
 
-.PHONY: upgrade
-.SILENT: upgrade
-upgrade: build
-	dfx canister install --all --mode=upgrade
+	@echo "=== Test 2: get (composite query) retrieves the stored value ==="
+	@# This exercises the composite query: Map.get calls Bucket.get on a child canister.
+	@result=$$(icp canister call --query backend get '(0)') && \
+	  echo "$$result" && \
+	  echo "$$result" | grep -q 'opt "zero"' && \
+	  echo "PASS" || (echo "FAIL" && exit 1)
 
-.PHONY: test
-.SILENT: test
-test: install
-	dfx canister call Map test '()'
-	dfx canister call --query Map get '(15)' \
-		| grep '(opt "15")' && echo 'PASS'
+	@echo "=== Test 3: getUpdate returns the same value via an update call ==="
+	@result=$$(icp canister call backend getUpdate '(0)') && \
+	  echo "$$result" && \
+	  echo "$$result" | grep -q 'opt "zero"' && \
+	  echo "PASS" || (echo "FAIL" && exit 1)
 
-.PHONY: clean
-.SILENT: clean
-clean:
-	rm -fr .dfx
+	@echo "=== Test 4: get returns null for a missing key ==="
+	@result=$$(icp canister call --query backend get '(99)') && \
+	  echo "$$result" && \
+	  echo "$$result" | grep -q 'null' && \
+	  echo "PASS" || (echo "FAIL" && exit 1)
+
+	@echo "=== Test 5: composite query routes correctly across all four buckets ==="
+	@# Keys 0-3 each map to a different bucket (k % 4): 0→B0, 1→B1, 2→B2, 3→B3.
+	@# The composite query must call the right child canister for each key.
+	@icp canister call backend put '(1, "one")' && \
+	  icp canister call backend put '(2, "two")' && \
+	  icp canister call backend put '(3, "three")' && \
+	  result0=$$(icp canister call --query backend get '(0)') && \
+	  result1=$$(icp canister call --query backend get '(1)') && \
+	  result2=$$(icp canister call --query backend get '(2)') && \
+	  result3=$$(icp canister call --query backend get '(3)') && \
+	  echo "$$result0" && echo "$$result1" && echo "$$result2" && echo "$$result3" && \
+	  echo "$$result0" | grep -q 'opt "zero"' && \
+	  echo "$$result1" | grep -q 'opt "one"' && \
+	  echo "$$result2" | grep -q 'opt "two"' && \
+	  echo "$$result3" | grep -q 'opt "three"' && \
+	  echo "PASS" || (echo "FAIL" && exit 1)

motoko/composite_query/Makefile

@@ -1,50 +1,54 @@
 # Composite queries
 
-This example modifies the simple actor class example to demonstrate the implementation of composite queries.
+On the Internet Computer, regular query functions are fast (no consensus) but have one strict limitation: **they cannot call other canisters**. Composite queries lift this restriction — a `composite query func` can call query methods on other canisters while keeping the speed benefit of a query call.
 
-The original example demonstrates a simple use of actor classes, allowing a program to dynamically install new actors (that is, canisters). It also demonstrates a multi-canister project, and actors using inter-actor communication through `shared` functions.
+For more background see [Composite queries](https://docs.internetcomputer.org/guides/canister-calls/parallel-inter-canister-calls/#composite-queries) in the ICP developer docs.
 
-In the original example, shared functions `Map.get` and `Bucket.get` were both implemented as
-update methods so that `Map.get` could call `Bucket.get`.
+This example implements a distributed key-value store (`Map`) that shards its entries across four dynamically-installed `Bucket` child canisters. Looking up a key requires calling the appropriate bucket:
 
-In this version `Bucket.get` is implemented as a query function and `Map.get` as a composite query function.
-Although queries and composite queries are fast, composite queries can only be invoked as ingress messages, either
-using `dfx` (see below) or an agent through, for example, a browser front-end (not illustrated here).
+- `get(k)` — **composite query**: delegates to the correct `Bucket.get(k)` as a cross-canister query call. Fast, no consensus.
+- `getUpdate(k)` — **update call**: same lookup, but via an update call to the bucket. Slower (goes through consensus) but provided here for comparison.
 
-In detail, the example provides actor `Map`.
-`Map` is a dead-simple, distributed key-value store, mapping `Nat` to `Text` values, with entries stored in a small number of separate `Bucket` actors, installed on demand.
+Both functions return the same result; the difference is latency and call semantics.
 
-[Map.mo](./src/map/Map.mo) imports a Motoko _actor class_ `Bucket(i, n)`
-from library [Buckets.mo](./src/map/Buckets.mo).
-It also imports `mo:core/Cycles` to share its cycles amongst the buckets it creates.
+## Architecture
 
-Each call to `Buckets.Bucket(n, i)` within `Map` instantiates a new `Bucket` instance (the `i`-th of `n`) dedicated to those entries of the `Map` whose key _hashes_ to `i` (by taking the remainder of the key modulo division by `n`).
-
-Each asynchronous instantiation of the `Bucket` actor class corresponds to the dynamic, programmatic installation of a new `Bucket` canister.
-
-Each new `Bucket` must be provisioned with enough cycles to pay for its installation and running costs.
-`Map` achieves this by attaching an equal share of `Map`'s initial cycle balance to each asynchronous call to `Bucket(n, i)`, using the syntax `await (with cycles = cycleShare) Buckets.Bucket(n, i)`.
-
-`Map`'s `test` method simply `put`s 16 consecutive entries into `Map`. These entries are distributed evenly amongst the buckets making up the key-value store. Adding the first entry to a bucket takes longer than adding a subsequent one, since the bucket needs to be installed on first use.
+```
+Map (backend)
+  n = 4 buckets     ┌── Bucket 0  (keys 0, 4, 8, …)
+  key % n routes ───┼── Bucket 1  (keys 1, 5, 9, …)
+                    ├── Bucket 2  (keys 2, 6, 10, …)
+                    └── Bucket 3  (keys 3, 7, 11, …)
+```
 
-## Deploying from ICP Ninja
+`Map.put(k, v)` dynamically installs a `Bucket` if one does not exist for `k % 4`, then stores the entry there. `Map.get(k)` and `Map.getUpdate(k)` both route to the same bucket via `k % 4`.
 
-[![](https://icp.ninja/assets/open.svg)](https://icp.ninja/editor?g=https://github.com/dfinity/examples/tree/master/motoko/composite_query)
+## Build and deploy from the command line
 
-## Build and deploy from the command-line
+### Prerequisites
 
-### 1. [Download and install the IC SDK.](https://internetcomputer.org/docs/building-apps/getting-started/install)
+- Node.js
+- icp-cli: `npm install -g @icp-sdk/icp-cli @icp-sdk/ic-wasm`
+- ic-mops: `npm install -g ic-mops`
 
-### 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/)
+### Install
 
-### 3. Navigate into the project's directory.
+```bash
+git clone https://github.com/dfinity/examples
+cd examples/motoko/composite_query
+```
 
-### 4. Deploy the project to your local environment:
+### Deploy and test
 
+```bash
+icp network start -d
+icp deploy --cycles 30t
+make test
+icp network stop
 ```
-dfx start --background --clean && dfx deploy
-```
+
+> `icp deploy --cycles 30t` is required because `Map` dynamically creates `Bucket` canisters — it needs extra cycles to fund their installation. If tests fail with an out-of-cycles error, run `make topup`.
 
 ## 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/composite_query/README.md

@@ -3,7 +3,7 @@ import VarArray "mo:core/VarArray";
 import Cycles "mo:core/Cycles";
 import Buckets "Buckets";
 
-persistent actor Map {
+actor Map {
 
   let n = 4; // number of buckets
 

motoko/composite_query/src/map/Buckets.mo motoko/composite_query/backend/Buckets.momotoko/composite_query/src/map/Buckets.mo renamed to motoko/composite_query/backend/Buckets.mo

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

motoko/composite_query/src/map/Map.mo motoko/composite_query/backend/app.momotoko/composite_query/src/map/Map.mo renamed to motoko/composite_query/backend/app.mo

@@ -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"