From 0455c4cbbec41c19d3605cdb32468d034f84b8c4 Mon Sep 17 00:00:00 2001 From: "pr-automation-bot-public[bot]" Date: Wed, 27 May 2026 07:55:10 +0000 Subject: [PATCH] chore: bump Motoko to v1.8.2 --- .sources/VERSIONS | 2 +- .sources/motoko | 2 +- .../fundamentals/actors/data-persistence.md | 2 +- .../motoko/fundamentals/actors/index.md | 3 -- .../actors/orthogonal-persistence/index.md | 3 -- .../fundamentals/basic-syntax/comments.md | 2 +- .../fundamentals/basic-syntax/identifiers.md | 2 +- .../motoko/fundamentals/basic-syntax/index.md | 3 -- .../fundamentals/basic-syntax/literals.md | 2 +- .../fundamentals/basic-syntax/whitespace.md | 2 +- .../motoko/fundamentals/control-flow/index.md | 3 -- .../declarations/class-declarations.md | 2 +- .../motoko/fundamentals/declarations/index.md | 3 -- .../motoko/fundamentals/types/index.md | 3 -- .../motoko/icp-features/system-functions.md | 44 ++++++++++++++----- docs/languages/motoko/index.md | 23 ---------- .../motoko/reference/compiler-ref.md | 2 +- 17 files changed, 41 insertions(+), 62 deletions(-) diff --git a/.sources/VERSIONS b/.sources/VERSIONS index 32e6a9c..063866e 100644 --- a/.sources/VERSIONS +++ b/.sources/VERSIONS @@ -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.8.0 75c4123 +motoko v1.8.2 f45204b 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 diff --git a/.sources/motoko b/.sources/motoko index b77651f..f45204b 160000 --- a/.sources/motoko +++ b/.sources/motoko @@ -1 +1 @@ -Subproject commit b77651f63988ec53c95b1a61760c399fcc760577 +Subproject commit f45204bc75c8e0ed5198fd2fe7265679af71814a diff --git a/docs/languages/motoko/fundamentals/actors/data-persistence.md b/docs/languages/motoko/fundamentals/actors/data-persistence.md index 8e3eea3..b97eed2 100644 --- a/docs/languages/motoko/fundamentals/actors/data-persistence.md +++ b/docs/languages/motoko/fundamentals/actors/data-persistence.md @@ -180,7 +180,7 @@ A cleaner, more maintainable solution, is to declare an explicit migration expre Both of these data migration paths are supported by static and dynamic checks that prevent data loss or corruption. A user may still lose data due to coding errors, so should tread carefully. For more information, see the [example of explicit migration](./compatibility.md#explicit-migration-using-a-migration-function) and the -reference material on [migration expressions](../../reference/language-manual.md#migration-expressions). +reference material on [migration expressions](../../language-manual.md#migration-expressions). ## Legacy features diff --git a/docs/languages/motoko/fundamentals/actors/index.md b/docs/languages/motoko/fundamentals/actors/index.md index 0a8a420..9e74ca3 100644 --- a/docs/languages/motoko/fundamentals/actors/index.md +++ b/docs/languages/motoko/fundamentals/actors/index.md @@ -1,10 +1,7 @@ --- title: "Actors" -description: "Actors are Motoko's unit of state and asynchronous concurrency. Each canister is an actor with private state and a public, async-only interface." sidebar: order: 3 label: "Actors" hidden: true --- - -Actors are Motoko's unit of state and asynchronous concurrency. Each canister is an actor: it has private state and a public interface composed of asynchronous methods. This section covers the actor model, messaging, persistence across upgrades, and migration patterns. diff --git a/docs/languages/motoko/fundamentals/actors/orthogonal-persistence/index.md b/docs/languages/motoko/fundamentals/actors/orthogonal-persistence/index.md index fd5d36e..1373d64 100644 --- a/docs/languages/motoko/fundamentals/actors/orthogonal-persistence/index.md +++ b/docs/languages/motoko/fundamentals/actors/orthogonal-persistence/index.md @@ -1,10 +1,7 @@ --- title: "Orthogonal persistence" -description: "How Motoko preserves the entire program state across canister upgrades, with no database layer or serialization code." sidebar: order: 6 label: "Orthogonal persistence" hidden: true --- - -Orthogonal persistence is the mechanism by which Motoko preserves an actor's state across canister upgrades automatically: no database, no stable memory API, no serialization code. This section covers the classical and enhanced persistence models and the trade-offs between them. diff --git a/docs/languages/motoko/fundamentals/basic-syntax/comments.md b/docs/languages/motoko/fundamentals/basic-syntax/comments.md index 80d6489..a2aa6f7 100644 --- a/docs/languages/motoko/fundamentals/basic-syntax/comments.md +++ b/docs/languages/motoko/fundamentals/basic-syntax/comments.md @@ -45,7 +45,7 @@ Multi-line comments can be nested within each other. ## Resources -- [Comment style guide](../../reference/style-guide.md#comments) +- [Comment style guide](../../style-guide.md#comments) - [Generating Motoko documentation](/developer-tools/#mo-doc) diff --git a/docs/languages/motoko/fundamentals/basic-syntax/identifiers.md b/docs/languages/motoko/fundamentals/basic-syntax/identifiers.md index ca08df9..e8b32dd 100644 --- a/docs/languages/motoko/fundamentals/basic-syntax/identifiers.md +++ b/docs/languages/motoko/fundamentals/basic-syntax/identifiers.md @@ -16,4 +16,4 @@ let snake_case_identifier = "for compatibility with other languages"; ## Reserved syntax keywords -Motoko reserves [keywords](../../reference/language-manual.md#keywords) for its syntax and they cannot be used as identifiers. +Motoko reserves [keywords](../../language-manual.md#keywords) for its syntax and they cannot be used as identifiers. diff --git a/docs/languages/motoko/fundamentals/basic-syntax/index.md b/docs/languages/motoko/fundamentals/basic-syntax/index.md index f978983..43cc2f7 100644 --- a/docs/languages/motoko/fundamentals/basic-syntax/index.md +++ b/docs/languages/motoko/fundamentals/basic-syntax/index.md @@ -1,10 +1,7 @@ --- title: "Basic syntax" -description: "The lexical and surface syntax of Motoko: identifiers, literals, operators, functions, comments, and the structure of an actor." sidebar: order: 2 label: "Basic syntax" hidden: true --- - -This section covers the lexical and surface syntax of Motoko: how to define an actor, write functions, declare identifiers, use literals and operators, and the conventions for comments and whitespace. diff --git a/docs/languages/motoko/fundamentals/basic-syntax/literals.md b/docs/languages/motoko/fundamentals/basic-syntax/literals.md index f0c7ad9..94eb047 100644 --- a/docs/languages/motoko/fundamentals/basic-syntax/literals.md +++ b/docs/languages/motoko/fundamentals/basic-syntax/literals.md @@ -25,5 +25,5 @@ You can use literals directly in expressions. ## Resources -- [Literals](../../reference/language-manual.md#literals) +- [Literals](../../language-manual.md#literals) diff --git a/docs/languages/motoko/fundamentals/basic-syntax/whitespace.md b/docs/languages/motoko/fundamentals/basic-syntax/whitespace.md index ce73106..5cc36c0 100644 --- a/docs/languages/motoko/fundamentals/basic-syntax/whitespace.md +++ b/docs/languages/motoko/fundamentals/basic-syntax/whitespace.md @@ -26,5 +26,5 @@ persistent actor Counter { ## Resources -- [Motoko style guide](../../reference/style-guide.md) +- [Motoko style guide](../../style-guide.md) diff --git a/docs/languages/motoko/fundamentals/control-flow/index.md b/docs/languages/motoko/fundamentals/control-flow/index.md index 7f363b2..7681360 100644 --- a/docs/languages/motoko/fundamentals/control-flow/index.md +++ b/docs/languages/motoko/fundamentals/control-flow/index.md @@ -1,10 +1,7 @@ --- title: "Control flow" -description: "Motoko's control flow constructs: blocks, conditionals, switch expressions, loops, and the expression-oriented evaluation model." sidebar: order: 6 label: "Control flow" hidden: true --- - -Control flow in Motoko is expression-oriented: blocks, conditionals, `switch`, and loops are all expressions that evaluate to a value. This section covers each construct and the patterns that compose them. diff --git a/docs/languages/motoko/fundamentals/declarations/class-declarations.md b/docs/languages/motoko/fundamentals/declarations/class-declarations.md index 4861ead..0438118 100644 --- a/docs/languages/motoko/fundamentals/declarations/class-declarations.md +++ b/docs/languages/motoko/fundamentals/declarations/class-declarations.md @@ -166,5 +166,5 @@ Using this `system` syntax, developers can: - Manually install, upgrade, or reinstall canisters. - Access lower-level canister management features provided by ICP. -[Learn more about actor class management](../../reference/language-manual.md#actor-class-management). +[Learn more about actor class management](../../language-manual.md#actor-class-management). diff --git a/docs/languages/motoko/fundamentals/declarations/index.md b/docs/languages/motoko/fundamentals/declarations/index.md index 9c132a9..8ca6fbd 100644 --- a/docs/languages/motoko/fundamentals/declarations/index.md +++ b/docs/languages/motoko/fundamentals/declarations/index.md @@ -1,10 +1,7 @@ --- title: "Declarations" -description: "Motoko's declaration forms: variables, types, functions, classes, modules, and objects." sidebar: order: 5 label: "Declarations" hidden: true --- - -Declarations introduce names into a Motoko program. This section covers the full set of declaration forms: variable and type bindings, functions, classes, modules, and object literals, including the rules around scope and recursion. diff --git a/docs/languages/motoko/fundamentals/types/index.md b/docs/languages/motoko/fundamentals/types/index.md index 96bc3c6..b9acc74 100644 --- a/docs/languages/motoko/fundamentals/types/index.md +++ b/docs/languages/motoko/fundamentals/types/index.md @@ -1,10 +1,7 @@ --- title: "Types" -description: "Motoko's type system: primitive types, records, tuples, variants, options, results, arrays, function types, and subtyping." sidebar: order: 4 label: "Types" hidden: true --- - -Motoko has a sound, expressive type system that prevents whole classes of bugs at compile time: null-pointer errors, missing-pattern errors, and uncoordinated stable-state changes across upgrades. This section covers each type form and the subtyping rules that connect them. diff --git a/docs/languages/motoko/icp-features/system-functions.md b/docs/languages/motoko/icp-features/system-functions.md index 0755138..78e5da3 100644 --- a/docs/languages/motoko/icp-features/system-functions.md +++ b/docs/languages/motoko/icp-features/system-functions.md @@ -49,35 +49,55 @@ system func timer(setGlobalTimer : Nat64 -> ()) : async () { ## `preupgrade()` -The `preupgrade()` system function is invoked immediately before a canister upgrade. It runs before the new Wasm module is installed, giving the current version one last chance to act. The function takes no arguments and must have type `() -> ()`. +The preupgrade() system function is invoked immediately before a canister upgrade to prepare for state migration. Its primary role is to save critical data, typically non-stable variables, into stable storage, ensuring that important state information is preserved across the upgrade. This function executes before the new Wasm module is installed, making it the last opportunity to capture any necessary state from the current canister version. + +Any failure, such as a trap or exceeding computation limits prevents the upgrade from succeeding, potentially leaving the canister in an unrecoverable state. As a result, **using `preupgrade()` is discouraged unless necessary**. + +The following example saves a `HashMap` of user balances into a stable variable before upgrading. + +`balances` is a non-stable `HashMap` that would normally be lost during an upgrade. Before upgrading, `preupgrade()` stores the key-value pairs in a stable array (`savedBalances`). + +After upgrading, the `postupgrade()` function (#postupgrade) can restore the saved state. ```motoko no-repl -persistent actor MyCanister { +import Iter "mo:core/Iter"; +import HashMap "mo:base/HashMap"; // Data structure from original standard library + +persistent actor Token { + + transient var balances = HashMap.HashMap(10, Text.equal, Text.hash); // Non-stable + var savedBalances : [(Text, Nat)] = []; // Implicit stable storage + system func preupgrade() { - // Runs before the upgrade installs the new Wasm. + savedBalances := Iter.toArray(balances.entries()); // Save state before upgrade } } ``` -:::danger -If `preupgrade` traps, runs out of cycles, or hits any other IC computing limit, **the upgrade fails and the canister cannot be upgraded going forward**: it is stuck on the current version. Use of this hook is discouraged. -::: - -With orthogonal persistence, `mo:core` data structures persist across upgrades automatically and this hook is rarely needed. For the (legacy) save-into-stable-storage pattern and the migration alternatives that replace it, see [Data persistence](../fundamentals/actors/data-persistence.md). ## `postupgrade()` -The `postupgrade()` system function runs immediately after an upgrade installs the new Wasm. The function takes no arguments and must have type `() -> ()`. +The `postupgrade()` system function is called immediately after a canister upgrade, allowing a canister to restore state or execute initialization logic. Unlike `preupgrade()`, **it is not required**, as most of its effects can be achieved using actor initialization expressions (`let` bindings and expression statements). However, `postupgrade()` is useful for reconstructing data structures or running migration logic. + +This example restores the `balances` `HashMap` using the data that was saved by `preupgrade()`. ```motoko no-repl -persistent actor MyCanister { +import HashMap "mo:base/HashMap"; // Data structure from original standard library + +persistent actor Token { + + transient var balances = HashMap.HashMap(10, Text.equal, Text.hash); + var savedBalances : [(Text, Nat)] = []; + system func postupgrade() { - // Runs after the upgrade installs the new Wasm. + balances := HashMap.fromIter(savedBalances.vals(), 10, Text.equal, Text.hash); } } ``` -`postupgrade` is rarely required: the same effect can usually be achieved with actor initialization expressions (`let` bindings and statements at the top of the actor body), which run on every install and upgrade. See [Data persistence](../fundamentals/actors/data-persistence.md) for the recommended patterns. +The **use of upgrade hooks is not recommended** as they can fail and cause the program to enter an unrecoverable state. With advancements in orthogonal persistence, these hooks are expected to be deprecated. + +In many cases, stable variables or actor initialization expressions can replace `postupgrade()`. Complex transformations increase the risk of errors and failures. ## `lowmemory()` diff --git a/docs/languages/motoko/index.md b/docs/languages/motoko/index.md index a25f9e1..2b9c334 100644 --- a/docs/languages/motoko/index.md +++ b/docs/languages/motoko/index.md @@ -70,29 +70,6 @@ If you have an existing project using `base`, you can migrate incrementally; bot `core` and all other Motoko packages are managed with [Mops](https://mops.one), which handles dependency resolution, compiler toolchain management, and publishing. Browse community packages at [mops.one](https://mops.one). -## Example projects - -Starting points by use case: - -**Web applications** - -- [Hello, world!](https://github.com/dfinity/examples/tree/master/motoko/hello_world) -- [Calling external APIs from a Motoko canister](https://github.com/dfinity/examples/tree/master/motoko/send_http_get) -- [Reversi game](https://github.com/ninegua/reversi) - -**DeFi** - -- [ICRC-1 token canister](https://github.com/sonicdex/icrc-1-public/) -- [Decentralized exchange (DEX)](https://github.com/dfinity/examples/tree/master/motoko/icrc2-swap) -- [ICRC-7 NFTs](https://github.com/noku-team/icrc7_motoko) - -**Chain Fusion** - -- [Ethereum integration](https://github.com/dfinity/icp-eth-starter) -- [Bitcoin point-of-sale](https://github.com/dfinity/examples/tree/master/motoko/ic-pos) - -For more, browse the full [Motoko examples collection](https://github.com/dfinity/examples/tree/master/motoko). - ## Further reading - [Quickstart](/getting-started/quickstart): create and deploy your first canister diff --git a/docs/languages/motoko/reference/compiler-ref.md b/docs/languages/motoko/reference/compiler-ref.md index 8a62451..ed4ccf8 100644 --- a/docs/languages/motoko/reference/compiler-ref.md +++ b/docs/languages/motoko/reference/compiler-ref.md @@ -53,7 +53,7 @@ You can use the following options with the `moc` command. | `--incremental-gc` | Use incremental GC (default, works with both enhanced orthogonal persistence and legacy/classical persistence). | | `--idl` | Compile binary and emit Candid IDL specification to `.did` file. | | `-i` | Runs the compiler in an interactive read–eval–print loop (REPL) shell so you can evaluate program execution (implies -r). | -| `--implicit-derivation-depth ` | Maximum recursion depth for [implicit](../fundamentals/implicit-parameters.md) argument derivation (default 100). Raise if a complex derivation is rejected as depth-limited. | +| `--implicit-derivation-depth ` | Maximum recursion depth for [implicit](./fundamentals/11-implicit-parameters.md) argument derivation (default 100). Raise if a complex derivation is rejected as depth-limited. | | `--legacy-persistence` | Use legacy (classical) persistence. This also enables the usage of --copying-gc, --compacting-gc, and --generational-gc. Deprecated in favor of the new enhanced orthogonal persistence, which is default. Legacy persistence will be removed in the future.| | `--map` | Outputs a JavaScript source map. | | `--max-stable-pages ` | Set maximum number of pages available for library `ExperimentStableMemory.mo` (default 65536). |