feat: refund a portion of remaining unused tokens to user (#3734)

* add new field to cctx structure to track user gas burned

* add unit tests

* add doc

* add unit test for migration

* add check for pre upgrade cctxs

* add older logic for handling cctxs created before upgrade

* remove LegacyChainParams

* add unit test for refund gas fee

* remove old migration

* add temp note for PR review

* fix typo

* fix typo

* generate files

* add missing test case

* add missing test case

* refactor based on comments

* update EtherWithdrawRestricted test

* update EtherWithdrawRestricted test

* update EtherWithdrawRestricted test

* enable all tests

* update module version for observer migration

* generated docs

* generated docs

* remove deprecated comments

* use older chainparams for upgrade tests

* use older chainparams for upgrade tests

* changes based on comments 1

* add addition param to CallZRC20Deposit

* update comments for legacy cctx and refactor unit tests to use the parent function ManageUnusedGasFee

* adjust non zevm chain test cases

* fix lint errors

* fix comments and rebase develop

* add statement to  ErrParamsStabilityPoolPercentage

* Update x/crosschain/keeper/msg_server_vote_outbound.go

Co-authored-by: Lucas Bertrand <lucas.bertrand.22@gmail.com>

* fix comments 3

* rebase develop 2

* rebase develop 2

* update admin test

---------

Co-authored-by: Lucas Bertrand <lucas.bertrand.22@gmail.com>

Author: kingpinXD

Makefile

@@ -394,7 +394,7 @@ start-upgrade-test-light: zetanode-upgrade
 start-upgrade-test-admin: zetanode-upgrade
 	@echo "--> Starting admin upgrade test"
 	export LOCALNET_MODE=upgrade && \
-	export UPGRADE_HEIGHT=90 && \
+	export UPGRADE_HEIGHT=60 && \
 	export USE_ZETAE2E_ANTE=true && \
 	export E2E_ARGS="${E2E_ARGS} --skip-regular --test-admin" && \
 	cd contrib/localnet/ && $(DOCKER_COMPOSE) --profile upgrade -f docker-compose-upgrade.yml up -d

changelog.md

@@ -18,6 +18,7 @@ by calling `updateAdditionalActionFee` admin function.
 * [4157](https://github.com/zeta-chain/node/pull/4157) - multiple evm calls in single tx
 * [4211](https://github.com/zeta-chain/node/pull/4211) - provide error information in cctx when Bitcoin deposit fail
 * [4218](https://github.com/zeta-chain/node/pull/4218) - enable NoAssetCall from Bitcoin chain
+* [3834](https://github.com/zeta-chain/node/pull/3734) - refund a portion of remaining unused tokens to user
 
 ### Refactor
 

cmd/zetae2e/local/evm.go

@@ -102,11 +102,11 @@ func startEVMTests(eg *errgroup.Group, conf config.Config, deployerRunner *runne
 		evmTestRoutine(conf, "zeta", conf.AdditionalAccounts.UserZeta, color.FgRed, deployerRunner, verbose,
 			e2etests.TestZetaDepositName,
 			e2etests.TestETHDepositName,
-			//e2etests.TestZetaDepositAndCallName,
-			//e2etests.TestZetaDepositAndCallRevertName,
-			//e2etests.TestZetaDepositRevertAndAbortName,
-			//e2etests.TestZetaDepositAndCallRevertWithCallName,
-			//e2etests.TestZetaDepositAndCallNoMessageName,
+			e2etests.TestZetaDepositAndCallName,
+			e2etests.TestZetaDepositAndCallRevertName,
+			e2etests.TestZetaDepositRevertAndAbortName,
+			e2etests.TestZetaDepositAndCallRevertWithCallName,
+			e2etests.TestZetaDepositAndCallNoMessageName,
 			e2etests.TestZetaWithdrawName,
 			e2etests.TestZetaWithdrawAndCallName,
 			e2etests.TestZetaWithdrawAndCallRevertName,

cmd/zetae2e/local/local.go

@@ -295,7 +295,7 @@ func localE2ETest(cmd *cobra.Command, _ []string) {
 		deployerRunner.SetupZRC20(zrc20Deployment)
 
 		// Update the chain params to contains protocol contract addresses
-		deployerRunner.UpdateProtocolContractsInChainParams(testLegacy)
+		deployerRunner.UpdateEVMChainParams(testLegacy)
 
 		if shouldSetupTON {
 			deployerRunner.SetupTON(
@@ -314,7 +314,10 @@ func localE2ETest(cmd *cobra.Command, _ []string) {
 		deployerRunner.Logger.Print("Running post-upgrade setup for %s", runner.V36Version)
 		err = OverwriteAccountData(cmd, &conf)
 		require.NoError(deployerRunner, err, "Failed to override account data from the config file")
-		deployerRunner.RunSetup(testLegacy)
+		deployerRunner.RunSetup()
+		if testAdmin {
+			deployerRunner.UpdateEVMChainParams(false)
+		}
 	})
 
 	// if a config output is specified, write the config

docs/openapi/openapi.swagger.yaml

@@ -54444,6 +54444,9 @@ definitions:
       confirmationMode:
         $ref: '#/definitions/zetachain.zetacore.crosschain.ConfirmationMode'
         title: confirmation mode used for the outbound
+      userGasFeePaid:
+        type: string
+        description: This field tracks the original gas fee paid by the user.
   zetachain.zetacore.crosschain.OutboundTracker:
     type: object
     properties:
@@ -55141,6 +55144,12 @@ definitions:
         description: |-
           Skip actions that require scanning the contents of each block.
           The main thing this disables is transfers directly to the TSS address.
+      stabilityPoolPercentage:
+        type: string
+        format: uint64
+        description: |-
+          Percentage of unused tokens for outbounds that are are sent to the
+          stability pool. The value should be between 0 and 100.
   zetachain.zetacore.observer.ChainParamsList:
     type: object
     properties:

docs/zetacore/gas_fee.md

@@ -0,0 +1,117 @@
+# ZetaChain Gas Fee Documentation
+
+## Overview
+
+Gas fees in ZetaChain refer to the amount paid by users to execute transactions on connected chains. These fees **do not** include any gas payments that users make on the source chain to initiate transactions.
+
+## Key Concepts
+
+- **Deposit**: Transfer tokens from a connected chain to ZetaChain
+- **Withdraw**: Transfer tokens from ZetaChain to a connected chain
+- **Coin Types**: Different token types used for transactions (Gas, ERC20, ZETA, No Asset)
+- **Revert**: When a transaction fails and needs to be reverted
+
+## V2 Protocol Flows
+
+### Deposit Transactions
+
+Deposits transfer tokens from connected chains to ZetaChain.
+
+- Gas Fee is always in GAS ZRC20. If the amount is in a different ERC20, it's swapped to buy Gas tokens
+
+| Transaction Type | GAS FEE Deposit | GAS FEE Revert | Notes |
+|------------------|-----------------|----------------|-------|
+| Deposit | Free | User Pays based on cointype | Revert fees paid using the GAS ZRC20 on source chain |
+| DepositAndCall | Free | User Pays based on cointype | Revert fees paid using the GAS ZRC20 on source chain |
+| Call | Free | Revert Not supported | Revert fees paid using the GAS ZRC20 on source chain |
+
+#### Gas Fee Payment by Coin Type
+
+1. **CoinType ERC20**
+   - User is using ERC20/ZRC20 tokens
+   - `Protocol` calculates expected gas cost on connected chain, using `Current Gas Price` * `Revert Gas Limit` + Protocol Flat Fee
+   - ERC20 tokens are swapped to buy gas ZRC20 tokens
+   - Gas ZRC20 tokens are burned to pay for the gas fee
+
+2. **CoinType Gas**
+   - User paid in the native gas token on a connected chain
+   - `Protocol` calculates expected gas cost on connected chain, using `Current Gas Price` * `Revert Gas Limit` + Protocol Flat Fee
+   - Gas token can be directly burned to pay for the gas fee
+
+3. **NoAssetCall**
+   - No revert processing in this case, the cross-chain transaction is aborted
+
+### Withdraw Transactions
+
+Withdrawals transfer tokens from ZetaChain to connected chains.
+
+| Transaction Type | GAS FEE Withdraw | GAS FEE Revert | Notes |
+|------------------|-----------------|----------------|-------|
+| Withdraw | User Pays based on withdraw type | Free call to OnRevert using fixed GasLimit | Initiated through Gateway smart contract |
+| WithdrawAndCall | User Pays based on withdraw type | Free call to OnRevert using fixed GasLimit | Initiated through Gateway smart contract |
+| Call | User Pays based on withdraw type | Free call to OnRevert using fixed GasLimit | Initiated through Gateway smart contract |
+
+- Withdrawals are initiated by users through zEVM smart contract calls
+- Fees are always paid in the GAS ZRC20 token for the target connected chain, this fees is paid separately by the user an is not deducted from the amount.However when the transaction reverts, the revert fee is deducted from the amount
+- CCTX type is either GAS or ERC20 depending on the token
+
+**Gas Fee Payment by withdraw type:**
+
+1. **Withdraw**
+   - `Gateway Smart contract` calculates expected gas cost on connected chain based on `gasPrice` * `ZRC20.GasLimit` + Protocol Flat Fee
+
+2. **WithdrawAndCall**
+   - `Gateway Smart contract` calculates expected gas cost on connected chain based on `gasPrice` * `CallOptions.GasLimit` + Protocol Flat Fee
+
+3. **Call**
+   - `Gateway Smart contract` calculates expected gas cost on connected chain based on `gasPrice` * `ZRC20.GasLimit` + Protocol Flat Fee
+
+## V1 Protocol Flows
+
+- V1 flows for ERC20/ZRC20 and GAS tokens have already been deprecated
+- V1 flows for ZETA token deposits and withdrawals are still supported but are planned to be deprecated soon.
+
+### Deposit Transactions
+
+| Transaction Type | GAS FEE Deposit | GAS FEE Revert | Notes |
+|------------------|-----------------|----------------|-------|
+| Deposit zEVM | Free | User pays based on coin type | Gas fee for revert based on cointype |
+| Deposit Connected Chain (Msg-Passing) | User pays based on coin type | User pays based on coin type | Fees in connected chain's gas token |
+
+#### Gas Fee Payment by Coin Type
+
+1. **CoinType Zeta**
+   - User is using ERC20/ZRC20 "Zeta Token"
+   - `Protocol` calculates expected gas cost on connected chain using `gasPrice * 2` * `CallOptions.GasLimit` + Protocol Flat Fee
+   - Zeta tokens are swapped to buy gas ZRC20 tokens
+   - Gas tokens are burned to pay for the gas fee
+   - **Important**: Gas price is multiplied by 2× when calculating the fee
+
+2. **CoinType ERC20**
+   - User is using ERC20/ZRC20 tokens
+   - `Protocol` calculates expected gas cost on connected chain using `gasPrice` * `GasZRC20.GasLimit` + Protocol Flat Fee
+   - ERC20 tokens are swapped to buy gas ZRC20 tokens
+   - Gas tokens are burned to pay for the gas fee
+
+3. **CoinType Gas**
+   - User paid in native gas token on connected chain
+   - `Protocol` calculates expected gas cost on connected chain using `gasPrice` * `GasZRC20.GasLimit` + Protocol Flat Fee
+   - Gas token can be directly burned to pay for fee
+
+### Withdraw Transactions
+
+| Transaction Type | GAS FEE Deposit | GAS FEE Revert | Notes |
+|------------------|-----------------|----------------|-------|
+| ZRC20 Withdraw | User pays | Not supported | Uses same mechanism as V2 withdrawals |
+| ZETA Sent | User pays | Free call to OnRevert using fixed GasLimit | Total Zeta (value + gas) is burned |
+
+#### Details by Withdraw Type
+
+1. **ZRC20 Withdraw**
+   - Uses the same mechanism as V2 withdrawals but initiated through ZRC20 contract
+
+2. **ZETA Sent**
+   - Total Zeta amount (value + gas) is burned
+   - A portion is minted to swap and pay for gas in outbound chain
+   - `Protocol` calculates expected gas cost on a connected chain using `gasPrice * 2` * `CallOptions.GasLimit` + Protocol Flat Fee
+   - Value portion is unlocked in connected chain after successful outbound transaction

docs/zetacore/managment_for_unused_gas_fee.md

@@ -0,0 +1,69 @@
+# Management for Unused Gas Fee
+
+## Overview
+
+This document explains how gas fees are managed when processing outbound transactions on connected chains, particularly focusing on how differences between estimated and actual gas usage are handled.
+The Gas fee is always paid in the Gas ZRC20 token of the connected chain ,irrespective of coin type.
+
+## Gas Fee Scenarios
+
+When processing outbound transactions, there are two possible scenarios regarding gas fees:
+
+1. **User Overpays** (Common)
+    - Users often overpay gas fees to ensure transactions are processed
+    - EVM chains automatically refund unused gas to the caller (TSS address)
+    - This creates an opportunity to return a portion of these funds to users
+
+2. **User Underpays**
+    - Gas prices may increase after transaction submission
+    - In these cases, the stability pool covers the difference
+    - No refund mechanism applies in underpayment scenarios
+
+## Refund Mechanism for Overpayments
+
+For overpayment scenarios, we implement the following refund logic:
+
+### Fee Tracking
+
+- We track the initial gas fee paid by the user when initiating the transaction. This does not include the Protocol Fee.
+- When an outbound transaction completes (regardless of status), we calculate the actual fee used:
+  ```
+  actualFee = receipt.GasUsed * transaction.GasPrice()
+  ```
+
+### Difference in Fee Calculation
+
+- The difference in fee is calculated as:
+  ```
+  totalRemainingFees = userGasFeePaid - actualFee
+  ```
+- We then take 95% of this amount for further calculations:
+  ```
+  remainingFees = 95% of totalRemainingFees
+  ```
+- We intentionally use only 95% of the unused fee to avoid any potential over-minting:
+    - The 5% of tokens that are not minted back are retained by the TSS address
+    - This creates a safety buffer since we burn the total amount of tokens when initiating the transaction, which creates a deficit
+
+### Fee Distribution
+
+The remaining fees are distributed as follows:
+
+1. **Stability Pool Allocation**
+    - For non-EVM chains: 100% of this amount goes to the stability pool
+    - For EVM chains: A configurable percentage (defined in the chain parameters) goes to the stability pool
+
+2. **User Refund**
+    - For EVM chains: The remaining amount after stability pool allocation is refunded to the user
+    - Refunds are provided as ZRC20 gas tokens of the connected chain
+
+3. **Fallback**
+    - If refunding fails for any reason, all remaining fees are allocated to the stability pool
+
+## Implementation Details
+
+- The refund is always in the form of gas tokens from the connected chain
+- The stability pool funded is always associated with the gas token of the outbound chain
+- The system requires chain parameters to be properly configured
+- The mechanism handles various edge cases (invalid addresses, zero amounts, etc.).
+- We refund the amount to the sender irrespective of whether it is a user or a contract. The contract should implement a mechanism to handle the refund.

e2e/e2etests/e2etests.go

@@ -1877,7 +1877,7 @@ var AllE2ETests = []runner.E2ETest{
 			{Description: "amount in wei", DefaultValue: "100000"},
 		},
 		TestEtherWithdrawRestricted,
-		runner.WithMinimumVersion("v30.0.0"),
+		runner.WithMinimumVersion("v37.0.0"),
 	),
 	runner.NewE2ETest(
 		TestLegacyEtherDepositAndCallRefundName,

e2e/e2etests/test_eth_withdraw_restricted_address.go

@@ -3,14 +3,17 @@ package e2etests
 import (
 	"math/big"
 
+	"cosmossdk.io/math"
 	"github.com/ethereum/go-ethereum/accounts/abi/bind"
 	ethcommon "github.com/ethereum/go-ethereum/common"
 	"github.com/stretchr/testify/require"
 	"github.com/zeta-chain/protocol-contracts/pkg/gatewayzevm.sol"
 
 	"github.com/zeta-chain/node/e2e/runner"
 	"github.com/zeta-chain/node/e2e/utils"
+	crosschainkeeper "github.com/zeta-chain/node/x/crosschain/keeper"
 	crosschaintypes "github.com/zeta-chain/node/x/crosschain/types"
+	observertypes "github.com/zeta-chain/node/x/observer/types"
 )
 
 // TestEtherWithdrawRestricted tests the withdrawal to a restricted receiver address
@@ -71,5 +74,39 @@ func TestEtherWithdrawRestricted(r *runner.E2ERunner, args []string) {
 	// revert address should receive the amount
 	revertBalanceAfter, err := r.ETHZRC20.BalanceOf(&bind.CallOpts{}, revertAddress)
 	require.NoError(r, err)
-	require.EqualValues(r, new(big.Int).Add(revertBalanceBefore, amount), revertBalanceAfter)
+
+	userBalanceAfterUint := math.NewUintFromBigInt(revertBalanceAfter)
+	userBalanceBeforeUint := math.NewUintFromBigInt(revertBalanceBefore)
+	totalRevertAmount := getTotalRevertedAmount(r, cctx)
+
+	require.EqualValues(r, userBalanceAfterUint.Sub(totalRevertAmount), userBalanceBeforeUint)
+}
+
+func getTotalRevertedAmount(r *runner.E2ERunner, cctx *crosschaintypes.CrossChainTx) math.Uint {
+	outboundParams := cctx.OutboundParams[0]
+	outboundTxGasUsed := math.NewUint(outboundParams.GasUsed)
+	outboundTxFinalGasPrice := math.NewUintFromBigInt(outboundParams.EffectiveGasPrice.BigInt())
+	outboundTxFeePaid := outboundTxGasUsed.Mul(outboundTxFinalGasPrice)
+	userGasFeePaid := outboundParams.UserGasFeePaid
+	totalRemainingFees := userGasFeePaid.Sub(outboundTxFeePaid)
+
+	remainingFees := crosschainkeeper.PercentOf(totalRemainingFees, crosschaintypes.UsableRemainingFeesPercentage)
+	if remainingFees.LTE(math.ZeroUint()) {
+		return math.ZeroUint()
+	}
+
+	evmChainID, err := r.EVMClient.ChainID(r.Ctx)
+	require.NoError(r, err)
+
+	chainParams, err := r.ObserverClient.GetChainParamsForChain(
+		r.Ctx,
+		&observertypes.QueryGetChainParamsForChainRequest{
+			ChainId: evmChainID.Int64(),
+		},
+	)
+	require.NoError(r, err)
+
+	stabilityPoolAmount := crosschainkeeper.PercentOf(remainingFees, chainParams.ChainParams.StabilityPoolPercentage)
+	refundAmount := remainingFees.Sub(stabilityPoolAmount)
+	return cctx.InboundParams.Amount.Add(refundAmount)
 }

e2e/runner/setup_zetacore_configuration.go

@@ -13,10 +13,10 @@ import (
 	observertypes "github.com/zeta-chain/node/x/observer/types"
 )
 
-// UpdateProtocolContractsInChainParams update the erc20 custody contract and gateway address in the chain params
+// UpdateEVMChainParams update the erc20 custody contract and gateway address in the chain params
 // TODO: should be used for all protocol contracts including the ZETA connector
 // https://github.com/zeta-chain/node/issues/3257
-func (r *E2ERunner) UpdateProtocolContractsInChainParams(testLegacy bool) {
+func (r *E2ERunner) UpdateEVMChainParams(testLegacy bool) {
 	res, err := r.ObserverClient.GetChainParams(r.Ctx, &observertypes.QueryGetChainParamsRequest{})
 	require.NoError(r, err)