feat: add Tron payment detection support

- Add TronFeeProxyDetector for detecting Tron payments
- Add TronInfoRetriever for fetching payment data from TheGraph
- Add GraphQL queries for Tron payments
- Integrate Tron detector into payment network factory
- Add unit tests for detector and retriever

Author: rodrigopavezi

packages/payment-detection/codegen-tron.yml

@@ -0,0 +1,11 @@
+overwrite: true
+# Using local schema until the subgraph is deployed to The Graph Studio
+schema: '../substreams-tron/schema.graphql'
+documents: src/thegraph/queries/tron/*.graphql
+generates:
+  src/thegraph/generated/graphql-tron.ts:
+    plugins:
+      - 'typescript'
+      - 'typescript-operations'
+      - 'typescript-graphql-request'
+      - 'typescript-document-nodes'

packages/payment-detection/package.json

@@ -38,7 +38,7 @@
     "prepare": "yarn run build",
     "test": "jest --runInBand",
     "test:watch": "yarn test --watch",
-    "codegen": "graphql-codegen --config codegen.yml ; graphql-codegen --config codegen-superfluid.yml; graphql-codegen --config codegen-near.yml"
+    "codegen": "graphql-codegen --config codegen.yml ; graphql-codegen --config codegen-superfluid.yml; graphql-codegen --config codegen-near.yml; graphql-codegen --config codegen-tron.yml"
   },
   "dependencies": {
     "@requestnetwork/currency": "0.30.0",

packages/payment-detection/src/index.ts

@@ -16,6 +16,7 @@ import {
   getTheGraphClientUrl,
   getTheGraphEvmClient,
   getTheGraphNearClient,
+  getTheGraphTronClient,
 } from './thegraph';
 import {
   calculateEscrowState,
@@ -30,6 +31,7 @@ import {
   unpadAmountFromChainlink,
 } from './utils';
 import { NearConversionNativeTokenPaymentDetector, NearNativeTokenPaymentDetector } from './near';
+import { TronERC20FeeProxyPaymentDetector, TronInfoRetriever } from './tron';
 import { FeeReferenceBasedDetector } from './fee-reference-based-detector';
 import { SuperFluidPaymentDetector } from './erc777/superfluid-detector';
 import { EscrowERC20InfoRetriever } from './erc20/escrow-info-retriever';
@@ -55,6 +57,8 @@ export {
   SuperFluidPaymentDetector,
   NearNativeTokenPaymentDetector,
   NearConversionNativeTokenPaymentDetector,
+  TronERC20FeeProxyPaymentDetector,
+  TronInfoRetriever,
   EscrowERC20InfoRetriever,
   SuperFluidInfoRetriever,
   MetaDetector,
@@ -65,6 +69,7 @@ export {
   getTheGraphClientUrl,
   getTheGraphEvmClient,
   getTheGraphNearClient,
+  getTheGraphTronClient,
   parseLogArgs,
   padAmountForChainlink,
   unpadAmountFromChainlink,

packages/payment-detection/src/payment-network-factory.ts

@@ -24,6 +24,7 @@ import { SuperFluidPaymentDetector } from './erc777/superfluid-detector';
 import { EthFeeProxyPaymentDetector, EthInputDataPaymentDetector } from './eth';
 import { AnyToERC20PaymentDetector, AnyToEthFeeProxyPaymentDetector } from './any';
 import { NearConversionNativeTokenPaymentDetector, NearNativeTokenPaymentDetector } from './near';
+import { TronERC20FeeProxyPaymentDetector } from './tron';
 import { getPaymentNetworkExtension } from './utils';
 import { getTheGraphClient } from './thegraph';
 import { getDefaultProvider } from 'ethers';
@@ -55,6 +56,13 @@ const supportedPaymentNetwork: ISupportedPaymentNetworkByCurrency = {
     'near-testnet': {
       [PN_ID.ERC20_FEE_PROXY_CONTRACT]: ERC20FeeProxyPaymentDetector<CurrencyTypes.NearChainName>,
     },
+    // TRON chains
+    tron: {
+      [PN_ID.ERC20_FEE_PROXY_CONTRACT]: TronERC20FeeProxyPaymentDetector,
+    },
+    nile: {
+      [PN_ID.ERC20_FEE_PROXY_CONTRACT]: TronERC20FeeProxyPaymentDetector,
+    },
 
     '*': {
       [PN_ID.ERC20_ADDRESS_BASED]: ERC20AddressBasedPaymentDetector,

packages/payment-detection/src/thegraph/client.ts

@@ -1,9 +1,10 @@
 /* eslint-disable @typescript-eslint/explicit-module-boundary-types */
 import { CurrencyTypes } from '@requestnetwork/types';
-import { NearChains } from '@requestnetwork/currency';
+import { NearChains, TronChains } from '@requestnetwork/currency';
 import { GraphQLClient } from 'graphql-request';
 import { Block_Height, getSdk, Maybe } from './generated/graphql';
 import { getSdk as getNearSdk } from './generated/graphql-near';
+import { getSdk as getTronSdk } from './generated/graphql-tron';
 
 const THE_GRAPH_STUDIO_URL =
   'https://api.studio.thegraph.com/query/67444/request-payments-$NETWORK/version/latest';
@@ -20,6 +21,13 @@ const THE_GRAPH_URL_MANTLE =
 const THE_GRAPH_URL_CORE =
   'https://thegraph.coredao.org/subgraphs/name/requestnetwork/request-payments-core';
 
+// TRON Substreams-powered subgraph URLs
+const THE_GRAPH_URL_TRON =
+  'https://api.studio.thegraph.com/query/67444/request-payments-tron/version/latest';
+
+const THE_GRAPH_URL_TRON_NILE =
+  'https://api.studio.thegraph.com/query/67444/request-payments-tron-nile/version/latest';
+
 const THE_GRAPH_EXPLORER_SUBGRAPH_ID: Partial<Record<CurrencyTypes.ChainName, string>> = {
   ['arbitrum-one']: '3MtDdHbzvBVNBpzUTYXGuDDLgTd1b8bPYwoH1Hdssgp9',
   avalanche: 'A27V4PeZdKHeyuBkehdBJN8cxNtzVpXvYoqkjHUHRCFp',
@@ -47,11 +55,13 @@ const THE_GRAPH_EXPLORER_SUBGRAPH_ID: Partial<Record<CurrencyTypes.ChainName, st
 /**
  * A GraphQL client to query Request's subgraph.
  *
- * @type TGraphClientVariant: null if no variant, 'near' if native token payments detection on Near
+ * @type TGraphClientVariant: null if no variant, 'near' if native token payments detection on Near, 'tron' for TRON
  */
 export type TheGraphClient<TChain extends CurrencyTypes.VMChainName = CurrencyTypes.EvmChainName> =
   (TChain extends CurrencyTypes.NearChainName
     ? ReturnType<typeof getNearSdk>
+    : TChain extends CurrencyTypes.TronChainName
+    ? ReturnType<typeof getTronSdk>
     : ReturnType<typeof getSdk>) & {
     options?: TheGraphQueryOptions;
   };
@@ -104,6 +114,9 @@ export const getTheGraphClient = (
 ) => {
   const url = getTheGraphClientUrl(network, options);
   if (!url) return;
+  if (TronChains.isChainSupported(network)) {
+    return getTheGraphTronClient(url, options);
+  }
   return NearChains.isChainSupported(network)
     ? getTheGraphNearClient(url, options)
     : getTheGraphEvmClient(url, options);
@@ -127,6 +140,15 @@ export const getTheGraphNearClient = (url: string, options?: TheGraphClientOptio
   return sdk;
 };
 
+export const getTheGraphTronClient = (url: string, options?: TheGraphClientOptions) => {
+  const [clientOptions, queryOptions] = extractClientOptions(url, options);
+  const sdk: TheGraphClient<CurrencyTypes.TronChainName> = getTronSdk(
+    new GraphQLClient(url, clientOptions),
+  );
+  sdk.options = queryOptions;
+  return sdk;
+};
+
 export const getTheGraphClientUrl = (
   network: CurrencyTypes.ChainName,
   options?: TheGraphClientOptions,
@@ -155,6 +177,10 @@ export const getTheGraphClientUrl = (
       return THE_GRAPH_URL_MANTLE_TESTNET;
     case chain === 'core':
       return THE_GRAPH_URL_CORE;
+    case chain === 'tron':
+      return THE_GRAPH_URL_TRON;
+    case chain === 'nile':
+      return THE_GRAPH_URL_TRON_NILE;
     default:
       return shouldUseTheGraphExplorer ? theGraphExplorerUrl : theGraphStudioUrl;
   }

packages/payment-detection/src/thegraph/queries/tron/GetTronPayments.graphql

@@ -0,0 +1,45 @@
+# Getting TRC20 payments from the ERC20FeeProxy contract on TRON
+query GetTronPayments(
+  $reference: Bytes!
+  $to: String!
+  $tokenAddress: String!
+  $contractAddress: String!
+) {
+  payments(
+    where: {
+      reference: $reference
+      to: $to
+      tokenAddress: $tokenAddress
+      contractAddress: $contractAddress
+    }
+    orderBy: timestamp
+    orderDirection: asc
+  ) {
+    amount
+    block
+    txHash
+    feeAmount
+    feeAddress
+    from
+    timestamp
+    tokenAddress
+  }
+}
+
+# Getting TRC20 payments without token address filter (for any token)
+query GetTronPaymentsAnyToken($reference: Bytes!, $to: String!, $contractAddress: String!) {
+  payments(
+    where: { reference: $reference, to: $to, contractAddress: $contractAddress }
+    orderBy: timestamp
+    orderDirection: asc
+  ) {
+    amount
+    block
+    txHash
+    feeAmount
+    feeAddress
+    from
+    timestamp
+    tokenAddress
+  }
+}

packages/payment-detection/src/thegraph/queries/tron/graphql.config.yml

@@ -0,0 +1,2 @@
+# Using local schema until the subgraph is deployed to The Graph Studio
+schema: ../../../../../substreams-tron/schema.graphql

packages/payment-detection/src/tron/index.ts

@@ -0,0 +1,3 @@
+export { TronERC20FeeProxyPaymentDetector } from './tron-fee-proxy-detector';
+export { TronInfoRetriever } from './tron-info-retriever';
+export type { TronPaymentEvent } from './tron-info-retriever';

packages/payment-detection/src/tron/tron-fee-proxy-detector.ts

@@ -0,0 +1,119 @@
+import { erc20FeeProxyArtifact } from '@requestnetwork/smart-contracts';
+import {
+  CurrencyTypes,
+  ExtensionTypes,
+  PaymentTypes,
+  RequestLogicTypes,
+} from '@requestnetwork/types';
+import { TronChains, isSameChain } from '@requestnetwork/currency';
+
+import { ERC20FeeProxyPaymentDetectorBase } from '../erc20/fee-proxy-contract';
+import { NetworkNotSupported } from '../balance-error';
+import { ReferenceBasedDetectorOptions, TGetSubGraphClient } from '../types';
+import { TronInfoRetriever, TronPaymentEvent } from './tron-info-retriever';
+import { TheGraphClient } from '../thegraph';
+
+/**
+ * Handle payment networks with ERC20 fee proxy contract extension on TRON chains
+ */
+export class TronERC20FeeProxyPaymentDetector extends ERC20FeeProxyPaymentDetectorBase<
+  ExtensionTypes.PnFeeReferenceBased.IFeeReferenceBased,
+  TronPaymentEvent
+> {
+  private readonly getSubgraphClient: TGetSubGraphClient<CurrencyTypes.TronChainName>;
+  protected readonly network: CurrencyTypes.TronChainName | undefined;
+
+  constructor({
+    advancedLogic,
+    currencyManager,
+    getSubgraphClient,
+    network,
+  }: ReferenceBasedDetectorOptions & {
+    network?: CurrencyTypes.TronChainName;
+    getSubgraphClient: TGetSubGraphClient<CurrencyTypes.TronChainName>;
+  }) {
+    super(
+      ExtensionTypes.PAYMENT_NETWORK_ID.ERC20_FEE_PROXY_CONTRACT,
+      advancedLogic.getFeeProxyContractErc20ForNetwork(network) ??
+        advancedLogic.extensions.feeProxyContractErc20,
+      currencyManager,
+    );
+    this.getSubgraphClient = getSubgraphClient;
+    this.network = network;
+  }
+
+  /**
+   * Gets the deployment information for the ERC20FeeProxy contract on TRON
+   */
+  public static getDeploymentInformation(
+    network: CurrencyTypes.TronChainName,
+    _paymentNetworkVersion?: string,
+  ): { address: string; creationBlockNumber: number } {
+    void _paymentNetworkVersion; // Parameter kept for API compatibility
+    // For TRON, we use the 'tron' version of the artifact
+    const address = erc20FeeProxyArtifact.getAddress(network, 'tron');
+    const creationBlockNumber =
+      network === 'tron'
+        ? 79216121 // TRON mainnet
+        : 63208782; // Nile testnet
+
+    return { address, creationBlockNumber };
+  }
+
+  /**
+   * Extracts the payment events of a request on TRON
+   */
+  protected async extractEvents(
+    eventName: PaymentTypes.EVENTS_NAMES,
+    toAddress: string | undefined,
+    paymentReference: string,
+    requestCurrency: RequestLogicTypes.ICurrency,
+    paymentChain: CurrencyTypes.TronChainName,
+    _paymentNetwork: ExtensionTypes.IState,
+  ): Promise<PaymentTypes.AllNetworkEvents<TronPaymentEvent>> {
+    void _paymentNetwork; // Parameter required by parent class signature
+    // Validate that the payment chain is a supported TRON chain
+    if (!TronChains.isChainSupported(paymentChain)) {
+      throw new NetworkNotSupported(
+        `Unsupported TRON network '${paymentChain}' for TRON payment detector`,
+      );
+    }
+
+    if (this.network && !isSameChain(paymentChain, this.network)) {
+      throw new NetworkNotSupported(
+        `Unsupported network '${paymentChain}' for payment detector instantiated with '${this.network}'`,
+      );
+    }
+
+    if (!toAddress) {
+      return {
+        paymentEvents: [],
+      };
+    }
+
+    const { address: proxyContractAddress } =
+      TronERC20FeeProxyPaymentDetector.getDeploymentInformation(paymentChain);
+
+    const subgraphClient = this.getSubgraphClient(
+      paymentChain,
+    ) as TheGraphClient<CurrencyTypes.TronChainName>;
+
+    if (!subgraphClient) {
+      throw new Error(
+        `Could not get a TheGraph-based info retriever for TRON chain ${paymentChain}. ` +
+          `Ensure the TRON Substreams-powered subgraph is deployed and accessible.`,
+      );
+    }
+
+    const infoRetriever = new TronInfoRetriever(subgraphClient);
+
+    return infoRetriever.getTransferEvents({
+      eventName,
+      paymentReference,
+      toAddress,
+      contractAddress: proxyContractAddress,
+      paymentChain,
+      acceptedTokens: [requestCurrency.value],
+    });
+  }
+}