feat(tron): add gasless TRC20 withdraw branch (sign-only)

Branch build_tron_withdraw on WithdrawFeeMethod (Native/Gasless/Auto):
Gasless signs a TIP-712 PermitTransfer locally and returns it as a
TronGasfreeRelayPayload wrapped in TransactionData::Unsigned for later
submission via send_raw_transaction. Auto compares native vs gasless
quotes and falls back; Gasless honors fallback_to_native on deterministic
provider unavailability.

Add a TxFeeDetails::TronGasless variant for the token-paid fee shape so
fee details can stay sized for native withdraws and clients can branch
on the type tag instead of probing optional fields.

Thread per-token gasless config (transfer_max_fee cap) through ERC20
token activation; the cap is enforced into the signed permit's max_fee.
Reject fee_method=gasless|auto on non-TRON coins explicitly.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: shamardy

mm2src/coins/eth.rs

@@ -118,7 +118,7 @@ use std::str::from_utf8;
 use std::str::FromStr;
 use std::sync::atomic::{AtomicU64, Ordering as AtomicOrdering};
 use std::sync::{Arc, Mutex};
-use tron::gasfree::ResolvedTronGaslessProvider;
+use tron::gasfree::{ResolvedTronGaslessProvider, ResolvedTronGaslessTokenConfig};
 use web3::types::{
     Action as TraceAction, BlockId, BlockNumber, Bytes, CallRequest, FilterBuilder, Log, Trace, TraceFilterBuilder,
     Transaction as Web3Transaction, TransactionId, U64,
@@ -1087,6 +1087,8 @@ pub struct EthCoinImpl {
     /// or when gasless is not configured. Tokens can access this when withdrawing
     /// via `platform_coin()`.
     pub(crate) tron_gasless_provider: Option<ResolvedTronGaslessProvider>,
+    /// Token-level TRON GasFree configuration resolved at activation time.
+    pub(crate) tron_gasless_token_config: Option<ResolvedTronGaslessTokenConfig>,
     /// This spawner is used to spawn coin's related futures that should be aborted on coin deactivation
     /// and on [`MmArc::stop`].
     pub abortable_system: AbortableQueue,
@@ -7258,6 +7260,7 @@ pub async fn eth_coin_from_conf_and_request(
         gas_limit_v2,
         estimate_gas_mult,
         tron_gasless_provider: None,
+        tron_gasless_token_config: None,
         abortable_system,
     };
 
@@ -8263,6 +8266,7 @@ impl EthCoin {
             gas_limit_v2: EthGasLimitV2::default(),
             estimate_gas_mult: None,
             tron_gasless_provider: self.tron_gasless_provider.clone(),
+            tron_gasless_token_config: self.tron_gasless_token_config.clone(),
             abortable_system: self.abortable_system.create_subsystem().unwrap(),
         };
         EthCoin(Arc::new(coin))

mm2src/coins/eth/eth_withdraw.rs

@@ -2,9 +2,14 @@ use super::{
     u256_from_big_decimal, u256_to_big_decimal, ChainSpec, ChainTaggedAddress, EthCoinType, EthDerivationMethod,
     EthPrivKeyPolicy, Public, WithdrawError, WithdrawRequest, WithdrawResult, ERC20_CONTRACT, H256,
 };
+use crate::eth::tron::gasfree::withdraw::{
+    is_standard_tron_withdraw_unavailable, maybe_build_tron_gasless_withdraw, validate_non_tron_gasless_request,
+    TronGaslessMode,
+};
+use crate::eth::tron::gasfree::GaslessWithdrawError;
 use crate::eth::tron::sign::sign_tron_transaction;
 use crate::eth::tron::withdraw::{
-    build_tron_trc20_withdraw, build_tron_trx_withdraw, validate_tron_fee_policy, TronWithdrawContext,
+    build_standard_tron_withdraw, validate_tron_fee_policy, StandardTronWithdrawParams, TronWithdrawContext,
 };
 use crate::eth::tron::TronAddress;
 use crate::eth::wallet_connect::WcEthTxParams;
@@ -28,13 +33,15 @@ use crypto::hw_rpc_task::HwRpcTaskAwaitingStatus;
 use crypto::trezor::trezor_rpc_task::{TrezorRequestStatuses, TrezorRpcTaskProcessor};
 use crypto::{CryptoCtx, HwRpcError};
 use ethabi::Token;
+use ethereum_types::U256;
 use futures::compat::Future01CompatExt;
 use kdf_walletconnect::{WalletConnectCtx, WalletConnectOps};
 use mm2_core::mm_ctx::MmArc;
 use mm2_err_handle::map_mm_error::MapMmError;
 use mm2_err_handle::mm_error::MmResult;
 use mm2_err_handle::prelude::{MapToMmResult, MmError, MmResultExt, OrMmError};
 use prost::Message;
+use std::convert::TryFrom;
 use std::ops::Deref;
 use std::sync::Arc;
 #[cfg(target_arch = "wasm32")]
@@ -67,6 +74,12 @@ where
     #[allow(clippy::result_large_err)]
     fn on_finishing(&self) -> Result<(), MmError<WithdrawError>>;
 
+    #[allow(clippy::result_large_err)]
+    fn on_fetching_gasless_quote(&self) -> Result<(), MmError<WithdrawError>>;
+
+    #[allow(clippy::result_large_err)]
+    fn on_signing_gasless_authorization(&self) -> Result<(), MmError<WithdrawError>>;
+
     /// Signs the transaction with a Trezor hardware wallet.
     async fn sign_tx_with_trezor(
         &self,
@@ -84,7 +97,7 @@ where
         from_tagged: &ChainTaggedAddress,
         to_tagged: &ChainTaggedAddress,
         tx: TransactionData,
-        amount: ethabi::ethereum_types::U256,
+        amount: U256,
         total_fee: &BigDecimal,
         fee_details: TxFeeDetails,
     ) -> WithdrawResult {
@@ -286,6 +299,7 @@ where
                 "Memo is not yet supported for TRON withdraw (TRON charges 1 TRX burn fee for memo)".to_owned(),
             ));
         }
+        let gasless_mode = TronGaslessMode::try_from(req)?;
 
         // 2. Validate key policy (only Iguana/HDWallet supported for TRON MVP)
         match coin.priv_key_policy {
@@ -314,26 +328,39 @@ where
             .tron_rpc()
             .ok_or_else(|| WithdrawError::InternalError("TRON RPC client is not initialized".to_owned()))?;
 
-        let my_balance = coin.address_balance(from_tagged).compat().await.map_mm_err()?;
-        let my_balance_dec = u256_to_big_decimal(my_balance, coin.decimals).map_mm_err()?;
+        let trc20_contract = match &coin.coin_type {
+            EthCoinType::Eth => None,
+            EthCoinType::Erc20 { token_addr, .. } => Some(TronAddress::from(*token_addr)),
+            EthCoinType::Nft { .. } => {
+                return MmError::err(WithdrawError::ProtocolNotSupported(
+                    "NFT withdraw is not supported for TRON".to_owned(),
+                ))
+            },
+        };
 
-        if req.max && my_balance.is_zero() {
-            return MmError::err(WithdrawError::ZeroBalanceToWithdrawMax);
+        if gasless_mode == TronGaslessMode::Gasless {
+            let Some(contract_tron) = trc20_contract else {
+                return MmError::err(WithdrawError::Gasless(GaslessWithdrawError::Unavailable));
+            };
+
+            if let Some(details) =
+                maybe_build_tron_gasless_withdraw(self, tron, &from_tagged, &to_tagged, contract_tron, gasless_mode)
+                    .await?
+            {
+                return Ok(details);
+            }
         }
 
+        let my_balance = coin.address_balance(from_tagged).compat().await.map_mm_err()?;
+        let my_balance_dec = u256_to_big_decimal(my_balance, coin.decimals).map_mm_err()?;
+
         let amount_base_units = if req.max {
+            if my_balance.is_zero() {
+                return MmError::err(WithdrawError::ZeroBalanceToWithdrawMax);
+            }
             my_balance
         } else {
-            let amount = u256_from_big_decimal(&req.amount, coin.decimals).map_mm_err()?;
-            if amount > my_balance {
-                let required_dec = u256_to_big_decimal(amount, coin.decimals).map_mm_err()?;
-                return MmError::err(WithdrawError::NotSufficientBalance {
-                    coin: ticker.to_owned(),
-                    available: my_balance_dec,
-                    required: required_dec,
-                });
-            }
-            amount
+            u256_from_big_decimal(&req.amount, coin.decimals).map_mm_err()?
         };
 
         // 4. Convert addresses to TRON format
@@ -347,7 +374,7 @@ where
         let resources = tron.get_account_resource(&from_tron).await.map_mm_err()?;
         let prices = tron.get_chain_prices().await.map_mm_err()?;
 
-        // 7. Build tx, estimate fees — branching on coin type
+        // 7. Build tx and estimate fees.
         let withdraw_ctx = TronWithdrawContext {
             from: &from_tron,
             to: &to_tron,
@@ -357,24 +384,42 @@ where
             fee_coin: ticker,
             expiration_seconds: req.expiration_seconds,
         };
-        let (raw, tron_fee_details, final_amount) = match &coin.coin_type {
-            EthCoinType::Eth => {
-                build_tron_trx_withdraw(&withdraw_ctx, amount_base_units, my_balance, &my_balance_dec, req.max)?
-            },
-            EthCoinType::Erc20 {
-                token_addr, platform, ..
-            } => {
-                let contract_tron = TronAddress::from(*token_addr);
-                let trc20_ctx = TronWithdrawContext {
-                    fee_coin: platform.as_str(),
-                    ..withdraw_ctx
+        let standard_tron_withdraw_params = StandardTronWithdrawParams {
+            coin_type: &coin.coin_type,
+            ticker,
+            decimals: coin.decimals,
+            balance: my_balance,
+            balance_dec: &my_balance_dec,
+            amount_base_units,
+            is_max: req.max,
+            ctx: &withdraw_ctx,
+            tron,
+        };
+
+        let (raw, tron_fee_details, final_amount) = match build_standard_tron_withdraw(standard_tron_withdraw_params)
+            .await
+        {
+            Ok(prepared) => prepared,
+            Err(standard_fee_route_err) => {
+                if gasless_mode != TronGaslessMode::Auto
+                    || req.max
+                    || !is_standard_tron_withdraw_unavailable(&standard_fee_route_err)
+                {
+                    return Err(standard_fee_route_err);
+                }
+
+                let Some(contract_tron) = trc20_contract else {
+                    return Err(standard_fee_route_err);
                 };
-                build_tron_trc20_withdraw(&trc20_ctx, tron, &contract_tron, amount_base_units).await?
-            },
-            EthCoinType::Nft { .. } => {
-                return MmError::err(WithdrawError::ProtocolNotSupported(
-                    "NFT withdraw is not supported for TRON".to_owned(),
-                ))
+
+                if let Some(details) =
+                    maybe_build_tron_gasless_withdraw(self, tron, &from_tagged, &to_tagged, contract_tron, gasless_mode)
+                        .await?
+                {
+                    return Ok(details);
+                }
+
+                return Err(standard_fee_route_err);
             },
         };
 
@@ -417,6 +462,8 @@ where
             return self.build_tron_withdraw(from_tagged, to_tagged).await;
         }
 
+        validate_non_tron_gasless_request(&req)?;
+
         // ── EVM withdraw: existing path (unchanged) ──
         let my_balance = coin.address_balance(from_tagged).compat().await.map_mm_err()?;
         let my_balance_dec = u256_to_big_decimal(my_balance, coin.decimals).map_mm_err()?;
@@ -603,6 +650,18 @@ impl EthWithdraw for InitEthWithdraw {
             .map_mm_err()
     }
 
+    fn on_fetching_gasless_quote(&self) -> Result<(), MmError<WithdrawError>> {
+        self.task_handle
+            .update_in_progress_status(WithdrawInProgressStatus::FetchingGaslessQuote)
+            .map_mm_err()
+    }
+
+    fn on_signing_gasless_authorization(&self) -> Result<(), MmError<WithdrawError>> {
+        self.task_handle
+            .update_in_progress_status(WithdrawInProgressStatus::SigningGaslessAuthorization)
+            .map_mm_err()
+    }
+
     async fn sign_tx_with_trezor(
         &self,
         derivation_path: &DerivationPath,
@@ -677,6 +736,14 @@ impl EthWithdraw for StandardEthWithdraw {
         Ok(())
     }
 
+    fn on_fetching_gasless_quote(&self) -> Result<(), MmError<WithdrawError>> {
+        Ok(())
+    }
+
+    fn on_signing_gasless_authorization(&self) -> Result<(), MmError<WithdrawError>> {
+        Ok(())
+    }
+
     async fn sign_tx_with_trezor(
         &self,
         _derivation_path: &DerivationPath,

mm2src/coins/eth/for_tests.rs

@@ -95,6 +95,7 @@ fn make_eth_coin(
         gas_limit_v2,
         estimate_gas_mult,
         tron_gasless_provider: None,
+        tron_gasless_token_config: None,
         abortable_system: AbortableQueue::default(),
     }))
 }

mm2src/coins/eth/tron/fee.rs

@@ -24,6 +24,7 @@ use serde::{Deserialize, Serialize};
 const RESULT_BYTES_OVERHEAD_PER_CONTRACT: u64 = 64;
 /// TRON signatures are 65 bytes (`r || s || v`), used here as estimation placeholder.
 const PLACEHOLDER_SIGNATURE_LEN: usize = 65;
+pub const TRON_GASFREE_PROVIDER_NAME: &str = "gasfree";
 
 /// Fee breakdown for a TRON transaction.
 ///
@@ -37,20 +38,32 @@ pub struct TronTxFeeDetails {
     pub bandwidth_fee: BigDecimal,
     pub energy_fee: BigDecimal,
     pub total_fee: BigDecimal,
-    /// TODO(Commit 9): populated by `build_tron_withdraw` when the gasless branch is taken. Check if it's better to have 2 variants while backward compatible
-    #[serde(default, skip_serializing_if = "Option::is_none")]
-    pub gasless: Option<TronGaslessFeeMeta>,
 }
 
-/// Gasless provider fee metadata for TRC20 withdrawals routed through GasFree.
+/// Fee rail used for TRON gasless fee metadata.
+#[derive(Clone, Copy, Debug, Deserialize, Eq, PartialEq, Serialize)]
+#[serde(rename_all = "snake_case")]
+pub enum TronGaslessFeeMethod {
+    /// Provider-sponsored TRC20 transfer authorized through GasFree.
+    Gasless,
+}
+
+/// Fee details for TRC20 withdrawals routed through GasFree.
+///
+/// Distinct variant from [`TronTxFeeDetails`] because the user pays the provider
+/// fee in the token itself (no TRX bandwidth/energy) and signs an off-chain
+/// authorization rather than broadcasting on-chain.
 #[derive(Clone, Debug, Deserialize, PartialEq, Serialize)]
-pub struct TronGaslessFeeMeta {
-    pub fee_method: String,
-    pub provider: String,
+pub struct TronGaslessFeeDetails {
+    pub coin: String,
+    pub fee_method: TronGaslessFeeMethod,
+    pub provider_name: String,
     pub gasfree_address: String,
     pub transfer_fee: BigDecimal,
     pub activation_fee: BigDecimal,
     pub total_token_fee: BigDecimal,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub signed_max_fee: Option<BigDecimal>,
     pub trace_id: Option<String>,
 }
 
@@ -192,7 +205,6 @@ fn estimate_fee_details(
         bandwidth_fee: sun_to_trx_decimal(bandwidth_fee_sun),
         energy_fee: sun_to_trx_decimal(energy_fee_sun),
         total_fee: sun_to_trx_decimal(total_fee_sun),
-        gasless: None,
     }
 }
 

mm2src/coins/eth/tron/gasfree/config.rs

@@ -1,6 +1,7 @@
 use super::client::TronGasfreeClient;
 use super::error::TronGaslessConfigError;
 use crate::eth::tron::{Network, TronAddress};
+use ethereum_types::U256;
 use serde::Deserialize;
 use std::str::FromStr;
 use std::sync::Arc;
@@ -59,8 +60,15 @@ impl TronGaslessProviderConfig {
     }
 }
 
+/// Token-level GasFree settings resolved at activation time for TRON TRC20 assets.
+#[derive(Clone, Debug, PartialEq)]
+pub struct ResolvedTronGaslessTokenConfig {
+    /// Maximum provider fee allowed for transfers, converted at activation to token base units.
+    pub transfer_max_fee_token_base_units: Option<U256>,
+}
+
 /// Fully-validated GasFree provider state that can be stored on coin context.
-/// Redult of [`resolve_tron_gasless_provider`](super::resolve_tron_gasless_provider).
+/// Result of [`resolve_tron_gasless_provider`](super::resolve_tron_gasless_provider).
 #[derive(Clone)]
 pub struct ResolvedTronGaslessProvider {
     raw: TronGaslessProviderConfig,

mm2src/coins/eth/tron/gasfree/error.rs

@@ -1,3 +1,4 @@
+use crate::eth::{format_remote_error, Web3RpcError};
 use common::HttpStatusCode;
 use derive_more::Display;
 use http::StatusCode;
@@ -108,3 +109,19 @@ impl From<SlurpError> for TronGasfreeError {
         }
     }
 }
+
+impl From<Web3RpcError> for TronGasfreeError {
+    fn from(err: Web3RpcError) -> Self {
+        match err {
+            Web3RpcError::Transport(message) => TronGasfreeError::Transport(message),
+            Web3RpcError::Timeout(message) => TronGasfreeError::Timeout(message),
+            Web3RpcError::BadResponse(message) | Web3RpcError::InvalidResponse(message) => {
+                TronGasfreeError::InvalidResponse(message)
+            },
+            Web3RpcError::RemoteError { code, message } => {
+                TronGasfreeError::InvalidResponse(format_remote_error(code, message))
+            },
+            other => TronGasfreeError::InvalidResponse(other.to_string()),
+        }
+    }
+}