From 28ef967c0a75918854ac659c9d4d8912ccb3e58f Mon Sep 17 00:00:00 2001 From: kubel Date: Thu, 28 Sep 2023 14:07:06 +0200 Subject: [PATCH 01/27] Add decry[ted notifications spec --- .../web3wallet/decrypted-norifications.md | 31 +++++++++++++++++++ docs/specs/meta-clients/web3wallet/sdk-api.md | 2 +- docs/specs/servers/push/spec.md | 6 +++- 3 files changed, 37 insertions(+), 2 deletions(-) create mode 100644 docs/specs/meta-clients/web3wallet/decrypted-norifications.md diff --git a/docs/specs/meta-clients/web3wallet/decrypted-norifications.md b/docs/specs/meta-clients/web3wallet/decrypted-norifications.md new file mode 100644 index 00000000..49d045ce --- /dev/null +++ b/docs/specs/meta-clients/web3wallet/decrypted-norifications.md @@ -0,0 +1,31 @@ +# Decrypted Notification + +The below class introduces the general way of handling decprytped notifications received by a wallet. The implementation details differs on each platform. + +```typescript + +abstract class DecryptedNotification { + //decrypt encrypted request + public decryptMessage(params: { topic: string, encryptedMessage: string }): Promise; + + //get notification metadata for a given request + public getNotificationMetadata(params: { topic: string, message: Message }): Promise; +} + + //Message + { + "id": string, + "jsonrpc": string, + "method": string, + "params": string, //Sign(proposal, request) params, Auth request params, Notify params + } + + //Notification + { + "title": string, + "body": string, + "icon": string, + "url": string, + "type": string, + } +``` \ No newline at end of file diff --git a/docs/specs/meta-clients/web3wallet/sdk-api.md b/docs/specs/meta-clients/web3wallet/sdk-api.md index 3c3328a1..c3ec9882 100644 --- a/docs/specs/meta-clients/web3wallet/sdk-api.md +++ b/docs/specs/meta-clients/web3wallet/sdk-api.md @@ -71,7 +71,7 @@ class Web3Wallet { public abstract getPendingAuthRequests(): Promise>; // register device token for Push server (BOTH) - public abstract registerDeviceToken(token: string): Promise; + public abstract registerDeviceToken(token: string, isDecrypted: boolean?): Promise; // ---------- Events ----------------------------------------------- // diff --git a/docs/specs/servers/push/spec.md b/docs/specs/servers/push/spec.md index 6dd03d24..cefb52df 100644 --- a/docs/specs/servers/push/spec.md +++ b/docs/specs/servers/push/spec.md @@ -61,7 +61,8 @@ POST /clients { "client_id": , "type": , - "token": + "token": , + "is_decrypted": //optional } ``` @@ -69,6 +70,7 @@ POST /clients - `TYPE`: The push service to use e.g. APNS, FCM. This will be validated against the supported types on the Push Server's side. - `DEVICE_TOKEN`: The device's token for the push service e.g. FCM, APNS. +- `IS_DECRYPTED`: Defines when to send non-encrypted or encrypted content(Encrypted_Sign, Encrypted_Auth) ### Unregister Client @@ -102,5 +104,7 @@ POST /clients/ Auth = 1 << 2 Chat = 1 << 3 Notify = 1 << 4 + Encrypted_Sign = 1100 / 1108 (session_propose / session_request) + Encrypted_Auth = 3000 (auth_request) ``` - `blob`: If the payload is encrypted this is just the encrypted blob, when this is cleartext it should be base64 encoded. The blob should follow the format from of the [Notify Message](https://specs.walletconnect.com/2.0/specs/clients/notify/data-structures#notify-message) From 868815b7a2c1340ebd6a3087c127dbd10ea7b600 Mon Sep 17 00:00:00 2001 From: Chris Smith Date: Thu, 28 Sep 2023 11:35:10 -0400 Subject: [PATCH 02/27] chore: improve decrypted notifications specs --- docs/specs/servers/push/spec.md | 104 ++++++++++++++++++++------------ 1 file changed, 64 insertions(+), 40 deletions(-) diff --git a/docs/specs/servers/push/spec.md b/docs/specs/servers/push/spec.md index cefb52df..09abac44 100644 --- a/docs/specs/servers/push/spec.md +++ b/docs/specs/servers/push/spec.md @@ -15,7 +15,7 @@ These are the default responses and are only different if otherwise specified. ``` { - "status": "OK" + "status": "OK" } ``` @@ -23,13 +23,13 @@ These are the default responses and are only different if otherwise specified. ``` { - "status": "FAILED", - "errors": [ - { "name": "", description": "" } - ] - "fields": [ - { "field": "type", "description": "", "location": "" } - ] + "status": "FAILED", + "errors": [ + { "name": "", description": "" } + ] + "fields": [ + { "field": "type", "description": "", "location": "" } + ] } ``` @@ -58,19 +58,28 @@ OK, push-server v0.1.0 ``` POST /clients +``` + +Request body: +```typescript { - "client_id": , - "type": , - "token": , - "is_decrypted": //optional + // The Client's ID from the Relay pairing. + client_id: string, + + // The push service to use. + type: "apns" | "apns-sandbox" | "fcm" | "noop", + + // The device's token for the push service. + token: string, + + // See below + enable_raw?: boolean, } ``` -- `CLIENT_ID`: The Client's ID from the Relay pairing. -- `TYPE`: The push service to use e.g. APNS, FCM. This will be validated against the supported types on the Push - Server's side. -- `DEVICE_TOKEN`: The device's token for the push service e.g. FCM, APNS. -- `IS_DECRYPTED`: Defines when to send non-encrypted or encrypted content(Encrypted_Sign, Encrypted_Auth) +- `enable_raw` - enables sending of raw notifications + - When this is set to `true`, the pushed notification will always be the value from `payload.raw` from Send Notifications below. + - When this is set to `false` or not present, the legacy behavior of conditionally sending (depending on `payload.flags`) encrypted or cleartext push notifications from `payload.blob` is used. ### Unregister Client @@ -84,27 +93,42 @@ DELETE /clients/ ``` POST /clients/ +``` + +- `CLIENT_ID` - This is used to map to the device token + +Headers: +- `X-Ed25519-Timestamp` - timestamp of the signature +- `X-Ed25519-Signature` - hex encoded ed25519 signature of `format!("{}.{}.{}", timestamp, body.len(), body)` where `body` is the request body + +Request body: +```typescript { - "id": "0000-0000-0000-0000" - "payload": { - "topic": "", - "flags": , - "blob": "" - } -``` - -- `CLIENT_ID`: This is used to map to the device token -- `id`: This is generated by the Relay to prevent duplicate notifications -- `payload`: A string with 3 values encoded and split with a `:` as a delimiter. - - `topic`: This is used by the SDKs to decrypt encrypted payloads on the client side - - `flags`: an integer value that uses bitmasks to encode information about the payload for the SDKs, the flags are below - ``` - Encrypted = 1 << 0 - Sign = 1 << 1 - Auth = 1 << 2 - Chat = 1 << 3 - Notify = 1 << 4 - Encrypted_Sign = 1100 / 1108 (session_propose / session_request) - Encrypted_Auth = 3000 (auth_request) - ``` - - `blob`: If the payload is encrypted this is just the encrypted blob, when this is cleartext it should be base64 encoded. The blob should follow the format from of the [Notify Message](https://specs.walletconnect.com/2.0/specs/clients/notify/data-structures#notify-message) + // Message ID for deduplication purposes + // Note: When `payload.raw` is set, `sha264(payload.raw)` should be used as the Message ID instead + id: string, + + payload: { + // Topic of the message. This is used by the SDKs to decrypt encrypted payloads on the client side + topic: string, + + // Raw message sent on the topic + raw: string, + + // See below + flags: number, + + // See below + blob: string, + } +``` + +- `flags`: an integer value that uses bitmasks to encode information about the payload for the SDKs, the flags are below + ``` + Encrypted = 1 << 0 + Sign = 1 << 1 + Auth = 1 << 2 + Chat = 1 << 3 + Notify = 1 << 4 + ``` +- `blob`: If the payload is encrypted this is just the encrypted blob, when this is cleartext it should be base64 encoded. The blob should follow the format from of the [Notify Message](https://specs.walletconnect.com/2.0/specs/clients/notify/data-structures#notify-message) From 6ccf212636039a07daf0041fa2ac8184bfd7fe90 Mon Sep 17 00:00:00 2001 From: Chris Smith Date: Thu, 28 Sep 2023 11:40:01 -0400 Subject: [PATCH 03/27] chore: always_encrypted --- docs/specs/meta-clients/web3wallet/sdk-api.md | 2 +- docs/specs/servers/push/spec.md | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/specs/meta-clients/web3wallet/sdk-api.md b/docs/specs/meta-clients/web3wallet/sdk-api.md index c3ec9882..92e2f0a1 100644 --- a/docs/specs/meta-clients/web3wallet/sdk-api.md +++ b/docs/specs/meta-clients/web3wallet/sdk-api.md @@ -71,7 +71,7 @@ class Web3Wallet { public abstract getPendingAuthRequests(): Promise>; // register device token for Push server (BOTH) - public abstract registerDeviceToken(token: string, isDecrypted: boolean?): Promise; + public abstract registerDeviceToken(token: string, alwaysEncrypted: boolean?): Promise; // ---------- Events ----------------------------------------------- // diff --git a/docs/specs/servers/push/spec.md b/docs/specs/servers/push/spec.md index 09abac44..4e4ecbe4 100644 --- a/docs/specs/servers/push/spec.md +++ b/docs/specs/servers/push/spec.md @@ -73,11 +73,11 @@ Request body: token: string, // See below - enable_raw?: boolean, + always_encrypted?: boolean, } ``` -- `enable_raw` - enables sending of raw notifications +- `always_encrypted` - enables always sending of raw encrypted notifications - When this is set to `true`, the pushed notification will always be the value from `payload.raw` from Send Notifications below. - When this is set to `false` or not present, the legacy behavior of conditionally sending (depending on `payload.flags`) encrypted or cleartext push notifications from `payload.blob` is used. From 860aacbfe993ac509a80f8d1407f177857fe01a5 Mon Sep 17 00:00:00 2001 From: Chris Smith Date: Thu, 28 Sep 2023 11:44:20 -0400 Subject: [PATCH 04/27] chore: update names --- docs/specs/meta-clients/web3wallet/sdk-api.md | 2 +- docs/specs/servers/push/spec.md | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/specs/meta-clients/web3wallet/sdk-api.md b/docs/specs/meta-clients/web3wallet/sdk-api.md index 92e2f0a1..c1611ea7 100644 --- a/docs/specs/meta-clients/web3wallet/sdk-api.md +++ b/docs/specs/meta-clients/web3wallet/sdk-api.md @@ -71,7 +71,7 @@ class Web3Wallet { public abstract getPendingAuthRequests(): Promise>; // register device token for Push server (BOTH) - public abstract registerDeviceToken(token: string, alwaysEncrypted: boolean?): Promise; + public abstract registerDeviceToken(token: string, enableAlwaysEncrypted: boolean?): Promise; // ---------- Events ----------------------------------------------- // diff --git a/docs/specs/servers/push/spec.md b/docs/specs/servers/push/spec.md index 4e4ecbe4..766d4f3a 100644 --- a/docs/specs/servers/push/spec.md +++ b/docs/specs/servers/push/spec.md @@ -73,11 +73,11 @@ Request body: token: string, // See below - always_encrypted?: boolean, + always_raw?: boolean, } ``` -- `always_encrypted` - enables always sending of raw encrypted notifications +- `always_raw` - enables always sending of raw notifications - When this is set to `true`, the pushed notification will always be the value from `payload.raw` from Send Notifications below. - When this is set to `false` or not present, the legacy behavior of conditionally sending (depending on `payload.flags`) encrypted or cleartext push notifications from `payload.blob` is used. From a91609ed4fc8079cfcb5e1961ffbddfde3d1cc27 Mon Sep 17 00:00:00 2001 From: Jakub Witczak Date: Thu, 28 Sep 2023 18:05:41 +0200 Subject: [PATCH 05/27] Update docs/specs/meta-clients/web3wallet/decrypted-norifications.md Co-authored-by: Chris Smith <1979423+chris13524@users.noreply.github.com> --- .../web3wallet/decrypted-norifications.md | 38 +++++++++---------- 1 file changed, 17 insertions(+), 21 deletions(-) diff --git a/docs/specs/meta-clients/web3wallet/decrypted-norifications.md b/docs/specs/meta-clients/web3wallet/decrypted-norifications.md index 49d045ce..2ad4014b 100644 --- a/docs/specs/meta-clients/web3wallet/decrypted-norifications.md +++ b/docs/specs/meta-clients/web3wallet/decrypted-norifications.md @@ -3,29 +3,25 @@ The below class introduces the general way of handling decprytped notifications received by a wallet. The implementation details differs on each platform. ```typescript - abstract class DecryptedNotification { - //decrypt encrypted request - public decryptMessage(params: { topic: string, encryptedMessage: string }): Promise; + // decrypt encrypted request + public decryptMessage(params: { topic: string, encryptedMessage: string }): Promise; - //get notification metadata for a given request - public getNotificationMetadata(params: { topic: string, message: Message }): Promise; + // get notification metadata for a given request + public getNotificationMetadata(params: { topic: string, message: Message }): Promise; } - //Message - { - "id": string, - "jsonrpc": string, - "method": string, - "params": string, //Sign(proposal, request) params, Auth request params, Notify params - } +type Message = { + id: string, + jsonrpc: string, + method: string, + params: string, //Sign(proposal, request) params, Auth request params, Notify params +} - //Notification - { - "title": string, - "body": string, - "icon": string, - "url": string, - "type": string, - } -``` \ No newline at end of file +type Notification = { + title: string, + body: string, + icon: string, + url: string, + type: string, +} \ No newline at end of file From 304e86a67b11ce1c6d4305d0e54e4e63e903be84 Mon Sep 17 00:00:00 2001 From: Jakub Witczak Date: Thu, 28 Sep 2023 18:08:35 +0200 Subject: [PATCH 06/27] Update docs/specs/meta-clients/web3wallet/sdk-api.md Co-authored-by: Chris Smith <1979423+chris13524@users.noreply.github.com> --- docs/specs/meta-clients/web3wallet/sdk-api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/specs/meta-clients/web3wallet/sdk-api.md b/docs/specs/meta-clients/web3wallet/sdk-api.md index c3ec9882..55d51657 100644 --- a/docs/specs/meta-clients/web3wallet/sdk-api.md +++ b/docs/specs/meta-clients/web3wallet/sdk-api.md @@ -71,7 +71,7 @@ class Web3Wallet { public abstract getPendingAuthRequests(): Promise>; // register device token for Push server (BOTH) - public abstract registerDeviceToken(token: string, isDecrypted: boolean?): Promise; + public abstract registerDeviceToken(token: string, enableEncrypted: boolean?): Promise; // ---------- Events ----------------------------------------------- // From 7d89303b9ef7e97990f0a6046001b349222e03bc Mon Sep 17 00:00:00 2001 From: Chris Smith Date: Thu, 28 Sep 2023 13:03:31 -0400 Subject: [PATCH 07/27] chore: clarify notification content --- docs/specs/servers/push/spec.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/docs/specs/servers/push/spec.md b/docs/specs/servers/push/spec.md index 766d4f3a..6297777e 100644 --- a/docs/specs/servers/push/spec.md +++ b/docs/specs/servers/push/spec.md @@ -78,8 +78,8 @@ Request body: ``` - `always_raw` - enables always sending of raw notifications - - When this is set to `true`, the pushed notification will always be the value from `payload.raw` from Send Notifications below. - - When this is set to `false` or not present, the legacy behavior of conditionally sending (depending on `payload.flags`) encrypted or cleartext push notifications from `payload.blob` is used. + - When this is set to `true`, the pushed notification will always be the value from `payload.raw` from Send Notifications below. The notification will contain `topic` and `message` fields. + - When this is set to `false` or not present, the legacy behavior of conditionally sending (depending on `payload.flags`) encrypted or cleartext push notifications from `payload.blob` is used. The notification will contain `topic`, `flags`, and `blob` fields. ### Unregister Client @@ -91,6 +91,8 @@ DELETE /clients/ ### Send Notification +This API is called by the relay. + ``` POST /clients/ ``` From f15c8ab6ae53667b3dd46ffcde8aeebafcaf126b Mon Sep 17 00:00:00 2001 From: Chris Smith Date: Sun, 1 Oct 2023 22:00:02 -0400 Subject: [PATCH 08/27] chore: dedicated topic and message fields for easier migration later --- docs/specs/servers/push/spec.md | 19 ++++++++++++------- 1 file changed, 12 insertions(+), 7 deletions(-) diff --git a/docs/specs/servers/push/spec.md b/docs/specs/servers/push/spec.md index 6297777e..ee4206db 100644 --- a/docs/specs/servers/push/spec.md +++ b/docs/specs/servers/push/spec.md @@ -78,7 +78,7 @@ Request body: ``` - `always_raw` - enables always sending of raw notifications - - When this is set to `true`, the pushed notification will always be the value from `payload.raw` from Send Notifications below. The notification will contain `topic` and `message` fields. + - When this is set to `true`, the push notification will be `topic` and `message` from Send Notifications below. - When this is set to `false` or not present, the legacy behavior of conditionally sending (depending on `payload.flags`) encrypted or cleartext push notifications from `payload.blob` is used. The notification will contain `topic`, `flags`, and `blob` fields. ### Unregister Client @@ -106,17 +106,22 @@ Headers: Request body: ```typescript { + // Topic of the message. This is used by the SDKs to decrypt encrypted payloads on the client side + topic: string, + + // The relay message. + message: string, + + // ==== Legacy Fields ==== + // Message ID for deduplication purposes - // Note: When `payload.raw` is set, `sha264(payload.raw)` should be used as the Message ID instead + // Note: When `message` is provided, `sha264(message)` should be used as the Message ID instead id: string, payload: { - // Topic of the message. This is used by the SDKs to decrypt encrypted payloads on the client side + // Same as `topic` above topic: string, - // Raw message sent on the topic - raw: string, - // See below flags: number, @@ -133,4 +138,4 @@ Request body: Chat = 1 << 3 Notify = 1 << 4 ``` -- `blob`: If the payload is encrypted this is just the encrypted blob, when this is cleartext it should be base64 encoded. The blob should follow the format from of the [Notify Message](https://specs.walletconnect.com/2.0/specs/clients/notify/data-structures#notify-message) +- `blob`: If the flags specify encrypted, then this is just the relay message. If not encrypted, this is cleartext and should follow the format from of the [Notify Message](https://specs.walletconnect.com/2.0/specs/clients/notify/data-structures#notify-message) From db1e02f996e85776ccd657aa907b86244319344f Mon Sep 17 00:00:00 2001 From: Chris Smith Date: Sun, 1 Oct 2023 22:00:52 -0400 Subject: [PATCH 09/27] chore: simplify language --- docs/specs/servers/push/spec.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/specs/servers/push/spec.md b/docs/specs/servers/push/spec.md index ee4206db..6a0c173d 100644 --- a/docs/specs/servers/push/spec.md +++ b/docs/specs/servers/push/spec.md @@ -78,8 +78,8 @@ Request body: ``` - `always_raw` - enables always sending of raw notifications - - When this is set to `true`, the push notification will be `topic` and `message` from Send Notifications below. - - When this is set to `false` or not present, the legacy behavior of conditionally sending (depending on `payload.flags`) encrypted or cleartext push notifications from `payload.blob` is used. The notification will contain `topic`, `flags`, and `blob` fields. + - When set to `true`, the push notification will be `topic` and `message` from Send Notifications below. + - When set to `false` or not present, the legacy behavior of conditionally sending (depending on `payload.flags`) encrypted or cleartext push notifications from `payload.blob` is used. The notification will contain `topic`, `flags`, and `blob` fields. ### Unregister Client From de43c3c53c7ae3c6e2ef3c25ac1cd7015e6260c3 Mon Sep 17 00:00:00 2001 From: Chris Smith Date: Sun, 1 Oct 2023 22:03:34 -0400 Subject: [PATCH 10/27] chore: not a "message ID" --- docs/specs/servers/push/spec.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/specs/servers/push/spec.md b/docs/specs/servers/push/spec.md index 6a0c173d..45c93a52 100644 --- a/docs/specs/servers/push/spec.md +++ b/docs/specs/servers/push/spec.md @@ -114,8 +114,8 @@ Request body: // ==== Legacy Fields ==== - // Message ID for deduplication purposes - // Note: When `message` is provided, `sha264(message)` should be used as the Message ID instead + // Unique ID for deduplication purposes + // Note: When `message` is provided, `sha264(message)` should be used to deduplicate instead id: string, payload: { From acae8c2abe3e93b8adb38aa871146aaa6ace3414 Mon Sep 17 00:00:00 2001 From: Jakub Witczak Date: Mon, 2 Oct 2023 13:55:10 +0200 Subject: [PATCH 11/27] Update sdk-api.md --- docs/specs/meta-clients/web3wallet/sdk-api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/specs/meta-clients/web3wallet/sdk-api.md b/docs/specs/meta-clients/web3wallet/sdk-api.md index c1611ea7..70da8e64 100644 --- a/docs/specs/meta-clients/web3wallet/sdk-api.md +++ b/docs/specs/meta-clients/web3wallet/sdk-api.md @@ -71,7 +71,7 @@ class Web3Wallet { public abstract getPendingAuthRequests(): Promise>; // register device token for Push server (BOTH) - public abstract registerDeviceToken(token: string, enableAlwaysEncrypted: boolean?): Promise; + public abstract registerDeviceToken(token: string, enableAlwaysDecrypted: boolean?): Promise; // ---------- Events ----------------------------------------------- // From 14c6f0a74a1e6c81a5744074d71f7b66a6db4880 Mon Sep 17 00:00:00 2001 From: Chris Smith <1979423+chris13524@users.noreply.github.com> Date: Mon, 2 Oct 2023 10:24:56 -0400 Subject: [PATCH 12/27] chore: apply push suggestions MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Szymon Rząd --- docs/specs/servers/push/spec.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/specs/servers/push/spec.md b/docs/specs/servers/push/spec.md index 45c93a52..948fb5e6 100644 --- a/docs/specs/servers/push/spec.md +++ b/docs/specs/servers/push/spec.md @@ -77,8 +77,8 @@ Request body: } ``` -- `always_raw` - enables always sending of raw notifications - - When set to `true`, the push notification will be `topic` and `message` from Send Notifications below. +- `always_raw` - forces sending raw notifications + - When set to `true`, the push notification will be `topic` and `message` as per [Send Notifications](#send-notification) section. - When set to `false` or not present, the legacy behavior of conditionally sending (depending on `payload.flags`) encrypted or cleartext push notifications from `payload.blob` is used. The notification will contain `topic`, `flags`, and `blob` fields. ### Unregister Client @@ -91,7 +91,7 @@ DELETE /clients/ ### Send Notification -This API is called by the relay. +This endpoint is called by the relay. ``` POST /clients/ @@ -130,7 +130,7 @@ Request body: } ``` -- `flags`: an integer value that uses bitmasks to encode information about the payload for the SDKs, the flags are below +- `flags`: An integer value that uses bitmasks to encode information about the payload for the SDKs, the flags are below ``` Encrypted = 1 << 0 Sign = 1 << 1 From 282a8ae98095a25bc19158d1bce3797cb2257e0e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Szymon=20Rz=C4=85d?= Date: Mon, 2 Oct 2023 16:48:07 +0200 Subject: [PATCH 13/27] chore: Apply suggestion --- docs/specs/meta-clients/web3wallet/decrypted-norifications.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/specs/meta-clients/web3wallet/decrypted-norifications.md b/docs/specs/meta-clients/web3wallet/decrypted-norifications.md index 2ad4014b..6471709b 100644 --- a/docs/specs/meta-clients/web3wallet/decrypted-norifications.md +++ b/docs/specs/meta-clients/web3wallet/decrypted-norifications.md @@ -1,6 +1,6 @@ # Decrypted Notification -The below class introduces the general way of handling decprytped notifications received by a wallet. The implementation details differs on each platform. +The below class introduces the general way of handling decrypted notifications received by a wallet. The implementation details differs on each platform. ```typescript abstract class DecryptedNotification { From a8ea748d90cad8887a7b254d4c81df1b0781c418 Mon Sep 17 00:00:00 2001 From: kubel Date: Wed, 4 Oct 2023 11:56:24 +0200 Subject: [PATCH 14/27] Add tags --- .../web3wallet/decrypted-norifications.md | 11 ++++++++--- 1 file changed, 8 insertions(+), 3 deletions(-) diff --git a/docs/specs/meta-clients/web3wallet/decrypted-norifications.md b/docs/specs/meta-clients/web3wallet/decrypted-norifications.md index 6471709b..a6d04ac7 100644 --- a/docs/specs/meta-clients/web3wallet/decrypted-norifications.md +++ b/docs/specs/meta-clients/web3wallet/decrypted-norifications.md @@ -15,8 +15,7 @@ type Message = { id: string, jsonrpc: string, method: string, - params: string, //Sign(proposal, request) params, Auth request params, Notify params -} + params: string, type Notification = { title: string, @@ -24,4 +23,10 @@ type Notification = { icon: string, url: string, type: string, -} \ No newline at end of file +} +``` + +Clients can expect receiving the following tags: +- Sign: `SESSION_PROPOSE(1100)`, `SESSION_REQUEST(1108)` +- Auth: `AUTH_REQUEST(3000)` +- Notify: `NOTIFY_MESSAGE(4002)` \ No newline at end of file From 50668714bf25925a7e45fbfc17e682b79e2a63cd Mon Sep 17 00:00:00 2001 From: Chris Smith Date: Wed, 4 Oct 2023 12:35:21 -0400 Subject: [PATCH 15/27] chore: improve tag filtering --- ...ed-norifications.md => decrypted-notifications.md} | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) rename docs/specs/meta-clients/web3wallet/{decrypted-norifications.md => decrypted-notifications.md} (68%) diff --git a/docs/specs/meta-clients/web3wallet/decrypted-norifications.md b/docs/specs/meta-clients/web3wallet/decrypted-notifications.md similarity index 68% rename from docs/specs/meta-clients/web3wallet/decrypted-norifications.md rename to docs/specs/meta-clients/web3wallet/decrypted-notifications.md index a6d04ac7..9ff612aa 100644 --- a/docs/specs/meta-clients/web3wallet/decrypted-norifications.md +++ b/docs/specs/meta-clients/web3wallet/decrypted-notifications.md @@ -1,4 +1,4 @@ -# Decrypted Notification +# Decrypted Notifications The below class introduces the general way of handling decrypted notifications received by a wallet. The implementation details differs on each platform. @@ -16,6 +16,7 @@ type Message = { jsonrpc: string, method: string, params: string, +} type Notification = { title: string, @@ -26,7 +27,7 @@ type Notification = { } ``` -Clients can expect receiving the following tags: -- Sign: `SESSION_PROPOSE(1100)`, `SESSION_REQUEST(1108)` -- Auth: `AUTH_REQUEST(3000)` -- Notify: `NOTIFY_MESSAGE(4002)` \ No newline at end of file +Clients will be pushed all messages sent on the topic, so the client should filter these by the message's `method` and only display push notifications for the following methods: +- Sign: `wc_sessionPropose` (1100), `wc_sessionRequest` (1108) +- Auth: `wc_authRequest` (3000) +- Notify: `wc_notifyMessage` (4002) From 264bd16db8c681cb3598b1deacac26756385510a Mon Sep 17 00:00:00 2001 From: Chris Smith Date: Wed, 4 Oct 2023 12:37:59 -0400 Subject: [PATCH 16/27] feat: enableAlwaysDecrypted defaults to false --- docs/specs/meta-clients/web3wallet/sdk-api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/specs/meta-clients/web3wallet/sdk-api.md b/docs/specs/meta-clients/web3wallet/sdk-api.md index 70da8e64..56929386 100644 --- a/docs/specs/meta-clients/web3wallet/sdk-api.md +++ b/docs/specs/meta-clients/web3wallet/sdk-api.md @@ -71,7 +71,7 @@ class Web3Wallet { public abstract getPendingAuthRequests(): Promise>; // register device token for Push server (BOTH) - public abstract registerDeviceToken(token: string, enableAlwaysDecrypted: boolean?): Promise; + public abstract registerDeviceToken(token: string, enableAlwaysDecrypted?: boolean = false): Promise; // ---------- Events ----------------------------------------------- // From d83fc21af042c411ba08dfa16c6526324314d0f8 Mon Sep 17 00:00:00 2001 From: Chris Smith Date: Wed, 4 Oct 2023 13:06:33 -0400 Subject: [PATCH 17/27] chore: push server handles cleartext generation --- docs/specs/servers/push/spec.md | 15 ++++++++++----- 1 file changed, 10 insertions(+), 5 deletions(-) diff --git a/docs/specs/servers/push/spec.md b/docs/specs/servers/push/spec.md index 948fb5e6..74adad58 100644 --- a/docs/specs/servers/push/spec.md +++ b/docs/specs/servers/push/spec.md @@ -77,9 +77,12 @@ Request body: } ``` -- `always_raw` - forces sending raw notifications - - When set to `true`, the push notification will be `topic` and `message` as per [Send Notifications](#send-notification) section. - - When set to `false` or not present, the legacy behavior of conditionally sending (depending on `payload.flags`) encrypted or cleartext push notifications from `payload.blob` is used. The notification will contain `topic`, `flags`, and `blob` fields. +- `always_raw` - forces sending raw notifications, defaults to `false` + - When set to `true`, the push notification will contain, as custom data, `topic`, `tag`, and `message` from the request payload in [Send Notifications](#send-notification) section. + - When set to `false`, cleartext notifications will be sent for certain messages based on `tag`, but all other messages follow the same behavior as `always_raw=true` and will be sent encrypted. Cleartext messages: + - Sign API `wc_sessionPropose` (tag: 1100) and `wc_sessionRequest` (tag: 1108) + - title: Signature required + - body: You have a message to sign ### Unregister Client @@ -109,13 +112,15 @@ Request body: // Topic of the message. This is used by the SDKs to decrypt encrypted payloads on the client side topic: string, + // Tag of the message. + tag: string, + // The relay message. message: string, - // ==== Legacy Fields ==== + // ==== Deprecated fields ==== // Unique ID for deduplication purposes - // Note: When `message` is provided, `sha264(message)` should be used to deduplicate instead id: string, payload: { From 1a9ad6005447d6d7d6458824579ecc103f4af825 Mon Sep 17 00:00:00 2001 From: Jakub Witczak Date: Mon, 9 Oct 2023 11:55:12 +0200 Subject: [PATCH 18/27] Update decrypted-notifications.md --- docs/specs/meta-clients/web3wallet/decrypted-notifications.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/specs/meta-clients/web3wallet/decrypted-notifications.md b/docs/specs/meta-clients/web3wallet/decrypted-notifications.md index 9ff612aa..24977313 100644 --- a/docs/specs/meta-clients/web3wallet/decrypted-notifications.md +++ b/docs/specs/meta-clients/web3wallet/decrypted-notifications.md @@ -27,7 +27,7 @@ type Notification = { } ``` -Clients will be pushed all messages sent on the topic, so the client should filter these by the message's `method` and only display push notifications for the following methods: +Clients will be pushed all messages sent on the topic, so the client should filter these by the message's `tag` and only display push notifications for the following methods: - Sign: `wc_sessionPropose` (1100), `wc_sessionRequest` (1108) - Auth: `wc_authRequest` (3000) - Notify: `wc_notifyMessage` (4002) From d699a9fa0e036e28c349800a500fef1223de5d4d Mon Sep 17 00:00:00 2001 From: Jakub Witczak Date: Tue, 10 Oct 2023 09:24:45 +0200 Subject: [PATCH 19/27] Update docs/specs/servers/push/spec.md Co-authored-by: Chris Smith <1979423+chris13524@users.noreply.github.com> --- docs/specs/servers/push/spec.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/specs/servers/push/spec.md b/docs/specs/servers/push/spec.md index 74adad58..c5a70327 100644 --- a/docs/specs/servers/push/spec.md +++ b/docs/specs/servers/push/spec.md @@ -113,7 +113,7 @@ Request body: topic: string, // Tag of the message. - tag: string, + tag: number, // The relay message. message: string, From bfa3f8b0aebc498b558c650efb9c1018c58b0bf5 Mon Sep 17 00:00:00 2001 From: Chris Smith <1979423+chris13524@users.noreply.github.com> Date: Tue, 10 Oct 2023 13:25:00 -0400 Subject: [PATCH 20/27] chore: change field order --- docs/specs/meta-clients/web3wallet/decrypted-notifications.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/specs/meta-clients/web3wallet/decrypted-notifications.md b/docs/specs/meta-clients/web3wallet/decrypted-notifications.md index 24977313..1617e24a 100644 --- a/docs/specs/meta-clients/web3wallet/decrypted-notifications.md +++ b/docs/specs/meta-clients/web3wallet/decrypted-notifications.md @@ -19,11 +19,11 @@ type Message = { } type Notification = { + type: string, title: string, body: string, icon: string, url: string, - type: string, } ``` From 1a95259130de3d9904c3451aba260dc20f8c1538 Mon Sep 17 00:00:00 2001 From: kubel Date: Tue, 21 Nov 2023 12:34:33 +0100 Subject: [PATCH 21/27] split Notify and Web3Wallet notifications specs --- .../clients/notify/decrypted-notifications.md | 21 +++++++++++++++++++ .../web3wallet/decrypted-notifications.md | 21 +++++++++---------- 2 files changed, 31 insertions(+), 11 deletions(-) create mode 100644 docs/specs/clients/notify/decrypted-notifications.md diff --git a/docs/specs/clients/notify/decrypted-notifications.md b/docs/specs/clients/notify/decrypted-notifications.md new file mode 100644 index 00000000..ca3408fe --- /dev/null +++ b/docs/specs/clients/notify/decrypted-notifications.md @@ -0,0 +1,21 @@ +# Decrypted Notifications + +The below class introduces the general way of handling notify notifications received by a wallet. This should be handled in the background service where the implementation details differs on each platform. + +```typescript +abstract class DecryptedNotification { + // decrypt encrypted request + public decryptMessage(params: { topic: string, encryptedMessage: string }): Promise; +} + +type NotifyMessage = { + id: string, + title: string, + body: string, + icon: string, + url: string, +} +``` + +Clients will be pushed all messages sent on the topic, so the client should filter these by the message's `tag` and only display push notifications for the following methods: +- Notify: `wc_notifyMessage` (4002) \ No newline at end of file diff --git a/docs/specs/meta-clients/web3wallet/decrypted-notifications.md b/docs/specs/meta-clients/web3wallet/decrypted-notifications.md index 1617e24a..ff0e46c0 100644 --- a/docs/specs/meta-clients/web3wallet/decrypted-notifications.md +++ b/docs/specs/meta-clients/web3wallet/decrypted-notifications.md @@ -1,6 +1,6 @@ # Decrypted Notifications -The below class introduces the general way of handling decrypted notifications received by a wallet. The implementation details differs on each platform. +The below class introduces the general way of handling decrypted notifications notifications (Sign, Auth) received by a wallet. This should be handled in the background service where the implementation details differs on each platform. ```typescript abstract class DecryptedNotification { @@ -8,26 +8,25 @@ abstract class DecryptedNotification { public decryptMessage(params: { topic: string, encryptedMessage: string }): Promise; // get notification metadata for a given request - public getNotificationMetadata(params: { topic: string, message: Message }): Promise; + public getMetadata(params: { topic: string }): Promise; } type Message = { id: string, - jsonrpc: string, - method: string, + jsonrpc: string, + method: string, params: string, } -type Notification = { - type: string, - title: string, - body: string, - icon: string, +type Metadata = { + name: string, + description: string, + url: string, + icons: string[], url: string, } ``` Clients will be pushed all messages sent on the topic, so the client should filter these by the message's `tag` and only display push notifications for the following methods: - Sign: `wc_sessionPropose` (1100), `wc_sessionRequest` (1108) -- Auth: `wc_authRequest` (3000) -- Notify: `wc_notifyMessage` (4002) +- Auth: `wc_authRequest` (3000) \ No newline at end of file From c70e02dda4fbdb2084be16fc15d182b150b748be Mon Sep 17 00:00:00 2001 From: Jakub Witczak Date: Tue, 21 Nov 2023 14:20:22 +0100 Subject: [PATCH 22/27] Update docs/specs/servers/push/spec.md Co-authored-by: Chris Smith <1979423+chris13524@users.noreply.github.com> --- docs/specs/servers/push/spec.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/specs/servers/push/spec.md b/docs/specs/servers/push/spec.md index c5a70327..c53d3597 100644 --- a/docs/specs/servers/push/spec.md +++ b/docs/specs/servers/push/spec.md @@ -79,7 +79,7 @@ Request body: - `always_raw` - forces sending raw notifications, defaults to `false` - When set to `true`, the push notification will contain, as custom data, `topic`, `tag`, and `message` from the request payload in [Send Notifications](#send-notification) section. - - When set to `false`, cleartext notifications will be sent for certain messages based on `tag`, but all other messages follow the same behavior as `always_raw=true` and will be sent encrypted. Cleartext messages: + - When set to `false`, cleartext notifications will be sent for certain messages based on `tag`, but all other messages will contain, as custom data, `payload.topic` and `payload.blob` from the request payload in [Send Notifications](#send-notification) section. Cleartext messages: - Sign API `wc_sessionPropose` (tag: 1100) and `wc_sessionRequest` (tag: 1108) - title: Signature required - body: You have a message to sign From f37635991ab3bec19a0e00355e3530b912c9d18f Mon Sep 17 00:00:00 2001 From: Jakub Witczak Date: Tue, 21 Nov 2023 14:23:15 +0100 Subject: [PATCH 23/27] Update docs/specs/servers/push/spec.md Co-authored-by: Chris Smith <1979423+chris13524@users.noreply.github.com> --- docs/specs/servers/push/spec.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/specs/servers/push/spec.md b/docs/specs/servers/push/spec.md index c53d3597..ba2f0029 100644 --- a/docs/specs/servers/push/spec.md +++ b/docs/specs/servers/push/spec.md @@ -143,4 +143,4 @@ Request body: Chat = 1 << 3 Notify = 1 << 4 ``` -- `blob`: If the flags specify encrypted, then this is just the relay message. If not encrypted, this is cleartext and should follow the format from of the [Notify Message](https://specs.walletconnect.com/2.0/specs/clients/notify/data-structures#notify-message) +- `blob`: If the flags specify encrypted, then this is just the relay message. If not encrypted, this is base64 encoded cleartext and should follow the format from of the [Notify Message](https://specs.walletconnect.com/2.0/specs/clients/notify/data-structures#notify-message) From dea9c0955131297d421569d68a6eb973a915e434 Mon Sep 17 00:00:00 2001 From: Jakub Witczak Date: Tue, 21 Nov 2023 14:25:04 +0100 Subject: [PATCH 24/27] Update docs/specs/servers/push/spec.md Co-authored-by: Chris Smith <1979423+chris13524@users.noreply.github.com> --- docs/specs/servers/push/spec.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/specs/servers/push/spec.md b/docs/specs/servers/push/spec.md index ba2f0029..143f2922 100644 --- a/docs/specs/servers/push/spec.md +++ b/docs/specs/servers/push/spec.md @@ -118,7 +118,7 @@ Request body: // The relay message. message: string, - // ==== Deprecated fields ==== + // ==== Legacy fields ==== // Unique ID for deduplication purposes id: string, From 71164e3129ff013a6fcb035fd5dbaeac0ef86ea9 Mon Sep 17 00:00:00 2001 From: kubel Date: Tue, 21 Nov 2023 14:35:09 +0100 Subject: [PATCH 25/27] Update --- docs/specs/clients/notify/decrypted-notifications.md | 1 + .../meta-clients/web3wallet/decrypted-notifications.md | 5 ++--- docs/specs/servers/push/background-service | 6 ++++++ 3 files changed, 9 insertions(+), 3 deletions(-) create mode 100644 docs/specs/servers/push/background-service diff --git a/docs/specs/clients/notify/decrypted-notifications.md b/docs/specs/clients/notify/decrypted-notifications.md index ca3408fe..00550b37 100644 --- a/docs/specs/clients/notify/decrypted-notifications.md +++ b/docs/specs/clients/notify/decrypted-notifications.md @@ -10,6 +10,7 @@ abstract class DecryptedNotification { type NotifyMessage = { id: string, + type: string, title: string, body: string, icon: string, diff --git a/docs/specs/meta-clients/web3wallet/decrypted-notifications.md b/docs/specs/meta-clients/web3wallet/decrypted-notifications.md index ff0e46c0..4b8d196b 100644 --- a/docs/specs/meta-clients/web3wallet/decrypted-notifications.md +++ b/docs/specs/meta-clients/web3wallet/decrypted-notifications.md @@ -5,13 +5,13 @@ The below class introduces the general way of handling decrypted notifications n ```typescript abstract class DecryptedNotification { // decrypt encrypted request - public decryptMessage(params: { topic: string, encryptedMessage: string }): Promise; + public decryptMessage(params: { topic: string, encryptedMessage: string }): Promise; // get notification metadata for a given request public getMetadata(params: { topic: string }): Promise; } -type Message = { +type RpcRequest = { id: string, jsonrpc: string, method: string, @@ -23,7 +23,6 @@ type Metadata = { description: string, url: string, icons: string[], - url: string, } ``` diff --git a/docs/specs/servers/push/background-service b/docs/specs/servers/push/background-service new file mode 100644 index 00000000..97157fd7 --- /dev/null +++ b/docs/specs/servers/push/background-service @@ -0,0 +1,6 @@ +### Background Service + +Each platform is responsible for handling decrypted notifications in background services received by a wallet where the implementation details differns on each platforms. The background service decides based on tag the type of notification to handle. + +- [Notify Notifications](docs/specs/clients/notify/decrypted-notifications.md) +- [Web3Wallet Notifications](docs/specs/meta-clients/web3wallet/decrypted-notifications.md) \ No newline at end of file From 0ed7aef56e1bfb7b48e500487b533c02fcda0d5d Mon Sep 17 00:00:00 2001 From: Jakub Witczak Date: Tue, 21 Nov 2023 15:57:20 +0100 Subject: [PATCH 26/27] Update docs/specs/servers/push/background-service Co-authored-by: Chris Smith <1979423+chris13524@users.noreply.github.com> --- docs/specs/servers/push/background-service | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/specs/servers/push/background-service b/docs/specs/servers/push/background-service index 97157fd7..b85d9644 100644 --- a/docs/specs/servers/push/background-service +++ b/docs/specs/servers/push/background-service @@ -1,6 +1,6 @@ ### Background Service -Each platform is responsible for handling decrypted notifications in background services received by a wallet where the implementation details differns on each platforms. The background service decides based on tag the type of notification to handle. +Each platform is responsible for handling decrypted notifications in background services received by a wallet where the implementation details differ on each platforms. The background service decides based on tag the type of notification to handle. - [Notify Notifications](docs/specs/clients/notify/decrypted-notifications.md) - [Web3Wallet Notifications](docs/specs/meta-clients/web3wallet/decrypted-notifications.md) \ No newline at end of file From ca2ce724fa1965f7d635ddf60421cfa1f66a56b6 Mon Sep 17 00:00:00 2001 From: kubel Date: Tue, 28 Nov 2023 09:25:42 +0100 Subject: [PATCH 27/27] Change flag name --- docs/specs/meta-clients/web3wallet/sdk-api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/specs/meta-clients/web3wallet/sdk-api.md b/docs/specs/meta-clients/web3wallet/sdk-api.md index 56929386..dc3d9843 100644 --- a/docs/specs/meta-clients/web3wallet/sdk-api.md +++ b/docs/specs/meta-clients/web3wallet/sdk-api.md @@ -71,7 +71,7 @@ class Web3Wallet { public abstract getPendingAuthRequests(): Promise>; // register device token for Push server (BOTH) - public abstract registerDeviceToken(token: string, enableAlwaysDecrypted?: boolean = false): Promise; + public abstract registerDeviceToken(token: string, enableEncrypted?: boolean = false): Promise; // ---------- Events ----------------------------------------------- //