@exodus/ethereum-api 8.23.2 → 8.24.1

package/CHANGELOG.md

@@ -3,6 +3,26 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+## [8.24.1](https://github.com/ExodusMovement/assets/compare/@exodus/ethereum-api@8.24.0...@exodus/ethereum-api@8.24.1) (2024-12-19)
+
+
+### License
+
+
+* license: re-license under MIT license (#4694)
+
+
+
+## [8.24.0](https://github.com/ExodusMovement/assets/compare/@exodus/ethereum-api@8.23.2...@exodus/ethereum-api@8.24.0) (2024-12-17)
+
+
+### Features
+
+
+* feat: evm staking send simplification (#4681)
+
+
+
 ## [8.23.2](https://github.com/ExodusMovement/assets/compare/@exodus/ethereum-api@8.23.1...@exodus/ethereum-api@8.23.2) (2024-12-17)
 
 

package/LICENSE

@@ -0,0 +1,7 @@
+Copyright (c) 2024 Exodus Movement, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -1,3 +1,121 @@
 # @exodus/ethereum-api
 
-Transaction monitors, fee monitors, RPC with the blockchain node, and other networking code for Ethereum and EVM-based blockchains. See [Asset Packages](../../docs/asset-packages.md) for more detail on this package's role.
+Transaction monitors, fee monitors, RPC with the blockchain node, and other networking code for Ethereum and EVM-based blockchains. See [Asset Packages](../../docs/asset-packages.md) for more detail on this package`s role.
+
+## Fees
+
+This section explains how fees currently work in Exodus and provides guidance on troubleshooting and tuning them via remote configuration. It reverse-engineers the existing unified implementation. The document aims to help readers understand the fee mechanism and suggest ways to improve it further.
+
+### Gas Price
+
+Excluding custom fees, the result `gasPrice * gasPriceMultiplier` is used to resolve the transaction's gas price (legacy) and max gas price (EIP-1559).
+
+The `gasPrice` value is, in preference order, loaded from:
+
+1. Remote config
+2. The node via the fee data monitor
+3. The default configuration.
+
+Using remote config is never recommended, as manually updating this value won't keep up with network activity.
+
+Fee and remote monitors are executed as soon as the wallet starts. The default fee data fields defined in code would be overridden (if they are set) before the user can interact with the wallet.
+
+To tune the fee resolution, we can:
+
+- Increase or decrease `gasPriceMultiplier` via remote config. For example, `1.2` would bump the current network gas price by 20%.
+- Set a `min` value via remote config. Gas price will never be lower than this value.
+- Set a `max` value via remote config. Gas price will never be higher than this value.
+
+If the `gasPrice` returned by the node is not accurate or lower than the network's, the transaction may get stuck in pending status or may not be broadcast to the blockchain.
+
+This is an undesirable situation:
+
+- We could increase the nonce for the second transaction, but if the first one drops, the second one will also fail, even if the fees of the second one are high enough.
+- If the wallet assumes the transaction was dropped and the nonce is reused, the network will interpret this unrelated second transaction as attempting to replace the first one (transaction replacement underprice error).
+- The user submitting a second transaction to "retry" could be dangerous. Both transactions might get mined, causing the user to execute the swap twice instead of once.
+
+One escape valve could be to update the `min`, `max`, or `gasPriceMultiplier` via remote config. This should be a temporary patch that needs to be rolled back once the node's gas price stabilizes.
+
+### Base Gas Price
+
+The base gas price (or base fee) is the minimum amount of gas required to be paid per unit of gas to include a transaction in a block.
+
+It can be found in `feeData.baseFeePerGas`. The fee monitor keeps it up to date by monitoring the latest block's information. It could be tuned by remote config, but this is not recommended.
+
+The `feeData.baseFeePerGas` is only used when showing an "estimated fee" in the UI and not when sending a transaction.
+
+One possible improvement is to define the max gas price based on the base gas price rather than the network's current gas price.
+
+### Gas Limit
+
+The `gasLimit` refers to the maximum amount of gas a transaction or block is allowed to consume during its execution.
+Most EVMs assume 21,000 when transferring the main asset. Some EVMs, like Mantle, Arbitrum One, and Arbitrum Nova, use a different gas limit. These gas limits need to be estimated, similar to when performing smart contract calls.
+
+For smart contract calls, like sending or swapping, the wallet estimates a gas limit based on the contract, the sender, the receiver, the amounts, etc. The gas limit is then bumped by a 20% `extraPercentage` as a safety net.
+
+If the gas limit estimation fails, the code may fall back to a high default value defined per asset (`asset.gasLimit`).
+
+Currently, there is no way to tune the gas limit resolution via remote config, and "extra percentage" values are hardcoded in the code.
+
+Both the bumped `gasLimit` and the bumped `gasPrice` resolved when showing the fees are reused when sending.
+
+The higher the gas limit and the gas price, the higher the max network fee, even though not all that gas may be used. The higher the max network fee, the lower the user's available balance.
+
+### Additional L2 Fees
+
+L2 networks may have additional fees. Arbitrum One, Arbitrum Nova, and Mantle include the fees in the gas estimation (`forceGasLimitEstimation`). Base and Aptos need an additional fee estimation to get this extra fee (`estimateL1DataFee`).
+
+The L2 extra fee needs to be considered when showing the fee to the user, resolving the available balance, and creating the transaction. The fee may be implicit in the transaction.
+
+### Custom Fees
+
+Custom fees allow users to set a custom `gasPrice`. The wallet allows a range, as follows:
+
+- `recommended: gasPrice * gasPriceMultiplier`
+- `min: gasPrice * gasPriceMultiplier * gasPriceMinimumRate`
+- `max: gasPrice * gasPriceMultiplier * gasPriceMaximumRate`
+
+If the user picks the recommended value, the custom fee is not set, leaving the default fee behavior.
+Custom fees can be disabled by setting `rbfEnabled: false` via remote config. Currently, only Ethereum allows custom fees. Other EVMs could be included in the future.
+
+The wallet allows acceleration when custom fees are allowed (and vice versa).
+
+If the user picks a different custom fee in that range, the fee is calculated as `customFee * gasLimit`. `gasPriceMultiplier` is not applied to the custom gas price.
+
+A transaction created with a low custom fee may be stuck for a while, blocking future transactions, and it may create issues with the nonce, as explained above.
+
+Min and max values can be tuned by changing `gasPriceMinimumRate` and `gasPriceMaximumRate` via remote config.
+
+### TX formulas
+
+Table shows how the txs are create for both legacy and 1559 logic for major use case:
+
+|                    | Send some main                | Send all main                 | Send token/contract call      | Send main with custom fee | Send token/contract with custom fee | Accelerate                                                   |
+| ------------------ | ----------------------------- | ----------------------------- | ----------------------------- | ------------------------- | ----------------------------------- | ------------------------------------------------------------ |
+| Legacy Gas Price   | gasPrice \* gasPriceMultipler | gasPrice \* gasPriceMultipler | gasPrice \* gasPriceMultipler | customFee                 | customFee                           | max(current gasPrice,original tx gasPrice) \* BUMP_RATE 1.2  |
+| Legacy Gas Limit   | 21000                         | 21000                         | estimated + 20% extra         | 21000                     | estimated + 20% extra               | original tx gasLimit                                         |
+| -                  | -                             | -                             | -                             | -                         | -                                   | -                                                            |
+| 1559 Max gas Price | gasPrice \* gasPriceMultipler | gasPrice \* gasPriceMultipler | gasPrice \* gasPriceMultipler | customFee                 | customFee                           | max(current gasPrice, original tx gasPrice) \* BUMP_RATE 1.2 |
+| 1559 Tip gas Price | tipGasPrice                   | gasPrice \* gasPriceMultipler | tipGasPrice                   | customFee                 | tipGasPrice                         | orginal tx tipGasPrice \* BUMP_RATE 1.2                      |
+| 1559 Gas Limit     | 21000                         | 21000                         | estimated + 20% extra         | 21000                     | estimated + 20% extra               | original tx gasLimit                                         |
+
+### Fee Data Example
+
+This is the default fee data configuration for Ethereum. Other EVMs have different default fee data.
+
+All these values can be tuned via remote config, although it may not be recommended as they are also tuned by the fee monitors:
+
+- **`baseFeePerGas`:** `50 Gwei` – Reference value for the base gas price. It is quickly updated by the fee monitor.
+- **`gasPrice`:** `75 Gwei` – Reference value for the network gas price. It is quickly updated by the fee monitor.
+- **`tipGasPrice`:** `2 Gwei` – Controls the `maxPriorityFeePerGas` for all transactions when EIP-1559 is enabled.
+- **`eip1559Enabled`:** `true` – Enables or disables EIP-1559. A value of `false` means legacy fees and transactions.
+- **`rbfEnabled`:** `true` – Enables custom fees and acceleration. Currently, this is only available for Ethereum but can be expanded to other EVMs.
+- **`gasPriceMaximumRate`:** `1.3` – Controls the maximum value in the custom fee slider.
+- **`gasPriceMinimumRate`:** `0.5` – Controls the minimum value in the custom fee slider.
+- **`gasPriceMultiplier`:** `1` – Controls the `gasPrice` and `maxFeePerGas` of transactions, resolved as `current gas price * this multiplier`.
+- **`max`:** `250 Gwei` – Controls the maximum gas price value that can be set.
+- **`min`:** `1 Gwei` – Controls the minimum gas price value that can be set.
+- **`fuelThreshold`:** `0.025 ETH` – If the balance falls below this value and the user holds tokens, a low balance warning is displayed.
+- **`enableFeeDelegation`:** `false` – Not implemented.
+- **`origin`:** `75 Gwei` – Legacy; consider removing.
+- **`swapFee`:** `0.05 ETH` – Legacy; consider removing.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@exodus/ethereum-api",
-  "version": "8.23.2",
+  "version": "8.24.1",
   "description": "Transaction monitors, fee monitors, RPC with the blockchain node, and other networking code for Ethereum and EVM-based blockchains",
   "type": "module",
   "main": "src/index.js",
@@ -10,10 +10,10 @@
     "!src/**/__tests__"
   ],
   "author": "Exodus Movement, Inc.",
-  "license": "UNLICENSED",
+  "license": "MIT",
   "homepage": "https://github.com/ExodusMovement/assets/tree/master/ethereum/ethereum-api",
   "publishConfig": {
-    "access": "restricted"
+    "access": "public"
   },
   "scripts": {
     "test": "run -T exodus-test --jest",
@@ -28,7 +28,7 @@
     "@exodus/bip44-constants": "^195.0.0",
     "@exodus/crypto": "^1.0.0-rc.13",
     "@exodus/currency": "^6.0.1",
-    "@exodus/ethereum-lib": "^5.8.1",
+    "@exodus/ethereum-lib": "^5.8.2",
     "@exodus/ethereum-meta": "^2.1.5",
     "@exodus/ethereumholesky-meta": "^2.0.0",
     "@exodus/ethereumjs": "^1.0.0",
@@ -38,6 +38,7 @@
     "@exodus/solidity-contract": "^1.1.3",
     "@exodus/web3-ethereum-utils": "^3.27.1",
     "bn.js": "^5.2.1",
+    "delay": "^4.0.1",
     "events": "^1.1.1",
     "idna-uts46-hx": "^2.3.1",
     "lodash": "^4.17.15",
@@ -54,8 +55,7 @@
     "@exodus/ethereumgoerli-meta": "^2.0.0",
     "@exodus/ethereumsepolia-meta": "^2.0.0",
     "@exodus/fantommainnet-meta": "^2.0.0",
-    "@exodus/rootstock-meta": "^2.0.0",
-    "delay": "4.0.1"
+    "@exodus/rootstock-meta": "^2.0.0"
   },
   "bugs": {
     "url": "https://github.com/ExodusMovement/assets/issues?q=is%3Aissue+is%3Aopen+label%3Aethereum-api"
@@ -64,5 +64,5 @@
     "type": "git",
     "url": "git+https://github.com/ExodusMovement/assets.git"
   },
-  "gitHead": "2036bf64aa16ee26a864a4aa971b050fc4631104"
+  "gitHead": "9f590f5439d73cba02054d608fb3d5c62fbdcf34"
 }

package/src/staking/ethereum/service.js

@@ -3,6 +3,7 @@ import { isNumberUnit } from '@exodus/currency'
 import { getServer } from '../../exodus-eth-server/index.js'
 import { estimateGasLimit } from '../../gas-estimation.js'
 import { fromHexToBigInt } from '../../number-utils.js'
+import { createWatchTx as defaultCreateWatch } from '../../watch-tx.js'
 import { stakingProviderClientFactory } from '../staking-provider-client.js'
 import { EthereumStaking } from './api.js'
 
@@ -11,7 +12,7 @@ const extraGasLimit = 20_000 // extra gas Limit to prevent tx failing if somethi
 export function createEthereumStakingService({
   asset,
   assetClientInterface,
-  createAndBroadcastTX,
+  createWatchTx = defaultCreateWatch,
 }) {
   const staking = new EthereumStaking(asset)
   const stakingProvider = stakingProviderClientFactory()
@@ -33,7 +34,7 @@ export function createEthereumStakingService({
       amount,
     })
 
-    const { gasPrice, gasLimit, fee } = await estimateTxFee(delegatorAddress, to, amount, data)
+    const { gasPrice, gasLimit } = await estimateTxFee(delegatorAddress, to, amount, data)
 
     console.log(
       `delegator address ${delegatorAddress} staking ${amount.toDefaultString({
@@ -48,7 +49,6 @@ export function createEthereumStakingService({
       txData: data,
       gasPrice,
       gasLimit,
-      fee,
     })
 
     // Goerli is not supported
@@ -226,7 +226,7 @@ export function createEthereumStakingService({
     })
     if (withdrawRequest) {
       const { to, data } = withdrawRequest
-      const { gasPrice, gasLimit, fee } = await estimateTxFee(delegatorAddress, to, null, data)
+      const { gasPrice, gasLimit } = await estimateTxFee(delegatorAddress, to, null, data)
       return prepareAndSendTx({
         asset,
         walletAccount,
@@ -234,7 +234,6 @@ export function createEthereumStakingService({
         txData: data,
         gasPrice,
         gasLimit,
-        fee,
       })
     }
   }
@@ -314,7 +313,6 @@ export function createEthereumStakingService({
       txData: txInput,
       gasPrice,
       gasLimit,
-      fee,
       waitForConfirmation = false,
     } = Object.create(null)
   ) {
@@ -323,28 +321,27 @@ export function createEthereumStakingService({
       walletAccount,
       address: to,
       amount: amount || asset.currency.ZERO,
-      // unified tx-send param
       shouldLog: true,
-      txInput,
-      feeAmount: fee,
-      feeOpts: {
-        gasPrice,
-        gasLimit,
-      },
-      // mobile: tx-send parms
       options: {
         shouldLog: true,
         txInput,
         gasPrice,
         gasLimit,
-        feeAmount: fee,
       },
-      waitForConfirmation,
     }
 
-    console.log('sending staking tx:', sendTxArgs)
+    const { txId } = await asset.baseAsset.api.sendTx(sendTxArgs)
 
-    const { txId } = await createAndBroadcastTX(sendTxArgs)
+    const baseAsset = asset.baseAsset
+    if (waitForConfirmation) {
+      const getTxLog = (...args) => assetClientInterface.getTxLog(...args)
+      const watchTx = createWatchTx({
+        walletAccount,
+        getTxLog,
+        baseAsset,
+      })
+      await watchTx(txId)
+    }
 
     return txId
   }

package/src/staking/matic/service.js

@@ -3,10 +3,14 @@ import BN from 'bn.js'
 
 import { getServer } from '../../exodus-eth-server/index.js'
 import { estimateGasLimit } from '../../gas-estimation.js'
+import { createWatchTx as defaultCreateWatch } from '../../watch-tx.js'
 import { stakingProviderClientFactory } from '../staking-provider-client.js'
 import { MaticStakingApi } from './api.js'
 
-export function createPolygonStakingService({ assetClientInterface, createAndBroadcastTX }) {
+export function createPolygonStakingService({
+  assetClientInterface,
+  createWatchTx = defaultCreateWatch,
+}) {
   const stakingApi = new MaticStakingApi()
   const assetName = 'ethereum'
   const stakingProvider = stakingProviderClientFactory()
@@ -33,7 +37,7 @@ export function createPolygonStakingService({ assetClientInterface, createAndBro
     amount = amountToCurrency({ asset, amount })
 
     const txApproveData = await stakingApi.approveStakeManager(amount)
-    let { gasPrice, gasLimit, fee } = await estimateTxFee(
+    let { gasPrice, gasLimit } = await estimateTxFee(
       delegatorAddress,
       stakingApi.polygonContract.address,
       txApproveData
@@ -45,11 +49,10 @@ export function createPolygonStakingService({ assetClientInterface, createAndBro
       txData: txApproveData,
       gasPrice,
       gasLimit,
-      fee,
     })
 
     const txDelegateData = await stakingApi.delegate({ amount })
-    ;({ gasPrice, gasLimit, fee } = await estimateTxFee(
+    ;({ gasPrice, gasLimit } = await estimateTxFee(
       delegatorAddress,
       stakingApi.validatorShareContract.address,
       txDelegateData
@@ -61,7 +64,6 @@ export function createPolygonStakingService({ assetClientInterface, createAndBro
       txData: txDelegateData,
       gasPrice,
       gasLimit,
-      fee,
     })
 
     await stakingProvider.notifyStaking({
@@ -85,7 +87,7 @@ export function createPolygonStakingService({ assetClientInterface, createAndBro
     amount = amountToCurrency({ asset, amount })
 
     const txUndelegateData = await stakingApi.undelegate({ amount })
-    const { gasPrice, gasLimit, fee } = await estimateTxFee(
+    const { gasPrice, gasLimit } = await estimateTxFee(
       delegatorAddress.toLowerCase(),
       stakingApi.validatorShareContract.address,
       txUndelegateData
@@ -96,7 +98,6 @@ export function createPolygonStakingService({ assetClientInterface, createAndBro
       txData: txUndelegateData,
       gasPrice,
       gasLimit,
-      fee,
     })
   }
 
@@ -108,7 +109,7 @@ export function createPolygonStakingService({ assetClientInterface, createAndBro
     const delegatorAddress = address.toLowerCase()
 
     const txWithdrawRewardsData = await stakingApi.withdrawRewards()
-    const { gasPrice, gasLimit, fee } = await estimateTxFee(
+    const { gasPrice, gasLimit } = await estimateTxFee(
       delegatorAddress,
       stakingApi.validatorShareContract.address,
       txWithdrawRewardsData
@@ -119,7 +120,6 @@ export function createPolygonStakingService({ assetClientInterface, createAndBro
       txData: txWithdrawRewardsData,
       gasPrice,
       gasLimit,
-      fee,
     })
   }
 
@@ -267,37 +267,37 @@ export function createPolygonStakingService({ assetClientInterface, createAndBro
     txData: txInput,
     gasPrice,
     gasLimit,
-    fee,
     waitForConfirmation = false,
   } = {}) {
-    const { ethereum } = await assetClientInterface.getAssetsForNetwork({
+    const { ethereum: asset } = await assetClientInterface.getAssetsForNetwork({
       baseAssetName: 'ethereum',
     })
     const sendTxArgs = {
-      asset: ethereum,
+      asset,
       walletAccount,
       address: to,
-      amount: ethereum.currency.ZERO,
-      // unified tx-send param
-      shouldLog: true,
-      txInput,
-      feeAmount: fee,
-      feeOpts: {
-        gasPrice,
-        gasLimit,
-      },
-      // mobile: tx-send parms
+      amount: asset.currency.ZERO,
       options: {
         shouldLog: true,
         txInput,
         gasPrice,
         gasLimit,
-        feeAmount: fee,
       },
       waitForConfirmation,
     }
 
-    const { txId } = await createAndBroadcastTX(sendTxArgs)
+    const { txId } = await asset.baseAsset.api.sendTx(sendTxArgs)
+
+    const baseAsset = asset.baseAsset
+    if (waitForConfirmation) {
+      const getTxLog = (...args) => assetClientInterface.getTxLog(...args)
+      const watchTx = createWatchTx({
+        walletAccount,
+        getTxLog,
+        baseAsset,
+      })
+      await watchTx(txId)
+    }
 
     return txId
   }

package/src/watch-tx.js

@@ -0,0 +1,32 @@
+import delay from 'delay'
+import ms from 'ms'
+
+const WATCH_TX_DELAY = ms('5s')
+const WATCH_TX_TIMEOUT = ms('5m')
+
+// this could go to asset-lib
+export const createWatchTx =
+  ({
+    walletAccount,
+    getTxLog,
+    baseAsset,
+    watchTxDelay = WATCH_TX_DELAY,
+    watchTxTimeout = WATCH_TX_TIMEOUT,
+  }) =>
+  async (txId) => {
+    const start = Date.now()
+    let txConfirmed = false
+    let hasTimedOut = false
+
+    while (!hasTimedOut && !txConfirmed) {
+      await delay(watchTxDelay)
+      const baseAssetTxLog = await getTxLog({
+        assetName: baseAsset.name,
+        walletAccount,
+      })
+      txConfirmed = baseAssetTxLog.get(txId)?.confirmed
+      hasTimedOut = Date.now() - start > watchTxTimeout
+    }
+
+    return { txId, confirmed: txConfirmed, hasTimedOut }
+  }