Internet Computer Association

DFINITY Foundation

Synapse.vote (formerly ICP Maximalist Network)

Arthur’s Neuron (used to be cycle_dao)

ICDevs.org

CryptoIsGood

Anvil

ICPL.app

The Fools' Court

ysyms

The Accumulators’ Neuron

RawTech Venture

Paul Young

ICPMANUAL

8yeargangDAO

John Wiegley

Isaac Valadez

Krzysztof Żelazko

Always Rejects

Nicolas.ic



# Summary

Heartbeat is a mechanism for canisters to perform periodic tasks on the Internet Computer. If a canister exports the `canister_heartbeat` WASM method, then this method will be invoked in roughly every round (the actual schedule depends on the subnet load).

The main drawback of the existing heartbeat design is that it is impossible to configure the frequency or disable the heartbeat. This "all or nothing" design wastes resources and cycles.

The goal of this proposal is to provide a way to run any number of periodic tasks with configurable frequency using a high-level timer library implemented in Motoko and Rust. The design has been proposed and discussed on the forum: https://forum.dfinity.org/t/heartbeat-improvements-timers-community-consideration/14201

# Proposed Design

We propose to add a global timer functionality to the Internet Computer. This timer will be separate from the existing heartbeat functionality, which will continue to be supported, but canisters can easily migrate to use the more flexible timer instead of the existing heartbeat.

# Proposed changes in the Internet Computer

1. Add a new System API `ic0.global_timer_set(time: i64) -> i64` function.
2. The function schedules a call to the exported "canister_global_timer" Wasm method in some round after the specified time.
3. The function returns the previous value of the timer.

# Proposed changes in Motoko/Rust CDK

Add a timer library with the following interface:

1. `timer_id = set_timer(delay, fun)` – one-off execution of the fun after a minimum delay in seconds.
2. `timer_id = set_timer_interval(delay, fun)` – periodic execution of the fun with a minimum delay in seconds.
3. `clear_timer(timer_id)` – clear the previously set one-off or periodic timer_id.

Note: the API is in pseudocode, and will be adapted to the Motoko/Rust style.

# Implementation Details

1. The "canister_global_timer" will be called with the `Heartbeat` SystemAPI type, so the same restrictions apply as for the heartbeats.

2. The timer will be canceled during the upgrade, so the canister is expected to serialize the state of its timers and later restore it and set the timers in the "canister_post_upgrade".

# Alternatives

A few alternatives were considered:

1. Heartbeat interval: allows canisters to change their heartbeat interval run time. Conceptually very similar solution to timers, but might be confusing for the existing users of the heartbeats.
2. Multiple timers: the IC is to provide an interface similar to JS setTimeout/setInterval. A complete solution for Rust, but seems like much more work for Motoko team.
3. Call-based timers: canisters call a management canister and receive a reject after a delay. The timers might be awaitable like normal calls, but the pending calls prevent canisters from being upgraded until there are no more pending timers.

# Key Teams Involved

Runtime, Language and SDK teams will be involved in this implementation.



Motion to introduce canister timers