Boxes for application calls in static array

src/boxStorage.ts

@@ -0,0 +1,42 @@
+import { EncodedBoxReference } from './types';
+import { BoxReference } from './types/transactions/base';
+
+function translateBoxReference(
+  reference: BoxReference,
+  foreignApps: number[],
+  appIndex: number
+): EncodedBoxReference {
+  const referenceId = reference.appIndex;
+  const referenceName = reference.name;
+  const isOwnReference = referenceId === 0 || referenceId === appIndex;
+  let index = 0;
+
+  if (foreignApps != null) {
+    // Foreign apps start from index 1; index 0 is its own app ID.
+    index = foreignApps.indexOf(referenceId) + 1;
+  }
+  // Check if the app referenced is itself after checking the foreign apps array.
+  // If index is zero, then the app ID was not found in the foreign apps array
+  // or the foreign apps array was null.
+  if (index === 0 && !isOwnReference) {
+    // Error if the app is trying to reference a foreign app that was not in
+    // its own foreign apps array.
+    throw new Error(`Box ref with appId ${referenceId} not in foreign-apps`);
+  }
+  return { i: index, n: referenceName };
+}
+
+/**
+ * translateBoxReferences translates an array of BoxReferences with app IDs
+ * into an array of EncodedBoxReferences with foreign indices.
+ */
+export function translateBoxReferences(
+  references: BoxReference[],
+  foreignApps: number[],
+  appIndex: number
+): EncodedBoxReference[] {
+  if (references == null || !Array.isArray(references)) return [];
+  return references.map((bx) =>
+    translateBoxReference(bx, foreignApps, appIndex)
+  );
+}

src/composer.ts

@@ -21,6 +21,7 @@ import {
   isTransactionWithSigner,
 } from './signer';
 import {
+  BoxReference,
   OnApplicationComplete,
   SuggestedParams,
 } from './types/transactions/base';
@@ -201,6 +202,7 @@ export class AtomicTransactionComposer {
     numLocalInts,
     numLocalByteSlices,
     extraPages,
+    boxes,
     note,
     lease,
     rekeyTo,
@@ -232,6 +234,8 @@ export class AtomicTransactionComposer {
     numLocalByteSlices?: number;
     /** The number of extra pages to allocate for the application's programs. Only set this if this is an application creation call. If omitted, defaults to 0. */
     extraPages?: number;
+    /** The box references for this application call */
+    boxes?: BoxReference[];
     /** The note value for this application call */
     note?: Uint8Array;
     /** The lease value for this application call */
@@ -317,6 +321,8 @@ export class AtomicTransactionComposer {
     const refArgTypes: ABIReferenceType[] = [];
     const refArgValues: ABIValue[] = [];
     const refArgIndexToBasicArgIndex: Map<number, number> = new Map();
+    // TODO: Box encoding for ABI
+    const boxReferences: BoxReference[] = !boxes ? [] : boxes;
 
     for (let i = 0; i < methodArgs.length; i++) {
       let argType = method.args[i].type;
@@ -437,6 +443,7 @@ export class AtomicTransactionComposer {
         accounts: foreignAccounts,
         foreignApps,
         foreignAssets,
+        boxes: boxReferences,
         onComplete:
           onComplete == null ? OnApplicationComplete.NoOpOC : onComplete,
         approvalProgram,

src/makeTxn.ts

@@ -1100,6 +1100,7 @@ export function makeAssetTransferTxnWithSuggestedParamsFromObject(
  * @param accounts - Array of Address strings, any additional accounts to supply to the application
  * @param foreignApps - Array of int, any other apps used by the application, identified by index
  * @param foreignAssets - Array of int, any assets used by the application, identified by index
+ * @param boxes - Array of BoxReference, app ID and name of box to be accessed
  * @param note - Arbitrary data for sender to store
  * @param lease - Lease a transaction
  * @param rekeyTo - String representation of the Algorand address that will be used to authorize all future transactions
@@ -1119,6 +1120,7 @@ export function makeApplicationCreateTxn(
   accounts?: AppCreateTxn['appAccounts'],
   foreignApps?: AppCreateTxn['appForeignApps'],
   foreignAssets?: AppCreateTxn['appForeignAssets'],
+  boxes?: AppCreateTxn['boxes'],
   note?: AppCreateTxn['note'],
   lease?: AppCreateTxn['lease'],
   rekeyTo?: AppCreateTxn['reKeyTo'],
@@ -1140,6 +1142,7 @@ export function makeApplicationCreateTxn(
     appAccounts: accounts,
     appForeignApps: foreignApps,
     appForeignAssets: foreignAssets,
+    boxes,
     note,
     lease,
     reKeyTo: rekeyTo,
@@ -1181,6 +1184,7 @@ export function makeApplicationCreateTxnFromObject(
       | 'accounts'
       | 'foreignApps'
       | 'foreignAssets'
+      | 'boxes'
       | 'note'
       | 'lease'
       | 'rekeyTo'
@@ -1202,6 +1206,7 @@ export function makeApplicationCreateTxnFromObject(
     o.accounts,
     o.foreignApps,
     o.foreignAssets,
+    o.boxes,
     o.note,
     o.lease,
     o.rekeyTo,
@@ -1227,6 +1232,7 @@ export function makeApplicationCreateTxnFromObject(
  * @param accounts - Array of Address strings, any additional accounts to supply to the application
  * @param foreignApps - Array of int, any other apps used by the application, identified by index
  * @param foreignAssets - Array of int, any assets used by the application, identified by index
+ * @param boxes - Array of BoxReference, app ID and name of box to be accessed
  * @param note - Arbitrary data for sender to store
  * @param lease - Lease a transaction
  * @param rekeyTo - String representation of the Algorand address that will be used to authorize all future transactions
@@ -1241,6 +1247,7 @@ export function makeApplicationUpdateTxn(
   accounts?: AppUpdateTxn['appAccounts'],
   foreignApps?: AppUpdateTxn['appForeignApps'],
   foreignAssets?: AppUpdateTxn['appForeignAssets'],
+  boxes?: AppUpdateTxn['boxes'],
   note?: AppUpdateTxn['note'],
   lease?: AppUpdateTxn['lease'],
   rekeyTo?: AppUpdateTxn['reKeyTo']
@@ -1257,6 +1264,7 @@ export function makeApplicationUpdateTxn(
     appAccounts: accounts,
     appForeignApps: foreignApps,
     appForeignAssets: foreignAssets,
+    boxes,
     note,
     lease,
     reKeyTo: rekeyTo,
@@ -1288,6 +1296,7 @@ export function makeApplicationUpdateTxnFromObject(
       | 'accounts'
       | 'foreignApps'
       | 'foreignAssets'
+      | 'boxes'
       | 'note'
       | 'lease'
       | 'rekeyTo'
@@ -1304,6 +1313,7 @@ export function makeApplicationUpdateTxnFromObject(
     o.accounts,
     o.foreignApps,
     o.foreignAssets,
+    o.boxes,
     o.note,
     o.lease,
     o.rekeyTo
@@ -1326,6 +1336,7 @@ export function makeApplicationUpdateTxnFromObject(
  * @param accounts - Array of Address strings, any additional accounts to supply to the application
  * @param foreignApps - Array of int, any other apps used by the application, identified by index
  * @param foreignAssets - Array of int, any assets used by the application, identified by index
+ * @param boxes - Array of BoxReference, app ID and name of box to be accessed
  * @param note - Arbitrary data for sender to store
  * @param lease - Lease a transaction
  * @param rekeyTo - String representation of the Algorand address that will be used to authorize all future transactions
@@ -1338,6 +1349,7 @@ export function makeApplicationDeleteTxn(
   accounts?: AppDeleteTxn['appAccounts'],
   foreignApps?: AppDeleteTxn['appForeignApps'],
   foreignAssets?: AppDeleteTxn['appForeignAssets'],
+  boxes?: AppDeleteTxn['boxes'],
   note?: AppDeleteTxn['note'],
   lease?: AppDeleteTxn['lease'],
   rekeyTo?: AppDeleteTxn['reKeyTo']
@@ -1352,6 +1364,7 @@ export function makeApplicationDeleteTxn(
     appAccounts: accounts,
     appForeignApps: foreignApps,
     appForeignAssets: foreignAssets,
+    boxes,
     note,
     lease,
     reKeyTo: rekeyTo,
@@ -1379,6 +1392,7 @@ export function makeApplicationDeleteTxnFromObject(
       | 'accounts'
       | 'foreignApps'
       | 'foreignAssets'
+      | 'boxes'
       | 'note'
       | 'lease'
       | 'rekeyTo'
@@ -1393,6 +1407,7 @@ export function makeApplicationDeleteTxnFromObject(
     o.accounts,
     o.foreignApps,
     o.foreignAssets,
+    o.boxes,
     o.note,
     o.lease,
     o.rekeyTo
@@ -1415,6 +1430,7 @@ export function makeApplicationDeleteTxnFromObject(
  * @param accounts - Array of Address strings, any additional accounts to supply to the application
  * @param foreignApps - Array of int, any other apps used by the application, identified by index
  * @param foreignAssets - Array of int, any assets used by the application, identified by index
+ * @param boxes - Array of BoxReference, app ID and name of box to be accessed
  * @param note - Arbitrary data for sender to store
  * @param lease - Lease a transaction
  * @param rekeyTo - String representation of the Algorand address that will be used to authorize all future transactions
@@ -1427,6 +1443,7 @@ export function makeApplicationOptInTxn(
   accounts?: AppOptInTxn['appAccounts'],
   foreignApps?: AppOptInTxn['appForeignApps'],
   foreignAssets?: AppOptInTxn['appForeignAssets'],
+  boxes?: AppOptInTxn['boxes'],
   note?: AppOptInTxn['note'],
   lease?: AppOptInTxn['lease'],
   rekeyTo?: AppOptInTxn['reKeyTo']
@@ -1441,6 +1458,7 @@ export function makeApplicationOptInTxn(
     appAccounts: accounts,
     appForeignApps: foreignApps,
     appForeignAssets: foreignAssets,
+    boxes,
     note,
     lease,
     reKeyTo: rekeyTo,
@@ -1468,6 +1486,7 @@ export function makeApplicationOptInTxnFromObject(
       | 'accounts'
       | 'foreignApps'
       | 'foreignAssets'
+      | 'boxes'
       | 'note'
       | 'lease'
       | 'rekeyTo'
@@ -1482,6 +1501,7 @@ export function makeApplicationOptInTxnFromObject(
     o.accounts,
     o.foreignApps,
     o.foreignAssets,
+    o.boxes,
     o.note,
     o.lease,
     o.rekeyTo
@@ -1504,6 +1524,7 @@ export function makeApplicationOptInTxnFromObject(
  * @param accounts - Array of Address strings, any additional accounts to supply to the application
  * @param foreignApps - Array of int, any other apps used by the application, identified by index
  * @param foreignAssets - Array of int, any assets used by the application, identified by index
+ * @param boxes - Array of BoxReference, app ID and name of box to be accessed
  * @param note - Arbitrary data for sender to store
  * @param lease - Lease a transaction
  * @param rekeyTo - String representation of the Algorand address that will be used to authorize all future transactions
@@ -1516,6 +1537,7 @@ export function makeApplicationCloseOutTxn(
   accounts?: AppCloseOutTxn['appAccounts'],
   foreignApps?: AppCloseOutTxn['appForeignApps'],
   foreignAssets?: AppCloseOutTxn['appForeignAssets'],
+  boxes?: AppCloseOutTxn['boxes'],
   note?: AppCloseOutTxn['note'],
   lease?: AppCloseOutTxn['lease'],
   rekeyTo?: AppCloseOutTxn['reKeyTo']
@@ -1530,6 +1552,7 @@ export function makeApplicationCloseOutTxn(
     appAccounts: accounts,
     appForeignApps: foreignApps,
     appForeignAssets: foreignAssets,
+    boxes,
     note,
     lease,
     reKeyTo: rekeyTo,
@@ -1557,6 +1580,7 @@ export function makeApplicationCloseOutTxnFromObject(
       | 'accounts'
       | 'foreignApps'
       | 'foreignAssets'
+      | 'boxes'
       | 'note'
       | 'lease'
       | 'rekeyTo'
@@ -1571,6 +1595,7 @@ export function makeApplicationCloseOutTxnFromObject(
     o.accounts,
     o.foreignApps,
     o.foreignAssets,
+    o.boxes,
     o.note,
     o.lease,
     o.rekeyTo
@@ -1593,6 +1618,7 @@ export function makeApplicationCloseOutTxnFromObject(
  * @param accounts - Array of Address strings, any additional accounts to supply to the application
  * @param foreignApps - Array of int, any other apps used by the application, identified by index
  * @param foreignAssets - Array of int, any assets used by the application, identified by index
+ * @param boxes - Array of BoxReference, app ID and name of box to be accessed
  * @param note - Arbitrary data for sender to store
  * @param lease - Lease a transaction
  * @param rekeyTo - String representation of the Algorand address that will be used to authorize all future transactions
@@ -1605,6 +1631,7 @@ export function makeApplicationClearStateTxn(
   accounts?: AppClearStateTxn['appAccounts'],
   foreignApps?: AppClearStateTxn['appForeignApps'],
   foreignAssets?: AppClearStateTxn['appForeignAssets'],
+  boxes?: AppClearStateTxn['boxes'],
   note?: AppClearStateTxn['note'],
   lease?: AppClearStateTxn['lease'],
   rekeyTo?: AppClearStateTxn['reKeyTo']
@@ -1619,6 +1646,7 @@ export function makeApplicationClearStateTxn(
     appAccounts: accounts,
     appForeignApps: foreignApps,
     appForeignAssets: foreignAssets,
+    boxes,
     note,
     lease,
     reKeyTo: rekeyTo,
@@ -1646,6 +1674,7 @@ export function makeApplicationClearStateTxnFromObject(
       | 'accounts'
       | 'foreignApps'
       | 'foreignAssets'
+      | 'boxes'
       | 'note'
       | 'lease'
       | 'rekeyTo'
@@ -1660,6 +1689,7 @@ export function makeApplicationClearStateTxnFromObject(
     o.accounts,
     o.foreignApps,
     o.foreignAssets,
+    o.boxes,
     o.note,
     o.lease,
     o.rekeyTo
@@ -1682,6 +1712,7 @@ export function makeApplicationClearStateTxnFromObject(
  * @param accounts - Array of Address strings, any additional accounts to supply to the application
  * @param foreignApps - Array of int, any other apps used by the application, identified by index
  * @param foreignAssets - Array of int, any assets used by the application, identified by index
+ * @param boxes - Array of BoxReference, app ID and name of box to be accessed
  * @param note - Arbitrary data for sender to store
  * @param lease - Lease a transaction
  * @param rekeyTo - String representation of the Algorand address that will be used to authorize all future transactions
@@ -1694,6 +1725,7 @@ export function makeApplicationNoOpTxn(
   accounts?: AppNoOpTxn['appAccounts'],
   foreignApps?: AppNoOpTxn['appForeignApps'],
   foreignAssets?: AppNoOpTxn['appForeignAssets'],
+  boxes?: AppNoOpTxn['boxes'],
   note?: AppNoOpTxn['note'],
   lease?: AppNoOpTxn['lease'],
   rekeyTo?: AppNoOpTxn['reKeyTo']
@@ -1708,6 +1740,7 @@ export function makeApplicationNoOpTxn(
     appAccounts: accounts,
     appForeignApps: foreignApps,
     appForeignAssets: foreignAssets,
+    boxes,
     note,
     lease,
     reKeyTo: rekeyTo,
@@ -1735,6 +1768,7 @@ export function makeApplicationNoOpTxnFromObject(
       | 'accounts'
       | 'foreignApps'
       | 'foreignAssets'
+      | 'boxes'
       | 'note'
       | 'lease'
       | 'rekeyTo'
@@ -1749,6 +1783,7 @@ export function makeApplicationNoOpTxnFromObject(
     o.accounts,
     o.foreignApps,
     o.foreignAssets,
+    o.boxes,
     o.note,
     o.lease,
     o.rekeyTo
@@ -1781,6 +1816,7 @@ export function makeApplicationCallTxnFromObject(
       | 'accounts'
       | 'foreignApps'
       | 'foreignAssets'
+      | 'boxes'
       | 'note'
       | 'lease'
       | 'rekeyTo'
@@ -1825,6 +1861,7 @@ export function makeApplicationCallTxnFromObject(
     appAccounts: options.accounts,
     appForeignApps: options.foreignApps,
     appForeignAssets: options.foreignAssets,
+    boxes: options.boxes,
     note: options.note,
     lease: options.lease,
     reKeyTo: options.rekeyTo,