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

package/LICENSE

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

package/README.md

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

package/package.json

@@ -1,7 +1,8 @@
 {
   "name": "@exodus/ethereum-api",
-  "version": "9.0.0-alpha.2",
-  "description": "Ethereum Api",
+  "version": "9.0.0",
+  "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",
   "files": [
     "src",
@@ -9,55 +10,54 @@
     "!src/**/__tests__"
   ],
   "author": "Exodus Movement, Inc.",
-  "license": "UNLICENSED",
+  "license": "MIT",
   "homepage": "https://github.com/ExodusMovement/assets/tree/master/ethereum/ethereum-api",
   "publishConfig": {
-    "access": "restricted"
+    "access": "public",
+    "provenance": false
   },
   "scripts": {
-    "test": "run -T jest",
-    "lint": "run -T eslint .",
-    "lint:fix": "yarn lint --fix"
+    "test": "exodus-test --jest"
   },
   "dependencies": {
-    "@exodus/asset-lib": "^4.2.0",
-    "@exodus/assets": "^9.1.1",
-    "@exodus/basic-utils": "^2.1.0",
+    "@exodus/asset": "^2.0.4",
+    "@exodus/asset-lib": "^5.9.2",
+    "@exodus/assets": "^11.4.0",
+    "@exodus/basic-utils": "^3.0.1",
     "@exodus/bip44-constants": "^195.0.0",
-    "@exodus/crypto": "^1.0.0-rc.0",
-    "@exodus/currency": "^2.1.3",
-    "@exodus/ethereum-lib": "^5.0.0",
-    "@exodus/ethereum-meta": "^1.5.1",
-    "@exodus/ethereumholesky-meta": "^1.0.3",
-    "@exodus/ethereumjs-util": "^7.1.0-exodus.7",
+    "@exodus/crypto": "^1.0.0-rc.26",
+    "@exodus/currency": "^6.0.1",
+    "@exodus/ethereum-lib": "^5.25.0",
+    "@exodus/ethereum-meta": "^2.9.1",
+    "@exodus/ethereumjs": "^1.11.0",
     "@exodus/fetch": "^1.3.0",
-    "@exodus/key-utils": "^3.1.0",
-    "@exodus/models": "^11.0.0",
+    "@exodus/models": "^13.0.0",
+    "@exodus/safe-string": "^1.4.0",
+    "@exodus/send-validation-model": "^1.2.0",
     "@exodus/simple-retry": "^0.0.6",
-    "@exodus/solidity-contract": "^1.1.3",
-    "@exodus/web3-ethereum-utils": "^3.27.1",
+    "@exodus/solidity-contract": "^1.3.0",
+    "@exodus/traceparent": "^3.0.1",
+    "@exodus/web3-utils": "^1.51.2",
     "bn.js": "^5.2.1",
+    "delay": "^4.0.1",
+    "eventemitter3": "^4.0.7",
     "events": "^1.1.1",
     "idna-uts46-hx": "^2.3.1",
-    "js-sha3": "^0.8.0",
     "lodash": "^4.17.15",
     "make-concurrent": "^4.0.0",
     "minimalistic-assert": "^1.0.1",
     "ms": "^2.1.1",
-    "socket.io-client": "^2.1.1",
-    "ws": "^6.1.0"
+    "socket.io-client": "^2.1.1"
   },
   "devDependencies": {
-    "@exodus/assets": "^9.1.1",
     "@exodus/assets-testing": "^1.0.0",
-    "@exodus/bsc-meta": "^1.2.2",
-    "@exodus/ethereumarbone-meta": "^1.2.0",
-    "@exodus/ethereumgoerli-meta": "^1.0.5",
-    "@exodus/ethereumsepolia-meta": "^1.0.3",
-    "@exodus/fantommainnet-meta": "^1.1.2",
-    "@exodus/rootstock-meta": "^1.0.7",
-    "cross-fetch": "^3.1.5",
-    "delay": "4.0.1"
+    "@exodus/bsc-meta": "^2.5.1",
+    "@exodus/errors": "^3.8.0",
+    "@exodus/ethereumarbone-meta": "^2.1.2",
+    "@exodus/fantommainnet-meta": "^2.0.5",
+    "@exodus/matic-meta": "^2.2.7",
+    "@exodus/rootstock-meta": "^2.0.5",
+    "@exodus/send-validation": "^5.4.1"
   },
   "bugs": {
     "url": "https://github.com/ExodusMovement/assets/issues?q=is%3Aissue+is%3Aopen+label%3Aethereum-api"
@@ -65,5 +65,6 @@
   "repository": {
     "type": "git",
     "url": "git+https://github.com/ExodusMovement/assets.git"
-  }
+  },
+  "gitHead": "92d6cdde313e5244fb05a99b1be964a96f989c3b"
 }

package/src/address-has-history.js

@@ -1,6 +1,10 @@
 export const addressHasHistoryFactory =
   ({ server }) =>
   async (address) => {
-    const history = await server.getHistoryV2(address, { index: 0, limit: 1 })
-    return history.length > 0
+    const [nonceHex, balanceHex] = await Promise.all([
+      server.getTransactionCount(address, 'pending'),
+      server.getBalanceProxied(address, 'latest'),
+    ])
+
+    return Number.parseInt(nonceHex, 16) > 0 || Number.parseInt(balanceHex, 16) > 0
   }

package/src/allowance/constants.js

@@ -2,12 +2,11 @@
 // before setting a non-zero allowance
 export const ZERO_ALLOWANCE_ASSETS = [
   'tetherusd',
-  'aragon',
-  'bancor',
-  'status',
+  'bnt_ethereum_20e5a6cf',
+  'snt_ethereum_181cbd8b',
   'decentraland',
-  'dent',
-  'lidodao',
+  'dent_ethereum_6cf2defc',
+  'ldo_ethereum_6d05833f',
   'enjincoin',
 ]
 

package/src/allowance/index.js

@@ -1,6 +1,11 @@
-import { fetchGasLimit } from '../gas-estimation'
-import { getServer } from '../exodus-eth-server/server-map'
-import { ALLOWANCE_TX_TIMEOUT, APPROVAL_GAS_LIMIT, ZERO_ALLOWANCE_ASSETS } from './constants'
+import { isNumberUnit } from '@exodus/currency'
+import { buffer2currency, createUnsignedTxFactory } from '@exodus/ethereum-lib'
+import { bufferToInt } from '@exodus/ethereumjs/util'
+import assert from 'minimalistic-assert'
+
+import { getServer } from '../exodus-eth-server/index.js'
+import { fetchGasLimit } from '../gas-estimation.js'
+import { ALLOWANCE_TX_TIMEOUT, APPROVAL_GAS_LIMIT, ZERO_ALLOWANCE_ASSETS } from './constants.js'
 
 export const isZeroAllowanceAsset = (assetName) => ZERO_ALLOWANCE_ASSETS.includes(assetName)
 
@@ -27,62 +32,177 @@ export async function isSpendingApprovalRequired({
   return tokenAmount.gt(allowance)
 }
 
+export const buildApproveTx = async ({
+  spenderAddress,
+  asset,
+  feeData,
+  fromAddress,
+  approveAmount = asset.currency.ZERO,
+  gasLimit,
+  txInput,
+  nonce,
+  walletAccount,
+}) => {
+  assert(asset, 'expected asset')
+  assert(feeData, 'expected feeData')
+  assert(isNumberUnit(approveAmount), 'expected approveAmount')
+  assert(typeof spenderAddress === 'string', 'expected spenderAddress')
+  assert(walletAccount, 'expected walletAccount')
+
+  const { baseAsset } = asset
+  const chainId = baseAsset.chainId
+  assert(typeof chainId === 'number', 'expected chainId')
+
+  const createUnsignedTx = createUnsignedTxFactory({ chainId })
+
+  const toAddress = asset.contract.address
+  assert(typeof toAddress === 'string', 'expected contract address')
+
+  if (!txInput) txInput = asset.contract.approve.build(spenderAddress, approveAmount.toBaseString())
+
+  if (typeof nonce !== 'number') {
+    nonce = await baseAsset.getNonce({ asset, fromAddress, walletAccount })
+  }
+
+  if (!gasLimit) {
+    gasLimit = await fetchGasLimit({
+      asset: baseAsset,
+      amount: baseAsset.currency.ZERO,
+      toAddress,
+      txInput,
+      feeData,
+      isContract: true,
+      fromAddress,
+    })
+  }
+
+  return createUnsignedTx({
+    asset,
+    address: toAddress,
+    amount: baseAsset.currency.ZERO,
+    nonce,
+    txInput,
+    gasLimit,
+    gasPrice: feeData.gasPrice,
+    tipGasPrice: feeData.tipGasPrice,
+    fromAddress,
+    eip1559Enabled: feeData.eip1559Enabled,
+  })
+}
+
+// @temporary
+// @deprecated use buildApproveTx instead
+export const buildLegacyApproveTx = async ({
+  spenderAddress,
+  asset,
+  feeData,
+  fromAddress,
+  approveAmount,
+  gasLimit,
+  txInput,
+  nonce,
+  walletAccount,
+}) => {
+  const unsignedTx = await buildApproveTx({
+    spenderAddress,
+    asset,
+    feeData,
+    fromAddress,
+    approveAmount,
+    gasLimit,
+    txInput,
+    nonce,
+    walletAccount,
+  })
+
+  const baseAsset = asset.baseAsset
+
+  return {
+    asset: baseAsset,
+    address: unsignedTx.txData.to,
+    amount: buffer2currency({ asset: baseAsset, value: unsignedTx.txData.value }),
+    txInput: unsignedTx.txData.data,
+    gasPrice: buffer2currency({ asset: baseAsset, value: unsignedTx.txData.gasPrice }),
+    tipGasPrice: unsignedTx.txData.tipGasPrice
+      ? buffer2currency({ asset: baseAsset, value: unsignedTx.txData.tipGasPrice })
+      : undefined,
+    gasLimit: bufferToInt(unsignedTx.txData.gasLimit),
+    fromAddress: unsignedTx.txMeta.fromAddress,
+  }
+}
+
+// @deprecated use buildApproveTx instead
 export const createApprove =
-  ({ sendTx }) =>
+  ({ assetClientInterface } = Object.create(null)) =>
   async ({
     spenderAddress,
     asset,
     feeData,
+    fromAddress,
     approveAmount,
     gasLimit,
-    txInput: preTxInput,
-    ...rest
+    txInput,
+    nonce,
+    walletAccount,
+    ...extras
   }) => {
-    const baseAsset = asset.baseAsset
-    const txInput =
-      preTxInput ?? asset.contract.approve.build(spenderAddress, approveAmount.toBaseString())
+    if (!assetClientInterface) {
+      const approveTx = await buildLegacyApproveTx({
+        spenderAddress,
+        asset,
+        feeData,
+        fromAddress,
+        approveAmount,
+        gasLimit,
+        txInput,
+        nonce,
+        walletAccount,
+      })
 
-    const toAddress = asset.contract.address
-    const gasLimitOptions = {
-      asset: baseAsset,
-      amount: baseAsset.currency.ZERO,
-      toAddress,
-      txInput,
-      feeData,
-      isContract: true,
-    }
+      const { unsignedTx } = await asset.baseAsset.api.createTx({
+        walletAccount,
+        ...approveTx,
+        ...extras,
+      })
+      const txData = await asset.baseAsset.api.sendTx({
+        asset: asset.baseAsset,
+        walletAccount,
+        unsignedTx,
+      })
 
-    gasLimit = gasLimit || (await fetchGasLimit(gasLimitOptions))
+      if (!txData || !txData.txId) {
+        throw new Error(`Failed to approve ${asset.displayTicker} - ${spenderAddress}`)
+      }
 
-    const txData = await sendTx({
-      asset: baseAsset.name,
-      receiver: {
-        address: toAddress,
-        amount: baseAsset.currency.ZERO,
-      },
-      txInput,
-      gasPrice: feeData.gasPrice,
+      return txData
+    }
+
+    const unsignedTx = await buildApproveTx({
+      spenderAddress,
+      asset,
+      feeData,
+      fromAddress,
+      approveAmount,
       gasLimit,
-      silent: true,
-      ...rest,
+      txInput,
+      nonce,
+      walletAccount,
     })
 
-    if (!txData || !txData.txId) {
-      throw new Error(`Failed to approve ${asset.displayTicker} - ${spenderAddress}`)
-    }
+    const { txId } = await asset.baseAsset.api.sendTx({ asset, walletAccount, unsignedTx })
 
-    return txData
+    return { txId }
   }
 
 const createSendApprovalAndWatchConfirmation =
-  ({ sendTx, watchTxConfirmation }) =>
+  ({ watchTxConfirmation }) =>
   async (data) => {
     // To change the approve amount you first have to reduce the addresses`
     // allowance to zero by calling `approve(_spender, 0)` if it is not
     // already 0 to mitigate the race condition described here:
     // see: https://github.com/ethereum/EIPs/issues/20#issuecomment-263524729
     // see: https://etherscan.io/address/0xdac17f958d2ee523a2206206994597c13d831ec7#code
-    const approve = createApprove({ sendTx })
+    const approve = createApprove()
     const { txId } = await approve(data)
     await watchTxConfirmation(
       { asset: data.asset.baseAsset.name, walletAccount: data.walletAccount },
@@ -94,11 +214,10 @@ const createSendApprovalAndWatchConfirmation =
   }
 
 export const createApproveSpendingTokens =
-  ({ sendTx, watchTxConfirmation }) =>
+  ({ watchTxConfirmation }) =>
   async (data) => {
     const txIds = []
     const sendApprovalAndWatchConfirmation = createSendApprovalAndWatchConfirmation({
-      sendTx,
       watchTxConfirmation,
     })
     if (ZERO_ALLOWANCE_ASSETS.includes(data.asset.name) && !data.approveAmount.isZero) {
@@ -110,14 +229,14 @@ export const createApproveSpendingTokens =
 
       txIds.push(revokeTokenApprovalTxId)
       // Hardcoded min gas limit. Otherwise `fetchGasLimit` will fail since `approve(_spender, 0)` is not yet confirmed
-      // eslint-disable-next-line @exodus/mutable/no-param-reassign-prop-only
+      // eslint-disable-next-line @exodus/hydra/no-param-reassign-prop-only
       data.gasLimit = Math.max(data.gasLimit || 0, APPROVAL_GAS_LIMIT)
     }
 
-    const tokenApprovalTxId = await sendApprovalAndWatchConfirmation({ ...data, sendTx })
+    const tokenApprovalTxId = await sendApprovalAndWatchConfirmation(data)
     txIds.push(tokenApprovalTxId)
 
     return txIds
   }
 
-export { APPROVAL_GAS_LIMIT, ZERO_ALLOWANCE_ASSETS } from './constants'
+export { APPROVAL_GAS_LIMIT, ZERO_ALLOWANCE_ASSETS } from './constants.js'

package/src/check-tx/create-assess-transaction.js

@@ -0,0 +1,23 @@
+import { fetchival } from '@exodus/fetch'
+import assert from 'minimalistic-assert'
+
+export const DEFAULT_ASSESS_TRANSACTION_API_URL =
+  'https://simulation.a.exodus.io/simulation/transaction/assessment'
+
+export const createAssessTransaction = (
+  { apiUrl = DEFAULT_ASSESS_TRANSACTION_API_URL, headers, request = fetchival } = Object.create(
+    null
+  )
+) => {
+  assert(typeof apiUrl === 'string' && apiUrl.length > 0, 'apiUrl must be a non-empty string')
+
+  return async function assessTransaction({ payload }) {
+    return request(apiUrl, {
+      method: 'POST',
+      headers: {
+        ...headers,
+        'Content-Type': 'application/json',
+      },
+    }).post(payload)
+  }
+}

package/src/check-tx/create-check-tx.js

@@ -0,0 +1,104 @@
+import { memoizeLruCache } from '@exodus/asset-lib'
+import assert from 'minimalistic-assert'
+import ms from 'ms'
+
+const DEFAULT_TIMEOUT_MS = 5000
+const DEFAULT_CACHE_MAX = 500
+// Short TTL to dedupe rapid retypes without holding stale verdicts.
+const DEFAULT_CACHE_TTL_MS = ms('1m')
+const GENERIC_RISK_REASON = 'This transaction was flagged as risky.'
+const RECIPIENT_INVOLVEMENT_TYPES = new Set(['scammer', 'destination'])
+
+const normalizeAddress = (address) => (typeof address === 'string' ? address.toLowerCase() : '')
+
+// `input` and `hash` are part of the key so different calldata gets its own verdict.
+const buildCacheKey = ({ chain, fromAddress, toAddress, value, input, hash }) =>
+  [
+    chain,
+    normalizeAddress(fromAddress),
+    normalizeAddress(toAddress),
+    String(value),
+    input ?? '',
+    hash ?? '',
+  ].join(':')
+
+const isRecipientFinding = ({ finding, recipientAddress }) => {
+  const relatedAssets = Array.isArray(finding?.relatedAssets) ? finding.relatedAssets : []
+  return relatedAssets.some((relatedAsset) => {
+    if (normalizeAddress(relatedAsset?.address) !== normalizeAddress(recipientAddress)) {
+      return false
+    }
+
+    const involvementTypes = Array.isArray(relatedAsset.involvementTypes)
+      ? relatedAsset.involvementTypes
+      : []
+    return involvementTypes.some((type) => RECIPIENT_INVOLVEMENT_TYPES.has(type))
+  })
+}
+
+const findRecipientFinding = ({ findings, recipientAddress }) => {
+  if (!Array.isArray(findings) || !recipientAddress) return
+  return findings.find((candidate) => isRecipientFinding({ finding: candidate, recipientAddress }))
+}
+
+const parseAssessment = ({ body, recipientAddress }) => {
+  if (!body?.success) return { action: 'NONE' }
+  if (body.data?.recommendation !== 'deny') return { action: 'NONE' }
+  const finding = findRecipientFinding({ findings: body.data?.findings, recipientAddress })
+  if (!finding) return { action: 'NONE' }
+
+  return {
+    action: 'WARN',
+    reason: finding.title || GENERIC_RISK_REASON,
+  }
+}
+
+// Rejects after `timeoutMs`. The underlying request keeps running because the
+// API helper doesn't accept an AbortSignal.
+const withTimeout = async (promise, timeoutMs) => {
+  let timeoutId
+  const timeoutPromise = new Promise((_resolve, reject) => {
+    timeoutId = setTimeout(() => reject(new Error('checkTx: timeout')), timeoutMs)
+  })
+  try {
+    return await Promise.race([promise, timeoutPromise])
+  } finally {
+    clearTimeout(timeoutId)
+  }
+}
+
+const noopLogger = { warn: () => {} }
+
+export const createCheckTx = (
+  { timeout = DEFAULT_TIMEOUT_MS, makeApiCall, logger = noopLogger } = Object.create(null)
+) => {
+  assert(typeof makeApiCall === 'function', 'makeApiCall is required')
+
+  const warn = typeof logger?.warn === 'function' ? logger.warn.bind(logger) : noopLogger.warn
+
+  // Errors and timeouts throw and are evicted by memoize-lru-cache, so only
+  // vendor-confirmed verdicts get cached.
+  const fetchVerdict = memoizeLruCache(
+    async ({ chain, fromAddress, toAddress, value, input, hash }) => {
+      const transaction = { chain, fromAddress, toAddress, value }
+      if (input !== undefined) transaction.input = input
+      if (hash !== undefined) transaction.hash = hash
+
+      const body = await withTimeout(makeApiCall({ payload: { transaction } }), timeout)
+
+      if (!body) throw new Error('checkTx: empty response')
+      return parseAssessment({ body, recipientAddress: toAddress })
+    },
+    buildCacheKey,
+    { max: DEFAULT_CACHE_MAX, maxAge: DEFAULT_CACHE_TTL_MS }
+  )
+
+  return async (payload) => {
+    try {
+      return await fetchVerdict(payload)
+    } catch (error) {
+      warn('checkTx: failing open', error)
+      return { action: 'NONE' }
+    }
+  }
+}

package/src/check-tx/index.js

@@ -0,0 +1 @@
+export { createCheckTx } from './create-check-tx.js'