@exodus/ethereum-api 8.73.1 → 8.73.3

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 }) {