dfinity · marc0olo · May 19, 2026 · May 19, 2026
@@ -57,7 +57,7 @@ chain-fusion-signer   v0.3.0
 papi                  v0.1.1                                                    168bc9d
 ic-pub-key            v1.0.1                                                    f89fa55
 icp-cli               v0.2.3                                                    caeac37
-motoko                v1.7.0                                                     1e65e26
+motoko                v1.8.0                                                     75c4123
 motoko-core           v2.4.0                                                    cd37dbf
 cdk-rs                ic-cdk v0.20.1 / ic-cdk-timers v1.0.0 / ic-cdk-executor v2.0.0  317f55c
 candid                2025-12-18  # candid v0.10.20, didc v0.5.4                2e4a2cf

@@ -250,19 +250,19 @@ When using [enhanced multi-migration](/languages/motoko/fundamentals/actors/enha
 
 Motoko uses three versions of the stable signature format, each corresponding to a different migration style:
 
-**Version 1.0.0 — Single.** The original format, listing the actor's stable fields. Used when the actor has no migration function.
+**Version 1.0.0: Single.** The original format, listing the actor's stable fields. Used when the actor has no migration function.
 
 ```motoko no-repl file=<motokoExamples>/count-v1.most
 ```
 
-**Version 3.0.0 — Pre/Post.** Used when the actor declares a single migration function via `(with migration = ...)`. The signature contains a pre-signature (the fields the migration function consumes from the old actor) and a post-signature (the new actor's stable fields):
+**Version 3.0.0: Pre/Post.** Used when the actor declares a single migration function via `(with migration = ...)`. The signature contains a pre-signature (the fields the migration function consumes from the old actor) and a post-signature (the new actor's stable fields):
 
 ```motoko no-repl file=<motokoExamples>/count-v9.most
 ```
 
 Fields marked `in` are required inputs that must be present in the previous actor. Fields marked `stable` are carried through or newly declared.
 
-**Version 4.0.0 — Multi (enhanced).** Used with `--enhanced-migration`. The signature contains the full migration chain followed by the actor's stable fields. Each entry in the chain records a migration module's name and function signature:
+**Version 4.0.0: Multi (enhanced).** Used with `--enhanced-migration`. The signature contains the full migration chain followed by the actor's stable fields. Each entry in the chain records a migration module's name and function signature:
 
 ```
 // Version: 4.0.0

@@ -6,7 +6,7 @@ title: "Enhanced multi-migration"
 
 Enhanced multi-migration lets you manage canister state changes over time through a series of migration modules, each stored in its own file. Instead of writing a single inline migration function, one builds up a chain of small, self-contained migrations that the compiler and runtime apply in order.
 
-This approach is especially useful for long-lived canisters whose data shape evolves across many deployments. Each migration captures one logical change — adding a field, renaming a field, changing a type — and the compiler verifies that the entire chain is consistent.
+This approach is especially useful for long-lived canisters whose data shape evolves across many deployments. Each migration captures one logical change: adding a field, renaming a field, changing a type: and the compiler verifies that the entire chain is consistent.
 
 ## Overview
 
@@ -17,7 +17,7 @@ With enhanced multi-migration you:
 3. Each migration module exports a `public func migration({...}) : {...}` that transforms a subset of stable fields.
 4. Pass `--enhanced-migration ./migrations` to `moc` when compiling.
 
-The compiler reads all migration modules in lexicographic order, checks that they compose correctly, and compiles them into the actor. At runtime, only migrations that have not yet been applied are executed — already-applied migrations are skipped automatically.
+The compiler reads all migration modules in lexicographic order, checks that they compose correctly, and compiles them into the actor. At runtime, only migrations that have not yet been applied are executed: already-applied migrations are skipped automatically.
 
 :::note
 Enhanced multi-migration requires enhanced orthogonal persistence. It cannot be combined with the inline `(with migration = ...)` syntax used for [single migration functions](/languages/motoko/fundamentals/actors/compatibility#explicit-migration-using-a-migration-function).
@@ -52,7 +52,7 @@ module {
 }
 ```
 
-The input record describes which stable fields this migration reads from the current state. The output record describes which fields this migration produces. The input field types must be compatible with the state at that point in the chain, and the output field types must ultimately be compatible with the new actor's declared stable fields. A migration only needs to mention the fields it cares about — all other stable fields are carried through unchanged.
+The input record describes which stable fields this migration reads from the current state. The output record describes which fields this migration produces. The input field types must be compatible with the state at that point in the chain, and the output field types must ultimately be compatible with the new actor's declared stable fields. A migration only needs to mention the fields it cares about: all other stable fields are carried through unchanged.
 
 ### The actor
 
@@ -71,7 +71,7 @@ actor {
 }
 ```
 
-The initial value of each uninitialized variable is determined entirely by the migration chain. When the canister is first deployed, every migration runs in order and the final state provides the values. On subsequent upgrades, only newly added migrations execute, but the result is the same: the migration chain — not the actor source — is the single source of truth for stable variable values.
+The initial value of each uninitialized variable is determined entirely by the migration chain. When the canister is first deployed, every migration runs in order and the final state provides the values. On subsequent upgrades, only newly added migrations execute, but the result is the same: the migration chain: not the actor source: is the single source of truth for stable variable values.
 
 The compiler rejects any stable variable that carries an initializer when `--enhanced-migration` is enabled. This prevents ambiguity about whether the value comes from the migration chain or from the inline expression.
 
@@ -81,7 +81,7 @@ Non-stable declarations (local variables inside functions, private helper fields
 
 ### Static actor body
 
-Because the migration chain is the sole source of stable variable values, the top-level code in the actor body must be **static** — it must evaluate without immediate side effects. Arbitrary function calls, mutable updates to non-stable state, and other effectful expressions at the top level of the actor are rejected by the compiler.
+Because the migration chain is the sole source of stable variable values, the top-level code in the actor body must be **static**: it must evaluate without immediate side effects. Arbitrary function calls, mutable updates to non-stable state, and other effectful expressions at the top level of the actor are rejected by the compiler.
 
 The one exception is calls to functions that require `<system>` capability, such as setting up ICP timers or configuring Candid decoding limits. These calls are permitted because they do not alter stable variable state; their effects are confined to system-level configuration.
 
@@ -118,13 +118,13 @@ moc --enhanced-orthogonal-persistence \
 
 Each migration's `migration` function declares which fields it reads (input) and which fields it produces (output). The relationship between input and output fields determines what happens to the state:
 
-- **Input and output** — the migration transforms this field. It reads the old value and produces a new one, potentially with a different type. The output value replaces the old one in the state.
+- **Input and output**: the migration transforms this field. It reads the old value and produces a new one, potentially with a different type. The output value replaces the old one in the state.
 
-- **Output only** — the migration introduces a new field. The field is added to the state with the value and type returned by the migration.
+- **Output only**: the migration introduces a new field. The field is added to the state with the value and type returned by the migration.
 
-- **Input only** — the migration consumes and removes this field. The field is dropped from the state. Later migrations can no longer reference it.
+- **Input only**: the migration consumes and removes this field. The field is dropped from the state. Later migrations can no longer reference it.
 
-- **Neither input nor output** — the field is untouched by this migration and carried through to the next migration (or the final actor) as-is.
+- **Neither input nor output**: the field is untouched by this migration and carried through to the next migration (or the final actor) as-is.
 
 For example, given the state `{a : Nat; b : Text; c : Bool}` and a migration:
 
@@ -272,7 +272,7 @@ module {
 
 Here is how an actor's state might evolve across several deployments:
 
-**Step 1 — Initial deployment:**
+**Step 1: Initial deployment:**
 
 ```motoko no-repl
 // migrations/20250101_000000_Init.mo
@@ -291,7 +291,7 @@ actor {
 
 State: `{a : Nat}`
 
-**Step 2 — Add field `b`:**
+**Step 2: Add field `b`:**
 
 ```motoko no-repl
 // migrations/20250201_000000_AddB.mo
@@ -311,7 +311,7 @@ actor {
 
 State: `{a : Nat; b : Int}`
 
-**Step 3 — Change `b` from `Int` to `Bool`:**
+**Step 3: Change `b` from `Int` to `Bool`:**
 
 ```motoko no-repl
 // migrations/20250301_000000_ChangeBType.mo
@@ -331,7 +331,7 @@ actor {
 
 State: `{a : Nat; b : Bool}`
 
-**Step 4 — Drop field `a`:**
+**Step 4: Drop field `a`:**
 
 ```motoko no-repl
 // migrations/20250401_000000_DropA.mo
@@ -350,7 +350,7 @@ actor {
 
 State: `{b : Bool}`
 
-**Step 5 — Reintroduce `a` with a new type:**
+**Step 5: Reintroduce `a` with a new type:**
 
 ```motoko no-repl
 // migrations/20250501_000000_AddAText.mo

@@ -14,7 +14,7 @@ Use `//` for comments that extend to the end of a line.
 // This is a single-line comment
 ```
 
-Use `///` for function or module documentation (also known as "doc comments"). Module documentation can be exported into documentation files such as Markdown or HTML using [mo-doc](../../../../developer-tools/index.md#mo-doc).
+Use `///` for function or module documentation (also known as "doc comments"). Module documentation can be exported into documentation files such as Markdown or HTML using [mo-doc](/developer-tools/#mo-doc).
 
 ```motoko no-repl
 /// Returns the sum of two integers.
@@ -46,5 +46,5 @@ Multi-line comments can be nested within each other.
 
 - [Comment style guide](/languages/motoko/reference/style-guide#comments)
 
-- [Generating Motoko documentation](../../../../developer-tools/index.md#mo-doc)
+- [Generating Motoko documentation](/developer-tools/#mo-doc)
 
@@ -39,7 +39,7 @@ type Result<Ok, Err> = { #ok : Ok; #err : Err }
 
 Unlike option types, the Result type includes a second type parameter `Err` which allows you to specify exactly what kind of error occurred. This makes error handling more informative and flexible.
 
-```motoko no-repl file=<motokoExamples>/todo-error.mo#L60-L60
+```motoko no-repl file=<motokoExamples>/todo-error.mo#L59-L59
 ```
 
 The previous example can be revised to use `Result` types:

@@ -6,25 +6,25 @@ description: "Motoko language documentation"
 ## Overview
 
 Implicit parameters allow you to omit frequently-used function arguments at call sites when the compiler can infer them from context. This feature is particularly useful when working with ordered collections like `Map` and `Set` from the `core` library, which require comparison functions but where the comparison logic is usually obvious from the key type.
-Other exampes are `equal` and `toText` functions.
+Other examples are `equal` and `toText` functions.
 
 ## Basic usage
 
 ### Declaring implicit parameters
 
 When declaring a function, any function parameter can be declared implicit using the `implicit` type constructor:
 
-For example, the core Map library, declares a function:
+For example, the core `Map` library declares a function:
 
 ```motoko no-repl
 public func add<K, V>(self: Map<K, V>, compare : (implicit : (K, K) -> Order), key : K, value : V) {
   // ...
 }
 ```
 
-The `implicit` marker on the type of parameter `compare` indicates the call-site can omit it the `compare` argument, provided it can be inferred the call site.
+The `implicit` marker on the type of parameter `compare` indicates the call-site can omit the `compare` argument, provided it can be inferred at the call site.
 
-A function can declare more than on implicit parameter, even of the same name.
+A function can declare more than one implicit parameter, even of the same name.
 
 
 ```motoko
@@ -58,7 +58,7 @@ Map.add(map, 5, "five");
 ```
 The compiler automatically finds an appropriate comparison function based on the type of the key argument.
 
-The availabe candidates are:
+The available candidates are:
 * Any value named `compare` whose type matches the parameter type.
 
 If there is no such value,
@@ -69,7 +69,7 @@ An ambiguous call can always be disambiguated by supplying the explicit argument
 
 ### Contextual dot notation
 
-Implicit parameters dovetail nicely with the [contextual dot notation](contextual-dot).
+Implicit parameters dovetail nicely with [contextual dot notation](/languages/motoko/fundamentals/contextual-dot).
 The dot notation and implicit arguments can be used in conjunction to shorten code.
 
 For example, since the first parameter of `Map.add` is called `self`, we can both use `map` as the receiver of `add` "method" calls
@@ -84,7 +84,7 @@ let map = Map.empty<Nat, Text>();
 // Using contextual dot notation, without implicits - must provide compare function explicitly
 map.add(Nat.compare, 5, "five");
 
-// Using contextual dot nation together with implicits - compare function inferred from key type
+// Using contextual dot notation together with implicits - compare function inferred from key type
 map.add(5, "five");
 ```
 
@@ -150,7 +150,7 @@ let scores = Map.empty<Text, Nat>();
 // Add player scores
 scores.add("Alice", 100);
 scores.add("Bob", 85);
-scores.add( "Charlie", 92);
+scores.add("Charlie", 92);
 
 // Update a score
 scores.add("Bob", 95);
@@ -161,7 +161,7 @@ if (scores.containsKey("Alice")) {
 };
 
 // Get size
-let playerCount = scores.size()
+let playerCount = scores.size();
 ```
 
 ## How inference works
@@ -170,13 +170,57 @@ The compiler infers an implicit argument by:
 
 1. Examining the types of the explicit arguments provided.
 2. Looking for all candidate values for the implicit argument in the current scope that match the required type and name.
-3. From these, selecting the best unique candidate based on type specifity.
+3. From these, selecting the best unique candidate based on type specificity.
 
 If there is no unique best candidate the compiler rejects the call as ambiguous.
 
-If a callee takes several implicits parameter, either all implicit arguments must be omitted, or all explicit and implicit arguments must be provided at the call site,
+If a callee takes several implicit parameters, either all implicit arguments must be omitted, or all explicit and implicit arguments must be provided at the call site,
 in their declared order.
 
+### Resolution order
+
+The compiler searches for implicit arguments in the following order, stopping at the first tier that produces a unique match:
+
+1. **Direct**: values whose type directly matches:
+   1. Local values in the current scope.
+   2. Module fields of modules in scope (e.g., `Nat.compare`).
+   3. Fields of unimported modules (requires `--implicit-package`).
+2. **Derived**: functions with implicit parameters that, after stripping their own implicits and instantiating type parameters, match the required type (see [Implicit derivation](#implicit-derivation) below):
+   1. Local values in the current scope.
+   2. Module fields (e.g., `Array.compare<T>`).
+   3. Fields of unimported modules (requires `--implicit-package`).
+Within each tier, if multiple candidates match, the compiler picks the most specific one (by subtyping). If no unique best candidate exists, the call is rejected as ambiguous.
+
+This ordering guarantees that direct matches are always preferred over derived ones, and local definitions take precedence over imported or unimported module definitions.
+
+### Implicit derivation
+
+When no direct match exists, the compiler can **derive** an implicit argument from a function that itself has implicit parameters. This eliminates the need for boilerplate wrapper functions. The candidate function can be polymorphic (the compiler infers the type instantiation) or monomorphic.
+
+For example, suppose `Array.compare` is declared as:
+
+```motoko no-repl
+public func compare<T>(a : [T], b : [T], compare : (implicit : (T, T) -> Order)) : Order
+```
+
+and a function requires an implicit `compare : ([Nat], [Nat]) -> Order`. Without derivation, you would need to write a wrapper:
+
+```motoko no-repl
+module MyArray {
+  public func compare(a : [Nat], b : [Nat]) : Order {
+    Array.compare(a, b) // resolves inner `compare` to Nat.compare
+  };
+};
+```
+
+With derivation, the compiler handles this automatically. It recognizes that `Array.compare<Nat>`, after removing its implicit `compare` parameter and instantiating `T := Nat`, has the right type. It then recursively resolves the inner implicit (`Nat.compare`) and synthesizes the wrapper for you.
+
+This works transitively: a `compare` for `[[Nat]]` is derived via `Array.compare<[Nat]>`, which needs `[Nat]` compare, which is derived via `Array.compare<Nat>`, which needs `Nat.compare`: all resolved automatically.
+
+The resolution depth is bounded to guarantee termination. If you encounter a depth limit, you can increase it with `--implicit-derivation-depth` or provide the argument explicitly.
+
+When derivation is attempted but fails (for example, because an inner implicit can't be resolved), the compiler reports which inner implicits were missing and, when applicable, a hint about which module to import.
+
 ### Supported types
 
 The core library provides comparison functions for common types:
@@ -278,7 +322,9 @@ There is no need to update existing code unless you want to take advantage of th
 
 ## Performance considerations
 
-Implicit arguments have no runtime overhead. The comparison function is resolved at compile time, so there is no performance difference between using implicit and explicit arguments. The resulting code is identical.
+Implicit arguments are resolved at compile time.
+- For direct matches, the resulting code is identical to explicitly passing the argument.
+- For derived implicits, the compiler synthesizes a wrapper function at each call site. This creates a small overhead per call site, which could be mitigated by caching in the future. For now, if this becomes a performance issue, consider defining the function explicitly so all call sites share a single definition.
 
 ## See also