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

package/src/create-asset-plugin-factory.js

@@ -0,0 +1,115 @@
+import { createMetaDef } from '@exodus/asset'
+import assert from 'minimalistic-assert'
+
+import { createAssetFactory } from './create-asset.js'
+
+// Move to ethereum-api for config base evm
+export const createAssetPluginFactory = (config) => {
+  assert(config, 'config is required')
+  assert(config.chainId, 'chainId is required')
+  assert(config.meta, 'config.meta is required')
+  assert(config.meta.explorerUrl, 'meta.explorerUrl is required')
+
+  const chainId = config.chainId
+  const { explorerUrl, decimals, ...meta } = config.meta
+  const chainIdHex = '0x' + chainId.toString(16)
+  const name = `evm${chainIdHex}`.toLowerCase()
+  const ticker = name.toUpperCase()
+  const tokenType = `EVM_${chainIdHex}_TOKEN`.toUpperCase()
+
+  const units = {
+    wei: 0,
+    Kwei: 3,
+    Mwei: 6,
+    Gwei: 9,
+    [ticker]: decimals || 18,
+  }
+
+  // adds lots of validation in config
+  const tokenOverrides = (token) => ({
+    ...token,
+    assetId: token.addresses.current.toLowerCase(),
+    assetType: tokenType,
+    contract: token.addresses,
+  })
+
+  const blockExplorer = {
+    addressUrl: (address) => `${explorerUrl}/address/${encodeURIComponent(address)}`,
+    txUrl: (txId) => `${explorerUrl}/tx/${encodeURIComponent(txId)}`,
+  }
+
+  const assetType = 'ETHEREUM_LIKE'
+  const { assetsList } = createMetaDef({
+    assetParams: {
+      ...meta,
+      name,
+      ticker,
+      units,
+      chainId,
+      assetType,
+      blockExplorer,
+    },
+    tokensParams: meta.tokens || [],
+    tokenOverrides,
+  })
+  const feeDataConfig = Object.fromEntries(
+    Object.entries({
+      gasPrice: config.gasPrice,
+      baseFeePerGas: config.baseFeePerGas,
+      eip1559Enabled: config.eip1559Enabled,
+      ...config.feeData,
+    }).filter(([_, value]) => value !== undefined)
+  )
+
+  const createAsset = createAssetFactory({
+    assetsList,
+    feeDataConfig,
+    ...config.plugin,
+  })
+
+  return { name, chainId, createAsset }
+}
+
+// https://docs.metamask.io/wallet/reference/wallet_addethereumchain/
+export const fromAddEthereumChainParameterToFactoryParams = (params) => {
+  assert(params.chainId, 'chainId is required')
+  assert(params.chainName, 'chainName is required')
+  assert(params.rpcUrls?.[0], 'rpcUrls is required')
+  assert(params.blockExplorerUrls?.[0], 'blockExplorerUrls is required')
+  assert(params.nativeCurrency, 'nativeCurrency is required')
+  assert(params.nativeCurrency.symbol, 'nativeCurrency.symbol is required')
+  assert(params.nativeCurrency.decimals, 'nativeCurrency.decimals is required')
+
+  const chainId = parseInt(params.chainId.replace('0x', ''), 16)
+
+  // obvious coloring:)
+  const color =
+    params.color ||
+    '#' +
+      (chainId % 256).toString(16) +
+      ((chainId + 50) % 256).toString(16) +
+      ((chainId + 100) % 256).toString(16)
+  return {
+    chainId,
+    meta: {
+      explorerUrl: params.blockExplorerUrls[0],
+      displayNetworkName: params.chainName,
+      displayName: params.nativeCurrency.name || params.nativeCurrency.symbol,
+      displayTicker: params.nativeCurrency.symbol,
+      decimals: params.nativeCurrency.decimals,
+      primaryColor: color,
+      gradientColors: [color, color],
+    },
+    plugin: {
+      serverUrl: params.rpcUrls?.[0],
+      confirmationsNumber: 5,
+      monitorType: 'no-history',
+      isTestnet: params.isTestnet,
+      ...params.plugin, // extra plugin configuration
+    },
+    feeData: params.feeData,
+    baseFeePerGas: params.baseFeePerGas,
+    gasPrice: params.gasPrice,
+    eip1559Enabled: params.eip1559Enabled,
+  }
+}

package/src/create-asset-utils.js

@@ -0,0 +1,520 @@
+import { BlacklistCheckTypes } from '@exodus/asset-lib'
+import { parseUnsignedTx } from '@exodus/ethereum-lib'
+import { defaultAbiCoder } from '@exodus/ethereumjs/ethers5-abi'
+import { safeString } from '@exodus/safe-string'
+import assert from 'minimalistic-assert'
+import ms from 'ms'
+
+import { EVM_ERROR_REASONS, withErrorReason } from './error-wrapper.js'
+import ClarityServerV2 from './exodus-eth-server/clarity-v2.js'
+import { ValidMonitorTypes } from './exodus-eth-server/index.js'
+import { createEthereumHooks } from './hooks/index.js'
+import {
+  EthLikeMulticall3RpcRequestAccumulator,
+  EthLikeRpcRequestAccumulator,
+} from './multicall3/index.js'
+import { ClarityMonitor } from './tx-log/clarity-monitor.js'
+import { ClarityTruncatedHistoryMonitor } from './tx-log/clarity-truncated-history-monitor.js'
+import { EthereumMonitor } from './tx-log/ethereum-monitor.js'
+import { EthereumNoHistoryMonitor } from './tx-log/ethereum-no-history-monitor.js'
+import { getOptimisticTxLogEffects } from './tx-log/get-optimistic-txlog-effects.js'
+import { BLOCK_TAG_LATEST, BLOCK_TAG_PENDING, resolveNonce } from './tx-send/nonce-utils.js'
+import { signTx } from './tx-sign/index.js'
+
+// Determines the appropriate `monitorType`, `serverUrl` and `monitorInterval`
+// to use for a given config.
+export const resolveMonitorSettings = (
+  {
+    asset,
+    configWithOverrides,
+    defaultMonitorInterval,
+    defaultMonitorType,
+    defaultServerUrl,
+    defaultWsGatewayUri,
+  } = Object.create(null)
+) => {
+  assert(asset, 'expected asset')
+  assert(
+    ValidMonitorTypes.includes(defaultMonitorType),
+    `defaultMonitorType ${defaultMonitorType} for ${asset.name} is invalid.`
+  )
+  assert(defaultServerUrl, `expected default serverUrl for ${asset.name}`)
+
+  // NOTE: When trying to enable `clarity-v3` as an asset
+  //       default config, there must exist a default
+  //       gateway definition.
+  if (defaultMonitorType === 'clarity-v3') {
+    assert(defaultWsGatewayUri, 'expected defaultWsGatewayUri')
+  }
+
+  const overrideMonitorType = configWithOverrides?.monitorType
+  const overrideServerUrl = configWithOverrides?.serverUrl
+  const overrideMonitorInterval = configWithOverrides?.monitorInterval
+  const overrideWsGatewayUri = configWithOverrides?.wsGatewayUri
+
+  const defaultResolution = {
+    // NOTE: Regardless of the `monitorType`, the `monitorInterval`
+    //       will be respected.
+    monitorInterval: overrideMonitorInterval ?? defaultMonitorInterval,
+    monitorType: defaultMonitorType,
+    serverUrl: defaultServerUrl,
+    wsGatewayUri: defaultWsGatewayUri,
+  }
+
+  const fallbackWithWarning = (msg) => {
+    console.debug([msg, `Falling back to ${defaultMonitorType}<${defaultServerUrl}>.`].join(' '))
+    return defaultResolution
+  }
+
+  if (!overrideMonitorType && overrideServerUrl) {
+    return fallbackWithWarning(
+      `Received an \`overrideServerUrl\`, but not the \`monitorType\` for ${asset.name}.`
+    )
+  }
+
+  // If we don't attempt to override the `monitorType`, we resort
+  // to the default configuration.
+  if (!overrideMonitorType) return defaultResolution
+
+  if (!ValidMonitorTypes.includes(overrideMonitorType)) {
+    return fallbackWithWarning(`"${overrideMonitorType}" is not a valid \`MonitorType\`.`)
+  }
+
+  const wsGatewayUri = overrideWsGatewayUri || defaultWsGatewayUri
+
+  if (overrideMonitorType === 'clarity-v3' && !wsGatewayUri) {
+    return fallbackWithWarning(
+      "Attempted to use 'clarity-v3' without a defining a supporting wsGatewayUri."
+    )
+  }
+
+  // Permit the `monitorType` and `serverUrl` to be overrided.
+  return {
+    ...defaultResolution,
+    monitorType: overrideMonitorType,
+    serverUrl: overrideServerUrl,
+    wsGatewayUri,
+  }
+}
+
+export const stringifyPrivateTx = (tx) => {
+  assert(tx, 'expected tx')
+  if (tx instanceof Uint8Array) return `0x${Buffer.from(tx).toString('hex')}`
+
+  assert(typeof tx === 'string', 'expected string')
+  if (tx.startsWith('0x')) return tx
+
+  return `0x${tx}`
+}
+
+const assertSendPrivateTxProps = ({ asset, unsignedTx, walletAccount }) => {
+  assert(asset, 'expected asset')
+  assert(unsignedTx, 'expected unsignedTx')
+  assert(walletAccount, 'expected walletAccount')
+}
+
+// Block builders drop private transactions that carry no bid — accepted by
+// the relay but never included on chain (ExodusMovement/assets#8084). The
+// effective bid is min(tipGasPrice, gasPrice - baseFeePerGas): `gasPrice` is
+// the maxFeePerGas ceiling for EIP-1559 transactions and the all-in price
+// for legacy ones, so either term at zero kills the bid.
+const assertNonZeroTipGasPrice = async ({ asset, assetClientInterface, unsignedTx }) => {
+  const { eip1559Enabled, gasPrice, tipGasPrice } = parseUnsignedTx({ asset, unsignedTx })
+
+  if (eip1559Enabled && (!tipGasPrice || tipGasPrice.isZero)) {
+    throw new Error(
+      'ERR_PRIVATE_TX_ZERO_TIP: transaction pays no tipGasPrice; block builders drop zero-bid private transactions'
+    )
+  }
+
+  const feeData = await assetClientInterface.getFeeConfig({ assetName: asset.baseAsset.name })
+  const baseFeePerGas = feeData?.baseFeePerGas
+  if (!baseFeePerGas || gasPrice.gt(baseFeePerGas)) return
+
+  throw new Error(
+    `ERR_PRIVATE_TX_ZERO_TIP: transaction gasPrice (${gasPrice.toBaseString()}) does not exceed baseFeePerGas (${baseFeePerGas.toBaseString()}); block builders drop zero-bid private transactions`
+  )
+}
+
+export const createTransactionPrivacyResult = ({
+  assetClientInterface,
+  broadcastPrivateBundle,
+  broadcastPrivateTx,
+}) => {
+  assert(assetClientInterface, 'expected assetClientInterface')
+  assert(typeof broadcastPrivateBundle === 'function')
+  assert(typeof broadcastPrivateTx === 'function')
+
+  const sendPrivateTx = async ({ asset, unsignedTx, walletAccount }) => {
+    assertSendPrivateTxProps({ asset, unsignedTx, walletAccount })
+    await assertNonZeroTipGasPrice({ asset, assetClientInterface, unsignedTx })
+
+    const { rawTx, txId } = await signTx({
+      asset,
+      assetClientInterface,
+      unsignedTx,
+      walletAccount,
+    })
+
+    await broadcastPrivateTx(rawTx.toString('hex'))
+
+    const fromAddress = unsignedTx.txMeta?.fromAddress
+    assert(typeof fromAddress === 'string', 'expected fromAddress')
+
+    const { nonce, optimisticTxLogEffects } = await getOptimisticTxLogEffects({
+      asset,
+      assetClientInterface,
+      fromAddress,
+      txId,
+      unsignedTx,
+      walletAccount,
+    })
+
+    for (const optimisticTxLogEffect of optimisticTxLogEffects) {
+      await assetClientInterface.updateTxLogAndNotify(optimisticTxLogEffect)
+    }
+
+    return { nonce, txId }
+  }
+
+  const sendPrivateBundle = async ({ unsignedTxBundle }) => {
+    assert(
+      Array.isArray(unsignedTxBundle) && unsignedTxBundle.length > 0,
+      'expected non-empty unsignedTxBundle'
+    )
+
+    unsignedTxBundle.forEach(assertSendPrivateTxProps)
+
+    for (const { asset, unsignedTx } of unsignedTxBundle) {
+      await assertNonZeroTipGasPrice({ asset, assetClientInterface, unsignedTx })
+    }
+
+    const signTxResults = await Promise.all(
+      unsignedTxBundle.map(({ asset, unsignedTx, walletAccount }) =>
+        signTx({ assetClientInterface, asset, unsignedTx, walletAccount })
+      )
+    )
+
+    const maybeBundleResult = await broadcastPrivateBundle({
+      txs: signTxResults.map(({ rawTx }) => rawTx.toString('hex')),
+    })
+
+    const bundleHash = maybeBundleResult?.bundleHash || undefined
+
+    const getOptimisticTxLogEffectsResults = []
+
+    for (const [i, { txId }] of signTxResults.entries()) {
+      const { asset, unsignedTx, walletAccount } = unsignedTxBundle[i]
+
+      const fromAddress = unsignedTx.txMeta?.fromAddress
+      assert(typeof fromAddress === 'string', 'expected fromAddress')
+
+      void getOptimisticTxLogEffectsResults.push(
+        await getOptimisticTxLogEffects({
+          asset,
+          assetClientInterface,
+          fromAddress,
+          txId,
+          unsignedTx,
+          walletAccount,
+          // TODO: use consistent naming
+          bundleId: bundleHash,
+        })
+      )
+    }
+
+    const optimisticTxLogEffects = getOptimisticTxLogEffectsResults.flatMap(
+      ({ optimisticTxLogEffects }) => optimisticTxLogEffects
+    )
+
+    for (const optimisticTxLogEffect of optimisticTxLogEffects) {
+      await assetClientInterface.updateTxLogAndNotify(optimisticTxLogEffect)
+    }
+
+    return {
+      bundleHash,
+      txIds: signTxResults.map(({ txId }) => txId),
+    }
+  }
+
+  return {
+    broadcastPrivateBundle,
+    broadcastPrivateTx,
+    sendPrivateTx,
+    sendPrivateBundle,
+  }
+}
+
+export const createTransactionPrivacyFactory = ({
+  assetClientInterface,
+  assetName,
+  server,
+  supportsTransactionPrivacy,
+}) => {
+  assert(assetClientInterface, 'expected assetClientInterface')
+  assert(server, 'expected server')
+
+  if (!supportsTransactionPrivacy) return Object.create(null)
+
+  if (!(server instanceof ClarityServerV2)) {
+    console.warn(
+      `attempted to enable transactionPrivacy for ${assetName} but provided server is incompatible`
+    )
+    return Object.create(null)
+  }
+
+  const broadcastPrivateBundle = async ({ txs }) => {
+    assert(Array.isArray(txs), 'txs must be an array')
+    assert(txs.length > 0, 'txs must be a non-empty array')
+
+    const sendBundleResult = await server.sendBundle({
+      txs: txs.map((tx) => stringifyPrivateTx(tx)),
+    })
+    if (typeof sendBundleResult === 'string') return { bundleHash: sendBundleResult }
+
+    const bundleHash = sendBundleResult?.bundleHash
+    if (typeof bundleHash === 'string') return { bundleHash }
+
+    console.warn('unexpected sendBundleResult shape, cannot determine bundle hash')
+    return null
+  }
+
+  const broadcastPrivateTx = (tx) => broadcastPrivateBundle({ txs: [tx] })
+
+  return createTransactionPrivacyResult({
+    assetClientInterface,
+    broadcastPrivateBundle,
+    broadcastPrivateTx,
+  })
+}
+
+export const createRpcRequestAccumulatorFactory =
+  ({ multicall3Address }) =>
+  () =>
+    multicall3Address
+      ? new EthLikeMulticall3RpcRequestAccumulator({ multicall3Address })
+      : new EthLikeRpcRequestAccumulator()
+
+export const createHistoryMonitorFactory = ({
+  assetName,
+  assetClientInterface,
+  monitorInterval,
+  monitorType,
+  server,
+  stakingConfiguration,
+  rpcBalanceAssetNames,
+  eip7702Whitelist,
+  getBlackListStatus,
+}) => {
+  assert(assetName, 'expected assetName')
+  assert(assetClientInterface, 'expected assetClientInterface')
+  assert(monitorType, 'expected monitorType')
+  assert(server, 'expected server')
+  assert(
+    stakingConfiguration &&
+      typeof stakingConfiguration === 'object' &&
+      !Array.isArray(stakingConfiguration),
+    'expected object stakingConfiguration'
+  )
+
+  return (args) => {
+    let monitor
+    switch (monitorType) {
+      case 'clarity-v3':
+        console.debug('clarity-v3 is no longer supported, falling back to clarity-v2')
+      // eslint-disable-next-line no-fallthrough
+      case 'clarity':
+      case 'clarity-v2':
+        monitor = new ClarityMonitor({
+          assetClientInterface,
+          interval: ms(monitorInterval || '5m'),
+          server,
+          rpcBalanceAssetNames,
+          eip7702Whitelist,
+          getBlackListStatus,
+          ...args,
+        })
+        break
+      case 'clarity-truncated-history':
+        monitor = new ClarityTruncatedHistoryMonitor({
+          assetClientInterface,
+          interval: ms(monitorInterval || '5m'),
+          server,
+          eip7702Whitelist,
+          getBlackListStatus,
+          ...args,
+        })
+        break
+      case 'no-history':
+        monitor = new EthereumNoHistoryMonitor({
+          assetClientInterface,
+          interval: ms(monitorInterval || '15s'),
+          server,
+          eip7702Whitelist,
+          getBlackListStatus,
+          ...args,
+        })
+        break
+      case 'magnifier':
+        monitor = new EthereumMonitor({
+          assetClientInterface,
+          interval: ms(monitorInterval || '15s'),
+          server,
+          rpcBalanceAssetNames,
+          ...args,
+        })
+        break
+      default:
+        throw new Error(`Monitor type ${monitorType} of evm asset ${assetName} is unknown`)
+    }
+
+    if (Object.keys(stakingConfiguration).length > 0) {
+      const hooks = createEthereumHooks({
+        assetClientInterface,
+        assetName,
+        stakingConfiguration,
+        server,
+      })
+      for (const [name, hook] of Object.entries(hooks)) monitor.addHook(name, hook)
+    }
+
+    return monitor
+  }
+}
+
+export const createSecurityChecks = ({ eip7702Whitelist }) => {
+  return ({ accountState }) => {
+    // Always return global scam findings before lower-severity checks because
+    // global checks can block the app at startup.
+    if (accountState?.isBlacklisted) {
+      return {
+        isSecure: false,
+        type: 'GLOBAL_SCAM',
+        reason: 'Account is globally blacklisted.',
+      }
+    }
+
+    const delegation = accountState?.eip7702Delegation
+    if (
+      eip7702Whitelist.isSupported() &&
+      Boolean(delegation?.isDelegated) &&
+      !delegation?.isWhitelisted
+    ) {
+      return {
+        isSecure: false,
+        type: 'LOST_PERMISSIONS',
+        reason: 'Account is delegated to a non-whitelisted EIP-7702 address.',
+      }
+    }
+
+    return {
+      isSecure: true,
+      type: null,
+      reason: null,
+    }
+  }
+}
+
+export const getNonceFactory = ({ assetClientInterface, useAbsoluteBalanceAndNonce }) => {
+  assert(assetClientInterface, 'expected assetClientInterface')
+  assert(typeof useAbsoluteBalanceAndNonce === 'boolean', 'expected useAbsoluteBalanceAndNonce')
+
+  const getNonce = async ({
+    asset,
+    fromAddress,
+    walletAccount,
+    forceFromNode,
+    // NOTE: By default, Exodus assumes the client will by default want
+    //       to send transactions on top of those which are currently
+    //       pending at the public mempool.
+    tag = BLOCK_TAG_PENDING,
+  }) => {
+    assert(asset, 'expected asset')
+    assert(typeof fromAddress === 'string', 'expected fromAddress')
+    assert(walletAccount, 'expected walletAccount')
+
+    const [txLog, accountState] = await Promise.all([
+      assetClientInterface.getTxLog({
+        assetName: asset.baseAsset.name,
+        walletAccount,
+      }),
+      assetClientInterface.getAccountState({
+        assetName: asset.baseAsset.name,
+        walletAccount,
+      }),
+    ])
+
+    return resolveNonce({
+      asset,
+      fromAddress,
+      txLog,
+      accountState,
+      forceFromNode,
+      tag,
+      useAbsoluteNonce: useAbsoluteBalanceAndNonce,
+    })
+  }
+
+  return { getNonce }
+}
+
+// Creates a contract-based blacklist check function.
+// async ({ address }) => boolean
+export const createContractBlackListCheck = ({ contractAddress, selector, server }) => {
+  assert(contractAddress, 'expected contractAddress')
+  assert(selector, 'expected selector')
+  assert(server, 'expected server')
+
+  return async ({ address }) => {
+    const tag = BLOCK_TAG_LATEST
+    const encodedAddress = address.slice(2).toLowerCase().padStart(64, '0')
+    const data = selector + encodedAddress
+    const result = await withErrorReason({
+      promise: server.ethCall({ to: contractAddress, data }, tag),
+      errorReasonInfo: EVM_ERROR_REASONS.ethCallErc20Failed,
+      hint: safeString`getBlackListStatus:ethCall`,
+      baseAssetName: server.baseAssetName,
+    })
+
+    if (typeof result !== 'string' || result.length === 0) {
+      throw new Error('getBlackListStatus got invalid ethCall response')
+    }
+
+    let isBlacklisted
+    try {
+      ;[isBlacklisted] = defaultAbiCoder.decode(['bool'], result)
+    } catch (err) {
+      throw new Error(`getBlackListStatus got invalid ABI bool result: ${err.message}`)
+    }
+
+    return isBlacklisted
+  }
+}
+
+// Composes blacklist check factories into a single getBlackListStatus.
+// Returns undefined if no checks are provided.
+// Returns { isBlacklisted: true } if ANY check returns true.
+// NOTE: blacklistChecks defaults to [] as a convenience, but it is the asset's responsibility
+// to be properly configured with the appropriate checks. An empty array means no blacklist
+// checks are run, which implies EIP-7702 is effectively enabled on that network with no whitelist.
+export const createGetBlackListStatus = ({ address: addressApi, blacklistChecks = [], server }) => {
+  if (blacklistChecks.length === 0) return
+
+  assert(addressApi, 'expected address')
+
+  // Extend here to support additional blacklist sources (e.g. an internal database query).
+  const checks = blacklistChecks.map((factory) => {
+    if (factory.type === BlacklistCheckTypes.CONTRACT_CALL) {
+      assert(server, 'expected server for CONTRACT_CALL blacklist check')
+      return factory({ server })
+    }
+
+    throw new Error(`Unknown blacklist check type: ${factory.type}`)
+  })
+
+  return async ({ address }) => {
+    assert(addressApi.validate(address), 'getBlackListStatus requires a valid Ethereum address')
+    const results = await Promise.all(checks.map((check) => check({ address })))
+    return { isBlacklisted: results.some(Boolean) }
+  }
+}