0.13.0

• motoko (moc)

  • Added a new primitive cyclesBurn : <system> Nat -> Nat for burning the canister's cycles
    programmatically (#4690).

  • For beta testing: Support enhanced orthogonal persistence, enabled with new moc flag --enhanced-orthogonal-persistence (#4193).

    This implements scalable and efficient orthogonal persistence (stable variables) for Motoko:

    • The Wasm main memory (heap) is retained on upgrade with new program versions directly picking up this state.
    • The Wasm main memory has been extended to 64-bit to scale as large as stable memory in the future.
    • The runtime system checks that data changes of new program versions are compatible with the old state.

    Implications:

    • Upgrades become extremely fast, only depending on the number of types, not on the number of heap objects.
    • Upgrades will no longer hit the IC instruction limit, even for maximum heap usage.
    • The change to 64-bit increases the memory demand on the heap, in worst case by a factor of two.
    • For step-wise release handling, the IC initially only offers a limited capacity of the 64-bit space (e.g. 4GB or 6GB), that will be gradually increased in future to the capacity of stable memory.
    • There is moderate performance regression of around 10% for normal execution due to combined related features (precise tagging, change to incremental GC, and handling of compile-time-known data).
    • The garbage collector is fixed to incremental GC and cannot be chosen.
    • Float.format(#hex prec, x) is no longer supported (expected to be very rarely used in practice).
    • The debug print format of NaN changes (originally nan).

    To activate enhanced orthogonal persistence under dfx, the following command-line argument needs to be specified in dfx.json:

    ...
      "type" : "motoko"
      ...
      "args" : "--enhanced-orthogonal-persistence"
    ...
    

    BREAKING CHANGE (Minor): changes some aspects of Float formatting.

    For more information, see:

    • The Motoko design documentation design/OrthogonalPersistence.md
    • The Motoko user documentation doc/md/canister-maintenance/upgrades.md.

  • Candid decoding: impose an upper limit on the number of values decoded or skipped in a single candid payload,
    as a linear function, max_values, of binary payload size.

      max_values(blob) = (blob.size() * numerator)/denominator + bias
    

    The current default settings are {numerator = 1; denominator = 1; bias = 1024 }, allowing a maximum
    of 1024 values plus one additional value per byte in the payload.

    While hopefully not required, the constant factors can be read/modified using system functions:

    • Prim.setCandidLimits: <system>{numerator : Nat32; denominator : Nat32; bias : Nat32 } -> ()
    • Prim.getCandidLimits: <system>() -> {numerator : Nat32; denominator : Nat32; bias : Nat32 }

0.12.1

• motoko (moc)

  • Added a new command-line flag --print-source-on-error to print source code context on error (#4650).

  • debugging: __motoko_runtime_information() as privileged query for runtime statistics (#4635).

    Exposing a privileged system-level query function __motoko_runtime_information()
    that reports the current runtime statistics of the canister, such as the heap size,
    the total number of allocated objects, the total amount of reclaimed memory and more.
    This is useful because several statistics of the reported information cannot be
    inspected on the IC replica dashboard as they are internal to the Motoko runtime system.
    This query is only authorized to the canister controllers and self-calls of the canister.

    __motoko_runtime_information : () -> {
        compilerVersion : Text;
        rtsVersion : Text;
        garbageCollector : Text;
        sanityChecks : Nat;
        memorySize : Nat;
        heapSize : Nat;
        totalAllocation : Nat;
        reclaimed : Nat;
        maxLiveSize : Nat;
        stableMemorySize : Nat;
        logicalStableMemorySize : Nat;
        maxStackSize : Nat;
        callbackTableCount : Nat;
        callbackTableSize : Nat;
    }

0.12.0

• motoko (moc)

  • feat: finally clauses for try expressions (#4507).

    A trailing finally clause to try/catch expressions facilitates structured
    resource deallocation (e.g. acquired locks, etc.) and similar cleanups in the
    presence of control-flow expressions (return, break, continue, throw).
    Additionally, in presence of finally the catch clause becomes optional and
    and any uncaught error from the try block will be propagated, after executing the finally block.

    Note: finally-expressions that are in scope will be executed even if an execution
    path following an await-expression traps. This feature, formerly not available in Motoko,
    allows programmers to implement cleanups even in the presence of traps. For trapping
    execution paths prior to any await, the replica-provided state roll-back mechanism
    ensures that no cleanup is required.

    The relevant security best practices are accessible at
    https://internetcomputer.org/docs/current/developer-docs/security/security-best-practices/inter-canister-calls#recommendation

    BREAKING CHANGE (Minor): finally is now a reserved keyword,
    programs using this identifier will break.

  • bugfix: mo-doc will now generate correct entries for public variables (#4626).

0.11.3

• motoko (moc)

  • feat: motoko-san contributions by Serokell. Now able to verify some simple but non-trivial actors
    (thanks to the entire Serokell team) (#4500).

  • bugfix: Corrects the interpreter (and compiler) to recognise certain type parameters as callable function types (#4617).

0.11.2

• motoko (moc)

  • deprecation: Deprecate the use of base library's ExperimentalStableMemory (ESM) (#4573).
    New moc flag --experimental-stable-memory <n> controls the level of deprecation:

    • n < 0: error on use of stable memory primitives.
    • n = 0: warn on use of stable memory primitives.
    • n > 1: warning-less use of stable memory primitives (for legacy applications).
      Users of ESM should consider migrating their code to use isolated regions (library Region.mo) instead.

  • bugfix: Fix the detection of unused declarations in switch and catch alternatives (#4560).

  • improvement: Only warn on unused identifiers if type checking is error-free (#4561).

0.11.1

• motoko (moc)

  • feat: Custom error message for unused, punned field bindings (#4454).

  • feat: Don't report top-level identifiers as unused (#4452).

  • bugfix: Declaring <system, ...> capability on a class enables system capabilities in its body (#4449).

  • bugfix: Fix crash compiling actor reference containing an await (#4418, #4450).

  • bugfix: Fix crash when compiling with flag --experimental-rtti (#4434).

0.11.0

• motoko (moc)

  • Warn on detection of unused identifiers (code M0194) (#4377).

    • By design, warnings are not emitted for code imported from a package.
    • A warning can be suppressed by replacing the identifier entirely by a wildcard _,
      or by prefixing it with an _, e.g. replace x by _x.

    Limitations: recursive and mutually recursive definitions are considered used,
    even if never referenced outside the recursive definition.

  • Remove __get_candid_interface_tmp_hack endpoint. Candid interface is already stored as canister metadata, this temporary endpoint is redundant, thus removed. (#4386)

  • Improved capability system, introducing a synchronous (system) capability (#4406).

    actor initialisation body, pre/postupgrade hooks, async function bodies (and
    blocks) possess this capability. Functions (and classes) can demand it by prepending system
    to the type argument list. The capability can be forwarded in calls by mentioning <system, …>
    in the instantiation parameter list.

    BREAKING CHANGE (Minor): A few built-in functions have been marked with demand
    for the system capability. In order to call these, the full call hierarchy needs to be
    adapted to pass the system capability.

  • Introduced the feature for precise tagging of scalar values (#4369).

    Controlled by flag --experimental-rtti (off by default). Minor performance changes for
    arithmetic expected. We advise to only turn on the feature for testing, as currently no
    productive upsides exist (though future improvements will depend on it), and performance
    of arithmetic will degrade somewhat. See the PR for the whole picture.

• motoko-base

  • Added Option.equal function (thanks to ByronBecker) (dfinity/motoko-base⁠#615).

0.10.4

• motoko (moc)

  • Officializing the new incremental garbage collector after a successful beta testing phase.
    The incremental GC can be enabled by the moc flag --incremental-gc (#3837) and is designed to scale for large program heap sizes.

    Note: While resolving scalability issues with regard to the instruction limit of the GC work, it is now possible to hit other scalability limits:

    • Out of memory: A program can run out of memory if it fills the entire memory space with live objects.
    • Upgrade limits: When using stable variables, the current mechanism of serialization and deserialization to and from stable memory can exceed the instruction limit or run out of memory.

    Recommendations:

    • Test the upgrade: Thoroughly test the upgrade mechanism for different data volumes and heap sizes and conservatively determine the amount of stable data that is supported when upgrading the program.
    • Monitor the heap size: Monitor the memory and heap size (Prim.rts_memory_size() and Prim.rts_heap_size()) of the application in production.
    • Limit the heap size: Implement a custom limit in the application to keep the heap size and data volume below the scalability limit that has been determined during testing, in particular for the upgrade mechanism.
    • Avoid large allocations per message: Avoid large allocations of 100 MB or more per message, but rather distribute larger allocations across multiple messages. Large allocations per message extend the duration of the GC increment. Moreover, memory pressure may occur because the GC has a higher reclamation latency than a classical stop-the-world collector.
    • Consider a backup query function: Depending on the application case, it can be beneficial to offer an privileged query function to extract the critical canister state in several chunks. The runtime system maintains an extra memory reserve for query functions. Of course, such a function has to be implemented with a check that restricts it to authorized callers only. It is also important to test this function well.
    • Last resort if memory would be full: Assuming the memory is full with objects that have shortly become garbage before the memory space has been exhausted, the canister owner or controllers can call the system-level function __motoko_gc_trigger() multiple times to run extra GC increments and complete a GC run, for collecting the latest garbage in a full heap. Up to 100 calls of this function may be needed to complete a GC run in a 4GB memory space. The GC keeps an specific memory reserve to be able to perform its work even if the application has exhausted the memory. Usually, this functionality is not needed in practice but is only useful in such exceptional cases.

  • Allow type annotations on free-standing object/module/actor blocks, in order to perform a conformity check with an interface type (#4324).

0.10.3

• motoko (moc)

  • Include doc comments to Candid interfaces generated via the --idl flag (#4334).

  • bugfix: fix broken implementations of Region.loadNat32, Region.storeNat32, Region.loadInt32, Region.storeInt32 (#4335).
    Values previously stored with the broken 32-bit operations must be loaded with care.
    If bit 0 is clear, the original value can be obtained by an arithmetic shift right by 1 bit.
    If bit 0 is set, the value cannot be trusted and should be ignored
    (it encodes some transient address of a boxed value).

• motoko-base

  • Added ExperimentalInternetComputer.performanceCounter function to get the raw performance
    counters (dfinity/motoko-base⁠#600).

  • Added Array.take function to get some prefix of an array (dfinity/motoko-base⁠#587).

  • Deprecated TrieSet.mem in favor of TrieSet.has (dfinity/motoko-base⁠#576).

  • bugfix: Array.chain(as, f) was incorrectly trapping when f(a) was an empty array
    (dfinity/motoko-base⁠#599).

0.10.2

• motoko (moc)

  • bugfix: separate tag from underscore in coverage warnings (#4274).

  • Code compiled for targets WASI (-wasi-system-api) and pure Wasm (-no-system-api) can now
    use up to 4GB of (efficiently emulated) stable memory, enabling more offline testing of, for example,
    stable data structures built using libraries Regions.mo and ExperimentalStableMemory.mo.
    Note that any Wasm engine (such as wasmtime), used to execute such binaries, must support and enable
    Wasm features multi-memory and bulk-memory (as well as the standard NaN canonicalization) (#4256).

  • bugfix: fully implement Region.loadXXX/storeXXX for Int8, Int16 and Float (#4270).

  • BREAKING CHANGE (Minor): values of type Principal are now constrained to contain
    at most 29 bytes, matching the IC's notion of principal (#4268).

    In particular:

    • An actor import will be statically rejected if the binary representation of the (aliased) textually encoded
      principal contains strictly more than 29 bytes.

    • Principal.fromBlob(b) will trap if b contains strictly more than 29 bytes.

    • The actor literal, actor <exp>, will trap if the binary representation of
      of the textually encoded principal <exp> contains strictly more than 29 bytes.

• motoko-base

  • bugfix: fix Array.tabulateVar to avoid repeated side-effects (dfinity/motoko-base⁠#596)