feat(PE-5825): ANT read interface

README.md

@@ -520,7 +520,6 @@ const auction = await arIO.getAuction({ domain });
 Retrieves all active auctions.
 
 ```typescript
-
 const auctions = await arIO.getAuctions({ evaluationOptions });
 
 // output
@@ -545,7 +544,33 @@ const auctions = await arIO.getAuctions({ evaluationOptions });
 //     "type": "permabuy"
 //   }
 // }
+```
+
+## ANT API's
+
+The ANT contract class allows for fetching data given a provided ANT contract ID.
+
+### `getRecords({ evaluationOptions })`
 
+Returns all records on the configured ANT contract, including the required `@` record that resolve connected ArNS names.
+
+```typescript
+const contractTxId = 'bh9l1cy0aksiL_x9M359faGzM_yjralacHIUo8_nQXM';
+const ant = new ANT({ contractTxId });
+const records = await ANT.getRecords();
+
+// output
+// {
+//     "@": {
+//       "transactionId": "nOXJjj_vk0Dc1yCgdWD8kti_1iHruGzLQLNNBHVpN0Y",
+//       "ttlSeconds": 3600
+//     },
+//     "cn": {
+//       "transactionId": "_HquerT6pfGFXrVxRxQTkJ7PV5RciZCqvMjLtUY0C1k",
+//       "ttlSeconds": 3300
+//     }
+//   }
+```
 
 ## Developers
 
@@ -591,4 +616,7 @@ For more information on how to contribute, please see [CONTRIBUTING.md].
 [examples]: ./examples
 [arns-service]: https://github.com/ar-io/arns-service
 [CONTRIBUTING.md]: ./CONTRIBUTING.md
+
+```
+
 ```

docker-compose.yaml

@@ -9,7 +9,7 @@ services:
     environment:
       - LOG_LEVEL=debug
       - PREFETCH_CONTRACTS=true
-      - PREFETCH_CONTRACT_IDS=_NctcA2sRy1-J4OmIQZbYFPM17piNcbdBPH2ncX2RL8
+      - PREFETCH_CONTRACT_IDS=['_NctcA2sRy1-J4OmIQZbYFPM17piNcbdBPH2ncX2RL8', 'UC2zwawQoTnh0TNd9mYLQS4wObBBeaOU5LPQTNETqA4']
       - BOOTSTRAP_CONTRACTS=false
     healthcheck:
       test: ['CMD', 'curl', '-f', 'http://localhost:3000/healthcheck']

src/common.ts

@@ -15,6 +15,8 @@
  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
  */
 import {
+  ANTRecord,
+  ANTState,
   ArIOState,
   ArNSAuctionData,
   ArNSNameData,
@@ -29,6 +31,27 @@ export type BlockHeight = number;
 export type SortKey = string;
 export type WalletAddress = string;
 
+// TODO: append this with other configuration options (e.g. local vs. remote evaluation)
+export type ContractConfiguration =
+  | {
+      contract?: SmartWeaveContract<unknown>;
+    }
+  | {
+      contractTxId: string;
+    };
+
+export function isContractConfiguration<T>(
+  config: ContractConfiguration,
+): config is { contract: SmartWeaveContract<T> } {
+  return 'contract' in config;
+}
+
+export function isContractTxIdConfiguration(
+  config: ContractConfiguration,
+): config is { contractTxId: string } {
+  return 'contractTxId' in config;
+}
+
 export type EvaluationOptions = {
   evalTo?: { sortKey: SortKey } | { blockHeight: BlockHeight };
   // TODO: any other evaluation constraints
@@ -115,6 +138,30 @@ export interface ArIOContract {
   }>): Promise<ArNSAuctionData>;
 }
 
+export interface ANTContract {
+  getState({ evaluationOptions }: EvaluationParameters): Promise<ANTState>;
+  getRecord({
+    domain,
+    evaluationOptions,
+  }: EvaluationParameters<{ domain: string }>): Promise<ANTRecord>;
+  getRecords({
+    evaluationOptions,
+  }: EvaluationParameters): Promise<Record<string, ANTRecord>>;
+  getOwner({ evaluationOptions }: EvaluationParameters): Promise<string>;
+  getControllers({
+    evaluationOptions,
+  }: EvaluationParameters): Promise<string[]>;
+  getTicker({ evaluationOptions }: EvaluationParameters): Promise<string>;
+  getName({ evaluationOptions }: EvaluationParameters): Promise<string>;
+  getBalance({
+    address,
+    evaluationOptions,
+  }: EvaluationParameters<{ address: string }>): Promise<number>;
+  getBalances({
+    evaluationOptions,
+  }: EvaluationParameters): Promise<Record<string, number>>;
+}
+
 /* eslint-disable @typescript-eslint/no-explicit-any */
 export interface Logger {
   setLogLevel: (level: string) => void;

src/common/ant.ts

@@ -0,0 +1,120 @@
+/**
+ * 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 {
+  ANTContract,
+  ANTRecord,
+  ANTState,
+  ContractConfiguration,
+  EvaluationOptions,
+  EvaluationParameters,
+  SmartWeaveContract,
+  isContractConfiguration,
+  isContractTxIdConfiguration,
+} from '../types.js';
+import { RemoteContract } from './contracts/remote-contract.js';
+
+export class ANT implements ANTContract {
+  private contract: SmartWeaveContract<ANTState>;
+
+  constructor(config: ContractConfiguration) {
+    if (isContractConfiguration<ANTState>(config)) {
+      this.contract = config.contract;
+    } else if (isContractTxIdConfiguration(config)) {
+      this.contract = new RemoteContract<ANTState>({
+        contractTxId: config.contractTxId,
+      });
+    }
+  }
+
+  /**
+   * Returns the current state of the contract.
+   */
+  async getState(params: EvaluationParameters): Promise<ANTState> {
+    const state = await this.contract.getContractState(params);
+    return state;
+  }
+
+  async getRecord({
+    domain,
+    evaluationOptions,
+  }: EvaluationParameters<{ domain: string }>): Promise<ANTRecord> {
+    const records = await this.getRecords({ evaluationOptions });
+    return records[domain];
+  }
+
+  async getRecords({
+    evaluationOptions,
+  }: {
+    evaluationOptions?: EvaluationOptions | Record<string, never> | undefined;
+  }): Promise<Record<string, ANTRecord>> {
+    const state = await this.contract.getContractState({ evaluationOptions });
+    return state.records;
+  }
+
+  async getOwner({
+    evaluationOptions,
+  }: {
+    evaluationOptions?: EvaluationOptions | Record<string, never> | undefined;
+  }): Promise<string> {
+    const state = await this.contract.getContractState({ evaluationOptions });
+    return state.owner;
+  }
+
+  async getControllers({
+    evaluationOptions,
+  }: {
+    evaluationOptions?: EvaluationOptions | Record<string, never> | undefined;
+  }): Promise<string[]> {
+    const state = await this.contract.getContractState({ evaluationOptions });
+    return state.controllers;
+  }
+
+  async getName({
+    evaluationOptions,
+  }: {
+    evaluationOptions?: EvaluationOptions | Record<string, never> | undefined;
+  }): Promise<string> {
+    const state = await this.contract.getContractState({ evaluationOptions });
+    return state.name;
+  }
+
+  async getTicker({
+    evaluationOptions,
+  }: {
+    evaluationOptions?: EvaluationOptions | Record<string, never> | undefined;
+  }): Promise<string> {
+    const state = await this.contract.getContractState({ evaluationOptions });
+    return state.ticker;
+  }
+
+  async getBalances({
+    evaluationOptions,
+  }: {
+    evaluationOptions?: EvaluationOptions | Record<string, never> | undefined;
+  }): Promise<Record<string, number>> {
+    const state = await this.contract.getContractState({ evaluationOptions });
+    return state.balances;
+  }
+
+  async getBalance({
+    address,
+    evaluationOptions,
+  }: EvaluationParameters<{ address: string }>): Promise<number> {
+    const balances = await this.getBalances({ evaluationOptions });
+    return balances[address];
+  }
+}

src/common/ar-io.ts

@@ -14,7 +14,8 @@
  * 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 { ARNS_TESTNET_REGISTRY_TX } from '../constants.js';
+import { ArconnectSigner, ArweaveSigner } from 'arbundles';
+
 import {
   ArIOContract,
   ArIOState,
@@ -32,13 +33,17 @@ import {
 import { RemoteContract } from './contracts/remote-contract.js';
 
 // TODO: append this with other configuration options (e.g. local vs. remote evaluation)
-export type ContractConfiguration =
+export type ArIOSigner = ArweaveSigner | ArconnectSigner;
+export type ContractConfiguration = {
+  signer?: ArIOSigner; // TODO: optionally allow JWK in place of signer
+} & (
   | {
       contract?: SmartWeaveContract<unknown>;
     }
   | {
       contractTxId: string;
-    };
+    }
+);
 
 function isContractConfiguration<T>(
   config: ContractConfiguration,
@@ -54,21 +59,20 @@ function isContractTxIdConfiguration(
 
 export class ArIO implements ArIOContract {
   private contract: SmartWeaveContract<ArIOState>;
+  // eslint-disable-next-line @typescript-eslint/ban-ts-comment
+  // @ts-ignore
+  private signer: ArIOSigner | undefined;
 
-  constructor(
-    config: ContractConfiguration = {
-      // default to a contract that uses the arns service to do the evaluation
-      contract: new RemoteContract<ArIOState>({
-        contractTxId: ARNS_TESTNET_REGISTRY_TX,
-      }),
-    },
-  ) {
+  constructor({ signer, ...config }: ContractConfiguration) {
+    this.signer = signer;
     if (isContractConfiguration<ArIOState>(config)) {
       this.contract = config.contract;
     } else if (isContractTxIdConfiguration(config)) {
       this.contract = new RemoteContract<ArIOState>({
         contractTxId: config.contractTxId,
       });
+    } else {
+      throw new Error('Invalid configuration.');
     }
   }
 

src/contract-state.ts

@@ -181,3 +181,21 @@ export interface ArIOState {
   vaults: RegistryVaults;
   prescribedObservers: PrescribedObservers;
 }
+
+// ANT
+
+export type ANTRecord = {
+  transactionId: string;
+  ttlSeconds: number;
+};
+
+export type ANTRecords = Record<string, ANTRecord> & { '@': ANTRecord };
+
+export type ANTState = {
+  owner: WalletAddress;
+  controllers: WalletAddress[];
+  name: string;
+  ticker: string;
+  records: ANTRecords;
+  balances: Balances;
+};