feat(PE-5773): add auctions read apis (#18)

ar-io · Mar 15, 2024 · e0c6fca · e0c6fca
2 parents 1b6772e + 3f30f77
commit e0c6fca
Show file tree

Hide file tree

Showing 4 changed files with 140 additions and 0 deletions.
diff --git a/README.md b/README.md
@@ -480,6 +480,73 @@ const previousEpochObservers = arIO.getPrescribedObservers({
 // ]
 ```
 
+### `getAuction({ domain, evaluationOptions })`
+
+Return the auction info for the supplied domain, be it in auction, registered, or available to auction.
+
+```typescript
+const auction = await arIO.getAuction({ domain });
+
+// output
+
+// {
+//   "name": "ardrive",
+//   "initiator": "",
+//   "contractTxId": "",
+//   "startPrice": 89950,
+//   "floorPrice": 1799,
+//   "startHeight": 1384196,
+//   "endHeight": 1394276,
+//   "type": "lease",
+//   "years": 1,
+//   "isActive": false,
+//   "isAvailableForAuction": false,
+//   "isRequiredToBeAuctioned": false,
+//   "currentPrice": 1799,
+//   "prices": {
+//     "1384196": 89950,
+//     "1384226": 88930,
+//     "1384256": 87922,
+//     ...
+//     "1394216": 1921,
+//     "1394246": 1899,
+//     "1394276": 1877
+//   }
+// }
+```
+
+### `getAuctions({ evauluationOptions })`
+
+Retrieves all active auctions.
+
+```typescript
+
+const auctions = await arIO.getAuctions({ evaluationOptions });
+
+// output
+
+// {
+//   "cyprien": {
+//     "contractTxId": "Fmhdc4f1rWK6Zn1W__7GNvWvo4d1FSze7rLK5AOnO5E",
+//     "endHeight": 1386879,
+//     "floorPrice": 4758777913,
+//     "initiator": "UPJHTNsaKcC6baqLFHMAMI7daWPIG3NDDfFQ2s2h8T0",
+//     "startHeight": 1376799,
+//     "startPrice": 237938895627,
+//     "type": "permabuy"
+//   },
+//   "saktinaga": {
+//     "contractTxId": "nl8heYyDxKowujaDqbsPkjALzULYG8T0z3J91CdWDIM",
+//     "endHeight": 1386834,
+//     "floorPrice": 2379388956,
+//     "initiator": "TE0zVR32RF5qFAO8K50-pEivZpM_s35HK-dex-5d-IU",
+//     "startHeight": 1376754,
+//     "startPrice": 118969447813,
+//     "type": "permabuy"
+//   }
+// }
+
+
 ## Developers
 
 ### Requirements
@@ -524,3 +591,4 @@ 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
+```
diff --git a/src/common.ts b/src/common.ts
@@ -16,10 +16,12 @@
  */
 import {
   ArIOState,
+  ArNSAuctionData,
   ArNSNameData,
   EpochDistributionData,
   Gateway,
   Observations,
+  RegistrationType,
   WeightedObserver,
 } from './contract-state.js';
 
@@ -100,6 +102,17 @@ export interface ArIOContract {
   getDistributions({
     evaluationOptions,
   }: EvaluationParameters): Promise<EpochDistributionData>;
+  getAuctions({
+    evaluationOptions,
+  }: EvaluationParameters): Promise<Record<string, ArNSAuctionData>>;
+  getAuction({
+    domain,
+    type,
+    evaluationOptions,
+  }: EvaluationParameters<{
+    domain: string;
+    type?: RegistrationType;
+  }>): Promise<ArNSAuctionData>;
 }
 
 /* eslint-disable @typescript-eslint/no-explicit-any */

diff --git a/src/common/ar-io.ts b/src/common/ar-io.ts
@@ -18,11 +18,14 @@ import { ARNS_TESTNET_REGISTRY_TX } from '../constants.js';
 import {
   ArIOContract,
   ArIOState,
+  ArNSAuctionData,
   ArNSNameData,
   EpochDistributionData,
+  EvaluationOptions,
   EvaluationParameters,
   Gateway,
   Observations,
+  RegistrationType,
   SmartWeaveContract,
   WeightedObserver,
 } from '../types.js';
@@ -215,4 +218,33 @@ export class ArIO implements ArIOContract {
     });
     return distributions;
   }
+
+  async getAuction({
+    domain,
+    type,
+    evaluationOptions,
+  }: EvaluationParameters<{
+    domain: string;
+    type?: RegistrationType;
+  }>): Promise<ArNSAuctionData> {
+    return this.contract.readInteraction({
+      functionName: 'auction',
+      inputs: {
+        name: domain,
+        type,
+      },
+      evaluationOptions,
+    });
+  }
+  async getAuctions({
+    evaluationOptions,
+  }: {
+    evaluationOptions?: EvaluationOptions | Record<string, never> | undefined;
+  }): Promise<Record<string, ArNSAuctionData>> {
+    const { auctions } = await this.contract.getContractState({
+      evaluationOptions,
+    });
+
+    return auctions;
+  }
 }
diff --git a/tests/ar-io.test.ts b/tests/ar-io.test.ts
@@ -232,4 +232,31 @@ describe('ArIO Client', () => {
     });
     expect(distributions).toBeDefined();
   });
+
+  it.each([
+    [{ sortKey: evaluateToSortKey.toString() }],
+    [{ blockHeight: evaluateToBlockHeight }],
+  ])(
+    `should return auction for provided evaluation options: ${JSON.stringify('%s')}`,
+    async (evalTo) => {
+      const auction = await arIO.getAuction({
+        domain: 'ardrive',
+        evaluationOptions: { evalTo },
+      });
+      expect(auction).toBeDefined();
+    },
+  );
+
+  it.each([
+    [{ sortKey: evaluateToSortKey.toString() }],
+    [{ blockHeight: evaluateToBlockHeight }],
+  ])(
+    `should return auction for provided evaluation options: ${JSON.stringify('%s')}`,
+    async (evalTo) => {
+      const auctions = await arIO.getAuctions({
+        evaluationOptions: { evalTo },
+      });
+      expect(auctions).toBeDefined();
+    },
+  );
 });