chore(motoko): migrate composite_query, parallel_calls, random_maze, classes, hello_cycles to mo:core 2.4.0 (#1325)

marc0olo · web-flow · commit c9f9f5d8f757 · 2026-04-20T13:29:40.000+02:00
* chore(motoko): migrate composite_query, parallel_calls, random_maze to mo:core 2.4.0

- composite_query: RBTree → Map, ExperimentalCycles.add → (with cycles =), Array.init → VarArray.repeat, add mops.toml
- parallel_calls: functional List → mutable List, Iter.range → Nat.range, add mops.toml
- random_maze: Random.Finite → Random.AsyncRandom, Stack class → Stack module, List → pure/List, Array.init → VarArray.repeat, add mops.toml

* chore: migrate random_maze, classes, hello_cycles to mo:core 2.4.0

- random_maze: remove unnecessary transient from constant let bindings
- classes: replace mo:base RBTree+Array+ExperimentalCycles with
  mo:core Map+VarArray+Cycles; add persistent keyword; use
  (with cycles = N) syntax; add mops.toml
- hello_cycles: replace mo:base imports with mo:core; add persistent
  keyword; use (with cycles = N) syntax and Cycles.accept&lt;system&gt;;
  add mops.toml

* refactor: apply modern Motoko style via mops check --fix

- Pin moc = "1.5.1" and enable warnings M0236/M0237/M0223 in all
  five example mops.toml files
- classes/composite_query Buckets.mo: context dot for map.get/map.add,
  Nat import needed for implicit compare resolution
- parallel_calls: context dot for l.add/l.values, c.toText();
  explicit (): () return type on setup_callee; catch _ {} for unused e
- random_maze: context dot for s.push/s.pop, us.isEmpty/us.size/us.get,
  cs.pushFront; redundant type annotations removed (M0223);
  irrefutable let pattern made exhaustive with else branch

* docs: update READMEs and annotate mops.toml warning flags for mo:core examples

* docs: remove stale alias note from Cycles import description
diff --git a/motoko/classes/README.md b/motoko/classes/README.md
@@ -6,13 +6,13 @@ The example defines two Motoko actors, `Map` and `Test`.
 
 Map is a simple, distributed key-value store, mapping `Nat` to `Text` values, with entries stored in a small number of separate Bucket actors, installed on demand.
 
-`Map.mo` imports a Motoko actor class `Bucket(i, n)` from the library `Buckets.mo`. It also imports the `ExperimentalCycles` base library, naming it `Cycles` for short, to share its cycles amongst the buckets it creates.
+`Map.mo` imports a Motoko actor class `Bucket(i, n)` from the library `Buckets.mo`. It also imports `mo:core/Cycles` to share its cycles amongst the buckets it creates.
 
 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 adding an equal share of Map's initial cycle balance to each asynchronous call to `Bucket(n, i)`, using a call to `Cycles.add(cycleShare)`.
+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)`.
 
 The `Test.mo` actor imports the (installed) `Map` canister, using `Maps` Candid interface to determine its Motoko type. `Test`'s run method simply puts 24 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 take longer than adding a subsequent one, since the bucket needs to be installed on first use.
 
diff --git a/motoko/classes/mops.toml b/motoko/classes/mops.toml
@@ -1,5 +1,13 @@
 # Motoko dependencies (https://mops.one/)
 
+[toolchain]
+moc = "1.5.1"
+
 [dependencies]
-base = "0.14.9"
-core = "1.0.0"
+core = "2.4.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", "-W", "M0237", "-W", "M0223"]
diff --git a/motoko/classes/src/map/Buckets.mo b/motoko/classes/src/map/Buckets.mo
@@ -1,12 +1,12 @@
-import Nat "mo:base/Nat";
-import Map "mo:base/RBTree";
+import Map "mo:core/Map";
+import Nat "mo:core/Nat";
 
 persistent actor class Bucket(n : Nat, i : Nat) {
 
   type Key = Nat;
   type Value = Text;
 
-  transient let map = Map.RBTree<Key, Value>(Nat.compare);
+  let map = Map.empty<Key, Value>();
 
   public func get(k : Key) : async ?Value {
     assert ((k % n) == i);
@@ -15,7 +15,7 @@ persistent actor class Bucket(n : Nat, i : Nat) {
 
   public func put(k : Key, v : Value) : async () {
     assert ((k % n) == i);
-    map.put(k, v);
+    map.add(k, v);
   };
 
 };
diff --git a/motoko/classes/src/map/Map.mo b/motoko/classes/src/map/Map.mo
@@ -1,5 +1,5 @@
-import Array "mo:base/Array";
-import Cycles "mo:base/ExperimentalCycles";
+import VarArray "mo:core/VarArray";
+import Cycles "mo:core/Cycles";
 import Buckets "Buckets";
 
 persistent actor Map {
@@ -14,7 +14,7 @@ persistent actor Map {
 
   type Bucket = Buckets.Bucket;
 
-  let buckets : [var ?Bucket] = Array.init(n, null);
+  let buckets : [var ?Bucket] = VarArray.repeat(null, n);
 
   public func get(k : Key) : async ?Value {
     switch (buckets[k % n]) {
@@ -27,9 +27,7 @@ persistent actor Map {
     let i = k % n;
     let bucket = switch (buckets[i]) {
       case null {
-        // provision next send, i.e. Bucket(n, i), with cycles
-        Cycles.add(cycleShare);
-        let b = await Buckets.Bucket(n, i); // dynamically install a new Bucket
+        let b = await (with cycles = cycleShare) Buckets.Bucket(n, i);
         buckets[i] := ?b;
         b;
       };
diff --git a/motoko/classes/src/test/Test.mo b/motoko/classes/src/test/Test.mo
@@ -1,4 +1,4 @@
-import Debug "mo:base/Debug";
+import Debug "mo:core/Debug";
 import Map "canister:map";
 
 persistent actor Test {
diff --git a/motoko/composite_query/README.md b/motoko/composite_query/README.md
@@ -16,14 +16,14 @@ In detail, the example provides actor `Map`.
 
 [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 the `ExperimentalCycles` base library, naming it `Cycles` for short, to share its cycles amongst the buckets it creates.
+It also imports `mo:core/Cycles` to share its cycles amongst the buckets it creates.
 
 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 adding an equal share of `Map`'s initial cycle balance to each asynchronous call to `Bucket(n, i)`, using a call to `Cycles.add(cycleShare)`.
+`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.
 
diff --git a/motoko/composite_query/mops.toml b/motoko/composite_query/mops.toml
@@ -0,0 +1,13 @@
+# Motoko dependencies (https://mops.one/)
+
+[toolchain]
+moc = "1.5.1"
+
+[dependencies]
+core = "2.4.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", "-W", "M0237", "-W", "M0223"]
diff --git a/motoko/composite_query/src/map/Buckets.mo b/motoko/composite_query/src/map/Buckets.mo
@@ -1,12 +1,12 @@
-import Nat "mo:base/Nat";
-import Map "mo:base/RBTree";
+import Map "mo:core/Map";
+import Nat "mo:core/Nat";
 
 persistent actor class Bucket(n : Nat, i : Nat) {
 
   type Key = Nat;
   type Value = Text;
 
-  transient let map = Map.RBTree<Key, Value>(Nat.compare);
+  let map = Map.empty<Key, Value>();
 
   public query func get(k : Key) : async ?Value {
     assert ((k % n) == i);
@@ -15,7 +15,7 @@ persistent actor class Bucket(n : Nat, i : Nat) {
 
   public func put(k : Key, v : Value) : async () {
     assert ((k % n) == i);
-    map.put(k, v);
+    map.add(k, v);
   };
 
 };
diff --git a/motoko/composite_query/src/map/Map.mo b/motoko/composite_query/src/map/Map.mo
@@ -1,6 +1,6 @@
-import Debug "mo:base/Debug";
-import Array "mo:base/Array";
-import Cycles "mo:base/ExperimentalCycles";
+import Debug "mo:core/Debug";
+import VarArray "mo:core/VarArray";
+import Cycles "mo:core/Cycles";
 import Buckets "Buckets";
 
 persistent actor Map {
@@ -15,7 +15,7 @@ persistent actor Map {
 
   type Bucket = Buckets.Bucket;
 
-  let buckets : [var ?Bucket] = Array.init(n, null);
+  let buckets : [var ?Bucket] = VarArray.repeat(null, n);
 
   public func getUpdate(k : Key) : async ?Value {
     switch (buckets[k % n]) {
@@ -36,8 +36,7 @@ persistent actor Map {
     let bucket = switch (buckets[i]) {
       case null {
         // provision next send, i.e. Bucket(n, i), with cycles
-        Cycles.add(cycleShare);
-        let b = await Buckets.Bucket(n, i); // dynamically install a new Bucket
+        let b = await (with cycles = cycleShare) Buckets.Bucket(n, i); // dynamically install a new Bucket
         buckets[i] := ?b;
         b;
       };
diff --git a/motoko/hello_cycles/mops.toml b/motoko/hello_cycles/mops.toml
@@ -0,0 +1,13 @@
+# Motoko dependencies (https://mops.one/)
+
+[toolchain]
+moc = "1.5.1"
+
+[dependencies]
+core = "2.4.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", "-W", "M0237", "-W", "M0223"]
diff --git a/motoko/hello_cycles/src/hello_cycles/main.mo b/motoko/hello_cycles/src/hello_cycles/main.mo
@@ -1,26 +1,25 @@
-import Nat "mo:base/Nat";
-import Nat64 "mo:base/Nat64";
-import Cycles "mo:base/ExperimentalCycles";
+import Nat "mo:core/Nat";
+import Nat64 "mo:core/Nat64";
+import Cycles "mo:core/Cycles";
 
-persistent actor HelloCycles  {
+persistent actor HelloCycles {
 
-  transient let limit = 10_000_000;
+  let limit = 10_000_000;
 
   public func wallet_balance() : async Nat {
     return Cycles.balance();
   };
 
   public func wallet_receive() : async { accepted: Nat64 } {
     let available = Cycles.available();
-    let accepted = Cycles.accept(Nat.min(available, limit));
+    let accepted = Cycles.accept<system>(Nat.min(available, limit));
     { accepted = Nat64.fromNat(accepted) };
   };
 
   public func transfer(
     receiver : shared () -> async (),
     amount : Nat) : async { refunded : Nat } {
-      Cycles.add(amount);
-      await receiver();
+      await (with cycles = amount) receiver();
       { refunded = Cycles.refunded() };
   };
 
diff --git a/motoko/parallel_calls/mops.toml b/motoko/parallel_calls/mops.toml
@@ -0,0 +1,13 @@
+# Motoko dependencies (https://mops.one/)
+
+[toolchain]
+moc = "1.5.1"
+
+[dependencies]
+core = "2.4.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", "-W", "M0237", "-W", "M0223"]
diff --git a/motoko/parallel_calls/src/caller/main.mo b/motoko/parallel_calls/src/caller/main.mo
@@ -1,15 +1,15 @@
-import List "mo:base/List";
-import Error "mo:base/Error";
-import Principal "mo:base/Principal";
-import Iter "mo:base/Iter";
+import List "mo:core/List";
+import Error "mo:core/Error";
+import Principal "mo:core/Principal";
+import Nat "mo:core/Nat";
 
 persistent actor {
 
     type callee_interface = (actor { ping : () -> async () });
     var callee = null : ?callee_interface;
 
-    public func setup_callee(c : Principal) {
-        callee := ?(actor (Principal.toText(c)) : callee_interface);
+    public func setup_callee(c : Principal) : () {
+        callee := ?(actor (c.toText()) : callee_interface);
     };
 
     public func sequential_calls(n : Nat) : async Nat {
@@ -22,11 +22,11 @@ persistent actor {
 
         var successful_calls = 0;
 
-        for (i in Iter.range(1, n)) {
+        for (_ in Nat.range(0, n)) {
             try {
                 await c.ping();
                 successful_calls += 1;
-            } catch (e) {};
+            } catch _ {};
         };
         successful_calls;
     };
@@ -39,25 +39,22 @@ persistent actor {
             case (?c) { c };
         };
 
-        var l = List.nil<async ()>();
+        let l = List.empty<async ()>();
 
-        for (i in Iter.range(1, n)) {
+        for (_ in Nat.range(0, n)) {
             try {
-                l := List.push(c.ping(), l);
-            } catch (e) {};
+                l.add(c.ping());
+            } catch _ {};
         };
 
         // The responses on the IC will in this example come in the order of the requests in practice.
-        // We reverse the list to match the order of the requests here, as the Motoko scheduler has
-        // some overhead if the responses are awaited out of order.
-        l := List.reverse(l);
-
+        // We use List.add (append) so the order already matches the request order.
         var successful_calls = 0;
-        for (a in List.toIter(l)) {
+        for (a in l.values()) {
             try {
                 await a;
                 successful_calls += 1;
-            } catch (e) {};
+            } catch _ {};
         };
 
         successful_calls;
diff --git a/motoko/random_maze/README.md b/motoko/random_maze/README.md
@@ -4,17 +4,17 @@ The example generates a random maze using cryptographic randomness.
 
 It illustrates:
 
-- Importing library `Random` to use cryptographic randomness.
-- Make asynchronous requests for entropy using shared function `Random.blob()`.
-- Generating bounded, discrete random numbers using helper class `Random.Finite(entropy: blob)`. Each instance, f, of this class consumes its initially supplied entropy as it is called to sample from various distributions. Calls to, for example, `f.coin()` can fail by returning `null`, requiring `f` to be discarded in favor of a fresh instance of the Finite class, constructed from a fresh blob of entropy obtained from a new call to `Random.blob()` (for example `f := Finite(await Random.blob())`).
+- Importing library `Random` from `mo:core` to use cryptographic randomness.
+- Obtaining an `AsyncRandom` instance via `Random.crypto()`, which automatically fetches entropy from the management canister on demand — no manual blob management needed.
+- Generating bounded, discrete random numbers using `await* random.natRange(low, high)`.
 
 The application is built from the following Motoko source code file:
 
 - `main.mo`: contains the actor definition and methods exposed by this canister.
 
 This actor uses Motoko's random library to generate a cryptographically random maze of user-specified size.
 
-The function `generate` calls library function `Random.blob()` asynchronously to obtain 256 bits of raw entropy (256 random bits as 32 bytes) from the Internet Computer. It makes these calls on demand as it is constructing a maze. The bits of these blobs are consumed to generate samples from a variety of discrete distributions using some of the other classes and functions of library Random.mo.
+The function `generate` uses `Random.crypto()` to obtain an `AsyncRandom` instance that transparently fetches entropy from the Internet Computer whenever needed. Bounded random numbers are sampled with `await* random.natRange(0, n)`, which handles entropy replenishment automatically.
 
 This is a Motoko example that does not currently have a Rust variant.
 
diff --git a/motoko/random_maze/mops.toml b/motoko/random_maze/mops.toml
@@ -0,0 +1,13 @@
+# Motoko dependencies (https://mops.one/)
+
+[toolchain]
+moc = "1.5.1"
+
+[dependencies]
+core = "2.4.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", "-W", "M0237", "-W", "M0223"]
diff --git a/motoko/random_maze/src/random_maze/Main.mo b/motoko/random_maze/src/random_maze/Main.mo

Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-import Debug "mo:base/Debug";`
	`1`	`+import Debug "mo:core/Debug";`
`2`	`2`	`import Map "canister:map";`
`3`	`3`
`4`	`4`	`persistent actor Test {`