BlockHeaders: Support for /v2/blockheaders against Indexer API (v2.x line)

.circleci/config.yml

@@ -3,7 +3,7 @@ version: 2.1
 orbs:
   node: circleci/node@5.0.0
   slack: circleci/slack@4.4.2
-  browser-tools: circleci/browser-tools@1.4.8
+  browser-tools: circleci/browser-tools@1.5.1
   gh-pages: sugarshin/gh-pages@1.0.0
 
 parameters:

src/client/v2/indexer/indexer.ts

@@ -15,6 +15,7 @@ import LookupApplications from './lookupApplications';
 import LookupApplicationLogs from './lookupApplicationLogs';
 import LookupApplicationBoxByIDandName from './lookupApplicationBoxByIDandName';
 import SearchAccounts from './searchAccounts';
+import SearchForBlockHeaders from './searchForBlockHeaders';
 import SearchForTransactions from './searchForTransactions';
 import SearchForAssets from './searchForAssets';
 import SearchForApplications from './searchForApplications';
@@ -345,6 +346,21 @@ export default class IndexerClient extends ServiceClient {
     return new SearchForTransactions(this.c, this.intDecoding);
   }
 
+  /**
+   * Returns information about indexed block headers.
+   *
+   * #### Example
+   * ```typescript
+   * const txns = await indexerClient.searchForBlockHeaders().do();
+   * ```
+   *
+   * [Response data schema details](https://developer.algorand.org/docs/rest-apis/indexer/#get-v2block-headers)
+   * @category GET
+   */
+  searchForBlockHeaders() {
+    return new SearchForBlockHeaders(this.c, this.intDecoding);
+  }
+
   /**
    * Returns information about indexed assets.
    *

src/client/v2/indexer/searchForBlockHeaders.ts

@@ -0,0 +1,212 @@
+import JSONRequest from '../jsonrequest';
+
+/**
+ * Returns information about indexed block headers.
+ *
+ * #### Example
+ * ```typescript
+ * const bhs = await indexerClient.searchForBlockHeaders().do();
+ * ```
+ *
+ * [Response data schema details](https://developer.algorand.org/docs/rest-apis/indexer/#get-v2block-headers)
+ * @category GET
+ */
+export default class SearchForBlockHeaders extends JSONRequest {
+  /**
+   * @returns `/v2/block-headers`
+   */
+  // eslint-disable-next-line class-methods-use-this
+  path() {
+    return '/v2/block-headers';
+  }
+
+  /**
+   * Accounts marked as absent in the block header's participation updates.
+   *
+   * #### Example
+   * ```typescript
+   * const address1 = "XBYLS2E6YI6XXL5BWCAMOA4GTWHXWENZMX5UHXMRNWWUQ7BXCY5WC5TEPA";
+   * const address2 = "4H5UNRBJ2Q6JENAXQ6HNTGKLKINP4J4VTQBEPK5F3I6RDICMZBPGNH6KD4";
+   * const bhs = await indexerClient
+   *        .searchForBlockHeaders()
+   *        .absent([address1,address2])
+   *        .do();
+   * ```
+   *
+   * @param absent - a comma separated list of addresses
+   * @category query
+   */
+  absent(absent: string[]) {
+    this.query.absent = absent;
+    return this;
+  }
+
+  /**
+   * Include results after the given time.
+   *
+   * #### Example
+   * ```typescript
+   * const afterTime = "2022-10-21T00:00:11.55Z";
+   * const bhs = await indexerClient
+   *        .searchForBlockHeaders()
+   *        .afterTime(afterTime)
+   *        .do();
+   * ```
+   *
+   * @param after - rfc3339 string
+   * @category query
+   */
+  afterTime(after: string) {
+    this.query['after-time'] = after;
+    return this;
+  }
+
+  /**
+   * Include results before the given time.
+   *
+   * #### Example
+   * ```typescript
+   * const beforeTime = "2022-02-02T20:20:22.02Z";
+   * const bhs = await indexerClient
+   *        .searchForBlockHeaders()
+   *        .beforeTime(beforeTime)
+   *        .do();
+   * ```
+   *
+   * @param before - rfc3339 string
+   * @category query
+   */
+  beforeTime(before: string) {
+    this.query['before-time'] = before;
+    return this;
+  }
+
+  /**
+   * Accounts marked as expired in the block header's participation updates.
+   *
+   * #### Example
+   * ```typescript
+   * const address1 = "XBYLS2E6YI6XXL5BWCAMOA4GTWHXWENZMX5UHXMRNWWUQ7BXCY5WC5TEPA";
+   * const address2 = "4H5UNRBJ2Q6JENAXQ6HNTGKLKINP4J4VTQBEPK5F3I6RDICMZBPGNH6KD4";
+   * const bhs = await indexerClient
+   *        .searchForBlockHeaders()
+   *        .expired([address1,address2])
+   *        .do();
+   * ```
+   *
+   * @param expired - - a comma separated list of addresses
+   * @category query
+   */
+  expired(expired: string[]) {
+    this.query.expired = expired;
+    return this;
+  }
+
+  /**
+   * Maximum number of results to return.
+   *
+   * #### Example
+   * ```typescript
+   * const maxResults = 25;
+   * const bhs = await indexerClient
+   *        .searchForBlockHeaders()
+   *        .limit(maxResults)
+   *        .do();
+   * ```
+   *
+   * @param limit
+   * @category query
+   */
+  limit(limit: number) {
+    this.query.limit = limit;
+    return this;
+  }
+
+  /**
+   * Include results at or before the specified max-round.
+   *
+   * #### Example
+   * ```typescript
+   * const maxRound = 18309917;
+   * const bhs = await indexerClient
+   *        .searchForBlockHeaders()
+   *        .maxRound(maxRound)
+   *        .do();
+   * ```
+   *
+   * @param round
+   * @category query
+   */
+  maxRound(round: number) {
+    this.query['max-round'] = round;
+    return this;
+  }
+
+  /**
+   * Include results at or after the specified min-round.
+   *
+   * #### Example
+   * ```typescript
+   * const minRound = 18309917;
+   * const bhs = await indexerClient
+   *        .searchForBlockHeaders()
+   *        .minRound(minRound)
+   *        .do();
+   * ```
+   *
+   * @param round
+   * @category query
+   */
+  minRound(round: number) {
+    this.query['min-round'] = round;
+    return this;
+  }
+
+  /**
+   * The next page of results.
+   *
+   * #### Example
+   * ```typescript
+   * const maxResults = 25;
+   *
+   * const bh1 = await indexerClient
+   *        .searchForBlockHeaders()
+   *        .limit(maxResults)
+   *        .do();
+   *
+   * const bh2 = await indexerClient
+   *        .searchForBlockHeaders()
+   *        .limit(maxResults)
+   *        .nextToken(bh1["next-token"])
+   *        .do();
+   * ```
+   *
+   * @param nextToken - provided by the previous results
+   * @category query
+   */
+  nextToken(nextToken: string) {
+    this.query.next = nextToken;
+    return this;
+  }
+
+  /**
+   * Accounts marked as proposer in the block header's participation updates.
+   *
+   * #### Example
+   * ```typescript
+   * const address1 = "XBYLS2E6YI6XXL5BWCAMOA4GTWHXWENZMX5UHXMRNWWUQ7BXCY5WC5TEPA";
+   * const address2 = "4H5UNRBJ2Q6JENAXQ6HNTGKLKINP4J4VTQBEPK5F3I6RDICMZBPGNH6KD4";
+   * const bhs = await indexerClient
+   *        .searchForBlockHeaders()
+   *        .proposers([address1,address2])
+   *        .do();
+   * ```
+   *
+   * @param proposers - a comma separated list of addresses
+   * @category query
+   */
+  proposers(proposers: string[]) {
+    this.query.proposers = proposers;
+    return this;
+  }
+}

tests/9.Client.ts

@@ -43,8 +43,13 @@ describe('client', () => {
         format: 'json',
         abc: 'xyz',
         l: '2',
+        adds: [
+          'XBYLS2E6YI6XXL5BWCAMOA4GTWHXWENZMX5UHXMRNWWUQ7BXCY5WC5TEPA',
+          '4H5UNRBJ2Q6JENAXQ6HNTGKLKINP4J4VTQBEPK5F3I6RDICMZBPGNH6KD4',
+        ],
       });
-      const expected = 'http://localhost:3000/relative?format=json&abc=xyz&l=2';
+      const expected =
+        'http://localhost:3000/relative?format=json&abc=xyz&l=2&adds=XBYLS2E6YI6XXL5BWCAMOA4GTWHXWENZMX5UHXMRNWWUQ7BXCY5WC5TEPA%2C4H5UNRBJ2Q6JENAXQ6HNTGKLKINP4J4VTQBEPK5F3I6RDICMZBPGNH6KD4';
 
       assert.strictEqual(actual, expected);
     });

tests/cucumber/steps/steps.js

@@ -2359,6 +2359,47 @@ module.exports = function getSteps(options) {
     }
   );
 
+  When(
+    'we make a Search For BlockHeaders call with minRound {int} maxRound {int} limit {int} nextToken {string} beforeTime {string} afterTime {string} proposers {string} expired {string} absent {string}',
+    async function (
+      minRound,
+      maxRound,
+      limit,
+      nextToken,
+      beforeTime,
+      afterTime,
+      proposers,
+      expired,
+      absent
+    ) {
+      const builder = this.indexerClient
+        .searchForBlockHeaders()
+        .afterTime(afterTime)
+        .beforeTime(beforeTime)
+        .limit(limit)
+        .maxRound(maxRound)
+        .minRound(minRound)
+        .nextToken(nextToken);
+
+      if (proposers !== null && proposers.trim().length > 0) {
+        const proposersArray = proposers.split(',');
+        builder.proposers(proposersArray);
+      }
+
+      if (expired !== null && expired.trim().length > 0) {
+        const expiredArray = expired.split(',');
+        builder.expired(expiredArray);
+      }
+
+      if (absent !== null && absent.trim().length > 0) {
+        const absentArray = absent.split(',');
+        builder.absent(absentArray);
+      }
+
+      await builder.do();
+    }
+  );
+
   When(
     'we make a Search For Transactions call with account {string} NotePrefix {string} TxType {string} SigType {string} txid {string} round {int} minRound {int} maxRound {int} limit {int} beforeTime {string} afterTime {string} currencyGreaterThan {int} currencyLessThan {int} assetIndex {int} addressRole {string} ExcluseCloseTo {string} rekeyTo {string}',
     async function (
@@ -2738,6 +2779,28 @@ module.exports = function getSteps(options) {
     }
   );
 
+  let anySearchForBlockHeadersResponse;
+
+  When('we make any SearchForBlockHeaders call', async function () {
+    anySearchForBlockHeadersResponse = await this.indexerClient
+      .searchForBlockHeaders()
+      .do();
+  });
+
+  Then(
+    'the parsed SearchForBlockHeaders response should have a block array of len {int} and the element at index {int} should have round {string}',
+    (length, idx, roundStr) => {
+      assert.strictEqual(
+        anySearchForBlockHeadersResponse.blocks.length,
+        length
+      );
+      assert.strictEqual(
+        anySearchForBlockHeadersResponse.blocks[idx].round,
+        parseInt(roundStr)
+      );
+    }
+  );
+
   let anySearchForAssetsResponse;
 
   When('we make any SearchForAssets call', async function () {

tests/cucumber/unit.tags

@@ -12,6 +12,7 @@
 @unit.dryrun.trace.application
 @unit.feetest
 @unit.indexer
+@unit.indexer.blockheaders
 @unit.indexer.ledger_refactoring
 @unit.indexer.logs
 @unit.indexer.heartbeat