Merge remote-tracking branch 'origin/alpha' into PE-5759

CHANGELOG.md

@@ -1,3 +1,11 @@
+# [1.0.0-alpha.6](https://github.com/ar-io/ar-io-sdk/compare/v1.0.0-alpha.5...v1.0.0-alpha.6) (2024-03-13)
+
+
+### Features
+
+* **observers:** add API for fetching prescribed observers ([a18e130](https://github.com/ar-io/ar-io-sdk/commit/a18e1306b185143b3b44416da168bf0610418d9c))
+* **observers:** add API for fetching prescribed observers ([#17](https://github.com/ar-io/ar-io-sdk/issues/17)) ([17ce6de](https://github.com/ar-io/ar-io-sdk/commit/17ce6de4aea61e5f97c999cdc96011dd911f7ad6))
+
 # [1.0.0-alpha.5](https://github.com/ar-io/ar-io-sdk/compare/v1.0.0-alpha.4...v1.0.0-alpha.5) (2024-03-12)
 
 

README.md

@@ -347,6 +347,49 @@ 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.
@@ -387,47 +430,54 @@ const epoch = await arIO.getCurrentEpoch();
 // }
 ```
 
-### `getObservations({ evaluationOptions })`
+### `getPrescribedObservers({ evaluationOptions })`
 
-Returns the epoch-indexed observation list.
+Retrieves the prescribed observers of the ArIO contract. To fetch prescribed observers for a previous epoch set the `evaluationOptions` to the desired epoch.
 
 ```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"
-//       }
-// }
-```
+const observers = arIO.getPrescribedObservers();
 
-### `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.
+// outputs:
 
-```typescript
-const arIO = new ArIO();
-const distributions = await arIO.getDistributions();
+// [
+//   {
+//     "gatewayAddress": "BpQlyhREz4lNGS-y3rSS1WxADfxPpAuing9Lgfdrj2U",
+//     "observerAddress": "2Fk8lCmDegPg6jjprl57-UCpKmNgYiKwyhkU4vMNDnE",
+//     "stake": 10000,
+//     "start": 1296976,
+//     "stakeWeight": 1,
+//     "tenureWeight": 0.41453703703703704,
+//     "gatewayRewardRatioWeight": 1,
+//     "observerRewardRatioWeight": 1,
+//     "compositeWeight": 0.41453703703703704,
+//     "normalizedCompositeWeight": 0.0018972019546783507
+//   },
+//   ...
+// ]
 
-// output
+// observers from a previous epoch
+const previousEpochObservers = arIO.getPrescribedObservers({
+  evaluationOptions: {
+    evalTo: { blockHeight: 1296975 }, // some block height from a previous epoch
+  },
+});
 
-// {
-//     epochEndHeight: 1382379,
-//     epochPeriod: 43,
-//     epochStartHeight: 1381660,
-//     epochZeroStartHeight: 1350700,
-//     nextDistributionHeight: 1382394
-// }
+// [
+//   {
+//     "gatewayAddress": "2Ic0ZIpt85tjiVRaD_qoTSo9jgT7w0rbf4puSTRidcU",
+//     "observerAddress": "2Ic0ZIpt85tjiVRaD_qoTSo9jgT7w0rbf4puSTRidcU",
+//     "stake": 10000,
+//     "start": 1292450,
+//     "stakeWeight": 1,
+//     "tenureWeight": 0.4494598765432099,
+//     "gatewayRewardRatioWeight": 1,
+//     "observerRewardRatioWeight": 1,
+//     "compositeWeight": 0.4494598765432099,
+//     "normalizedCompositeWeight": 0.002057032496835938
+//   },
+//   ...
+// ]
 ```
 
 ## Developers

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ar.io/sdk",
-  "version": "1.0.0-alpha.5",
+  "version": "1.0.0-alpha.6",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/ar-io/ar-io-sdk.git"

src/common.ts

@@ -20,6 +20,7 @@ import {
   EpochDistributionData,
   Gateway,
   Observations,
+  WeightedObserver,
 } from './contract-state.js';
 
 export type BlockHeight = number;
@@ -88,6 +89,9 @@ export interface ArIOContract {
   getCurrentEpoch({
     evaluationOptions,
   }: EvaluationParameters): Promise<EpochDistributionData>;
+  getPrescribedObservers({
+    evaluationOptions,
+  }: EvaluationParameters): Promise<WeightedObserver[]>;
   getObservations({
     evaluationOptions,
   }: EvaluationParameters<{

src/common/ar-io.ts

@@ -24,17 +24,18 @@ import {
   Gateway,
   Observations,
   SmartWeaveContract,
+  WeightedObserver,
 } 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>;
-    }
+    contract?: SmartWeaveContract<unknown>;
+  }
   | {
-      contractTxId: string;
-    };
+    contractTxId: string;
+  };
 
 function isContractConfiguration<T>(
   config: ContractConfiguration,
@@ -184,6 +185,18 @@ export class ArIO implements ArIOContract {
       evaluationOptions,
     });
   }
+
+  /**
+   * Returns the prescribed observers for the current epoch. If you are looking for prescribed observers for a past epoch, use `evaluationOptions: { blockHeight: <blockHeightDuringEpoch> }`.
+   */
+  async getPrescribedObservers({
+    evaluationOptions,
+  }: EvaluationParameters = {}): Promise<WeightedObserver[]> {
+    return this.contract.readInteraction<never, WeightedObserver[]>({
+      functionName: 'prescribedObservers',
+      evaluationOptions,
+    });
+  }
   async getObservations({
     evaluationOptions,
   }: EvaluationParameters<{

src/version.ts

@@ -17,4 +17,4 @@
 
 // AUTOMATICALLY GENERATED FILE - DO NOT TOUCH
 
-export const version = '1.0.0-alpha.5';
+export const version = '1.0.0-alpha.6';

tests/ar-io.test.ts

@@ -150,6 +150,48 @@ describe('ArIO Client', () => {
     expect(epoch.epochZeroStartHeight).toBeDefined();
   });
 
+  it('should return the prescribed observers for the current epoch', async () => {
+    const observers = await arIO.getPrescribedObservers();
+    expect(observers).toBeDefined();
+    for (const observer of observers) {
+      expect(observer.gatewayAddress).toBeDefined();
+      expect(observer.observerAddress).toBeDefined();
+      expect(observer.stake).toBeDefined();
+      expect(observer.start).toBeDefined();
+      expect(observer.stakeWeight).toBeDefined();
+      expect(observer.tenureWeight).toBeDefined();
+      expect(observer.gatewayRewardRatioWeight).toBeDefined();
+      expect(observer.observerRewardRatioWeight).toBeDefined();
+      expect(observer.compositeWeight).toBeDefined();
+      expect(observer.normalizedCompositeWeight).toBeDefined();
+    }
+  });
+
+  it.each([
+    [{ sortKey: evaluateToSortKey.toString() }],
+    [{ blockHeight: evaluateToBlockHeight }],
+  ])(
+    `should return the prescribed observers for provided evaluation options: ${JSON.stringify('%s')}`,
+    async (evalTo) => {
+      const observers = await arIO.getPrescribedObservers({
+        evaluationOptions: { evalTo },
+      });
+      expect(observers).toBeDefined();
+      for (const observer of observers) {
+        expect(observer.gatewayAddress).toBeDefined();
+        expect(observer.observerAddress).toBeDefined();
+        expect(observer.stake).toBeDefined();
+        expect(observer.start).toBeDefined();
+        expect(observer.stakeWeight).toBeDefined();
+        expect(observer.tenureWeight).toBeDefined();
+        expect(observer.gatewayRewardRatioWeight).toBeDefined();
+        expect(observer.observerRewardRatioWeight).toBeDefined();
+        expect(observer.compositeWeight).toBeDefined();
+        expect(observer.normalizedCompositeWeight).toBeDefined();
+      }
+    },
+  );
+
   it('should return observation information', async () => {
     const observations = await arIO.getObservations();
     const observation = await arIO.getObservations({