fix(tron-sdk): parse custom_rpc_header in TronJsonRpcProvider and TronTransactionBuilder (#8558)

Co-authored-by: devin-ai-integration[bot] <158243242+devin-ai-integration[bot]@users.noreply.github.com>

Author: Xaroz

.changeset/tron-custom-rpc-headers.md

@@ -0,0 +1,5 @@
+---
+"@hyperlane-xyz/tron-sdk": patch
+---
+
+TronJsonRpcProvider and TronTransactionBuilder were updated to parse custom_rpc_header query params into HTTP headers, fixing auth with third-party RPC providers like Tatum.

typescript/tron-sdk/src/ethers/TronJsonRpcProvider.ts

@@ -2,6 +2,8 @@ import { BigNumber, providers } from 'ethers';
 
 import { retryAsync } from '@hyperlane-xyz/utils';
 
+import { stripCustomRpcHeaders } from './urlUtils.js';
+
 const DEFAULT_MAX_RETRIES = 3;
 const DEFAULT_BASE_RETRY_MS = 250;
 
@@ -31,7 +33,9 @@ export class TronJsonRpcProvider extends providers.StaticJsonRpcProvider {
     maxRetries = DEFAULT_MAX_RETRIES,
     baseRetryMs = DEFAULT_BASE_RETRY_MS,
   ) {
-    super(host, network);
+    const { url: cleanUrl, headers } = stripCustomRpcHeaders(host);
+    const hasHeaders = Object.keys(headers).length > 0;
+    super(hasHeaders ? { url: cleanUrl, headers } : cleanUrl, network);
     this.host = host;
     this.maxRetries = maxRetries;
     this.baseRetryMs = baseRetryMs;

typescript/tron-sdk/src/ethers/TronWallet.ts

@@ -9,28 +9,7 @@ import {
   TronJsonRpcProvider,
 } from './TronJsonRpcProvider.js';
 import { TransactionRequest } from '@ethersproject/providers';
-
-/**
- * Extract custom_rpc_header query params from a URL into a headers object.
- * e.g. "https://api.trongrid.io?custom_rpc_header=TRON-PRO-API-KEY:abc"
- * returns { "TRON-PRO-API-KEY": "abc" }
- */
-function parseCustomHeaders(url: string): Record<string, string> {
-  const headers: Record<string, string> = {};
-  try {
-    const parsed = new URL(url);
-    for (const [key, value] of parsed.searchParams) {
-      if (key !== 'custom_rpc_header') continue;
-      const colonIdx = value.indexOf(':');
-      if (colonIdx > 0) {
-        headers[value.slice(0, colonIdx)] = value.slice(colonIdx + 1);
-      }
-    }
-  } catch {
-    // Not a valid URL, return empty headers
-  }
-  return headers;
-}
+import { stripCustomRpcHeaders } from './urlUtils.js';
 
 /** Union of possible TronWeb transaction types */
 export type TronTransaction =
@@ -80,13 +59,11 @@ export class TronWallet extends Wallet {
     // TronWeb needs the base HTTP API URL — strip /jsonrpc path if present, and
     // fall back to public TronGrid for third-party providers that only serve JSON-RPC.
     // Extract custom headers before stripping path, as they may contain API keys.
-    const headers = parseCustomHeaders(tronUrl);
-    const parsed = new URL(tronUrl);
+    const { url: cleanTronUrl, headers } = stripCustomRpcHeaders(tronUrl);
+    const parsed = new URL(cleanTronUrl);
     if (parsed.pathname.endsWith('/jsonrpc')) {
       parsed.pathname = parsed.pathname.slice(0, -8);
     }
-    // Strip custom_rpc_header params from the base URL
-    parsed.searchParams.delete('custom_rpc_header');
     const baseUrl = parsed.toString();
     const tronWebUrl =
       /^https?:\/\/(localhost|127\.0\.0\.1|[^/]*trongrid)/.test(baseUrl)
@@ -195,14 +172,24 @@ export class TronTransactionBuilder extends TronWeb {
     jsonRpcUrl?: string,
     headers?: Record<string, string>,
   ) {
-    super({ fullHost: tronWebUrl, headers });
+    // Strip custom_rpc_header from the URL and merge with any provided headers
+    const { url: cleanTronWebUrl, headers: parsedHeaders } =
+      stripCustomRpcHeaders(tronWebUrl);
+    const mergedHeaders = { ...parsedHeaders, ...headers };
+    super({ fullHost: cleanTronWebUrl, headers: mergedHeaders });
 
     this.tronAddress = tronAddress;
     this.setAddress(this.tronAddress);
-    // Use provided JSON-RPC URL, or derive from TronWeb URL
-    const rpcUrl =
-      jsonRpcUrl ??
-      (tronWebUrl.endsWith('/jsonrpc') ? tronWebUrl : `${tronWebUrl}/jsonrpc`);
+    // Use provided JSON-RPC URL, or derive from TronWeb URL.
+    // Use URL API so /jsonrpc goes into the pathname, not after query params.
+    let rpcUrl = jsonRpcUrl;
+    if (!rpcUrl) {
+      const u = new URL(tronWebUrl);
+      if (!u.pathname.endsWith('/jsonrpc')) {
+        u.pathname = u.pathname.replace(/\/$/, '') + '/jsonrpc';
+      }
+      rpcUrl = u.toString();
+    }
     this.provider = new TronJsonRpcProvider(rpcUrl);
     this.tronAddressHex = this.address.toHex(this.tronAddress);
   }

typescript/tron-sdk/src/ethers/urlUtils.test.ts

@@ -0,0 +1,83 @@
+import { expect } from 'chai';
+
+import { parseCustomHeaders, stripCustomRpcHeaders } from './urlUtils.js';
+
+describe('parseCustomHeaders', () => {
+  it('extracts a single custom_rpc_header', () => {
+    const url =
+      'https://api.trongrid.io?custom_rpc_header=TRON-PRO-API-KEY:abc123';
+    expect(parseCustomHeaders(url)).to.deep.equal({
+      'TRON-PRO-API-KEY': 'abc123',
+    });
+  });
+
+  it('extracts multiple custom_rpc_header params', () => {
+    const url =
+      'https://host?custom_rpc_header=x-api-key:key1&custom_rpc_header=Authorization:Bearer%20token';
+    expect(parseCustomHeaders(url)).to.deep.equal({
+      'x-api-key': 'key1',
+      Authorization: 'Bearer token',
+    });
+  });
+
+  it('handles header values with colons', () => {
+    const url = 'https://host?custom_rpc_header=x-api-key:token:with:colons';
+    expect(parseCustomHeaders(url)).to.deep.equal({
+      'x-api-key': 'token:with:colons',
+    });
+  });
+
+  it('returns empty object for URL without custom_rpc_header', () => {
+    const url = 'https://api.trongrid.io/jsonrpc';
+    expect(parseCustomHeaders(url)).to.deep.equal({});
+  });
+
+  it('returns empty object for invalid URL', () => {
+    expect(parseCustomHeaders('not-a-url')).to.deep.equal({});
+  });
+
+  it('ignores malformed header values without colon', () => {
+    const url = 'https://host?custom_rpc_header=nocolon';
+    expect(parseCustomHeaders(url)).to.deep.equal({});
+  });
+});
+
+describe('stripCustomRpcHeaders', () => {
+  it('strips custom_rpc_header and returns clean URL with headers', () => {
+    const url =
+      'https://tron-mainnet.gateway.tatum.io/jsonrpc?custom_rpc_header=x-api-key:abc123';
+    const result = stripCustomRpcHeaders(url);
+    expect(result.url).to.equal(
+      'https://tron-mainnet.gateway.tatum.io/jsonrpc',
+    );
+    expect(result.headers).to.deep.equal({ 'x-api-key': 'abc123' });
+  });
+
+  it('preserves non-custom_rpc_header query params', () => {
+    const url = 'https://host/jsonrpc?custom_rpc_header=x-api-key:abc&other=1';
+    const result = stripCustomRpcHeaders(url);
+    expect(result.url).to.equal('https://host/jsonrpc?other=1');
+    expect(result.headers).to.deep.equal({ 'x-api-key': 'abc' });
+  });
+
+  it('returns original URL unchanged when no custom_rpc_header', () => {
+    const url = 'https://api.trongrid.io/jsonrpc';
+    const result = stripCustomRpcHeaders(url);
+    expect(result.url).to.equal(url);
+    expect(result.headers).to.deep.equal({});
+  });
+
+  it('returns original URL unchanged when xApiKey query param is used', () => {
+    const url = 'https://tron-mainnet.gateway.tatum.io/jsonrpc?xApiKey=abc123';
+    const result = stripCustomRpcHeaders(url);
+    expect(result.url).to.equal(url);
+    expect(result.headers).to.deep.equal({});
+  });
+
+  it('strips malformed custom_rpc_header without colon', () => {
+    const url = 'https://host/jsonrpc?custom_rpc_header=nocolon';
+    const result = stripCustomRpcHeaders(url);
+    expect(result.url).to.equal('https://host/jsonrpc');
+    expect(result.headers).to.deep.equal({});
+  });
+});

typescript/tron-sdk/src/ethers/urlUtils.ts

@@ -0,0 +1,48 @@
+/**
+ * Parse custom_rpc_header query params from a URL into a headers object.
+ * e.g. "https://api.trongrid.io?custom_rpc_header=TRON-PRO-API-KEY:abc"
+ * returns { "TRON-PRO-API-KEY": "abc" }
+ */
+export function parseCustomHeaders(url: string): Record<string, string> {
+  const headers: Record<string, string> = {};
+  try {
+    const parsed = new URL(url);
+    for (const [key, value] of parsed.searchParams) {
+      if (key !== 'custom_rpc_header') continue;
+      const colonIdx = value.indexOf(':');
+      if (colonIdx > 0) {
+        headers[value.slice(0, colonIdx)] = value.slice(colonIdx + 1);
+      }
+    }
+  } catch {
+    // Not a valid URL, return empty headers
+  }
+  return headers;
+}
+
+/**
+ * Strip custom_rpc_header query params from a URL and return the clean URL
+ * along with the extracted headers.
+ *
+ * e.g. "https://host/jsonrpc?custom_rpc_header=x-api-key:abc&other=1"
+ * returns { url: "https://host/jsonrpc?other=1", headers: { "x-api-key": "abc" } }
+ *
+ * If no custom_rpc_header params are present, returns the original URL unchanged.
+ */
+export function stripCustomRpcHeaders(url: string): {
+  url: string;
+  headers: Record<string, string>;
+} {
+  const headers = parseCustomHeaders(url);
+  let parsed: URL;
+  try {
+    parsed = new URL(url);
+  } catch {
+    return { url, headers };
+  }
+  if (!parsed.searchParams.has('custom_rpc_header')) {
+    return { url, headers };
+  }
+  parsed.searchParams.delete('custom_rpc_header');
+  return { url: parsed.toString(), headers };
+}