ICRC-121 – Wasm Orchestration Service Block Specification

Developers
1

Introducing ICRC-121 – Wasm Orchestration Service Block Specification

image
image1024×1024 146 KB

I’m happy to present the first draft of ICRC-121, a specification that extends the ICRC-3 ledger to incorporate comprehensive logging for Wasm orchestration. This new standard is designed to bring transparency and auditability to the orchestration of canister deployments on the Internet Computer.

Key Highlights of ICRC-121

  • Detailed Upgrade Logging:
    ICRC-121 introduces the 121upgrade_to block, which allows operators to record detailed parameters for each upgrade or installation event. This includes caller identity, target canister information, installation arguments, the requested Wasm hash, and optional snapshot/stop flags.

  • Completion and Outcome Tracking:
    The 121upgrade_finished block captures the full lifecycle of an upgrade—from initiation to final outcome. This enables participants to review whether an upgrade succeeded, failed, or timed out, along with any associated error messages.

  • Snapshot and Revert Management:
    Supporting robust recovery processes, ICRC-121 includes dedicated blocks for snapshot creation (121snapshot_finished) and revert operations (121revert_snapshot and 121revert_result). These blocks ensure that canister state recovery is both verifiable and transparent.

  • Configuration and Lifecycle Events:
    Beyond upgrades, ICRC-121 records key lifecycle events such as configuration changes (121config), as well as start and stop operations for canisters (121start and 121stop).

Why ICRC-121 Matters

ICRC-121 is not merely a set of technical definitions—it represents a crucial step forward in standardizing canister orchestration on the Internet Computer. By providing clear and immutable records for every deployment, upgrade, rollback, and configuration change, the specification achieves:

  • Enhanced Auditability and Compliance:
    Every change is traced and verifiable, ensuring a robust audit trail.

  • Operational Integrity:
    A deterministic sequence of recorded events supports effective troubleshooting and thorough post-deployment analysis.

  • Forward Compatibility:
    Flexible and extensible block schemas ensure that the standard can adapt to evolving canister management needs.

A Call to the Community

We invite developers, operators, and stakeholders across the Internet Computer ecosystem to review and adopt ICRC-121. This standard lays the foundation for improved canister management, contributing to greater system integrity and user trust.

ICRC Title Author Discussions Status Type Category Created
121 Wasm Orchestration Service Block Specification - ICRC3 Extension Austin Fatheree (@skilesare) ICRC-121 - Wasm Orchestration Service Block Specification - ICRC3 Extension · Issue #121 · dfinity/ICRC · GitHub Draft Standards Track 2025-03-18

ICRC-121: Wasm Orchestration Service Block Specification - ICRC3 Extension

1. Scope

This document defines the block types and associated fields for recording critical events in the orchestration of wasm installation, upgrade, rollback, and configuration as defined in ICRC-120. It is intended to ensure a deterministic recording of configuration changes and deployments, along with proper auditability of recorded events.

The ICRC-121 specification extends ICRC-3 by introducing a set of detailed block definitions that record relevant events for wasm orchestration.

The ICRC-121 specification covers:

  • Audit Logging with ICRC-3 Blocks:
    Detailed recording of each orchestration step via immutable logs.

2. Terminology and Definitions

  • Wasm Module:
    A binary executable module deployed as part of a canister.

  • Canister Upgrade:
    The process of replacing a canister’s executable code with a new version while preserving state.

  • Snapshot:
    A stored state of a canister taken prior to a code upgrade, used for reverting in case of upgrade failures.

  • ICRC-3 Block:
    A log entry recorded on the ICRC-3 ledger capturing metadata associated with operations (e.g., upgrades, rollbacks).

  • Orchestration Function:
    A method used to manage and coordinate the lifecycle of a canister upgrade.

3. ICRC-3 Block Schemas

ICRC-121 blocks consist of the following top level fields as defined in ICRC-3

  • btype - Identifies the block type
  • ts - Timestamp of the block.
  • tx - Transaction details. See bellow for definitions.

3-1. 121upgrade_to

This block records the execution of a request to install or upgrade a canister to a particular wasm instance. Note: As the configuration of canisters on the Internet Computer changes over time, these values may change or be added to. Any tool that consumes the 121upgrade_to block should handle unknown configuration values gracefully without failing.

tx Fields:

  • caller: Principal
    • The unique identifier of the caller invoking the configuration change. Principals are represented as a Blob of the raw principal.
  • canisterId: Principal
    • The identifier of the canister being installed to. Principals are represented as a Blob of the raw principal.
  • args: Blob
    • The install args to pass to the management canister when the item is installed or upgraded.
  • mode: Text - install or upgrade
  • targetHash: Blob
    • The hash of the wasm that is requested for the operation
  • snapshot: - Optional - Nat
    • 1 Indicated a request to take a snapshot before upgrading
  • stop: - Optional - Nat
    • 1Indicated a request to stop the canister before upgrading
  • parameters: Optional - Map
    • Optional Values passed in the request to be used throughout the process
      • controllers: Optional - Array of Principal
      • The list of controllers of the canister. Principals are represented as Blobs of the raw principal
      • compute_allocation: Optional - Nat
        • Amount of compute that the canister has allocated.
      • memory_allocation: Optional - Nat
        • Amount of memory (storage) that the canister has allocated.
      • freezing_threshold: Optional - Nat
        • A safety threshold to prevent the canister from running out of cycles and avoid being deleted.
      • reserved_cycles_limit: Optional - Nat
        • A safety threshold to protect against spending too many cycles for resource reservation.
      • wasm_memory_limit: Optional - Nat
        • A safety threshold to protect against reaching the 4GiB hard limit of 32-bit Wasm memory.
      • log_visibility: Optional - Text
        • controllers or public. Controls who can read the canister logs.

3-2. Upgrade Finished Block Schema (121upgrade_finished)

This block records the recognition that an upgrade or install process has completed.

tx Fields:

  • canisterId: Principal
    • The identifier of the canister being installed to. Principals are represented as a Blob of the raw principal.
  • upgrade_block: Nat
    • Points to the upgrade_to block transaction.
  • status: text
    • success, failed, timeout
  • error: optional Text
    • Error if one was reported by the 120_upgrade_finished function
  • restart - optional - Nat
    -1 indicates that the canister was restarted.

3-3. Clean Snapshot Block Schema (121clean_snapshot)

This block records the recognition that a snapshot has been cleaned from the replica.

tx Fields:

  • canisterId: Principal
    • The identifier of the canister being installed to. Principals are represented as a Blob of the raw principal.
  • callerId: Principal
    • The identifier of the caller initiating the clean. Principals are represented as a Blob of the raw principal.
  • snapshotKey: Text
    • The identifier of the snapshot to clean.

3-4. Revert Snapshot Block Schema (121revert_snapshot)

This block records the recognition that a snapshot has been cleaned from the replica.

tx Fields:

  • canisterId: Principal
    • The identifier of the canister being installed to. Principals are represented as a Blob of the raw principal.
  • callerId: Principal
    • The identifier of the caller initiating the clean. Principals are represented as a Blob of the raw principal.
  • snapshotId: Text
    • The identifier of the snapshot to clean.
  • restart: Text
    • true or false - indicates if the user wants a restart after the snapshot.

3-5. Revert Result Block Schema (121revert_result)

This block records the result of snapshot revert request.

tx Fields:

  • canisterId: Principal
    • The identifier of the canister being installed to. Principals are represented as a Blob of the raw principal.
  • result: Text
    • success, failed, timeout
  • error : Optional - Text
    • Error Text if necessary/available
  • snapshotBlock: Nat
    • The identifier of the block where the revert was requested.

3-6. Snapshot Finished Block Schema (121snapshot_finished)

This block records the recognition that a snapshot has completed.

tx Fields:

  • canisterId: Principal

    • The identifier of the canister being installed to. Principals are represented as a Blob of the raw principal.

  • upgrade_block: optional - Nat

    • Points to the upgrade_to block transaction.

  • restart: optional - Nat

    • 1 if the canister was restarted.

  • status: text

    • success, failed, timeout

  • error : Optional - Text

    • Error Text if necessary/available

  • snapshot_id: optional - text

    • id of the snapshot produced by the attempt if available

    3-7. Configuration Update Block Schema (121config)

    This block records the configuration updates provided in an icrc120_config_canister request.

    tx Fields:

    • caller: Principal
      • The unique identifier of the caller invoking the configuration change. Principals are represented as a Blob of the raw principal.
    • canisterId: Principal
      • The identifier of the canister being configured. Principals are represented as a Blob of the raw principal.
    • configs: Map
      • A map of configuration key-value pairs.
        • sys:controllers: Optional - Array of Principal
          • The list of controllers of the canister. Principals are represented as Blobs of the raw principal.
        • sys:compute_allocation: Optional - Nat
          • Amount of compute that the canister has allocated.
        • sys:memory_allocation: Optional - Nat
          • Amount of memory (storage) that the canister has allocated.
        • sys:freezing_threshold: Optional - Nat
          • A safety threshold to prevent the canister from running out of cycles and avoid being deleted.
        • sys:reserved_cycles_limit: Optional - Nat
          • A safety threshold to protect against spending too many cycles for resource reservation.
        • sys:wasm_memory_limit: Optional - Nat
          • A safety threshold to protect against reaching the 4GiB hard limit of 32-bit Wasm memory.
        • sys:log_visibility: Optional - Text
          • controllers or public. Controls who can read the canister logs.

    3-8. Start Canister Block Schema (121start)

    This block records the recognition that a canister has been started.

    tx Fields:

    • canisterId: Principal
      • The identifier of the canister being started. Principals are represented as a Blob of the raw principal.
    • callerId: Principal
      • The identifier of the caller initiating the start. Principals are represented as a Blob of the raw principal.
    • timeout: Nat - timeout requested by the user.
    • status: Text
      • success, failed, timeout
    • error: Optional - Text
      • Error Text if necessary/available

    3-9. Stop Canister Block Schema (121stop)

    This block records the recognition that a canister has been stopped.

    tx Fields:

    • canisterId: Principal
      • The identifier of the canister being stopped. Principals are represented as a Blob of the raw principal.
    • callerId: Principal
      • The identifier of the caller initiating the stop. Principals are represented as a Blob of the raw principal.
    • timeout - Nat - timeout provided byt he user
    • status: Text
      • success, failed, timeout
    • error: Optional - Text
      • Error Text if necessary/available

4. Implementation Considerations

  • Event Ordering: Ensure that entries are recorded in the exact order of operations to maintain a reliable historical ledger. For new ledgers, and where possible, the first record in the ICRC-3 log SHOULD BE the initial wasm installation. Other events should not occur until after this block has been recorded with confirmed wasm hashs, canisterId, and subnet information. For in flight, ledgers it should be appended to the log in the next upgrade.

  • Replica Events: Because changes to the canister at the replica level do not currently produce a lifecycle event inside the canister, the canister should periodically capture any changes to these items and record them in a timely manner. They should be recorded as configuration changes with the method name “sys:replica”.

//todo: define sys names

5. References

ICRC-3

An implementation of ICRC-119 Registry MUST also support the methods and standards defined in ICRC-3

ICRC-10

An implementation of ICRC-119 Registry MUST also support the method icrc10_supported_standards (per ICRC-10), and include the following entries in its response:

  record { name = "ICRC-3"; url = "https://github.com/dfinity/ICRC-1/tree/main/standards/ICRC-3"; }
  record { name = "ICRC-10"; url = "https://github.com/dfinity/ICRC/ICRCs/ICRC-10"; }
  record { name = "ICRC-121"; url = "https://github.com/dfinity/ICRC/ICRCs/ICRC-121"; }