Merge pull request #1815 from LiskHQ/1792-add-endpoint-to-fetch-escro…

…wed-NFTs

Add endpoint to fetch escrowed NFTs

docs/api/version3.md

@@ -60,6 +60,7 @@ The Lisk Service API is compatible with RESTful guidelines. The specification be
   - [Non-fungible Token (NFT)](#nft)
     - [NFT constants](#nft-constants)
     - [NFT search](#nft-search)
+    - [NFT escrowed](#nft-escrowed)
     - [NFT supported](#nft-supported)
   - [Legacy](#legacy)
     - [Legacy Account Details](#legacy-account-details)
@@ -2115,6 +2116,59 @@ Get all NFTs
 https://service.lisk.com/api/v3/nft
 ```
 
+### NFT escrowed
+
+Retrieves NFTs based on criteria defined by params.
+
+_Supports pagination._
+
+
+#### Endpoints
+
+- HTTP GET `/api/v3/nft/escrowed`
+- RPC `get.nft.escrowed`
+
+#### Request parameters
+
+| Parameter | Type | Validation | Default | Comment |
+| --------- | ---- | ---------- | ------- | ------- |
+| escrowedChainID | String | `/^\b[a-fA-F0-9]{8}\b$/` | *(empty)* |  |
+| limit | Number | `[1,100]` | 10 |  |
+| offset | Number | `[0,Inf)` | 0 |  |
+
+#### Response example
+
+200 OK
+
+```jsonc
+{
+    "data": [{
+       "escrowedChainID": "04000001",
+       "id": "0000000000000000000000000000000000",
+       "nft":{
+         "chainID": "00000000",
+         "collectionID": "10000000",
+         "index": 1,
+       },
+    }],
+    "meta": {}
+}
+```
+
+400 Bad Request
+```jsonc
+{
+  "error": true,
+  "message": "Unknown input parameter(s): <param_name>"
+}
+```
+
+#### Examples
+
+Get all escrowed NFTs
+```
+https://service.lisk.com/api/v3/nft/escrowed
+```
 
 
 ### NFT supported

services/blockchain-connector/methods/nft.js

@@ -13,17 +13,19 @@
  * Removal or modification of this copyright notice is prohibited.
  *
  */
-const {
-	getNFTConstants,
-	getSupportedNFTs,
-} = require('../shared/sdk');
+const { getNFTConstants, getNFTEscrowed, getSupportedNFTs } = require('../shared/sdk');
 
 module.exports = [
 	{
 		name: 'getNFTConstants',
 		controller: async () => getNFTConstants(),
 		params: {},
 	},
+	{
+		name: 'getNFTEscrowed',
+		controller: async () => getNFTEscrowed(),
+		params: {},
+	},
 	{
 		name: 'getSupportedNFTs',
 		controller: async () => getSupportedNFTs(),

services/blockchain-connector/shared/sdk/index.js

@@ -117,17 +117,15 @@ const {
 const { cacheCleanup } = require('./cache');
 const { formatTransaction } = require('./formatter');
 const { encodeCCM } = require('./encoder');
-const {
-	getNFTConstants,
-	getSupportedNFTs,
-} = require('./nft');
+const { getNFTConstants, getNFTEscrowed, getSupportedNFTs, updateNFTInfo } = require('./nft');
 
 const init = async () => {
 	// Initialize the local cache
 	await getNodeInfo(true);
 	await cacheRegisteredRewardModule();
 	await cacheFeeConstants();
 	await updateTokenInfo();
+	await updateNFTInfo();
 
 	// Cache all the schemas
 	setSchemas(await getSchemas());
@@ -249,5 +247,6 @@ module.exports = {
 
 	// NFT
 	getNFTConstants,
+	getNFTEscrowed,
 	getSupportedNFTs,
 };

services/blockchain-connector/shared/sdk/nft.js

@@ -13,13 +13,13 @@
 * Removal or modification of this copyright notice is prohibited.
 *
 */
-const { Exceptions: { TimeoutException }, Logger } = require('lisk-service-framework');
+const { Exceptions: { TimeoutException }, Logger, Signals } = require('lisk-service-framework');
 const { timeoutMessage } = require('./client');
 
 const logger = Logger();
 
 let moduleConstants;
-
+let escrowedNFTs;
 let supportedNFTsInfo;
 
 const getNFTConstants = async () => {
@@ -39,6 +39,31 @@ const getNFTConstants = async () => {
 	}
 };
 
+const getNFTEscrowed = async (isForceUpdate = false) => {
+	try {
+		if (isForceUpdate || !escrowedNFTs) {
+			// TODO: Fetch escrowed NFTs directly from node when implemented
+			// escrowedNFTs = await invokeEndpoint('nft_getEscrowed');
+			escrowedNFTs = [{
+				escrowedChainID: '04000001',
+				id: '0000000000000000000000000000000000',
+				nft: {
+					chainID: '00000000',
+					collectionID: '10000000',
+					index: 1,
+				},
+			}];
+		}
+		return escrowedNFTs;
+	} catch (err) {
+		if (err.message.includes(timeoutMessage)) {
+			throw new TimeoutException('Request timed out when calling \'getEscrowed\'.');
+		}
+		logger.warn(`Error returned when invoking 'nft_getEscrowed'.\n${err.stack}`);
+		throw err;
+	}
+};
+
 const getSupportedNFTs = async () => {
 	try {
 		if (!supportedNFTsInfo) {
@@ -57,7 +82,22 @@ const getSupportedNFTs = async () => {
 	}
 };
 
+const updateNFTInfo = async () => {
+	const updateNFTInfoListener = async () => {
+		try {
+			await getNFTEscrowed(true);
+		} catch (err) {
+			logger.error(`Error occurred when caching NFT information:\n${err.stack}`);
+		}
+	};
+
+	Signals.get('chain_newBlock').add(updateNFTInfoListener);
+	Signals.get('chain_deleteBlock').add(updateNFTInfoListener);
+};
+
 module.exports = {
 	getNFTConstants,
+	getNFTEscrowed,
 	getSupportedNFTs,
+	updateNFTInfo,
 };

services/blockchain-indexer/methods/dataService/controllers/nft.js

@@ -55,6 +55,19 @@ const getNFTConstants = async () => {
 	return constants;
 };
 
+const getNFTEscrowed = async () => {
+	const escrowed = {
+		data: {},
+		meta: {},
+	};
+
+	const response = await dataService.getNFTEscrowed();
+	if (response.data) escrowed.data = response.data;
+	if (response.meta) escrowed.meta = response.meta;
+
+	return escrowed;
+};
+
 const getNFTHistory = async (params) => {
 	const history = {
 		data: [],
@@ -84,6 +97,7 @@ const getSupportedNFTs = async () => {
 module.exports = {
 	getNFTs,
 	getNFTConstants,
+	getNFTEscrowed,
 	getNFTHistory,
 	getSupportedNFTs,
 };

services/blockchain-indexer/methods/dataService/modules/nft.js

@@ -16,6 +16,7 @@
 const {
 	getNFTs,
 	getNFTConstants,
+	getNFTEscrowed,
 	getNFTHistory,
 	getSupportedNFTs,
 } = require('../controllers/nft');
@@ -35,6 +36,15 @@ module.exports = [
 			offset: { optional: true, type: 'number' },
 		},
 	},
+	{
+		name: 'nft.escrowed',
+		controller: getNFTEscrowed,
+		params: {
+			escrowedChainID: { optional: true, type: 'string' },
+			limit: { optional: true, type: 'number' },
+			offset: { optional: true, type: 'number' },
+		},
+	},
 	{
 		name: 'nft.constants',
 		controller: getNFTConstants,

services/blockchain-indexer/shared/dataService/business/index.js

@@ -62,6 +62,7 @@ const {
 const {
 	getNFTs,
 	getNFTConstants,
+	getNFTEscrowed,
 	getNFTHistory,
 	getSupportedNFTs,
 } = require('./nft');
@@ -163,6 +164,7 @@ module.exports = {
 	// NFT
 	getNFTs,
 	getNFTConstants,
+	getNFTEscrowed,
 	getNFTHistory,
 	getSupportedNFTs,
 

services/blockchain-indexer/shared/dataService/business/nft/index.js

@@ -15,12 +15,14 @@
  */
 const { getNFTs } = require('./nft');
 const { getNFTConstants } = require('./constants');
+const { getNFTEscrowed } = require('./nftEscrowed');
 const { getNFTHistory } = require('./history');
 const { getSupportedNFTs } = require('./supported');
 
 module.exports = {
 	getNFTs,
 	getNFTConstants,
+	getNFTEscrowed,
 	getNFTHistory,
 	getSupportedNFTs,
 };

services/blockchain-indexer/shared/dataService/business/nft/nftEscrowed.js

@@ -0,0 +1,40 @@
+/*
+ * LiskHQ/lisk-service
+ * Copyright © 2023 Lisk Foundation
+ *
+ * See the LICENSE file at the top-level directory of this distribution
+ * for licensing information.
+ *
+ * Unless otherwise agreed in a custom licensing agreement with the Lisk Foundation,
+ * no part of this software, including this file, may be copied, modified,
+ * propagated, or distributed except according to the terms contained in the
+ * LICENSE file.
+ *
+ * Removal or modification of this copyright notice is prohibited.
+ *
+ */
+
+const { Logger } = require('lisk-service-framework');
+const { requestConnector } = require('../../../utils/request');
+
+const logger = Logger();
+
+const getNFTEscrowed = async () => {
+	try {
+		const escrowedNFTs = await requestConnector('getNFTEscrowed');
+
+		return {
+			data: escrowedNFTs,
+			meta: {},
+		};
+	} catch (err) {
+		const errMessage = `Unable to fetch escrowed NFTs from connector due to: ${err.message}.`;
+		logger.warn(errMessage);
+		logger.trace(err.stack);
+		throw new Error(errMessage);
+	}
+};
+
+module.exports = {
+	getNFTEscrowed,
+};

services/blockchain-indexer/shared/dataService/index.js

@@ -69,13 +69,6 @@ const {
 	getTokenTopBalances,
 } = require('./token');
 
-const {
-	getNFTs,
-	getNFTConstants,
-	getNFTHistory,
-	getSupportedNFTs,
-} = require('./nft');
-
 const {
 	getTransactions,
 	getPendingTransactions,
@@ -110,6 +103,14 @@ const { getValidator, validateBLSKey } = require('./validator');
 const { getGenerators } = require('./generators');
 const { invokeEndpoint } = require('./invoke');
 
+const {
+	getNFTs,
+	getNFTConstants,
+	getNFTEscrowed,
+	getSupportedNFTs,
+	getNFTHistory,
+} = require('./nft');
+
 module.exports = {
 	// Blocks
 	getBlocks,
@@ -129,6 +130,13 @@ module.exports = {
 	getStakers,
 	getPosClaimableRewards,
 
+	// NFTs
+	getNFTs,
+	getNFTEscrowed,
+	getNFTConstants,
+	getSupportedNFTs,
+	getNFTHistory,
+
 	// Token
 	tokenHasUserAccount,
 	getAvailableTokenIDs,
@@ -208,10 +216,4 @@ module.exports = {
 	resolveMainchainServiceURL,
 
 	invokeEndpoint,
-
-	// NFT
-	getNFTs,
-	getNFTConstants,
-	getNFTHistory,
-	getSupportedNFTs,
 };

services/blockchain-indexer/shared/dataService/nft/index.js

@@ -15,12 +15,14 @@
  */
 const { getNFTs } = require('./nft');
 const { getNFTConstants } = require('./constants');
+const { getNFTEscrowed } = require('./nftEscrowed');
 const { getNFTHistory } = require('./history');
 const { getSupportedNFTs } = require('./supported');
 
 module.exports = {
 	getNFTs,
 	getNFTConstants,
+	getNFTEscrowed,
 	getNFTHistory,
 	getSupportedNFTs,
 };