feat: Add accounts/{}/foreign-asset-balances (#1834)

* feat: Add accounts/{}/foreign-asset-balances

* feat: Query optimization for accounts/{}/foreign-asset-balances

Inspired from Filippo's suggestion

* fix: Have isFrozen return false if pallet is not available

* docs: Add docs for foreign-asset-balances

* feat: Address Tarik's comments on typing

Using XcmVersionedLocation now.

* style: Remove annoying inline linting rules from AccountsFerignAssetsService.ts

Author: andrew-ifrita

docs-v2/dist/bundle.js

@@ -434,6 +434,70 @@ paths:
             application/json:
               schema:
                 $ref: '#/components/schemas/Error'
+  /accounts/{accountId}/foreign-asset-balances:
+    get:
+      tags:
+      - accounts
+      summary: Get an array of foreign-asset-balances for an account.
+      description: Returns information about an account's foreign-asset-balances. This is
+        specific to the foreignAssets pallet for parachains. If no `foreignAssets` query parameter
+        is provided, all foreign-asset-balances for the given account will be returned.
+      operationId: getForeignAssetBalances
+      parameters:
+      - name: accountId
+        in: path
+        description: SS58 address of the account.
+        required: true
+        schema:
+          type: string
+          format: SS58
+      - name: at
+        in: query
+        description: Block at which to query foreign-asset-balance info for the
+          specified account.
+        required: false
+        schema:
+          type: string
+          description: Block height (as a positive integer) or hash
+            (as a hex string).
+          format: unsignedInteger or $hex
+      - name: useRcBlock
+        in: query
+        description: When set to 'true', uses the relay chain block specified in the 'at' parameter to determine corresponding Asset Hub block(s) for retrieving foreign-asset-balance info. Only supported for Asset Hub endpoints. Requires 'at' parameter to specify the relay chain block. When used, returns an array of response objects (one for each Asset Hub block found) or empty array if none found.
+        required: false
+        schema:
+          type: boolean
+          description: When set to 'true', uses relay chain block mode with the 'at' parameter.
+      - name: foreignAssets
+        in: query
+        description: An array of multilocation JSON strings to be queried. If not supplied, all
+          foreign asset balances associated with the `accountId` will be returned. The array query param
+          format follows Express 4.x API. ex:`?foreignAssets[]={"parents":"1","interior":{"X1":{"Parachain":"2125"}}}&foreignAssets[]={"parents":"2","interior":{"X1":{"GlobalConsensus":"Polkadot"}}}`.
+        required: false
+        schema:
+          type: array
+          items:
+            type: string
+          description: An array of multilocation objects represented as JSON strings.
+          format: Array of JSON strings
+      responses:
+        "200":
+          description: successful operation
+          content:
+            application/json:
+              schema:
+                oneOf:
+                  - $ref: '#/components/schemas/AccountForeignAssetsBalances'
+                  - type: array
+                    items:
+                      $ref: '#/components/schemas/AccountForeignAssetsBalances'
+                description: Returns a single object when using standard parameters. Returns an array when using 'useRcBlock' parameter (array contains one object per Asset Hub block found, or empty array if none found).
+        "400":
+          description: Invalid Address, invalid blockId supplied for at query param, or invalid parameter combination
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
   /accounts/{accountId}/proxy-info:
     get:
       tags:
@@ -5065,6 +5129,49 @@ components:
           type: string
           description: The Asset Hub block timestamp. Only present when `useRcBlock` parameter is used.
           format: unsignedInteger
+    AccountForeignAssetsBalances:
+      type: object
+      properties:
+        at:
+          $ref: '#/components/schemas/BlockIdentifiers'
+        foreignAssets:
+          type: array
+          description: An array of queried foreign assets.
+          items:
+            $ref: '#/components/schemas/ForeignAssetBalance'
+        rcBlockHash:
+          type: string
+          description: The relay chain block hash used for the query. Only present when `useRcBlock` parameter is used.
+        rcBlockNumber:
+          type: string
+          description: The relay chain block number used for the query. Only present when `useRcBlock` parameter is used.
+          format: unsignedInteger
+        ahTimestamp:
+          type: string
+          description: The Asset Hub block timestamp. Only present when `useRcBlock` parameter is used.
+          format: unsignedInteger
+    ForeignAssetBalance:
+      type: object
+      properties:
+        multiLocation:
+          type: object
+          description: The multilocation identifier of the foreign asset. This is an XCM multilocation
+            object that uniquely identifies an asset across different parachains.
+        balance:
+          type: string
+          description: The balance of the foreign asset.
+          format: unsignedInteger
+        isFrozen:
+          type: boolean
+          description: Whether the asset is frozen for non-admin transfers. Returns false if the
+            runtime does not support isFrozen.
+        isSufficient:
+          type: boolean
+          description: Whether a non-zero balance of this asset is a deposit of sufficient
+            value to account for the state bloat associated with its balance storage. If set to
+            `true`, then non-zero balances may be stored without a `consumer` reference (and thus
+            an ED in the Balances pallet or whatever else is used to control user-account state
+            growth).
     AccountProxyInfo:
       type: object
       properties:

docs-v2/openapi-v1.yaml

@@ -434,6 +434,70 @@ paths:
             application/json:
               schema:
                 $ref: '#/components/schemas/Error'
+  /accounts/{accountId}/foreign-asset-balances:
+    get:
+      tags:
+      - accounts
+      summary: Get an array of foreign-asset-balances for an account.
+      description: Returns information about an account's foreign-asset-balances. This is
+        specific to the foreignAssets pallet for parachains. If no `foreignAssets` query parameter
+        is provided, all foreign-asset-balances for the given account will be returned.
+      operationId: getForeignAssetBalances
+      parameters:
+      - name: accountId
+        in: path
+        description: SS58 address of the account.
+        required: true
+        schema:
+          type: string
+          format: SS58
+      - name: at
+        in: query
+        description: Block at which to query foreign-asset-balance info for the
+          specified account.
+        required: false
+        schema:
+          type: string
+          description: Block height (as a positive integer) or hash
+            (as a hex string).
+          format: unsignedInteger or $hex
+      - name: useRcBlock
+        in: query
+        description: When set to 'true', uses the relay chain block specified in the 'at' parameter to determine corresponding Asset Hub block(s) for retrieving foreign-asset-balance info. Only supported for Asset Hub endpoints. Requires 'at' parameter to specify the relay chain block. When used, returns an array of response objects (one for each Asset Hub block found) or empty array if none found.
+        required: false
+        schema:
+          type: boolean
+          description: When set to 'true', uses relay chain block mode with the 'at' parameter.
+      - name: foreignAssets
+        in: query
+        description: An array of multilocation JSON strings to be queried. If not supplied, all
+          foreign asset balances associated with the `accountId` will be returned. The array query param
+          format follows Express 4.x API. ex:`?foreignAssets[]={"parents":"1","interior":{"X1":{"Parachain":"2125"}}}&foreignAssets[]={"parents":"2","interior":{"X1":{"GlobalConsensus":"Polkadot"}}}`.
+        required: false
+        schema:
+          type: array
+          items:
+            type: string
+          description: An array of multilocation objects represented as JSON strings.
+          format: Array of JSON strings
+      responses:
+        "200":
+          description: successful operation
+          content:
+            application/json:
+              schema:
+                oneOf:
+                  - $ref: '#/components/schemas/AccountForeignAssetsBalances'
+                  - type: array
+                    items:
+                      $ref: '#/components/schemas/AccountForeignAssetsBalances'
+                description: Returns a single object when using standard parameters. Returns an array when using 'useRcBlock' parameter (array contains one object per Asset Hub block found, or empty array if none found).
+        "400":
+          description: Invalid Address, invalid blockId supplied for at query param, or invalid parameter combination
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
   /accounts/{accountId}/proxy-info:
     get:
       tags:
@@ -5065,6 +5129,49 @@ components:
           type: string
           description: The Asset Hub block timestamp. Only present when `useRcBlock` parameter is used.
           format: unsignedInteger
+    AccountForeignAssetsBalances:
+      type: object
+      properties:
+        at:
+          $ref: '#/components/schemas/BlockIdentifiers'
+        foreignAssets:
+          type: array
+          description: An array of queried foreign assets.
+          items:
+            $ref: '#/components/schemas/ForeignAssetBalance'
+        rcBlockHash:
+          type: string
+          description: The relay chain block hash used for the query. Only present when `useRcBlock` parameter is used.
+        rcBlockNumber:
+          type: string
+          description: The relay chain block number used for the query. Only present when `useRcBlock` parameter is used.
+          format: unsignedInteger
+        ahTimestamp:
+          type: string
+          description: The Asset Hub block timestamp. Only present when `useRcBlock` parameter is used.
+          format: unsignedInteger
+    ForeignAssetBalance:
+      type: object
+      properties:
+        multiLocation:
+          type: object
+          description: The multilocation identifier of the foreign asset. This is an XCM multilocation
+            object that uniquely identifies an asset across different parachains.
+        balance:
+          type: string
+          description: The balance of the foreign asset.
+          format: unsignedInteger
+        isFrozen:
+          type: boolean
+          description: Whether the asset is frozen for non-admin transfers. Returns false if the
+            runtime does not support isFrozen.
+        isSufficient:
+          type: boolean
+          description: Whether a non-zero balance of this asset is a deposit of sufficient
+            value to account for the state bloat associated with its balance storage. If set to
+            `true`, then non-zero balances may be stored without a `consumer` reference (and thus
+            an ED in the Balances pallet or whatever else is used to control user-account state
+            growth).
     AccountProxyInfo:
       type: object
       properties:

docs/dist/app.bundle.js

@@ -25,6 +25,7 @@ export const assetHubKusamaControllers: ControllerConfig = {
 		'AccountsAssets',
 		'AccountsBalanceInfo',
 		'AccountsCompare',
+		'AccountsForeignAssets',
 		'AccountsPoolAssets',
 		'AccountsProxyInfo',
 		'AccountsStakingInfo',

docs/src/openapi-v1.yaml

@@ -24,6 +24,7 @@ export const assetHubNextWestendControllers: ControllerConfig = {
 	controllers: [
 		'AccountsAssets',
 		'AccountsBalanceInfo',
+		'AccountsForeignAssets',
 		'AccountsPoolAssets',
 		'AccountsProxyInfo',
 		'AccountsStakingInfo',

src/chains-config/assetHubKusamaControllers.ts

@@ -25,6 +25,7 @@ export const assetHubPolkadotControllers: ControllerConfig = {
 		'AccountsAssets',
 		'AccountsBalanceInfo',
 		'AccountsCompare',
+		'AccountsForeignAssets',
 		'AccountsPoolAssets',
 		'AccountsProxyInfo',
 		'AccountsStakingInfo',

src/chains-config/assetHubNextWestendControllers.ts

@@ -24,6 +24,7 @@ export const assetHubWestendControllers: ControllerConfig = {
 	controllers: [
 		'AccountsAssets',
 		'AccountsBalanceInfo',
+		'AccountsForeignAssets',
 		'AccountsPoolAssets',
 		'AccountsProxyInfo',
 		'AccountsStakingInfo',

src/chains-config/assetHubPolkadotControllers.ts

@@ -0,0 +1,120 @@
+// Copyright 2017-2025 Parity Technologies (UK) Ltd.
+// This file is part of Substrate API Sidecar.
+//
+// Substrate API Sidecar is free software: you can redistribute it and/or modify
+// it under the terms of the GNU General Public License as published by
+// the Free Software Foundation, either version 3 of the License, or
+// (at your option) any later version.
+//
+// This program is distributed in the hope that it will be useful,
+// but WITHOUT ANY WARRANTY; without even the implied warranty of
+// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+// GNU General Public License for more details.
+//
+// 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 { RequestHandler } from 'express';
+
+import { validateAddress, validateUseRcBlock } from '../../middleware';
+import { AccountsForeignAssetsService } from '../../services/accounts';
+import AbstractController from '../AbstractController';
+
+/**
+ * Get foreign asset balance information for an address.
+ *
+ * Paths:
+ * - `address`: The address to query
+ *
+ * Query:
+ * - (Optional)`at`: Block at which to retrieve balance information. Block
+ *  	identifier, as the block height or block hash. Defaults to most recent block.
+ * - (Optional) `useRcBlock`: When true, treats the `at` parameter as a relay chain block
+ *  	to find corresponding Asset Hub blocks. Only supported for Asset Hub endpoints.
+ * - (Optional)`foreignAssets`: Comma-separated list of multilocation JSON strings to filter by.
+ *    If not provided, all foreign asset balances for the account will be returned.
+ *
+ * `/accounts/:address/foreign-asset-balances`
+ * Returns:
+ * - When using `useRcBlock=true`: An array of response objects, one for each Asset Hub block found
+ *   in the specified relay chain block. Returns empty array `[]` if no Asset Hub blocks found.
+ * - When using `useRcBlock=false` or omitted: A single response object.
+ *
+ * Response object structure:
+ * - `at`: Block number and hash at which the call was made.
+ * - `foreignAssets`: An array of `ForeignAssetBalance` objects which have a multilocation attached to them
+ * 		- `multiLocation`: The multilocation identifier of the foreign asset.
+ * 		- `balance`: The balance of the foreign asset.
+ * 		- `isFrozen`: Whether the asset is frozen for non-admin transfers.
+ * 		- `isSufficient`: Whether a non-zero balance of this asset is a deposit of sufficient
+ * 			value to account for the state bloat associated with its balance storage. If set to
+ *			`true`, then non-zero balances may be stored without a `consumer` reference (and thus
+ * 			an ED in the Balances pallet or whatever else is used to control user-account state
+ *			growth).
+ * - `rcBlockHash`: The relay chain block hash used for the query. Only present when `useRcBlock=true`.
+ * - `rcBlockNumber`: The relay chain block number used for the query. Only present when `useRcBlock=true`.
+ * - `ahTimestamp`: The Asset Hub block timestamp. Only present when `useRcBlock=true`.
+ *
+ * Substrate Reference:
+ * - ForeignAssets Pallet: https://crates.parity.io/pallet_assets/index.html
+ * - `AssetBalance`: https://crates.parity.io/pallet_assets/struct.AssetBalance.html
+ * - XCM Multilocations: https://wiki.polkadot.network/docs/learn-xcm
+ *
+ */
+export default class AccountsForeignAssetsController extends AbstractController<AccountsForeignAssetsService> {
+	static controllerName = 'AccountsForeignAssets';
+	static requiredPallets = [['ForeignAssets']];
+
+	constructor(api: string) {
+		super(api, '/accounts/:address', new AccountsForeignAssetsService(api));
+		this.initRoutes();
+	}
+
+	protected initRoutes(): void {
+		this.router.use(this.path, validateAddress, validateUseRcBlock);
+
+		this.safeMountAsyncGetHandlers([['/foreign-asset-balances', this.getForeignAssetBalances]]);
+	}
+
+	private getForeignAssetBalances: RequestHandler = async (
+		{ params: { address }, query: { at, useRcBlock, foreignAssets } },
+		res,
+	): Promise<void> => {
+		if (useRcBlock === 'true') {
+			const rcAtResults = await this.getHashFromRcAt(at);
+
+			// Return empty array if no Asset Hub blocks found
+			if (rcAtResults.length === 0) {
+				AccountsForeignAssetsController.sanitizedSend(res, []);
+				return;
+			}
+
+			const foreignAssetsArray = Array.isArray(foreignAssets) ? (foreignAssets as string[]) : [];
+
+			// Process each Asset Hub block found
+			const results = [];
+			for (const { ahHash, rcBlockHash, rcBlockNumber } of rcAtResults) {
+				const result = await this.service.fetchForeignAssetBalances(ahHash, address, foreignAssetsArray);
+
+				const apiAt = await this.api.at(ahHash);
+				const ahTimestamp = await apiAt.query.timestamp.now();
+
+				const enhancedResult = {
+					...result,
+					rcBlockHash: rcBlockHash.toString(),
+					rcBlockNumber,
+					ahTimestamp: ahTimestamp.toString(),
+				};
+
+				results.push(enhancedResult);
+			}
+
+			AccountsForeignAssetsController.sanitizedSend(res, results);
+		} else {
+			const hash = await this.getHashFromAt(at);
+			const foreignAssetsArray = Array.isArray(foreignAssets) ? (foreignAssets as string[]) : [];
+			const result = await this.service.fetchForeignAssetBalances(hash, address, foreignAssetsArray);
+			AccountsForeignAssetsController.sanitizedSend(res, result);
+		}
+	};
+}