@exodus/ethereum-api 9.0.0-alpha.2 → 9.0.0

package/src/staking/ethereum/api.js

@@ -1,11 +1,24 @@
 import { createContract } from '@exodus/ethereum-lib'
+import { bufferToHex } from '@exodus/ethereumjs/util'
+import { safeString } from '@exodus/safe-string'
 import { retry } from '@exodus/simple-retry'
-import { bufferToHex } from '@exodus/ethereumjs-util'
 import assert from 'minimalistic-assert'
 
+import { EVM_ERROR_REASONS, withErrorReason } from '../../error-wrapper.js'
+import { EthLikeRpcRequestAccumulator } from '../../multicall3/index.js'
+import { createCachedStakingRead } from '../cached-read.js'
+
+// TODO: Shouldn't this be a function of `ethereumStakingState.minDelegateAmount`?
 const MIN_AMOUNT = '0.1'
 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: {
@@ -16,10 +29,6 @@ export class EthereumStaking {
       EVERSTAKE_ADDRESS_CONTRACT_ACCOUNTING: '0x6e95818C2Dde3d87406F5C5d0A759d9372053a94',
       EVERSTAKE_ADDRESS_CONTRACT_POOL: '0x1F28aD3B3e26192a09c1248D4092c692c32f8Ec0',
     },
-    ethereumholesky: {
-      EVERSTAKE_ADDRESS_CONTRACT_ACCOUNTING: '0x624087DD1904ab122A32878Ce9e933C7071F53B9',
-      EVERSTAKE_ADDRESS_CONTRACT_POOL: '0xAFA848357154a6a624686b348303EF9a13F63264',
-    },
   }
 
   static METHODS_IDS = {
@@ -27,54 +36,111 @@ export class EthereumStaking {
     UNSTAKE: '0x76ec871c', // unstake(uint256 amount)
     UNSTAKE_PENDING: '0xed0723d4', // unstakePending(uint256 amount)
     CLAIM_UNSTAKE: '0x33986ffa', // claimWithdrawRequest(uint256 amount)
+    DEPOSIT: '0x47e7ef24', // deposit(address staker, uint256 amount)
   }
 
-  constructor({
-    asset, // ethereum or ethereumholesky for testnet
-    minAmount = MIN_AMOUNT,
-    server,
-  }) {
-    assert(server, 'server is required')
-    this.asset = asset
+  static isDelegationTransactonCalldata = (txInput) => {
+    const txInputHex = (Buffer.isBuffer(txInput) ? bufferToHex(txInput) : txInput) || '0x'
+    if (typeof txInputHex !== 'string') throw new Error('expected string')
+
+    return txInputHex.toLowerCase().startsWith(EthereumStaking.METHODS_IDS.DELEGATE)
+  }
+
+  constructor(assetName, currency, minAmount = MIN_AMOUNT, server) {
+    this.asset = { name: assetName, currency }
     const accountingAddress =
-      EthereumStaking.addresses[asset.name].EVERSTAKE_ADDRESS_CONTRACT_ACCOUNTING
-    const poolAddress = EthereumStaking.addresses[asset.name].EVERSTAKE_ADDRESS_CONTRACT_POOL
+      EthereumStaking.addresses[assetName].EVERSTAKE_ADDRESS_CONTRACT_ACCOUNTING
+    const poolAddress = EthereumStaking.addresses[assetName].EVERSTAKE_ADDRESS_CONTRACT_POOL
 
     this.contractAccounting = createContract(accountingAddress, 'ethStakingAccounting')
     this.contractPool = createContract(poolAddress, 'ethStakingPool')
     this.accountingAddress = accountingAddress
     this.poolAddress = poolAddress
-    this.minAmount = asset.currency.defaultUnit(minAmount)
+    this.minAmount = currency.defaultUnit(minAmount)
     this.server = server
   }
 
-  buildTxData = (contract, method, ...args) => {
+  #buildTxData = (contract, method, ...args) => {
     return contract[method].build(...args)
   }
 
-  callReadFunctionContract = (contract, method, ...args) => {
-    const callData = this.buildTxData(contract, method, ...args)
+  #callReadFunctionContract = (contract, method, ...args) =>
+    this.#callReadFunctionContractFrom(contract, method, undefined, ...args)
+
+  #callReadFunctionContractFrom = (contract, method, from, ...args) => {
+    const callData = this.#buildTxData(contract, method, ...args)
     const data = {
       data: bufferToHex(callData),
       to: contract.address,
       tag: 'latest',
     }
 
+    if (typeof from === 'string' && from.length > 0) data.from = from
+
     const eth = this.server
-    return retry(eth.ethCall, { delayTimesMs: RETRY_DELAYS })(data)
+    assert(eth, 'server is required')
+    return withErrorReason({
+      promise: retry((...args) => eth.ethCall(...args), { delayTimesMs: RETRY_DELAYS })(data),
+      errorReasonInfo: EVM_ERROR_REASONS.ethCallFailed,
+      hint: safeString`stakingEthReadFunctionContract`,
+      baseAssetName: eth.baseAssetName,
+    })
   }
 
+  // Do not use Multicall for these reads without verifying the deployed Accounting
+  // implementation (currently unverified). JSON-RPC batching preserves msg.sender
+  // and isolated eth_call execution, including autocompound simulation semantics.
+  async getStakingState(address) {
+    const read = () => {
+      const requests = new EthLikeRpcRequestAccumulator()
+      for (const method of [
+        'autocompoundBalanceOf',
+        'pendingBalanceOf',
+        'pendingDepositedBalanceOf',
+        'withdrawRequest',
+      ]) {
+        requests.contractStaticCallRequest(this.contractAccounting, method, address)
+      }
+      assert(this.server, 'server is required')
+      return requests.flush(this.server)
+    }
+    const [[active], [pending], [deposited], [requested, readyForClaim]] = await withErrorReason({
+      promise: retry(read, { delayTimesMs: RETRY_DELAYS })(),
+      errorReasonInfo: EVM_ERROR_REASONS.ethCallFailed,
+      hint: safeString`stakingEthReadFunctionContract`,
+      baseAssetName: this.asset.name,
+    })
+    const { currency } = this.asset
+    return {
+      activeStakedBalance: currency.baseUnit(active),
+      pendingBalance: currency.baseUnit(pending),
+      pendingDepositedBalance: currency.baseUnit(deposited),
+      withdrawRequest: {
+        requested: currency.baseUnit(requested),
+        readyForClaim: currency.baseUnit(readyForClaim),
+        canSendClaimRequest: requested !== '0' && requested === readyForClaim,
+      },
+    }
+  }
+
+  getCachedTotalRewards = createCachedStakingRead({
+    read: (address) => this.getTotalRewards(address, { throwOnError: true }),
+  })
+
   // === ACCOUNTING ===
 
   /** Return total deposited and activated pool balance */
   async poolsBalance() {
-    const totalPoolBalance = await this.callReadFunctionContract(this.contractAccounting, 'balance')
+    const totalPoolBalance = await this.#callReadFunctionContract(
+      this.contractAccounting,
+      'balance'
+    )
     return this.asset.currency.baseUnit(totalPoolBalance)
   }
 
   /** Return pool pending balance. Always < 32 ETH */
   async poolPendingBalance() {
-    const pendingBalance = await this.callReadFunctionContract(
+    const pendingBalance = await this.#callReadFunctionContract(
       this.contractAccounting,
       'pendingBalance'
     )
@@ -83,7 +149,7 @@ export class EthereumStaking {
 
   /** Return user pending balance (waiting to be added from the Pool contract to the ETH2 validator) */
   async pendingBalanceOf(address) {
-    let pendingBalance = await this.callReadFunctionContract(
+    let pendingBalance = await this.#callReadFunctionContract(
       this.contractAccounting,
       'pendingBalanceOf',
       address
@@ -94,7 +160,7 @@ export class EthereumStaking {
 
   /** Return total user autocompound balance. Part of this balance could be in pending state after rewards autocompound */
   async autocompoundBalanceOf(address) {
-    const userBalance = await this.callReadFunctionContract(
+    const userBalance = await this.#callReadFunctionContract(
       this.contractAccounting,
       'autocompoundBalanceOf',
       address
@@ -104,7 +170,7 @@ export class EthereumStaking {
 
   /** Return user pending deposited balance. Balance which deposited into validator but not active yet. Pending deposited balance can't be unstake till validator activation */
   async pendingDepositedBalanceOf(address) {
-    const userBalance = await this.callReadFunctionContract(
+    const userBalance = await this.#callReadFunctionContract(
       this.contractAccounting,
       'pendingDepositedBalanceOf',
       address
@@ -114,7 +180,7 @@ export class EthereumStaking {
 
   /** Return user active origin deposited balance */
   async depositedBalanceOf(address) {
-    const depositedBalance = await this.callReadFunctionContract(
+    const depositedBalance = await this.#callReadFunctionContract(
       this.contractAccounting,
       'depositedBalanceOf',
       address
@@ -122,8 +188,8 @@ export class EthereumStaking {
     return this.asset.currency.baseUnit(depositedBalance)
   }
 
-  /* Get earned Rewards */
   async getLiquidRewards(address) {
+    // latest accrued rewards
     const [compoundBalance, depositedBalance] = await Promise.all([
       this.autocompoundBalanceOf(address),
       this.depositedBalanceOf(address),
@@ -131,9 +197,42 @@ export class EthereumStaking {
     return compoundBalance.sub(depositedBalance)
   }
 
+  async getTotalRewards(address, { throwOnError = false } = {}) {
+    // use external everstake API to get total rewards
+    const url = new URL(EVERSTAKE_API_URL)
+
+    const options = {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({
+        address,
+      }),
+    }
+
+    try {
+      const response = await fetch(url.toString(), options)
+      if (!response.ok) throw new Error('Failed to fetch ETH total rewards')
+      const rewards = await response.json()
+      if (rewards === 'address') return this.asset.currency.ZERO // address not found
+      if (
+        !(
+          (typeof rewards === 'string' && /^\d+$/.test(rewards)) ||
+          (Number.isSafeInteger(rewards) && rewards >= 0)
+        )
+      ) {
+        throw new Error('Malformed ETH total rewards')
+      }
+      return this.asset.currency.baseUnit(rewards)
+    } catch (error) {
+      console.warn('Error fetching ETH total rewards:', error)
+      if (throwOnError) throw error
+      return this.asset.currency.ZERO
+    }
+  }
+
   /** Return withdrawable unstaked amount  */
   async withdrawRequest(address) {
-    let amounts = await this.callReadFunctionContract(
+    let amounts = await this.#callReadFunctionContract(
       this.contractAccounting,
       'withdrawRequest',
       address
@@ -148,20 +247,53 @@ export class EthereumStaking {
 
   // === POOL ===
 
+  /** Determine the effects of a deposit operation by mocking a transaction from the Everstake Pool contract, which can be used to estimate slippage. */
+  async getDepositEffects(depositorAddress, amount) {
+    const { address: from } = this.contractPool
+    const prankDepositReturnData = await this.#callReadFunctionContractFrom(
+      this.contractAccounting,
+      'deposit',
+      from,
+      depositorAddress,
+      amount.toBaseString()
+    )
+    const [interchangedAmount, activatedSlots] =
+      this.contractAccounting.deposit.parse(prankDepositReturnData)
+
+    return {
+      interchangedAmount: this.asset.currency.baseUnit(interchangedAmount),
+      activatedSlots: BigInt(activatedSlots),
+    }
+  }
+
   async stake({ amount, source = '2' }) {
     if (amount.gte(this.minAmount)) {
       return {
         to: this.poolAddress,
         amount,
-        data: bufferToHex(this.buildTxData(this.contractPool, 'stake', source)), // tx data field
+        data: bufferToHex(this.#buildTxData(this.contractPool, 'stake', source)), // tx data field
       }
     }
 
     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)
 
@@ -170,7 +302,7 @@ export class EthereumStaking {
         to: this.poolAddress,
         amount: this.asset.currency.ZERO,
         data: bufferToHex(
-          this.buildTxData(this.contractPool, 'unstake', amountWei, allowedInterchangeNum, source)
+          this.#buildTxData(this.contractPool, 'unstake', amountWei, allowedInterchangeNum, source)
         ),
       }
     }
@@ -186,7 +318,7 @@ export class EthereumStaking {
         return {
           to: this.accountingAddress,
           amount: this.asset.currency.ZERO,
-          data: bufferToHex(this.buildTxData(this.contractAccounting, 'claimWithdrawRequest')),
+          data: bufferToHex(this.#buildTxData(this.contractAccounting, 'claimWithdrawRequest')),
         }
       }
 
@@ -206,13 +338,13 @@ export class EthereumStaking {
         return {
           to: this.poolAddress,
           amount: this.asset.currency.ZERO,
-          data: bufferToHex(this.buildTxData(this.contractPool, 'unstakePending', amountWei)),
+          data: bufferToHex(this.#buildTxData(this.contractPool, 'unstakePending', amountWei)),
         }
       } catch (err) {
         throw new Error(err)
       }
     } else {
-      throw new Error(`Min Amount ${this.minAmount}`)
+      throw new Error(`Max Amount for unstakePending ${pendingBalance}`)
     }
   }
 }

package/src/staking/ethereum/deps.js

@@ -0,0 +1,37 @@
+import { EthereumStaking } from './api.js'
+import { createEthereumStakingService, getEthereumStakingInfo } from './service.js'
+
+/** Staking server factory for ethereum (used by stakingApiFactory). */
+export const stakingServerFactory = ({ assetName, currency, server, minAmount }) =>
+  new EthereumStaking(assetName, currency, minAmount, server)
+
+/** Staking service factory for ethereum (used by stakingApiFactory). */
+export const stakingServiceFactory = ({ assetClientInterface, server, stakingServer }) => {
+  const service = createEthereumStakingService({
+    assetName: stakingServer.asset.name,
+    assetClientInterface,
+  })
+
+  return {
+    ...service,
+    getStakingInfo: ({ address, useCache = false, useQueueCache = useCache, background = false }) =>
+      getEthereumStakingInfo({
+        address,
+        asset: stakingServer.asset,
+        server,
+        staking: stakingServer,
+        useCache,
+        useQueueCache,
+        background,
+      }),
+    stake: service.delegate,
+    unstake: service.undelegate,
+    claimUnstaked: service.claimUndelegatedBalance,
+  }
+}
+
+/** Staking deps for ethereum base asset (plugin can pass as stakingDependencies.ethereum). */
+export const ethereumStakingDeps = {
+  stakingServerFactory,
+  stakingServiceFactory,
+}

package/src/staking/ethereum/everstake.js

@@ -0,0 +1,113 @@
+import { fetch as exodusFetch } from '@exodus/fetch'
+import { TraceId } from '@exodus/traceparent'
+import assert from 'minimalistic-assert'
+
+import { createCachedStakingRead } from '../cached-read.js'
+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()
+
+  const response = await exodusFetch(url, config)
+
+  const newErrorWithTrace = (msg) => {
+    const error = new Error(msg)
+    error.traceId = TraceId.fromResponse(response)
+    return error
+  }
+
+  if (!response.ok) throw newErrorWithTrace(`failed to fetch ${path}`)
+
+  const data = await response.json()
+
+  if (!data || typeof data !== 'object') throw newErrorWithTrace('malformed response')
+
+  return data
+}
+
+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
+  }
+}
+
+// The queue is global, not delegator-specific. Share successful background reads
+// across wallets; explicit refreshes bypass both its deadline and in-flight work.
+export const getCachedEverstakeValidatorsQueue = createCachedStakingRead({
+  read: () => getEverstakeValidatorsQueue(),
+})
+
+export const getEverstakeValidatorsQueue = async () => {
+  // https://swagger.eth-api-b2c.everstake.one/#/Staking/validatorsQueue
+  const result = await fetch('v1/validators/queue')
+
+  const {
+    // Estimated time in seconds of delay before validator become active
+    validator_activation_time: validatorActivationTime,
+    // Estimated time in seconds of delay before validator become exited
+    validator_exit_time: validatorExitTime,
+    // Withdraw period in seconds from Beacon chain
+    validator_withdraw_time: validatorWithdrawTime,
+  } = result
+
+  assert(isFiniteInteger(validatorActivationTime), 'expected integer validatorActivationTime')
+  assert(isFiniteInteger(validatorExitTime), 'expected integer validatorExitTime')
+  assert(isFiniteInteger(validatorWithdrawTime), 'expected integer validatorWithdrawTime')
+
+  // NOTE: We convert the values into milliseconds for
+  //       normalized handling on clients.
+  return {
+    validatorActivationTime: validatorActivationTime * 1000,
+    validatorExitTime: validatorExitTime * 1000,
+    validatorWithdrawTime: validatorWithdrawTime * 1000,
+  }
+}

package/src/staking/ethereum/index.js

@@ -1,3 +1,4 @@
-export * from './staking-utils'
-export * from './api'
-export * from './service'
+export * from './staking-utils.js'
+export * from './api.js'
+export * from './service.js'
+export { ethereumStakingDeps } from './deps.js'