Update subgraph URLs and add indexer support

Author: flopez7

packages/sdk/python/human-protocol-sdk/human_protocol_sdk/constants.py

@@ -37,7 +37,7 @@ class OperatorCategory(Enum):
             "https://api.studio.thegraph.com/query/74256/ethereum/version/latest"
         ),
         "subgraph_url_api_key": (
-            "https://gateway-arbitrum.network.thegraph.com/api/[SUBGRAPH_API_KEY]/deployments/id/QmXGmcjEtwwEgB83KE2ECjjYY38kLMqzaq4ip8GWY7A6zz"
+            "https://gateway.thegraph.com/api/deployments/id/QmXGmcjEtwwEgB83KE2ECjjYY38kLMqzaq4ip8GWY7A6zz"
         ),
         "hmt_address": "0xd1ba9BAC957322D6e8c07a160a3A8dA11A0d2867",
         "factory_address": "0xD9c75a1Aa4237BB72a41E5E26bd8384f10c1f55a",
@@ -53,7 +53,7 @@ class OperatorCategory(Enum):
             "https://api.studio.thegraph.com/query/74256/sepolia/version/latest"
         ),
         "subgraph_url_api_key": (
-            "https://gateway-arbitrum.network.thegraph.com/api/[SUBGRAPH_API_KEY]/deployments/id/QmT4xNvZh8ymarrk1zdytjLhCW59iuTavsd4JgHS4LbCVB"
+            "https://gateway.thegraph.com/api/deployments/id/QmT4xNvZh8ymarrk1zdytjLhCW59iuTavsd4JgHS4LbCVB"
         ),
         "hmt_address": "0x792abbcC99c01dbDec49c9fa9A828a186Da45C33",
         "factory_address": "0x5987A5558d961ee674efe4A8c8eB7B1b5495D3bf",
@@ -69,7 +69,7 @@ class OperatorCategory(Enum):
             "https://api.studio.thegraph.com/query/74256/bsc/version/latest"
         ),
         "subgraph_url_api_key": (
-            "hthttps://gateway-arbitrum.network.thegraph.com/api/[SUBGRAPH_API_KEY]/deployments/id/QmdVdpm9NnFz5B8QyzhW1bW1nNfRWemTiFn2MrhYZGTSQD"
+            "https://gateway.thegraph.com/api/deployments/id/QmdVdpm9NnFz5B8QyzhW1bW1nNfRWemTiFn2MrhYZGTSQD"
         ),
         "hmt_address": "0x711Fd6ab6d65A98904522d4e3586F492B989c527",
         "factory_address": "0x92FD968AcBd521c232f5fB8c33b342923cC72714",
@@ -85,7 +85,7 @@ class OperatorCategory(Enum):
             "https://api.studio.thegraph.com/query/74256/bsc-testnet/version/latest"
         ),
         "subgraph_url_api_key": (
-            "https://gateway-arbitrum.network.thegraph.com/api/[SUBGRAPH_API_KEY]/deployments/id/QmZjYMktZe8RAz7W7qL33VZBV6AC57xsLyE1cEfv6NABdZ"
+            "https://gateway.thegraph.com/api/deployments/id/QmZjYMktZe8RAz7W7qL33VZBV6AC57xsLyE1cEfv6NABdZ"
         ),
         "hmt_address": "0xE3D74BBFa45B4bCa69FF28891fBE392f4B4d4e4d",
         "factory_address": "0x2bfA592DBDaF434DDcbb893B1916120d181DAD18",
@@ -103,7 +103,7 @@ class OperatorCategory(Enum):
             "https://api.studio.thegraph.com/query/74256/polygon/version/latest"
         ),
         "subgraph_url_api_key": (
-            "https://gateway-arbitrum.network.thegraph.com/api/[SUBGRAPH_API_KEY]/deployments/id/QmUt9mmfNjtC5ZnQNiWHRbFG3k5zfngMuoTyky9jhXYqG2"
+            "https://gateway.thegraph.com/api/deployments/id/QmUt9mmfNjtC5ZnQNiWHRbFG3k5zfngMuoTyky9jhXYqG2"
         ),
         "hmt_address": "0xc748B2A084F8eFc47E086ccdDD9b7e67aEb571BF",
         "factory_address": "0xBDBfD2cC708199C5640C6ECdf3B0F4A4C67AdfcB",
@@ -121,7 +121,7 @@ class OperatorCategory(Enum):
             "https://api.studio.thegraph.com/query/74256/amoy/version/latest"
         ),
         "subgraph_url_api_key": (
-            "https://gateway-arbitrum.network.thegraph.com/api/[SUBGRAPH_API_KEY]/deployments/id/QmWRUFWpWoRRUh7Ec1HUJEwxc84DkP4iFTfLLsoVngJAPa"
+            "https://gateway.thegraph.com/api/deployments/id/QmWRUFWpWoRRUh7Ec1HUJEwxc84DkP4iFTfLLsoVngJAPa"
         ),
         "hmt_address": "0x792abbcC99c01dbDec49c9fa9A828a186Da45C33",
         "factory_address": "0xAFf5a986A530ff839d49325A5dF69F96627E8D29",

packages/sdk/python/human-protocol-sdk/human_protocol_sdk/utils.py

@@ -38,6 +38,7 @@ class SubgraphOptions:
 
     max_retries: Optional[int] = None
     base_delay: Optional[int] = None  # milliseconds
+    indexer_id: Optional[str] = None
 
 
 def is_indexer_error(error: Exception) -> bool:
@@ -90,40 +91,50 @@ def custom_gql_fetch(
 
     :raise Exception: If the subgraph query fails
     """
+    subgraph_api_key = os.getenv("SUBGRAPH_API_KEY", "")
+
     if not options:
         return _fetch_subgraph_data(network, query, params)
 
-    if (
-        options.max_retries is not None
-        and options.base_delay is None
-        or options.max_retries is None
-        and options.base_delay is not None
-    ):
+    has_max_retries = options.max_retries is not None
+    has_base_delay = options.base_delay is not None
+
+    if has_max_retries != has_base_delay:
         raise ValueError(
             "Retry configuration must include both max_retries and base_delay"
         )
 
-    max_retries = int(options.max_retries)
-    base_delay = options.base_delay / 1000
+    if options.indexer_id and not subgraph_api_key:
+        raise ValueError(
+            "Routing requests to a specific indexer requires SUBGRAPH_API_KEY to be set"
+        )
+
+    max_retries = int(options.max_retries) if has_max_retries else 0
+    base_delay_seconds = (options.base_delay or 0) / 1000
 
     last_error = None
 
     for attempt in range(max_retries + 1):
         try:
-            return _fetch_subgraph_data(network, query, params)
+            return _fetch_subgraph_data(network, query, params, options.indexer_id)
         except Exception as error:
             last_error = error
 
             if not is_indexer_error(error):
                 break
 
-            delay = base_delay * attempt
+            delay = base_delay_seconds * attempt
             time.sleep(delay)
 
     raise last_error
 
 
-def _fetch_subgraph_data(network: dict, query: str, params: dict = None):
+def _fetch_subgraph_data(
+    network: dict,
+    query: str,
+    params: dict = None,
+    indexer_id: Optional[str] = None,
+):
     subgraph_api_key = os.getenv("SUBGRAPH_API_KEY", "")
     if subgraph_api_key:
         subgraph_url = network["subgraph_url_api_key"].replace(
@@ -135,7 +146,15 @@ def _fetch_subgraph_data(network: dict, query: str, params: dict = None):
         )
         subgraph_url = network["subgraph_url"]
 
-    request = requests.post(subgraph_url, json={"query": query, "variables": params})
+    subgraph_url = _attach_indexer_id(subgraph_url, indexer_id)
+
+    headers = (
+        {"Authorization": f"Bearer {subgraph_api_key}"} if subgraph_api_key else None
+    )
+
+    request = requests.post(
+        subgraph_url, json={"query": query, "variables": params}, headers=headers
+    )
     if request.status_code == 200:
         return request.json()
     else:
@@ -146,6 +165,12 @@ def _fetch_subgraph_data(network: dict, query: str, params: dict = None):
         )
 
 
+def _attach_indexer_id(url: str, indexer_id: Optional[str]) -> str:
+    if not indexer_id:
+        return url
+    return f"{url}/indexers/id/{indexer_id}"
+
+
 def get_hmt_balance(wallet_addr, token_addr, w3):
     """Get HMT balance
 

packages/sdk/python/human-protocol-sdk/test/human_protocol_sdk/test_utils.py

@@ -1,8 +1,11 @@
+import os
 import unittest
 from unittest.mock import Mock, patch
 from validators import ValidationError
 
 from human_protocol_sdk.utils import (
+    _attach_indexer_id,
+    _fetch_subgraph_data,
     SubgraphOptions,
     custom_gql_fetch,
     is_indexer_error,
@@ -53,6 +56,12 @@ def setUp(self):
         }
         self.query = "query Test"
         self.variables = {"foo": "bar"}
+        if "SUBGRAPH_API_KEY" in os.environ:
+            del os.environ["SUBGRAPH_API_KEY"]
+
+    def tearDown(self):
+        if "SUBGRAPH_API_KEY" in os.environ:
+            del os.environ["SUBGRAPH_API_KEY"]
 
     def test_returns_response_without_options(self):
         expected = {"data": {"ok": True}}
@@ -126,3 +135,65 @@ def test_raises_after_exhausting_retries(self):
 
         self.assertTrue(is_indexer_error(ctx.exception))
         self.assertEqual(mock_fetch.call_count, 3)
+
+    def test_routes_requests_to_specific_indexer(self):
+        options = SubgraphOptions(indexer_id="0xabc123")
+        expected = {"data": {"ok": True}}
+        os.environ["SUBGRAPH_API_KEY"] = "secure-token"
+
+        with patch(
+            "human_protocol_sdk.utils._fetch_subgraph_data",
+            return_value=expected,
+        ) as mock_fetch:
+            result = custom_gql_fetch(
+                self.network, self.query, self.variables, options=options
+            )
+
+        self.assertEqual(result, expected)
+        mock_fetch.assert_called_once_with(
+            self.network, self.query, self.variables, "0xabc123"
+        )
+
+    def test_raises_when_indexer_without_api_key(self):
+        options = SubgraphOptions(indexer_id="0xabc123")
+
+        with self.assertRaises(ValueError) as ctx:
+            custom_gql_fetch(self.network, self.query, self.variables, options)
+
+        self.assertIn(
+            "Routing requests to a specific indexer requires SUBGRAPH_API_KEY to be set",
+            str(ctx.exception),
+        )
+
+    def test_fetch_subgraph_adds_authorization_header(self):
+        network = {
+            "subgraph_url": "http://subgraph",
+            "subgraph_url_api_key": "http://subgraph-with-key",
+        }
+
+        with patch.dict(os.environ, {"SUBGRAPH_API_KEY": "token"}, clear=True):
+            with patch("human_protocol_sdk.utils.requests.post") as mock_post:
+                mock_post.return_value.status_code = 200
+                mock_post.return_value.json.return_value = {"data": {}}
+
+                _fetch_subgraph_data(network, self.query, self.variables)
+
+        mock_post.assert_called_once()
+        self.assertEqual(
+            mock_post.call_args.kwargs.get("headers"),
+            {"Authorization": "Bearer token"},
+        )
+
+
+class TestAttachIndexerId(unittest.TestCase):
+    def test_converts_subgraph_path_to_deployment(self):
+        base_url = "https://gateway.thegraph.com/api/key/deployments/id/Qm123"
+        result = _attach_indexer_id(base_url, "0xabc")
+        self.assertEqual(
+            result,
+            "https://gateway.thegraph.com/api/key/deployments/id/Qm123/indexers/id/0xabc",
+        )
+
+    def test_returns_original_url_when_indexer_missing(self):
+        url = "https://gateway.thegraph.com/api/deployments/id/Qm123"
+        self.assertEqual(_attach_indexer_id(url, None), url)

packages/sdk/typescript/human-protocol-sdk/example/escrow.ts

@@ -9,11 +9,14 @@ export const getEscrows = async () => {
     return;
   }
 
-  const escrows = await EscrowUtils.getEscrows({
-    status: [EscrowStatus.Pending, EscrowStatus.Complete],
-    chainId: ChainId.POLYGON_AMOY,
-    first: 1000,
-  });
+  const escrows = await EscrowUtils.getEscrows(
+    {
+      status: [EscrowStatus.Pending, EscrowStatus.Complete],
+      chainId: ChainId.POLYGON_AMOY,
+      first: 10,
+    },
+    { indexerId: '0xbdfb5ee5a2abf4fc7bb1bd1221067aef7f9de491' }
+  );
 
   console.log('Pending escrows:', escrows.length);
 };

packages/sdk/typescript/human-protocol-sdk/src/constants.ts

@@ -36,7 +36,7 @@ export const NETWORKS: {
     subgraphUrl:
       'https://api.studio.thegraph.com/query/74256/ethereum/version/latest',
     subgraphUrlApiKey:
-      'https://gateway-arbitrum.network.thegraph.com/api/[SUBGRAPH_API_KEY]/deployments/id/QmXGmcjEtwwEgB83KE2ECjjYY38kLMqzaq4ip8GWY7A6zz',
+      'https://gateway.thegraph.com/api/deployments/id/QmXGmcjEtwwEgB83KE2ECjjYY38kLMqzaq4ip8GWY7A6zz',
     oldSubgraphUrl: '',
     oldFactoryAddress: '',
   },
@@ -51,7 +51,7 @@ export const NETWORKS: {
     subgraphUrl:
       'https://api.studio.thegraph.com/query/74256/sepolia/version/latest',
     subgraphUrlApiKey:
-      'https://gateway-arbitrum.network.thegraph.com/api/[SUBGRAPH_API_KEY]/deployments/id/QmT4xNvZh8ymarrk1zdytjLhCW59iuTavsd4JgHS4LbCVB',
+      'https://gateway.thegraph.com/api/deployments/id/QmT4xNvZh8ymarrk1zdytjLhCW59iuTavsd4JgHS4LbCVB',
     oldSubgraphUrl: '',
     oldFactoryAddress: '',
   },
@@ -66,7 +66,7 @@ export const NETWORKS: {
     subgraphUrl:
       'https://api.studio.thegraph.com/query/74256/bsc/version/latest',
     subgraphUrlApiKey:
-      'https://gateway-arbitrum.network.thegraph.com/api/[SUBGRAPH_API_KEY]/deployments/id/QmdVdpm9NnFz5B8QyzhW1bW1nNfRWemTiFn2MrhYZGTSQD',
+      'https://gateway.thegraph.com/api/deployments/id/QmdVdpm9NnFz5B8QyzhW1bW1nNfRWemTiFn2MrhYZGTSQD',
     oldSubgraphUrl: 'https://api.thegraph.com/subgraphs/name/humanprotocol/bsc',
     oldFactoryAddress: '0xc88bC422cAAb2ac8812de03176402dbcA09533f4',
   },
@@ -81,7 +81,7 @@ export const NETWORKS: {
     subgraphUrl:
       'https://api.studio.thegraph.com/query/74256/bsc-testnet/version/latest',
     subgraphUrlApiKey:
-      'https://gateway-arbitrum.network.thegraph.com/api/[SUBGRAPH_API_KEY]/deployments/id/QmZjYMktZe8RAz7W7qL33VZBV6AC57xsLyE1cEfv6NABdZ',
+      'https://gateway.thegraph.com/api/deployments/id/QmZjYMktZe8RAz7W7qL33VZBV6AC57xsLyE1cEfv6NABdZ',
     oldSubgraphUrl:
       'https://api.thegraph.com/subgraphs/name/humanprotocol/bsctest',
     oldFactoryAddress: '0xaae6a2646c1f88763e62e0cd08ad050ea66ac46f',
@@ -97,7 +97,7 @@ export const NETWORKS: {
     subgraphUrl:
       'https://api.studio.thegraph.com/query/74256/polygon/version/latest',
     subgraphUrlApiKey:
-      'https://gateway-arbitrum.network.thegraph.com/api/[SUBGRAPH_API_KEY]/deployments/id/QmUt9mmfNjtC5ZnQNiWHRbFG3k5zfngMuoTyky9jhXYqG2',
+      'https://gateway.thegraph.com/api/deployments/id/QmUt9mmfNjtC5ZnQNiWHRbFG3k5zfngMuoTyky9jhXYqG2',
     oldSubgraphUrl:
       'https://api.thegraph.com/subgraphs/name/humanprotocol/polygon',
     oldFactoryAddress: '0x45eBc3eAE6DA485097054ae10BA1A0f8e8c7f794',
@@ -113,7 +113,7 @@ export const NETWORKS: {
     subgraphUrl:
       'https://api.studio.thegraph.com/query/74256/amoy/version/latest',
     subgraphUrlApiKey:
-      'https://gateway-arbitrum.network.thegraph.com/api/[SUBGRAPH_API_KEY]/deployments/id/QmWRUFWpWoRRUh7Ec1HUJEwxc84DkP4iFTfLLsoVngJAPa',
+      'https://gateway.thegraph.com/api/deployments/id/QmWRUFWpWoRRUh7Ec1HUJEwxc84DkP4iFTfLLsoVngJAPa',
     oldSubgraphUrl: '',
     oldFactoryAddress: '',
   },

packages/sdk/typescript/human-protocol-sdk/src/error.ts

@@ -313,6 +313,13 @@ export const ErrorRetryParametersMissing = new Error(
   'Retry configuration must include both maxRetries and baseDelay'
 );
 
+/**
+ * @constant {Error} - Retry configuration is missing required parameters.
+ */
+export const ErrorRoutingRequestsToIndexerRequiresApiKey = new Error(
+  'Routing requests to a specific indexer requires SUBGRAPH_API_KEY to be set'
+);
+
 /**
  * @constant {Warning} - Possible version mismatch.
  */

packages/sdk/typescript/human-protocol-sdk/src/interfaces.ts

@@ -321,4 +321,9 @@ export interface SubgraphOptions {
   maxRetries?: number;
   /** Base delay between retries in milliseconds */
   baseDelay?: number;
+  /**
+   * Optional indexer identifier. When provided, requests target
+   * `{gateway}/deployments/id/<DEPLOYMENT_ID>/indexers/id/<INDEXER_ID>`.
+   */
+  indexerId?: string;
 }