@0xtorch/evm 0.0.61 → 0.0.63

package/explorer/blockscout/getTransactionsByAddress.ts

@@ -0,0 +1,64 @@
+import { z } from 'zod'
+import type { Hex } from '../../types'
+import { lowerHexSchema } from '../../types/primitive'
+import type { TransactionIndex } from '../../types/transactionIndex'
+import type { BlockscoutClient } from './client'
+
+type GetTransactionsByAddressParameters = {
+  client: BlockscoutClient
+  address: Hex
+  startblock?: number
+  endblock?: number
+  page?: number
+  offset?: number
+  sort?: 'asc' | 'desc'
+}
+
+const transactionSchema = z.object({
+  blockNumber: z.string().regex(/^\d+$/).transform(Number),
+  hash: lowerHexSchema,
+  timeStamp: z.string().regex(/^\d+$/).transform(Number),
+})
+const resultSchema = z.array(transactionSchema)
+
+/** {@link https://docs.blockscout.com/developer-support/api/rpc-endpoints/account#get-transactions-by-address} */
+export const getTransactionsByAddress = async ({
+  client,
+  address,
+  startblock = 0,
+  endblock,
+  page = 1,
+  offset = 10_000,
+  sort = 'asc',
+}: GetTransactionsByAddressParameters): Promise<TransactionIndex[]> => {
+  try {
+    const result = await client.get({
+      path: '',
+      query: {
+        module: 'account',
+        action: 'txlist',
+        address,
+        startblock: startblock.toString(),
+        ...(endblock === undefined
+          ? {}
+          : {
+              endblock: endblock.toString(),
+            }),
+        page: page.toString(),
+        offset: offset.toString(),
+        sort,
+      },
+      resultSchema,
+    })
+    return result.map((v) => ({
+      blockNumber: v.blockNumber,
+      hash: v.hash,
+      timestamp: v.timeStamp * 1000,
+    }))
+  } catch (error) {
+    if (error instanceof Error && error.message === 'No transactions found') {
+      return []
+    }
+    throw error
+  }
+}

package/explorer/etherscan/client.ts

@@ -0,0 +1,144 @@
+import { rest } from '@0xtorch/core'
+import { type ZodType, type ZodTypeDef, z } from 'zod'
+import { IS_DEBUG } from '../../tests'
+
+export type EtherscanClient = {
+  get: <
+    Output,
+    Def extends ZodTypeDef = ZodTypeDef,
+    Input = Output,
+  >(parameters: {
+    path: string
+    query: Record<string, string>
+    resultSchema: ZodType<Output, Def, Input>
+  }) => Promise<Output>
+}
+
+type CreateEtherscanClientParameters = {
+  apiBaseUrl: string
+  apiKey?: string
+  proxyUrl?: string
+  headers?: Record<string, string>
+}
+
+export const createEtherscanClient = ({
+  apiBaseUrl,
+  apiKey,
+  proxyUrl,
+  headers,
+}: CreateEtherscanClientParameters): EtherscanClient => {
+  // 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,
+    }: {
+      path: string
+      query: Record<string, string>
+      resultSchema: ZodType<Output, Def, Input>
+    },
+    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, apiBaseUrl)
+      for (const [key, value] of Object.entries(query)) {
+        url.searchParams.set(key, value)
+      }
+      if (apiKey !== undefined) {
+        url.searchParams.set('apikey', apiKey)
+      }
+      if (IS_DEBUG) {
+        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 &&
+        (error.message === 'Max rate limit reached' ||
+          error.message === 'Max calls per sec rate limit reached' ||
+          error.message ===
+            'Max rate limit reached, please use API Key for higher rate limit')
+      ) {
+        if (IS_DEBUG) {
+          console.debug(error)
+        }
+        await new Promise((resolve) => setTimeout(resolve, 5000))
+        return get({ path, query, resultSchema }, repeat + 1)
+      }
+      throw error
+    }
+  }
+
+  return {
+    get,
+  }
+}

package/explorer/etherscan/create.ts

@@ -0,0 +1,216 @@
+import type { 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 { createEtherscanClient } 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 CreateEtherscanParameters = {
+  name: string
+  baseUrl: string
+  apiBaseUrl: string
+  apiKey?: string
+  proxyUrl?: string
+  headers?: Record<string, string>
+}
+
+export const createEtherscan = ({
+  name,
+  baseUrl,
+  apiBaseUrl,
+  apiKey,
+  proxyUrl,
+  headers,
+}: CreateEtherscanParameters): Explorer => {
+  const client = createEtherscanClient({
+    apiBaseUrl,
+    apiKey,
+    proxyUrl,
+    headers,
+  })
+
+  return {
+    name,
+    baseUrl,
+    getAddressInternalTransactions: async ({ address, fromBlock, toBlock }) => {
+      const internalTransactions = new Map<
+        string,
+        InternalTransactionWithIndex
+      >()
+      let startblock = fromBlock
+      const endblock = toBlock
+      const maxPageSize = 10_000
+      while (true) {
+        const result = await getListOfInternalTransactionsByAddress({
+          client,
+          address,
+          startblock,
+          endblock,
+        })
+        for (const transaction of result) {
+          const id = createInternalTransactionId(transaction)
+          if (!internalTransactions.has(id)) {
+            internalTransactions.set(id, transaction)
+          }
+        }
+        if (result.length < maxPageSize) {
+          break
+        }
+        const maxBlockNumber = Math.max(...result.map((x) => x.blockNumber))
+        startblock = maxBlockNumber
+      }
+      return [...internalTransactions.values()]
+    },
+    getAddressTransactionIndexes: async ({ address, fromBlock, toBlock }) => {
+      const indexes = new Map<LowerHex, TransactionIndex>()
+      let startblock = fromBlock
+      const endblock = toBlock
+      const maxPageSize = 10_000
+      while (true) {
+        const result = await getListOfNormalTransactionsByAddress({
+          client,
+          address,
+          startblock,
+          endblock,
+        })
+        for (const index of result) {
+          if (!indexes.has(index.hash)) {
+            indexes.set(index.hash, index)
+          }
+        }
+        if (result.length < maxPageSize) {
+          break
+        }
+        const maxBlockNumber = Math.max(...result.map((x) => x.blockNumber))
+        startblock = maxBlockNumber
+      }
+      return [...indexes.values()]
+    },
+    getAddressTokenTransferIndexes: async ({ address, fromBlock, toBlock }) => {
+      const indexes = new Map<LowerHex, TransactionIndex>()
+      const maxPageSize = 10_000
+      const endblock = toBlock
+
+      // ERC20
+      let startblock = fromBlock
+      while (true) {
+        const result = await getListOfErc20TokenTransferEventsByAddress({
+          client,
+          address,
+          startblock,
+          endblock,
+        })
+        for (const index of result) {
+          if (!indexes.has(index.hash)) {
+            indexes.set(index.hash, index)
+          }
+        }
+        if (result.length < maxPageSize) {
+          break
+        }
+        const maxBlockNumber = Math.max(...result.map((x) => x.blockNumber))
+        startblock = maxBlockNumber
+      }
+
+      // ERC721
+      startblock = fromBlock
+      while (true) {
+        const result = await getListOfErc721TokenTransferEventsByAddress({
+          client,
+          address,
+          startblock,
+          endblock,
+        })
+        for (const index of result) {
+          if (!indexes.has(index.hash)) {
+            indexes.set(index.hash, index)
+          }
+        }
+        if (result.length < maxPageSize) {
+          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,
+        })
+        for (const index of result) {
+          if (!indexes.has(index.hash)) {
+            indexes.set(index.hash, index)
+          }
+        }
+        if (result.length < maxPageSize) {
+          break
+        }
+        const maxBlockNumber = Math.max(...result.map((x) => x.blockNumber))
+        startblock = maxBlockNumber
+      }
+
+      return [...indexes.values()]
+    },
+    getBlockNumberOfTimestamp: ({ timestamp }): Promise<number> =>
+      getBlockNumberByTimestamp({
+        client,
+        timestamp: Math.floor(timestamp / 1000),
+      }),
+    getContract: ({ address }) =>
+      getContractSourceCodeForVerifiedContract({
+        client,
+        address,
+      }),
+    getContractCreations: ({ addresses }) =>
+      getContractCreatorAndCreationTxHash({
+        client,
+        contractaddresses: addresses,
+      }),
+    getEventLogs: async ({
+      address,
+      topic0,
+      fromBlock: fromBlockParam,
+      toBlock,
+    }) => {
+      const logs: LogWithBlockNumber[] = []
+      let fromBlock = fromBlockParam ?? 0
+      const maxPageSize = 10_000
+      while (true) {
+        const result = await getEventLogsByAddressFilteredByTopics({
+          client,
+          address,
+          topic0,
+          fromBlock,
+          toBlock,
+        })
+        logs.push(...result)
+        if (result.length < maxPageSize) {
+          break
+        }
+        const maxBlockNumber = Math.max(...result.map((x) => x.blockNumber))
+        fromBlock = maxBlockNumber
+      }
+      return logs
+    },
+    getInternalTransactionOfTransaction: ({ hash }) =>
+      getInternalTransactionsByTransactionHash({
+        client,
+        txhash: hash,
+      }),
+  }
+}

package/explorer/etherscan/getBlockNumberByTimestamp.ts

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

package/explorer/etherscan/getContractCreatorAndCreationTxHash.ts

@@ -0,0 +1,36 @@
+import { z } from 'zod'
+import type { Hex } from '../../types'
+import { addressPrimitiveSchema, lowerHexSchema } from '../../types/primitive'
+import type { ContractCreation } from '../types'
+import type { EtherscanClient } from './client'
+
+type GetContractCreatorAndCreationTxHashParameters = {
+  client: EtherscanClient
+  contractaddresses: Hex[]
+}
+
+const contractCreationSchema = z.object({
+  contractAddress: addressPrimitiveSchema,
+  contractCreator: addressPrimitiveSchema,
+  txHash: lowerHexSchema,
+})
+const resultSchema = z.array(contractCreationSchema)
+
+/** {@link https://docs.etherscan.io/api-endpoints/contracts#get-contract-creator-and-creation-tx-hash} */
+export const getContractCreatorAndCreationTxHash = async ({
+  client,
+  contractaddresses,
+}: GetContractCreatorAndCreationTxHashParameters): Promise<
+  ContractCreation[]
+> => {
+  const result = await client.get({
+    path: '',
+    query: {
+      module: 'contract',
+      action: 'getcontractcreation',
+      contractaddresses: contractaddresses.join(','),
+    },
+    resultSchema,
+  })
+  return result
+}

package/explorer/etherscan/getContractSourceCodeForVerifiedContract.ts

@@ -0,0 +1,51 @@
+import { z } from 'zod'
+import type { Hex } from '../../types'
+import type { Contract } from '../types'
+import type { EtherscanClient } from './client'
+
+type GetContractSourceCodeForVerifiedContractParameters = {
+  client: EtherscanClient
+  address: Hex
+}
+
+const resultSchema = z.array(
+  z.object({
+    ABI: z.string().optional(),
+    ContractName: z.string().optional(),
+  }),
+)
+
+/** {@link https://docs.etherscan.io/api-endpoints/contracts#get-contract-source-code-for-verified-contract-source-codes} */
+export const getContractSourceCodeForVerifiedContract = async ({
+  client,
+  address,
+}: GetContractSourceCodeForVerifiedContractParameters): Promise<
+  Contract | undefined
+> => {
+  const result = await client.get({
+    path: '',
+    query: {
+      module: 'contract',
+      action: 'getsourcecode',
+      address,
+    },
+    resultSchema,
+  })
+  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/etherscan/getEventLogsByAddressFilteredByTopics.ts

@@ -0,0 +1,57 @@
+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 { EtherscanClient } from './client'
+
+type GetEventLogsByAddressFilteredByTopicsParameters = {
+  client: EtherscanClient
+  address: Hex
+  topic0: LowerHex
+  fromBlock?: number
+  toBlock?: number
+}
+
+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/api-endpoints/logs#get-event-logs-by-address-filtered-by-topics} */
+export const getEventLogsByAddressFilteredByTopics = async ({
+  client,
+  address,
+  topic0,
+  fromBlock,
+  toBlock,
+}: GetEventLogsByAddressFilteredByTopicsParameters): Promise<
+  LogWithBlockNumber[]
+> => {
+  const result = await client.get({
+    path: '',
+    query: {
+      module: 'logs',
+      action: 'getLogs',
+      address,
+      topic0,
+      ...(fromBlock === undefined ? {} : { fromBlock: fromBlock.toString() }),
+      ...(toBlock === undefined ? {} : { toBlock: toBlock.toString() }),
+    },
+    resultSchema,
+  })
+  return result
+}

package/explorer/etherscan/getInternalTransactionsByTransactionHash.ts

@@ -0,0 +1,73 @@
+import { z } from 'zod'
+import type { LowerHex } from '../../types'
+import type { InternalTransactionWithIndex } from '../../types/internalTransaction'
+import { addressPrimitiveSchema, bigintTextSchema } from '../../types/primitive'
+import type { EtherscanClient } from './client'
+
+type GetInternalTransactionsByTransactionHashParameters = {
+  client: EtherscanClient
+  txhash: LowerHex
+}
+
+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/api-endpoints/accounts#get-internal-transactions-by-transaction-hash} */
+export const getInternalTransactionsByTransactionHash = async ({
+  client,
+  txhash,
+}: GetInternalTransactionsByTransactionHashParameters): Promise<
+  InternalTransactionWithIndex[]
+> => {
+  try {
+    const result = await client.get({
+      path: '',
+      query: {
+        module: 'account',
+        action: 'txlistinternal',
+        txhash,
+      },
+      resultSchema,
+    })
+    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
+  }
+}