Skip to content

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

New issue
New issue
Open
Open
ICRC-121 - Wasm Orchestration Service Block Specification - ICRC3 Extension#121
@skilesare

Description

@skilesare
skilesare
opened on Mar 8, 2025
ICRC Title Author Discussions Status Type Category Created
121 Wasm Orchestration Service Block Specification - ICRC3 Extension Austin Fatheree (@skilesare) #121 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
  • restart: Text
    • true or false - indicates if the user wants a restart after the snapshot.
  • 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

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.
  • snapshot_id: 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.
  • snapshot_id: 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 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.
        • sys:wasm_meory_threshold: Optional - Nat
          • a safety threshold for canister when dealing with memory that will trigger a canister lifecycle hook.

    3-7. 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

    3-8. 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 by the user
    • status: Text
      • success, failed, timeout

3-9. 121snapshot

This block records the execution of a request to snapshot a canister.

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.
  • upgrade_block - optional - Nat
    • The identifier of the upgrade request block if this is being taken as part of an upgrade request
  • restart: Text - optional
    • true or false - indicates if the user wants a restart after the snapshot.

3-10. 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.
  • snapshot_block*: optional - Nat
    • Points to the snapshot block transaction if this occurs as part of a snapshot request
  • snapshot_id: optional - text
    • id of the snapshot produced by the attempt if 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"; }

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions