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

package/src/exodus-eth-server/errors.js

@@ -0,0 +1,40 @@
+import { safeString } from '@exodus/safe-string'
+
+// Transplated from: https://github.com/ethereum/go-ethereum/blob/master/core/txpool/errors.go.
+const TxPoolErrors = {
+  ALREADY_KNOWN: safeString`already known`,
+  INVALID_SENDER: safeString`invalid sender`,
+  UNDERPRICED: safeString`transaction underpriced`,
+  REPLACE_UNDERPRICED: safeString`replacement transaction underpriced`,
+  TX_GAS_PRICE_TOO_LOW: safeString`transaction gas price below minimum`,
+  ACCOUNT_LIMIT_EXCEEDED: safeString`account limit exceeded`,
+  GAS_LIMIT: safeString`exceeds block gas limit`,
+  NEGATIVE_VALUE: safeString`negative value`,
+  OVERSIZED_DATA: safeString`oversized data`,
+  TX_BLOB_LIMIT_EXCEEDED: safeString`transaction blob limit exceeded`,
+  ALREADY_RESERVED: safeString`address already reserved`,
+  INFLIGHT_TX_LIMIT_REACHED: safeString`in-flight transaction limit reached for delegated accounts`,
+}
+
+const DYNAMIC_RPC_ERRORS = {
+  TRANSACTION_TYPE_NOT_SUPPORTED: safeString`transaction type not supported`,
+  ONLY_REPLAY_PROTECTED_TRANSACTIONS: safeString`only replay-protected (EIP-155) transactions allowed over RPC`,
+  TRANSACTION_GAS_PRICE_BELOW_MINIMUM: safeString`transaction gas price below minimum`,
+}
+
+const SERVO_ERRORS = {
+  EMPTY_BUNDLE: safeString`numTxs=0: invalid num txs`,
+}
+
+export const KNOWN_RPC_ERRORS = { ...TxPoolErrors, ...DYNAMIC_RPC_ERRORS, ...SERVO_ERRORS }
+
+export const tryMappingToRpcErrors = (errorMessage) => {
+  if (typeof errorMessage !== 'string') return
+
+  return Object.values(KNOWN_RPC_ERRORS)
+    .sort((a, b) => b.length - a.length)
+    .find((knownRpcError) => errorMessage.includes(knownRpcError))
+}
+
+export const errorMessageToSafeHint = (messageOrCode) =>
+  tryMappingToRpcErrors(messageOrCode) || messageOrCode

package/src/exodus-eth-server/eth-like-server.js

@@ -0,0 +1,385 @@
+import { bufferToHex } from '@exodus/ethereumjs/util'
+import SolidityContract from '@exodus/solidity-contract'
+import EventEmitter from 'events/events.js'
+import assert from 'minimalistic-assert'
+
+import { fromHexToString } from '../number-utils.js'
+import { getFallbackGasPriceEstimation } from './utils.js'
+
+export class EthLikeServerBase extends EventEmitter {
+  id = 0
+
+  buildRequest({ method, params = [] }) {
+    return { jsonrpc: '2.0', id: this.id++, method, params }
+  }
+
+  balanceOfRequest(address, tokenAddress, tag = 'latest') {
+    const contract = SolidityContract.simpleErc20(tokenAddress)
+    const callData = contract.balanceOf.build(address)
+    const data = {
+      data: bufferToHex(callData),
+      to: tokenAddress,
+    }
+    return this.ethCallRequest(data, tag)
+  }
+
+  getBalanceRequest(address, tag = 'latest') {
+    return this.buildRequest({ method: 'eth_getBalance', params: [address, tag] })
+  }
+
+  gasPriceRequest() {
+    return this.buildRequest({ method: 'eth_gasPrice' })
+  }
+
+  estimateGasRequest(data, tag = 'latest') {
+    return this.buildRequest({ method: 'eth_estimateGas', params: [data, tag] })
+  }
+
+  sendRawTransactionRequest(data) {
+    const _data = data instanceof Uint8Array ? Buffer.from(data).toString('hex') : data
+    const hex = _data.startsWith('0x') ? _data : '0x' + _data
+    return this.buildRequest({ method: 'eth_sendRawTransaction', params: [hex] })
+  }
+
+  // @deprecated
+  coinbaseRequest() {
+    return this.buildRequest({ method: 'eth_coinbase' })
+  }
+
+  getCodeRequest(address, tag = 'latest') {
+    return this.buildRequest({ method: 'eth_getCode', params: [address, tag] })
+  }
+
+  getStorageAtRequest(address, position, tag = 'latest') {
+    return this.buildRequest({ method: 'eth_getStorageAt', params: [address, position, tag] })
+  }
+
+  getTransactionCountRequest(address, tag = 'latest') {
+    return this.buildRequest({ method: 'eth_getTransactionCount', params: [address, tag] })
+  }
+
+  getTransactionByHashRequest(hash) {
+    return this.buildRequest({ method: 'eth_getTransactionByHash', params: [hash] })
+  }
+
+  getTransactionReceiptRequest(txhash) {
+    return this.buildRequest({ method: 'eth_getTransactionReceipt', params: [txhash] })
+  }
+
+  ethCallRequest(data, tag = 'latest') {
+    return this.buildRequest({ method: 'eth_call', params: [data, tag] })
+  }
+
+  blockNumberRequest() {
+    return this.buildRequest({ method: 'eth_blockNumber' })
+  }
+
+  getLogsRequest(object) {
+    return this.buildRequest({ method: 'eth_getLogs', params: [object] })
+  }
+
+  getBlockByNumberRequest(numberHex, isFullTxs = false) {
+    return this.buildRequest({ method: 'eth_getBlockByNumber', params: [numberHex, isFullTxs] })
+  }
+
+  getBlockByHashRequest(blockHash, isFullTxs = false) {
+    return this.buildRequest({ method: 'eth_getBlockByHash', params: [blockHash, isFullTxs] })
+  }
+
+  getBlockTransactionCountByHashRequest(blockHash) {
+    return this.buildRequest({ method: 'eth_getBlockTransactionCountByHash', params: [blockHash] })
+  }
+
+  getBlockTransactionCountByNumberRequest(quantityOrTag) {
+    return this.buildRequest({
+      method: 'eth_getBlockTransactionCountByNumber',
+      params: [quantityOrTag],
+    })
+  }
+
+  // @deprectated
+  getCompilersRequest() {
+    return this.buildRequest({ method: 'eth_getCompilers' })
+  }
+
+  // TODO: Expose on Clarity
+  // maxPriorityFeePerGasRequest() {
+  //   return this.buildRequest({ method: 'eth_maxPriorityFeePerGas' })
+  // }
+
+  // TODO: Expose on Clarity
+  // feeHistoryRequest(blockCount, newestBlock, rewardPercentiles) {
+  //   return this.buildRequest({
+  //     method: 'eth_feeHistory',
+  //     params: [blockCount, newestBlock, rewardPercentiles],
+  //   })
+  // }
+
+  simulateV1Request(...params) {
+    return this.buildRequest({
+      method: 'eth_simulateV1',
+      params,
+    })
+  }
+
+  getNetVersionRequest() {
+    return this.buildRequest({ method: 'net_version' })
+  }
+
+  // @deprecated
+  simulateRawTransactionRequest(rawTx, applyPending = true) {
+    const replaced = rawTx.replace('0x', '')
+    return this.buildRequest({
+      method: 'debug_simulateRawTransaction',
+      params: [replaced, applyPending],
+    })
+  }
+
+  contractStaticCallFromRequest(contract, functionName, from, ...args) {
+    assert(contract instanceof SolidityContract, 'expected SolidityContract contract')
+    assert(typeof functionName === 'string', 'expected string functionName')
+
+    const requestProps = {
+      to: contract.address,
+      data: bufferToHex(contract[functionName].build(...args)),
+    }
+
+    if (from) requestProps.from = from
+
+    return this.ethCallRequest(requestProps)
+  }
+
+  sendBundleRequest({ txs }) {
+    assert(Array.isArray(txs), 'expected array txs')
+    return this.buildRequest({ method: 'eth_sendBundle', params: [{ txs }] })
+  }
+}
+
+const __MISSING_FUNCTION_IMPLEMENTATION__ = () => assert(false)
+
+export class EthLikeServer extends EthLikeServerBase {
+  /**
+   * Validates a JSON-RPC batch response, returning each `result` ordered to
+   * match `batch` (correlated by `id`, since responses can arrive out of order).
+   *
+   * @param {Array<{ id: number|string }>} args.batch - Requests sent, in the order results are expected.
+   * @param {unknown} args.responses - Raw transport payload; expected `[{ id, result }]` but treated as untrusted (gateways may return `{ message }` on error).
+   * @param {string} args.errorMessage - Thrown-error prefix per transport (e.g. `'Bad rpc batch response'`, `'Bad Response'`).
+   * @param {boolean} [args.tolerant] - When true, a request without a valid entry (JSON-RPC error entry, non-numeric `id`, duplicated or out-of-batch `id`, missing from a short response) maps to `undefined` instead of failing the whole batch.
+   * @returns {unknown[]} Each request's `result`, ordered to match `batch`. Entries with a duplicated or out-of-batch `id` are discarded in both modes, so an affected request maps to `undefined` rather than another request's result.
+   * @throws {Error} When `responses` isn't an array; in strict mode also when length mismatches `batch` or any entry lacks a numeric `id` / defined `result`.
+   */
+  parseBatchResponse({ batch, responses, errorMessage, tolerant = false }) {
+    // Gateways can respond with a JSON object (e.g. `{ message }`) instead of a batch array.
+    if (!Array.isArray(responses)) {
+      // Untrusted server text: keep only a short string preview, developer-facing (no `hint`).
+      const message = [responses?.message, responses?.error?.message].find(
+        (value) => typeof value === 'string'
+      )
+      const preview = message ? `: ${message.slice(0, 100)}` : ''
+      throw new Error(`${errorMessage}${preview}`)
+    }
+
+    const isValidEntry = (response) => !isNaN(response?.id) && response?.result !== undefined
+
+    if (!tolerant && (responses.length !== batch.length || !responses.every(isValidEntry))) {
+      throw new Error(errorMessage)
+    }
+
+    // Safe against prototype keys: only entries with a validated numeric `id` are kept.
+    const keyed = Object.fromEntries(
+      responses
+        .filter(isValidEntry)
+        .filter(({ id }, _i, all) => {
+          const key = `${id}`
+          const inBatch = batch.some((request) => `${request.id}` === key)
+          const unique = all.filter(({ id: other }) => `${other}` === key).length === 1
+          return inBatch && unique
+        })
+        .map((response) => [`${response.id}`, response.result])
+    )
+    return batch.map((request) => keyed[`${request.id}`])
+  }
+
+  async getCode(...params) {
+    const request = this.getCodeRequest(...params)
+    return this.sendRequest(request)
+  }
+
+  async estimateGas(...params) {
+    const request = this.estimateGasRequest(...params)
+    return this.sendRequest(request)
+  }
+
+  async sendRawTransaction(...params) {
+    const request = this.sendRawTransactionRequest(...params)
+    return this.sendRequest(request)
+  }
+
+  async getStorageAt(...params) {
+    const request = this.getStorageAtRequest(...params)
+    return this.sendRequest(request)
+  }
+
+  async getTransactionCount(...params) {
+    const request = this.getTransactionCountRequest(...params)
+    return this.sendRequest(request)
+  }
+
+  async getTransactionByHash(...params) {
+    const request = this.getTransactionByHashRequest(...params)
+    return this.sendRequest(request)
+  }
+
+  async getTransactionReceipt(...params) {
+    const request = this.getTransactionReceiptRequest(...params)
+    return this.sendRequest(request)
+  }
+
+  async ethCall(...params) {
+    const request = this.ethCallRequest(...params)
+    return this.sendRequest(request)
+  }
+
+  async blockNumber(...params) {
+    const request = this.blockNumberRequest(...params)
+    return this.sendRequest(request)
+  }
+
+  async getBlockByNumber(...params) {
+    const request = this.getBlockByNumberRequest(...params)
+    return this.sendRequest(request)
+  }
+
+  async isContract(address) {
+    const code = await this.getCode(address)
+    return code.length > 2
+  }
+
+  // @deprecated
+  async simulateRawTransaction(...params) {
+    const request = this.simulateRawTransactionRequest(...params)
+    return this.sendRequest(request)
+  }
+
+  async getBaseFeePerGas() {
+    const response = await this.getLatestBlock()
+    if (response.baseFeePerGas) {
+      return fromHexToString(response.baseFeePerGas)
+    }
+  }
+
+  async getLatestBlock() {
+    return this.getBlockByNumber('latest')
+  }
+
+  async gasPrice(...params) {
+    const request = this.gasPriceRequest(...params)
+    return this.sendRequest(request)
+  }
+
+  // for fee monitor
+  async getGasPrice() {
+    return this.gasPrice()
+  }
+
+  async getBalance(...params) {
+    const request = this.getBalanceRequest(...params)
+    return this.sendRequest(request)
+  }
+
+  async getBalanceProxied(...params) {
+    return this.getBalance(...params)
+  }
+
+  async getBlockByHash(...params) {
+    const request = this.getBlockByHashRequest(...params)
+    return this.sendRequest(request)
+  }
+
+  async getBlockTransactionCountByNumber(...params) {
+    const request = this.getBlockTransactionCountByNumberRequest(...params)
+    return this.sendRequest(request)
+  }
+
+  async getBlockTransactionCountByHash(...params) {
+    const request = this.getBlockTransactionCountByHashRequest(...params)
+    return this.sendRequest(request)
+  }
+
+  async simulateV1(...params) {
+    const request = this.simulateV1Request(...params)
+    return this.sendRequest(request)
+  }
+
+  // @deprecated
+  async getCoinbase() {
+    const request = this.coinbaseRequest()
+    return this.sendRequest(request)
+  }
+
+  // @deprecated
+  async getCompilers() {
+    const request = this.getCompilersRequest()
+    return this.sendRequest(request)
+  }
+
+  // TODO: Expose on Clarity
+  // async getMaxPriorityFeePerGas() {
+  //   const request = this.maxPriorityFeePerGasRequest()
+  //   return this.sendRequest(request)
+  // }
+
+  // TODO: Expose on Clarity
+  // async getFeeHistory(...params) {
+  //   const request = this.feeHistoryRequest(...params)
+  //   return this.sendRequest(request)
+  // }
+
+  async getNetVersion() {
+    const request = this.getNetVersionRequest()
+    return this.sendRequest(request)
+  }
+
+  async getLogs(...params) {
+    const request = this.getLogsRequest(...params)
+    return this.sendRequest(request)
+  }
+
+  async proxyToCoinNode(params) {
+    const request = this.buildRequest(params)
+    return this.sendRequest(request)
+  }
+
+  async getGasPriceEstimation() {
+    return getFallbackGasPriceEstimation({ server: this })
+  }
+
+  async balanceOf(address, tokenAddress, tag = 'latest') {
+    const request = this.balanceOfRequest(address, tokenAddress, tag)
+    const result = await this.sendRequest(request)
+    const balance = fromHexToString(result)
+    return {
+      confirmed: {
+        [tokenAddress]: balance,
+      },
+    }
+  }
+
+  async contractStaticCallFrom(contract, functionName, ...params) {
+    const request = this.contractStaticCallFromRequest(contract, functionName, ...params)
+    return contract[functionName].parse(await this.sendRequest(request))
+  }
+
+  async contractStaticCall(contract, functionName, ...params) {
+    return this.contractStaticCallFrom(contract, functionName, undefined, ...params)
+  }
+
+  sendRequest() {
+    return __MISSING_FUNCTION_IMPLEMENTATION__()
+  }
+
+  sendBatchRequest() {
+    return __MISSING_FUNCTION_IMPLEMENTATION__()
+  }
+}

package/src/exodus-eth-server/fetch-json.js

@@ -0,0 +1,48 @@
+import { retry } from '@exodus/simple-retry'
+import { TraceId } from '@exodus/traceparent'
+
+const getTextFromResponse = async (response) => {
+  try {
+    const responseBody = await response.text()
+    return responseBody.slice(0, 100)
+  } catch {
+    return ''
+  }
+}
+
+export const fetchJson = async (url, fetchOptions) => {
+  const response = await fetch(url, fetchOptions)
+
+  if (!response.ok) {
+    const traceId = TraceId.fromResponse(response)
+    const error = new Error(
+      `${url} returned ${response.status}: ${
+        response.statusText || 'Unknown Status Text'
+      }. Body: ${await getTextFromResponse(response)}`
+    )
+    if (traceId) {
+      error.traceId = traceId
+    }
+
+    throw error
+  }
+
+  const json = await response.json()
+
+  // Only capture trace ID if there's an RPC error in the response
+  // (consumers extract it via __traceId when throwing the error)
+  if (json.error) {
+    const traceId = TraceId.fromResponse(response)
+    if (traceId) {
+      json.__traceId = traceId
+    }
+  }
+
+  return json
+}
+
+export const fetchJsonRetry = (url, fetchOptions) => {
+  const waitTimes = ['3s']
+  const fetchWithRetry = retry(fetchJson, { delayTimesMs: waitTimes })
+  return fetchWithRetry(url, fetchOptions)
+}

package/src/exodus-eth-server/index.js

@@ -0,0 +1,77 @@
+import assert from 'minimalistic-assert'
+
+import { create } from './api.js'
+import ApiCoinNodesServer from './api-coin-nodes.js'
+import ClarityServer from './clarity.js'
+import ClarityServerV2 from './clarity-v2.js'
+import WsGateway from './ws-gateway.js'
+
+export const ValidMonitorTypes = [
+  'no-history',
+  'clarity',
+  'clarity-v2',
+  'clarity-truncated-history',
+  'clarity-v3',
+  'magnifier',
+]
+
+export function createEvmServer({ assetName, serverUrl, monitorType }) {
+  assert(assetName, 'assetName is required')
+  assert(serverUrl, 'serverUrl is required')
+  assert(monitorType, 'monitorType is required')
+
+  // Truncated-history uses the same Clarity v2 HTTP/WS server; only the monitor class differs.
+  switch (monitorType) {
+    case 'no-history':
+      return new ApiCoinNodesServer({ baseAssetName: assetName, uri: serverUrl })
+    case 'clarity':
+      return new ClarityServer({ baseAssetName: assetName, uri: serverUrl })
+    case 'clarity-v2':
+    case 'clarity-truncated-history':
+    case 'clarity-v3':
+      return new ClarityServerV2({ baseAssetName: assetName, uri: serverUrl })
+    case 'magnifier':
+      return create(serverUrl, assetName)
+    default:
+      throw new Error(`No server API found for ${assetName} and type ${monitorType}`)
+  }
+}
+
+const gatewayUriToWsGateway = Object.create(null)
+
+export const createWsGateway = ({ uri } = Object.create(null)) => {
+  assert(typeof uri === 'string', 'expected string uri')
+
+  uri = new URL(uri).toString()
+
+  const wsGateway = gatewayUriToWsGateway[uri]
+  if (wsGateway) return wsGateway
+
+  // NOTE: We disable the ability to `setServer` on the
+  //       `WsGateway`, since we assume a mapping between
+  //       `gatewayUri -> WsGateway`.
+  //
+  //       This is a safe modification since a `WsGateway`
+  //       monitor isn't rigged up to the same life cycle
+  //       as other servers.
+  class FrozenWsGateway extends WsGateway {
+    constructor() {
+      super({ uri })
+    }
+
+    setServer() {
+      assert(false, 'setServer is disabled')
+    }
+  }
+
+  const frozenWsGateway = new FrozenWsGateway()
+  gatewayUriToWsGateway[uri] = frozenWsGateway
+
+  return frozenWsGateway
+}
+
+export function getServer(asset) {
+  const { name, server } = asset.baseAsset
+  assert(server, `${name} server is not set on asset.baseAsset.server`)
+  return server
+}

package/src/exodus-eth-server/utils.js

@@ -0,0 +1,31 @@
+import assert from 'minimalistic-assert'
+
+const desc = (a, b) => (a > b ? -1 : b > a ? 1 : 0)
+
+export const getFallbackGasPriceEstimation = async ({ server }) => {
+  const [latestBlock, gasPrice] = await Promise.all([server.getLatestBlock(), server.getGasPrice()])
+
+  assert(latestBlock, 'expected latestBlock')
+  assert(gasPrice, 'expected gasPrice')
+
+  const baseFeePerGas = latestBlock.baseFeePerGas
+  if (!baseFeePerGas) return { gasPrice }
+
+  const [max, min] = [BigInt(gasPrice), BigInt(baseFeePerGas)].sort(desc)
+
+  const toHex = (b) => `0x${b.toString(16)}`
+
+  // TODO: Use `eth_feeHistory` or `eth_maxPriorityFeePerGas`
+  //       instead (requires allowlist at the RPC).
+  // HACK: Infer the RPC's implicit `tipGasPrice`:
+  //       https://github.com/ethereum/go-ethereum/blob/d3dd48e59db28ea04bd92e4337cdd488ccb8fbec/internal/ethapi/api.go#L69C1-L79C2
+  const maxPriorityFeePerGas50Percentile = max - min
+
+  const rewardPercentiles = {
+    25: toHex(maxPriorityFeePerGas50Percentile / BigInt(2)),
+    50: toHex(maxPriorityFeePerGas50Percentile),
+    75: toHex((maxPriorityFeePerGas50Percentile * BigInt(3)) / BigInt(2)),
+  }
+
+  return { gasPrice, baseFeePerGas, rewardPercentiles }
+}