@0xtorch/evm 0.0.126 → 0.0.127

package/explorer/etherscanV2/client.ts

@@ -0,0 +1,154 @@
+import { rest } from '@0xtorch/core'
+import { type ZodType, type ZodTypeDef, z } from 'zod'
+
+export type EtherscanV2Client = {
+  get: <
+    Output,
+    Def extends ZodTypeDef = ZodTypeDef,
+    Input = Output,
+  >(parameters: {
+    path: string
+    query: Record<string, string>
+    resultSchema: ZodType<Output, Def, Input>
+    headers?: Record<string, string>
+  }) => Promise<Output>
+}
+
+const baseUrl = 'https://api.etherscan.io/api'
+
+type CreateEtherscanV2ClientParameters = {
+  chainId: number
+  apiKey?: string
+  proxyUrl?: string
+}
+
+export const createEtherscanV2Client = ({
+  chainId,
+  apiKey,
+  proxyUrl,
+}: CreateEtherscanV2ClientParameters): EtherscanV2Client => {
+  // apiKey = undefined かつ proxyUrl = undefined の場合はエラー
+  if (apiKey === undefined && proxyUrl === undefined) {
+    throw new Error('apiKey or proxyUrl must be provided')
+  }
+
+  const rateLimitPerSecond = 5
+  const requestTimestamps: number[] = []
+
+  const get = async <
+    Output,
+    Def extends ZodTypeDef = ZodTypeDef,
+    Input = Output,
+  >(
+    {
+      path,
+      query,
+      resultSchema,
+      headers,
+    }: {
+      path: string
+      query: Record<string, string>
+      resultSchema: ZodType<Output, Def, Input>
+      headers?: Record<string, string>
+    },
+    repeat = 0,
+  ): Promise<Output> => {
+    // rate limit を超えていたら 1 秒待つ
+    const time1SecondAgo = Date.now() - 1000
+    if (
+      requestTimestamps.filter((t) => t >= time1SecondAgo).length >=
+      rateLimitPerSecond
+    ) {
+      await new Promise<void>((resolve) => {
+        const intervalId = setInterval(() => {
+          const time1SecondAgo = Date.now() - 1000
+          if (
+            requestTimestamps.filter((t) => t >= time1SecondAgo).length <
+            rateLimitPerSecond
+          ) {
+            clearInterval(intervalId)
+            resolve()
+            return
+          }
+        }, 1000)
+      })
+    }
+
+    // requestTimestamps に追加
+    requestTimestamps.push(Date.now())
+
+    // define the schema for the response
+    const responseSchema = z.object({
+      status: z.string(),
+      message: z.string(),
+      result: z.union([resultSchema, z.string()]).nullable(),
+    })
+
+    // request
+    try {
+      const url = new URL(path, baseUrl)
+      url.searchParams.set('chainid', chainId.toString())
+      for (const [key, value] of Object.entries(query)) {
+        url.searchParams.set(key, value)
+      }
+      if (apiKey !== undefined) {
+        url.searchParams.set('apikey', apiKey)
+      }
+      console.debug(`[GET] ${url.toString()}`)
+      const { status, message, result } = await rest(
+        proxyUrl === undefined
+          ? url.toString()
+          : `${proxyUrl}${encodeURIComponent(url.toString())}`,
+        {
+          schema: responseSchema,
+          fetchOptions: {
+            headers: {
+              ...headers,
+            },
+          },
+        },
+      )
+      if (status !== '1') {
+        throw typeof result === 'string'
+          ? new Error(result)
+          : new Error(message)
+      }
+      if (result === null || result === undefined) {
+        throw new Error(message)
+      }
+      if (typeof result === 'string') {
+        throw new TypeError(result)
+      }
+      return result as Output
+    } catch (error) {
+      if (repeat < 3 && error instanceof Error) {
+        if (
+          error.message === 'Max rate limit reached' ||
+          error.message === 'Max calls per sec rate limit reached' ||
+          error.message === 'Max calls per sec rate limit reached (5/sec)' ||
+          error.message ===
+            'Max rate limit reached, please use API Key for higher rate limit'
+        ) {
+          console.debug(error)
+          await new Promise((resolve) => setTimeout(resolve, 5000))
+          return get({ path, query, resultSchema }, repeat + 1)
+        }
+        if (
+          error.message.includes('429') ||
+          error.message.includes(
+            'Unexpected error, timeout or server too busy. Please try again later',
+          )
+        ) {
+          console.debug(error)
+          await new Promise((resolve) => setTimeout(resolve, 10_000))
+          return await get({ path, query, resultSchema }, repeat + 1)
+        }
+      }
+      throw error
+    }
+  }
+
+  return {
+    get,
+  }
+}

package/explorer/etherscanV2/create.ts

@@ -0,0 +1,251 @@
+import type { Erc20Transfer, LowerHex } from '../../types'
+import type { InternalTransactionWithIndex } from '../../types/internalTransaction'
+import type { TransactionIndex } from '../../types/transactionIndex'
+import { createInternalTransactionId } from '../../utils/createInternalTransactionId'
+import type { Explorer, LogWithBlockNumber } from '../types'
+import { createEtherscanV2Client } from './client'
+import { getBlockNumberByTimestamp } from './getBlockNumberByTimestamp'
+import { getContractCreatorAndCreationTxHash } from './getContractCreatorAndCreationTxHash'
+import { getContractSourceCodeForVerifiedContract } from './getContractSourceCodeForVerifiedContract'
+import { getEventLogsByAddressFilteredByTopics } from './getEventLogsByAddressFilteredByTopics'
+import { getInternalTransactionsByTransactionHash } from './getInternalTransactionsByTransactionHash'
+import { getListOfErc20TokenTransferEventsByAddress } from './getListOfErc20TokenTransferEventsByAddress'
+import { getListOfErc721TokenTransferEventsByAddress } from './getListOfErc721TokenTransferEventsByAddress'
+import { getListOfErc1155TokenTransferEventsByAddress } from './getListOfErc1155TokenTransferEventsByAddress'
+import { getListOfInternalTransactionsByAddress } from './getListOfInternalTransactionsByAddress'
+import { getListOfNormalTransactionsByAddress } from './getListOfNormalTransactionsByAddress'
+
+type CreateEtherscanV2Parameters = {
+  name: string
+  baseUrl: string
+  chainId: number
+  apiKey?: string
+  proxyUrl?: string
+  pageSize?: number
+}
+
+export const createEtherscanV2 = ({
+  name,
+  baseUrl,
+  chainId,
+  apiKey,
+  proxyUrl,
+  pageSize = 10_000,
+}: CreateEtherscanV2Parameters): Explorer => {
+  const client = createEtherscanV2Client({
+    chainId,
+    apiKey,
+    proxyUrl,
+  })
+
+  return {
+    name,
+    baseUrl,
+    getAddressInternalTransactions: async ({
+      address,
+      fromBlock,
+      toBlock,
+      headers,
+    }) => {
+      const internalTransactions = new Map<
+        string,
+        InternalTransactionWithIndex
+      >()
+      let startblock = fromBlock
+      const endblock = toBlock
+      while (true) {
+        const result = await getListOfInternalTransactionsByAddress({
+          client,
+          address,
+          startblock,
+          endblock,
+          offset: pageSize,
+          headers,
+        })
+        for (const transaction of result) {
+          const id = createInternalTransactionId(transaction)
+          if (!internalTransactions.has(id)) {
+            internalTransactions.set(id, transaction)
+          }
+        }
+        if (result.length < pageSize) {
+          break
+        }
+        const maxBlockNumber = Math.max(...result.map((x) => x.blockNumber))
+        startblock = maxBlockNumber
+      }
+      return [...internalTransactions.values()]
+    },
+    getAddressTransactionIndexes: async ({
+      address,
+      fromBlock,
+      toBlock,
+      headers,
+    }) => {
+      const indexes = new Map<LowerHex, TransactionIndex>()
+      let startblock = fromBlock
+      const endblock = toBlock
+      while (true) {
+        const result = await getListOfNormalTransactionsByAddress({
+          client,
+          address,
+          startblock,
+          endblock,
+          offset: pageSize,
+          headers,
+        })
+        for (const index of result) {
+          if (!indexes.has(index.hash)) {
+            indexes.set(index.hash, index)
+          }
+        }
+        if (result.length < pageSize) {
+          break
+        }
+        const maxBlockNumber = Math.max(...result.map((x) => x.blockNumber))
+        startblock = maxBlockNumber
+      }
+      return [...indexes.values()]
+    },
+    getAddressTokenTransferIndexes: async ({
+      address,
+      fromBlock,
+      toBlock,
+      headers,
+    }) => {
+      const indexes = new Map<LowerHex, TransactionIndex>()
+      const erc20Transfers: Erc20Transfer[] = []
+      const endblock = toBlock
+
+      // ERC20
+      let startblock = fromBlock
+      while (true) {
+        const { indexes: resultIndexes, erc20Transfers: resultErc20Transfers } =
+          await getListOfErc20TokenTransferEventsByAddress({
+            client,
+            address,
+            startblock,
+            endblock,
+            offset: pageSize,
+            headers,
+          })
+        for (const index of resultIndexes) {
+          if (!indexes.has(index.hash)) {
+            indexes.set(index.hash, index)
+          }
+        }
+        erc20Transfers.push(...resultErc20Transfers)
+        if (resultIndexes.length < pageSize) {
+          break
+        }
+        const maxBlockNumber = Math.max(
+          ...resultIndexes.map((x) => x.blockNumber),
+        )
+        startblock = maxBlockNumber
+      }
+
+      // ERC721
+      startblock = fromBlock
+      while (true) {
+        const result = await getListOfErc721TokenTransferEventsByAddress({
+          client,
+          address,
+          startblock,
+          endblock,
+          offset: pageSize,
+          headers,
+        })
+        for (const index of result) {
+          if (!indexes.has(index.hash)) {
+            indexes.set(index.hash, index)
+          }
+        }
+        if (result.length < pageSize) {
+          break
+        }
+        const maxBlockNumber = Math.max(...result.map((x) => x.blockNumber))
+        startblock = maxBlockNumber
+      }
+
+      // ERC1155
+      startblock = fromBlock
+      while (true) {
+        const result = await getListOfErc1155TokenTransferEventsByAddress({
+          client,
+          address,
+          startblock,
+          endblock,
+          offset: pageSize,
+          headers,
+        })
+        for (const index of result) {
+          if (!indexes.has(index.hash)) {
+            indexes.set(index.hash, index)
+          }
+        }
+        if (result.length < pageSize) {
+          break
+        }
+        const maxBlockNumber = Math.max(...result.map((x) => x.blockNumber))
+        startblock = maxBlockNumber
+      }
+
+      return {
+        indexes: [...indexes.values()],
+        erc20Transfers,
+      }
+    },
+    getBlockNumberOfTimestamp: ({ timestamp, headers }): Promise<number> =>
+      getBlockNumberByTimestamp({
+        client,
+        timestamp: Math.floor(timestamp / 1000),
+        headers,
+      }),
+    getContract: ({ address, headers }) =>
+      getContractSourceCodeForVerifiedContract({
+        client,
+        address,
+        headers,
+      }),
+    getContractCreations: ({ addresses, headers }) =>
+      getContractCreatorAndCreationTxHash({
+        client,
+        contractaddresses: addresses,
+        headers,
+      }),
+    getEventLogs: async ({
+      address,
+      topic0,
+      fromBlock: fromBlockParam,
+      toBlock,
+      headers,
+    }) => {
+      const logs: LogWithBlockNumber[] = []
+      let fromBlock = fromBlockParam ?? 0
+      const maxPageSize = 10_000
+      while (true) {
+        const result = await getEventLogsByAddressFilteredByTopics({
+          client,
+          address,
+          topic0,
+          fromBlock,
+          toBlock,
+          headers,
+        })
+        logs.push(...result)
+        if (result.length < maxPageSize) {
+          break
+        }
+        const maxBlockNumber = Math.max(...result.map((x) => x.blockNumber))
+        fromBlock = maxBlockNumber
+      }
+      return logs
+    },
+    getInternalTransactionOfTransaction: ({ hash, headers }) =>
+      getInternalTransactionsByTransactionHash({
+        client,
+        txhash: hash,
+        headers,
+      }),
+  }
+}

package/explorer/etherscanV2/getBlockNumberByTimestamp.ts

@@ -0,0 +1,33 @@
+import { z } from 'zod'
+import type { EtherscanV2Client } from './client'
+
+type GetBlockNumberByTimestampParameters = {
+  client: EtherscanV2Client
+  /** Unix timestamp in seconds */
+  timestamp: number
+  closest?: 'before' | 'after'
+  headers?: Record<string, string>
+}
+
+const resultSchema = z.string().regex(/^\d+$/).transform(Number)
+
+/** {@link https://docs.etherscan.io/etherscan-v2/api-endpoints/blocks#get-block-number-by-timestamp} */
+export const getBlockNumberByTimestamp = async ({
+  client,
+  timestamp,
+  closest = 'before',
+  headers,
+}: GetBlockNumberByTimestampParameters) => {
+  const result = await client.get({
+    path: '',
+    query: {
+      module: 'block',
+      action: 'getblocknobytime',
+      timestamp: timestamp.toString(),
+      closest,
+    },
+    resultSchema,
+    headers,
+  })
+  return result
+}

package/explorer/etherscanV2/getContractCreatorAndCreationTxHash.ts

@@ -0,0 +1,46 @@
+import { z } from 'zod'
+import type { Hex } from '../../types'
+import { addressPrimitiveSchema, lowerHexSchema } from '../../types/primitive'
+import type { ContractCreation } from '../types'
+import type { EtherscanV2Client } from './client'
+
+type GetContractCreatorAndCreationTxHashParameters = {
+  client: EtherscanV2Client
+  contractaddresses: Hex[]
+  headers?: Record<string, string>
+}
+
+const contractCreationSchema = z.object({
+  contractAddress: addressPrimitiveSchema,
+  contractCreator: addressPrimitiveSchema,
+  txHash: lowerHexSchema,
+})
+const resultSchema = z.array(contractCreationSchema)
+
+/** {@link https://docs.etherscan.io/etherscan-v2/api-endpoints/contracts#get-contract-creator-and-creation-tx-hash} */
+export const getContractCreatorAndCreationTxHash = async ({
+  client,
+  contractaddresses,
+  headers,
+}: GetContractCreatorAndCreationTxHashParameters): Promise<
+  ContractCreation[]
+> => {
+  try {
+    const result = await client.get({
+      path: '',
+      query: {
+        module: 'contract',
+        action: 'getcontractcreation',
+        contractaddresses: contractaddresses.join(','),
+      },
+      resultSchema,
+      headers,
+    })
+    return result
+  } catch (error) {
+    if (error instanceof Error && error.message.includes('No data found')) {
+      return []
+    }
+    throw error
+  }
+}

package/explorer/etherscanV2/getContractSourceCodeForVerifiedContract.ts

@@ -0,0 +1,54 @@
+import { z } from 'zod'
+import type { Hex } from '../../types'
+import type { Contract } from '../types'
+import type { EtherscanV2Client } from './client'
+
+type GetContractSourceCodeForVerifiedContractParameters = {
+  client: EtherscanV2Client
+  address: Hex
+  headers?: Record<string, string>
+}
+
+const resultSchema = z.array(
+  z.object({
+    ABI: z.string().optional(),
+    ContractName: z.string().optional(),
+  }),
+)
+
+/** {@link https://docs.etherscan.io/etherscan-v2/api-endpoints/contracts#get-contract-source-code-for-verified-contract-source-codes} */
+export const getContractSourceCodeForVerifiedContract = async ({
+  client,
+  address,
+  headers,
+}: GetContractSourceCodeForVerifiedContractParameters): Promise<
+  Contract | undefined
+> => {
+  const result = await client.get({
+    path: '',
+    query: {
+      module: 'contract',
+      action: 'getsourcecode',
+      address,
+    },
+    resultSchema,
+    headers,
+  })
+  if (result.length === 0) {
+    return undefined
+  }
+  const contract = result[0]
+  if (
+    contract.ABI === undefined ||
+    contract.ABI.length === 0 ||
+    contract.ContractName === undefined ||
+    contract.ContractName.length === 0
+  ) {
+    return undefined
+  }
+
+  return {
+    abi: contract.ABI,
+    name: contract.ContractName,
+  }
+}

package/explorer/etherscanV2/getEventLogsByAddressFilteredByTopics.ts

@@ -0,0 +1,67 @@
+import type { Hex } from 'viem'
+import { z } from 'zod'
+import type { LowerHex } from '../../types'
+import { addressPrimitiveSchema, lowerHexSchema } from '../../types/primitive'
+import type { LogWithBlockNumber } from '../types'
+import type { EtherscanV2Client } from './client'
+
+type GetEventLogsByAddressFilteredByTopicsParameters = {
+  client: EtherscanV2Client
+  address: Hex
+  topic0: LowerHex
+  fromBlock?: number
+  toBlock?: number
+  headers?: Record<string, string>
+}
+
+const logSchema = z.object({
+  address: addressPrimitiveSchema,
+  blockNumber: z
+    .string()
+    .regex(/^0x[\da-f]*$/)
+    .transform((x) => (x === '0x' ? 0 : Number(x))),
+  data: lowerHexSchema,
+  logIndex: z
+    .string()
+    .regex(/^0x[\da-f]*$/)
+    .transform((x) => (x === '0x' ? 0 : Number(x))),
+  topics: z
+    .array(lowerHexSchema.nullable())
+    .transform((x) => x.filter((v): v is LowerHex => v !== null)),
+  transactionHash: lowerHexSchema,
+})
+const resultSchema = z.array(logSchema)
+
+/** {@link https://docs.etherscan.io/etherscan-v2/api-endpoints/logs#get-event-logs-by-address-filtered-by-topics} */
+export const getEventLogsByAddressFilteredByTopics = async ({
+  client,
+  address,
+  topic0,
+  fromBlock,
+  toBlock,
+  headers,
+}: GetEventLogsByAddressFilteredByTopicsParameters): Promise<
+  LogWithBlockNumber[]
+> => {
+  try {
+    const result = await client.get({
+      path: '',
+      query: {
+        module: 'logs',
+        action: 'getLogs',
+        address,
+        topic0,
+        ...(fromBlock === undefined ? {} : { fromBlock: fromBlock.toString() }),
+        ...(toBlock === undefined ? {} : { toBlock: toBlock.toString() }),
+      },
+      resultSchema,
+      headers,
+    })
+    return result
+  } catch (error) {
+    if (error instanceof Error && error.message.includes('No records found')) {
+      return []
+    }
+    throw error
+  }
+}

package/explorer/etherscanV2/getInternalTransactionsByTransactionHash.ts

@@ -0,0 +1,76 @@
+import { z } from 'zod'
+import type { LowerHex } from '../../types'
+import type { InternalTransactionWithIndex } from '../../types/internalTransaction'
+import { addressPrimitiveSchema, bigintTextSchema } from '../../types/primitive'
+import type { EtherscanV2Client } from './client'
+
+type GetInternalTransactionsByTransactionHashParameters = {
+  client: EtherscanV2Client
+  txhash: LowerHex
+  headers?: Record<string, string>
+}
+
+const internalTransactionSchema = z.object({
+  blockNumber: z.string().regex(/^\d+$/).transform(Number),
+  contractAddress: z.union([
+    addressPrimitiveSchema,
+    z
+      .literal('')
+      .nullable()
+      .transform(() => undefined),
+  ]),
+  from: addressPrimitiveSchema,
+  gas: bigintTextSchema,
+  isError: z
+    .string()
+    .regex(/^\d+$/)
+    .transform((x) => x === '1'),
+  timeStamp: z.string().regex(/^\d+$/).transform(Number),
+  to: z.union([
+    addressPrimitiveSchema,
+    z
+      .literal('')
+      .nullable()
+      .transform(() => undefined),
+  ]),
+  value: bigintTextSchema,
+})
+const resultSchema = z.array(internalTransactionSchema)
+
+/** {@link https://docs.etherscan.io/etherscan-v2/api-endpoints/accounts#get-internal-transactions-by-transaction-hash} */
+export const getInternalTransactionsByTransactionHash = async ({
+  client,
+  txhash,
+  headers,
+}: GetInternalTransactionsByTransactionHashParameters): Promise<
+  InternalTransactionWithIndex[]
+> => {
+  try {
+    const result = await client.get({
+      path: '',
+      query: {
+        module: 'account',
+        action: 'txlistinternal',
+        txhash,
+      },
+      resultSchema,
+      headers,
+    })
+    return result.map((v) => ({
+      blockNumber: v.blockNumber,
+      contractAddress: v.contractAddress,
+      from: v.from,
+      gas: v.gas,
+      isError: v.isError,
+      timestamp: v.timeStamp * 1000,
+      to: v.to,
+      txHash: txhash,
+      value: v.value,
+    }))
+  } catch (error) {
+    if (error instanceof Error && error.message === 'No transactions found') {
+      return []
+    }
+    throw error
+  }
+}