feat(PE-5800): epoch apis

.prettierignore

@@ -0,0 +1 @@
+CHANGELOG.md

package.json

@@ -29,6 +29,15 @@
     "email": "info@ar.io",
     "website": "https://ar.io"
   },
+  "keywords": [
+    "arweave",
+    "ar",
+    "blockchain",
+    "warp",
+    "contracts",
+    "ar.io",
+    "ao"
+  ],
   "exports": {
     ".": {
       "import": "./lib/esm/node/index.js",

src/common.ts

@@ -14,7 +14,12 @@
  * 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 { ArIOState, ArNSNameData, Gateway } from './contract-state.js';
+import {
+  ArIOState,
+  ArNSNameData,
+  EpochDistributionData,
+  Gateway,
+} from './contract-state.js';
 
 export type BlockHeight = number;
 export type SortKey = string;
@@ -73,6 +78,15 @@ export interface ArIOContract {
   }: EvaluationParameters): Promise<
     Record<string, ArNSNameData> | Record<string, never>
   >;
+  getEpoch({
+    blockHeight,
+    evaluationOptions,
+  }: {
+    blockHeight: number;
+  } & EvaluationParameters): Promise<EpochDistributionData>;
+  getCurrentEpoch({
+    evaluationOptions,
+  }: EvaluationParameters): Promise<EpochDistributionData>;
 }
 
 /* eslint-disable @typescript-eslint/no-explicit-any */

src/common/ar-io.ts

@@ -19,6 +19,7 @@ import {
   ArIOContract,
   ArIOState,
   ArNSNameData,
+  EpochDistributionData,
   EvaluationParameters,
   Gateway,
   SmartWeaveContract,
@@ -149,4 +150,37 @@ export class ArIO implements ArIOContract {
       evaluationOptions,
     });
   }
+
+  /**
+   * Returns the current epoch.
+   */
+  async getCurrentEpoch({
+    evaluationOptions,
+  }: EvaluationParameters = {}): Promise<EpochDistributionData> {
+    return this.contract.readInteraction({
+      functionName: 'epoch',
+      evaluationOptions,
+    });
+  }
+
+  /**
+   * Returns the epoch information for the provided block height.
+   */
+  async getEpoch({
+    blockHeight,
+    evaluationOptions,
+  }: {
+    blockHeight: number;
+  } & EvaluationParameters): Promise<EpochDistributionData> {
+    return this.contract.readInteraction<
+      { height: number },
+      EpochDistributionData
+    >({
+      functionName: 'epoch',
+      inputs: {
+        height: blockHeight,
+      },
+      evaluationOptions,
+    });
+  }
 }

src/contract-state.ts

@@ -156,7 +156,8 @@ export type EpochDistributionData = {
   epochStartHeight: number; // the current epoch start height
   epochEndHeight: number; // the current epoch end height
   epochPeriod: number;
-  nextDistributionHeight: number;
+  epochDistributionHeight: number;
+  epochBlockLength: number;
 };
 
 export type Vaults = Record<string, VaultData>;

tests/ar-io.test.ts

@@ -112,4 +112,41 @@ describe('ArIO Client', () => {
     });
     expect(records[domain]).toBeDefined();
   });
+
+  it('should return the current epoch information', async () => {
+    const epoch = await arIO.getCurrentEpoch();
+    expect(epoch).toBeDefined();
+    expect(epoch.epochStartHeight).toBeDefined();
+    expect(epoch.epochBlockLength).toBeDefined();
+    expect(epoch.epochDistributionHeight).toBeDefined();
+    expect(epoch.epochEndHeight).toBeDefined();
+    expect(epoch.epochPeriod).toBeDefined();
+    expect(epoch.epochZeroStartHeight).toBeDefined();
+  });
+
+  it('should return the current epoch information when evaluated at a given block height', async () => {
+    const epoch = await arIO.getCurrentEpoch({
+      evaluationOptions: { evalTo: { blockHeight: evaluateToBlockHeight } },
+    });
+    expect(epoch).toBeDefined();
+    expect(epoch.epochStartHeight).toBeDefined();
+    expect(epoch.epochBlockLength).toBeDefined();
+    expect(epoch.epochDistributionHeight).toBeDefined();
+    expect(epoch.epochEndHeight).toBeDefined();
+    expect(epoch.epochPeriod).toBeDefined();
+    expect(epoch.epochZeroStartHeight).toBeDefined();
+  });
+
+  it('should return the epoch information at a given block height', async () => {
+    const epoch = await arIO.getEpoch({
+      blockHeight: evaluateToBlockHeight,
+    });
+    expect(epoch).toBeDefined();
+    expect(epoch.epochStartHeight).toBeDefined();
+    expect(epoch.epochBlockLength).toBeDefined();
+    expect(epoch.epochDistributionHeight).toBeDefined();
+    expect(epoch.epochEndHeight).toBeDefined();
+    expect(epoch.epochPeriod).toBeDefined();
+    expect(epoch.epochZeroStartHeight).toBeDefined();
+  });
 });