Boxes: Add support for Boxes

.test-env

@@ -1,6 +1,6 @@
 # Configs for testing repo download:
 SDK_TESTING_URL="https://github.com/algorand/algorand-sdk-testing"
-SDK_TESTING_BRANCH="master"
+SDK_TESTING_BRANCH="feature/box-storage"
 SDK_TESTING_HARNESS="test-harness"
 
 VERBOSE_HARNESS=0

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 (!Array.isArray(references)) return [];
+  return references.map((bx) =>
+    translateBoxReference(bx, foreignApps, appIndex)
+  );
+}

src/client/v2/algod/algod.ts

@@ -9,6 +9,8 @@ import Dryrun from './dryrun';
 import Genesis from './genesis';
 import GetAssetByID from './getAssetByID';
 import GetApplicationByID from './getApplicationByID';
+import GetApplicationBoxByName from './getApplicationBoxByName';
+import GetApplicationBoxes from './getApplicationBoxes';
 import HealthCheck from './healthCheck';
 import PendingTransactionInformation from './pendingTransactionInformation';
 import PendingTransactions from './pendingTransactions';
@@ -431,6 +433,41 @@ 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 boxValue = await algodClient.getApplicationBoxByName(index).name(boxName).do();
+   * ```
+   *
+   * [Response data schema details](https://developer.algorand.org/docs/rest-apis/algod/v2/#get-v2applicationsapplication-idbox)
+   * @param index - The application ID to look up.
+   * @category GET
+   */
+  getApplicationBoxByName(index: number) {
+    return new GetApplicationBoxByName(this.c, this.intDecoding, index);
+  }
+
+  /**
+   * Given an application ID, return all the box names associated with the app.
+   *
+   * #### Example
+   * ```typescript
+   * const index = 60553466;
+   * const boxesResult = await algodClient.getApplicationBoxes(index).max(3).do();
+   * ```
+   *
+   * [Response data schema details](https://developer.algorand.org/docs/rest-apis/algod/v2/#get-v2applicationsapplication-idboxes)
+   * @param index - The application ID to look up.
+   * @category GET
+   */
+  getApplicationBoxes(index: number) {
+    return new GetApplicationBoxes(this.c, this.intDecoding, index);
+  }
+
   /**
    * Returns the entire genesis file.
    *

src/client/v2/algod/getApplicationBoxByName.ts

@@ -0,0 +1,55 @@
+import JSONRequest from '../jsonrequest';
+import HTTPClient from '../../client';
+import IntDecoding from '../../../types/intDecoding';
+import { BoxReference } from '../../../types';
+
+/**
+ * Given an application ID and the box name (key), return the value stored in the box.
+ *
+ * #### Example
+ * ```typescript
+ * const index = 1234;
+ * const boxName = Buffer.from("foo");
+ * const boxValue = await algodClient.getApplicationBoxByName(index).name(boxName).do();
+ * ```
+ *
+ * [Response data schema details](https://developer.algorand.org/docs/rest-apis/algod/v2/#get-v2applicationsapplication-idbox)
+ * @param index - The application ID to look up.
+ * @category GET
+ */
+export default class GetApplicationBoxByName extends JSONRequest<BoxReference> {
+  constructor(c: HTTPClient, intDecoding: IntDecoding, private index: number) {
+    super(c, intDecoding);
+    this.index = index;
+  }
+
+  /**
+   * @returns `/v2/applications/${index}/box`
+   */
+  path() {
+    return `/v2/applications/${this.index}/box`;
+  }
+
+  /**
+   * Box name in bytes, and encodes it into a b64 string with goal encoded prefix.
+   *
+   * #### Example
+   * ```typescript
+   * const boxName = Buffer.from("foo");
+   * const boxValue = await algodClient
+   *        .getApplicationBoxByName(1234)
+   *        .name(boxName)
+   *        .do();
+   * ```
+   *
+   * @param name - name of box in bytes.
+   * @category query
+   */
+  name(name: Uint8Array) {
+    // Encode query in base64 format and append the encoding prefix.
+    let encodedName = Buffer.from(name).toString('base64');
+    encodedName = `b64:${encodedName}`;
+    this.query.name = encodeURI(encodedName);
+    return this;
+  }
+}

src/client/v2/algod/getApplicationBoxes.ts

@@ -0,0 +1,52 @@
+import JSONRequest from '../jsonrequest';
+import HTTPClient from '../../client';
+import IntDecoding from '../../../types/intDecoding';
+import { BoxesResponse } from './models/types';
+
+/**
+ * Given an application ID, return all the box names associated with the app.
+ *
+ * #### Example
+ * ```typescript
+ * const index = 1234;
+ * const boxesResult = await algodClient.getApplicationBoxes(index).max(3).do();
+ * ```
+ *
+ * [Response data schema details](https://developer.algorand.org/docs/rest-apis/algod/v2/#get-v2applicationsapplication-idboxes)
+ * @param index - The application ID to look up.
+ * @category GET
+ */
+export default class GetApplicationBoxes extends JSONRequest<BoxesResponse> {
+  constructor(c: HTTPClient, intDecoding: IntDecoding, private index: number) {
+    super(c, intDecoding);
+    this.index = index;
+    this.query.max = 0;
+  }
+
+  /**
+   * @returns `/v2/applications/${index}/boxes`
+   */
+  path() {
+    return `/v2/applications/${this.index}/boxes`;
+  }
+
+  /**
+   * Limit results for pagination.
+   *
+   * #### Example
+   * ```typescript
+   * const maxResults = 20;
+   * const boxesResult = await algodClient
+   *        .GetApplicationBoxes(1234)
+   *        .limit(maxResults)
+   *        .do();
+   * ```
+   *
+   * @param limit - maximum number of results to return.
+   * @category query
+   */
+  max(max: number) {
+    this.query.max = max;
+    return this;
+  }
+}

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

@@ -1029,6 +1029,89 @@ 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',
+    };
+  }
+}
+
+/**
+ * Box descriptor describes a Box.
+ */
+export class BoxDescriptor extends BaseModel {
+  /**
+   * Base64 encoded box name
+   */
+  public name: Uint8Array;
+
+  /**
+   * Creates a new `BoxDescriptor` object.
+   * @param name - Base64 encoded box name
+   */
+  constructor(name: string | Uint8Array) {
+    super();
+    this.name =
+      typeof name === 'string'
+        ? new Uint8Array(Buffer.from(name, 'base64'))
+        : name;
+
+    this.attribute_map = {
+      name: 'name',
+    };
+  }
+}
+
+/**
+ * Box names of an application
+ */
+export class BoxesResponse extends BaseModel {
+  public boxes: BoxDescriptor[];
+
+  /**
+   * Creates a new `BoxesResponse` object.
+   * @param boxes -
+   */
+  constructor(boxes: BoxDescriptor[]) {
+    super();
+    this.boxes = boxes;
+
+    this.attribute_map = {
+      boxes: 'boxes',
+    };
+  }
+}
+
 export class BuildVersion extends BaseModel {
   public branch: string;
 
@@ -2111,7 +2194,6 @@ export class StateProof extends BaseModel {
       typeof stateproof === 'string'
         ? new Uint8Array(Buffer.from(stateproof, 'base64'))
         : stateproof;
-
     this.attribute_map = {
       message: 'Message',
       stateproof: 'StateProof',

src/client/v2/indexer/indexer.ts

@@ -13,10 +13,12 @@ import LookupAccountCreatedApplications from './lookupAccountCreatedApplications
 import LookupAssetByID from './lookupAssetByID';
 import LookupApplications from './lookupApplications';
 import LookupApplicationLogs from './lookupApplicationLogs';
+import LookupApplicationBoxByIDandName from './lookupApplicationBoxByIDandName';
 import SearchAccounts from './searchAccounts';
 import SearchForTransactions from './searchForTransactions';
 import SearchForAssets from './searchForAssets';
 import SearchForApplications from './searchForApplications';
+import SearchForApplicationBoxes from './searchForApplicationBoxes';
 import { BaseHTTPClient } from '../../baseHTTPClient';
 import {
   CustomTokenHeader,
@@ -372,4 +374,36 @@ export default class IndexerClient extends ServiceClient {
   searchForApplications() {
     return new SearchForApplications(this.c, this.intDecoding);
   }
+
+  /**
+   * Returns information about indexed application boxes.
+   *
+   * #### Example
+   * ```typescript
+   * const boxesResult = await indexerClient.searchForApplicationBoxes().do();
+   * ```
+   *
+   * [Response data schema details](https://developer.algorand.org/docs/rest-apis/indexer/#get-v2applicationsapplication-idboxes)
+   * @param appID - The ID of the application with boxes.
+   * @category GET
+   */
+  searchForApplicationBoxes(appID: number) {
+    return new SearchForApplicationBoxes(this.c, this.intDecoding, appID);
+  }
+
+  /**
+   * Returns information about the application box given its name.
+   *
+   * #### Example
+   * ```typescript
+   * const boxValue = await indexerClient.lookupApplicationBoxByIDandName().do();
+   * ```
+   *
+   * [Response data schema details](https://developer.algorand.org/docs/rest-apis/indexer/#get-v2applicationsapplication-idbox)
+   * @param appID - The ID of the application with boxes.
+   * @category GET
+   */
+  lookupApplicationBoxByIDandName(appID: number) {
+    return new LookupApplicationBoxByIDandName(this.c, this.intDecoding, appID);
+  }
 }