feat: add includeClaimable query param to vesting-info endpoints (#1860)

* Abstract relay chain logic into its own module

* Abstract vesting calculation

* Adjust types for accounts vesting

* Refactor para inclusion service to use the new abstracted relay logic

* update account vesting service

* Update test response

* Update controllers

* Change unlockable to claimable

* Update implementation to use locks

* Update types

* Updates test-helpers

* Update service

* linter

* Update docs

* update docs

* Optimize for useRcBlock

Author: TarikGul

docs-v2/dist/bundle.js

@@ -8,7 +8,7 @@ info:
   license:
     name: GPL-3.0-or-later
     url: https://github.com/paritytech/substrate-api-sidecar/blob/master/LICENSE
-  version: 20.11.0
+  version: 20.12.0
 servers:
 - url: https://polkadot-public-sidecar.parity-chains.parity.io/
   description: Polkadot Parity public sidecar
@@ -742,6 +742,12 @@ paths:
         schema:
           type: boolean
           description: When set to 'true', uses relay chain block mode with the 'at' parameter.
+      - name: includeClaimable
+        in: query
+        description: When set to 'true', calculates and includes vested amounts for each vesting schedule plus the claimable amount. For Asset Hub post-migration queries, this requires a relay chain connection since vesting schedules use relay chain block numbers.
+        required: false
+        schema:
+          type: boolean
       responses:
         "200":
           description: successful operation
@@ -978,6 +984,12 @@ paths:
           description: Block height (as a non-negative integer) or hash
             (as a hex string).
           format: unsignedInteger or $hex
+      - name: includeClaimable
+        in: query
+        description: When set to 'true', calculates and includes vested amounts for each vesting schedule plus the claimable amount. For relay chain pre-migration queries, vested amounts are calculated using the relay chain's own block number.
+        required: false
+        schema:
+          type: boolean
       responses:
         "200":
           description: successful operation
@@ -5332,6 +5344,28 @@ components:
           type: string
           description: The Asset Hub block timestamp. Only present when `useRcBlock` parameter is used.
           format: unsignedInteger
+        vestedBalance:
+          type: string
+          description: Total vested amount across all schedules based on time elapsed. Only present when `includeClaimable` parameter is used.
+          format: unsignedInteger
+        vestingTotal:
+          type: string
+          description: Total locked amount across all vesting schedules. Only present when `includeClaimable` parameter is used.
+          format: unsignedInteger
+        vestedClaimable:
+          type: string
+          description: Actual amount that can be claimed now (vestedBalance minus already claimed). Only present when `includeClaimable` parameter is used.
+          format: unsignedInteger
+        blockNumberForCalculation:
+          type: string
+          description: The block number used for vesting calculations. Only present when `includeClaimable` parameter is used.
+          format: unsignedInteger
+        blockNumberSource:
+          type: string
+          description: Which chain's block number was used for calculations ('relay' or 'self'). Only present when `includeClaimable` parameter is used.
+          enum:
+            - relay
+            - self
     AddressDetails:
       type: object
       properties:
@@ -8125,6 +8159,10 @@ components:
           type: string
           description: Starting block for unlocking (vesting).
           format: unsignedInteger
+        vested:
+          type: string
+          description: Amount that has vested based on time elapsed for this schedule. Only present when `includeClaimable` parameter is used.
+          format: unsignedInteger
       description: Vesting schedule for an account.
     WeightsV2:
       type: object

docs-v2/openapi-v1.yaml

@@ -742,6 +742,12 @@ paths:
         schema:
           type: boolean
           description: When set to 'true', uses relay chain block mode with the 'at' parameter.
+      - name: includeClaimable
+        in: query
+        description: When set to 'true', calculates and includes vested amounts for each vesting schedule plus the claimable amount. For Asset Hub post-migration queries, this requires a relay chain connection since vesting schedules use relay chain block numbers.
+        required: false
+        schema:
+          type: boolean
       responses:
         "200":
           description: successful operation
@@ -978,6 +984,12 @@ paths:
           description: Block height (as a non-negative integer) or hash
             (as a hex string).
           format: unsignedInteger or $hex
+      - name: includeClaimable
+        in: query
+        description: When set to 'true', calculates and includes vested amounts for each vesting schedule plus the claimable amount. For relay chain pre-migration queries, vested amounts are calculated using the relay chain's own block number.
+        required: false
+        schema:
+          type: boolean
       responses:
         "200":
           description: successful operation
@@ -5332,6 +5344,28 @@ components:
           type: string
           description: The Asset Hub block timestamp. Only present when `useRcBlock` parameter is used.
           format: unsignedInteger
+        vestedBalance:
+          type: string
+          description: Total vested amount across all schedules based on time elapsed. Only present when `includeClaimable` parameter is used.
+          format: unsignedInteger
+        vestingTotal:
+          type: string
+          description: Total locked amount across all vesting schedules. Only present when `includeClaimable` parameter is used.
+          format: unsignedInteger
+        vestedClaimable:
+          type: string
+          description: Actual amount that can be claimed now (vestedBalance minus already claimed). Only present when `includeClaimable` parameter is used.
+          format: unsignedInteger
+        blockNumberForCalculation:
+          type: string
+          description: The block number used for vesting calculations. Only present when `includeClaimable` parameter is used.
+          format: unsignedInteger
+        blockNumberSource:
+          type: string
+          description: Which chain's block number was used for calculations ('relay' or 'self'). Only present when `includeClaimable` parameter is used.
+          enum:
+            - relay
+            - self
     AddressDetails:
       type: object
       properties:
@@ -8125,6 +8159,10 @@ components:
           type: string
           description: Starting block for unlocking (vesting).
           format: unsignedInteger
+        vested:
+          type: string
+          description: Amount that has vested based on time elapsed for this schedule. Only present when `includeClaimable` parameter is used.
+          format: unsignedInteger
       description: Vesting schedule for an account.
     WeightsV2:
       type: object

docs/dist/app.bundle.js

@@ -14,6 +14,7 @@
 // You should have received a copy of the GNU General Public License
 // along with this program.  If not, see <http://www.gnu.org/licenses/>.
 
+import BN from 'bn.js';
 import { RequestHandler } from 'express';
 import { IAddressParam } from 'src/types/requests';
 
@@ -30,7 +31,12 @@ import AbstractController from '../AbstractController';
  * Query params:
  * - (Optional)`at`: Block at which to retrieve runtime version information at. Block
  * 		identifier, as the block height or block hash. Defaults to most recent block.
- * - (Optional)`useRcBlock`: When set to 'true', uses the relay chain block specified in the 'at' parameter to determine corresponding Asset Hub block(s). Only supported for Asset Hub endpoints.
+ * - (Optional)`includeClaimable`: When set to 'true', calculates and includes vested
+ *      amounts for each vesting schedule plus the claimable amount. This may require a
+ *      relay chain connection for Asset Hub post-migration queries. Defaults to 'false'.
+ * - (Optional)`useRcBlock`: When set to 'true', uses the relay chain block specified in the
+ *      'at' parameter to determine corresponding Asset Hub block(s). Only supported for
+ *      Asset Hub endpoints.
  *
  * Returns:
  * - When using `useRcBlock` parameter: An array of response objects, one for each Asset Hub block found
@@ -39,13 +45,23 @@ import AbstractController from '../AbstractController';
  *
  * Response object structure:
  * - `at`: Block number and hash at which the call was made.
- * - `vesting`: Vesting schedule for an account.
+ * - `vesting`: Array of vesting schedules for an account.
  *   - `locked`: Number of tokens locked at start.
  *   - `perBlock`: Number of tokens that gets unlocked every block after `startingBlock`.
  *   - `startingBlock`: Starting block for unlocking(vesting).
- * - `rcBlockNumber`: The relay chain block number used for the query. Only present when `useRcBlock` parameter is used.
+ *   - `vested`: (Only when `includeClaimable=true`) Amount that has vested based on time elapsed.
+ * - `vestedBalance`: (Only when `includeClaimable=true`) Total vested across all schedules.
+ * - `vestingTotal`: (Only when `includeClaimable=true`) Total locked across all schedules.
+ * - `vestedClaimable`: (Only when `includeClaimable=true`) Actual amount that can be claimed now.
+ * - `blockNumberForCalculation`: (Only when `includeClaimable=true`) The block number used for calculations.
+ * - `blockNumberSource`: (Only when `includeClaimable=true`) Which chain's block number was used ('relay' or 'self').
+ * - `rcBlockHash`: The relay chain block hash. Only present when `useRcBlock` parameter is used.
+ * - `rcBlockNumber`: The relay chain block number. Only present when `useRcBlock` parameter is used.
  * - `ahTimestamp`: The Asset Hub block timestamp. Only present when `useRcBlock` parameter is used.
  *
+ * Note: When `includeClaimable=true` for Asset Hub post-migration queries, a relay chain
+ * connection is required since vesting schedules use relay chain block numbers.
+ *
  * Substrate Reference:
  * - Vesting Pallet: https://crates.parity.io/pallet_vesting/index.html
  * - `VestingInfo`: https://crates.parity.io/pallet_vesting/struct.VestingInfo.html
@@ -72,9 +88,11 @@ export default class AccountsVestingInfoController extends AbstractController<Ac
 	 * @param res Express Response
 	 */
 	private getAccountVestingInfo: RequestHandler<IAddressParam> = async (
-		{ params: { address }, query: { at, useRcBlock } },
+		{ params: { address }, query: { at, useRcBlock, includeClaimable } },
 		res,
 	): Promise<void> => {
+		const shouldIncludeClaimable = includeClaimable === 'true';
+
 		if (useRcBlock === 'true') {
 			const rcAtResults = await this.getHashFromRcAt(at);
 
@@ -87,7 +105,13 @@ export default class AccountsVestingInfoController extends AbstractController<Ac
 			// Process each Asset Hub block found
 			const results = [];
 			for (const { ahHash, rcBlockHash, rcBlockNumber } of rcAtResults) {
-				const result = await this.service.fetchAccountVestingInfo(ahHash, address);
+				// Pass rcBlockNumber to skip relay block search when includeClaimable is used
+				const result = await this.service.fetchAccountVestingInfo(
+					ahHash,
+					address,
+					shouldIncludeClaimable,
+					new BN(rcBlockNumber),
+				);
 
 				const apiAt = await this.api.at(ahHash);
 				const ahTimestamp = await apiAt.query.timestamp.now();
@@ -105,7 +129,7 @@ export default class AccountsVestingInfoController extends AbstractController<Ac
 			AccountsVestingInfoController.sanitizedSend(res, results);
 		} else {
 			const hash = await this.getHashFromAt(at);
-			const result = await this.service.fetchAccountVestingInfo(hash, address);
+			const result = await this.service.fetchAccountVestingInfo(hash, address, shouldIncludeClaimable);
 			AccountsVestingInfoController.sanitizedSend(res, result);
 		}
 	};

docs/src/openapi-v1.yaml

@@ -31,13 +31,24 @@ import AbstractController from '../../AbstractController';
  * Query params:
  * - (Optional)`at`: Block at which to retrieve vesting information at. Block
  * 		identifier, as the block height or block hash. Defaults to most recent block.
+ * - (Optional)`includeClaimable`: When set to 'true', calculates and includes vested
+ *      amounts for each vesting schedule plus the claimable amount. Defaults to 'false'.
  *
  * Returns:
  * - `at`: Block number and hash at which the call was made.
- * - `vesting`: Vesting schedule for an account.
+ * - `vesting`: Array of vesting schedules for an account.
  *   - `locked`: Number of tokens locked at start.
  *   - `perBlock`: Number of tokens that gets unlocked every block after `startingBlock`.
  *   - `startingBlock`: Starting block for unlocking(vesting).
+ *   - `vested`: (Only when `includeClaimable=true`) Amount that has vested based on time elapsed.
+ * - `vestedBalance`: (Only when `includeClaimable=true`) Total vested across all schedules.
+ * - `vestingTotal`: (Only when `includeClaimable=true`) Total locked across all schedules.
+ * - `vestedClaimable`: (Only when `includeClaimable=true`) Actual amount that can be claimed now.
+ * - `blockNumberForCalculation`: (Only when `includeClaimable=true`) The block number used for calculations.
+ * - `blockNumberSource`: (Only when `includeClaimable=true`) Which chain's block number was used ('relay' or 'self').
+ *
+ * Note: For relay chain pre-migration queries, vested amounts are calculated using the relay
+ * chain's own block number. Post-migration, vesting has moved to Asset Hub.
  *
  * Substrate Reference:
  * - Vesting Pallet: https://crates.parity.io/pallet_vesting/index.html
@@ -70,7 +81,7 @@ export default class RcAccountsVestingInfoController extends AbstractController<
 	 * @param res Express Response
 	 */
 	private getAccountVestingInfo: RequestHandler<IAddressParam> = async (
-		{ params: { address }, query: { at } },
+		{ params: { address }, query: { at, includeClaimable } },
 		res,
 	): Promise<void> => {
 		const rcApi = ApiPromiseRegistry.getApiByType('relay')[0]?.api;
@@ -79,8 +90,9 @@ export default class RcAccountsVestingInfoController extends AbstractController<
 			throw new Error('Relay chain API not found, please use SAS_SUBSTRATE_MULTI_CHAIN_URL env variable');
 		}
 
+		const shouldIncludeClaimable = includeClaimable === 'true';
 		const hash = await this.getHashFromAt(at, { api: rcApi });
-		const result = await this.service.fetchAccountVestingInfo(hash, address);
+		const result = await this.service.fetchAccountVestingInfo(hash, address, shouldIncludeClaimable);
 
 		RcAccountsVestingInfoController.sanitizedSend(res, result);
 	};