ARC-0027: Provider Message Schema #272

kieranroneill · 2024-01-12T15:56:51Z

Summary

This proposal intends to outline a common message schema to be used in dApp/provider (wallet) communication.

The proposal attempts to build off the fundamental work of the previous ARCs; wallet transaction signing (ARC-0005), wallet address discovery (ARC-0006), wallet transaction network posting (ARC-0007) and wallet transaction signing & posting (ARC-0008), to comprehensively outline a common message schema, and to extend this schema with an aim to allow more robustness with multiple AVM (Algorand Virtual Machine) chains.

Aside from extending the schema of the previous ARCs, this proposal also adds a couple of new methods that aim to "fill the gap". These include:

A discovery method that is used to get information about providers such as what methods are supported and what chains.
A "disable" method that allows a dApp to remove itself from providers.

ARCs/arc-0027.md

…stions Co-authored-by: Doug Richar <[email protected]>

ehanoc

I'm a big big fan of this proposal.

Overall, to finalize it, maybe we could include a reference implementation for us to test ourselves?

ehanoc · 2024-01-24T10:32:21Z

ARCs/arc-0027.md

@@ -0,0 +1,1611 @@
+---
+arc: 27
+title: Web Extension Wallet Interface


What do you think of keeping this agnostic to the platform? We could just say Wallet Interface for instance

ehanoc · 2024-01-24T10:34:26Z

ARCs/arc-0027.md

+| Description                                                                                                                                                                                                                                                                                                                                                                                                                          | Benefits                                                                                                                                                                                                                                                                                                                    | Drawbacks                                                                                                                                                                                                                        |
+|:-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| The global `window.algorand` object is overwritten by an injected script from a web extension's content script. This overwritten object will provide features that allows the dapp to interact with the wallet which may or may not conform to previous ARCs ([ARC-0005](./arc-0005.md#specification), [ARC-0006](./arc-0006.md#specification), [ARC-0007](./arc-0007.md#specification) or [ARC-0008](./arc-0008.md#specification)). | - Dapps will not have to install any external SDKs<br/>- Dapps do not need to know which wallet the user is using (if the injected wallet conforms to [ARC-0005](./arc-0005.md#specification), [ARC-0006](./arc-0006.md#specification), [ARC-0007](./arc-0007.md#specification) or [ARC-0008](./arc-0008.md#specification)) | - In the instance of multiple web extension wallets, another wallet extension may overwrite this object.<br/>- Once overwritten, the `window.algorand` object will only service the last web extension wallet that overwrote it. |
+| A wallet provides a separate SDK that is installed by a dapp to interact with the wallet.                                                                                                                                                                                                                                                                                                                                            | - Allows wallets full control over how dapps interact with wallets, ie. provide a bespoke UX.                                                                                                                                                                                                                               | - Dapps need to install each SDK separately, thereby increasing the amount of development time, and complexity, needed to implement each wallet separately.                                                                      |


Wouldn't this be a single SDK for dapp developers? They would just need to comply with the API, no?

Maybe that's something could be provided in the ARC as a reference implementation. Thoughts?

ehanoc · 2024-01-24T10:37:06Z

ARCs/arc-0027.md

+
+The dapp will, itself, listen to broadcasted responses from any providers. Below is a simple diagram for the flow of data for an enable request:
+
+![Simple BroadcastChannel API using web extensions](../assets/arc-0027/simple_message_bus.png)


I like it, is there samples for us to include here and test?

I am separately developing an npm package, that is essentially an SDK wrapper around this, for wallets/dApps to install for minimum code. Similar to the Algorand Provider I built way back.

The UseWallet implementation of the Kibisis wallet uses it into interact with the Kibisis web extension wallet.

ehanoc · 2024-01-24T10:50:20Z

ARCs/arc-0027.md

+* `reference`:
+  - **MUST** be `arc0027:sign_txns:response`
+
+#### Sign Bytes


I'm a fan of us supporting signing for multiple purposes and arbitrary data signing. But signBytes:

seems to give freedom to the app to define what purposes this can be used for with a simple string. Seems that it can be gamed to trick users to sign things that they shouldn't, even transactions.

Doesn't consider multiple encoding schemes

Validation of the content to be signed should be matched against a known schema?

That's one of the things i'm trying to address in ARC-52#SignMetadata is to enforce the context of what we are signing and validate it quickly from a list of possible schema templates (i.e authentication requests, messages, identity), so that the user doesn't have to understand msgpack encoding or CBOR and the wallet can still validate what is signing.

It's a longer conversation though.

I wholeheartedly agree. I have been playing with this with Algorand Provider + Kibisis and, if I recall, Kibisis displays the data if it is:

A valid UTF-8 string

A parseable JWT

For example, for JWTs, if it is correctly parsed it shows this screen:

It also shows some warnings if the JWT has expired or the subject/sub of the JWT does not match the account to sign.

As you can workout, I am a fan of JWTs 😅

(It was actually the only reason I built Kibisis as I wanted to implement, for the then, app I was building to use user JWT authentication using an Algorand account)

But you are right, the schema of this function requires more work as it is not fit for consumption.

kewde · 2024-02-08T15:19:38Z

ARCs/arc-0027.md

+
+## Abstract
+
+Building off of the previous ARCs relating to; wallet transaction signing ([ARC-0005](./arc-0005.md#specification)), wallet address discovery ([ARC-0006](./arc-0006.md#specification)), wallet transaction network posting ([ARC-0007](./arc-0007.md#specification)) and wallet transaction signing & posting ([ARC-0008](./arc-0008.md#specification)), this proposal aims to extend and comprehensively outline a common interface between multiple web extension wallets and dapps by utilizing the pub/sub semantics of the <a href="https://developer.mozilla.org/en-US/docs/Web/API/Broadcast_Channel_API">BroadcastChannel API</a>.


Using a BroadcastChannel is an interesting choice and would need a bit more inspection. AFAIK web extensions do not typically inject in iframes, with this approach we may be allowing embedded iframes to trigger a wallet popup as long as that origin is also open in a tab elsewhere.

Do I understand it correctly that if multiple tabs are open and thus content scripts are listening to the BroadcastChannel, then they need to avoid registering multiple times? If registering multiple times is allowed, would the content script need to synchronize internally to ensure that it deals with e.g "signTxn" only once, as to not open 10 popups for each of the 10 tabs that are open?

kewde · 2024-02-08T15:25:13Z

ARCs/arc-0027.md

+* `result.host`:
+  - **RECOMMENDED** a URL that points to a live website
+* `result.icon`:
+  - **RECOMMENDED** be a URI that conforms to <a href="https://www.rfc-editor.org/rfc/rfc2397">[RFC-2397]</a>


Can we make this mandatory? Having remote URI's here may make it harder to implement, and potentially more dangerous too.

Along with limiting the supported filetypes would be nice? 'svg+xml' | 'webp' | 'png' | 'gif' are the ones supported by wallet-standard.

kewde · 2024-02-08T15:37:58Z

ARCs/arc-0027.md

+  - **MUST** be a code of one of the [errors](#errors)
+* `message`:
+  - **SHOULD** be human-readable to allow for display to a user
+* `providerId`:


Can we clarify if the providerId is static value or whether this is allowed to be a random value every time it is registered? If it is a static value, will we maintain a list somewhere of the "taken" values which we'll respect on a gentlemen's agreement, even though collisions are very rare.

kewde · 2024-02-08T15:40:20Z

ARCs/arc-0027.md

+* `result.networks.methods`:
+  - **SHOULD** be one or all of `enable`, `postTxns`, `signAndPostTxns`, `signBytes` or `signTxns`
+  - **MAY** be empty
+* `result.host`:


Should we mandate that this must be "https://"?

…schema

…rations

PhearZero · 2024-07-15T23:45:06Z

ARCs/arc-0027.md

+```json
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "/schemas/request-message",


Small Nit: Looks like this one should be response-message

Thank you! One can miss stuff like this in a copy + paste 😅

No worries! Trying out the specification in Kotlin/Java and was doing a lot of copy + paste myself!

SudoWeezy · 2024-09-05T08:59:29Z

@kieranroneill How far are we to move this ARC to the review stage?
I think it would be great to move forward with this one now that we have deprecated ARC 6-11

kieranroneill · 2024-09-05T10:34:50Z

@kieranroneill How far are we to move this ARC to the review stage? I think it would be great to move forward with this one now that we have deprecated ARC 6-11

@SudoWeezy Sounds good! I have been battle testing this proposed spec in Kibisis, through AVM Web Provider and UseWallet, so I am happy to give feedback and discuss it further.

drichar

Some feedback from an issue I encountered adding a second ARC-27 extension wallet to https://github.com/TxnLab/use-wallet

drichar · 2024-09-10T14:52:02Z

ARCs/arc-0027.md

+  - **OPTIONAL** if omitted, the provider **SHOULD** assume the "default" network
+  - **MUST** be a base64 encoded hash of the genesis block of the network
+* `providerId`:
+  - **OPTIONAL** if omitted, all providers **MAY** respond


The providerId param needs to be required, otherwise you'll have wallets responding to enable requests not intended for them. I can't think of a situation where this would be the desired behavior. Enable requests should be 1-to-1.

drichar · 2024-09-10T14:53:43Z

ARCs/arc-0027.md

+```
+where:
+* `providerId`:
+  - **OPTIONAL** if omitted, all providers **MAY** respond


Similar to enable requests, disable requests should require a providerId and wallets should only respond to disable requests intended for them.

kieranroneill added 9 commits December 19, 2023 16:59

docs: add specification for arc0013

239cc0b

feat: add enable method

42a66a8

feat: add sign transactions method

faf0ecf

chore: squash

af7b702

feat: add sign bytes specification

948f147

refactor: remove network configuration from sign txns

7dce8b1

feat: add post txns schema

b027646

feat: add rationale

1dd200f

chore: squash

16fa601

github-actions bot added c-new s-draft t-interface labels Jan 12, 2024

kieranroneill and others added 2 commits January 12, 2024 15:57

refactor: rename to arc-0027

37e3be4

Fix Linting

0726fe7

drichar reviewed Jan 19, 2024

View reviewed changes

ARCs/arc-0027.md Outdated Show resolved Hide resolved

fix: correct get providers required response as per @drichar 's sugge…

e8a6729

…stions Co-authored-by: Doug Richar <[email protected]>

ehanoc reviewed Jan 24, 2024

View reviewed changes

kewde reviewed Feb 8, 2024

View reviewed changes

kieranroneill added 3 commits April 4, 2024 09:35

refactor: remove focus on web extension and strictly conform to json …

8b498ae

…schema

feat: add brief disbale description

1d0dfc5

refactor: update abstract, motivation, rationale and security conside…

0e8434d

…rations

kieranroneill changed the title ~~ARC-0027: Web Extension Provider Interface~~ ARC-0027: Provider Message Schema Apr 5, 2024

kieranroneill linked an issue Apr 5, 2024 that may be closed by this pull request

[ARC-0027] Remove explicit reference to a web extension kieranroneill/ARCs#2

Open

kieranroneill and others added 4 commits April 6, 2024 14:11

chore: squash

757b074

refactor: use more general terminology when referring to dapps

65e7fd3

refactor: make provider id a requirement for post-like transactions

f52edd6

fix links

39fdb1a

SudoWeezy and others added 2 commits April 8, 2024 12:19

fix linting

a76788f

feat: add sign message schema to sign arbitrary strings

82e003b

kieranroneill linked an issue Apr 24, 2024 that may be closed by this pull request

[ARC-0027] Add sign message schema kieranroneill/ARCs#3

Open

feat: make signer optional for sign message params

4c06bae

PhearZero reviewed Jul 15, 2024

View reviewed changes

fix: replace response message schema id

18268a7

Status -> Review

4b96501

github-actions bot added s-review and removed s-draft labels Sep 6, 2024

drichar reviewed Sep 10, 2024

View reviewed changes

refcator: enforce provider id for signing and connection methods

68ad15e

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

ARC-0027: Provider Message Schema #272

ARC-0027: Provider Message Schema #272

kieranroneill commented Jan 12, 2024 •

edited

Loading

ehanoc left a comment

ehanoc Jan 24, 2024

ehanoc Jan 24, 2024

ehanoc Jan 24, 2024

kieranroneill Feb 5, 2024

ehanoc Jan 24, 2024

kieranroneill Feb 5, 2024

kewde Feb 8, 2024

kewde Feb 8, 2024 •

edited

Loading

kewde Feb 8, 2024 •

edited

Loading

kewde Feb 8, 2024

kewde Feb 8, 2024

PhearZero Jul 15, 2024

kieranroneill Jul 16, 2024

PhearZero Jul 16, 2024

SudoWeezy commented Sep 5, 2024

kieranroneill commented Sep 5, 2024 •

edited

Loading

drichar left a comment

drichar Sep 10, 2024

drichar Sep 10, 2024


		The dapp will, itself, listen to broadcasted responses from any providers. Below is a simple diagram for the flow of data for an enable request:

		![Simple BroadcastChannel API using web extensions](../assets/arc-0027/simple_message_bus.png)


		## Abstract

		Building off of the previous ARCs relating to; wallet transaction signing ([ARC-0005](./arc-0005.md#specification)), wallet address discovery ([ARC-0006](./arc-0006.md#specification)), wallet transaction network posting ([ARC-0007](./arc-0007.md#specification)) and wallet transaction signing & posting ([ARC-0008](./arc-0008.md#specification)), this proposal aims to extend and comprehensively outline a common interface between multiple web extension wallets and dapps by utilizing the pub/sub semantics of the <a href="https://developer.mozilla.org/en-US/docs/Web/API/Broadcast_Channel_API">BroadcastChannel API</a>.

ARC-0027: Provider Message Schema #272

Are you sure you want to change the base?

ARC-0027: Provider Message Schema #272

Conversation

kieranroneill commented Jan 12, 2024 • edited Loading

Summary

ehanoc left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

kewde Feb 8, 2024 • edited Loading

Choose a reason for hiding this comment

kewde Feb 8, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

SudoWeezy commented Sep 5, 2024

kieranroneill commented Sep 5, 2024 • edited Loading

drichar left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

kieranroneill commented Jan 12, 2024 •

edited

Loading

kewde Feb 8, 2024 •

edited

Loading

kewde Feb 8, 2024 •

edited

Loading

kieranroneill commented Sep 5, 2024 •

edited

Loading