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

package/src/exodus-eth-server/clarity-v2.js

@@ -0,0 +1,255 @@
+import assert from 'minimalistic-assert'
+
+import ClarityServer, { RPC_REQUEST_TIMEOUT } from './clarity.js'
+import { fetchJsonRetry } from './fetch-json.js'
+
+const ASSETS_GATEWAY_URL = 'https://assets-gateway-clarity-api.a.exodus.io/assets'
+
+export const encodeCursor = (blockNumberBigInt, isLegacy = false) => {
+  if (typeof blockNumberBigInt !== 'bigint') throw new Error('expected bigint')
+
+  if (isLegacy) {
+    const cursor = Buffer.alloc(26)
+    cursor.writeBigInt64LE(blockNumberBigInt, 10)
+    return cursor
+  }
+
+  const cursor = Buffer.alloc(8)
+  cursor.writeBigUInt64LE(blockNumberBigInt, 0)
+  return cursor
+}
+
+export const decodeCursor = (cursor) => {
+  if (Buffer.isBuffer(cursor)) {
+    // New format: buffer containing only the block number
+    if (cursor.length === 8) return { blockNumber: cursor.readBigUInt64LE(0) }
+
+    // Old format: buffer with length 26
+    if (cursor.length === 26) return { blockNumber: cursor.readBigInt64LE(10) }
+  }
+
+  // Doesn't match any known format, return default
+  return { blockNumber: BigInt(0) }
+}
+
+const fetchHttpRequest = ({ baseApiPath, path, method, body, search }) => {
+  assert(typeof baseApiPath === 'string', 'expected string baseApiPath')
+
+  const url = new URL(`${baseApiPath}${path}`)
+  if (search) url.search = search
+
+  const fetchOptions = {
+    method,
+    headers: { 'Content-Type': 'application/json' },
+  }
+
+  if (body) fetchOptions.body = JSON.stringify(body)
+  return fetchJsonRetry(url, fetchOptions)
+}
+
+export default class ClarityServerV2 extends ClarityServer {
+  constructor({ baseAssetName, uri }) {
+    super({ baseAssetName, uri })
+    this.updateBaseApiPath() // default to assets-gateway
+  }
+
+  updateBaseApiPath(uri) {
+    const base = uri || ASSETS_GATEWAY_URL
+    this.baseApiPath = new URL(`${base}/api/v2/${this.baseAssetName}`).toString()
+  }
+
+  setURI(uri) {
+    super.setURI(uri)
+    this.updateBaseApiPath(uri) // pass in the uri from remote config to override assets-gateway
+  }
+
+  getTransactionsFromBlockNumber = async ({ address, blockNumber, withInput, truncated }) => {
+    const url = new URL(`${this.baseApiPath}/addresses/${encodeURIComponent(address)}/transactions`)
+    url.searchParams.set('cursor', blockNumber || '0')
+
+    if (withInput) {
+      url.searchParams.set('withInput', 'true')
+    }
+
+    if (truncated) {
+      url.searchParams.set('truncated', 'true')
+    }
+
+    return fetchJsonRetry(url)
+  }
+
+  // Clarity exposes a new way to determine fee data for EIP-1559
+  // networks. In addition to the `nextBlockBaseFeePerGas`, we also
+  // receive a `rewardPercentiles` mapping, which defines the prevailing
+  // 25th, 50th and 75th percentiles of `maxPriorityFeePerGas` for
+  // an EVM-based network.
+  async getGasPriceEstimation() {
+    return fetchJsonRetry(`${this.baseApiPath}/gas-price-estimation`)
+  }
+
+  async getFee() {
+    // HACK: When we call `getFee`, we should still
+    //       subscribe for period fee updates.
+    await this.connectFee()
+
+    try {
+      // NOTE: Depending on whether the network is `eip1559Enabled`
+      //       **on the backend**, this can omit certain
+      //       properties.
+      //
+      //       By default, we should receive:
+      //       + blockNumber
+      //       + gasPrice
+      //       + baseGasPrice (deprecated)
+      //
+      //       In addition, when `eip1559Enabled` on Clarity:
+      //       + baseFeePerGas
+      //       + nextBaseFeePerGas
+      //       + rewardPercentiles
+      //
+      //       See: https://github.com/ExodusMovement/clarity/blob/d3c2a7f501a4391da630592bca3bf57c3ddd5e89/src/modules/ethereum-like/gas-price/index.js#L192C5-L219C6
+      return await this.getGasPriceEstimation()
+    } catch {
+      // HACK: The `getGasPriceEstimation` endpoint is not guaranteed
+      //       to exist for all assets. In this case, we'll fallback
+      //       to legacy behaviour, which is to query via the WebSocket.
+      return this.getFeeFromWebSocket()
+    }
+  }
+
+  /**
+   * Paginates GET .../addresses/:addr/transactions. Pass `truncated: true` to opt
+   * into the backend's truncation mode + `accountInfo` pre-cursor snapshots (used by
+   * `ClarityTruncatedHistoryMonitor`). For `clarity`/`clarity-v2`/`clarity-v3` flows,
+   * leave the default so Clarity returns full history.
+   */
+  async getAllTransactions({ address, cursor, withInput = true, truncated = false }) {
+    let { blockNumber } = decodeCursor(cursor)
+
+    let transactions = []
+
+    // accountInfo rows carry balance/nonce snapshots for blocks before the
+    // initial cursor — used to derive correct state with truncated history.
+    // Only collected (and returned) when the caller opted into `truncated`.
+    const accountInfo = truncated ? [] : null
+
+    while (true) {
+      const result = await this.getTransactionsFromBlockNumber({
+        address,
+        blockNumber: blockNumber.toString(),
+        withInput,
+        truncated,
+      })
+
+      const txs = result.transactions || []
+
+      if (accountInfo && Array.isArray(result.accountInfo)) {
+        accountInfo.push(...result.accountInfo)
+      }
+
+      const nextBlockNumber = BigInt(result.cursor)
+
+      if (txs.length === 0) {
+        // fetch until no more new transactions
+        blockNumber = nextBlockNumber
+        break
+      }
+
+      if (nextBlockNumber <= blockNumber) {
+        console.warn(
+          `Invalid cursor: next block number is not greater than current block number at cursor ${blockNumber}`
+        )
+
+        // self healing, reset cursor to the smaller block number and remove the transactions greater than the block number
+        transactions.push(...txs)
+        transactions = transactions.filter((tx) => tx.blockNumber <= nextBlockNumber)
+        blockNumber = nextBlockNumber
+        break
+      }
+
+      transactions.push(...txs)
+      blockNumber = nextBlockNumber
+    }
+
+    const newCursor = Buffer.alloc(8)
+    newCursor.writeBigUInt64LE(BigInt(blockNumber), 0)
+
+    // Separate confirmed (has blockNumber) from pending (blockNumber is null)
+    const confirmed = transactions.filter((tx) => tx.blockNumber != null)
+    const pending = transactions.filter((tx) => tx.blockNumber == null)
+
+    return {
+      transactions: { confirmed, pending },
+      cursor: newCursor,
+      ...(accountInfo && { accountInfo }),
+    }
+  }
+
+  fetchRpcHttpRequest = ({ baseApiPath, path = '/rpc', body }) => {
+    return fetchHttpRequest({ baseApiPath, path, method: 'POST', body })
+  }
+
+  async sendRpcRequest(rpcRequest) {
+    try {
+      return await super.sendRpcRequest(rpcRequest)
+    } catch (err) {
+      // If we encounter an error which isn't associated
+      // with transport timeouts, then bubble up.
+      if (err.message !== RPC_REQUEST_TIMEOUT) throw err
+
+      const { baseApiPath } = this
+      return this.fetchRpcHttpRequest({ baseApiPath, body: rpcRequest })
+    }
+  }
+
+  // Maybe some functions from clarity should be overriden to have handleJsonRPCResponse as well
+
+  async sendRawTransaction(...params) {
+    const { baseApiPath } = this
+    const request = this.sendRawTransactionRequest(...params)
+    return this.handleJsonRPCResponse(
+      await this.fetchRpcHttpRequest({ baseApiPath, body: request })
+    )
+  }
+
+  async getTransactionCount(...params) {
+    // nonce is called during tx send, use it in rest api
+    const { baseApiPath } = this
+    const request = this.getTransactionCountRequest(...params)
+    return this.handleJsonRPCResponse(
+      await this.fetchRpcHttpRequest({ baseApiPath, body: request })
+    )
+  }
+
+  async estimateGas(...params) {
+    const { baseApiPath } = this
+    const request = this.estimateGasRequest(...params)
+    return this.handleJsonRPCResponse(
+      await this.fetchRpcHttpRequest({ baseApiPath, body: request })
+    )
+  }
+
+  getServoTransactionsByBundleHash({ bundleHash }) {
+    assert(bundleHash, 'expected bundleHash')
+
+    const { baseApiPath } = this
+
+    return fetchHttpRequest({
+      baseApiPath,
+      path: '/proxy/servo/transactions',
+      method: 'GET',
+      search: new URLSearchParams({ bundleHash }).toString(),
+    })
+  }
+
+  async sendBundle(...params) {
+    const { baseApiPath } = this
+    return this.handleJsonRPCResponse(
+      await this.fetchRpcHttpRequest({
+        baseApiPath,
+        path: '/proxy/servo',
+        body: this.sendBundleRequest(...params),
+      })
+    )
+  }
+}

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

@@ -1,21 +1,30 @@
-import { bufferToHex } from '@exodus/ethereumjs-util'
-import SolidityContract from '@exodus/solidity-contract'
-import EventEmitter from 'events'
+import { safeString } from '@exodus/safe-string'
+import { TraceId } from '@exodus/traceparent'
 import io from 'socket.io-client'
-import { fromHexToString } from '../number-utils'
 
-export default class ClarityServer extends EventEmitter {
+import { errorMessageToSafeHint } from './errors.js'
+import { EthLikeServer } from './eth-like-server.js'
+
+export const RPC_REQUEST_TIMEOUT = 'RPC_REQUEST_TIMEOUT'
+
+export default class ClarityServer extends EthLikeServer {
   constructor({ baseAssetName, uri }) {
     super()
     this.baseAssetName = baseAssetName
     this.uri = uri
+    this.wsUri = uri
     this.defaultUri = uri
     this.baseNamespace = `/v1/${this.baseAssetName}`
     this.sockets = Object.create(null)
-    this.id = 0
   }
 
   setURI(uri) {
+    if (!uri.includes('assets-gateway')) {
+      // assets-gateway endpoint doesn't support legacy ws
+      // guard this against remote config override
+      this.wsUri = uri
+    }
+
     this.dispose()
     this.uri = uri
   }
@@ -52,9 +61,10 @@ export default class ClarityServer extends EventEmitter {
   }
 
   createSocket(namespace) {
-    return io(`${this.uri}${namespace}`, {
+    return io(`${this.wsUri}${namespace}`, {
       transports: ['websocket', 'polling'],
       extraHeaders: { 'User-Agent': 'exodus' },
+      reconnection: true,
     })
   }
 
@@ -64,11 +74,11 @@ export default class ClarityServer extends EventEmitter {
   }
 
   disconnectRpc() {
-    this.disconnectSocket(this.rpcNamespace)
+    this.disconnectSocket(this.formatRpcNamespace())
   }
 
   disconnectFee() {
-    this.disconnectSocket(this.feeNamespace)
+    this.disconnectSocket(this.formatFeeNamespace())
   }
 
   disconnectSocket(namespace) {
@@ -83,8 +93,34 @@ export default class ClarityServer extends EventEmitter {
     for (const namespace of namespaces) {
       this.disconnectSocket(namespace)
     }
+
+    this.removeAllListeners('transaction')
+    this.removeAllListeners('feeUpdated')
   }
 
+  // See https://www.jsonrpc.org/specification#response_object for details.
+  handleJsonRPCResponse(response) {
+    const result = response?.result
+    const error = response?.error
+    if (error || result === undefined) {
+      const message = error?.message || error?.code || safeString`no result`
+
+      const revisedError = new Error(`Bad rpc response: ${message}`)
+      revisedError.hint = safeString`Bad rpc response: ${errorMessageToSafeHint(message)}`
+
+      // Preserve trace ID: from HTTP (__traceId) or WebSocket (traceparent in JSON body)
+      const traceId = response?.__traceId || response?.traceparent
+      if (traceId) {
+        revisedError.traceId = traceId
+      }
+
+      throw revisedError
+    }
+
+    return result
+  }
+
+  // Transport: WS only in ClarityServer, HTTP only in ClarityServerV2 (overridden)
   async getAllTransactions(params) {
     const transactions = { pending: [], confirmed: [] }
     const cursor = await this.getTransactions({
@@ -104,6 +140,7 @@ export default class ClarityServer extends EventEmitter {
     return { cursor, transactions }
   }
 
+  // Transport: WS only (uses transactions socket, not RPC socket)
   async getTransactions({ walletAccount, address, cursor, onChunk }) {
     const socket = this.connectTransactions({ walletAccount, address })
     const listener = (isPending, chunk, callback) => {
@@ -124,10 +161,11 @@ export default class ClarityServer extends EventEmitter {
       .finally(() => socket.off('transactionsChunk', listener))
   }
 
-  async getFee() {
+  // Transport: WS only (uses fee socket)
+  getFeeFromWebSocket() {
     const socket = this.connectFee()
     return new Promise((resolve, reject) => {
-      const timeout = setTimeout(() => reject(new Error('Fee Timeout')), 30_000)
+      const timeout = setTimeout(() => reject(new Error('Fee Timeout')), 3000)
       socket.emit('getFee', (fee) => {
         clearTimeout(timeout)
         if (!fee) {
@@ -140,6 +178,12 @@ export default class ClarityServer extends EventEmitter {
     })
   }
 
+  // Transport: WS only in ClarityServer, HTTP first → WS fallback in ClarityServerV2 (overridden)
+  async getFee() {
+    return this.getFeeFromWebSocket()
+  }
+
+  // Transport: Depends on getFee() - WS only in ClarityServer, HTTP first → WS fallback in ClarityServerV2
   // for fee monitors
   async getGasPrice() {
     const fee = await this.getFee()
@@ -149,273 +193,31 @@ export default class ClarityServer extends EventEmitter {
   async sendRpcRequest(rpcRequest) {
     const rpcSocket = this.connectRpc()
     return new Promise((resolve, reject) => {
-      const timeout = setTimeout(() => reject(new Error('Rpc Timeout')), 30_000)
+      const timeout = setTimeout(() => reject(new Error(RPC_REQUEST_TIMEOUT)), 3000)
       rpcSocket.emit('request', rpcRequest, (response) => {
         clearTimeout(timeout)
+        const rawTraceparent = response?.traceparent || response?.[0]?.traceparent
+        if (rawTraceparent) {
+          // eslint-disable-next-line @exodus/hydra/no-param-reassign-prop-only
+          response.traceparent = TraceId.fromRawTraceparent(rawTraceparent)
+        }
+
         resolve(response)
       })
     })
   }
 
-  async sendBatchRequest(batch) {
+  // Transport: WS only in ClarityServer, WS first → HTTP fallback in ClarityServerV2
+  async sendBatchRequest(batch, { tolerant } = {}) {
     const responses = await this.sendRpcRequest(batch)
-    // FIXME: this falls apart if responses is not an array
-    const isValid = responses.every((response) => {
-      return !isNaN(response?.id) && response?.result
-    })
-    if (responses.length !== batch.length || !isValid) {
-      throw new Error('Bad Response')
-    }
-
-    const keyed = responses.reduce((acc, response) => {
-      return { ...acc, [`${response.id}`]: response.result }
-    }, Object.create(null))
-    return batch.map((request) => keyed[`${request.id}`])
+    return this.parseBatchResponse({ batch, responses, errorMessage: 'Bad Response', tolerant })
   }
 
+  // Transport: Uses sendRpcRequest - WS only in ClarityServer, WS first → HTTP fallback in ClarityServerV2
   async sendRequest(request) {
     const response = await this.sendRpcRequest(request)
-    const result = response?.result
-    const error = response?.error
-    if (error || result === undefined) {
-      const message = error?.message || error?.code || 'no result'
-      throw new Error(`Bad rpc response: ${message}`)
-    }
-
-    return result
-  }
-
-  async isContract(address) {
-    const code = await this.getCode(address)
-    return code.length > 2
-  }
-
-  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 hex = data.startsWith('0x') ? data : '0x' + data
-    return this.buildRequest({ method: 'eth_sendRawTransaction', params: [hex] })
-  }
-
-  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],
-    })
-  }
-
-  getCompilersRequest() {
-    return this.buildRequest({ method: 'eth_getCompilers' })
-  }
-
-  getNetVersionRequest() {
-    return this.buildRequest({ method: 'net_version' })
-  }
-
-  simulateRawTransactionRequest(rawTx, applyPending = true) {
-    const replaced = rawTx.replace('0x', '')
-    return this.buildRequest({
-      method: 'debug_simulateRawTransaction',
-      params: [replaced, applyPending],
-    })
-  }
-
-  async proxyToCoinNode(params) {
-    const request = this.buildRequest(params)
-    return this.sendRequest(request)
-  }
-
-  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 getBalance(...params) {
-    const request = this.getBalanceRequest(...params)
-    return this.sendRequest(request)
-  }
-
-  async getBalanceProxied(...params) {
-    return this.getBalance(...params)
-  }
-
-  async gasPrice(...params) {
-    const request = this.gasPriceRequest(...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 getCode(...params) {
-    const request = this.getCodeRequest(...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 getLatestBlock() {
-    return this.getBlockByNumber('latest')
-  }
-
-  async getBaseFeePerGas() {
-    const response = await this.getLatestBlock()
-    if (response.baseFeePerGas) {
-      return fromHexToString(response.baseFeePerGas)
-    }
-  }
-
-  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 getBlockByNumber(...params) {
-    const request = this.getBlockByNumberRequest(...params)
-    return this.sendRequest(request)
-  }
-
-  async simulateRawTransaction(...params) {
-    const request = this.simulateRawTransactionRequest(...params)
-    return this.sendRequest(request)
-  }
-
-  async getCoinbase() {
-    const request = this.coinbaseRequest()
-    return this.sendRequest(request)
-  }
-
-  async getCompilers() {
-    const request = this.getCompilersRequest()
-    return this.sendRequest(request)
-  }
-
-  async getNetVersion() {
-    const request = this.getNetVersion()
-    return this.sendRequest(request)
-  }
 
-  async getLogs(...params) {
-    const request = this.getLogsRequest(...params)
-    return this.sendRequest(request)
+    return this.handleJsonRPCResponse(response)
   }
 
   formatTransactionsNamespace(address) {