Box support for Indexer endpoints (#619)

* Add boxes endpoint with path tests * Add lookup box by name api for indexer * Merge develop branch into feature/box-storage (#620) * properly set trace maxWidth (#593) * fix: safe intDecoding (#599) * fix: safe intDecoding * test: parse number in edge case * refactor: remove optional chaining for node12 * Remove code that relies on node's path module (#598) * Remove code that relies on node's path module * Replace url-parse with built in WHATWG URL API * Removed path-browserify fallback from webpack config * Removed path-browserify and url-parse from npm dependencies * Removed references to `path-browserify` in FAQ.md * bump version * Github-Actions: Adding PR title and label checks (#600) * Remove unused/unmaintained templates (#607) * Dev Tools: Source map decoder (#590) * adding source map decoder * Enhancement: Upgrade typedoc and plugins (#605) * Update ts-node, typescript, and typedoc to latest * docs: tealSign (#610) * bump version and add to changelog * update README.md for new version * API: Support attaching signatures to standard and multisig transactions (#595) * Add attach signature method to transaction class * Add multisig external signature methods * Fix failing multisig test * Add signature length checks * Add method to create an unsigned multisig transaction blob * Rename multisig create methods and use unencoded transaction * Refactor `createMultisigTransactionWithSignature` to use `createMultisigTransaction` method * Fix algosdk createMultisigTransaction export * Use MultisigMetadata without pks in new create method * These types should be consolidated in the future, and addrs seems like a better convention to use long-term * More descriptive test suite name * AVM: Consolidate TEAL and AVM versions (#609) * Testing: Use Dev mode network for cucumber tests (#614) * Send zero txn to itself * Refactor block advance functions * Revise steps to allow for rekeying transient accounts * Try to reduce flaky tests * Move constant into step * Add artificial sleep instead of sending blank txns when mimicking wait for block API * Reduce flaky tests * Remove unnecessary use of v2 algod client (#616) * Remove unnecessary use of v2 algod client * Add missing await for async function calls (#617) * Rename rekey tag in makefile * Revert testing branch back to master Co-authored-by: Michael Diamant <michaeldiamant@users.noreply.github.com> * Revert package lock from develop Co-authored-by: Joe Polny <50534337+joe-p@users.noreply.github.com> Co-authored-by: AlgoDoggo <93348148+AlgoDoggo@users.noreply.github.com> Co-authored-by: Bryan Dela Cruz <bdshi13@outlook.com> Co-authored-by: Lucky Baar <lucky.baar@algorand.com> Co-authored-by: Jack <87339414+algojack@users.noreply.github.com> Co-authored-by: Eric Warehime <eric.warehime@gmail.com> Co-authored-by: Ben Guidarelli <ben.guidarelli@gmail.com> Co-authored-by: Fionna Chan <fionnacst@gmail.com> Co-authored-by: Jack Smith <jack.smith@algorand.com> Co-authored-by: Jacob Daitzman <jdtzmn@gmail.com> Co-authored-by: Michael Diamant <michaeldiamant@users.noreply.github.com> * Revert package lock * Fix comments in box related APIs * Add next token to indexer box API test * rm unused step * Update src/client/v2/algod/getApplicationBoxByName.ts * Update .test-env Co-authored-by: Joe Polny <50534337+joe-p@users.noreply.github.com> Co-authored-by: AlgoDoggo <93348148+AlgoDoggo@users.noreply.github.com> Co-authored-by: Bryan Dela Cruz <bdshi13@outlook.com> Co-authored-by: Lucky Baar <lucky.baar@algorand.com> Co-authored-by: Jack <87339414+algojack@users.noreply.github.com> Co-authored-by: Eric Warehime <eric.warehime@gmail.com> Co-authored-by: Ben Guidarelli <ben.guidarelli@gmail.com> Co-authored-by: Fionna Chan <fionnacst@gmail.com> Co-authored-by: Jack Smith <jack.smith@algorand.com> Co-authored-by: Jacob Daitzman <jdtzmn@gmail.com> Co-authored-by: Michael Diamant <michaeldiamant@users.noreply.github.com> Co-authored-by: Hang Su <hang.su@algorand.com> Co-authored-by: Hang Su <87964331+ahangsu@users.noreply.github.com>
algorand · Sep 6, 2022 · af80784 · af80784
1 parent dccb952
commit af80784
Show file tree

Hide file tree

Showing 8 changed files with 249 additions and 4 deletions.
diff --git a/src/client/v2/algod/algod.ts b/src/client/v2/algod/algod.ts
@@ -440,7 +440,7 @@ export default class AlgodClient extends ServiceClient {
    * ```typescript
    * const index = 60553466;
    * const boxName = Buffer.from("foo");
-   * const app = await algodClient.getApplicationBoxByName(index).name(boxName).do();
+   * 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)
@@ -457,7 +457,7 @@ export default class AlgodClient extends ServiceClient {
    * #### Example
    * ```typescript
    * const index = 60553466;
-   * const app = await algodClient.getApplicationBoxes(index).max(3).do();
+   * 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)

diff --git a/src/client/v2/algod/getApplicationBoxByName.ts b/src/client/v2/algod/getApplicationBoxByName.ts
@@ -3,17 +3,48 @@ 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`;
   }
 
-  // name sets the box name in base64 encoded format.
+  /**
+   * 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');

diff --git a/src/client/v2/algod/getApplicationBoxes.ts b/src/client/v2/algod/getApplicationBoxes.ts
@@ -3,18 +3,48 @@ 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`;
   }
 
-  // max sets the maximum number of results to be returned from this query.
+  /**
+   * 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;

diff --git a/src/client/v2/indexer/indexer.ts b/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);
+  }
 }
diff --git a/src/client/v2/indexer/lookupApplicationBoxByIDandName.ts b/src/client/v2/indexer/lookupApplicationBoxByIDandName.ts
@@ -0,0 +1,52 @@
+import JSONRequest from '../jsonrequest';
+import HTTPClient from '../../client';
+import IntDecoding from '../../../types/intDecoding';
+
+export default class LookupApplicationBoxByIDandName extends JSONRequest {
+  /**
+   * Returns information about indexed application boxes.
+   *
+   * #### Example
+   * ```typescript
+   * const boxValue = await indexerClient.LookupApplicationBoxByIDandName(1234).do();
+   * ```
+   *
+   * [Response data schema details](https://developer.algorand.org/docs/rest-apis/indexer/#get-v2applicationsapplication-idbox)
+   * @oaram index - application index.
+   * @category GET
+   */
+  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 indexerClient
+   *        .LookupApplicationBoxByIDandName(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;
+  }
+}
diff --git a/src/client/v2/indexer/searchForApplicationBoxes.ts b/src/client/v2/indexer/searchForApplicationBoxes.ts
@@ -0,0 +1,75 @@
+import JSONRequest from '../jsonrequest';
+import HTTPClient from '../../client';
+import IntDecoding from '../../../types/intDecoding';
+
+export default class SearchForApplicationBoxes extends JSONRequest {
+  /**
+   * Returns information about indexed application boxes.
+   *
+   * #### Example
+   * ```typescript
+   * const boxesResult = await indexerClient.SearchForApplicationBoxes(1234).do();
+   * ```
+   *
+   * [Response data schema details](https://developer.algorand.org/docs/rest-apis/indexer/#get-v2applicationsapplication-idboxes)
+   * @oaram index - application index.
+   * @category GET
+   */
+  constructor(c: HTTPClient, intDecoding: IntDecoding, private index: number) {
+    super(c, intDecoding);
+    this.index = index;
+  }
+
+  /**
+   * @returns `/v2/applications/${index}/boxes`
+   */
+  path() {
+    return `/v2/applications/${this.index}/boxes`;
+  }
+
+  /**
+   * Specify the next page of results.
+   *
+   * #### Example
+   * ```typescript
+   * const maxResults = 20;
+   *
+   * const boxesPage1 = await indexerClient
+   *        .SearchForApplicationBoxes(1234)
+   *        .limit(maxResults)
+   *        .do();
+   *
+   * const boxesPage2 = await indexerClient
+   *        .SearchForApplicationBoxes(1234)
+   *        .limit(maxResults)
+   *        .nextToken(boxesPage1["next-token"])
+   *        .do();
+   * ```
+   * @param nextToken - provided by the previous results.
+   * @category query
+   */
+  nextToken(next: string) {
+    this.query.next = next;
+    return this;
+  }
+
+  /**
+   * Limit results for pagination.
+   *
+   * #### Example
+   * ```typescript
+   * const maxResults = 20;
+   * const boxesResult = await indexerClient
+   *        .SearchForApplicationBoxes(1234)
+   *        .limit(maxResults)
+   *        .do();
+   * ```
+   *
+   * @param limit - maximum number of results to return.
+   * @category query
+   */
+  limit(limit: number) {
+    this.query.limit = limit;
+    return this;
+  }
+}
diff --git a/tests/cucumber/steps/steps.js b/tests/cucumber/steps/steps.js
@@ -2242,6 +2242,28 @@ module.exports = function getSteps(options) {
     }
   );
 
+  When(
+    'we make a SearchForApplicationBoxes call with applicationID {int} with max {int} nextToken {string}',
+    async function (index, limit, token) {
+      await this.indexerClient
+        .searchForApplicationBoxes(index)
+        .limit(limit)
+        .nextToken(token)
+        .do();
+    }
+  );
+
+  When(
+    'we make a LookupApplicationBoxByIDandName call with applicationID {int} with encoded box name {string}',
+    async function (index, name) {
+      const boxKey = splitAndProcessAppArgs(name)[0];
+      await this.indexerClient
+        .lookupApplicationBoxByIDandName(index)
+        .name(boxKey)
+        .do();
+    }
+  );
+
   When(
     'we make a LookupApplicationLogsByID call with applicationID {int} limit {int} minRound {int} maxRound {int} nextToken {string} sender {string} and txID {string}',
     async function (appID, limit, minRound, maxRound, nextToken, sender, txID) {

diff --git a/tests/cucumber/unit.tags b/tests/cucumber/unit.tags
@@ -3,6 +3,7 @@
 @unit.algod
 @unit.algod.ledger_refactoring
 @unit.applications
+@unit.applications.boxes
 @unit.atomic_transaction_composer
 @unit.dryrun
 @unit.dryrun.trace.application