feat: add in-transit XCM msgs in blocks endpoint

docs/src/openapi-v1.yaml

@@ -693,17 +693,17 @@ paths:
           type: boolean
       - name: decodedXcmMsgs
         in: query
-        description: When set to `true`, this will show the decoded XCM messages within
-          the extrinsics of the requested block.
+        description: When set to `true`, this will show the decoded XCM messages within the extrinsics 
+          of the requested block.
         required: false
         schema:
           type: boolean
           default: false
       - name: paraId
         in: query
-        description: When it is set, this will return only the decoded XCM messages
-          for the specified paraId/parachain Id. To activate this functionality,
-          ensure that the `decodedXcmMsgs` parameter is set to true.
+        description: When it is set, this will return only the decoded XCM messages for the specified
+          origin Parachain Id (originParaId). To activate this functionality, ensure that the `decodedXcmMsgs`
+          parameter is set to true.
         required: false
         schema:
           type: string
@@ -843,17 +843,17 @@ paths:
           default: false
       - name: decodedXcmMsgs
         in: query
-        description: When set to `true`, this will show the decoded XCM messages within
-          the extrinsics of the requested block.
+        description: When set to `true`, this will show the decoded XCM messages within the extrinsics 
+          of the requested block.
         required: false
         schema:
           type: boolean
           default: false
       - name: paraId
         in: query
-        description: When it is set, this will return only the decoded XCM messages
-          for the specified paraId/parachain Id. To activate this functionality,
-          ensure that the `decodedXcmMsgs` parameter is set to true.
+        description: When it is set, this will return only the decoded XCM messages for the specified
+          origin Parachain Id (originParaId). To activate this functionality, ensure that the `decodedXcmMsgs`
+          parameter is set to true.
         required: false
         schema:
           type: string
@@ -2901,6 +2901,9 @@ components:
       allOf:
         - $ref: "#/components/schemas/Block"
         - $ref: "#/components/schemas/DecodedXcmMsgs"
+      description: Block information that includes the decoded XCM messages if any are found in the queried block.
+        If not, the decodedXcmMsgs object will be returned with three empty arrays corresponding to each direction,
+        horizontalMessages, downwardMessages, upwardMessages.
     BondedPool:
       type: object
       properties:
@@ -2967,22 +2970,16 @@ components:
         decodedXcmMsgs:
           type: object
           properties:
-            horizontalMessages:
-              type: array
-              items:
-                type: object
-                properties:
-                  sentAt:
-                    type: string
-                    format: unsignedInteger
-                    description: Represents the block number that the XCM message was sent at on the relay chain.
-                  paraId:
-                    type: string
-                    format: unsignedInteger
-                    description: The paraId that the specific XCM message was sent from.
-                  data:
-                    type: object
-                    description: The decoded instructions and their respective fields that are included in the XCM message.
+            horizontalMessages: {
+              "oneOf": [
+                {
+                  "$ref": "#/components/schemas/DecodedXcmMsgsHorizontalMessagesInRelay"
+                },
+                {
+                  "$ref": "#/components/schemas/DecodedXcmMsgsHorizontalMessagesInParachain"
+                }
+              ]
+            }
             downwardMessages:
               type: array
               items:
@@ -2997,21 +2994,63 @@ components:
                     description: Represents the XCM message.
                   data:
                     type: object
-                    description: The decoded instructions and their respective fields that are included in the XCM message.
+                    description: The decoded instructions included in the XCM message and their respective fields.
             upwardMessages:
               type: array
               items:
                 type: object
                 properties:
-                  paraId:
+                  originParaId:
                     type: string
                     format: unsignedInteger
-                    description: The paraId that the specific XCM message was sent from.
+                    description: The Parachain id that the specific XCM message was sent from.
                   data:
                     type: object
-                    description: The decoded instructions and their respective fields that are included in the XCM message.
-      description: Object with three arrays, one for every XCM direction. The arrays are populated or left
-        empty based on the direction of the current XCM message that is being decoded.
+                    description: The decoded instructions included in the XCM message and their respective fields.
+      description: 
+        Object with three arrays, one for every XCM direction. The arrays are populated or left empty based on the direction 
+        of the current XCM message that is being decoded. The XCM messages can be Upward and/or Horizontal (`in transit`) messages when
+        connected to a Relay chain. When connected to a Parachain, the messages can be Downward and/or Horizontal. One or more messages
+        can be present in a single block. In case of multiple messages from the same paraIds (originParaId and/or destinationParaId),
+        the messages will be shown under the field `data`. 
+    DecodedXcmMsgsHorizontalMessagesInRelay:
+      type: array
+      items:
+        type: object
+        properties:
+          originParaId:
+            type: string
+            format: unsignedInteger
+            description: The Parachain id that the specific XCM message was sent from.
+          destinationParaId:
+            type: string
+            format: unsignedInteger
+            description: The Parachain id that the specific XCM message was sent at.
+          data:
+            type: object
+            description: The decoded instructions included in the XCM message and their respective fields.
+        description: Array that includes the Horizontal (`in transit`) messages when we are connected to a Relay Chain.
+          Each block can contain one or more messages. If multiple messages share the same origin and destination paraId,
+          they will be displayed within the data field.
+    DecodedXcmMsgsHorizontalMessagesInParachain:
+      type: array
+      items:
+        type: object
+        properties:
+          sentAt:
+            type: string
+            format: unsignedInteger
+            description: Represents the block number that the XCM message was sent at on the relay chain.
+          originParaId:
+            type: string
+            format: unsignedInteger
+            description: The Parachain id that the specific XCM message was sent from.
+          data:
+            type: object
+            description: The decoded instructions included in the XCM message and their respective fields.
+        description: Array that includes the Horizontal Messages when we are connected to a Parachain.
+          Each block can contain one or more messages. If multiple messages originate from the same parachain (originParaId),
+          they will be displayed within the data field.
     DigestItem:
       type: object
       properties:

src/services/blocks/BlocksService.spec.ts

@@ -41,8 +41,10 @@ import {
 	blockHash3356195,
 	blockHash6202603,
 	blockHash18468942,
+	blockHash19772575,
 	defaultMockApi,
 	mockApiBlock18468942,
+	mockApiBlock19772575,
 	mockAssetHubKusamaApiBlock3356195,
 	mockAssetHubKusamaApiBlock6202603,
 	mockForkedBlock789629,
@@ -52,16 +54,19 @@ import { events789629 } from '../test-helpers/mock/data/events789629Hex';
 import { events3356195 } from '../test-helpers/mock/data/events3356195Hex';
 import { events6202603 } from '../test-helpers/mock/data/events6202603Hex';
 import { events18468942 } from '../test-helpers/mock/data/events18468942Hex';
+import { events19772575 } from '../test-helpers/mock/data/events19772575Hex';
 import { validators789629Hex } from '../test-helpers/mock/data/validators789629Hex';
 import { validators3356195Hex } from '../test-helpers/mock/data/validators3356195Hex';
 import { validators6202603Hex } from '../test-helpers/mock/data/validators6202603Hex';
 import { validators18468942Hex } from '../test-helpers/mock/data/validators18468942Hex';
+import { validators19772575Hex } from '../test-helpers/mock/data/validators19772575Hex';
 import { parseNumberOrThrow } from '../test-helpers/mock/parseNumberOrThrow';
 import block789629Extrinsic from '../test-helpers/responses/blocks/block789629Extrinsic.json';
 import block3356195Response from '../test-helpers/responses/blocks/block3356195.json';
 import block6202603pId2087Response from '../test-helpers/responses/blocks/block6202603paraId2087.json';
 import block18468942Response from '../test-helpers/responses/blocks/block18468942.json';
 import block18468942pId2000Response from '../test-helpers/responses/blocks/block18468942paraId2000.json';
+import block19772575Response from '../test-helpers/responses/blocks/block19772575.json';
 import blocks789629Response from '../test-helpers/responses/blocks/blocks789629.json';
 import blocks789629Raw from '../test-helpers/responses/blocks/blocks789629Raw.json';
 import { BlocksService } from './BlocksService';
@@ -767,5 +772,81 @@ describe('BlocksService', () => {
 
 			expect(sanitizeNumbers(block)).toMatchObject(block6202603pId2087Response);
 		});
+
+		it('Should give back two decoded horizontal XCM messages (with different origin & destination paraId) that are `in transit` in Polkadot Relay block 19772575', async () => {
+			// Reset LRU cache
+			cache.clear();
+
+			// fetchBlock options
+			const options = {
+				eventDocs: true,
+				extrinsicDocs: true,
+				checkFinalized: false,
+				queryFinalizedHead: false,
+				omitFinalizedTag: false,
+				noFees: false,
+				checkDecodedXcm: true,
+				paraId: undefined,
+			};
+
+			const validatorsAt = (_hash: Hash) =>
+				Promise.resolve().then(() => polkadotRegistryV1000001.createType('Vec<ValidatorId>', validators19772575Hex));
+
+			const eventsAt = (_hash: Hash) =>
+				Promise.resolve().then(() => polkadotRegistryV1000001.createType('Vec<EventRecord>', events19772575));
+
+			const nextFeeMultiplierAt = (_hash: Hash) =>
+				Promise.resolve().then(() => polkadotRegistryV1000001.createType('Fixed128', 1000000000));
+
+			const mockHistoricApiXCM = {
+				registry: polkadotRegistryV1000001,
+				call: {
+					transactionPaymentApi: {},
+				},
+				consts: {
+					transactionPayment: {
+						transactionByteFee: polkadotRegistryV1000001.createType('Balance', 1000000),
+						weightToFee: [
+							{
+								coeffFrac: polkadotRegistryV1000001.createType('Perbill', 80000000),
+								coeffInteger: polkadotRegistryV1000001.createType('Balance', 0),
+								degree: polkadotRegistryV1000001.createType('u8', 1),
+								negative: false,
+							},
+						],
+					},
+					system: {
+						extrinsicBaseWeight: polkadotRegistryV1000001.createType('u64', 125000000),
+					},
+				},
+				query: {
+					session: {
+						validators: validatorsAt,
+					},
+					system: {
+						events: eventsAt,
+					},
+					transactionPayment: {
+						nextFeeMultiplier: nextFeeMultiplierAt,
+					},
+				},
+			} as unknown as ApiDecoration<'promise'>;
+
+			const mockApiXCM = {
+				...mockApiBlock19772575,
+				query: {
+					transactionPayment: {
+						nextFeeMultiplier: { at: nextFeeMultiplierAt },
+					},
+				},
+				at: (_hash: Hash) => mockHistoricApiXCM,
+			} as unknown as ApiPromise;
+
+			// Block Service
+			const blocksServiceXCM = new BlocksService(mockApiXCM, 0, cache, new QueryFeeDetailsCache(null, null));
+			const block = await blocksServiceXCM.fetchBlock(blockHash19772575, mockHistoricApiXCM, options);
+
+			expect(sanitizeNumbers(block)).toMatchObject(block19772575Response);
+		});
 	});
 });