feat: implement sign message method (#28)

* feat: implement sign message functionality * docs: add tutorials on signing a message * docs: update mentions of old types to use new types * docs: update readme to reflect use of event target * chore: squash
agoralabs-sh · Apr 24, 2024 · ef1e929 · ef1e929
1 parent fe34735
commit ef1e929
Show file tree

Hide file tree

Showing 31 changed files with 460 additions and 62 deletions.
diff --git a/README.md b/README.md
@@ -109,7 +109,7 @@ This will compile the Typescript source code into a `dist/` directory.
 
 ### 4.1. Useful Information
 
-* [ARC-0027][arc-0027]: this code is an implementation of ARC-0027 and leverages the [BroadcastChannel][boradcastchannel] API as a message bus between the webpage (dApp) and a web-based provider (wallet).
+* [ARC-0027][arc-0027]: this code is an implementation of the ARC-0027 spec and leverages the [EventTarget][event-target] as a message bus between the webpage (dApp) and a web-based provider (wallet).
 
 <sup>[Back to top ^][table-of-contents]</sup>
 
@@ -156,7 +156,7 @@ Please refer to the [LICENSE][license] file.
 
 <!-- Links -->
 [arc-0027]: https://github.com/algorandfoundation/ARCs/blob/main/ARCs/arc-0027.md
-[boradcastchannel]: https://developer.mozilla.org/en-US/docs/Web/API/Broadcast_Channel_API
+[event-target]: https://developer.mozilla.org/en-US/docs/Web/API/EventTarget
 [contribute]: ./CONTRIBUTING.md
 [documentation]: https://avm-web-provider.agoralabs.sh
 [license]: ./LICENSE

diff --git a/docs/api-reference/avm-web-client.mdx b/docs/api-reference/avm-web-client.mdx
@@ -166,6 +166,16 @@ import TOCInline from '@theme/TOCInline';
 |----------|-------------------------|
 | `string` | the ID of the listener. |
 
+### `onSignMessage(callback)`
+
+> Listens to `sign_message` messages sent from providers.
+
+#### Parameters
+
+| Name     | Type                                                                                                             | Required | Default | Description                                                                                                                   |
+|----------|------------------------------------------------------------------------------------------------------------------|----------|---------|-------------------------------------------------------------------------------------------------------------------------------|
+| callback | (`options`: [`IAVMWebClientCallbackOptions`](types#iavmwebclientcallbackoptions)) => (`void` \| `Promise<void>`) | yes      | -       | The callback is called when a response message is received. If the result was successful, the `error` parameter will be null. |
+
 ### `onSignTransactions(callback)`
 
 > Listens to `sign_transactions` messages sent from providers.
@@ -240,6 +250,22 @@ import TOCInline from '@theme/TOCInline';
 |----------|--------------------------------|
 | `string` | the ID of the request message. |
 
+### `signMessage([params])`
+
+> Request providers sign a UTF-8 encoded message.
+
+#### Parameters
+
+| Name   | Type                                             | Required | Default | Description                                                           |
+|--------|--------------------------------------------------|----------|---------|-----------------------------------------------------------------------|
+| params | [`ISignMessageParams`](types#isignmessageparams) | yes      | -       | Params that specify the message to sign, the signer and the provider. |
+
+#### Returns
+
+| Type     | Description                    |
+|----------|--------------------------------|
+| `string` | the ID of the request message. |
+
 ### `signTransactions([params])`
 
 > Request providers to sign a list of unsigned transactions.

diff --git a/docs/api-reference/avm-web-provider.mdx b/docs/api-reference/avm-web-provider.mdx
@@ -56,7 +56,7 @@ import TOCInline from '@theme/TOCInline';
 
 ### `onDiscover(callback)`
 
-> Listens to `discover` messages sent from clients. This will replace any previous set listeners. If null is supplied, the listener will be removed.
+> Listens to `discover` messages sent from clients.
 
 #### Parameters
 
@@ -72,7 +72,7 @@ import TOCInline from '@theme/TOCInline';
 
 ### `onEnable(callback)`
 
-> Listens to `enable` messages sent from clients. This will replace any previous set listeners. If null is supplied, the listener will be removed.
+> Listens to `enable` messages sent from clients.
 
 #### Parameters
 
@@ -88,7 +88,7 @@ import TOCInline from '@theme/TOCInline';
 
 ### `onPostTransactions(callback)`
 
-> Listens to `post_transactions` messages sent from clients. This will replace any previous set listeners. If null is supplied, the listener will be removed.
+> Listens to `post_transactions` messages sent from clients.
 
 #### Parameters
 
@@ -104,7 +104,7 @@ import TOCInline from '@theme/TOCInline';
 
 ### `onSignAndPostTransactions(callback)`
 
-> Listens to `sign_and_post_transactions` messages sent from clients. This will replace any previous set listeners. If null is supplied, the listener will be removed.
+> Listens to `sign_and_post_transactions` messages sent from clients.
 
 #### Parameters
 
@@ -118,9 +118,19 @@ import TOCInline from '@theme/TOCInline';
 |----------|-------------------------|
 | `string` | the ID of the listener. |
 
+### `onSignMessage(callback)`
+
+> Listens to `sign_message` messages sent from clients.
+
+#### Parameters
+
+| Name     | Type                                                                                                                                                                                                      | Required | Default | Description                                            |
+|----------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------|---------|--------------------------------------------------------|
+| callback | (`options`: [`IAVMWebProviderCallbackOptions`](types#iavmwebproviderlcallbackoptions)) => ([`ISignMessageResult`](types#isignmessageresult) \| [`Promise<ISignMessageResult>`](types#isignmessageresult)) | yes      | -       | The listener to call when the request message is sent. |
+
 ### `onSignTransactions(callback)`
 
-> Listens to `sign_transactions` messages sent from clients. This will replace any previous set listeners. If null is supplied, the listener will be removed.
+> Listens to `sign_transactions` messages sent from clients.
 
 #### Parameters
 

diff --git a/docs/api-reference/types.mdx b/docs/api-reference/types.mdx
@@ -151,6 +151,21 @@ This is the basic type for an error. For specific details on errors check out th
 | providerId | `string`   | yes      | -       | The ID of the provider.                                                                              |
 | txnIDs     | `string[]` | yes      | -       | A list of 52-character base32 strings (without padding) corresponding the completed transaction IDs. |
 
+### `ISignMessageParams`
+
+| Name       | Type     | Required | Default | Description                                 |
+|------------|----------|----------|---------|---------------------------------------------|
+| message    | `string` | yes      | -       | A human-readable UTF-8 string to sign.      |
+| providerId | `string` | no       | -       | The ID of the provider.                     |
+| signer     | `string` | yes      | -       | The address to be used to sign the message. |
+
+### `ISignMessageResult`
+
+| Name       | Type     | Required | Default | Description                                                                                 |
+|------------|----------|----------|---------|---------------------------------------------------------------------------------------------|
+| providerId | `string` | yes      | -       | The ID of the provider.                                                                     |
+| signature  | `string` | yes      | -       | A base64 encoded signature of the message signed by the private key of the intended signer. |
+
 ### `ISignTransactionsParams`
 
 | Name       | Type                    | Required | Default | Description                                       |

diff --git a/docs/clients/disabling-a-client.mdx b/docs/clients/disabling-a-client.mdx
@@ -54,10 +54,10 @@ client.disable();
   <TabItem value="typescript">
 
 ```typescript
-import { IAVMWebClientListenerOptions } from '@agoralabs-sh/avm-web-provider';
+import { IAVMWebClientCallbackOptions } from '@agoralabs-sh/avm-web-provider';
 
 // initialized client
-client.onDisable(({ error, result }: IAVMWebClientListenerOptions) => {
+client.onDisable(({ error, result }: IAVMWebClientCallbackOptions) => {
   if (error) {
     console.error('error:', error);
 
@@ -128,12 +128,12 @@ client.disable({
   <TabItem value="typescript">
 
 ```typescript
-import { IAVMWebClientListenerOptions } from '@agoralabs-sh/avm-web-provider';
+import { IAVMWebClientCallbackOptions } from '@agoralabs-sh/avm-web-provider';
 
 const providerId: string = '02657eaf-be17-4efc-b0a4-19d654b2448e';
 
 // initialized client
-client.onEnable(({ error, result }: IAVMWebClientListenerOptions) => {
+client.onEnable(({ error, result }: IAVMWebClientCallbackOptions) => {
   if (error) {
     console.error('error:', error);
 
@@ -208,10 +208,10 @@ client.disable({
   <TabItem value="typescript">
 
 ```typescript
-import { IAVMWebClientListenerOptions } from '@agoralabs-sh/avm-web-provider';
+import { IAVMWebClientCallbackOptions } from '@agoralabs-sh/avm-web-provider';
 
 // initialized client
-client.onEnable(({ error, result }: IAVMWebClientListenerOptions) => {
+client.onEnable(({ error, result }: IAVMWebClientCallbackOptions) => {
   if (error) {
     console.error('error:', error);
 

diff --git a/docs/clients/discover-providers.mdx b/docs/clients/discover-providers.mdx
@@ -76,10 +76,10 @@ client.discover();
   <TabItem value="typescript">
 
 ```typescript
-import { IAVMWebClientListenerOptions } from '@agoralabs-sh/avm-web-provider';
+import { IAVMWebClientCallbackOptions } from '@agoralabs-sh/avm-web-provider';
 
 // initialized client
-client.onDiscover(({ error, result }: IAVMWebClientListenerOptions) => {
+client.onDiscover(({ error, result }: IAVMWebClientCallbackOptions) => {
   if (error) {
     console.error('error:', error);
 
@@ -194,12 +194,12 @@ client.discover({ providerId });
   <TabItem value="typescript">
 
 ```typescript
-import { IAVMWebClientListenerOptions } from '@agoralabs-sh/avm-web-provider';
+import { IAVMWebClientCallbackOptions } from '@agoralabs-sh/avm-web-provider';
 
 const providerId: string = '02657eaf-be17-4efc-b0a4-19d654b2448e';
 
 // initialized client
-client.onDiscover(({ error, result }: IAVMWebClientListenerOptions) => {
+client.onDiscover(({ error, result }: IAVMWebClientCallbackOptions) => {
   if (error) {
     console.error('error:', error);
 

diff --git a/docs/clients/enabling-a-client.mdx b/docs/clients/enabling-a-client.mdx
@@ -78,10 +78,10 @@ client.enable();
   <TabItem value="typescript">
 
 ```typescript
-import { IAVMWebClientListenerOptions } from '@agoralabs-sh/avm-web-provider';
+import { IAVMWebClientCallbackOptions } from '@agoralabs-sh/avm-web-provider';
 
 // initialized client
-client.onEnable(({ error, result }: IAVMWebClientListenerOptions) => {
+client.onEnable(({ error, result }: IAVMWebClientCallbackOptions) => {
   if (error) {
     console.error('error:', error);
 
@@ -174,12 +174,12 @@ client.enable({ providerId });
   <TabItem value="typescript">
 
 ```typescript
-import { IAVMWebClientListenerOptions } from '@agoralabs-sh/avm-web-provider';
+import { IAVMWebClientCallbackOptions } from '@agoralabs-sh/avm-web-provider';
 
  const providerId: string = '02657eaf-be17-4efc-b0a4-19d654b2448e';
 
 // initialized client
-client.onEnable(({ error, result }: IAVMWebClientListenerOptions) => {
+client.onEnable(({ error, result }: IAVMWebClientCallbackOptions) => {
   if (error) {
     console.error('error:', error);
 
@@ -266,12 +266,12 @@ client.enable({ genesisHash });
   <TabItem value="typescript">
 
 ```typescript
-import { IAVMWebClientListenerOptions } from '@agoralabs-sh/avm-web-provider';
+import { IAVMWebClientCallbackOptions } from '@agoralabs-sh/avm-web-provider';
 
 const genesisHash: string = 'SGO1GKSzyE7IEPItTxCByw9x8FmnrCDexi9/cOUJOiI=';
 
 // initialized client
-client.onEnable(({ error, result }: IAVMWebClientListenerOptions) => {
+client.onEnable(({ error, result }: IAVMWebClientCallbackOptions) => {
   if (error) {
     console.error('error:', error);
 

diff --git a/docs/clients/index.md b/docs/clients/index.md
@@ -7,3 +7,4 @@
 * [Signing Transactions](clients/signing-transactions)
 * [Posting Transactions](clients/posting-transactions)
 * [Signing And Posting Transactions](clients/signing-and-posting-transactions)
+* [Signing A Message](clients/signing-a-message)
diff --git a/docs/clients/posting-transactions.mdx b/docs/clients/posting-transactions.mdx
@@ -62,10 +62,10 @@ client.postTransactions({
   <TabItem value="typescript">
 
 ```typescript
-import { IAVMWebClientListenerOptions } from '@agoralabs-sh/avm-web-provider';
+import { IAVMWebClientCallbackOptions } from '@agoralabs-sh/avm-web-provider';
 
 // initialized client
-client.onPostTransactions(({ error, result }: IAVMWebClientListenerOptions) => {
+client.onPostTransactions(({ error, result }: IAVMWebClientCallbackOptions) => {
   if (error) {
     console.error('error:', error);
 

diff --git a/docs/clients/signing-a-message.mdx b/docs/clients/signing-a-message.mdx
@@ -0,0 +1,96 @@
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+import TOCInline from '@theme/TOCInline';
+
+# Signing A Message
+
+<TOCInline
+  maxHeadingLevel={4}
+  toc={toc}
+/>
+
+## Overview
+
+Providers, if supported, can sign an arbitrary UTF-8 string.
+
+## Signing a message
+
+<Tabs
+  defaultValue="javascript"
+  values={[
+    { label: 'Javascript', value: 'javascript' },
+    { label: 'TypeScript', value: 'typescript' },
+  ]}>
+  <TabItem value="javascript">
+
+```js
+// initialized client
+client.onSignMessage(({ error, result }) => {
+  if (error) {
+    console.error('error:', error);
+
+    return;
+  }
+
+  console.log(result);
+  /*
+  {
+    providerId: '02657eaf-be17-4efc-b0a4-19d654b2448e',
+    signature: 'gqNzaWfEQ...',
+  }
+  */
+});
+
+// send a sign message request
+client.signMessage({
+  message: 'Hello humie!',
+  providerId: '02657eaf-be17-4efc-b0a4-19d654b2448e',
+  signer: 'P3AIQVDJ2CTH54KSJE63YWB7IZGS4W4JGC53I6GK72BGZ5BXO2B2PS4M4U',
+});
+```
+
+  </TabItem>
+  <TabItem value="typescript">
+
+```typescript
+import { IAVMWebClientCallbackOptions } from '@agoralabs-sh/avm-web-provider';
+
+// initialized client
+client.onSignMessage(({ error, result }: IAVMWebClientCallbackOptions) => {
+  if (error) {
+    console.error('error:', error);
+
+    return;
+  }
+
+  console.log(result);
+  /*
+  {
+    providerId: '02657eaf-be17-4efc-b0a4-19d654b2448e',
+    signature: 'gqNzaWfEQ...',
+  }
+  */
+});
+
+// send a sign message request
+client.signMessage({
+  message: 'Hello humie!',
+  providerId: '02657eaf-be17-4efc-b0a4-19d654b2448e',
+  signer: 'P3AIQVDJ2CTH54KSJE63YWB7IZGS4W4JGC53I6GK72BGZ5BXO2B2PS4M4U',
+});
+```
+
+  </TabItem>
+</Tabs>
+
+:::caution
+
+If this method is not supported, then a [`MethodNotSupportedError`](../../api-reference/errors#methodnotsupportederror) will be sent in the `error` parameter.
+
+:::
+
+:::caution
+
+If the signer is not known, or not authorized, then a [`UnauthorizedSignerError`](../../api-reference/errors#unauthorizedsignererror) will be sent in the `error` parameter.
+
+:::
diff --git a/docs/clients/signing-and-posting-transactions.mdx b/docs/clients/signing-and-posting-transactions.mdx
@@ -94,7 +94,7 @@ import {
   SuggestedParams,
   Transaction,
 } from 'algosdk';
-import { IAVMWebClientListenerOptions } from '@agoralabs-sh/avm-web-provider';
+import { IAVMWebClientCallbackOptions } from '@agoralabs-sh/avm-web-provider';
 
 // create a transaction
 try {
@@ -118,7 +118,7 @@ try {
 }
 
 // initialized client
-client.onSignAndPostTransactions(({ error, result }: IAVMWebClientListenerOptions) => {
+client.onSignAndPostTransactions(({ error, result }: IAVMWebClientCallbackOptions) => {
   if (error) {
     console.error('error:', error);