From d43335952fc428ee922609467617263593d35567 Mon Sep 17 00:00:00 2001 From: Olaf Tomalka Date: Wed, 9 Oct 2024 14:02:59 +0200 Subject: [PATCH 1/4] SIP-28: Background Events --- SIPS/sip-28.md | 97 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 97 insertions(+) create mode 100644 SIPS/sip-28.md diff --git a/SIPS/sip-28.md b/SIPS/sip-28.md new file mode 100644 index 00000000..176b6c9b --- /dev/null +++ b/SIPS/sip-28.md @@ -0,0 +1,97 @@ +--- +sip: 28 +title: Background Events +status: Draft +author: Olaf Tomalka (@ritave) +created: 2024-10-09 +--- + +## Abstract + +A few terse sentences that are a technical summary of the proposal. Someone should be able to read this paragraph and understand the gist of this SIP. + +## Motivation + +The "why" + +## Specification + +> Indented sections like this are considered non-normative. + +Formal specification of the proposed changes in the SIP. The specification must be complete enough that an implementation can be created from it. + +### 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](https://www.ietf.org/rfc/rfc2119.txt) + +### Snap Manifest + +This SIP introduces a new permission `endowment:background-event`. This permissions grants a Snap the ability to schedule future events. + +This permission takes no parameters and is specified in the `snap.manifest.json` as follows: + +```json +{ + "initialPermissions": { + "endowment:background-event": {} + } +} +``` + +### RPC Methods + +#### `snap_backgroundEventSchedule` + +This method allows a Snap to schedule a callback to `onBackgroundEvent` handler in the future with a JSON-RPC request object as a parameter. + +The RPC method takes two parameters: + +- `date` - An [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) date and time and optional timezone offset. + - The time's precision SHALL be truncated on the extension side to minutes. +- `request` - A JSON object that will provided as-is to `onBackgroundEvent` handler as parameter. + +```typescript +snap.request({ + method: "snap_backgroundEventSchedule", + 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_backgroundEventCancel` + +This method allows to cancel an already scheduled background event using the unique ID returned from `snap_backgroundEventSchedule` + +This RPC method takes one argument: + +- `id` - The id that was returned during schedule. + +```typescript +snap.request({ + method: "snap_backgroundEventCancel", + params: { + id: myReturnedId, + }, +}); +``` + +### `onBackgroundEvent` handler + +This SIP introduced a new handler called `onBackgroundEvent` which is called when a scheduled background event occurs. + +It has one parameter - `request`, that is provided without change. + +## Copyright + +Copyright and related rights waived via [CC0](../LICENSE). From c9e4a79260c7489d702c516693d9dc77a8d48507 Mon Sep 17 00:00:00 2001 From: Olaf Tomalka Date: Wed, 9 Oct 2024 15:04:38 +0200 Subject: [PATCH 2/4] Changes after code-review --- SIPS/sip-28.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/SIPS/sip-28.md b/SIPS/sip-28.md index 176b6c9b..cc914d53 100644 --- a/SIPS/sip-28.md +++ b/SIPS/sip-28.md @@ -8,18 +8,16 @@ created: 2024-10-09 ## Abstract -A few terse sentences that are a technical summary of the proposal. Someone should be able to read this paragraph and understand the gist of this SIP. +This SIP introduces a way the schedule non-recurring events in the future. ## Motivation -The "why" +Scheduled recurring events are already support in Snaps through Cronjobs feature. Introducing non-recurring events we 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. -Formal specification of the proposed changes in the SIP. The specification must be complete enough that an implementation can be created from it. - ### Language The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", @@ -28,21 +26,21 @@ The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", ### Snap Manifest -This SIP introduces a new permission `endowment:background-event`. This permissions grants a Snap the ability to schedule future events. +This SIP introduces a new permission `endowment:background-events`. This permissions grants a Snap the ability to schedule future events. This permission takes no parameters and is specified in the `snap.manifest.json` as follows: ```json { "initialPermissions": { - "endowment:background-event": {} + "endowment:background-events": {} } } ``` ### RPC Methods -#### `snap_backgroundEventSchedule` +#### `snap_scheduleBackgroundEvent` This method allows a Snap to schedule a callback to `onBackgroundEvent` handler in the future with a JSON-RPC request object as a parameter. @@ -50,6 +48,8 @@ The RPC method takes two parameters: - `date` - An [ISO 8601](https://en.wikipedia.org/wiki/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 `onBackgroundEvent` handler as parameter. ```typescript @@ -69,7 +69,7 @@ snap.request({ The RPC method call returns a `string` that is a unique ID representing that specific background event, allowing it to be cancelled. -#### `snap_backgroundEventCancel` +#### `snap_cancelBackgroundEvent` This method allows to cancel an already scheduled background event using the unique ID returned from `snap_backgroundEventSchedule` @@ -90,7 +90,7 @@ snap.request({ This SIP introduced a new handler called `onBackgroundEvent` which is called when a scheduled background event occurs. -It has one parameter - `request`, that is provided without change. +It has one parameter - `request`, which SHALL be provided without change from the one given as a parameter to `snap_scheduleBackgroundEvent`. ## Copyright From 0e02c96ca2528c8fbf8c8addd4c4b54cb783eaec Mon Sep 17 00:00:00 2001 From: Olaf Tomalka Date: Fri, 11 Oct 2024 11:07:23 +0200 Subject: [PATCH 3/4] Changes after code-review --- SIPS/sip-28.md | 31 +++++++++++++++++++++++++------ 1 file changed, 25 insertions(+), 6 deletions(-) diff --git a/SIPS/sip-28.md b/SIPS/sip-28.md index cc914d53..d4e796d7 100644 --- a/SIPS/sip-28.md +++ b/SIPS/sip-28.md @@ -8,11 +8,11 @@ created: 2024-10-09 ## Abstract -This SIP introduces a way the schedule non-recurring events in the future. +This SIP introduces a way to schedule non-recurring events in the future. ## Motivation -Scheduled recurring events are already support in Snaps through Cronjobs feature. Introducing non-recurring events we allow novel use-cases for Snap developers, such as allowing a snap that sets a reminder for ENS domain expiration date. +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 @@ -26,7 +26,7 @@ The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", ### Snap Manifest -This SIP introduces a new permission `endowment:background-events`. This permissions grants a Snap the ability to schedule future events. +This SIP introduces a new permission `endowment:background-events`. This permission grants a Snap the ability to schedule future events. This permission takes no parameters and is specified in the `snap.manifest.json` as follows: @@ -44,6 +44,13 @@ This permission takes no parameters and is specified in the `snap.manifest.json` This method allows a Snap to schedule a callback to `onBackgroundEvent` handler in the future with a JSON-RPC request object as a parameter. +```typescript +type ScheduleBackgroundEventParams = { + date: string; + request: Json; +}; +``` + The RPC method takes two parameters: - `date` - An [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) date and time and optional timezone offset. @@ -52,9 +59,11 @@ The RPC method takes two parameters: > Use ISO's `Z` identifier if you want to use UTC time. - `request` - A JSON object that will provided as-is to `onBackgroundEvent` handler as parameter. +An example of usage is given below. + ```typescript snap.request({ - method: "snap_backgroundEventSchedule", + method: "snap_scheduleBackgroundEvent", params: { date: "2024-10-09T09:59", request: { @@ -73,13 +82,19 @@ The RPC method call returns a `string` that is a unique ID representing that spe This method allows to cancel an already scheduled background event using the unique ID returned from `snap_backgroundEventSchedule` +```typescript +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. + ```typescript snap.request({ - method: "snap_backgroundEventCancel", + method: "snap_cancelBackgroundEvent", params: { id: myReturnedId, }, @@ -88,7 +103,11 @@ snap.request({ ### `onBackgroundEvent` handler -This SIP introduced a new handler called `onBackgroundEvent` which is called when a scheduled background event occurs. +This SIP introduces a new handler called `onBackgroundEvent` which is called when a scheduled background event occurs. + +```typescript +type OnBackgroundEventHandler = (args: { request: Json }) => Promise; +``` It has one parameter - `request`, which SHALL be provided without change from the one given as a parameter to `snap_scheduleBackgroundEvent`. From cd5ce6a62b15a825ab2443b71925891591e0916a Mon Sep 17 00:00:00 2001 From: Olaf Tomalka Date: Fri, 11 Oct 2024 11:17:43 +0200 Subject: [PATCH 4/4] Merged endowment:background-events and endowment:cronjob --- SIPS/sip-28.md | 30 ++++++++---------------------- 1 file changed, 8 insertions(+), 22 deletions(-) diff --git a/SIPS/sip-28.md b/SIPS/sip-28.md index d4e796d7..32670b79 100644 --- a/SIPS/sip-28.md +++ b/SIPS/sip-28.md @@ -26,29 +26,21 @@ The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", ### Snap Manifest -This SIP introduces a new permission `endowment:background-events`. This permission grants a Snap the ability to schedule future events. - -This permission takes no parameters and is specified in the `snap.manifest.json` as follows: - -```json -{ - "initialPermissions": { - "endowment:background-events": {} - } -} -``` +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 callback to `onBackgroundEvent` handler in the future with a JSON-RPC request object as a parameter. +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. ```typescript type ScheduleBackgroundEventParams = { date: string; - request: Json; + request: JsonRpcRequest; }; + +type ScheduleBackgroundEventResult = string; ``` The RPC method takes two parameters: @@ -57,7 +49,7 @@ The RPC method takes two parameters: - 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 `onBackgroundEvent` handler as parameter. +- `request` - A JSON object that will provided as-is to `onCronjob` handler as parameter. An example of usage is given below. @@ -101,15 +93,9 @@ snap.request({ }); ``` -### `onBackgroundEvent` handler - -This SIP introduces a new handler called `onBackgroundEvent` which is called when a scheduled background event occurs. - -```typescript -type OnBackgroundEventHandler = (args: { request: Json }) => Promise; -``` +### `onCronjob` handler -It has one parameter - `request`, which SHALL be provided without change from the one given as a parameter to `snap_scheduleBackgroundEvent`. +This SIP doesn't modify `onCronjob` handler in any way. ## Copyright