@exodus/ethereum-api 8.73.0 → 8.73.2

package/CHANGELOG.md

@@ -3,6 +3,24 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+## [8.73.2](https://github.com/ExodusMovement/assets/compare/@exodus/ethereum-api@8.73.1...@exodus/ethereum-api@8.73.2) (2026-05-05)
+
+**Note:** Version bump only for package @exodus/ethereum-api
+
+
+
+
+
+## [8.73.1](https://github.com/ExodusMovement/assets/compare/@exodus/ethereum-api@8.73.0...@exodus/ethereum-api@8.73.1) (2026-05-04)
+
+
+### Bug Fixes
+
+
+* fix(ethereum-api): pass assertion message to assert(), not startsWith() (#7924)
+
+
+
 ## [8.73.0](https://github.com/ExodusMovement/assets/compare/@exodus/ethereum-api@8.72.0...@exodus/ethereum-api@8.73.0) (2026-05-01)
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@exodus/ethereum-api",
-  "version": "8.73.0",
+  "version": "8.73.2",
   "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",
@@ -39,7 +39,7 @@
     "@exodus/simple-retry": "^0.0.6",
     "@exodus/solidity-contract": "^1.3.0",
     "@exodus/traceparent": "^3.0.1",
-    "@exodus/web3-ethereum-utils": "^4.6.0",
+    "@exodus/web3-ethereum-utils": "^4.7.4",
     "bn.js": "^5.2.1",
     "delay": "^4.0.1",
     "eventemitter3": "^4.0.7",
@@ -68,5 +68,5 @@
     "type": "git",
     "url": "git+https://github.com/ExodusMovement/assets.git"
   },
-  "gitHead": "d17ee07f3f8bf4cc67518f8a8395522578e8dae1"
+  "gitHead": "69553b4abf01b543d0e6006299166b8f7cc6271c"
 }

package/src/staking/ethereum/api.js

@@ -12,6 +12,11 @@ const RETRY_DELAYS = ['10s']
 
 const EVERSTAKE_API_URL = 'https://eth-clarity.a.exodus.io/everstake-rewards'
 
+export const UNSTAKE_DEFAULTS = {
+  allowedInterchangeNum: 0,
+  source: '2',
+}
+
 export class EthereumStaking {
   static addresses = {
     ethereum: {
@@ -229,8 +234,22 @@ export class EthereumStaking {
     throw new Error(`Min Amount ${this.minAmount}`)
   }
 
-  /* Unstake funds that are staked into the validator. Once unstaked they need to be claimed (once ready to withdraw) */
-  async unstake({ address, amount, allowedInterchangeNum = 0, source = '2' }) {
+  /**
+   * Unstake funds from the validator. The unstaked amount enters a withdrawal
+   * queue and must be claimed via `claimWithdrawRequest` after the validator exits.
+   *
+   * @param {number} allowedInterchangeNum - Max number of incoming stake requests
+   *   the contract may use to immediately return ETH to the unstaker (interchange).
+   *   When 0 (default), no interchange occurs and the full amount is queued.
+   *   When > 0, the contract may match up to N new stakers' deposits against this
+   *   unstake, returning ETH immediately without waiting for validator exit.
+   */
+  async unstake({
+    address,
+    amount,
+    allowedInterchangeNum = UNSTAKE_DEFAULTS.allowedInterchangeNum,
+    source = UNSTAKE_DEFAULTS.source,
+  }) {
     const amountWei = amount.toBaseString()
     const balance = await this.autocompoundBalanceOf(address) // amount staked into the validator (active balance)
 

package/src/staking/ethereum/everstake.js

@@ -2,7 +2,10 @@ import { fetch as exodusFetch } from '@exodus/fetch'
 import { TraceId } from '@exodus/traceparent'
 import assert from 'minimalistic-assert'
 
+import { UNSTAKE_DEFAULTS } from './api.js'
+
 const BASE_URL = 'https://eth-clarity.a.exodus.io/api/v2/ethereum/proxy/everstake/'
+const WALLET_SDK_BASE_URL = 'https://wallet-sdk-api.everstake.one/'
 
 const fetch = async (path, config = Object.create(null)) => {
   const url = new URL(path, BASE_URL).toString()
@@ -26,6 +29,56 @@ const fetch = async (path, config = Object.create(null)) => {
 
 const isFiniteInteger = (e) => Number.isInteger(e) && Number.isFinite(e)
 
+// Simulate an unstake to predict how much ETH the interchange pool returns instantly.
+// https://wallet-sdk-api.everstake.one/swagger/#/Ethereum/post_ethereum_pool_simulate_unstake
+//
+// Inputs:
+//   address: staker address (0x...)
+//   amount:  unstake amount in ETH (default units), e.g. "1.5" — NOT wei
+//   allowedInterchangeNum: interchange pool parameter (default from UNSTAKE_DEFAULTS)
+//   source: source identifier (default from UNSTAKE_DEFAULTS)
+//
+// Success (200): { result: <number> } — ETH returned instantly (capped by pool liquidity)
+// Error   (500): { "Internal Server Error": "Error: Max Amount For Unstake <max_eth>" }
+//                 when amount exceeds the staker's active balance
+export const simulateEverstakeUnstake = async ({
+  address,
+  amount,
+  allowedInterchangeNum = UNSTAKE_DEFAULTS.allowedInterchangeNum,
+  source = UNSTAKE_DEFAULTS.source,
+}) => {
+  try {
+    assert(typeof address === 'string' && address.startsWith('0x'), 'expected valid address')
+    assert(typeof amount === 'string' && amount.length > 0, 'expected amount in ETH as string')
+
+    const url = new URL('ethereum/pool/simulate_unstake', WALLET_SDK_BASE_URL).toString()
+
+    const response = await exodusFetch(url, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ address, amount, allowedInterchangeNum, source }),
+    })
+
+    if (!response.ok) {
+      const body = await response.json().catch(() => null)
+      const serverMsg = body?.['Internal Server Error'] || response.statusText
+      console.warn(`simulate_unstake failed: ${serverMsg}`)
+      return null
+    }
+
+    const data = await response.json()
+    if (!data || typeof data.result !== 'number') {
+      console.warn('simulate_unstake: malformed response', data)
+      return null
+    }
+
+    return { instantReturnEth: data.result }
+  } catch (e) {
+    console.warn('simulate_unstake error:', e.message)
+    return null
+  }
+}
+
 export const getEverstakeValidatorsQueue = async () => {
   // https://swagger.eth-api-b2c.everstake.one/#/Staking/validatorsQueue
   const result = await fetch('v1/validators/queue')

package/src/staking/ethereum/service.js

@@ -1,12 +1,78 @@
+/**
+ * Everstake ETH Staking — Balance States
+ *
+ * When a user stakes ETH via Everstake, their funds move through several
+ * buckets tracked by the Accounting contract. Each bucket has different
+ * rules about what operations are allowed.
+ *
+ *   User Wallet (ETH)
+ *       |
+ *       | stake()
+ *       v
+ *   pendingBalance
+ *       Pool waiting room. ETH sits here until enough accumulates
+ *       (32 ETH across all users) to fund a new validator.
+ *       Can be withdrawn instantly via unstakePending().
+ *       |
+ *       | pool reaches 32 ETH, deposits to Beacon chain
+ *       v
+ *   pendingDepositedBalance
+ *       Sent to Beacon chain but validator not yet activated.
+ *       LOCKED — cannot be unstaked until validator activates.
+ *       |
+ *       | validator activates
+ *       v
+ *   activeStakedBalance (autocompoundBalanceOf)
+ *       User's share of active validator ETH, including compounded
+ *       rewards. Can be unstaked via unstake().
+ *       |
+ *       | unstake()
+ *       |-----> ETH returned immediately (if pool has liquidity / interchange)
+ *       |       goes directly to wallet
+ *       v
+ *   unclaimedUndelegatedBalance
+ *       Withdrawal queue. Waiting for validator exit.
+ *       Global per-user — all unstake() calls accumulate into a single
+ *       balance. Cannot claim until the entire balance is ready.
+ *       |
+ *       | validator(s) exit
+ *       v
+ *   readyForClaim (withdrawRequest.readyForClaim)
+ *       When requested == readyForClaim, user can call
+ *       claimWithdrawRequest() to get ETH back to wallet.
+ *       |
+ *       | claimWithdrawRequest()
+ *       v
+ *   User Wallet (ETH)
+ *
+ * Additional derived values:
+ *   - delegatedBalance = activeStakedBalance + pendingBalance + pendingDepositedBalance
+ *   - depositedBalanceOf = the user's original deposit amount tracked by the
+ *     Accounting contract. Does NOT include compounded rewards — only what the
+ *     user explicitly staked. Grows when user stakes, shrinks when user unstakes.
+ *   - liquidRewards = activeStakedBalance - depositedBalanceOf
+ *     The difference between the user's current share of validator ETH
+ *     (which grows as validators earn rewards and autocompound) and what
+ *     they originally deposited. This is the "unrealized" profit that
+ *     would be forfeited if the user unstakes only their deposited amount.
+ *   - rewardsBalance (getTotalRewards) = historical total rewards from the
+ *     Everstake API, including already-claimed and compounded rewards.
+ *     Unlike liquidRewards, this is NOT derived on-chain — it comes from
+ *     an external Everstake endpoint and may lag behind real-time state.
+ */
+
 import { memoize } from '@exodus/basic-utils'
+import NumberUnit from '@exodus/currency'
 import assert from 'minimalistic-assert'
 
 import { estimateGasLimit, scaleGasLimitEstimate } from '../../gas-estimation.js'
+import { getOptimisticTxLogEffects } from '../../tx-log/get-optimistic-txlog-effects.js'
 import { createWatchTx as defaultCreateWatch } from '../../watch-tx.js'
 import { stakingProviderClientFactory } from '../staking-provider-client.js'
 import { amountToCurrency, DISABLE_BALANCE_CHECKS, resolveFeeData } from '../utils/index.js'
 import { EthereumStaking } from './api.js'
 import { getEverstakeValidatorsQueue } from './everstake.js'
+import { simulateUndelegateTransactions } from './staking-utils.js'
 
 const WETH9_ADDRESS = '0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2'
 
@@ -37,6 +103,74 @@ const getStakingApi = memoize(
   (asset) => asset.name
 )
 
+export async function getUndelegatePendingData({
+  staking,
+  delegatorAddress,
+  requestedAmount,
+  pendingAmount,
+  minAmount,
+  resolvedFeeData,
+  estimateTxFee,
+}) {
+  if (!pendingAmount.isPositive) return null
+
+  const leftOver = pendingAmount.sub(requestedAmount)
+
+  if (leftOver.isPositive && leftOver.lt(minAmount)) return null
+
+  // Essentially the min of the 2 amounts
+  const inactiveAmountToUnstake = pendingAmount.lte(requestedAmount)
+    ? pendingAmount
+    : requestedAmount
+
+  const { to, data } = await staking.unstakePending({
+    address: delegatorAddress,
+    amount: inactiveAmountToUnstake,
+  })
+
+  const feeInfo = estimateTxFee
+    ? await estimateTxFee({
+        from: delegatorAddress,
+        to,
+        amount: null,
+        txInput: data,
+        feeData: resolvedFeeData,
+      })
+    : null
+
+  return { plan: { to, txData: data, amount: inactiveAmountToUnstake }, feeInfo }
+}
+
+export async function getUndelegateData({
+  staking,
+  delegatorAddress,
+  requestedAmount,
+  pendingAmount,
+  resolvedFeeData,
+  estimateTxFee,
+}) {
+  const activeAmountToUnstake = requestedAmount.sub(pendingAmount)
+
+  if (!activeAmountToUnstake.isPositive) return null
+
+  const { to, data } = await staking.unstake({
+    address: delegatorAddress,
+    amount: activeAmountToUnstake,
+  })
+
+  const feeInfo = estimateTxFee
+    ? await estimateTxFee({
+        from: delegatorAddress,
+        to,
+        amount: null,
+        txInput: data,
+        feeData: resolvedFeeData,
+      })
+    : null
+
+  return { plan: { to, txData: data, amount: activeAmountToUnstake }, feeInfo }
+}
+
 export function createEthereumStakingService({
   asset: deprectedArg, // @deprecated use `assetName` instead
   assetName,
@@ -127,71 +261,40 @@ export function createEthereumStakingService({
     return txId
   }
 
-  async function getUndelegatePendingData({
-    delegatorAddress,
-    resquestedAmount,
-    pendingAmount,
-    minAmount,
-    feeData,
-  }) {
+  async function prepareUndelegate({ walletAccount, amount, feeData }) {
+    assert(amount instanceof NumberUnit, 'expected amount to be a NumberUnit')
     const asset = await getAsset(assetName)
     const staking = getStakingApi(asset)
-    const leftOver = pendingAmount.sub(resquestedAmount)
-
-    if (leftOver.isPositive && leftOver.lt(minAmount)) {
-      throw new Error(`Pending balance less than min stake amount ${minAmount}`)
-    }
-
-    const inactiveAmountToUnstake = pendingAmount.lte(resquestedAmount)
-      ? pendingAmount
-      : resquestedAmount
-
-    feeData = await resolveFeeData({ asset, assetClientInterface, feeData })
-
-    const { to, data } = await staking.unstakePending({
-      address: delegatorAddress,
-      amount: inactiveAmountToUnstake,
-    })
+    const minAmount = getMinAmount(asset)
+    const requestedAmount = amount
 
-    const { fee, gasLimit, gasPrice, tipGasPrice } = await estimateTxFee({
-      from: delegatorAddress,
-      to,
-      amount: null,
-      txInput: data,
-      feeData,
+    const [address, resolvedFeeData] = await Promise.all([
+      assetClientInterface.getReceiveAddress({
+        assetName,
+        walletAccount,
+      }),
+      resolveFeeData({ asset, assetClientInterface, feeData }),
+    ])
+    const delegatorAddress = address.toLowerCase()
+    const pendingAmount = await staking.pendingBalanceOf(delegatorAddress)
+    const baseNonce = await asset.baseAsset.getNonce({
+      asset,
+      fromAddress: delegatorAddress,
+      walletAccount,
+      tag: 'latest',
+      forceFromNode: true,
     })
 
-    return { to, txData: data, gasLimit, gasPrice, tipGasPrice, fee }
-  }
-
-  async function getUndelegateData({ delegatorAddress, resquestedAmount, pendingAmount, feeData }) {
-    const asset = await getAsset(assetName)
-    const staking = getStakingApi(asset)
-    const canUnstake = resquestedAmount.gt(pendingAmount)
-
-    if (!canUnstake) {
-      console.warn('UnstakePending covered requested unstake. Nothing to unstake from validator')
-      return Object.create(null)
+    return {
+      asset,
+      staking,
+      minAmount,
+      requestedAmount,
+      feeData: resolvedFeeData,
+      delegatorAddress,
+      pendingAmount,
+      baseNonce,
     }
-
-    const activeAmountToUnstake = resquestedAmount.sub(pendingAmount)
-
-    feeData = await resolveFeeData({ asset, assetClientInterface, feeData })
-
-    const { to, data } = await staking.unstake({
-      address: delegatorAddress,
-      amount: activeAmountToUnstake,
-    })
-
-    const { fee, gasLimit, gasPrice, tipGasPrice } = await estimateTxFee({
-      from: delegatorAddress,
-      to,
-      amount: null,
-      txInput: data,
-      feeData,
-    })
-
-    return { to, txData: data, gasLimit, gasPrice, tipGasPrice, fee }
   }
 
   /**
@@ -199,7 +302,8 @@ export function createEthereumStakingService({
    * Fee estimation depends on the executed txs. Can be both.
    * @returns total undelegete fee
    */
-  async function estimateUndelegate({ walletAccount, amount: resquestedAmount, feeData }) {
+  async function estimateUndelegate({ walletAccount, amount: requestedAmount, feeData }) {
+    assert(requestedAmount instanceof NumberUnit, 'expected amount to be a NumberUnit')
     const asset = await getAsset(assetName)
     const staking = getStakingApi(asset)
     const minAmount = getMinAmount(asset)
@@ -209,114 +313,251 @@ export function createEthereumStakingService({
 
     const pendingAmount = await staking.pendingBalanceOf(delegatorAddress)
 
-    let undelegatePendingFee = asset.currency.ZERO
-
-    if (pendingAmount.isPositive) {
-      try {
-        // try to estimate unstakePending
-        const { fee } = await getUndelegatePendingData({
-          delegatorAddress,
-          resquestedAmount,
-          pendingAmount,
-          minAmount,
-          feeData,
-        })
-        undelegatePendingFee = fee
-      } catch (err) {
-        // useful to debug fee calculation
-        console.warn('ETH unstake pending estimation failed, continuing with unstake', err)
-      }
+    let pendingResult = null
+    try {
+      pendingResult = await getUndelegatePendingData({
+        staking,
+        delegatorAddress,
+        requestedAmount,
+        pendingAmount,
+        minAmount,
+        resolvedFeeData: feeData,
+        estimateTxFee,
+      })
+    } catch (err) {
+      console.warn('ETH unstake pending estimation failed, continuing with unstake', err)
     }
 
-    const { fee: undelegateFee = asset.currency.ZERO } = await getUndelegateData({
+    const undelegateResult = await getUndelegateData({
+      staking,
       delegatorAddress,
-      resquestedAmount,
+      requestedAmount,
       pendingAmount,
-      minAmount,
-      feeData,
+      resolvedFeeData: feeData,
+      estimateTxFee,
     })
 
-    return undelegatePendingFee.add(undelegateFee)
-  }
+    const pendingFee = pendingResult?.feeInfo?.fee ?? asset.currency.ZERO
+    const undelegateFee = undelegateResult?.feeInfo?.fee ?? asset.currency.ZERO
 
-  async function undelegate({ walletAccount, amount, feeData, waitForConfirmation = true }) {
-    const asset = await getAsset(assetName)
-    const staking = getStakingApi(asset)
-    const minAmount = getMinAmount(asset)
+    return pendingFee.add(undelegateFee)
+  }
 
-    /*
-    unstakePending balance (not yet in validator) + unstake balance (in validator)
-    1. give priority to unstakePending (based on the amount)
-    2. unstake amount in validator.
-    */
-    const resquestedAmount = amountToCurrency({ asset, amount })
+  // NOTE: Like the legacy `undelegate()` flow, this planner currently splits
+  // the request using `pendingAmount` only. It does not pre-validate that the
+  // validator-side remainder is actually available in active staked balance,
+  // so an oversized request can still fail later when building/sending the
+  // validator unstake step.
+  async function undelegate({ walletAccount, amount, feeData, revertOnSimulationError = true }) {
+    const {
+      asset,
+      staking,
+      minAmount,
+      requestedAmount,
+      feeData: resolvedFeeData,
+      delegatorAddress,
+      pendingAmount,
+      baseNonce,
+    } = await prepareUndelegate({ walletAccount, amount, feeData })
 
-    let delegatorAddress
-    ;({ feeData, delegatorAddress } = await getTransactionProps({ feeData, walletAccount }))
+    if (!requestedAmount.isPositive) {
+      throw new Error('Undelegate amount must be positive')
+    }
 
-    const pendingAmount = await staking.pendingBalanceOf(delegatorAddress)
+    const txSteps = {
+      undelegatePending: {
+        plan: null,
+        gasLimit: null,
+        unsignedTx: null,
+        signedTx: null,
+        txId: null,
+      },
+      undelegate: {
+        plan: null,
+        gasLimit: null,
+        unsignedTx: null,
+        signedTx: null,
+        txId: null,
+      },
+    }
 
     console.log(
-      `delegator address ${delegatorAddress} unstaking ${resquestedAmount.toDefaultString({
+      `delegator address ${delegatorAddress} unstaking ${requestedAmount.toDefaultString({
         unit: true,
       })} - pending amount: ${pendingAmount.toDefaultString({ unit: true })}`
     )
 
-    let txId
-    if (pendingAmount.isPositive) {
-      const undelegatePendingData = await getUndelegatePendingData({
-        delegatorAddress,
-        resquestedAmount,
-        pendingAmount,
-        minAmount,
-        feeData,
-      })
+    // 1. Plan transactions and estimate fees
+    const pendingResult = await getUndelegatePendingData({
+      staking,
+      delegatorAddress,
+      requestedAmount,
+      pendingAmount,
+      minAmount,
+      resolvedFeeData,
+      estimateTxFee,
+    })
 
-      txId = await prepareAndSendTx({
-        asset,
-        walletAccount,
-        waitForConfirmation,
-        ...undelegatePendingData,
-        feeData,
-      })
+    const undelegateResult = await getUndelegateData({
+      staking,
+      delegatorAddress,
+      requestedAmount,
+      pendingAmount,
+      resolvedFeeData,
+      estimateTxFee,
+    })
 
-      // If we are waiting for confirmation, then sufficient time
-      // will have elapsed for us to re-estimate `feeData`.
-      //
-      // NOTE: This will invalidate previous transaction fee estimates!
-      if (waitForConfirmation) {
-        feeData = await assetClientInterface.getFeeData({ assetName })
-      }
+    if (!pendingResult && !undelegateResult) {
+      throw new Error('Requested undelegation produced no transactions')
     }
 
-    // may need also to unstake
-    const undelegateData = await getUndelegateData({
-      delegatorAddress,
-      resquestedAmount,
-      pendingAmount,
-      feeData,
+    let gasPrice
+    let tipGasPrice
+
+    if (pendingResult) {
+      txSteps.undelegatePending.plan = pendingResult.plan
+      txSteps.undelegatePending.gasLimit = pendingResult.feeInfo.gasLimit
+      gasPrice = pendingResult.feeInfo.gasPrice
+      tipGasPrice = pendingResult.feeInfo.tipGasPrice
+    }
+
+    if (undelegateResult) {
+      txSteps.undelegate.plan = undelegateResult.plan
+      txSteps.undelegate.gasLimit = undelegateResult.feeInfo.gasLimit
+      gasPrice = gasPrice || undelegateResult.feeInfo.gasPrice
+      tipGasPrice = tipGasPrice || undelegateResult.feeInfo.tipGasPrice
+    }
+
+    // 3. Create unsigned txs
+    const createTxBaseArgs = {
+      asset,
+      walletAccount,
+      fromAddress: delegatorAddress,
+      amount: asset.currency.ZERO,
+      tipGasPrice,
+      gasPrice,
+    }
+
+    const createdTxEntries = await Promise.all(
+      Object.entries(txSteps)
+        .filter(([, txStep]) => txStep.plan)
+        .map(async ([key, txStep], index) => {
+          const result = await asset.baseAsset.api.createTx({
+            ...createTxBaseArgs,
+            toAddress: txStep.plan.to,
+            txInput: txStep.plan.txData,
+            gasLimit: txStep.gasLimit,
+            nonce: baseNonce + index,
+          })
+          return [key, result.unsignedTx]
+        })
+    )
+
+    for (const [key, unsignedTx] of createdTxEntries) {
+      txSteps[key].unsignedTx = unsignedTx
+    }
+
+    await simulateUndelegateTransactions({
+      asset,
+      txSteps,
+      senderAddress: delegatorAddress,
+      gasPrice,
+      revertOnSimulationError,
     })
 
-    if (undelegateData.fee) {
-      txId = await prepareAndSendTx({
-        asset,
-        walletAccount,
-        ...undelegateData,
-        feeData,
-      })
+    // 4. Sign transactions
+    const signedTxEntries = await Promise.all(
+      Object.entries(txSteps)
+        .filter(([, txStep]) => txStep.unsignedTx)
+        .map(async ([key, txStep]) => {
+          const signedTx = await assetClientInterface.signTransaction({
+            assetName: asset.baseAsset.name,
+            unsignedTx: txStep.unsignedTx,
+            walletAccount,
+          })
+          const txId = `0x${signedTx.txId.toString('hex')}`
+          return [key, { signedTx, txId }]
+        })
+    )
+
+    for (const [key, { signedTx, txId }] of signedTxEntries) {
+      txSteps[key].signedTx = signedTx
+      txSteps[key].txId = txId
+    }
+
+    // 5. Broadcast transactions via bundle and get bundle hash
+    const bundleResponse = await asset.broadcastPrivateBundle({
+      txs: Object.values(txSteps)
+        .filter((txStep) => txStep.signedTx)
+        .map(({ signedTx }) => signedTx.rawTx),
+    })
+    const bundleHash = bundleResponse?.bundleHash
+
+    // 6. Optimistic tx-log effects: reflect tx presence and fee consumption only.
+    // The ETH returned to the user via the contract's internal transfer is not
+    // captured here — it will be picked up once the tx is confirmed on-chain.
+    // It would also be incorrect to optimistically log the full requested ETH
+    // as immediately received: some portion may instead be routed into the
+    // undelegation queue / withdraw-request system and only become claimable
+    // much later after validator exit.
+    //
+    // We now have a more deterministic model for these incoming ETH amounts,
+    // but it requires staking-operation context that getOptimisticTxLogEffects()
+    // does not currently accept:
+    //
+    // - unstakePending: the ETH returned is exactly the amount passed to
+    //   unstakePending(). In this flow that amount is chosen from the pre-send
+    //   pending balance and the requested undelegation amount:
+    //     amountPassedToUnstakePending = min(totalRequestedAmount, pendingBalanceBefore)
+    // - unstake: the ETH returned can be derived only from staking state before
+    //   and after the operation:
+    //     amountPassedToUnstake = totalRequestedAmount - pendingBalanceBefore
+    //     queuedFromUnstake = unclaimedUndelegatedBalanceAfter - unclaimedUndelegatedBalanceBefore
+    //     returnedImmediatelyFromUnstake = amountPassedToUnstake - queuedFromUnstake
+    //
+    // That is incompatible with the current tx-log side-effect hook, which only
+    // receives tx-local data (method id, calldata, nonce, gas, etc.) and not
+    // staking snapshots or precomputed ETH-return amounts.
+    const optimisticEffects = await Promise.all(
+      Object.values(txSteps)
+        .filter((txStep) => txStep.txId)
+        .map((txStep) =>
+          getOptimisticTxLogEffects({
+            asset: asset.baseAsset,
+            assetClientInterface,
+            fromAddress: delegatorAddress,
+            txId: txStep.txId,
+            unsignedTx: txStep.unsignedTx,
+            walletAccount,
+            bundleId: bundleHash ?? undefined,
+          })
+        )
+    )
+
+    for (const { optimisticTxLogEffects } of optimisticEffects) {
+      for (const effect of optimisticTxLogEffects) {
+        await assetClientInterface.updateTxLogAndNotify(effect)
+      }
     }
 
     // Testnet assets do not support delegations tracking
-    if (txId && assetName === 'ethereum') {
-      await stakingProvider.notifyUnstaking({
-        txId,
-        asset: assetName,
-        delegator: delegatorAddress,
-        amount: resquestedAmount.toBaseString(),
-      })
+    if (assetName === 'ethereum') {
+      const notify = (txStep) =>
+        stakingProvider.notifyUnstaking({
+          txId: txStep.txId,
+          asset: assetName,
+          delegator: delegatorAddress,
+          amount: txStep.plan.amount.toBaseString(),
+        })
+
+      await Promise.all([
+        txSteps.undelegatePending.txId && notify(txSteps.undelegatePending),
+        txSteps.undelegate.txId && notify(txSteps.undelegate),
+      ])
     }
 
-    return txId
+    // This is the most correct response, but it doesn't matter, it is not consumed by the apps
+    return bundleHash
   }
 
   async function claimUndelegatedBalance({ walletAccount, feeData }) {

package/src/staking/ethereum/staking-utils.js

@@ -1,4 +1,10 @@
-import { EthereumStaking } from './api.js'
+import NumberUnit from '@exodus/currency'
+import { parseUnsignedTx } from '@exodus/ethereum-lib'
+import { bufferToHex } from '@exodus/ethereumjs/util'
+import assert from 'minimalistic-assert'
+
+import { EthereumStaking, UNSTAKE_DEFAULTS } from './api.js'
+import { simulateEverstakeUnstake } from './everstake.js'
 
 const { DELEGATE, UNSTAKE, UNSTAKE_PENDING, CLAIM_UNSTAKE } = EthereumStaking.METHODS_IDS
 
@@ -8,8 +14,13 @@ const STAKING_MANAGER_CONTRACTS = new Set([
   EthereumStaking.addresses.ethereumholesky.EVERSTAKE_ADDRESS_CONTRACT_POOL.toLowerCase(),
 ])
 
+const METHOD_ID_CHAR_LENGTH = 10
+const FIRST_UINT256_END = METHOD_ID_CHAR_LENGTH + 64
+
 export const isEthereumStakingTx = ({ coinName }) =>
   ['ethereum', 'ethereumgoerli', 'ethereumholesky'].includes(coinName)
+export const isEthereumStakingPoolContract = (address) =>
+  typeof address === 'string' && STAKING_MANAGER_CONTRACTS.has(address.toLowerCase())
 export const isEthereumDelegate = (tx) =>
   isEthereumStakingTx(tx) && STAKING_MANAGER_CONTRACTS.has(tx.to) && tx.data?.methodId === DELEGATE
 export const isEthereumUndelegatePending = (tx) =>
@@ -18,3 +29,259 @@ export const isEthereumUndelegate = (tx) =>
   (isEthereumStakingTx(tx) && tx.data?.methodId === UNSTAKE) || isEthereumUndelegatePending(tx)
 export const isEthereumClaimUndelegate = (tx) =>
   isEthereumStakingTx(tx) && tx.data?.methodId === CLAIM_UNSTAKE
+
+export function decodeEthereumStakingFirstUintArg(transactionData) {
+  const txInputHex =
+    (Buffer.isBuffer(transactionData) ? bufferToHex(transactionData) : transactionData) || '0x'
+  assert(typeof txInputHex === 'string', 'expected string transactionData')
+  assert(
+    txInputHex.length >= FIRST_UINT256_END,
+    'expected staking transaction calldata with first uint256 arg'
+  )
+
+  return BigInt(`0x${txInputHex.slice(METHOD_ID_CHAR_LENGTH, FIRST_UINT256_END)}`)
+}
+
+export async function ethereumUnstakePendingOptimisticSideEffectTxLogs({
+  asset: baseAsset,
+  walletAccount,
+  feeAmount,
+  unstakePendingTxId,
+  nonce,
+  estimatedUnstakePendingGasLimit,
+  tipGasPrice,
+  transactionData,
+  txToAddress,
+  date,
+  bundleId,
+}) {
+  let amount
+  try {
+    const decodedAmount = decodeEthereumStakingFirstUintArg(transactionData)
+    amount = baseAsset.currency.baseUnit(decodedAmount.toString())
+  } catch (e) {
+    console.warn(
+      'Could not decode ETH unstakePending transaction data:',
+      unstakePendingTxId,
+      e.message,
+      transactionData
+    )
+    return []
+  }
+
+  return [
+    {
+      assetName: baseAsset.name,
+      walletAccount,
+      txs: [
+        {
+          confirmations: 0,
+          feeAmount,
+          feeCoinName: baseAsset.feeAsset.name,
+          selfSend: false,
+          to: txToAddress,
+          txId: unstakePendingTxId,
+          data: {
+            gasLimit: estimatedUnstakePendingGasLimit,
+            nonce,
+            ...(tipGasPrice && { tipGasPrice: tipGasPrice.toBaseString() }),
+            methodId: UNSTAKE_PENDING,
+            ...(bundleId ? { bundleId } : {}),
+          },
+          coinAmount: amount,
+          coinName: baseAsset.name,
+          currencies: {
+            [baseAsset.name]: baseAsset.currency,
+            [baseAsset.feeAsset.name]: baseAsset.feeAsset.currency,
+          },
+          date,
+        },
+      ],
+    },
+  ]
+}
+
+export async function ethereumUnstakeOptimisticSideEffectTxLogs({
+  asset: baseAsset,
+  walletAccount,
+  feeAmount,
+  unstakeTxId,
+  nonce,
+  estimatedUnstakeGasLimit,
+  tipGasPrice,
+  transactionData,
+  txToAddress,
+  fromAddress,
+  allowedInterchangeNum = UNSTAKE_DEFAULTS.allowedInterchangeNum,
+  date,
+  bundleId,
+}) {
+  let amountEth
+  try {
+    const decodedAmountWei = decodeEthereumStakingFirstUintArg(transactionData)
+    amountEth = baseAsset.currency.baseUnit(decodedAmountWei.toString()).toDefaultString()
+  } catch (e) {
+    console.warn(
+      'Could not decode ETH unstake transaction data:',
+      unstakeTxId,
+      e.message,
+      transactionData
+    )
+    return []
+  }
+
+  const result = await simulateEverstakeUnstake({
+    address: fromAddress,
+    amount: amountEth,
+    allowedInterchangeNum,
+  })
+
+  if (!result || result.instantReturnEth <= 0) return []
+
+  const instantAmount = baseAsset.currency.defaultUnit(String(result.instantReturnEth))
+
+  return [
+    {
+      assetName: baseAsset.name,
+      walletAccount,
+      txs: [
+        {
+          confirmations: 0,
+          feeAmount,
+          feeCoinName: baseAsset.feeAsset.name,
+          selfSend: false,
+          to: txToAddress,
+          txId: unstakeTxId,
+          data: {
+            gasLimit: estimatedUnstakeGasLimit,
+            nonce,
+            ...(tipGasPrice && { tipGasPrice: tipGasPrice.toBaseString() }),
+            methodId: UNSTAKE,
+            ...(bundleId ? { bundleId } : {}),
+          },
+          coinAmount: instantAmount,
+          coinName: baseAsset.name,
+          currencies: {
+            [baseAsset.name]: baseAsset.currency,
+            [baseAsset.feeAsset.name]: baseAsset.feeAsset.currency,
+          },
+          date,
+        },
+      ],
+    },
+  ]
+}
+
+export function buildSimulationRequest({ asset, unsignedTx, gasPrice }) {
+  const parsed = parseUnsignedTx({ asset, unsignedTx })
+  const chainId = unsignedTx.txData?.chainId
+  const from = unsignedTx.txMeta?.fromAddress
+  const to = unsignedTx.txMeta?.toAddress
+
+  assert(gasPrice instanceof NumberUnit, 'expected NumberUnit gasPrice')
+  assert(Number.isInteger(chainId), 'expected integer chainId')
+  assert(typeof from === 'string' && from, 'expected string fromAddress')
+  assert(typeof to === 'string' && to, 'expected string toAddress')
+
+  return {
+    chainId,
+    from,
+    to,
+    gas: `0x${parsed.gasLimit.toString(16)}`,
+    gasPrice: `0x${BigInt(gasPrice.toBaseString()).toString(16)}`,
+    value: `0x${BigInt(parsed.value.toBaseString()).toString(16)}`,
+    data: `0x${parsed.data?.toString('hex')}`,
+    nonce: `0x${parsed.nonce.toString(16)}`,
+  }
+}
+
+export async function simulateUndelegateTransactions({
+  asset,
+  txSteps,
+  senderAddress,
+  gasPrice,
+  blockNumber,
+  revertOnSimulationError,
+}) {
+  const transactions = Object.values(txSteps)
+    .filter((txStep) => txStep.unsignedTx)
+    .map((txStep) =>
+      buildSimulationRequest({ asset: asset.baseAsset, unsignedTx: txStep.unsignedTx, gasPrice })
+    )
+
+  if (transactions.length === 0) return
+
+  const simulationResponse = await asset.baseAsset.api.web3.simulateTransactions({
+    baseAssetName: asset.baseAsset.name,
+    origin: 'exodus-staking',
+    senderAddress,
+    ...(blockNumber === undefined ? undefined : { blockNumber }),
+    transactions,
+  })
+
+  if (simulationResponse?.warnings?.length || simulationResponse?.metadata?.humanReadableError) {
+    if (revertOnSimulationError) {
+      const err = new Error('StakingEthUndelegateSimulationError')
+      err.message = simulationResponse?.metadata?.humanReadableError
+      err.reason = `warnings: ${JSON.stringify(simulationResponse?.warnings)}`
+      err.hint = 'undelegate-eth-simulation-error'
+      throw err
+    } else {
+      console.warn(
+        'Simulation for ETH undelegate returned issues',
+        simulationResponse?.metadata?.humanReadableError
+      )
+    }
+  }
+
+  // Validate undelegatePending simulation results.
+  //
+  // Pass: every ETH entry in willReceive has a parseable balance and their
+  //       sum is positive (i.e. we are actually receiving ETH back).
+  // Fail: any ETH entry has a malformed balance (shape error), or the
+  //       summed ETH is zero/negative (no refund, or only non-ETH entries).
+  //
+  // Our on-chain analysis showed an apparent invariant: successful
+  // unstakePending() calls return exactly the input amount. We intentionally
+  // do not enforce that here because we were not able to prove it via
+  // simulation alone and there may be an off-chain component involved.
+  //
+  // When there's no pending balance (only unstake with
+  // allowedInterchangeNum=0), nothing may come back immediately — that's
+  // valid and we skip the check.
+  if (txSteps.undelegatePending.plan?.amount?.isPositive) {
+    const { balanceChanges = Object.create(null) } = simulationResponse || Object.create(null)
+
+    const asArray = (v) => (Array.isArray(v) ? v : [])
+    let invalidEthReceiveValue = false
+    let sumEthReceive = BigInt(0)
+
+    for (const receive of asArray(balanceChanges.willReceive)) {
+      const isEth = receive?.asset?.symbol === 'ETH' || receive?.asset?.name === 'Ether'
+      if (!isEth) continue
+
+      try {
+        sumEthReceive += BigInt(receive.balance.toBaseString())
+      } catch {
+        invalidEthReceiveValue = true
+      }
+    }
+
+    if (invalidEthReceiveValue || sumEthReceive <= BigInt(0)) {
+      if (revertOnSimulationError) {
+        const err = new Error('StakingEthUndelegateSimulationResultsError')
+        err.message = 'Simulation did not produce expected effects'
+        err.reason = invalidEthReceiveValue
+          ? 'invalid ETH balance.value in balanceChanges: willReceive'
+          : 'missing positive ETH in balanceChanges: willReceive (expected pending refund)'
+        err.hint = 'undelegate-eth-simulation-results-error'
+        throw err
+      } else {
+        console.warn(
+          'Simulation for ETH undelegate returned issues',
+          simulationResponse?.metadata?.humanReadableError
+        )
+      }
+    }
+  }
+}

package/src/tx-log/get-optimistic-txlog-effects.js

@@ -8,6 +8,12 @@ import {
 import { bufferToHex } from '@exodus/ethereumjs/util'
 import assert from 'minimalistic-assert'
 
+import { EthereumStaking } from '../staking/ethereum/api.js'
+import {
+  ethereumUnstakeOptimisticSideEffectTxLogs,
+  ethereumUnstakePendingOptimisticSideEffectTxLogs,
+  isEthereumStakingPoolContract,
+} from '../staking/ethereum/staking-utils.js'
 import { MaticStakingApi } from '../staking/matic/api.js'
 import {
   DELEGATE,
@@ -93,6 +99,7 @@ export const getOptimisticTxLogEffects = async ({
     data,
     date,
     bundleId,
+    fromAddress,
   })
 
   // Fallback to basic logic that only handles transfers + fee decoding
@@ -167,6 +174,7 @@ const operationTxLogSideEffects = async ({
   data,
   date,
   bundleId,
+  fromAddress,
 }) => {
   // Matic Delegate
   if (
@@ -188,6 +196,47 @@ const operationTxLogSideEffects = async ({
     })
   }
 
+  // Ethereum Undelegate
+  if (
+    isEthereumStakingPoolContract(txToAddress) &&
+    methodId === EthereumStaking.METHODS_IDS.UNSTAKE_PENDING
+  ) {
+    return ethereumUnstakePendingOptimisticSideEffectTxLogs({
+      asset,
+      walletAccount,
+      feeAmount,
+      unstakePendingTxId: txId,
+      nonce,
+      estimatedUnstakePendingGasLimit: gasLimit,
+      tipGasPrice,
+      transactionData: data,
+      txToAddress,
+      date,
+      bundleId,
+    })
+  }
+
+  // Ethereum Undelegate (unstake from active validator)
+  if (
+    isEthereumStakingPoolContract(txToAddress) &&
+    methodId === EthereumStaking.METHODS_IDS.UNSTAKE
+  ) {
+    return ethereumUnstakeOptimisticSideEffectTxLogs({
+      asset,
+      walletAccount,
+      feeAmount,
+      unstakeTxId: txId,
+      nonce,
+      estimatedUnstakeGasLimit: gasLimit,
+      tipGasPrice,
+      transactionData: data,
+      txToAddress,
+      fromAddress,
+      date,
+      bundleId,
+    })
+  }
+
   // Add other officially supported operations here
   // Then can fallback to simulation results (TODO)
   // Then finally to the default basic logic

package/src/tx-type/index.js

@@ -35,7 +35,8 @@ export const assertCriticalTxAttributes = (criticalTxAttributes) => {
 
   assert(amount instanceof NumberUnit, 'expected NumberUnit amount')
   assert(
-    typeof txInput === 'string' && txInput.startsWith('0x', 'expected hexadecimal string txInput')
+    typeof txInput === 'string' && txInput.startsWith('0x'),
+    'expected hexadecimal string txInput'
   )
   assert(isValidTxType(txType), 'expected valid txType')
   assert(txValue instanceof NumberUnit, 'expected NumberUnit txValue')