feat(PE-5759): observations and distributions apis

README.md

@@ -347,6 +347,89 @@ const records = arIO.getArNSRecords();
 // }
 ```
 
+### `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. The resulting object is pruned, to get older distributions use the `evaluationOptions` to `evalTo` a previous state.
+
+```typescript
+const arIO = new ArIO();
+const distributions = await arIO.getDistributions();
+
+// output
+
+// {
+//     epochEndHeight: 1382379,
+//     epochPeriod: 43,
+//     epochStartHeight: 1381660,
+//     epochZeroStartHeight: 1350700,
+//     nextDistributionHeight: 1382394
+// }
+```
+
+### `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
+// }
+```
+
 ### `getPrescribedObservers({ evaluationOptions })`
 
 Retrieves the prescribed observers of the ArIO contract. To fetch prescribed observers for a previous epoch set the `evaluationOptions` to the desired epoch.

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({ epochStartHeight: 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 },
   );

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({ epochStartHeight: 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 },
   );

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);

src/common.ts

@@ -19,6 +19,7 @@ import {
   ArNSNameData,
   EpochDistributionData,
   Gateway,
+  Observations,
   WeightedObserver,
 } from './contract-state.js';
 
@@ -91,6 +92,14 @@ export interface ArIOContract {
   getPrescribedObservers({
     evaluationOptions,
   }: EvaluationParameters): Promise<WeightedObserver[]>;
+  getObservations({
+    evaluationOptions,
+  }: EvaluationParameters<{
+    epochStartHeight?: number;
+  }>): Promise<Observations>;
+  getDistributions({
+    evaluationOptions,
+  }: EvaluationParameters): Promise<EpochDistributionData>;
 }
 
 /* eslint-disable @typescript-eslint/no-explicit-any */

src/common/ar-io.ts

@@ -22,6 +22,7 @@ import {
   EpochDistributionData,
   EvaluationParameters,
   Gateway,
+  Observations,
   SmartWeaveContract,
   WeightedObserver,
 } from '../types.js';
@@ -196,4 +197,22 @@ export class ArIO implements ArIOContract {
       evaluationOptions,
     });
   }
+  async getObservations({
+    evaluationOptions,
+  }: EvaluationParameters<{
+    epochStartHeight?: number;
+  }> = {}): Promise<Observations> {
+    const { observations } = await this.contract.getContractState({
+      evaluationOptions,
+    });
+    return observations;
+  }
+  async getDistributions({
+    evaluationOptions,
+  }: EvaluationParameters = {}): Promise<EpochDistributionData> {
+    const { distributions } = await this.contract.getContractState({
+      evaluationOptions,
+    });
+    return distributions;
+  }
 }

tests/ar-io.test.ts

@@ -191,4 +191,45 @@ describe('ArIO Client', () => {
       }
     },
   );
+
+  it('should return observation information', async () => {
+    const observations = await arIO.getObservations();
+    const observation = await arIO.getObservations({
+      epochStartHeight: 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();
+  });
 });