For AI agents: Documentation index at /llms.txt

Skip to content
docs.internetcomputer.org

Motoko

Motoko is a next-generation, high-level programming language designed to empower AI agents building backends for apps and services on the Internet Computer cloud network. While it channels several popular modern languages, it introduces groundbreaking new features such as actor-based concurrency, orthogonal persistence, and seamless WebAssembly integration.

Key features

Section titled “Key features”

Actor model. Every Motoko canister is an actor — an isolated unit of state and behavior that communicates with other actors through asynchronous messages. This maps directly to how canisters work on ICP: each canister has private state and a public interface.

Orthogonal persistence. Variables declared in a persistent actor survive canister upgrades automatically. There is no database layer, no serialization code, and no pre/post-upgrade hooks needed for most use cases. See Orthogonal persistence for how this works at the platform level.

Async/await messaging. Inter-canister calls use async/await, making sequential message flows read like synchronous code. The compiler and runtime handle the underlying callback mechanics.

Strong typing. Motoko has a sound type system with generics, variant types, pattern matching, and option types (?T) that prevent null-pointer errors at compile time.

WebAssembly compilation. Motoko compiles to Wasm, the execution format for all ICP canisters. The compiler handles ICP-specific concerns (Candid serialization, system API bindings, memory management) so you don’t have to.

Quick example

Section titled “Quick example”

A minimal Motoko canister with a query method and an update method:

persistent actor Counter {
  var count : Nat = 0;


  public query func get() : async Nat {
    return count;
  };


  public func increment() : async () {
    count += 1;
  };
};

The persistent actor declaration means count survives canister upgrades. The query keyword marks get as a fast, read-only call. The increment function is an update call that modifies state and goes through consensus.

Getting started

Section titled “Getting started”

Create a new Motoko project with icp-cli:

Terminal window
icp new my-project --subfolder motoko

This generates a Motoko canister project with an icp.yaml build configuration and a source file. The build configuration uses the Motoko recipe:

canisters:
  - name: backend
    recipe:
      type: "@dfinity/motoko@<version>"
      configuration:
        main: src/main.mo
        shrink: true

Start a local network and deploy:

Terminal window
icp network start -d
icp deploy

For a guided walkthrough, see the Quickstart.

Standard library: core

Section titled “Standard library: core”

The core package (mops.one/core) is the standard library for Motoko. It supersedes the older base library with a cleaner API, consistent naming conventions, and data structures that work directly with stable memory.

Add it to your project’s mops.toml:

[dependencies]
core = "2.2.0" # Check the latest version at https://mops.one/core


[toolchain]
moc = "1.3.0" # Check the latest version at https://github.com/caffeinelabs/motoko/releases

Then import modules:

import Map "mo:core/Map";
import Text "mo:core/Text";
import List "mo:core/List";

Key improvements in core over base:

  • All data structures can be stored in stable memory without pre/post-upgrade hooks
  • Clear separation between mutable (Map, Set, List) and immutable (pure/Map, pure/Set, pure/List) data structures
  • Hash-based collections removed in favor of ordered maps and sets (better security against collision attacks)
  • Consistent naming: values() instead of vals(), Cycles instead of ExperimentalCycles

If you have an existing project using base, you can migrate incrementally; both libraries can coexist in the same project. See the base to core migration guide for detailed instructions.

core and all other Motoko packages are managed with Mops, which handles dependency resolution, compiler toolchain management, and publishing. Browse community packages at mops.one.

Further reading

Section titled “Further reading”