feat(PE-5751): add blockheight and sortkey eval filters

src/common/caches/arns-remote-cache.ts

@@ -21,6 +21,7 @@ import {
   ArNSStateResponse,
   Gateway,
   HTTPClient,
+  ReadInteractionFilters,
 } from '../../types/index.js';
 import { NotFound } from '../error.js';
 import { AxiosHTTPService } from '../http.js';
@@ -58,32 +59,44 @@ export class ArNSRemoteCache implements ArIOContract {
     }
   }
 
-  async getGateway({ address }: { address: string }) {
+  async getGateway({
+    address,
+    blockHeight,
+    sortKey,
+  }: { address: string } & ReadInteractionFilters) {
     this.logger.debug(`Fetching gateway ${address}`);
-    const gateway = await this.getGateways().then((gateways) => {
-      if (gateways[address] === undefined) {
-        throw new NotFound(`Gateway not found: ${address}`);
-      }
-      return gateways[address];
-    });
+    const gateway = await this.getGateways({ blockHeight, sortKey }).then(
+      (gateways) => {
+        if (gateways[address] === undefined) {
+          throw new NotFound(`Gateway not found: ${address}`);
+        }
+        return gateways[address];
+      },
+    );
     return gateway;
   }
 
-  async getGateways() {
+  async getGateways({ blockHeight, sortKey }: ReadInteractionFilters) {
     this.logger.debug(`Fetching gateways`);
     const { result } = await this.http.get<
       ArNSStateResponse<'result', Record<string, Gateway>>
     >({
       endpoint: `/contract/${this.contractTxId.toString()}/read/gateways`,
+      params: { blockHeight, sortKey: sortKey?.toString() },
     });
     return result;
   }
 
-  async getBalance({ address }: { address: string }) {
+  async getBalance({
+    address,
+    blockHeight,
+    sortKey,
+  }: { address: string } & ReadInteractionFilters) {
     this.logger.debug(`Fetching balance for ${address}`);
     const { result } = await this.http
       .get<ArNSStateResponse<'result', number>>({
         endpoint: `/contract/${this.contractTxId.toString()}/state/balances/${address}`,
+        params: { blockHeight, sortKey: sortKey?.toString() },
       })
       .catch((e) => {
         if (e instanceof NotFound) {
@@ -94,32 +107,42 @@ export class ArNSRemoteCache implements ArIOContract {
     return result;
   }
 
-  async getBalances() {
+  async getBalances({ blockHeight, sortKey }: ReadInteractionFilters) {
     this.logger.debug(`Fetching balances`);
     const { result } = await this.http.get<
       ArNSStateResponse<'result', Record<string, number>>
     >({
       endpoint: `/contract/${this.contractTxId.toString()}/state/balances`,
+      params: { blockHeight, sortKey: sortKey?.toString() },
     });
     return result;
   }
 
-  async getArNSRecord({ domain }: { domain: string }): Promise<ArNSNameData> {
+  async getArNSRecord({
+    domain,
+    blockHeight,
+    sortKey,
+  }: { domain: string } & ReadInteractionFilters): Promise<ArNSNameData> {
     this.logger.debug(`Fetching record for ${domain}`);
     const { result } = await this.http.get<
       ArNSStateResponse<'result', ArNSNameData>
     >({
       endpoint: `/contract/${this.contractTxId.toString()}/state/records/${domain}`,
+      params: { blockHeight, sortKey: sortKey?.toString() },
     });
     return result;
   }
 
-  async getArNSRecords(): Promise<Record<string, ArNSNameData>> {
+  async getArNSRecords({
+    blockHeight,
+    sortKey,
+  }: ReadInteractionFilters): Promise<Record<string, ArNSNameData>> {
     this.logger.debug(`Fetching all records`);
     const { result } = await this.http.get<
       ArNSStateResponse<'result', Record<string, ArNSNameData>>
     >({
       endpoint: `/contract/${this.contractTxId.toString()}/state/records`,
+      params: { blockHeight, sortKey: sortKey?.toString() },
     });
     return result;
   }

src/common/http.ts

@@ -39,16 +39,19 @@ export class AxiosHTTPService implements HTTPClient {
     signal,
     allowedStatuses = [200, 202],
     headers,
+    params,
   }: {
     endpoint: string;
     signal?: AbortSignal;
     allowedStatuses?: number[];
     headers?: Record<string, string>;
+    params?: Record<string, unknown>;
   }): Promise<T> {
     this.logger.debug(`Get request to endpoint: ${endpoint}`);
     const { status, statusText, data } = await this.axios.get<T>(endpoint, {
       headers,
       signal,
+      params,
     });
 
     if (!allowedStatuses.includes(status)) {

src/constants.ts

@@ -16,6 +16,10 @@
  */
 
 export const ARWEAVE_TX_REGEX = new RegExp('^[a-zA-Z0-9_-]{43}$');
+// sortkey: padded blockheight to 12, JS timestamp, hash of transactionID + block hash. Timestamp only applicable to L2 and normally is all zeros.
+export const SORT_KEY_REGEX = new RegExp(
+  '^[0-9]{12},[0-9]{13},[a-fA-F0-9]{64}$',
+);
 export const ARNS_TESTNET_REGISTRY_TX =
   process.env.ARNS_REGISTRY_TX ?? 'bLAgYxAdX2Ry-nt6aH2ixgvJXbpsEYm28NgJgyqfs-U';
 

src/types/common.ts

@@ -14,16 +14,37 @@
  * You should have received a copy of the GNU Affero General Public License
  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
  */
+import { SmartWeaveSortKey } from '../utils/index.js';
 import { ArNSNameData, Gateway } from './contract-state.js';
 
+export type EvaluationFilters = {
+  blockHeight?: number;
+  sortKey?: SmartWeaveSortKey; // should be tested against regex for validity
+};
+
+// TODO: extend type with other read filters (e.g max eval time)
+export type ReadInteractionFilters = EvaluationFilters;
+
 // TODO: extend with additional methods
 export interface ArIOContract {
-  getGateway({ address }: { address: WalletAddress }): Promise<Gateway>;
-  getGateways(): Promise<Record<WalletAddress, Gateway>>;
-  getBalance({ address }: { address: WalletAddress }): Promise<number>;
-  getBalances(): Promise<Record<WalletAddress, number>>;
-  getArNSRecord({ domain }: { domain: string }): Promise<ArNSNameData>;
-  getArNSRecords(): Promise<Record<string, ArNSNameData>>;
+  getGateway(
+    props: { address: WalletAddress } & ReadInteractionFilters,
+  ): Promise<Gateway>;
+  getGateways(
+    props: ReadInteractionFilters,
+  ): Promise<Record<WalletAddress, Gateway>>;
+  getBalance(
+    props: { address: WalletAddress } & ReadInteractionFilters,
+  ): Promise<number>;
+  getBalances(
+    props: ReadInteractionFilters,
+  ): Promise<Record<WalletAddress, number>>;
+  getArNSRecord(
+    props: { domain: string } & ReadInteractionFilters,
+  ): Promise<ArNSNameData>;
+  getArNSRecords(
+    prop: ReadInteractionFilters,
+  ): Promise<Record<string, ArNSNameData>>;
 }
 
 /* eslint-disable @typescript-eslint/no-explicit-any */
@@ -45,11 +66,13 @@ export interface HTTPClient {
     signal,
     headers,
     allowedStatuses,
+    params,
   }: {
     endpoint: string;
     signal?: AbortSignal;
     headers?: Record<string, string>;
     allowedStatuses?: number[];
+    params?: Record<string, unknown>;
   }): Promise<T>;
   // TODO: add post method
   // post<T>({

src/utils/index.ts

@@ -16,3 +16,4 @@
  */
 export * from './arweave.js';
 export * from './http-client.js';
+export * from './smartweave/index.js';

src/utils/smartweave/evaluation.test.ts

@@ -0,0 +1,13 @@
+import { SmartWeaveSortKey } from './evaluation.js';
+
+describe(`Smartweave eval utils`, () => {
+  it(`should throw on a bad sort key`, async () => {
+    const sortKey = '123,456,abc';
+    const error = await (async () => new SmartWeaveSortKey(sortKey))().catch(
+      (e) => e,
+    );
+
+    expect(error).toBeInstanceOf(Error);
+    expect(error.message).toContain(sortKey);
+  });
+});

src/utils/smartweave/evaluation.ts

@@ -0,0 +1,49 @@
+/**
+ * Copyright (C) 2022-2024 Permanent Data Solutions, Inc. All Rights Reserved.
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program.  If not, see <http://www.gnu.org/licenses/>.
+ */
+import { SORT_KEY_REGEX } from '../../constants.js';
+
+export class SmartWeaveSortKey {
+  private _sortKey: string;
+  constructor(sortKey: string) {
+    if (!SmartWeaveSortKey.validate(sortKey)) {
+      throw new Error(`Invalid sort key: ${sortKey}`);
+    }
+
+    this._sortKey = sortKey;
+  }
+
+  static validate(sortKey: string): boolean {
+    return SORT_KEY_REGEX.test(sortKey);
+  }
+
+  toString(): string {
+    return this._sortKey;
+  }
+
+  parts(): string[] {
+    return this._sortKey.split(',');
+  }
+  blockHeight(): number {
+    return parseInt(this.parts()[0]);
+  }
+  timestamp(): number {
+    return parseInt(this.parts()[1]);
+  }
+  hash(): string {
+    return this.parts()[2];
+  }
+}

src/utils/smartweave/index.ts

@@ -0,0 +1,17 @@
+/**
+ * Copyright (C) 2022-2024 Permanent Data Solutions, Inc. All Rights Reserved.
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program.  If not, see <http://www.gnu.org/licenses/>.
+ */
+export * from './evaluation.js';

tests/ar-io.test.ts

@@ -5,7 +5,5 @@ describe('ArIO Client', () => {
     const arioClient = new ArIO();
 
     expect(arioClient).toBeInstanceOf(ArIO);
-    expect(arioClient.testnet).toBeDefined();
-    expect(arioClient.devnet).toBeDefined();
   });
 });