SIP-28: Background Events Source

Author Olaf Tomalka
Status Draft
Created 2024-10-09

Table of Contents

Abstract

This SIP introduces a way to schedule non-recurring events in the future.

Motivation

Scheduled recurring events are already supported in the Snaps platform via the Cronjobs feature. By introducing non-recurring events we will allow novel use-cases for Snap developers, such as allowing a snap that sets a reminder for ENS domain expiration date.

Specification

Indented sections like this are considered non-normative.

Language

The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “NOT RECOMMENDED”, “MAY”, and “OPTIONAL” written in uppercase in this document are to be interpreted as described in RFC 2119

Snap Manifest

This SIP doesn’t introduce any new permissions, but rather extends endowment:cronjob with new capabilities through two new RPC methods.

RPC Methods

snap_scheduleBackgroundEvent

This method allows a Snap to schedule a one-off callback to onCronjob handler in the future with a JSON-RPC request object as a parameter.

type ScheduleBackgroundEventParams = {
  date: string;
  request: JsonRpcRequest;
};

type ScheduleBackgroundEventResult = string;

The RPC method takes two parameters:

  • date - An ISO 8601 date and time and optional timezone offset.
    • The time’s precision SHALL be truncated on the extension side to minutes.
    • If no timezone is provided, the time SHALL be understood to be local-time.

      Use ISO’s Z identifier if you want to use UTC time.

  • request - A JSON object that will provided as-is to onCronjob handler as parameter.

An example of usage is given below.

snap.request({
  method: "snap_scheduleBackgroundEvent",
  params: {
    date: "2024-10-09T09:59",
    request: {
      method: "foobar",
      params: {
        foo: "bar",
      },
    },
  },
});

The RPC method call returns a string that is a unique ID representing that specific background event, allowing it to be cancelled.

snap_cancelBackgroundEvent

This method allows to cancel an already scheduled background event using the unique ID returned from snap_backgroundEventSchedule

type CancelBackgroundEventParams = { id: string };

This RPC method takes one argument:

  • id - The id that was returned during schedule.

An example of usage is given below.

snap.request({
  method: "snap_cancelBackgroundEvent",
  params: {
    id: myReturnedId,
  },
});

onCronjob handler

This SIP doesn’t modify onCronjob handler in any way.

Copyright and related rights waived via CC0.

Citation

Please cite this document as:

Olaf Tomalka, "SIP-28: Background Events [DRAFT]," Snaps Improvement Proposals, no. 28, October 2024. [Online serial]. Available: https://github.com/MetaMask/SIPs/blob/master/SIPS/sip-28.md