feat: add Tron payment detection retrievers and advanced logic support (#1691)

## Description of the changes

Added a new Substreams module for indexing ERC20FeeProxy payment events on the TRON blockchain. This module:

- Tracks `TransferWithReferenceAndFee` events from deployed ERC20FeeProxy contracts on TRON mainnet and Nile testnet
- Extracts payment details including token address, amount, recipient, payment reference, fee information, and transaction metadata
- Provides a Rust implementation with WASM compilation for Substreams
- Includes configuration for deployment as a Substreams-powered subgraph
- Contains Makefile, build scripts, and package configuration for easy development and deployment
- Implements Base58 encoding for TRON addresses
- Supports both mainnet (`TCUDPYnS9dH3WvFEaE7wN7vnDa51J4R4fd`) and Nile testnet (`THK5rNmrvCujhmrXa5DB1dASepwXTr9cJs`) contract addresses

---
Closes RequestNetwork/private-issues#226

Author: rodrigopavezi

packages/advanced-logic/src/advanced-logic.ts

@@ -173,9 +173,16 @@ export default class AdvancedLogic implements AdvancedLogicTypes.IAdvancedLogic
   }
 
   public getFeeProxyContractErc20ForNetwork(network?: string): FeeProxyContractErc20 {
-    return NearChains.isChainSupported(network)
-      ? new FeeProxyContractErc20(this.currencyManager, undefined, undefined, network)
-      : this.extensions.feeProxyContractErc20;
+    if (NearChains.isChainSupported(network) || this.isTronNetwork(network)) {
+      return new FeeProxyContractErc20(this.currencyManager, undefined, undefined, network);
+    }
+    return this.extensions.feeProxyContractErc20;
+  }
+
+  private isTronNetwork(network?: string): boolean {
+    if (!network) return false;
+    const normalized = network.toLowerCase();
+    return normalized === 'tron' || normalized === 'nile';
   }
 
   protected getNetwork(

packages/advanced-logic/src/extensions/payment-network/address-based.ts

@@ -158,6 +158,14 @@ export default abstract class AddressBasedPaymentNetwork<
     }
   }
 
+  /**
+   * Check if an address is a valid TRON Base58 address (starts with 'T', 34 chars).
+   * Use this in subclasses that override isValidAddress for TRON-specific networks.
+   */
+  public static isTronAddress(address: string): boolean {
+    return /^T[123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz]{33}$/.test(address);
+  }
+
   protected isValidAddressForSymbolAndNetwork(
     address: string,
     symbol: string,

packages/advanced-logic/src/extensions/payment-network/erc20/fee-proxy-contract.ts

@@ -1,6 +1,6 @@
 import { CurrencyTypes, ExtensionTypes, RequestLogicTypes } from '@requestnetwork/types';
 import { NearChains, isSameChain } from '@requestnetwork/currency';
-import { UnsupportedNetworkError } from '../address-based';
+import AddressBasedPaymentNetwork, { UnsupportedNetworkError } from '../address-based';
 import { FeeReferenceBasedPaymentNetwork } from '../fee-reference-based';
 
 const EVM_CURRENT_VERSION = '0.2.0';
@@ -57,8 +57,16 @@ export default class Erc20FeeProxyPaymentNetwork<
       } else {
         return this.isValidAddressForSymbolAndNetwork(address, 'NEAR', 'near');
       }
+    } else if (Erc20FeeProxyPaymentNetwork.isTronNetwork(this.network)) {
+      return AddressBasedPaymentNetwork.isTronAddress(address);
     } else {
       return super.isValidAddress(address);
     }
   }
+
+  private static isTronNetwork(network?: string): boolean {
+    if (!network) return false;
+    const normalized = network.toLowerCase();
+    return normalized === 'tron' || normalized === 'nile';
+  }
 }

packages/advanced-logic/test/extensions/payment-network/address-based.test.ts

@@ -49,4 +49,43 @@ describe('extensions/payment-network/address-based', () => {
       testAddressBasedPaymentNetwork.testIsValidAddress();
     }).toThrowError(new UnsupportedCurrencyError({ value: 'test', network: 'mainnet' }));
   });
+
+  it('base isValidAddress should reject TRON addresses for ERC20 currency type', () => {
+    class TestAddressBasedPaymentNetwork extends AddressBasedPaymentNetwork {
+      public constructor() {
+        super(
+          CurrencyManager.getDefault(),
+          ExtensionTypes.PAYMENT_NETWORK_ID.ERC20_ADDRESS_BASED,
+          'test',
+          RequestLogicTypes.CURRENCY.ERC20,
+        );
+      }
+      public testIsValidAddress(address: string) {
+        return this.isValidAddress(address);
+      }
+    }
+    const pn = new TestAddressBasedPaymentNetwork();
+    // A valid TRON Base58 address should NOT be accepted by the base class
+    // because the base class has no network context to know this is a TRON request
+    expect(pn.testIsValidAddress('TJCnKsPa7y5okkXvQAidZBzqx3QyQ6sxMW')).toBe(false);
+    // A valid Ethereum address should still be accepted
+    expect(pn.testIsValidAddress('0x0000000000000000000000000000000000000000')).toBe(true);
+  });
+
+  it('static isTronAddress should correctly validate TRON addresses', () => {
+    expect(AddressBasedPaymentNetwork.isTronAddress('TJCnKsPa7y5okkXvQAidZBzqx3QyQ6sxMW')).toBe(
+      true,
+    );
+    expect(AddressBasedPaymentNetwork.isTronAddress('T9yD14Nj9j7xAB4dbGeiX9h8unkKHxuWwb')).toBe(
+      true,
+    );
+    // Invalid: too short
+    expect(AddressBasedPaymentNetwork.isTronAddress('TJCnKsPa7y5okkXvQAid')).toBe(false);
+    // Invalid: doesn't start with T
+    expect(
+      AddressBasedPaymentNetwork.isTronAddress('0x0000000000000000000000000000000000000000'),
+    ).toBe(false);
+    // Invalid: empty
+    expect(AddressBasedPaymentNetwork.isTronAddress('')).toBe(false);
+  });
 });

packages/currency/src/chains/declarative/data/nile.ts

@@ -66,6 +66,99 @@ The code generation is included in the pre-build script and can be run manually:
 yarn codegen
 ```
 
+## TRON Payment Detection (Hasura-based)
+
+TRON payment detection uses a Hasura GraphQL API backed by a PostgreSQL database that is populated by a Substreams-based indexer. This approach was chosen because The Graph does not support subgraphs for native TRON (only TRON EVM).
+
+### Architecture
+
+```
+TRON Blockchain → Substreams → PostgreSQL → Hasura GraphQL → SDK
+```
+
+The payment data flows through:
+
+1. **Substreams**: Indexes ERC20FeeProxy payment events from the TRON blockchain
+2. **PostgreSQL**: Stores payment data via `substreams-sink-sql`
+3. **Hasura**: Exposes the PostgreSQL data as a GraphQL API
+4. **SDK**: Queries Hasura via `TronInfoRetriever` and `HasuraClient`
+
+### Components
+
+- **`TronFeeProxyPaymentDetector`**: Payment detector for TRON ERC20 Fee Proxy payments
+- **`TronInfoRetriever`**: Retrieves payment events from Hasura, implements `ITheGraphBaseInfoRetriever`
+- **`HasuraClient`**: GraphQL client for querying the Hasura endpoint
+
+### Usage
+
+The `TronFeeProxyPaymentDetector` is automatically registered in the `PaymentNetworkFactory` for TRON networks (`tron` and `nile`).
+
+```typescript
+import { PaymentNetworkFactory } from '@requestnetwork/payment-detection';
+
+// The factory automatically uses TronFeeProxyPaymentDetector for TRON
+const paymentNetwork = PaymentNetworkFactory.getPaymentNetworkFromRequest({
+  request,
+  advancedLogic,
+});
+
+const balance = await paymentNetwork.getBalance(request);
+```
+
+### Custom Hasura Endpoint
+
+By default, the `HasuraClient` connects to the production Hasura endpoint. To use a custom endpoint:
+
+```typescript
+import {
+  HasuraClient,
+  TronInfoRetriever,
+  TronFeeProxyPaymentDetector,
+} from '@requestnetwork/payment-detection';
+
+// Create a custom Hasura client
+const customClient = new HasuraClient({
+  baseUrl: 'https://your-hasura-instance.com/v1/graphql',
+});
+
+// Use it with TronInfoRetriever
+const retriever = new TronInfoRetriever(customClient);
+
+// Or use getHasuraClient with custom options
+import { getHasuraClient } from '@requestnetwork/payment-detection';
+
+const client = getHasuraClient('tron', {
+  baseUrl: 'https://your-hasura-instance.com/v1/graphql',
+});
+```
+
+### TRON-specific Event Fields
+
+TRON payment events include additional fields specific to the TRON blockchain:
+
+```typescript
+interface TronPaymentEvent {
+  txHash: string;
+  feeAmount: string;
+  block: number;
+  to: string;
+  from: string;
+  feeAddress?: string;
+  tokenAddress?: string;
+  // TRON-specific resource consumption
+  energyUsed?: string; // Total energy consumed
+  energyFee?: string; // Energy fee in SUN
+  netFee?: string; // Network/bandwidth fee in SUN
+}
+```
+
+### Supported Networks
+
+| Network | Chain Identifier | Description       |
+| ------- | ---------------- | ----------------- |
+| `tron`  | `tron`           | TRON Mainnet      |
+| `nile`  | `tron-nile`      | TRON Nile Testnet |
+
 # Test
 
 ```sh

packages/currency/src/chains/declarative/data/tron.ts

@@ -1,5 +1,5 @@
 overwrite: true
-schema: 'https://api.studio.thegraph.com/query/67444/request-payments-sepolia/version/latest'
+schema: 'https://api.studio.thegraph.com/query/67444/request-payments-base/version/latest'
 documents: src/thegraph/queries/*.graphql
 generates:
   src/thegraph/generated/graphql.ts:

packages/payment-detection/README.md

@@ -14,7 +14,7 @@ import { makeGetDeploymentInformation } from '../utils';
 import { TheGraphClient, TheGraphInfoRetriever } from '../thegraph';
 import { ReferenceBasedDetectorOptions, TGetSubGraphClient } from '../types';
 import { NearInfoRetriever } from '../near';
-import { TronInfoRetriever } from '../tron/tron-info-retriever';
+import { TronTheGraphInfoRetriever } from '../tron/retrievers/tron-thegraph-info-retriever';
 import { NetworkNotSupported } from '../balance-error';
 
 const PROXY_CONTRACT_ADDRESS_MAP = {
@@ -166,13 +166,13 @@ export class ERC20FeeProxyPaymentDetector<
       | TheGraphClient
       | TheGraphClient<CurrencyTypes.NearChainName>
       | TheGraphClient<CurrencyTypes.TronChainName>,
-  ): TheGraphInfoRetriever | NearInfoRetriever | TronInfoRetriever {
+  ): TheGraphInfoRetriever | NearInfoRetriever | TronTheGraphInfoRetriever {
     const graphInfoRetriever = EvmChains.isChainSupported(paymentChain)
       ? new TheGraphInfoRetriever(subgraphClient as TheGraphClient, this.currencyManager)
       : NearChains.isChainSupported(paymentChain) && this.network
       ? new NearInfoRetriever(subgraphClient as TheGraphClient<CurrencyTypes.NearChainName>)
       : TronChains.isChainSupported(paymentChain)
-      ? new TronInfoRetriever(subgraphClient as TheGraphClient<CurrencyTypes.TronChainName>)
+      ? new TronTheGraphInfoRetriever(subgraphClient as TheGraphClient<CurrencyTypes.TronChainName>)
       : undefined;
     if (!graphInfoRetriever) {
       throw new Error(

packages/payment-detection/codegen.yml

@@ -31,7 +31,13 @@ import {
   unpadAmountFromChainlink,
 } from './utils';
 import { NearConversionNativeTokenPaymentDetector, NearNativeTokenPaymentDetector } from './near';
-import { TronERC20FeeProxyPaymentDetector, TronInfoRetriever } from './tron';
+import {
+  TronFeeProxyPaymentDetector,
+  getHasuraClient,
+  HasuraClient,
+  TronInfoRetriever,
+} from './tron';
+export type { TronPaymentEvent } from './tron/retrievers/tron-info-retriever';
 import { FeeReferenceBasedDetector } from './fee-reference-based-detector';
 import { SuperFluidPaymentDetector } from './erc777/superfluid-detector';
 import { EscrowERC20InfoRetriever } from './erc20/escrow-info-retriever';
@@ -57,8 +63,11 @@ export {
   SuperFluidPaymentDetector,
   NearNativeTokenPaymentDetector,
   NearConversionNativeTokenPaymentDetector,
-  TronERC20FeeProxyPaymentDetector,
+  // TRON
+  TronFeeProxyPaymentDetector,
   TronInfoRetriever,
+  getHasuraClient,
+  HasuraClient,
   EscrowERC20InfoRetriever,
   SuperFluidInfoRetriever,
   MetaDetector,