From 244273a8dcafb021cb83b59420a572e5c2cfedeb Mon Sep 17 00:00:00 2001 From: Ravinda Date: Wed, 24 Aug 2022 16:26:49 +0530 Subject: [PATCH 1/7] Update: Improve a guide about how to use executeTx and ExecParams --- docs/guide/execute-transaction.md | 55 ++++++++++++++++++++++++++++--- packages/algob/src/types.ts | 4 ++- packages/runtime/src/runtime.ts | 5 +-- packages/web/src/lib/web-mode.ts | 2 ++ 4 files changed, 59 insertions(+), 7 deletions(-) diff --git a/docs/guide/execute-transaction.md b/docs/guide/execute-transaction.md index c14c8d25c..f91f51844 100644 --- a/docs/guide/execute-transaction.md +++ b/docs/guide/execute-transaction.md @@ -4,8 +4,7 @@ layout: splash # Execute Transaction -`executeTx` is a high level method of Deployer which can be used to perform transactions on Algorand Network. It supports every transaction (atomic or single) which is possible in network. Ex: Deploy ASA/App, Opt-In, Transfers, Delete, Destroy etc. `executeTx` takes `ExecParams[]` as parameter. -If the length of `ExecParams` array is greater than one, it will be considered as `atomic transaction`. +`executeTx` is a high level method of Deployer which can be used to perform transactions on Algorand Network. It supports every transaction (atomic or single) which is possible in network. Ex: Deploy ASA/App, Opt-In, Transfers, Delete, Destroy etc. `executeTx` takes `ExecParams[]` as parameter. If the length of `ExecParams` array is greater than one, it will be considered as `atomic transaction` otherwise `single transaction`. In below sections we will demonstrate how to pass these parameters. Note: For each parameter `type` and `sign` attributes are mandatory. @@ -15,6 +14,35 @@ Note: For each parameter `type` and `sign` attributes are mandatory. Depending on the transaction `type`, other attributes will specify a signer of the transaction. For example, for `TransactionType.TransferAlgo` the `fromAccount` must be a full account (with secret key) and will sign the transaction. +`deployer.executeTx` returns list of `TxnReceipt`, which extends `ConfirmedTxInfo`. + +```js +const receipts = deployer.executeTx([txn0, txn1]); +console.log("txn0 information: ", receipts[0]); +console.log("txn1 information: ", receipts[2]); +``` + +Below examples demonstrates, how to perform application call using `ExecParam` and `WebMode`. + +```js +appCall = () => { + const webMode: WebMode = new WebMode(AlgoSigner, networkType); + const tx: types.ExecParams[] = [ + { + type: types.TransactionType.CallApp, + sign: types.SignType.SecretKey, + fromAccount: { + addr: addr, + sk: new Uint8Array(0), + }, + appID: 100, + payFlags: {}, + }, + ]; + webMode.executeTx(tx); + }; +``` + ## Examples [`ExecParams`](https://algobuilder.dev/api/algob/modules/runtime.types.html#ExecParams) usage: #### [Transfer Algo using secret key](https://algobuilder.dev/api/algob/modules/runtime.types.html#AlgoTransferParam) @@ -26,7 +54,8 @@ Depending on the transaction `type`, other attributes will specify a signer of t fromAccount: john, toAccountAddr: alice.address, amountMicroAlgos: 100, - payFlags: { totalFee: fee } } + payFlags: { totalFee: fee } + } ``` - payFlags: [TxParams](https://algobuilder.dev/api/algob/interfaces/runtime.types.TxParams.html) @@ -261,7 +290,12 @@ Even though fee paid by alice is `0`, this transaction will pass because total f ## Sign and Send SDK Transaction object using `executeTx` method -`deployer.executeTx` method supports signing and sending sdk transaction objects. To do this you will have to pass an [`TransactionAndSign`](https://algobuilder.dev/api/web/interfaces/types.TransactionAndSign.html) object which has `transaction` and `sign`. Ex: +`deployer.executeTx` method supports signing and sending sdk transaction objects. To do this you will have to pass an [`TransactionAndSign`](https://algobuilder.dev/api/web/interfaces/types.TransactionAndSign.html) object which has following properties: + +- `type`: type of transaction. +- `sign`: signature [`types`](https://github.com/scale-it/algo-builder/blob/2bcef8f611b349dfb8dc3542ed2f0a129a0c405c/packages/web/src/types.ts#L117). + +Ex: ```js const tx = makeAssetCreateTxn( @@ -270,6 +304,7 @@ const tx = makeAssetCreateTxn( undefined, mockSuggestedParam.genesisHash, mockSuggestedParam.genesisID, 1e6, 0, false, undefined, undefined, undefined, undefined, "UM", "ASM", undefined ); + const transaction: wtypes.TransactionAndSign = { transaction: tx, sign: {sign: wtypes.SignType.SecretKey, fromAccount: bobAcc} @@ -280,6 +315,18 @@ const res = await deployer.executeTx([transaction]); You can check the implementation in [asa](https://github.com/scale-it/algo-builder/blob/master/examples/asa/scripts/2-gold-asc.js) example. +There is also a function to check if given object implements `Transaction` class and has `Sign`. + +```js +export function isSDKTransactionAndSign(object: unknown): object is TransactionAndSign { + if (object === undefined || object === null) { + return false; + } + const res = isSDKTransaction((object as TransactionAndSign).transaction); + return Object.prototype.hasOwnProperty.call(object, "sign") && res; +} +``` + ### SignTransactions function This function takes array of [`TransactionAndSign`](https://algobuilder.dev/api/web/interfaces/types.TransactionAndSign.html) objects and returns raw signed transaction diff --git a/packages/algob/src/types.ts b/packages/algob/src/types.ts index 6622fe2b2..68d5d6f77 100644 --- a/packages/algob/src/types.ts +++ b/packages/algob/src/types.ts @@ -716,7 +716,9 @@ export interface Deployer { * executes `ExecParams` or `Transaction` Object, SDK Transaction object passed to this function * will be signed and sent to network. User can use SDK functions to create transactions. * Note: If passing transaction object a signer/s must be provided. - * @param transactionParam transaction parameters or atomic transaction parameters + * Check out {@link https://algobuilder.dev/guide/execute-transaction.html#execute-transaction|execute-transaction} + * for more info. + * @param transactions transaction parameters or atomic transaction parameters * https://github.com/scale-it/algo-builder/blob/docs/docs/guide/execute-transaction.md * or TransactionAndSign object(SDK transaction object and signer parameters) */ diff --git a/packages/runtime/src/runtime.ts b/packages/runtime/src/runtime.ts index 41fbaac25..f7b5f6168 100644 --- a/packages/runtime/src/runtime.ts +++ b/packages/runtime/src/runtime.ts @@ -850,8 +850,9 @@ export class Runtime { } /** - * This function executes a transaction based on a smart - * contract logic and updates state afterwards + * This function executes a transaction based on a smart contract logic and updates state afterwards + * Check out {@link https://algobuilder.dev/guide/execute-transaction.html#execute-transaction|execute-transaction} + * for more info. * @param txnParams : Transaction parameters * @param debugStack: if passed then TEAL Stack is logged to console after * each opcode execution (upto depth = debugStack) diff --git a/packages/web/src/lib/web-mode.ts b/packages/web/src/lib/web-mode.ts index 7a3923375..e881cecad 100644 --- a/packages/web/src/lib/web-mode.ts +++ b/packages/web/src/lib/web-mode.ts @@ -151,6 +151,8 @@ export class WebMode { /** * Execute single transaction or group of transactions (atomic transaction) + * Check out {@link https://algobuilder.dev/guide/execute-transaction.html#execute-transaction|execute-transaction} + * for more info. * @param transactions transaction parameters, atomic transaction parameters * or TransactionAndSign object(SDK transaction object and signer parameters). * When list of ExecParams is used, the function will request wallet to sign transactions. From 13bb8454ceb9ceeeb649bdc2d053bdee366321d9 Mon Sep 17 00:00:00 2001 From: Ravinda Date: Wed, 24 Aug 2022 19:41:43 +0530 Subject: [PATCH 2/7] SignedTransaction --- docs/guide/execute-transaction.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/guide/execute-transaction.md b/docs/guide/execute-transaction.md index f91f51844..142dfa5f0 100644 --- a/docs/guide/execute-transaction.md +++ b/docs/guide/execute-transaction.md @@ -4,7 +4,7 @@ layout: splash # Execute Transaction -`executeTx` is a high level method of Deployer which can be used to perform transactions on Algorand Network. It supports every transaction (atomic or single) which is possible in network. Ex: Deploy ASA/App, Opt-In, Transfers, Delete, Destroy etc. `executeTx` takes `ExecParams[]` as parameter. If the length of `ExecParams` array is greater than one, it will be considered as `atomic transaction` otherwise `single transaction`. +`executeTx` is a high level method of Deployer which can be used to perform transactions on Algorand Network. It supports every transaction (atomic or single) which is possible in network. Ex: Deploy ASA/App, Opt-In, Transfers, Delete, Destroy etc. `executeTx` takes `ExecParams[]` or `SignedTransaction[]` as parameter. If the length of `ExecParams` array is greater than one, it will be considered as `atomic transaction` otherwise `single transaction`. In below sections we will demonstrate how to pass these parameters. Note: For each parameter `type` and `sign` attributes are mandatory. From 8925877734988b1b8dc4140792f8f1dc4381dfaa Mon Sep 17 00:00:00 2001 From: Ravinda Date: Wed, 24 Aug 2022 20:05:38 +0530 Subject: [PATCH 3/7] SignedTransaction example --- docs/guide/execute-transaction.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/docs/guide/execute-transaction.md b/docs/guide/execute-transaction.md index 142dfa5f0..9a3ab9cd6 100644 --- a/docs/guide/execute-transaction.md +++ b/docs/guide/execute-transaction.md @@ -43,6 +43,14 @@ appCall = () => { }; ``` +Below examples demonstrates, how to use `SignedTransaction` and `executeTx` in runtime. + +```js + const tx: Transaction = decodeSignedTransaction(rawTxns).txn; + let signedTx: SignedTransaction = {txn: tx}; + runtime.executeTx(signedTx); +``` + ## Examples [`ExecParams`](https://algobuilder.dev/api/algob/modules/runtime.types.html#ExecParams) usage: #### [Transfer Algo using secret key](https://algobuilder.dev/api/algob/modules/runtime.types.html#AlgoTransferParam) From 3cad5a90e0b9fc096bf94e9c8a88742c489b0dc4 Mon Sep 17 00:00:00 2001 From: Ravindra Meena Date: Wed, 24 Aug 2022 21:58:06 +0530 Subject: [PATCH 4/7] Update docs/guide/execute-transaction.md Co-authored-by: Robert Zaremba --- docs/guide/execute-transaction.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/guide/execute-transaction.md b/docs/guide/execute-transaction.md index 9a3ab9cd6..9ec8d718a 100644 --- a/docs/guide/execute-transaction.md +++ b/docs/guide/execute-transaction.md @@ -22,7 +22,7 @@ console.log("txn0 information: ", receipts[0]); console.log("txn1 information: ", receipts[2]); ``` -Below examples demonstrates, how to perform application call using `ExecParam` and `WebMode`. +Below we demonstrate how to perform application call using `ExecParam` and `WebMode`: ```js appCall = () => { From 9bff6efbfb79de389dc7bbb6a7bc58e6711e7fab Mon Sep 17 00:00:00 2001 From: Ravindra Meena Date: Wed, 24 Aug 2022 21:58:24 +0530 Subject: [PATCH 5/7] Update docs/guide/execute-transaction.md Co-authored-by: Robert Zaremba --- docs/guide/execute-transaction.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/guide/execute-transaction.md b/docs/guide/execute-transaction.md index 9ec8d718a..df6832692 100644 --- a/docs/guide/execute-transaction.md +++ b/docs/guide/execute-transaction.md @@ -43,7 +43,7 @@ appCall = () => { }; ``` -Below examples demonstrates, how to use `SignedTransaction` and `executeTx` in runtime. +We can also use `SignedTransaction` and `executeTx` in runtime: ```js const tx: Transaction = decodeSignedTransaction(rawTxns).txn; From 7726f591d872f4c1c746af1d0d3086a3981a6185 Mon Sep 17 00:00:00 2001 From: Ravinda Date: Mon, 29 Aug 2022 15:59:33 +0530 Subject: [PATCH 6/7] Exec params --- docs/guide/execute-transaction.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/docs/guide/execute-transaction.md b/docs/guide/execute-transaction.md index df6832692..11a912d3f 100644 --- a/docs/guide/execute-transaction.md +++ b/docs/guide/execute-transaction.md @@ -4,7 +4,7 @@ layout: splash # Execute Transaction -`executeTx` is a high level method of Deployer which can be used to perform transactions on Algorand Network. It supports every transaction (atomic or single) which is possible in network. Ex: Deploy ASA/App, Opt-In, Transfers, Delete, Destroy etc. `executeTx` takes `ExecParams[]` or `SignedTransaction[]` as parameter. If the length of `ExecParams` array is greater than one, it will be considered as `atomic transaction` otherwise `single transaction`. +`executeTx` is a high level method of Deployer which can be used to perform transactions on Algorand Network. It supports every transaction (atomic or single) which is possible in network. Ex: Deploy ASA/App, Opt-In, Transfers, Delete, Destroy etc. `executeTx` takes `ExecParams[]` or `SignedTransaction[]` as parameter. In below sections we will demonstrate how to pass these parameters. Note: For each parameter `type` and `sign` attributes are mandatory. @@ -51,7 +51,9 @@ We can also use `SignedTransaction` and `executeTx` in runtime: runtime.executeTx(signedTx); ``` -## Examples [`ExecParams`](https://algobuilder.dev/api/algob/modules/runtime.types.html#ExecParams) usage: +## ExecParams + +If the length of `ExecParams` array is greater than one, it will be considered as `atomic transaction` otherwise `single transaction`.Examples of [`ExecParams`](https://algobuilder.dev/api/algob/modules/runtime.types.html#ExecParams) usage. #### [Transfer Algo using secret key](https://algobuilder.dev/api/algob/modules/runtime.types.html#AlgoTransferParam) From c2aeca5d6c7ce4a37861edba81c89e7275135485 Mon Sep 17 00:00:00 2001 From: Ravinda Date: Mon, 29 Aug 2022 16:05:38 +0530 Subject: [PATCH 7/7] Signed txn --- docs/guide/execute-transaction.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/guide/execute-transaction.md b/docs/guide/execute-transaction.md index 11a912d3f..66d8fd18a 100644 --- a/docs/guide/execute-transaction.md +++ b/docs/guide/execute-transaction.md @@ -53,7 +53,7 @@ We can also use `SignedTransaction` and `executeTx` in runtime: ## ExecParams -If the length of `ExecParams` array is greater than one, it will be considered as `atomic transaction` otherwise `single transaction`.Examples of [`ExecParams`](https://algobuilder.dev/api/algob/modules/runtime.types.html#ExecParams) usage. +If the length of `ExecParams` array is greater than one, it will be considered as `atomic transaction` otherwise `single transaction`.Examples of [`ExecParams`](https://algobuilder.dev/api/algob/modules/runtime.types.html#ExecParams) usage. `ExecParams` is preferred when there is a transaction which is not already signed and want to be executed. #### [Transfer Algo using secret key](https://algobuilder.dev/api/algob/modules/runtime.types.html#AlgoTransferParam) @@ -339,7 +339,7 @@ export function isSDKTransactionAndSign(object: unknown): object is TransactionA ### SignTransactions function -This function takes array of [`TransactionAndSign`](https://algobuilder.dev/api/web/interfaces/types.TransactionAndSign.html) objects and returns raw signed transaction +This function takes array of [`TransactionAndSign`](https://algobuilder.dev/api/web/interfaces/types.TransactionAndSign.html) objects and returns raw signed transaction. `SignedTransaction` is preferred when there is a transaction which is already signed and has to be sent to network. ```js const transaction: wtypes.TransactionAndSign = [{