Merge pull request #39 from ar-io/PE-5977-save-observations

feat(PE-5977): add save observations API

README.md

@@ -13,7 +13,7 @@ This is the home of [ar.io] SDK. This SDK provides functionality for interacting
   - [Typescript](#typescript)
 - [ArIO Contract](#ario-contract)
   - [APIs](#apis)
-    - [init](#init-signer)
+    - [init](#init-signer-)
     - [getBalance](#getbalance-address-evaluationoptions-)
     - [getBalances](#getbalances-evaluationoptions-)
     - [getGateway](#getgateway-address-evaluationoptions-)
@@ -27,6 +27,12 @@ This is the home of [ar.io] SDK. This SDK provides functionality for interacting
     - [getPrescribedObservers](#getprescribedobservers-evaluationoptions-)
     - [getAuction](#getauction-domain-evaluationoptions-)
     - [getAuctions](#getauctions-evauluationoptions-)
+    - [joinNetwork](#joinnetworkparams)
+    - [updateGatewaySettings](#updategatewaysettingsgatewaysettings)
+    - [increaseDelegateStake](#increasedelegatestake-target-qty-)
+    - [decreaseDelegateStake](#decreasedelegatestake-target-qty-)
+    - [increaseOperatorStake](#increaseoperatorstake-qty-)
+    - [decreaseOperatorStake](#decreaseoperatorstake-qty-)
   - [Custom Contracts](#custom-contracts)
 - [ANT Contracts](#arweave-name-tokens-ants)
   - [APIs](#apis-1)
@@ -569,9 +575,9 @@ const auctions = await arIO.getAuctions({ evaluationOptions });
 // }
 ```
 
-#### `joinNetwork(params) ~ Requires signer during init()`
+#### `joinNetwork(params)`
 
-Joins a gateway to the ar.io network via its associated wallet.
+Joins a gateway to the ar.io network via its associated wallet. Requires `signer` to be provided on `ArIO.init` to sign the transaction.
 
 ```typescript
 const jointNetworkParams = {
@@ -602,9 +608,9 @@ const joinNetworkTx = await authenticatedArIO.joinNetwork(joinNetworkParams);
 // t4Xr0_J4Iurt7caNST02cMotaz2FIbWQ4Kbj616RHl3
 ```
 
-#### `updateGatewaySettings(gatewaySettings) ~ Requires signer during init()`
+#### `updateGatewaySettings(gatewaySettings)`
 
-Writes new gateway settings to the callers gateway configuration.
+Writes new gateway settings to the callers gateway configuration. Requires `signer` to be provided on `ArIO.init` to sign the transaction.
 
 ```typescript
 const updateGatewaySettingsParams = {
@@ -624,9 +630,9 @@ const updateGatewaySettingsTx = await authenticatedArIO.updateGatewaySettings(
 // t4Xr0_J4Iurt7caNST02cMotaz2FIbWQ4Kbj616RHl3
 ```
 
-#### `increaseDelegateStake({ target, qty }) ~ Requires signer during init()`
+#### `increaseDelegateStake({ target, qty })`
 
-Increases the callers stake on the target gateway.
+Increases the callers stake on the target gateway. Requires `signer` to be provided on `ArIO.init` to sign the transaction.
 
 ```typescript
 const params = {
@@ -646,9 +652,9 @@ const increaseDelegateStakeTx =
 // fDrr0_J4Iurt7caNST02cMotaz2FIbWQ4Kcj616RHl3
 ```
 
-#### `decreaseDelegateStake({ target, qty }) ~ Requires signer during init()`
+#### `decreaseDelegateStake({ target, qty })`
 
-Decreases the callers stake on the target gateway.
+Decreases the callers stake on the target gateway. Requires `signer` to be provided on `ArIO.init` to sign the transaction.
 
 ```typescript
 const params = {
@@ -668,9 +674,9 @@ const decreaseDelegateStakeTx =
 // fDrr0_J4Iurt7caNST02cMotaz2FIbWQ4Kcj616RHl3
 ```
 
-#### `increaseOperatorStake({ qty }) ~ Requires signer during init()`
+#### `increaseOperatorStake({ qty })`
 
-Increases the callers operator stake. Must be executed with a wallet registered as a gateway operator.
+Increases the callers operator stake. Must be executed with a wallet registered as a gateway operator. Requires `signer` to be provided on `ArIO.init` to sign the transaction.
 
 ```typescript
 const params = {
@@ -689,9 +695,9 @@ const increaseOperatorStakeTx =
 // fDrr0_J4Iurt7caNST02cMotaz2FIbWQ4Kcj616RHl3
 ```
 
-#### `decreaseOperatorStake({ qty }) ~ Requires signer during init()`
+#### `decreaseOperatorStake({ qty })`
 
-Decreases the callers operator stake. Must be executed with a wallet registered as a gateway operator.
+Decreases the callers operator stake. Must be executed with a wallet registered as a gateway operator. Requires `signer` to be provided on `ArIO.init` to sign the transaction.
 
 ```typescript
 const params = {
@@ -710,6 +716,27 @@ const decreaseOperatorStakeTx =
 // fDrr0_J4Iurt7caNST02cMotaz2FIbWQ4Kcj616RHl3
 ```
 
+### `saveObservations({ reportTxId, failedGateways })`
+
+Saves the observations of the current epoch. Requires `signer` to be provided on `ArIO.init` to sign the transaction.
+
+```typescript
+const params = {
+  reportTxId: 'fDrr0_J4Iurt7caNST02cMotaz2FIbWQ4Kcj616RHl3',
+  failedGateways: ['t4Xr0_J4Iurt7caNST02cMotaz2FIbWQ4Kbj616RHl3'],
+};
+
+const signer = new ArweaveSigner(jwk);
+// signer required for write interactions APIs
+const authenticatedArIO = ArIO.init({ signer });
+const saveObservationsTx = await authenticatedArIO.saveObservations(params);
+
+// saveObservationsTx is an Arweave transaction.
+// example:
+// saveObservationsTx.id
+// fDrr0_J4Iurt7caNST02cMotaz2FIbWQ4Kcj616RHl3
+```
+
 ### Custom Contracts
 
 The ArIO contract client class exposes APIs relevant to the ar.io contract. It can be configured to use any contract ID that adheres to the spec of the ar.io contract. In the default case, it will automatically build and utilize a contract data provider interface that is configured to point the the known mainnet contract ID at construction time. You can provide custom contract data provider or, alternatively, a `contractTxId` to the ArIO constructor to use a different, ar.io-spec-compatible contract.

jest.integration.config.mjs

@@ -1,5 +1,6 @@
 export default {
   preset: 'ts-jest',
+  // TODO: this should be using globalSetup once this is resolved: https://github.com/kulshekhar/ts-jest/issues/4127
   setupFiles: ['./tests/integration/jest.setup.ts'],
   globalTeardown: './tests/integration/jest.teardown.ts',
   clearMocks: true,

package.json

@@ -69,7 +69,7 @@
     "format:fix": "prettier --write .",
     "test": "yarn test:unit && yarn test:integration",
     "test:unit": "yarn clean && jest --config=jest.config.mjs",
-    "test:integration": "yarn clean && docker compose up -d && jest --config=jest.integration.config.mjs && docker compose down",
+    "test:integration": "yarn clean && docker compose up -d && jest --config=jest.integration.config.mjs --runInBand && docker compose down",
     "prepare": "husky install",
     "example:mjs": "yarn build:esm && node examples/node/index.mjs",
     "example:cjs": "yarn build:cjs && node examples/node/index.cjs",

src/common.ts

@@ -39,6 +39,7 @@ import {
 export type BlockHeight = number;
 export type SortKey = string;
 export type WalletAddress = string;
+export type TransactionId = string;
 
 // TODO: append this with other configuration options (e.g. local vs. remote evaluation)
 export type ContractSigner = ArweaveSigner | ArconnectSigner;
@@ -210,6 +211,10 @@ export interface ArIOWriteContract {
     target: WalletAddress;
     qty: number;
   }): Promise<WriteInteractionResult>;
+  saveObservations(params: {
+    reportTxId: TransactionId;
+    failedGateways: WalletAddress[];
+  }): Promise<WriteInteractionResult>;
 }
 
 export type WriteInteractionResult =

src/common/ar-io.ts

@@ -31,7 +31,9 @@ import {
   JoinNetworkParams,
   Observations,
   RegistrationType,
+  TransactionId,
   UpdateGatewaySettingsParams,
+  WalletAddress,
   WeightedObserver,
   WithSigner,
   WriteInteractionResult,
@@ -374,4 +376,18 @@ export class ArIOWritable extends ArIOReadable implements ArIOWriteContract {
     });
     return res;
   }
+
+  async saveObservations(params: {
+    reportTxId: TransactionId;
+    failedGateways: WalletAddress[];
+  }): Promise<WriteInteractionResult> {
+    return this.contract.writeInteraction({
+      functionName: AR_IO_CONTRACT_FUNCTIONS.SAVE_OBSERVATIONS,
+      inputs: {
+        observerReportTxId: params.reportTxId,
+        failedGateways: params.failedGateways,
+      },
+      signer: this.signer,
+    });
+  }
 }

src/common/contracts/warp-contract.ts

@@ -59,7 +59,7 @@ export class WarpContract<T>
     cacheUrl,
     warp = defaultWarp,
     logger = new DefaultLogger({
-      level: 'debug',
+      level: 'info',
     }),
   }: {
     contractTxId: string;

tests/integration/ar-io-writable.test.ts

@@ -1,13 +1,13 @@
 import { ArweaveSigner } from 'arbundles';
 
+import { WriteInteractionResult } from '../../src/common.js';
 import { ArIO } from '../../src/common/ar-io.js';
 import { WarpContract } from '../../src/common/index.js';
 import { DefaultLogger } from '../../src/common/logger.js';
 import { ArIOState } from '../../src/contract-state.js';
 import { localCacheUrl, warp } from '../constants.js';
 
 const gatewayAddress = process.env.PRIMARY_WALLET_ADDRESS!;
-
 const contractTxId = process.env.DEPLOYED_REGISTRY_CONTRACT_TX_ID!;
 const writeTestCases = [
   [
@@ -44,15 +44,22 @@ describe('ArIO Client', () => {
   });
 
   it.each(writeTestCases)(
-    'Should execute writes with parameters: %s',
-    async (
-      functionName: string,
-      inputs: Record<string, string | number | boolean>,
-    ) => {
-      const tx = await arIO[functionName]({
+    'should execute write interaction with parameters: %s',
+    async (functionName: string, inputs: Record<string, any>) => {
+      const tx: WriteInteractionResult = await arIO[functionName]({
         ...inputs,
       });
       expect(tx).toBeDefined();
     },
   );
+
+  // it('should successfully submit saveObservations interaction with parameters', async () => {
+  //   // mine blocks so we can submit a observations
+  //   await mineBlocks({ arweave, blocks: 20 });
+  //   const tx = await arIO.saveObservations({
+  //     reportTxId: gatewayAddress,
+  //     failedGateways: [gatewayAddress],
+  //   });
+  //   expect(tx).toBeDefined();
+  // });
 });