feat(contract): add distribution, observations apis, update readme an…

…d examples
ar-io · Mar 13, 2024 · 0208317 · 0208317
1 parent aa07dda
commit 0208317
Show file tree

Hide file tree

Showing 7 changed files with 241 additions and 13 deletions.
diff --git a/README.md b/README.md
@@ -347,6 +347,89 @@ const records = arIO.getArNSRecords();
 // }
 ```
 
+### `getEpoch({ evaluationOptions })`
+
+Returns the epoch data for the specified block height.
+
+```typescript
+const arIO = new ArIO();
+const epoch = await arIO.getEpoch({ blockHeight: 1382230 });
+
+// output
+
+// {
+//     epochStartHeight: 1381660,
+//     epochEndHeight: 1382379,
+//     epochZeroStartHeight: 1350700,
+//     epochDistributionHeight: 1382394,
+//     epochPeriod: 43,
+//     epochBlockLength: 720
+// }
+```
+
+### `getCurrentEpoch({ evaluationOptions })`
+
+Returns the current epoch data.
+
+```typescript
+const arIO = new ArIO();
+const epoch = await arIO.getCurrentEpoch();
+
+// output
+
+// {
+//     epochStartHeight: 1381660,
+//     epochEndHeight: 1382379,
+//     epochZeroStartHeight: 1350700,
+//     epochDistributionHeight: 1382394,
+//     epochPeriod: 43,
+//     epochBlockLength: 720
+// }
+```
+
+### `getObservations({ evaluationOptions })`
+
+Returns the epoch-indexed observation list.
+
+```typescript
+const arIO = new ArIO();
+const observations = await arIO.getObservations();
+
+// output
+
+// {
+//     "1350700": {
+//       "failureSummaries": {
+//         "-Tk2DDk8k4zkwtppp_XFKKI5oUgh6IEHygAoN7mD-w8": [
+//         ...
+//      "reports": {
+//         "IPdwa3Mb_9pDD8c2IaJx6aad51Ss-_TfStVwBuhtXMs": "B6UUjKWjjEWDBvDSMXWNmymfwvgR9EN27z5FTkEVlX4",
+//         "Ie2wEEUDKoU26c7IuckHNn3vMFdNQnMvfPBrFzAb3NA": "7tKsiQ2fxv0D8ZVN_QEv29fZ8hwFIgHoEDrpeEG0DIs",
+//         "osZP4D9cqeDvbVFBaEfjIxwc1QLIvRxUBRAxDIX9je8": "aatgznEvC_UPcxp1v0uw_RqydhIfKm4wtt1KCpONBB0",
+//         "qZ90I67XG68BYIAFVNfm9PUdM7v1XtFTn7u-EOZFAtk": "Bd8SmFK9-ktJRmwIungS8ur6JM-JtpxrvMtjt5JkB1M"
+//       }
+// }
+```
+
+### `getDistributions({ evaluationOptions })`
+
+Returns the current rewards distribution information.
+
+```typescript
+const arIO = new ArIO();
+const distributions = await arIO.getDistributions();
+
+// output
+
+// {
+//     epochEndHeight: 1382379,
+//     epochPeriod: 43,
+//     epochStartHeight: 1381660,
+//     epochZeroStartHeight: 1350700,
+//     nextDistributionHeight: 1382394
+// }
+```
+
 ## Developers
 
 ### Requirements

diff --git a/examples/node/index.cjs b/examples/node/index.cjs
@@ -12,6 +12,13 @@ const {
   });
   const ardriveRecord = await arIO.getArNSRecord({ domain: 'ardrive' });
   const allRecords = await arIO.getArNSRecords();
+  const oldEpoch = await arIO.getEpoch({
+    blockHeight: 1382230,
+  });
+  const epoch = await arIO.getCurrentEpoch();
+  const observations = await arIO.getObservations();
+  const observation = await arIO.getObservations({ epoch: 1350700 });
+  const distributions = await arIO.getDistributions();
 
   console.dir(
     {
@@ -22,6 +29,11 @@ const {
         'registered domains': Object.keys(allRecords).length,
         ardrive: allRecords.ardrive,
       },
+      oldEpoch,
+      epoch,
+      observations,
+      observation,
+      distributions,
     },
     { depth: 2 },
   );

diff --git a/examples/node/index.mjs b/examples/node/index.mjs
@@ -9,6 +9,13 @@ import { ARNS_TESTNET_REGISTRY_TX, ArIO } from '../../lib/esm/node/index.js';
   });
   const ardriveRecord = await arIO.getArNSRecord({ domain: 'ardrive' });
   const allRecords = await arIO.getArNSRecords();
+  const oldEpoch = await arIO.getEpoch({
+    blockHeight: 1382230,
+  });
+  const epoch = await arIO.getCurrentEpoch();
+  const observations = await arIO.getObservations();
+  const observation = await arIO.getObservations({ epoch: 1350700 });
+  const distributions = await arIO.getDistributions();
 
   console.dir(
     {
@@ -19,6 +26,11 @@ import { ARNS_TESTNET_REGISTRY_TX, ArIO } from '../../lib/esm/node/index.js';
         'registered domains': Object.keys(allRecords).length,
         ardrive: allRecords.ardrive,
       },
+      oldEpoch,
+      epoch,
+      observations,
+      observation,
+      distributions,
     },
     { depth: 2 },
   );

diff --git a/examples/web/index.html b/examples/web/index.html
@@ -22,6 +22,7 @@
       };
     </script>
   </head>
+
   <body class="bg-background flex flex-col items-center p-10 gap-10">
     <!-- gateways -->
     <div
@@ -83,6 +84,52 @@ <h1 class="text-textPrimary w-full font-bold">Browse Records</h1>
         </table>
       </div>
     </div>
+
+    <!-- Get all observations -->
+    <div
+      class="bg-surface flex flex-col gap-5 items-end justify-center p-5 rounded-md h-full"
+      style="width: 750px; height: 500px"
+    >
+      <h1 class="text-textPrimary w-full font-bold">Browse Observations</h1>
+      <div class="h-full w-full" style="overflow-y: scroll">
+        <table class="w-full bg-background text-textPrimary">
+          <thead>
+            <tr>
+              <th class="px-4 py-2">Epoch Height</th>
+              <th class="px-4 py-2">Reports Count</th>
+              <th class="px-4 py-2">Failure Summary Count</th>
+            </tr>
+          </thead>
+          <tbody id="observations-table-body">
+            <!-- Add more rows as needed -->
+          </tbody>
+        </table>
+      </div>
+    </div>
+
+    <!-- Distribution Data -->
+    <div
+      class="bg-surface flex flex-col gap-5 items-end justify-center p-5 rounded-md h-full"
+      style="width: 750px; height: 200px"
+    >
+      <h1 class="text-textPrimary w-full font-bold">View Distribution Data</h1>
+      <div class="h-full w-full" style="overflow-y: scroll">
+        <table class="w-full bg-background text-textPrimary">
+          <thead>
+            <tr>
+              <th class="px-4 py-2">Epoch Period</th>
+              <th class="px-4 py-2">Epoch Start Height</th>
+              <th class="px-4 py-2">Epoch End Height</th>
+              <th class="px-4 py-2">Next Epoch Height</th>
+            </tr>
+          </thead>
+          <tbody id="distributions-table-body">
+            <!-- Add more rows as needed -->
+          </tbody>
+        </table>
+      </div>
+    </div>
+
     <script type="module">
       import { ArIO } from './web.bundle.min.js';
 
@@ -97,6 +144,8 @@ <h1 class="text-textPrimary w-full font-bold">Browse Records</h1>
         });
         const record = await arIO.getArNSRecord({ domain: 'ardrive' });
         const records = await arIO.getArNSRecords();
+        const observations = await arIO.getObservations();
+        const distributions = await arIO.getDistributions();
 
         //  update the UI
 
@@ -135,6 +184,29 @@ <h1 class="text-textPrimary w-full font-bold">Browse Records</h1>
             `;
             })
             .join('');
+
+        document.getElementById('observations-table-body').innerHTML =
+          Object.entries(observations)
+            .map(([epoch, observationData]) => {
+              return `
+              <tr>
+                <td class="border border-surface px-4 py-2 text-primary"><a href="https://arscan.io/block/${epoch}" target="_blank">${epoch}</a></td>
+                <td class="border border-surface px-4 py-2 text-primary">${Object.keys(observationData.reports).length}</td>
+                <td class="border border-surface px-4 py-2">${Object.keys(observationData.failureSummaries).length}</td>
+              </tr>
+            `;
+            })
+            .join('');
+
+        document.getElementById('distributions-table-body').innerHTML = `
+              <tr>
+                <td class="border border-surface px-4 py-2 text-primary">${distributions.epochPeriod}</a></td>
+                <td class="border border-surface px-4 py-2 text-primary">${distributions.epochStartHeight}</td>
+                <td class="border border-surface px-4 py-2">${distributions.epochEndHeight}</td>
+                <td class="border border-surface px-4 py-2">${distributions.nextDistributionHeight}</td>
+              </tr>
+            `;
+        // end init
       }
 
       window.addEventListener('load', init);

diff --git a/src/common.ts b/src/common.ts
@@ -89,11 +89,13 @@ export interface ArIOContract {
     evaluationOptions,
   }: EvaluationParameters): Promise<EpochDistributionData>;
   getObservations({
+    epoch,
     evaluationOptions,
-  }: EvaluationParameters): Promise<Observations>;
+  }: EvaluationParameters<{ epoch?: number }>): Promise<Observations>;
   getDistributions({
+    epoch,
     evaluationOptions,
-  }: EvaluationParameters): Promise<EpochDistributionData>;
+  }: EvaluationParameters<{ epoch?: number }>): Promise<EpochDistributionData>;
 }
 
 /* eslint-disable @typescript-eslint/no-explicit-any */

diff --git a/src/common/ar-io.ts b/src/common/ar-io.ts
@@ -20,7 +20,6 @@ import {
   ArIOState,
   ArNSNameData,
   EpochDistributionData,
-  EvaluationOptions,
   EvaluationParameters,
   Gateway,
   Observations,
@@ -186,23 +185,30 @@ export class ArIO implements ArIOContract {
     });
   }
   async getObservations({
+    epoch,
     evaluationOptions,
-  }: {
-    evaluationOptions?: EvaluationOptions | Record<string, never> | undefined;
-  }): Promise<Observations> {
+  }: EvaluationParameters<{ epoch?: number }> = {}): Promise<Observations> {
     const { observations } = await this.contract.getContractState({
       evaluationOptions,
     });
-    return observations;
+    return epoch !== undefined ? { [epoch]: observations[epoch] } : observations;
   }
   async getDistributions({
+    epoch,
     evaluationOptions,
-  }: {
-    evaluationOptions?: EvaluationOptions | Record<string, never> | undefined;
-  }): Promise<EpochDistributionData> {
-    const { distributions } = await this.contract.getContractState({
-      evaluationOptions,
-    });
+  }: EvaluationParameters<{
+    epoch?: number;
+  }> = {}): Promise<EpochDistributionData> {
+    const distributions = epoch !== undefined
+      ? await this.getEpoch({
+        ...evaluationOptions,
+        blockHeight: epoch,
+      })
+      : await this.contract
+        .getContractState({
+          evaluationOptions,
+        })
+        .then((state) => state.distributions);
     return distributions;
   }
 }
diff --git a/tests/ar-io.test.ts b/tests/ar-io.test.ts
@@ -149,4 +149,45 @@ describe('ArIO Client', () => {
     expect(epoch.epochPeriod).toBeDefined();
     expect(epoch.epochZeroStartHeight).toBeDefined();
   });
+
+  it('should return observation information', async () => {
+    const observations = await arIO.getObservations();
+    const observation = await arIO.getObservations({
+      epoch: parseInt(Object.keys(observations)[0]),
+    });
+    expect(observations).toBeDefined();
+    expect(observation).toBeDefined();
+  });
+
+  it('should get the observation information at a given block height', async () => {
+    const observations = await arIO.getObservations({
+      evaluationOptions: { evalTo: { blockHeight: evaluateToBlockHeight } },
+    });
+    expect(observations).toBeDefined();
+  });
+
+  it('should return observations at a sortkey', async () => {
+    const observations = await arIO.getObservations({
+      evaluationOptions: { evalTo: { sortKey: evaluateToSortKey.toString() } },
+    });
+    expect(observations).toBeDefined();
+  });
+
+  it('should return distributions', async () => {
+    const distributions = await arIO.getDistributions();
+    expect(distributions).toBeDefined();
+  });
+
+  it('should return distributions at a blockheight', async () => {
+    const distributions = await arIO.getDistributions({
+      evaluationOptions: { evalTo: { blockHeight: evaluateToBlockHeight } },
+    });
+    expect(distributions).toBeDefined();
+  });
+  it('should return distributions at a sortkey', async () => {
+    const distributions = await arIO.getDistributions({
+      evaluationOptions: { evalTo: { sortKey: evaluateToSortKey.toString() } },
+    });
+    expect(distributions).toBeDefined();
+  });
 });