feat: add getStakeActivation (#12274)

* feat: add getStakeActivation

* chore: add rollup watch

* feat: use string literal for stake activation state

* fix: remove optional chaining due to issue with esdoc

* chore: remove optional_chaining

* feat: add live test for getStakeActivation

* feat: extend _buildArgs to support additional options, simplify unit test

web3.js/src/connection.js

@@ -806,6 +806,20 @@ const ParsedAccountInfoResult = struct.object({
   rentEpoch: 'number?',
 });
 
+/**
+ * @private
+ */
+const StakeActivationResult = struct.object({
+  state: struct.union([
+    struct.literal('active'),
+    struct.literal('inactive'),
+    struct.literal('activating'),
+    struct.literal('deactivating'),
+  ]),
+  active: 'number',
+  inactive: 'number',
+});
+
 /**
  * Expected JSON RPC response for the "getAccountInfo" message
  */
@@ -820,6 +834,11 @@ const GetParsedAccountInfoResult = jsonRpcResultAndContext(
   struct.union(['null', ParsedAccountInfoResult]),
 );
 
+/**
+ * Expected JSON RPC response for the "getStakeActivation" message with jsonParsed param
+ */
+const GetStakeActivationResult = jsonRpcResult(StakeActivationResult);
+
 /**
  * Expected JSON RPC response for the "getConfirmedSignaturesForAddress" message
  */
@@ -1201,6 +1220,20 @@ type ParsedAccountData = {
   space: number,
 };
 
+/**
+ * Stake Activation data
+ *
+ * @typedef {Object} StakeActivationData
+ * @property {string} state: <string - the stake account's activation state, one of: active, inactive, activating, deactivating
+ * @property {number} active: stake active during the epoch
+ * @property {number} inactive: stake inactive during the epoch
+ */
+type StakeActivationData = {
+  state: 'active' | 'inactive' | 'activating' | 'deactivating',
+  active: number,
+  inactive: number,
+};
+
 /**
  * Information describing an account
  *
@@ -1857,6 +1890,36 @@ export class Connection {
       });
   }
 
+  /**
+   * Returns epoch activation information for a stake account that has been delegated
+   */
+  async getStakeActivation(
+    publicKey: PublicKey,
+    commitment: ?Commitment,
+    epoch: ?number,
+  ): Promise<StakeActivationData> {
+    const args = this._buildArgs(
+      [publicKey.toBase58()],
+      commitment,
+      undefined,
+      epoch !== undefined ? {epoch} : undefined,
+    );
+
+    const unsafeRes = await this._rpcRequest('getStakeActivation', args);
+    const res = GetStakeActivationResult(unsafeRes);
+    if (res.error) {
+      throw new Error(
+        `failed to get Stake Activation ${publicKey.toBase58()}: ${
+          res.error.message
+        }`,
+      );
+    }
+    assert(typeof res.result !== 'undefined');
+
+    const {state, active, inactive} = res.result;
+    return {state, active, inactive};
+  }
+
   /**
    * Fetch all the accounts owned by the specified program id
    *
@@ -3093,9 +3156,10 @@ export class Connection {
     args: Array<any>,
     override: ?Commitment,
     encoding?: 'jsonParsed' | 'base64',
+    extra?: any,
   ): Array<any> {
     const commitment = override || this._commitment;
-    if (commitment || encoding) {
+    if (commitment || encoding || extra) {
       let options: any = {};
       if (encoding) {
         options.encoding = encoding;
@@ -3103,6 +3167,9 @@ export class Connection {
       if (commitment) {
         options.commitment = commitment;
       }
+      if (extra) {
+        options = Object.assign(options, extra);
+      }
       args.push(options);
     }
     return args;