GetApplicationBoxByName API

src/boxStorage.ts

@@ -0,0 +1,40 @@
+import { BoxReference } from './types/transactions/base';
+
+function translateBoxReference(
+  reference: BoxReference,
+  foreignApps: number[],
+  appIndex: number
+) {
+  const referenceId = reference.appIndex;
+  const referenceName = reference.name;
+  let index = 0;
+  // Foreign apps start from index 1; index 0 is its own app ID.
+  try {
+    index = foreignApps.indexOf(referenceId) + 1;
+  } catch (err) {
+    // Foreign app array cannot be empty unless the reference ID is itself.
+    if (referenceId !== 0 && referenceId !== appIndex) {
+      throw new Error(`Box ref with appId ${referenceId} not in foreign-apps`);
+    }
+  }
+  // Check if the app referenced is itself after checking the foreign apps array.
+  if (index === 0 && referenceId !== 0 && referenceId !== appIndex) {
+    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
+) {
+  if (!references) return [];
+  return references.map((bx) =>
+    translateBoxReference(bx, foreignApps, appIndex)
+  );
+}

src/client/v2/algod/algod.ts

@@ -8,6 +8,7 @@ import Compile from './compile';
 import Dryrun from './dryrun';
 import GetAssetByID from './getAssetByID';
 import GetApplicationByID from './getApplicationByID';
+import GetApplicationBoxByName from './getApplicationBoxByName';
 import HealthCheck from './healthCheck';
 import PendingTransactionInformation from './pendingTransactionInformation';
 import PendingTransactions from './pendingTransactions';
@@ -429,6 +430,31 @@ export default class AlgodClient extends ServiceClient {
     return new GetApplicationByID(this.c, this.intDecoding, index);
   }
 
+  /**
+   * Given an application ID and the box name (key), return the value stored in the box.
+   *
+   * #### Example
+   * ```typescript
+   * const index = 60553466;
+   * const boxName = Buffer.from("foo");
+   * const app = await algodClient.getApplicationBoxByName(index, boxName).do();
+   * ```
+   *
+   * TODO: Change below
+   * [Response data schema details](Fill me in!)
+   * @param index - The application ID to look up.
+   * @param boxName - The box name or key to look up.
+   * @category GET
+   */
+  getApplicationBoxByName(index: number, boxName: Uint8Array) {
+    return new GetApplicationBoxByName(
+      this.c,
+      this.intDecoding,
+      index,
+      boxName
+    );
+  }
+
   /**
    * Returns the entire genesis file.
    *

src/client/v2/algod/getApplicationBoxByName.ts

@@ -0,0 +1,22 @@
+import JSONRequest from '../jsonrequest';
+import HTTPClient from '../../client';
+import IntDecoding from '../../../types/intDecoding';
+import { encodeURLFromBytes } from '../../../encoding/uri';
+
+export default class GetApplicationBoxByName extends JSONRequest {
+  constructor(
+    c: HTTPClient,
+    intDecoding: IntDecoding,
+    private index: number,
+    private boxName: Uint8Array
+  ) {
+    super(c, intDecoding);
+    this.index = index;
+    this.boxName = boxName;
+  }
+
+  path() {
+    const encodedBoxName = encodeURLFromBytes(this.boxName);
+    return `/v2/applications/${this.index}/boxes/${encodedBoxName}`;
+  }
+}

src/client/v2/algod/models/types.ts

@@ -1029,6 +1029,43 @@ export class BlockResponse extends BaseModel {
   }
 }
 
+/**
+ * Box name and its content.
+ */
+export class Box extends BaseModel {
+  /**
+   * (name) box name, base64 encoded
+   */
+  public name: Uint8Array;
+
+  /**
+   * (value) box value, base64 encoded.
+   */
+  public value: Uint8Array;
+
+  /**
+   * Creates a new `Box` object.
+   * @param name - (name) box name, base64 encoded
+   * @param value - (value) box value, base64 encoded.
+   */
+  constructor(name: string | Uint8Array, value: string | Uint8Array) {
+    super();
+    this.name =
+      typeof name === 'string'
+        ? new Uint8Array(Buffer.from(name, 'base64'))
+        : name;
+    this.value =
+      typeof value === 'string'
+        ? new Uint8Array(Buffer.from(value, 'base64'))
+        : value;
+
+    this.attribute_map = {
+      name: 'name',
+      value: 'value',
+    };
+  }
+}
+
 export class BuildVersion extends BaseModel {
   public branch: string;
 

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/encoding/uri.ts

@@ -0,0 +1,29 @@
+/**
+ * This file contains URI encoding schemes for Uint8Arrays and Buffers.
+ *
+ * If there are non UTF-8 characters in the box name, the name will be converted
+ * to its corresponding hex value and escaped in the URL.
+ *  */
+
+const isUrlSafe = (char) => {
+  const urlSafePattern = /[a-zA-Z0-9\-_~.]+/;
+  return urlSafePattern.test(char);
+};
+
+export function encodeURLFromBytes(buf: Uint8Array) {
+  if (!(buf instanceof Uint8Array)) {
+    throw TypeError(`Argument ${buf} must be in bytes`);
+  }
+  let encoded = '';
+  for (let i = 0; i < buf.length; i++) {
+    const charBuf = Buffer.from('00', 'hex');
+    charBuf.writeUInt8(buf[i]);
+    const char = charBuf.toString();
+    if (isUrlSafe(char)) {
+      encoded += char;
+    } else {
+      encoded += `%${charBuf.toString('hex').toUpperCase()}`;
+    }
+  }
+  return encoded;
+}