@across-protocol/sdk 4.3.136 → 4.3.137-alpha.0

package/dist/types/src/utils/TokenUtils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"TokenUtils.d.ts","sourceRoot":"","sources":["../../../../src/utils/TokenUtils.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,QAAQ,EAAE,MAAM,kCAAkC,CAAC;AAC5D,OAAO,EAAY,SAAS,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAErD,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAEvD,OAAO,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAG7C,OAAO,EAAE,OAAO,EAAE,UAAU,EAAiB,MAAM,gBAAgB,CAAC;AAGpE,KAAK,gBAAgB,GAAG,SAAS,CAAC,QAAQ,GAAG,MAAM,CAAC;AAEpD,wBAAsB,cAAc,CAAC,OAAO,EAAE,MAAM,EAAE,gBAAgB,EAAE,gBAAgB,GAAG,OAAO,CAAC,WAAW,CAAC,CAI9G;AAED,eAAO,MAAM,mBAAmB,GAC9B,gBAAgB,MAAM,EACtB,kBAA6B,KAC5B;IAAE,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAAA;CAAE,GAAG,SAIlC,CAAC;AAEF;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,SAAS,CAa/E;AAED;;;;;;GAMG;AACH,eAAO,MAAM,yBAAyB,GACpC,QAAQ,MAAM,EACd,SAAS,MAAM,EACf;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAAgC,KAC/B,MAAM,GAAG,SAIX,CAAC;AAEF,wBAAgB,4BAA4B,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAGrF;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAC7B,OAAO,EAAE,MAAM,EACf,YAAY,EAAE,MAAM,EACpB,gBAAgB,EAAE,gBAAgB,EAClC,QAAQ,GAAE,QAAmB,GAC5B,OAAO,CAAC,SAAS,CAAC,CAGpB;AAED,wBAAgB,aAAa,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAI1D;AAED,wBAAgB,YAAY,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAIzD;AAED;;;;;;;;GAQG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,YAAY;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAAoB,GAAG,SAAS,CAe3G;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAMnF;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,cAAc,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,GAAG,UAAU,CAetF"}
+{"version":3,"file":"TokenUtils.d.ts","sourceRoot":"","sources":["../../../../src/utils/TokenUtils.ts"],"names":[],"mappings":"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"}

package/dist/types/src/utils/TypeGuards.d.ts

@@ -1,7 +1,9 @@
 import { SVMProvider } from "../arch/svm/types";
 import { EvmProvider } from "../arch/evm/types";
+import { TronWeb } from "tronweb";
 export declare function isPromiseFulfilled<T>(promiseSettledResult: PromiseSettledResult<T>): promiseSettledResult is PromiseFulfilledResult<T>;
 export declare function isPromiseRejected<T>(promiseSettledResult: PromiseSettledResult<T>): promiseSettledResult is PromiseRejectedResult;
 export declare function isDefined<T>(input: T | null | undefined): input is T;
-export declare function isEvmProvider(provider: EvmProvider | SVMProvider): provider is EvmProvider;
+export declare function isTvmProvider(provider: EvmProvider | SVMProvider | TronWeb): provider is TronWeb;
+export declare function isEvmProvider(provider: EvmProvider | SVMProvider | TronWeb): provider is EvmProvider;
 //# sourceMappingURL=TypeGuards.d.ts.map

package/dist/types/src/utils/TypeGuards.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"TypeGuards.d.ts","sourceRoot":"","sources":["../../../../src/utils/TypeGuards.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAGhD,wBAAgB,kBAAkB,CAAC,CAAC,EAClC,oBAAoB,EAAE,oBAAoB,CAAC,CAAC,CAAC,GAC5C,oBAAoB,IAAI,sBAAsB,CAAC,CAAC,CAAC,CAEnD;AAED,wBAAgB,iBAAiB,CAAC,CAAC,EACjC,oBAAoB,EAAE,oBAAoB,CAAC,CAAC,CAAC,GAC5C,oBAAoB,IAAI,qBAAqB,CAE/C;AAED,wBAAgB,SAAS,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,IAAI,GAAG,SAAS,GAAG,KAAK,IAAI,CAAC,CAEpE;AAED,wBAAgB,aAAa,CAAC,QAAQ,EAAE,WAAW,GAAG,WAAW,GAAG,QAAQ,IAAI,WAAW,CAE1F"}
+{"version":3,"file":"TypeGuards.d.ts","sourceRoot":"","sources":["../../../../src/utils/TypeGuards.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAEhD,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAElC,wBAAgB,kBAAkB,CAAC,CAAC,EAClC,oBAAoB,EAAE,oBAAoB,CAAC,CAAC,CAAC,GAC5C,oBAAoB,IAAI,sBAAsB,CAAC,CAAC,CAAC,CAEnD;AAED,wBAAgB,iBAAiB,CAAC,CAAC,EACjC,oBAAoB,EAAE,oBAAoB,CAAC,CAAC,CAAC,GAC5C,oBAAoB,IAAI,qBAAqB,CAE/C;AAED,wBAAgB,SAAS,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,IAAI,GAAG,SAAS,GAAG,KAAK,IAAI,CAAC,CAEpE;AAED,wBAAgB,aAAa,CAAC,QAAQ,EAAE,WAAW,GAAG,WAAW,GAAG,OAAO,GAAG,QAAQ,IAAI,OAAO,CAEhG;AAED,wBAAgB,aAAa,CAAC,QAAQ,EAAE,WAAW,GAAG,WAAW,GAAG,OAAO,GAAG,QAAQ,IAAI,WAAW,CAEpG"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@across-protocol/sdk",
   "author": "UMA Team",
-  "version": "4.3.136",
+  "version": "4.3.137-alpha.0",
   "license": "AGPL-3.0",
   "homepage": "https://docs.across.to/reference/sdk",
   "repository": {
@@ -111,7 +111,7 @@
     "typescript": "^5.9"
   },
   "dependencies": {
-    "@across-protocol/constants": "^3.1.100",
+    "@across-protocol/constants": "^3.1.106",
     "@across-protocol/contracts": "5.0.4",
     "@coral-xyz/anchor": "^0.30.1",
     "@eth-optimism/sdk": "^3.3.1",
@@ -135,6 +135,7 @@
     "lodash.get": "^4.4.2",
     "node-gyp": "^11.0.0",
     "superstruct": "^0.15.4",
+    "tronweb": "^6.2.2",
     "tslib": "^2.6.2",
     "viem": "^2.21.15",
     "winston": "^3.17.0",

package/src/arch/evm/UpgradeUtils.ts

@@ -0,0 +1,18 @@
+import { Contract } from "ethers";
+import { paginatedEventQuery } from "../../utils";
+
+/**
+ * Query for EIP-1967 contract upgrade events.
+ * @param contract A contract instance (must be a UUPS or transparent proxy that emits the Upgraded event).
+ * @param startBlock Optional start of the block range (inclusive). Defaults to 0.
+ * @param endBlock Optional end of the block range (inclusive). Defaults to latest.
+ * @returns An array of block numbers at which upgrades occurred, sorted ascending.
+ */
+export async function get1967Upgrades(contract: Contract, startBlock?: number, endBlock?: number): Promise<number[]> {
+  const from = startBlock ?? 0;
+  const to = endBlock ?? (await contract.provider.getBlockNumber());
+
+  const events = await paginatedEventQuery(contract, contract.filters.Upgraded(), { from, to });
+
+  return events.map(({ blockNumber }) => blockNumber);
+}

package/src/arch/evm/index.ts

@@ -1,4 +1,5 @@
 export * from "./SpokeUtils";
 export * from "./BlockUtils";
+export * from "./UpgradeUtils";
 export * from "./utils";
 export * from "./MessageUtils";

package/src/arch/index.ts

@@ -1,2 +1,3 @@
 export * as evm from "./evm";
 export * as svm from "./svm";
+export * as tvm from "./tvm";

package/src/arch/tvm/BlockUtils.ts

@@ -0,0 +1 @@
+export { averageBlockTime, EVMBlockFinder as TVMBlockFinder } from "../evm/BlockUtils";

package/src/arch/tvm/MessageUtils.ts

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

package/src/arch/tvm/ResourceUtils.ts

@@ -0,0 +1,92 @@
+import { TronWeb } from "tronweb";
+import type { ContractFunctionParameter } from "tronweb/lib/esm/types/TransactionBuilder";
+import { evmToTronAddress } from "./utils/address";
+
+export interface TronResourceEstimate {
+  energyRequired: number;
+  /** Recommended feeLimit in SUN (1 TRX = 1,000,000 SUN). */
+  feeLimit: number;
+}
+
+export interface TronAccountResources {
+  freeNetLimit: number;
+  freeNetUsed: number;
+  energyLimit: number;
+  energyUsed: number;
+}
+
+// Safety multiplier applied to the estimated fee limit (1.2x).
+const FEE_LIMIT_MULTIPLIER = 1.2;
+
+/**
+ * Query the current energy price in SUN per unit of energy.
+ * @param tronWeb A TronWeb instance.
+ * @returns The current energy price in SUN.
+ */
+async function getEnergyPrice(tronWeb: TronWeb): Promise<number> {
+  // getEnergyPrices() returns a comma-separated string of "timestamp:price" pairs.
+  // The last entry is the current price.
+  const pricesStr = await tronWeb.trx.getEnergyPrices();
+  const entries = pricesStr.split(",");
+  const lastEntry = entries[entries.length - 1];
+  const price = Number(lastEntry.split(":")[1]);
+
+  if (!Number.isFinite(price) || price <= 0) {
+    throw new Error(`getEnergyPrice: unexpected energy price: ${lastEntry}`);
+  }
+
+  return price;
+}
+
+/**
+ * Estimate the energy cost and recommended feeLimit for a smart contract call.
+ *
+ * @param tronWeb An authenticated TronWeb instance.
+ * @param contractAddress The target contract address (EVM hex or TRON Base58 format).
+ * @param functionSelector The Solidity function selector (e.g., "transfer(address,uint256)").
+ * @param parameters The function parameters in TronWeb's ContractFunctionParameter format.
+ * @param ownerAddress The address that will execute the transaction (EVM hex or TRON Base58).
+ * @returns The estimated energy required and recommended feeLimit in SUN.
+ */
+export async function estimateTransactionFee(
+  tronWeb: TronWeb,
+  contractAddress: string,
+  functionSelector: string,
+  parameters: ContractFunctionParameter[],
+  ownerAddress: string
+): Promise<TronResourceEstimate> {
+  // Normalise addresses to TRON Base58 if they are in EVM hex format.
+  const tronContractAddress = contractAddress.startsWith("0x") ? evmToTronAddress(contractAddress) : contractAddress;
+  const tronOwnerAddress = ownerAddress.startsWith("0x") ? evmToTronAddress(ownerAddress) : ownerAddress;
+
+  const [estimate, energyPrice] = await Promise.all([
+    tronWeb.transactionBuilder.estimateEnergy(tronContractAddress, functionSelector, {}, parameters, tronOwnerAddress),
+    getEnergyPrice(tronWeb),
+  ]);
+
+  const energyRequired = estimate.energy_required;
+
+  // Calculate feeLimit: energy * price-per-unit, with a safety margin.
+  const feeLimit = Math.ceil(energyRequired * energyPrice * FEE_LIMIT_MULTIPLIER);
+
+  return { energyRequired, feeLimit };
+}
+
+/**
+ * Query the current resource allocation and usage for an account.
+ *
+ * @param tronWeb A TronWeb instance.
+ * @param address The account address (EVM hex or TRON Base58 format).
+ * @returns The account's bandwidth and energy limits and usage.
+ */
+export async function getAccountResources(tronWeb: TronWeb, address: string): Promise<TronAccountResources> {
+  const tronAddress = address.startsWith("0x") ? evmToTronAddress(address) : address;
+  const resources = await tronWeb.trx.getAccountResources(tronAddress);
+
+  return {
+    freeNetLimit: resources.freeNetLimit ?? 0,
+    freeNetUsed: resources.freeNetUsed ?? 0,
+    energyLimit: resources.NetLimit ?? 0,
+    energyUsed: resources.NetUsed ?? 0,
+  };
+}

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,62 @@
+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
+): 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 txWrapper = await tronWeb.transactionBuilder.triggerSmartContract(
+    tronAddress,
+    // Use empty function selector — the `input` option provides the full calldata.
+    "",
+    { feeLimit, input: data },
+    [],
+    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/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) {