@across-protocol/sdk 4.4.0-alpha.9 → 4.4.1

package/src/clients/mocks/index.ts

@@ -1,4 +1,5 @@
 export * from "./MockConfigStoreClient";
+export * from "./MockEvents";
 export * from "./MockHubPoolClient";
 export * from "./MockSpokePoolClient";
 export * from "./MockSvmCpiEventsClient";

package/src/coingecko/Coingecko.ts

@@ -1,6 +1,7 @@
 import assert from "assert";
 import { fetchWithTimeout, getCoingeckoTokenIdByAddress, retry } from "../utils";
 import { Logger } from "../relayFeeCalculator";
+import { CoingeckoPriceNotFoundError } from "./CoingeckoErrors";
 
 export function msToS(ms: number) {
   return Math.floor(ms / 1000);
@@ -206,7 +207,9 @@ export class Coingecko {
     const _from = msToS(from);
     const _to = msToS(to);
     const result = await this.call<HistoricPriceChartData>(
-      `coins/ethereum/contract/${contract.toLowerCase()}/market_chart/range/?vs_currency=${currency}&from=${_from}&to=${_to}`
+      `coins/ethereum/contract/${encodeURIComponent(
+        contract.toLowerCase()
+      )}/market_chart/range/?vs_currency=${encodeURIComponent(currency)}&from=${_from}&to=${_to}`
     );
     // fyi timestamps are returned in ms in contrast to the current price endpoint
     if (result.prices) return result.prices;
@@ -230,7 +233,7 @@ export class Coingecko {
     const coingeckoTokenIdentifier = await this.getCoingeckoTokenId(contractAddress, chainId);
     assert(date, "Requires date string");
     // Build the path for the Coingecko API request
-    const url = `coins/${coingeckoTokenIdentifier}/history`;
+    const url = `coins/${encodeURIComponent(coingeckoTokenIdentifier)}/history`;
     // Build the query parameters for the Coingecko API request
     const queryParams = {
       date,
@@ -244,7 +247,9 @@ export class Coingecko {
   }
 
   getContractDetails(contract_address: string, platform_id = "ethereum") {
-    return this.call(`coins/${platform_id}/contract/${contract_address.toLowerCase()}`);
+    return this.call(
+      `coins/${encodeURIComponent(platform_id)}/contract/${encodeURIComponent(contract_address.toLowerCase())}`
+    );
   }
 
   async getCurrentPriceByContract(contractAddress: string, currency = "usd", chainId = 1): Promise<[string, number]> {
@@ -256,7 +261,9 @@ export class Coingecko {
       tokenPrice = priceCache[contractAddress];
     }
 
-    assert(tokenPrice !== undefined);
+    if (tokenPrice === undefined) {
+      throw new CoingeckoPriceNotFoundError({ identifier: contractAddress, currency, lookupType: "address" });
+    }
     return [tokenPrice.timestamp.toString(), tokenPrice.price];
   }
 
@@ -268,22 +275,25 @@ export class Coingecko {
       const coingeckoId = await this.getCoingeckoTokenId(contractAddress, chainId);
       // Build the path for the Coingecko API request
       const result = await this.call<Record<string, CGTokenPrice>>(
-        `simple/price?ids=${coingeckoId}&vs_currencies=${currency}&include_last_updated_at=true`
+        `simple/price?ids=${encodeURIComponent(coingeckoId)}&vs_currencies=${encodeURIComponent(
+          currency
+        )}&include_last_updated_at=true`
       );
       const cgPrice = result?.[coingeckoId];
       if (cgPrice === undefined || !cgPrice?.[currency]) {
-        const errMsg = `No price found for ${coingeckoId}`;
         this.logger.debug({
           at: "Coingecko#getCurrentPriceById",
-          message: errMsg,
+          message: `No Coingecko price found for id '${coingeckoId}' in ${currency}`,
         });
-        throw new Error(errMsg);
+        throw new CoingeckoPriceNotFoundError({ identifier: coingeckoId, currency, lookupType: "id" });
       } else {
         this.updatePriceCache(cgPrice, contractAddress, currency, platform_id);
       }
     }
     tokenPrice = priceCache[contractAddress];
-    assert(tokenPrice !== undefined);
+    if (tokenPrice === undefined) {
+      throw new CoingeckoPriceNotFoundError({ identifier: contractAddress, currency, lookupType: "address" });
+    }
     return [tokenPrice.timestamp.toString(), tokenPrice.price];
   }
 
@@ -291,22 +301,25 @@ export class Coingecko {
     let tokenPrice = this.getCachedSymbolPrice(symbol, currency);
     if (tokenPrice === undefined) {
       const result = await this.call<Record<string, CGTokenPrice>>(
-        `simple/price?symbols=${symbol}&vs_currencies=${currency}&include_last_updated_at=true`
+        `simple/price?symbols=${encodeURIComponent(symbol)}&vs_currencies=${encodeURIComponent(
+          currency
+        )}&include_last_updated_at=true`
       );
       const cgPrice = result?.[symbol.toLowerCase()] || result?.[symbol.toUpperCase()];
       if (cgPrice === undefined || !cgPrice?.[currency]) {
-        const errMsg = `Failed to retrieve ${symbol}/${currency} price via Coingecko API`;
         this.logger.debug({
           at: "Coingecko#getCurrentPriceBySymbol",
-          message: errMsg,
+          message: `No Coingecko price found for symbol '${symbol}' in ${currency}`,
         });
-        throw new Error(errMsg);
+        throw new CoingeckoPriceNotFoundError({ identifier: symbol, currency, lookupType: "symbol" });
       } else {
         this.updatePriceCacheBySymbol(cgPrice, symbol, currency);
       }
     }
     tokenPrice = this.getCachedSymbolPrice(symbol, currency);
-    assert(tokenPrice !== undefined);
+    if (tokenPrice === undefined) {
+      throw new CoingeckoPriceNotFoundError({ identifier: symbol, currency, lookupType: "symbol" });
+    }
     return [tokenPrice.timestamp.toString(), tokenPrice.price];
   }
 
@@ -344,9 +357,9 @@ export class Coingecko {
     try {
       // Coingecko expects a comma-delimited (%2c) list.
       result = await this.call(
-        `simple/token_price/${platform_id}?contract_addresses=${contract_addresses.join(
-          "%2C"
-        )}&vs_currencies=${currency}&include_last_updated_at=true`
+        `simple/token_price/${encodeURIComponent(platform_id)}?contract_addresses=${contract_addresses
+          .map((addr) => encodeURIComponent(addr))
+          .join("%2C")}&vs_currencies=${encodeURIComponent(currency)}&include_last_updated_at=true`
       );
     } catch (err) {
       const errMsg = `Failed to retrieve ${platform_id}/${currency} prices (${err})`;

package/src/coingecko/CoingeckoErrors.ts

@@ -0,0 +1,24 @@
+/**
+ * Thrown when a price lookup against the Coingecko API does not return a
+ * usable price for the requested identifier. Callers can use `instanceof` to
+ * map this to a 404 / not-found response without needing to string-match
+ * the underlying message.
+ */
+export type CoingeckoLookupType = "symbol" | "address" | "id";
+
+export class CoingeckoPriceNotFoundError extends Error {
+  readonly identifier: string;
+  readonly currency: string;
+  readonly lookupType: CoingeckoLookupType;
+
+  constructor(args: { identifier: string; currency: string; lookupType: CoingeckoLookupType; cause?: unknown }) {
+    super(
+      `No Coingecko price found for ${args.lookupType} '${args.identifier}' in ${args.currency}`,
+      args.cause !== undefined ? { cause: args.cause } : undefined
+    );
+    this.name = "CoingeckoPriceNotFoundError";
+    this.identifier = args.identifier;
+    this.currency = args.currency;
+    this.lookupType = args.lookupType;
+  }
+}

package/src/coingecko/index.ts

@@ -1 +1,2 @@
 export * from "./Coingecko";
+export * from "./CoingeckoErrors";

package/src/constants.ts

@@ -76,6 +76,7 @@ export const STABLE_COIN_SYMBOLS = [
   ...BRIDGED_USDC_SYMBOLS,
   TOKEN_SYMBOLS_MAP.USDB.symbol,
   TOKEN_SYMBOLS_MAP.USDC.symbol,
+  TOKEN_SYMBOLS_MAP.USDG.symbol,
   TOKEN_SYMBOLS_MAP.USDT.symbol,
   TOKEN_SYMBOLS_MAP["USDT-BNB"].symbol,
   TOKEN_SYMBOLS_MAP["USDT-SPOT"].symbol,

package/src/gasPriceOracle/adapters/solana.ts

@@ -1,14 +1,18 @@
 import { SVMProvider } from "../../arch/svm";
-import { toBN, dedupArray } from "../../utils";
+import { BN, toBN, dedupArray } from "../../utils";
 import { SvmGasPriceEstimate } from "../types";
 import { GasPriceEstimateOptions } from "../oracle";
+import { SvmGasPriceUnavailableError } from "../errors";
 import {
   TransactionMessage,
   TransactionMessageBytesBase64,
   TransactionMessageWithFeePayer,
   compileTransaction,
+  setTransactionMessageLifetimeUsingBlockhash,
 } from "@solana/kit";
 
+const MAX_BASE_FEE_ATTEMPTS = 2;
+
 /**
  * @notice Returns result of getFeeForMessage and getRecentPrioritizationFees RPC calls.
  * @returns GasPriceEstimate
@@ -18,13 +22,8 @@ export async function messageFee(provider: SVMProvider, opts: GasPriceEstimateOp
 
   // Cast the opaque unsignedTx type to a solana-kit TransactionMessage with fee payer.
   const unsignedTx = _unsignedTx as TransactionMessage & TransactionMessageWithFeePayer;
-  const compiledTransaction = compileTransaction(unsignedTx);
 
-  // Get this base fee. This should result in LAMPORTS_PER_SIGNATURE * nSignatures.
-  const encodedTransactionMessage = Buffer.from(compiledTransaction.messageBytes).toString(
-    "base64"
-  ) as TransactionMessageBytesBase64;
-  const baseFeeResponse = await provider.getFeeForMessage(encodedTransactionMessage).send();
+  const baseFee = await getBaseFee(provider, unsignedTx);
 
   // Get the priority fee by calling `getRecentPrioritzationFees` on all the addresses in the transaction's instruction array.
   const instructionAddresses = dedupArray(unsignedTx.instructions.map((instruction) => instruction.programAddress));
@@ -40,8 +39,29 @@ export async function messageFee(provider: SVMProvider, opts: GasPriceEstimateOp
   const microLamportsPerComputeUnit = toBN(
     totalPrioritizationFees / BigInt(Math.max(nonzeroPrioritizationFees.length, 1))
   );
-  return {
-    baseFee: toBN(baseFeeResponse!.value!),
-    microLamportsPerComputeUnit,
-  };
+
+  return { baseFee, microLamportsPerComputeUnit };
+}
+
+// `getFeeForMessage` returns `{ value: null }` when the cluster has not yet recognised
+// the blockhash referenced by the message. With a load-balanced RPC pool, this happens
+// when the request lands on a node that hasn't seen the blockhash from an earlier
+// `getLatestBlockhash` call. We side-step the race by always refreshing to a `confirmed`
+// blockhash before each attempt — by definition propagated to all healthy nodes — and
+// retrying once if a fee call still comes back null. Fee estimation is never sent
+// on-chain, so blockhash freshness doesn't matter.
+async function getBaseFee(provider: SVMProvider, tx: TransactionMessage & TransactionMessageWithFeePayer): Promise<BN> {
+  for (let attempt = 0; attempt < MAX_BASE_FEE_ATTEMPTS; attempt++) {
+    const { value: confirmedBlockhash } = await provider.getLatestBlockhash({ commitment: "confirmed" }).send();
+    const refreshedTx = setTransactionMessageLifetimeUsingBlockhash(confirmedBlockhash, tx);
+    const compiled = compileTransaction(refreshedTx);
+    const encoded = Buffer.from(compiled.messageBytes).toString("base64") as TransactionMessageBytesBase64;
+    const { value } = await provider.getFeeForMessage(encoded).send();
+    if (value !== null && value !== undefined) {
+      return toBN(value);
+    }
+  }
+  throw new SvmGasPriceUnavailableError(
+    "Solana getFeeForMessage returned null even after retrying with a confirmed blockhash"
+  );
 }

package/src/gasPriceOracle/errors.ts

@@ -0,0 +1,14 @@
+/**
+ * Thrown when the SVM gas-price oracle cannot determine a base fee for the
+ * supplied message — most commonly because Solana's `getFeeForMessage` RPC
+ * returned `{ value: null }` even after retrying with a confirmed blockhash.
+ *
+ * Callers can use `instanceof` to map this to a transient upstream-RPC error
+ * (e.g. HTTP 502 / 503) rather than treating it as an unhandled exception.
+ */
+export class SvmGasPriceUnavailableError extends Error {
+  constructor(message: string, opts?: { cause?: unknown }) {
+    super(message, opts?.cause !== undefined ? { cause: opts.cause } : undefined);
+    this.name = "SvmGasPriceUnavailableError";
+  }
+}

package/src/gasPriceOracle/index.ts

@@ -1,2 +1,3 @@
 export { getGasPriceEstimate, GasPriceEstimateOptions } from "./oracle";
 export { GasPriceEstimate, EvmGasPriceEstimate, SvmGasPriceEstimate } from "./types";
+export { SvmGasPriceUnavailableError } from "./errors";

package/src/gasPriceOracle/oracle.ts

@@ -111,9 +111,9 @@ function getGasPriceEthers(provider: providers.Provider, opts: GasPriceEstimateO
   const gasPriceFeeds = {
     [CHAIN_IDs.ARBITRUM]: arbitrum.eip1559,
     [CHAIN_IDs.POLYGON]: polygon.gasStation,
-    [CHAIN_IDs.SCROLL]: ethereum.legacy,
     [CHAIN_IDs.TEMPO]: ethereum.eip1559,
     [CHAIN_IDs.TRON]: ethereum.legacy,
+    [CHAIN_IDs.ROBINHOOD]: arbitrum.eip1559,
     [CHAIN_IDs.ZK_SYNC]: ethereum.legacy,
     // Testnet
     [CHAIN_IDs.POLYGON_AMOY]: polygon.gasStation,

package/src/providers/alchemy.ts

@@ -7,6 +7,7 @@ const MAINNET_CHAIN_IDs = Object.values(_MAINNET_CHAIN_IDs).map(Number);
 const endpoints: { [chainId: number]: string } = {
   [CHAIN_IDs.ARBITRUM]: "arb",
   [CHAIN_IDs.ARBITRUM_SEPOLIA]: "arb-sepolia",
+  [CHAIN_IDs.AVALANCHE]: "avax",
   [CHAIN_IDs.MAINNET]: "eth",
   [CHAIN_IDs.SEPOLIA]: "eth-sepolia",
   [CHAIN_IDs.OPTIMISM]: "opt",

package/src/providers/solana/quorumFallbackRpcFactory.ts

@@ -4,7 +4,7 @@ import { isPromiseFulfilled, isPromiseRejected } from "../../utils/TypeGuards";
 import { compareSvmRpcResults, createSendErrorWithMessage } from "../utils";
 import { CachedSolanaRpcFactory } from "./cachedRpcFactory";
 import { SolanaBaseRpcFactory, SolanaClusterRpcFactory } from "./baseRpcFactories";
-import { shouldFailImmediate } from "./utils";
+import { formatRpcError, isChainWideFailure, shouldFailImmediate } from "./utils";
 
 // This factory stores multiple Cached RPC factories so that users of this factory can specify multiple RPC providers
 // and the factory will fallback through them if any RPC calls fail. This factory also implements quorum logic amongst
@@ -57,18 +57,24 @@ export class QuorumFallbackSolanaRpcFactory extends SolanaBaseRpcFactory {
           .transport<TResponse>(...args)
           .then((result): [SolanaClusterRpcFactory, RpcResponse<TResponse>] => [factory.rpcFactory, result])
           .catch((error) => {
-            // Append the provider and error to the error array.
-            // eslint-disable-next-line @typescript-eslint/no-explicit-any
-            errors.push([factory.rpcFactory, (error as any)?.stack || error?.toString()]);
+            // Preserve the underlying JSON-RPC error code in the wrap message.
+            errors.push([factory.rpcFactory, formatRpcError(error)]);
 
             // If all fallback providers fail, then return the last received error.
             if (fallbackFactories.length === 0) {
               throw error;
             }
 
-            // If one RPC provider reverted, others likely will too. Skip them.
-            if (quorumThreshold === 1 && shouldFailImmediate(method, error)) {
-              throw new Error(`RPC provider reverted for method ${method}`);
+            // If the error is a deterministic, network-wide chain fact (slot skipped,
+            // preflight failure), every fallback provider will return the same answer.
+            // Skip the fallback so the chain rejects with the underlying SolanaError —
+            // both to save RPC budget and to keep `rejections.every(shouldFailImmediate)`
+            // below from being defeated by a non-Solana failure on a later fallback.
+            // Note: `isChainWideFailure` is intentionally narrower than `shouldFailImmediate`.
+            // SVM_LONG_TERM_STORAGE_SLOT_SKIPPED is provider-local (the slot may be missing from
+            // *this* provider's archive but present elsewhere), so we still try fallbacks for it.
+            if (isChainWideFailure(method, error)) {
+              throw error;
             }
 
             const currentFactory = factory.rpcFactory.clusterUrl;
@@ -95,6 +101,13 @@ export class QuorumFallbackSolanaRpcFactory extends SolanaBaseRpcFactory {
       };
 
       if (!results.every(isPromiseFulfilled)) {
+        // If every rejection is shouldFailImmediate, rethrow the original so callers can branch
+        // on `isSolanaError(...)` rather than seeing a wrapped Error.
+        const rejections = results.filter(isPromiseRejected);
+        if (rejections.length > 0 && rejections.every(({ reason }) => shouldFailImmediate(method, reason))) {
+          throw rejections[0].reason;
+        }
+
         // Format the error so that it's very clear which providers failed and succeeded.
         const errorTexts = getErrorStrings();
         const successfulProviderUrls = results.filter(isPromiseFulfilled).map((result) => result.value[0].clusterUrl);
@@ -200,7 +213,7 @@ export class QuorumFallbackSolanaRpcFactory extends SolanaBaseRpcFactory {
             .transport<TResponse>(...args)
             .then((result): [SolanaClusterRpcFactory, TResponse] => [factory.rpcFactory, result])
             .catch((err) => {
-              errors.push([factory.rpcFactory, err?.stack || err?.toString()]);
+              errors.push([factory.rpcFactory, formatRpcError(err)]);
               throw new Error("Fallback RPC call failed while trying to reach quorum");
             });
         })

package/src/providers/solana/utils.ts

@@ -1,6 +1,11 @@
 import { RpcTransport } from "@solana/rpc-spec";
 import { SolanaRpcApi } from "@solana/kit";
-import { isSolanaError, SVM_SLOT_SKIPPED, SVM_LONG_TERM_STORAGE_SLOT_SKIPPED } from "../../arch/svm";
+import {
+  isSolanaError,
+  SVM_SLOT_SKIPPED,
+  SVM_LONG_TERM_STORAGE_SLOT_SKIPPED,
+  SVM_TRANSACTION_PREFLIGHT_FAILURE,
+} from "../../arch/svm";
 
 /**
  * This is the type we pass to define a Solana RPC request "task".
@@ -58,6 +63,20 @@ export interface JitoInterface extends SolanaRpcApi {
   simulateBundle(transactions: { encodedTransactions: string[] }, opts?: SimulationOpts): SolanaBundleSimulation;
 }
 
+/**
+ * Render an RPC error for log/wrap messages. For SolanaErrors, includes the numeric JSON-RPC
+ * code alongside the server message; otherwise falls back to stack/toString.
+ */
+export function formatRpcError(error: unknown): string {
+  if (isSolanaError(error)) {
+    const { __code: code, __serverMessage: serverMessage } = error.context;
+    const message = serverMessage ?? (error as { message?: string }).message ?? "";
+    return `SolanaError [${code}]: ${message}`;
+  }
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  return (error as any)?.stack || (error as any)?.toString?.() || String(error);
+}
+
 /**
  * Determine whether a Solana RPC error indicates an unrecoverable error that should not be retried.
  * @param method RPC method name.
@@ -76,6 +95,35 @@ export function shouldFailImmediate(method: string, error: unknown): boolean {
     case "getBlockTime":
       // No block at the requested slot. This may not be correct for blocks > 1 year old.
       return [SVM_SLOT_SKIPPED, SVM_LONG_TERM_STORAGE_SLOT_SKIPPED].includes(code);
+    case "sendTransaction":
+      // Preflight failures are deterministic across providers; falling back only succeeds on RPCs that skip preflight.
+      return code === SVM_TRANSACTION_PREFLIGHT_FAILURE;
+    default:
+      return false;
+  }
+}
+
+/**
+ * Subset of `shouldFailImmediate` for errors that are deterministic *across the entire network*,
+ * not just for the provider that returned them. Used to decide whether to skip fallback providers
+ * after a required provider rejects.
+ *
+ * Excludes SVM_LONG_TERM_STORAGE_SLOT_SKIPPED: that code can mean "the slot is missing from this
+ * provider's long-term storage" rather than "the slot was skipped on the network", so an archival
+ * fallback may still be able to answer.
+ */
+export function isChainWideFailure(method: string, error: unknown): boolean {
+  if (!isSolanaError(error)) {
+    return false;
+  }
+
+  const { __code: code } = error.context;
+  switch (method) {
+    case "getBlock":
+    case "getBlockTime":
+      return code === SVM_SLOT_SKIPPED;
+    case "sendTransaction":
+      return code === SVM_TRANSACTION_PREFLIGHT_FAILURE;
     default:
       return false;
   }

package/src/providers/utils.ts

@@ -141,9 +141,10 @@ export function formatProviderError(provider: providers.StaticJsonRpcProvider, r
   return `Provider ${getOriginFromURL(provider.connection.url)} failed with error: ${rawErrorText}`;
 }
 
-export function createSendErrorWithMessage(message: string, sendError: Record<string, unknown>) {
-  const error = new Error(message);
-  return { ...sendError, ...error };
+// `{ cause }` keeps the wrapper an actual Error (was a spread-collapsed plain object) and keeps
+// the underlying rejection reason reachable for callers and loggers.
+export function createSendErrorWithMessage(message: string, sendError: unknown): Error {
+  return new Error(message, { cause: sendError });
 }
 
 /**

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

@@ -4,12 +4,13 @@ import { getDeployedAddress } from "@across-protocol/contracts";
 import { asL2Provider } from "@eth-optimism/sdk";
 import { providers } from "ethers";
 import { CUSTOM_GAS_TOKENS } from "../../constants";
-import { chainIsEvm, chainIsOPStack, isDefined, chainIsSvm, SvmAddress } from "../../utils";
+import { chainIsEvm, chainIsOPStack, isDefined, chainIsSvm, chainIsTvm, SvmAddress } from "../../utils";
 import { QueryBase } from "./baseQuery";
 import { SVMProvider as svmProvider } from "../../arch/svm";
 import { DEFAULT_LOGGER, getDefaultRelayer, Logger } from "../relayFeeCalculator";
 import { CustomGasTokenQueries } from "./customGasToken";
 import { SvmQuery } from "./svmQuery";
+import { TvmQuery } from "./tvmQuery";
 
 /**
  * Some chains have a fixed gas price that is applied to the gas estimates. We should override
@@ -35,7 +36,12 @@ export class QueryBase__factory {
     const customGasTokenSymbol = CUSTOM_GAS_TOKENS[chainId];
     if (chainIsEvm(chainId) && isDefined(customGasTokenSymbol)) {
       assert(relayerAddress.isEVM());
-      return new CustomGasTokenQueries({
+      // TVM chains route through TvmQuery so that bandwidth — a Tron-native cost the
+      // EVM compatibility layer's `eth_estimateGas` does not surface — is included in
+      // `auxiliaryNativeTokenCost`. Otherwise fall back to the EVM-flavoured custom gas
+      // token query.
+      const QueryCtor = chainIsTvm(chainId) ? TvmQuery : CustomGasTokenQueries;
+      return new QueryCtor({
         queryBaseArgs: [
           provider as providers.Provider,
           symbolMapping,

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

@@ -2,3 +2,4 @@ export * from "./baseQuery";
 export * from "./factory";
 export * from "./customGasToken";
 export * from "./svmQuery";
+export * from "./tvmQuery";

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

@@ -0,0 +1,20 @@
+import { arch } from "../..";
+import { RelayData } from "../../interfaces";
+import { BigNumber } from "../../utils";
+import { CustomGasTokenQueries } from "./customGasToken";
+
+/**
+ * TVM (TRON) query implementation. Extends `CustomGasTokenQueries` to add bandwidth
+ * accounting via `getAuxiliaryNativeTokenCost`, which the base EVM path returns 0 for.
+ *
+ * Energy (Tron's analogue of gas) is already estimated by `voidSigner.estimateGas`
+ * against the EVM-compat RPC and surfaces in `tokenGasCost`. Bandwidth is a separate
+ * Tron-native resource that the EVM compatibility layer does not surface, so we
+ * estimate it here from the deposit's `message` length and a fixed `fillRelay`
+ * calldata footprint.
+ */
+export class TvmQuery extends CustomGasTokenQueries {
+  override getAuxiliaryNativeTokenCost(deposit: RelayData): BigNumber {
+    return arch.tvm.getAuxiliaryNativeTokenCost(deposit);
+  }
+}

package/src/relayFeeCalculator/relayFeeCalculator.ts

@@ -299,17 +299,19 @@ export class RelayFeeCalculator {
   }
 
   /**
-   * Calculate the auxiliary native token fee as a % of the amount to relay.
+   * Resolve the auxiliary native token fee in absolute output-token units and as a
+   * percentage of `outputAmount`. The absolute form is amount-invariant (it depends
+   * only on the deposit and price), so callers reasoning about `minDeposit` should
+   * prefer it over the percent — the percent diverges as `outputAmount → 0`.
+   *
    * Treats auxiliary native outlay as value forwarded to user, reported separately.
    */
-  async auxNativeFeePercent(
+  protected async resolveAuxNativeFee(
     deposit: RelayData & { destinationChainId: number },
     outputAmount: BigNumberish,
     outputTokenInfo: TokenInfo,
     _tokenPrice?: number
-  ): Promise<BigNumber> {
-    if (toBN(outputAmount).eq(bnZero)) return MAX_BIG_INT;
-
+  ): Promise<{ auxFeesInToken: BigNumber; auxNativeFeePercent: BigNumber }> {
     let auxNativeCost = bnZero;
     try {
       auxNativeCost = this.queries.getAuxiliaryNativeTokenCost(deposit);
@@ -325,8 +327,26 @@ export class RelayFeeCalculator {
     }
 
     const tokenPrice = await this.resolveTokenPrice(outputTokenInfo, _tokenPrice, deposit);
-    const auxFeesInToken = nativeToToken(auxNativeCost, tokenPrice, outputTokenInfo.decimals, this.nativeTokenDecimals);
-    return percent(auxFeesInToken, outputAmount);
+    const auxFeesInToken = toBN(
+      nativeToToken(auxNativeCost, tokenPrice, outputTokenInfo.decimals, this.nativeTokenDecimals)
+    );
+    const auxNativeFeePercent = toBN(outputAmount).eq(bnZero) ? MAX_BIG_INT : percent(auxFeesInToken, outputAmount);
+    return { auxFeesInToken, auxNativeFeePercent };
+  }
+
+  /**
+   * Calculate the auxiliary native token fee as a % of the amount to relay.
+   * Treats auxiliary native outlay as value forwarded to user, reported separately.
+   */
+  async auxNativeFeePercent(
+    deposit: RelayData & { destinationChainId: number },
+    outputAmount: BigNumberish,
+    outputTokenInfo: TokenInfo,
+    _tokenPrice?: number
+  ): Promise<BigNumber> {
+    if (toBN(outputAmount).eq(bnZero)) return MAX_BIG_INT;
+    const { auxNativeFeePercent } = await this.resolveAuxNativeFee(deposit, outputAmount, outputTokenInfo, _tokenPrice);
+    return auxNativeFeePercent;
   }
 
   // Note: these variables are unused now, but may be needed in future versions of this function that are more complex.
@@ -554,7 +574,13 @@ export class RelayFeeCalculator {
     );
     const capitalFeeTotal = capitalFeePercent.mul(outToInDecimals(outputAmount.toString())).div(fixedPointAdjustment);
 
-    const auxNativeFeePercent = await this.auxNativeFeePercent(deposit, outputAmount, outputTokenInfo, tokenPrice);
+    const { auxFeesInToken, auxNativeFeePercent } = await this.resolveAuxNativeFee(
+      deposit,
+      outputAmount,
+      outputTokenInfo,
+      tokenPrice
+    );
+    const auxFeesInInputDecimals = toBN(outToInDecimals(auxFeesInToken.toString()));
     const auxNativeFeeTotal = auxNativeFeePercent
       .mul(outToInDecimals(outputAmount.toString()))
       .div(fixedPointAdjustment);
@@ -563,26 +589,41 @@ export class RelayFeeCalculator {
     const relayFeePercent = gasFeePercent.add(capitalFeePercent).add(auxNativeFeePercent);
     const relayFeeTotal = gasFeeTotal.add(capitalFeeTotal).add(auxNativeFeeTotal);
 
-    // We don't want the relayer to incur an excessive gas fee charge as a % of the deposited total. The maximum
-    // gas fee % charged is equal to the remaining fee % leftover after subtracting the capital fee % and aux fee %
-    // from the fee limit %. We then compute the minimum deposited amount required to not exceed the maximum
-    // gas fee %: maxGasFeePercent = gasFeeTotal / minDeposit. Refactor this to figure out the minDeposit:
-    // minDeposit = gasFeeTotal / maxGasFeePercent, and subsequently determine
-    // isAmountTooLow = amountToRelay < minDeposit.
+    // `maxGasFeePercent` reports the remaining fee budget at the given `outputAmount`:
+    // what fraction of the input can still be spent on gas after capital and auxiliary
+    // fees are taken out. Kept in per-amount terms for backwards compatibility with
+    // callers that display it as a live percentage.
     const maxGasFeePercent = max(
-      toBNWei(this.feeLimitPercent / 100)
-        .sub(capitalFeePercent)
-        .sub(auxNativeFeePercent),
-      toBN(0)
+      toBNWei(this.feeLimitPercent).div(100).sub(capitalFeePercent).sub(auxNativeFeePercent),
+      bnZero
     );
-    // If maxGasFee % is 0, then the min deposit should be infinite because there is no deposit amount that would
-    // incur a non zero gas fee % charge. In this case, isAmountTooLow should always be true.
+
+    // `minDeposit` is the smallest `outputAmount` for which gas, capital, and
+    // auxiliary fees together stay under `feeLimitPercent`. Solving with the variable
+    // costs in absolute terms (gas + aux scale as constant_cost / amount; capital is
+    // ~constant near the bound):
+    //
+    //   (gasFeeTotal + auxFeesInInputDecimals) / minDeposit + capitalFeePercent
+    //     <= feeLimitPercent
+    //
+    //   ⇒ minDeposit = (gasFeeTotal + auxFeesInInputDecimals) /
+    //                  (feeLimitPercent − capitalFeePercent)
+    //
+    // The earlier closed-form derived `minDeposit` from the per-amount
+    // `maxGasFeePercent`, which incorporated `auxNativeFeePercent = auxCost /
+    // outputAmount`. That ratio diverges as `outputAmount → 0`, pinning `minDeposit`
+    // to `MAX_BIG_INT` for any small simulation amount on chains with non-zero
+    // auxiliary cost (e.g. Tron bandwidth) — even though a real deposit would have
+    // been feasible. Computing it directly from absolute aux cost avoids that.
+    const minDepositBudget = max(toBNWei(this.feeLimitPercent).div(100).sub(capitalFeePercent), bnZero);
     let minDeposit: BigNumber, isAmountTooLow: boolean;
-    if (maxGasFeePercent.eq(toBN(0))) {
+    if (minDepositBudget.eq(bnZero)) {
+      // Capital fee alone has exhausted the budget; no deposit amount can satisfy
+      // the limit.
       minDeposit = MAX_BIG_INT;
       isAmountTooLow = true;
     } else {
-      minDeposit = gasFeeTotal.mul(fixedPointAdjustment).div(maxGasFeePercent);
+      minDeposit = gasFeeTotal.add(auxFeesInInputDecimals).mul(fixedPointAdjustment).div(minDepositBudget);
       isAmountTooLow = toBN(outputAmount).lt(minDeposit);
     }
 

package/src/utils/AddressUtils.ts

@@ -80,6 +80,29 @@ export function toEvmAddress(hexString: string): string {
   return utils.getAddress(rawAddress);
 }
 
+/**
+ * Normalizes an address to its canonical native string for the detected family
+ * (checksummed EVM hex, Solana base58, or TRON base58). Returns undefined when
+ * the input is not valid in any supported format.
+ */
+export function normalizeAddressString(address: string): string | undefined {
+  const value = address.trim();
+  if (!value) return undefined;
+
+  try {
+    // TVM base58 (T..., 34 chars).
+    if (value.length === 34 && TronWeb.isAddress(value)) return TvmAddress.from(value).toNative();
+    // TVM hex (41 + 40 hex chars, no 0x prefix) — distinct from EVM (0x + 40 hex chars).
+    if (value.length === 42 && TronWeb.isAddress(value)) return TvmAddress.from(value).toNative();
+    // EVM hex (0x + 40 hex).
+    if (value.length === 42 && isValidEvmAddress(value)) return EvmAddress.from(value).toNative();
+    // SVM base58 or 32-byte hex.
+    return SvmAddress.from(value).toNative();
+  } catch {
+    return undefined;
+  }
+}
+
 export function isValidEvmAddress(address: string): boolean {
   if (isAddress(address)) {
     return true;