@algorandfoundation/algokit-utils 6.3.0-beta.1 → 7.0.0-alpha.1

package/types/algorand-client-transaction-sender.mjs

@@ -1,19 +1,25 @@
-import { Config } from '../config.mjs';
+import algosdk, { Address } from 'algosdk';
+import { Buffer } from 'buffer';
+import { Config } from '../src/config.mjs';
+import { AppManager } from './app-manager.mjs';
 
+const getMethodCallForLog = ({ method, args }) => {
+    return `${method.name}(${(args ?? []).map((a) => (a instanceof Address ? a.toString() : typeof a === 'object' ? JSON.stringify(a, (_, v) => (typeof v === 'bigint' ? Number(v) : v instanceof Address ? v.toString() : v instanceof Uint8Array ? Buffer.from(v).toString('base64') : v)) : a))})`;
+};
 /** Orchestrates sending transactions for `AlgorandClient`. */
 class AlgorandClientTransactionSender {
     /**
      * Creates a new `AlgorandClientSender`
-     * @param newGroup A lambda that starts a new `AlgoKitComposer` transaction group
+     * @param newGroup A lambda that starts a new `TransactionComposer` transaction group
      * @param assetManager An `AssetManager` instance
      */
-    constructor(newGroup, assetManager) {
+    constructor(newGroup, assetManager, appManager) {
         /**
          * Send a payment transaction to transfer Algo between accounts.
          * @param params The parameters for the payment transaction
          * @example Basic example
          * ```typescript
-         * const result = await algorandClient.send.payment({
+         * const result = await algorand.send.payment({
          *  sender: 'SENDERADDRESS',
          *  receiver: 'RECEIVERADDRESS',
          *  amount: (4).algo(),
@@ -21,7 +27,7 @@ class AlgorandClientTransactionSender {
          * ```
          * @example Advanced example
          * ```typescript
-         * const result = await algorandClient.send.payment({
+         * const result = await algorand.send.payment({
          *   amount: (4).algo(),
          *   receiver: 'RECEIVERADDRESS',
          *   sender: 'SENDERADDRESS',
@@ -318,7 +324,7 @@ class AlgorandClientTransactionSender {
          *
          * @param params The parameters for the asset opt-out transaction
          *
-         * @example Basic example (without creator)
+         * @example Basic example (without creator, will be retrieved from algod)
          * ```typescript
          * await algorand.send.assetOptOut({sender: "SENDERADDRESS", assetId: 123456n, ensureZeroBalance: true })
          * ```
@@ -360,7 +366,7 @@ class AlgorandClientTransactionSender {
                     const accountAssetInfo = await this._assetManager.getAccountInformation(params.sender, params.assetId);
                     balance = accountAssetInfo.balance;
                 }
-                catch (e) {
+                catch {
                     throw new Error(`Account ${params.sender} is not opted-in to Asset ${params.assetId}; can't opt-out.`);
                 }
                 if (balance !== 0n) {
@@ -372,24 +378,424 @@ class AlgorandClientTransactionSender {
                 preLog: (params, transaction) => `Opting ${params.sender} out of asset with ID ${params.assetId} to creator ${params.creator} via transaction ${transaction.txID()}`,
             })(params);
         };
+        /**
+         * Create a smart contract.
+         *
+         * Note: you may prefer to use `algorand.client` to get an app client for more advanced functionality.
+         *
+         * @param params The parameters for the app creation transaction
+         * @example Basic example
+         * ```typescript
+         * const result = await algorand.send.appCreate({ sender: 'CREATORADDRESS', approvalProgram: 'TEALCODE', clearStateProgram: 'TEALCODE' })
+         * const createdAppId = result.appId
+         * ```
+         * @example Advanced example
+         * ```typescript
+         * await algorand.send.appCreate({
+         *  sender: 'CREATORADDRESS',
+         *  approvalProgram: "TEALCODE",
+         *  clearStateProgram: "TEALCODE",
+         *  schema: {
+         *    globalInts: 1,
+         *    globalByteSlices: 2,
+         *    localInts: 3,
+         *    localByteSlices: 4
+         *  },
+         *  extraProgramPages: 1,
+         *  onComplete: algosdk.OnApplicationComplete.OptInOC,
+         *  args: [new Uint8Array(1, 2, 3, 4)]
+         *  accountReferences: ["ACCOUNT_1"]
+         *  appReferences: [123n, 1234n]
+         *  assetReferences: [12345n]
+         *  boxReferences: ["box1", {appId: 1234n, name: "box2"}]
+         *  lease: 'lease',
+         *  note: 'note',
+         *  // You wouldn't normally set this field
+         *  firstValidRound: 1000n,
+         *  validityWindow: 10,
+         *  extraFee: (1000).microAlgo(),
+         *  staticFee: (1000).microAlgo(),
+         *  // Max fee doesn't make sense with extraFee AND staticFee
+         *  //  already specified, but here for completeness
+         *  maxFee: (3000).microAlgo(),
+         *  // Signer only needed if you want to provide one,
+         *  //  generally you'd register it with AlgorandClient
+         *  //  against the sender and not need to pass it in
+         *  signer: transactionSigner,
+         *  maxRoundsToWaitForConfirmation: 5,
+         *  suppressLog: true,
+         *})
+         * ```
+         */
+        this.appCreate = this._sendAppCreateCall((c) => c.addAppCreate, {
+            postLog: (params, result) => `App created by ${params.sender} with ID ${result.confirmation.applicationIndex} via transaction ${result.txIds.at(-1)}`,
+        });
+        /**
+         * Update a smart contract.
+         *
+         * Note: you may prefer to use `algorand.client` to get an app client for more advanced functionality.
+         *
+         * @param params The parameters for the app update transaction
+         * @example Basic example
+         * ```typescript
+         * await algorand.send.appUpdate({ sender: 'CREATORADDRESS', approvalProgram: 'TEALCODE', clearStateProgram: 'TEALCODE' })
+         * ```
+         * @example Advanced example
+         * ```typescript
+         * await algorand.send.appUpdate({
+         *  sender: 'CREATORADDRESS',
+         *  approvalProgram: "TEALCODE",
+         *  clearStateProgram: "TEALCODE",
+         *  onComplete: algosdk.OnApplicationComplete.UpdateApplicationOC,
+         *  args: [new Uint8Array(1, 2, 3, 4)]
+         *  accountReferences: ["ACCOUNT_1"]
+         *  appReferences: [123n, 1234n]
+         *  assetReferences: [12345n]
+         *  boxReferences: ["box1", {appId: 1234n, name: "box2"}]
+         *  lease: 'lease',
+         *  note: 'note',
+         *  // You wouldn't normally set this field
+         *  firstValidRound: 1000n,
+         *  validityWindow: 10,
+         *  extraFee: (1000).microAlgo(),
+         *  staticFee: (1000).microAlgo(),
+         *  // Max fee doesn't make sense with extraFee AND staticFee
+         *  //  already specified, but here for completeness
+         *  maxFee: (3000).microAlgo(),
+         *  // Signer only needed if you want to provide one,
+         *  //  generally you'd register it with AlgorandClient
+         *  //  against the sender and not need to pass it in
+         *  signer: transactionSigner,
+         *  maxRoundsToWaitForConfirmation: 5,
+         *  suppressLog: true,
+         *})
+         * ```
+         */
+        this.appUpdate = this._sendAppUpdateCall((c) => c.addAppUpdate, {
+            postLog: (params, result) => `App ${params.appId} updated ${params.args ? ` with ${params.args.map((a) => Buffer.from(a).toString('base64'))}` : ''} by ${params.sender} via transaction ${result.txIds.at(-1)}`,
+        });
+        /**
+         * Delete a smart contract.
+         *
+         * Note: you may prefer to use `algorand.client` to get an app client for more advanced functionality.
+         *
+         * @param params The parameters for the app deletion transaction
+         * @example Basic example
+         * ```typescript
+         * await algorand.send.appDelete({ sender: 'CREATORADDRESS' })
+         * ```
+         * @example Advanced example
+         * ```typescript
+         * await algorand.send.appDelete({
+         *  sender: 'CREATORADDRESS',
+         *  onComplete: algosdk.OnApplicationComplete.DeleteApplicationOC,
+         *  args: [new Uint8Array(1, 2, 3, 4)]
+         *  accountReferences: ["ACCOUNT_1"]
+         *  appReferences: [123n, 1234n]
+         *  assetReferences: [12345n]
+         *  boxReferences: ["box1", {appId: 1234n, name: "box2"}]
+         *  lease: 'lease',
+         *  note: 'note',
+         *  // You wouldn't normally set this field
+         *  firstValidRound: 1000n,
+         *  validityWindow: 10,
+         *  extraFee: (1000).microAlgo(),
+         *  staticFee: (1000).microAlgo(),
+         *  // Max fee doesn't make sense with extraFee AND staticFee
+         *  //  already specified, but here for completeness
+         *  maxFee: (3000).microAlgo(),
+         *  // Signer only needed if you want to provide one,
+         *  //  generally you'd register it with AlgorandClient
+         *  //  against the sender and not need to pass it in
+         *  signer: transactionSigner,
+         *  maxRoundsToWaitForConfirmation: 5,
+         *  suppressLog: true,
+         *})
+         * ```
+         */
+        this.appDelete = this._sendAppCall((c) => c.addAppDelete, {
+            postLog: (params, result) => `App ${params.appId} deleted ${params.args ? ` with ${params.args.map((a) => Buffer.from(a).toString('base64'))}` : ''} by ${params.sender} via transaction ${result.txIds.at(-1)}`,
+        });
         /**
          * Call a smart contract.
          *
-         * Note: you may prefer to use `algorandClient.client` to get an app client for more advanced functionality.
+         * Note: you may prefer to use `algorand.client` to get an app client for more advanced functionality.
+         *
+         * @param params The parameters for the app call transaction
+         * @example Basic example
+         * ```typescript
+         * await algorand.send.appCall({ sender: 'CREATORADDRESS' })
+         * ```
+         * @example Advanced example
+         * ```typescript
+         * await algorand.send.appCall({
+         *  sender: 'CREATORADDRESS',
+         *  onComplete: algosdk.OnApplicationComplete.OptInOC,
+         *  args: [new Uint8Array(1, 2, 3, 4)]
+         *  accountReferences: ["ACCOUNT_1"]
+         *  appReferences: [123n, 1234n]
+         *  assetReferences: [12345n]
+         *  boxReferences: ["box1", {appId: 1234n, name: "box2"}]
+         *  lease: 'lease',
+         *  note: 'note',
+         *  // You wouldn't normally set this field
+         *  firstValidRound: 1000n,
+         *  validityWindow: 10,
+         *  extraFee: (1000).microAlgo(),
+         *  staticFee: (1000).microAlgo(),
+         *  // Max fee doesn't make sense with extraFee AND staticFee
+         *  //  already specified, but here for completeness
+         *  maxFee: (3000).microAlgo(),
+         *  // Signer only needed if you want to provide one,
+         *  //  generally you'd register it with AlgorandClient
+         *  //  against the sender and not need to pass it in
+         *  signer: transactionSigner,
+         *  maxRoundsToWaitForConfirmation: 5,
+         *  suppressLog: true,
+         *})
+         * ```
          */
-        this.appCall = this._send((c) => c.addAppCall);
+        this.appCall = this._sendAppCall((c) => c.addAppCall, {
+            postLog: (params, result) => `App ${params.appId} called ${params.args ? ` with ${params.args.map((a) => Buffer.from(a).toString('base64'))}` : ''} by ${params.sender} via transaction ${result.txIds.at(-1)}`,
+        });
         /**
-         * Call a smart contract ABI method.
+         * Create a smart contract via an ABI method.
+         *
+         * Note: you may prefer to use `algorand.client` to get an app client for more advanced functionality.
          *
-         * Note: you may prefer to use `algorandClient.client` to get an app client for more advanced functionality.
+         * @param params The parameters for the app creation transaction
+         * @example Basic example
+         * ```typescript
+         * const method = new ABIMethod({
+         *   name: 'method',
+         *   args: [{ name: 'arg1', type: 'string' }],
+         *   returns: { type: 'string' },
+         * })
+         * const result = await algorand.send.appCreateMethodCall({ sender: 'CREATORADDRESS', approvalProgram: 'TEALCODE', clearStateProgram: 'TEALCODE', method: method, args: ["arg1_value"] })
+         * const createdAppId = result.appId
+         * ```
+         * @example Advanced example
+         * ```typescript
+         * const method = new ABIMethod({
+         *   name: 'method',
+         *   args: [{ name: 'arg1', type: 'string' }],
+         *   returns: { type: 'string' },
+         * })
+         * await algorand.send.appCreate({
+         *  sender: 'CREATORADDRESS',
+         *  method: method,
+         *  args: ["arg1_value"],
+         *  approvalProgram: "TEALCODE",
+         *  clearStateProgram: "TEALCODE",
+         *  schema: {
+         *    globalInts: 1,
+         *    globalByteSlices: 2,
+         *    localInts: 3,
+         *    localByteSlices: 4
+         *  },
+         *  extraProgramPages: 1,
+         *  onComplete: algosdk.OnApplicationComplete.OptInOC,
+         *  args: [new Uint8Array(1, 2, 3, 4)]
+         *  accountReferences: ["ACCOUNT_1"]
+         *  appReferences: [123n, 1234n]
+         *  assetReferences: [12345n]
+         *  boxReferences: ["box1", {appId: 1234n, name: "box2"}]
+         *  lease: 'lease',
+         *  note: 'note',
+         *  // You wouldn't normally set this field
+         *  firstValidRound: 1000n,
+         *  validityWindow: 10,
+         *  extraFee: (1000).microAlgo(),
+         *  staticFee: (1000).microAlgo(),
+         *  // Max fee doesn't make sense with extraFee AND staticFee
+         *  //  already specified, but here for completeness
+         *  maxFee: (3000).microAlgo(),
+         *  // Signer only needed if you want to provide one,
+         *  //  generally you'd register it with AlgorandClient
+         *  //  against the sender and not need to pass it in
+         *  signer: transactionSigner,
+         *  maxRoundsToWaitForConfirmation: 5,
+         *  suppressLog: true,
+         *})
+         * ```
          */
-        this.methodCall = this._send((c) => c.addMethodCall);
+        this.appCreateMethodCall = this._sendAppCreateCall((c) => c.addAppCreateMethodCall, {
+            postLog: (params, result) => `App created by ${params.sender} with ID ${result.confirmation.applicationIndex} via transaction ${result.txIds.at(-1)}`,
+        });
+        /**
+         * Update a smart contract via an ABI method.
+         *
+         * Note: you may prefer to use `algorand.client` to get an app client for more advanced functionality.
+         *
+         * @param params The parameters for the app update transaction
+         * @example Basic example
+         * ```typescript
+         * const method = new ABIMethod({
+         *   name: 'method',
+         *   args: [{ name: 'arg1', type: 'string' }],
+         *   returns: { type: 'string' },
+         * })
+         * await algorand.send.appUpdateMethodCall({ sender: 'CREATORADDRESS', approvalProgram: 'TEALCODE', clearStateProgram: 'TEALCODE', method: method, args: ["arg1_value"] })
+         * ```
+         * @example Advanced example
+         * ```typescript
+         * const method = new ABIMethod({
+         *   name: 'method',
+         *   args: [{ name: 'arg1', type: 'string' }],
+         *   returns: { type: 'string' },
+         * })
+         * await algorand.send.appUpdateMethodCall({
+         *  sender: 'CREATORADDRESS',
+         *  method: method,
+         *  args: ["arg1_value"],
+         *  approvalProgram: "TEALCODE",
+         *  clearStateProgram: "TEALCODE",
+         *  onComplete: algosdk.OnApplicationComplete.UpdateApplicationOC,
+         *  args: [new Uint8Array(1, 2, 3, 4)]
+         *  accountReferences: ["ACCOUNT_1"]
+         *  appReferences: [123n, 1234n]
+         *  assetReferences: [12345n]
+         *  boxReferences: ["box1", {appId: 1234n, name: "box2"}]
+         *  lease: 'lease',
+         *  note: 'note',
+         *  // You wouldn't normally set this field
+         *  firstValidRound: 1000n,
+         *  validityWindow: 10,
+         *  extraFee: (1000).microAlgo(),
+         *  staticFee: (1000).microAlgo(),
+         *  // Max fee doesn't make sense with extraFee AND staticFee
+         *  //  already specified, but here for completeness
+         *  maxFee: (3000).microAlgo(),
+         *  // Signer only needed if you want to provide one,
+         *  //  generally you'd register it with AlgorandClient
+         *  //  against the sender and not need to pass it in
+         *  signer: transactionSigner,
+         *  maxRoundsToWaitForConfirmation: 5,
+         *  suppressLog: true,
+         *})
+         * ```
+         */
+        this.appUpdateMethodCall = this._sendAppUpdateCall((c) => c.addAppUpdateMethodCall, {
+            postLog: (params, result) => `App ${params.appId} updated with ${getMethodCallForLog(params)} by ${params.sender} via transaction ${result.txIds.at(-1)}`,
+        });
+        /**
+         * Delete a smart contract via an ABI method.
+         *
+         * Note: you may prefer to use `algorand.client` to get an app client for more advanced functionality.
+         *
+         * @param params The parameters for the app deletion transaction
+         * @example Basic example
+         * ```typescript
+         * const method = new ABIMethod({
+         *   name: 'method',
+         *   args: [{ name: 'arg1', type: 'string' }],
+         *   returns: { type: 'string' },
+         * })
+         * await algorand.send.appDeleteMethodCall({ sender: 'CREATORADDRESS', method: method, args: ["arg1_value"] })
+         * ```
+         * @example Advanced example
+         * ```typescript
+         * const method = new ABIMethod({
+         *   name: 'method',
+         *   args: [{ name: 'arg1', type: 'string' }],
+         *   returns: { type: 'string' },
+         * })
+         * await algorand.send.appDeleteMethodCall({
+         *  sender: 'CREATORADDRESS',
+         *  method: method,
+         *  args: ["arg1_value"],
+         *  onComplete: algosdk.OnApplicationComplete.DeleteApplicationOC,
+         *  args: [new Uint8Array(1, 2, 3, 4)]
+         *  accountReferences: ["ACCOUNT_1"]
+         *  appReferences: [123n, 1234n]
+         *  assetReferences: [12345n]
+         *  boxReferences: ["box1", {appId: 1234n, name: "box2"}]
+         *  lease: 'lease',
+         *  note: 'note',
+         *  // You wouldn't normally set this field
+         *  firstValidRound: 1000n,
+         *  validityWindow: 10,
+         *  extraFee: (1000).microAlgo(),
+         *  staticFee: (1000).microAlgo(),
+         *  // Max fee doesn't make sense with extraFee AND staticFee
+         *  //  already specified, but here for completeness
+         *  maxFee: (3000).microAlgo(),
+         *  // Signer only needed if you want to provide one,
+         *  //  generally you'd register it with AlgorandClient
+         *  //  against the sender and not need to pass it in
+         *  signer: transactionSigner,
+         *  maxRoundsToWaitForConfirmation: 5,
+         *  suppressLog: true,
+         *})
+         * ```
+         */
+        this.appDeleteMethodCall = this._sendAppCall((c) => c.addAppDeleteMethodCall, {
+            postLog: (params, result) => `App ${params.appId} deleted with ${getMethodCallForLog(params)} by ${params.sender} via transaction ${result.txIds.at(-1)}`,
+        });
+        /**
+         * Call a smart contract via an ABI method.
+         *
+         * Note: you may prefer to use `algorand.client` to get an app client for more advanced functionality.
+         *
+         * @param params The parameters for the app call transaction
+         * @example Basic example
+         * ```typescript
+         * const method = new ABIMethod({
+         *   name: 'method',
+         *   args: [{ name: 'arg1', type: 'string' }],
+         *   returns: { type: 'string' },
+         * })
+         * await algorand.send.appCallMethodCall({ sender: 'CREATORADDRESS', method: method, args: ["arg1_value"] })
+         * ```
+         * @example Advanced example
+         * ```typescript
+         * const method = new ABIMethod({
+         *   name: 'method',
+         *   args: [{ name: 'arg1', type: 'string' }],
+         *   returns: { type: 'string' },
+         * })
+         * await algorand.send.appCallMethodCall({
+         *  sender: 'CREATORADDRESS',
+         *  method: method,
+         *  args: ["arg1_value"],
+         *  onComplete: algosdk.OnApplicationComplete.OptInOC,
+         *  args: [new Uint8Array(1, 2, 3, 4)]
+         *  accountReferences: ["ACCOUNT_1"]
+         *  appReferences: [123n, 1234n]
+         *  assetReferences: [12345n]
+         *  boxReferences: ["box1", {appId: 1234n, name: "box2"}]
+         *  lease: 'lease',
+         *  note: 'note',
+         *  // You wouldn't normally set this field
+         *  firstValidRound: 1000n,
+         *  validityWindow: 10,
+         *  extraFee: (1000).microAlgo(),
+         *  staticFee: (1000).microAlgo(),
+         *  // Max fee doesn't make sense with extraFee AND staticFee
+         *  //  already specified, but here for completeness
+         *  maxFee: (3000).microAlgo(),
+         *  // Signer only needed if you want to provide one,
+         *  //  generally you'd register it with AlgorandClient
+         *  //  against the sender and not need to pass it in
+         *  signer: transactionSigner,
+         *  maxRoundsToWaitForConfirmation: 5,
+         *  suppressLog: true,
+         *})
+         * ```
+         */
+        this.appCallMethodCall = this._sendAppCall((c) => c.addAppCallMethodCall, {
+            postLog: (params, result) => `App ${params.appId} called with ${getMethodCallForLog(params)} by ${params.sender} via transaction ${result.txIds.at(-1)}`,
+        });
         /** Register an online key. */
         this.onlineKeyRegistration = this._send((c) => c.addOnlineKeyRegistration, {
             preLog: (params, transaction) => `Registering online key for ${params.sender} via transaction ${transaction.txID()}`,
         });
         this._newGroup = newGroup;
         this._assetManager = assetManager;
+        this._appManager = appManager;
+    }
+    newGroup() {
+        return this._newGroup();
     }
     _send(c, log) {
         return async (params) => {
@@ -400,12 +806,12 @@ class AlgorandClientTransactionSender {
                 const transaction = (await composer.build()).transactions.at(-1).txn;
                 Config.getLogger(params?.suppressLog).debug(log.preLog(params, transaction));
             }
-            const rawResult = await composer.execute(params);
+            const rawResult = await composer.send(params);
             const result = {
                 // Last item covers when a group is created by an app call with ABI transaction parameters
-                transaction: rawResult.transactions[rawResult.transactions.length - 1],
-                confirmation: rawResult.confirmations[rawResult.confirmations.length - 1],
-                txId: rawResult.txIds[0],
+                transaction: rawResult.transactions.at(-1),
+                confirmation: rawResult.confirmations.at(-1),
+                txId: rawResult.txIds.at(-1),
                 ...rawResult,
             };
             if (log?.postLog) {
@@ -414,6 +820,30 @@ class AlgorandClientTransactionSender {
             return result;
         };
     }
+    _sendAppCall(c, log) {
+        return async (params) => {
+            const result = await this._send(c, log)(params);
+            return { ...result, return: AppManager.getABIReturn(result.confirmation, 'method' in params ? params.method : undefined) };
+        };
+    }
+    _sendAppUpdateCall(c, log) {
+        return async (params) => {
+            const result = await this._sendAppCall(c, log)(params);
+            const compiledApproval = typeof params.approvalProgram === 'string' ? this._appManager.getCompilationResult(params.approvalProgram) : undefined;
+            const compiledClear = typeof params.clearStateProgram === 'string' ? this._appManager.getCompilationResult(params.clearStateProgram) : undefined;
+            return { ...result, compiledApproval, compiledClear };
+        };
+    }
+    _sendAppCreateCall(c, log) {
+        return async (params) => {
+            const result = await this._sendAppUpdateCall(c, log)(params);
+            return {
+                ...result,
+                appId: BigInt(result.confirmation.applicationIndex),
+                appAddress: algosdk.getApplicationAddress(result.confirmation.applicationIndex),
+            };
+        };
+    }
 }
 
 export { AlgorandClientTransactionSender };