From 2344a4287666b17dd41d163fdb3ea9aa5335e6ec Mon Sep 17 00:00:00 2001 From: Kieran O'Neill Date: Tue, 9 Apr 2024 08:06:12 +0100 Subject: [PATCH] docs: add tutorials for signing and posting transactions --- docs/clients/disabling-a-client.mdx | 10 +- docs/clients/enabling-a-client.mdx | 8 +- docs/clients/index.md | 3 +- docs/clients/posting-transactions.mdx | 10 +- .../signing-and-posting-transactions.mdx | 169 ++++++++++++++++++ docs/providers/index.md | 3 +- ...to-sign-and-post-transactions-requests.mdx | 70 ++++++++ docs/scripts/sidebars.js | 4 +- 8 files changed, 263 insertions(+), 14 deletions(-) create mode 100644 docs/clients/signing-and-posting-transactions.mdx create mode 100644 docs/providers/responding-to-sign-and-post-transactions-requests.mdx diff --git a/docs/clients/disabling-a-client.mdx b/docs/clients/disabling-a-client.mdx index 85f8d11..76e9f93 100644 --- a/docs/clients/disabling-a-client.mdx +++ b/docs/clients/disabling-a-client.mdx @@ -54,7 +54,7 @@ client.disable(); ```typescript -import type { BaseARC0027Error, IDisableResult } from '@agoralabs-sh/avm-web-provider'; +import { BaseARC0027Error, IDisableResult } from '@agoralabs-sh/avm-web-provider'; // initialized client client.onDisable((result: IDisableResult: null, error: BaseARC0027Error | null) => { @@ -83,7 +83,7 @@ client.disable(); :::caution -If any providers do not support the `disable` method, then a [`MethodNotSupportedError`](../../api-reference/errors#methodnotsupportederror) will be returned. +If any providers do not support the `disable` method, then a [`MethodNotSupportedError`](../../api-reference/errors#methodnotsupportederror) should be returned. ::: @@ -128,7 +128,7 @@ client.disable({ ```typescript -import type { BaseARC0027Error, IDisableResult } from '@agoralabs-sh/avm-web-provider'; +import { BaseARC0027Error, IDisableResult } from '@agoralabs-sh/avm-web-provider'; const providerId: string = '02657eaf-be17-4efc-b0a4-19d654b2448e'; @@ -162,7 +162,7 @@ client.disable({ :::caution -If the network and the provider ID is specified, and the provider does not support the network, then a [`NetworkNotSupportedError`](../../api-reference/errors#networknotsupportederror) will be thrown. +If the network and the provider ID is specified, and the provider does not support the network, then a [`NetworkNotSupportedError`](../../api-reference/errors#networknotsupportederror) should be thrown. ::: @@ -208,7 +208,7 @@ client.disable({ ```typescript -import type { BaseARC0027Error, IDisableResult } from '@agoralabs-sh/avm-web-provider'; +import { BaseARC0027Error, IDisableResult } from '@agoralabs-sh/avm-web-provider'; // initialized client client.onEnable((result: IDisableResult: null, error: BaseARC0027Error | null) => { diff --git a/docs/clients/enabling-a-client.mdx b/docs/clients/enabling-a-client.mdx index 21d40cb..9a7928d 100644 --- a/docs/clients/enabling-a-client.mdx +++ b/docs/clients/enabling-a-client.mdx @@ -78,7 +78,7 @@ client.enable(); ```typescript -import type { BaseARC0027Error, IEnableResult } from '@agoralabs-sh/avm-web-provider'; +import { BaseARC0027Error, IEnableResult } from '@agoralabs-sh/avm-web-provider'; // initialized client client.onEnable((result: IEnableResult: null, error: BaseARC0027Error | null) => { @@ -174,7 +174,7 @@ client.enable({ providerId }); ```typescript -import type { BaseARC0027Error, IEnableResult } from '@agoralabs-sh/avm-web-provider'; +import { BaseARC0027Error, IEnableResult } from '@agoralabs-sh/avm-web-provider'; const providerId: string = '02657eaf-be17-4efc-b0a4-19d654b2448e'; @@ -266,7 +266,7 @@ client.enable({ genesisHash }); ```typescript -import type { BaseARC0027Error, IEnableResult } from '@agoralabs-sh/avm-web-provider'; +import { BaseARC0027Error, IEnableResult } from '@agoralabs-sh/avm-web-provider'; const genesisHash: string = 'SGO1GKSzyE7IEPItTxCByw9x8FmnrCDexi9/cOUJOiI='; @@ -308,6 +308,6 @@ client.enable({ genesisHash }); :::caution -If the network and the provider ID is specified, and the provider does not support the network, then a [`NetworkNotSupportedError`](../../api-reference/errors#networknotsupportederror) will be thrown. +If the network and the provider ID is specified, and the provider does not support the network, then a [`NetworkNotSupportedError`](../../api-reference/errors#networknotsupportederror) should be thrown. ::: diff --git a/docs/clients/index.md b/docs/clients/index.md index ddcc3cd..f84b272 100644 --- a/docs/clients/index.md +++ b/docs/clients/index.md @@ -3,5 +3,6 @@ * [Getting Started](clients/getting-started) * [Discover Providers](clients/discover-providers) * [Enabling A Client](clients/enabling-a-client) -* [Posting Transactions](clients/posting-transactions) * [Disabling A Client](clients/disabling-a-client) +* [Posting Transactions](clients/posting-transactions) +* [Signing And Posting Transactions](clients/signing-and-posting-transactions) diff --git a/docs/clients/posting-transactions.mdx b/docs/clients/posting-transactions.mdx index 2392697..0688724 100644 --- a/docs/clients/posting-transactions.mdx +++ b/docs/clients/posting-transactions.mdx @@ -62,7 +62,7 @@ client.postTransactions({ ```typescript -import type { BaseARC0027Error, IPostTransactionsResult } from '@agoralabs-sh/avm-web-provider'; +import { BaseARC0027Error, IPostTransactionsResult } from '@agoralabs-sh/avm-web-provider'; // initialized client client.onPostTransactions((result: IPostTransactionsResult: null, error: BaseARC0027Error | null) => { @@ -97,6 +97,12 @@ client.postTransactions({ :::caution -If this method is not supported, then a [`MethodNotSupportedError`](../../api-reference/errors#wmethodnotsupportederror) will be thrown. +If this method is not supported, then a [`MethodNotSupportedError`](../../api-reference/errors#methodnotsupportederror) should be thrown. + +::: + +:::caution + +If the transactions fail to be accepted by the network, then a [`FailedToPostSomeTransactionsError`](../../api-reference/errors#failedtopostsometransactionserror) should be thrown. ::: diff --git a/docs/clients/signing-and-posting-transactions.mdx b/docs/clients/signing-and-posting-transactions.mdx new file mode 100644 index 0000000..a10558c --- /dev/null +++ b/docs/clients/signing-and-posting-transactions.mdx @@ -0,0 +1,169 @@ +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import TOCInline from '@theme/TOCInline'; + +# Signing And Posting Transactions + + + +## Overview + +Providers may have the functionality to both sign & post transactions. This method allows clients to avoid using the previous methods of [signing transactions](signing-transactions) and [posting transactions](posting-transactions) separately and simply performs the functionality of these previous methods within one method. + +## Sending transactions to be signed & posted to the provider + + + + +```js +const algosdk = require('algosdk'); + +// create a transaction +try { + const client = new algosdk.Algodv2( + 'aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa', + 'http://localhost', + '4001', + ); + const encoder = new TextEncoder(); + const suggestedParams = await client.getTransactionParams().do(); + const transaction = algosdk.makePaymentTxnWithSuggestedParamsFromObject({ + amount: algosdk.algosToMicroalgos(1), + from: 'P3AIQVDJ2CTH54KSJE63YWB7IZGS4W4JGC53I6GK72BGZ5BXO2B2PS4M4U', + note: encoder.encode('Hello Human!'), + suggestedParams, + to: '6GT6EXFDAHZDZYUOPT725ZRWYBZDCEGYT7SYYXGJKRFUAG5B7JMI7DQRNQ', + }); + const transactionBytes = transaction.toByte(); +} catch (error) { + // handle error +} + +// initialized client +client.onSignAndPostTransactions((result, error) => { + if (error) { + console.error('error:', error); + + return; + } + + console.log(result); + /* + { + providerId: '02657eaf-be17-4efc-b0a4-19d654b2448e', + txnIDs: [ + 'OKU6A2Q...', + ], + } + */ +}); + +// broadcast a sign and post transactions request +client.signAndPostTransactions({ + providerId: '02657eaf-be17-4efc-b0a4-19d654b2448e', + txns: [ + { + txn: btoa(String.fromCodePoint(...transactionBytes)), // convert to base64 string + }, + ], +}); +``` + + + + +```typescript +import { + Algodv2, + algosToMicroalgos, + makePaymentTxnWithSuggestedParamsFromObject, + SuggestedParams, + Transaction, +} from 'algosdk'; +import { BaseARC0027Error, IPostTransactionsResult } from '@agoralabs-sh/avm-web-provider'; + +// create a transaction +try { + const client: Algodv2 = new Algodv2( + 'aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa', + 'http://localhost', + '4001', + ); + const encoder: TextEncoder = new TextEncoder(); + const suggestedParams: SuggestedParams = await client.getTransactionParams().do(); + const transaction: Transaction = makePaymentTxnWithSuggestedParamsFromObject({ + amount: algosToMicroalgos(1), + from: 'P3AIQVDJ2CTH54KSJE63YWB7IZGS4W4JGC53I6GK72BGZ5BXO2B2PS4M4U', + note: encoder.encode('Hello Human!'), + suggestedParams, + to: '6GT6EXFDAHZDZYUOPT725ZRWYBZDCEGYT7SYYXGJKRFUAG5B7JMI7DQRNQ', + }); + const transactionBytes: Uint8Array = transaction.toByte(); +} catch (error) { + // handle error +} + +// initialized client +client.onSignAndPostTransactions((result: IPostTransactionsResult: null, error: BaseARC0027Error | null) => { + if (error) { + console.error('error:', error); + + return; + } + + console.log(result); + /* + { + providerId: '02657eaf-be17-4efc-b0a4-19d654b2448e', + txnIDs: [ + 'OKU6A2Q...', + ], + } + */ +}); + +// broadcast a sign and post transactions request +client.signAndPostTransactions({ + providerId: '02657eaf-be17-4efc-b0a4-19d654b2448e', + txns: [ + { + txn: btoa(String.fromCodePoint(...transactionBytes)), // convert to base64 string + }, + ], +}); +``` + + + + +:::caution + +If this method is not supported, then a [`MethodNotSupportedError`](../../api-reference/errors#methodnotsupportederror) should be thrown. + +::: + +:::caution + +If there are a group of atomic transactions, but a computed group ID is invalid, then a [`InvalidGroupIdError`](../../api-reference/errors#invalidgroupiderror) or a [`InvalidInputError`](../../api-reference/errors#invalidinputerror) should be thrown. + +::: + +:::caution + +If any of the transactions are malformed, then a [`InvalidInputError`](../../api-reference/errors#invalidinputerror) may be thrown. + +::: + +:::caution + +If the transactions fail to be accepted by the network, then a [`FailedToPostSomeTransactionsError`](../../api-reference/errors#failedtopostsometransactionserror) should be thrown. + +::: diff --git a/docs/providers/index.md b/docs/providers/index.md index e03d790..e57a73a 100644 --- a/docs/providers/index.md +++ b/docs/providers/index.md @@ -4,4 +4,5 @@ * [Responding To Discover Requests](providers/responding-to-discover-requests) * [Responding To Enable Requests](providers/responding-to-enable-requests) * [Responding To Disable Requests](providers/responding-to-disable-requests) -* [Responding To Enable Requests](providers/responding-to-post-transactions-requests) +* [Responding To Post Requests](providers/responding-to-post-transactions-requests) +* [Responding To Sign And Post Requests](providers/responding-to-sign-and-post-transactions-requests) diff --git a/docs/providers/responding-to-sign-and-post-transactions-requests.mdx b/docs/providers/responding-to-sign-and-post-transactions-requests.mdx new file mode 100644 index 0000000..d48de1a --- /dev/null +++ b/docs/providers/responding-to-sign-and-post-transactions-requests.mdx @@ -0,0 +1,70 @@ +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import TOCInline from '@theme/TOCInline'; + +# Responding To Sign And Post Transactions Requests + + + +## Overview + +If your provider is able to both sign and post transactions, this method can simply be implemented to allow clients to perform both these methods within one method. + +## Responding to a sign and post transactions request + +Once our provider object has been initialized, we can simply listen to events and respond: + + + + +```js +const providerId = '02657eaf-be17-4efc-b0a4-19d654b2448e'; + +// initialized provider +provider.onSignAndPostTransactions((params) => { + if (params.providerId === providerId) { + // ... using the `params.txns` parameter, the provider signs and posts the transactions to the network and returns the transaction ids + + return { + providerId, + txnIDs: [ + 'OKU6A2Q...', + ], + }; + } +}); +``` + + + + +```typescript +import type { ISignTransactionsParams } from '@agoralabs-sh/avm-web-provider'; + +const providerId: string = '02657eaf-be17-4efc-b0a4-19d654b2448e'; + +// initialized provider +provider.onPostTransactions((params: ISignTransactionsParams) => { + if (params.providerId === providerId) { + // ... using the `params.txns` parameter, the provider signs and posts the transactions to the network and returns the transaction ids + + return { + providerId, + txnIDs: [ + 'OKU6A2Q...', + ], + }; + } +}); +``` + + + diff --git a/docs/scripts/sidebars.js b/docs/scripts/sidebars.js index 1457941..f4694ae 100644 --- a/docs/scripts/sidebars.js +++ b/docs/scripts/sidebars.js @@ -10,8 +10,9 @@ const sidebars = { 'clients/getting-started', 'clients/discover-providers', 'clients/enabling-a-client', - 'clients/posting-transactions', 'clients/disabling-a-client', + 'clients/posting-transactions', + 'clients/signing-and-posting-transactions', ], label: 'Clients', link: { @@ -27,6 +28,7 @@ const sidebars = { 'providers/responding-to-enable-requests', 'providers/responding-to-disable-requests', 'providers/responding-to-post-transactions-requests', + 'providers/responding-to-sign-and-post-transactions-requests', ], label: 'Providers', link: {