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"
 //   }
 // }
+```
+
+## Arweave Name Tokens (ANT's)
+
+The ANT contract client class exposes APIs relevant to compliant Arweave Name Token contracts. It can be configured to use any contract ID that adheres to the ANT contract spec. You must provide either a custom contract data provider or a contractTxId to the ANT class constructor to use.
 
+### `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,3 @@ 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

@@ -20,6 +20,7 @@ import {
   ArIOState,
   ArNSAuctionData,
   ArNSNameData,
+  ContractConfiguration,
   EpochDistributionData,
   EvaluationOptions,
   EvaluationParameters,
@@ -31,15 +32,6 @@ import {
 } from '../types.js';
 import { RemoteContract } from './contracts/remote-contract.js';
 
-// TODO: append this with other configuration options (e.g. local vs. remote evaluation)
-export type ContractConfiguration =
-  | {
-      contract?: SmartWeaveContract<unknown>;
-    }
-  | {
-      contractTxId: string;
-    };
-
 function isContractConfiguration<T>(
   config: ContractConfiguration,
 ): config is { contract: SmartWeaveContract<T> } {
@@ -69,6 +61,8 @@ export class ArIO implements ArIOContract {
       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;
+};

tests/ant.test.ts

@@ -0,0 +1,97 @@
+import { ANT } from '../src/common/ant';
+import { RemoteContract } from '../src/common/contracts/remote-contract';
+import { ANTState } from '../src/contract-state';
+
+describe('ANT contract apis', () => {
+  const ant = new ANT({
+    contract: new RemoteContract<ANTState>({
+      url: process.env.REMOTE_CACHE_URL || 'http://localhost:3000',
+      contractTxId: 'UC2zwawQoTnh0TNd9mYLQS4wObBBeaOU5LPQTNETqA4',
+    }),
+  });
+
+  const sortKey =
+    '000001383961,0000000000000,13987aba2d71b6229989690c15d2838a4deef0a90c3fc9e4d7227ed17e35d0bd';
+  const blockHeight = 1383961;
+
+  it.each([[{ sortKey }], [{ blockHeight }]])(
+    `should get contract state with evaluation options: ${JSON.stringify('%s')}`,
+    async (evalTo) => {
+      const state = await ant.getState({ evaluationOptions: { evalTo } });
+      expect(state).toBeDefined();
+    },
+  );
+
+  it.each([[{ sortKey }], [{ blockHeight }]])(
+    `should get record: ${JSON.stringify('%s')}`,
+    async (evalTo) => {
+      const record = await ant.getRecord({
+        domain: '@',
+        evaluationOptions: { evalTo },
+      });
+      expect(record).toBeDefined();
+    },
+  );
+
+  it.each([[{ sortKey }], [{ blockHeight }]])(
+    `should get records with evaluation options: ${JSON.stringify('%s')}`,
+    async (evalTo) => {
+      const records = await ant.getRecords({ evaluationOptions: { evalTo } });
+      console.dir({ records: records['@'] }, { depth: 4 });
+      expect(records).toBeDefined();
+    },
+  );
+
+  it.each([[{ sortKey }], [{ blockHeight }]])(
+    `should get owner with evaluation options: ${JSON.stringify('%s')}`,
+    async (evalTo) => {
+      const owner = await ant.getOwner({ evaluationOptions: { evalTo } });
+      expect(owner).toBeDefined();
+    },
+  );
+
+  it.each([[{ sortKey }], [{ blockHeight }]])(
+    `should get controllers with evaluation options: ${JSON.stringify('%s')}`,
+    async (evalTo) => {
+      const controllers = await ant.getControllers({
+        evaluationOptions: { evalTo },
+      });
+      expect(controllers).toBeDefined();
+    },
+  );
+
+  it.each([[{ sortKey }], [{ blockHeight }]])(
+    `should get name with evaluation options: ${JSON.stringify('%s')}`,
+    async (evalTo) => {
+      const state = await ant.getName({ evaluationOptions: { evalTo } });
+      expect(state).toBeDefined();
+    },
+  );
+
+  it.each([[{ sortKey }], [{ blockHeight }]])(
+    `should get ticker with evaluation options: ${JSON.stringify('%s')}`,
+    async (evalTo) => {
+      const state = await ant.getTicker({ evaluationOptions: { evalTo } });
+      expect(state).toBeDefined();
+    },
+  );
+
+  it.each([[{ sortKey }], [{ blockHeight }]])(
+    `should get balances with evaluation options: ${JSON.stringify('%s')}`,
+    async (evalTo) => {
+      const state = await ant.getBalances({ evaluationOptions: { evalTo } });
+      expect(state).toBeDefined();
+    },
+  );
+
+  it.each([[{ sortKey }], [{ blockHeight }]])(
+    `should get balance with evaluation options: ${JSON.stringify('%s')}`,
+    async (evalTo) => {
+      const state = await ant.getBalance({
+        address: 'TRVCopHzzO1VSwRUUS8umkiO2MpAL53XtVGlLaJuI94',
+        evaluationOptions: { evalTo },
+      });
+      expect(state).toBeDefined();
+    },
+  );
+});