@across-protocol/sdk 4.3.138 → 4.3.139-alpha.2

package/src/arch/tvm/SpokeUtils.ts

@@ -0,0 +1,225 @@
+import assert from "assert";
+import { Contract, providers } from "ethers";
+import { CHAIN_IDs } from "../../constants";
+import { FillStatus, FillWithBlock, RelayData } from "../../interfaces";
+import { get1967Upgrades } from "../evm/UpgradeUtils";
+import { relayFillStatus as evmRelayFillStatus } from "../evm/SpokeUtils";
+import {
+  BigNumber,
+  getRelayDataHash,
+  isDefined,
+  isUnsafeDepositId,
+  paginatedEventQuery,
+  spreadEventWithBlockNumber,
+  unpackFillEvent,
+} from "../../utils";
+
+type BlockTag = providers.BlockTag;
+
+// Re-export functions that work unchanged on TRON's JSON-RPC.
+export { populateV3Relay, getTimestampForBlock, fillStatusArray } from "../evm/SpokeUtils";
+
+// Local implementations for functions requiring historical eth_call,
+// which TRON does not support (only "latest" blockTag is accepted).
+
+/**
+ * @notice Retrieve the on-chain time at a specific block number.
+ * TRON does not support historical eth_call so block timestamps are used
+ * instead of SpokePool.getCurrentTime(). In production these are equivalent.
+ */
+export async function getTimeAt(spokePool: Contract, blockNumber: number): Promise<number> {
+  const block = await spokePool.provider.getBlock(blockNumber);
+  return block.timestamp;
+}
+
+// Fallback fill deadline buffer (6 hours) used when a contract upgrade is
+// detected in the query range. An upgrade implies fillDeadlineBuffer may
+// have changed and we cannot read historical state on TRON, so we use a
+// conservative upper bound.
+const FALLBACK_FILL_DEADLINE_BUFFER = 21600; // 6 hours in seconds
+
+/**
+ * @notice Return the maximum fill deadline buffer across a block range.
+ * TRON does not support historical eth_call, so we read the current value.
+ * If a contract upgrade (EIP-1967 Upgraded event) occurred within the range,
+ * the value may have changed at the upgrade boundary. In that case, return
+ * the greater of the current value and a conservative 6-hour fallback.
+ */
+export async function getMaxFillDeadlineInRange(
+  spokePool: Contract,
+  startBlock: number,
+  endBlock: number
+): Promise<number> {
+  const [fillDeadlineBuffer, upgrades] = await Promise.all([
+    spokePool.fillDeadlineBuffer(),
+    get1967Upgrades(spokePool, startBlock, endBlock),
+  ]);
+
+  const currentBuffer = Number(fillDeadlineBuffer);
+
+  if (upgrades.length > 0) {
+    return Math.max(currentBuffer, FALLBACK_FILL_DEADLINE_BUFFER);
+  }
+
+  return currentBuffer;
+}
+
+/**
+ * @notice Not supported on TVM — callers should use findDepositBlock instead.
+ */
+export function getDepositIdAtBlock(_contract: Contract, _blockTag: number): Promise<BigNumber> {
+  throw new Error("getDepositIdAtBlock: not supported on TVM");
+}
+
+/**
+ * @notice Find the block at which a deposit was created.
+ * TRON does not support historical eth_call, so event queries replace the
+ * EVM binary-search over numberOfDeposits().
+ */
+export async function findDepositBlock(
+  spokePool: Contract,
+  depositId: BigNumber,
+  lowBlock: number,
+  highBlock?: number
+): Promise<number | undefined> {
+  if (isUnsafeDepositId(depositId)) {
+    throw new Error(`Cannot search for depositId ${depositId}`);
+  }
+
+  highBlock ??= await spokePool.provider.getBlockNumber();
+  assert(highBlock > lowBlock, `Block numbers out of range (${lowBlock} >= ${highBlock})`);
+
+  const events = await paginatedEventQuery(
+    spokePool,
+    spokePool.filters.FundsDeposited(null, null, null, null, null, depositId),
+    { from: lowBlock, to: highBlock }
+  );
+
+  if (events.length === 0) {
+    return undefined;
+  }
+
+  return events[0].blockNumber;
+}
+
+/**
+ * @notice Determine the fill status of a relay at a given block.
+ * For "latest" queries, delegates to the EVM implementation (TRON's
+ * eth_call works normally for "latest"). For historical queries the
+ * status is reconstructed from on-chain events because TRON does not
+ * support eth_call with historical blockTags.
+ */
+export async function relayFillStatus(
+  spokePool: Contract,
+  relayData: RelayData,
+  blockTag: BlockTag = "latest",
+  destinationChainId?: number
+): Promise<FillStatus> {
+  if (blockTag === "latest") {
+    return evmRelayFillStatus(spokePool, relayData, blockTag, destinationChainId);
+  }
+
+  destinationChainId ??= await spokePool.chainId();
+  assert(isDefined(destinationChainId));
+
+  const hash = getRelayDataHash(relayData, destinationChainId);
+
+  // Historical blockTag: check the current state first as an optimisation.
+  // Fill status can only increase (Unfilled -> RequestedSlowFill -> Filled),
+  // so if the deposit is still Unfilled now it was Unfilled at every prior block.
+  const latestStatus = Number(await spokePool.fillStatuses(hash));
+  if (latestStatus === FillStatus.Unfilled) {
+    return FillStatus.Unfilled;
+  }
+
+  // Reconstruct from events up to the requested block.
+  const fromBlock = 0;
+  const toBlock = Number(blockTag);
+
+  const fillEvents = await paginatedEventQuery(
+    spokePool,
+    spokePool.filters.FilledRelay(null, null, null, null, null, relayData.originChainId, relayData.depositId),
+    { from: fromBlock, to: toBlock }
+  );
+
+  if (fillEvents.length > 0) {
+    return FillStatus.Filled;
+  }
+
+  // No fill before blockTag — check for slow fill requests.
+  if (latestStatus >= FillStatus.RequestedSlowFill) {
+    const slowFillEvents = await paginatedEventQuery(
+      spokePool,
+      spokePool.filters.RequestedSlowFill(null, null, null, null, relayData.originChainId, relayData.depositId),
+      { from: fromBlock, to: toBlock }
+    );
+
+    if (slowFillEvents.length > 0) {
+      return FillStatus.RequestedSlowFill;
+    }
+  }
+
+  return FillStatus.Unfilled;
+}
+
+/**
+ * @notice Find the block at which a fill was completed.
+ * TRON does not support historical eth_call, so event queries replace the
+ * EVM binary-search over fillStatuses().
+ */
+export async function findFillBlock(
+  spokePool: Contract,
+  relayData: RelayData,
+  lowBlockNumber: number,
+  highBlockNumber?: number
+): Promise<number | undefined> {
+  const { provider } = spokePool;
+  highBlockNumber ??= await provider.getBlockNumber();
+  assert(highBlockNumber > lowBlockNumber, `Block numbers out of range (${lowBlockNumber} >= ${highBlockNumber})`);
+
+  const events = await paginatedEventQuery(
+    spokePool,
+    spokePool.filters.FilledRelay(null, null, null, null, null, relayData.originChainId, relayData.depositId),
+    { from: lowBlockNumber, to: highBlockNumber }
+  );
+
+  if (events.length === 0) {
+    return undefined;
+  }
+
+  return events[0].blockNumber;
+}
+
+/**
+ * @notice Find the fill event for a deposit.
+ * Queries fill events directly rather than binary-searching then re-querying.
+ */
+export async function findFillEvent(
+  spokePool: Contract,
+  relayData: RelayData,
+  lowBlockNumber: number,
+  highBlockNumber?: number
+): Promise<FillWithBlock | undefined> {
+  const { provider } = spokePool;
+  highBlockNumber ??= await provider.getBlockNumber();
+
+  const events = await paginatedEventQuery(
+    spokePool,
+    spokePool.filters.FilledRelay(null, null, null, null, null, relayData.originChainId, relayData.depositId),
+    { from: lowBlockNumber, to: highBlockNumber }
+  );
+
+  if (events.length === 0) {
+    return undefined;
+  }
+
+  const event = events[0];
+  // In production the chainId returned from the provider matches 1:1 with the actual chainId. Querying the provider
+  // object saves an RPC query because the chainId is cached by StaticJsonRpcProvider instances. In hre, the SpokePool
+  // may be configured with a different chainId than what is returned by the provider.
+  const destinationChainId = Object.values(CHAIN_IDs).includes(relayData.originChainId)
+    ? (await spokePool.provider.getNetwork()).chainId
+    : Number(await spokePool.chainId());
+
+  return unpackFillEvent(spreadEventWithBlockNumber(event), destinationChainId);
+}

package/src/arch/tvm/TransactionUtils.ts

@@ -0,0 +1,64 @@
+import { TronWeb } from "tronweb";
+import { PopulatedTransaction } from "ethers";
+import { evmToTronAddress } from "./utils/address";
+
+export interface TronTransactionResult {
+  txid: string;
+  result: boolean;
+}
+
+/**
+ * Submit a populated EVM transaction to TRON via TronWeb.
+ *
+ * The EVM `populateV3Relay()` already produces correct ABI-encoded calldata.
+ * This function extracts `to` and `data` from the PopulatedTransaction,
+ * converts the target address to TRON Base58 format, and uses TronWeb's
+ * `triggerSmartContract` → `sign` → `sendRawTransaction` pipeline.
+ *
+ * @param tronWeb An authenticated TronWeb instance (with private key set).
+ * @param populatedTx The populated transaction containing `to` and `data`.
+ * @param feeLimit The maximum TRX to burn for energy consumption, in SUN (1 TRX = 1,000,000 SUN).
+ * @returns The transaction ID and result status.
+ */
+export async function submitTransaction(
+  tronWeb: TronWeb,
+  populatedTx: PopulatedTransaction,
+  feeLimit: number,
+  callValue: number = 0
+): Promise<TronTransactionResult> {
+  const { to, data } = populatedTx;
+  if (!to || !data) {
+    throw new Error("submitTransaction: populatedTx must have both 'to' and 'data' fields");
+  }
+
+  const tronAddress = evmToTronAddress(to);
+  const ownerAddress = tronWeb.defaultAddress?.base58;
+  if (!ownerAddress) {
+    throw new Error("submitTransaction: TronWeb instance must have a default address configured");
+  }
+
+  // Use triggerSmartContract with the `input` option to pass pre-encoded calldata.
+  // The function selector is empty — the full calldata (selector + params) is in `input`.
+  const input = data.startsWith("0x") ? data.slice(2) : data;
+  const txWrapper = await tronWeb.transactionBuilder.triggerSmartContract(
+    tronAddress,
+    // Use empty function selector — the `input` option provides the full calldata.
+    "",
+    { feeLimit, input, callValue },
+    [],
+    ownerAddress
+  );
+
+  if (!txWrapper?.result?.result) {
+    const message = txWrapper?.result?.message ?? "Unknown error";
+    throw new Error(`submitTransaction: triggerSmartContract failed: ${message}`);
+  }
+
+  const signedTx = await tronWeb.trx.sign(txWrapper.transaction);
+  const broadcast = await tronWeb.trx.sendRawTransaction(signedTx);
+
+  return {
+    txid: broadcast.txid ?? signedTx.txID,
+    result: broadcast.result ?? false,
+  };
+}

package/src/arch/tvm/index.ts

@@ -0,0 +1,6 @@
+export * from "./SpokeUtils";
+export * from "./BlockUtils";
+export * from "./TransactionUtils";
+export * from "./ResourceUtils";
+export * from "./utils";
+export * from "./MessageUtils";

package/src/arch/tvm/types.ts

@@ -0,0 +1,2 @@
+export { Provider } from "../evm/types";
+export type { TronWeb } from "tronweb";

package/src/arch/tvm/utils/address.ts

@@ -0,0 +1,33 @@
+import { TronWeb } from "tronweb";
+
+/**
+ * Convert an EVM-format hex address (0x...) to a TRON Base58Check address (T...).
+ * @param evmAddress The 0x-prefixed hex address.
+ * @returns The TRON Base58Check-encoded address.
+ */
+export function evmToTronAddress(evmAddress: string): string {
+  // TronWeb.address.fromHex expects a hex address (with or without 0x prefix)
+  // and returns the Base58Check-encoded TRON address.
+  return TronWeb.address.fromHex(evmAddress);
+}
+
+/**
+ * Convert a TRON Base58Check address (T...) to an EVM-format hex address (0x...).
+ * @param tronAddress The TRON Base58Check-encoded address.
+ * @returns The 0x-prefixed hex address.
+ */
+export function tronToEvmAddress(tronAddress: string): string {
+  // TronWeb.address.toHex returns hex with a 41 prefix (TRON's address prefix).
+  // We strip the leading "41" and add "0x" to get standard EVM format.
+  const hex = TronWeb.address.toHex(tronAddress);
+  return "0x" + hex.slice(2);
+}
+
+/**
+ * Check whether a string is a valid TRON Base58Check address.
+ * @param address The string to check.
+ * @returns True if the address is a valid TRON Base58Check address.
+ */
+export function isTronBase58Address(address: string): boolean {
+  return TronWeb.isAddress(address);
+}

package/src/arch/tvm/utils/index.ts

@@ -0,0 +1,2 @@
+export * from "./address";
+export * from "./wait";

package/src/arch/tvm/utils/wait.ts

@@ -0,0 +1 @@
+export * from "../../evm/utils/wait";

package/src/caching/index.ts

@@ -1,3 +1,2 @@
-export * from "./IPFS";
 export * from "./Arweave";
 export * from "./Memory";

package/src/clients/SpokePoolClient/EVMSpokePoolClient.ts

@@ -72,6 +72,34 @@ export class EVMSpokePoolClient extends SpokePoolClient {
     return Object.keys(this._availableEventsOnSpoke(knownEventNames));
   }
 
+  /**
+   * Retrieve the on-chain time at a specific block.
+   * EVM reads SpokePool.getCurrentTime() via multicall with a historical blockTag.
+   * @param blockNumber The block number to query.
+   * @returns The on-chain time as a number.
+   */
+  protected async _getCurrentTime(blockNumber: number): Promise<number> {
+    const { spokePool } = this;
+    const multicallFunctions = ["getCurrentTime"];
+    const multicallOutput = await spokePool.callStatic.multicall(
+      multicallFunctions.map((f) => spokePool.interface.encodeFunctionData(f)),
+      { blockTag: blockNumber }
+    );
+
+    const [currentTime] = multicallFunctions.map(
+      (fn, idx) => spokePool.interface.decodeFunctionResult(fn, multicallOutput[idx])[0]
+    );
+
+    if (!BigNumber.isBigNumber(currentTime) || currentTime.lt(this.currentTime)) {
+      const errMsg = BigNumber.isBigNumber(currentTime)
+        ? `currentTime: ${currentTime} < ${toBN(this.currentTime)}`
+        : `currentTime is not a BigNumber: ${JSON.stringify(currentTime)}`;
+      throw new Error(`EVMSpokePoolClient::update: ${errMsg}`);
+    }
+
+    return currentTime.toNumber();
+  }
+
   protected override async _update(eventsToQuery: string[]): Promise<SpokePoolUpdate> {
     const searchConfig = await this.updateSearchConfig(this.spokePool.provider);
     if (isUpdateFailureReason(searchConfig)) {
@@ -107,25 +135,14 @@ export class EVMSpokePoolClient extends SpokePoolClient {
     });
 
     const timerStart = Date.now();
-    const multicallFunctions = ["getCurrentTime"];
-    const [multicallOutput, ...events] = await Promise.all([
-      spokePool.callStatic.multicall(
-        multicallFunctions.map((f) => spokePool.interface.encodeFunctionData(f)),
-        { blockTag: searchConfig.to }
-      ),
+    const [currentTime, ...events] = await Promise.all([
+      this._getCurrentTime(searchConfig.to),
       ...eventSearchConfigs.map((config) => paginatedEventQuery(this.spokePool, config.filter, config.searchConfig)),
     ]);
     this.log("debug", `Time to query new events from RPC for ${this.chainId}: ${Date.now() - timerStart} ms`);
 
-    const [currentTime] = multicallFunctions.map(
-      (fn, idx) => spokePool.interface.decodeFunctionResult(fn, multicallOutput[idx])[0]
-    );
-
-    if (!BigNumber.isBigNumber(currentTime) || currentTime.lt(this.currentTime)) {
-      const errMsg = BigNumber.isBigNumber(currentTime)
-        ? `currentTime: ${currentTime} < ${toBN(this.currentTime)}`
-        : `currentTime is not a BigNumber: ${JSON.stringify(currentTime)}`;
-      throw new Error(`EVMSpokePoolClient::update: ${errMsg}`);
+    if (currentTime < this.currentTime) {
+      throw new Error(`EVMSpokePoolClient::update: currentTime: ${currentTime} < ${this.currentTime}`);
     }
 
     // Sort all events to ensure they are stored in a consistent order.
@@ -138,7 +155,7 @@ export class EVMSpokePoolClient extends SpokePoolClient {
 
     return {
       success: true,
-      currentTime: currentTime.toNumber(), // uint32
+      currentTime,
       searchEndBlock: searchConfig.to,
       events: eventsWithBlockNumber,
     };
@@ -190,12 +207,21 @@ export class EVMSpokePoolClient extends SpokePoolClient {
     return _getTimestampForBlock(this.spokePool.provider, blockNumber);
   }
 
-  private async queryDepositEvents(
+  /**
+   * Find the block at which a deposit was created.
+   * EVM uses a binary-search over historical numberOfDeposits().
+   * TVM overrides this with an event-based lookup.
+   */
+  protected _findDepositBlock(depositId: BigNumber, lowBlock: number, highBlock?: number): Promise<number | undefined> {
+    return findDepositBlock(this.spokePool, depositId, lowBlock, highBlock);
+  }
+
+  protected async queryDepositEvents(
     depositId: BigNumber
   ): Promise<{ event: Log; elapsedMs: number } | { reason: string }> {
     const tStart = Date.now();
     const upperBound = this.latestHeightSearched || undefined;
-    const from = await findDepositBlock(this.spokePool, depositId, this.deploymentBlock, upperBound);
+    const from = await this._findDepositBlock(depositId, this.deploymentBlock, upperBound);
     const chain = getNetworkName(this.chainId);
 
     if (!from) {

package/src/clients/SpokePoolClient/TVMSpokePoolClient.ts

@@ -0,0 +1,65 @@
+import {
+  findDepositBlock,
+  getMaxFillDeadlineInRange as getMaxFillDeadline,
+  getTimeAt as _getTimeAt,
+  relayFillStatus,
+} from "../../arch/tvm";
+import { FillStatus, RelayData } from "../../interfaces";
+import { BigNumber } from "../../utils";
+import { EVMSpokePoolClient } from "./EVMSpokePoolClient";
+import { TVM_SPOKE_POOL_CLIENT_TYPE } from "./types";
+
+/**
+ * A TVM-specific SpokePoolClient for TRON.
+ *
+ * TRON is EVM-compatible for reads and event queries, but diverges in three areas:
+ * 1. No historical `eth_call` — only "latest" blockTag is accepted.
+ * 2. No `eth_sendRawTransaction` — TRON uses Protobuf-encoded transactions via TronWeb.
+ * 3. Energy/bandwidth fee model instead of gas.
+ *
+ * This client extends EVMSpokePoolClient, overriding only the methods affected by (1).
+ * Transaction submission (2) and fee estimation (3) are handled by the arch/tvm utilities.
+ */
+export class TVMSpokePoolClient extends EVMSpokePoolClient {
+  // @ts-expect-error: Narrowing the base class literal type from "EVM" to "TVM".
+  override readonly type = TVM_SPOKE_POOL_CLIENT_TYPE;
+
+  public override relayFillStatus(relayData: RelayData, atHeight?: number): Promise<FillStatus> {
+    return relayFillStatus(this.spokePool, relayData, atHeight, this.chainId);
+  }
+
+  public override getMaxFillDeadlineInRange(startBlock: number, endBlock: number): Promise<number> {
+    return getMaxFillDeadline(this.spokePool, startBlock, endBlock);
+  }
+
+  public override getTimeAt(blockNumber: number): Promise<number> {
+    return _getTimeAt(this.spokePool, blockNumber);
+  }
+
+  /**
+   * Override to use TVM's event-based findDepositBlock
+   * instead of EVM's binary-search over historical numberOfDeposits().
+   */
+  protected override _findDepositBlock(
+    depositId: BigNumber,
+    lowBlock: number,
+    highBlock?: number
+  ): Promise<number | undefined> {
+    return findDepositBlock(this.spokePool, depositId, lowBlock, highBlock);
+  }
+
+  /**
+   * Override to avoid historical eth_call for getCurrentTime.
+   * TRON does not support eth_call with historical blockTags, so we
+   * use the block timestamp from provider.getBlock() instead of
+   * SpokePool.getCurrentTime({ blockTag }).
+   */
+  protected override async _getCurrentTime(blockNumber: number): Promise<number> {
+    const block = await this.spokePool.provider.getBlock(blockNumber);
+    const currentTime = block.timestamp;
+    if (currentTime < this.currentTime) {
+      throw new Error(`TVMSpokePoolClient::update: currentTime: ${currentTime} < ${this.currentTime}`);
+    }
+    return currentTime;
+  }
+}

package/src/clients/SpokePoolClient/index.ts

@@ -1,11 +1,13 @@
 import { EVMSpokePoolClient } from "./EVMSpokePoolClient";
 import { SVMSpokePoolClient } from "./SVMSpokePoolClient";
+import { TVMSpokePoolClient } from "./TVMSpokePoolClient";
 import { SpokePoolClient } from "./SpokePoolClient";
-import { EVM_SPOKE_POOL_CLIENT_TYPE, SVM_SPOKE_POOL_CLIENT_TYPE } from "./types";
+import { EVM_SPOKE_POOL_CLIENT_TYPE, SVM_SPOKE_POOL_CLIENT_TYPE, TVM_SPOKE_POOL_CLIENT_TYPE } from "./types";
 
 export { EVMSpokePoolClient } from "./EVMSpokePoolClient";
 export { SpokePoolClient, SpokePoolUpdate } from "./SpokePoolClient";
 export { SVMSpokePoolClient } from "./SVMSpokePoolClient";
+export { TVMSpokePoolClient } from "./TVMSpokePoolClient";
 export { SpokePoolManager } from "./SpokePoolClientManager";
 
 /**
@@ -27,3 +29,12 @@ export function isSVMSpokePoolClient(spokePoolClient: SpokePoolClient): spokePoo
   // @TODO: Should we handle the case where spokePoolClient is undefined?
   return spokePoolClient?.type === SVM_SPOKE_POOL_CLIENT_TYPE;
 }
+
+/**
+ * Checks if a SpokePoolClient is a TVMSpokePoolClient.
+ * @param spokePoolClient The SpokePoolClient to check.
+ * @returns True if the SpokePoolClient is a TVMSpokePoolClient, false otherwise.
+ */
+export function isTVMSpokePoolClient(spokePoolClient: SpokePoolClient): spokePoolClient is TVMSpokePoolClient {
+  return spokePoolClient?.type === TVM_SPOKE_POOL_CLIENT_TYPE;
+}

package/src/clients/SpokePoolClient/types.ts

@@ -1,2 +1,3 @@
 export const EVM_SPOKE_POOL_CLIENT_TYPE = "EVM";
 export const SVM_SPOKE_POOL_CLIENT_TYPE = "SVM";
+export const TVM_SPOKE_POOL_CLIENT_TYPE = "TVM";

package/src/clients/index.ts

@@ -11,8 +11,10 @@ export {
   SpokePoolUpdate,
   EVMSpokePoolClient,
   SVMSpokePoolClient,
+  TVMSpokePoolClient,
   isEVMSpokePoolClient,
   isSVMSpokePoolClient,
+  isTVMSpokePoolClient,
   SpokePoolManager,
 } from "./SpokePoolClient";
 export * as BundleDataClient from "./BundleDataClient";

package/src/gasPriceOracle/oracle.ts

@@ -113,6 +113,7 @@ function getGasPriceEthers(provider: providers.Provider, opts: GasPriceEstimateO
     [CHAIN_IDs.POLYGON]: polygon.gasStation,
     [CHAIN_IDs.SCROLL]: ethereum.legacy,
     [CHAIN_IDs.TEMPO]: ethereum.eip1559,
+    [CHAIN_IDs.TRON]: ethereum.legacy,
     [CHAIN_IDs.ZK_SYNC]: ethereum.legacy,
     // Testnet
     [CHAIN_IDs.POLYGON_AMOY]: polygon.gasStation,

package/src/relayFeeCalculator/chain-queries/factory.ts

@@ -3,6 +3,7 @@ import { CHAIN_IDs, TOKEN_SYMBOLS_MAP } from "@across-protocol/constants";
 import { getDeployedAddress } from "@across-protocol/contracts";
 import { asL2Provider } from "@eth-optimism/sdk";
 import { providers } from "ethers";
+import { TronWeb } from "tronweb";
 import { CUSTOM_GAS_TOKENS } from "../../constants";
 import { chainIsEvm, chainIsOPStack, isDefined, chainIsSvm, SvmAddress } from "../../utils";
 import { QueryBase } from "./baseQuery";
@@ -22,7 +23,7 @@ const fixedGasPrice = {
 export class QueryBase__factory {
   static create(
     chainId: number,
-    provider: providers.Provider | svmProvider,
+    provider: providers.Provider | svmProvider | TronWeb,
     symbolMapping = TOKEN_SYMBOLS_MAP,
     spokePoolAddress = getDeployedAddress("SpokePool", chainId),
     relayerAddress = getDefaultRelayer(chainId),

package/src/utils/AddressUtils.ts

@@ -1,7 +1,8 @@
 import { isAddress } from "viem";
 import { providers, utils } from "ethers";
 import bs58 from "bs58";
-import { BigNumber, chainIsEvm, chainIsSvm } from "./";
+import { TronWeb } from "tronweb";
+import { BigNumber, chainIsEvm, chainIsSvm, chainIsTvm } from "./";
 
 /**
  * Verify whether an address' bytecode resembles an EIP-7702 delegation.
@@ -107,6 +108,7 @@ export function toAddressType(address: string, chainId: number): Address {
 
   if (chainIsEvm(chainId) && EvmAddress.validate(rawAddress)) return new EvmAddress(rawAddress);
   else if (chainIsSvm(chainId) && SvmAddress.validate(rawAddress)) return new SvmAddress(rawAddress);
+  else if (chainIsTvm(chainId)) return TvmAddress.from(address);
 
   return new RawAddress(rawAddress);
 }
@@ -187,6 +189,7 @@ export abstract class Address {
   isValidOn(chainId: number): boolean {
     if (chainIsEvm(chainId)) return EvmAddress.validate(this.rawAddress);
     if (chainIsSvm(chainId)) return SvmAddress.validate(this.rawAddress);
+    if (chainIsTvm(chainId)) return TvmAddress.validate(this.rawAddress);
     return false;
   }
 
@@ -227,6 +230,10 @@ export abstract class Address {
   isSVM(): this is SvmAddress {
     return false;
   }
+
+  isTVM(): this is TvmAddress {
+    return false;
+  }
 }
 
 // Subclass of address which strictly deals with 20-byte addresses. These addresses are guaranteed to be valid EVM addresses, so `toAddress` will always succeed.
@@ -304,6 +311,59 @@ export class SvmAddress extends Address {
   }
 }
 
+// Subclass of address which handles TRON (TVM) addresses. Internally stores a 20-byte address (same as EVM),
+// but toNative() returns the TRON Base58Check-encoded address (T...).
+export class TvmAddress extends Address {
+  private readonly _type = "tvm";
+  private nativeAddress: string | undefined = undefined;
+
+  constructor(rawAddress: Uint8Array) {
+    if (!TvmAddress.validate(rawAddress)) {
+      throw new Error(`${utils.hexlify(rawAddress)} is not a valid TVM address`);
+    }
+
+    super(rawAddress);
+    this._type; // tsc noUnusedLocals appeasement.
+  }
+
+  static validate(rawAddress: Uint8Array): boolean {
+    return (
+      rawAddress.length == 20 || (rawAddress.length === 32 && rawAddress.slice(0, 12).every((field) => field === 0))
+    );
+  }
+
+  override isTVM(): this is TvmAddress {
+    return true;
+  }
+
+  // Returns the TRON Base58Check-encoded address (T...).
+  override toNative(): string {
+    const computeNative = () => {
+      const hexString = utils.hexlify(this.rawAddress);
+      // Strip leading zeros to get the 20-byte portion, then convert to TRON format.
+      const evmHex = utils.hexZeroPad(utils.hexStripZeros(hexString), 20);
+      return TronWeb.address.fromHex(evmHex);
+    };
+    return (this.nativeAddress ??= computeNative());
+  }
+
+  override toHexString(): string {
+    return this.toEvmAddress();
+  }
+
+  // Constructs a new TvmAddress from a string. Accepts both 0x-prefixed hex and TRON Base58Check addresses.
+  static from(address: string): TvmAddress {
+    if (address.startsWith("0x")) {
+      return new this(utils.arrayify(address));
+    }
+    // For base58 Tron addresses, convert via TronWeb to get the hex representation.
+    const hex = TronWeb.address.toHex(address);
+    // TronWeb returns hex with a 0x41 prefix (TRON's address byte). Strip 0x41 to get 20 bytes.
+    const rawHex = "0x" + hex.slice(2);
+    return new this(utils.arrayify(rawHex));
+  }
+}
+
 export class RawAddress extends Address {
   private readonly _type = "raw";