@0xtorch/evm 0.0.61 → 0.0.63

package/explorer/blockscout/client.ts

@@ -0,0 +1,114 @@
+import { rest } from '@0xtorch/core'
+import { type ZodType, type ZodTypeDef, z } from 'zod'
+import { IS_DEBUG } from '../../tests'
+
+export type BlockscoutClient = {
+  get: <
+    Output,
+    Def extends ZodTypeDef = ZodTypeDef,
+    Input = Output,
+  >(parameters: {
+    path: string
+    query: Record<string, string>
+    resultSchema: ZodType<Output, Def, Input>
+  }) => Promise<Output>
+}
+
+export const createBlockscoutClient = (
+  apiBaseUrl: string,
+): BlockscoutClient => {
+  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.append(key, value)
+      }
+      if (IS_DEBUG) {
+        console.debug(`[GET] ${url.toString()}`)
+      }
+      const { status, message, result } = await rest(url.toString(), {
+        schema: responseSchema,
+      })
+      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'
+      ) {
+        if (IS_DEBUG) {
+          console.debug(error)
+        }
+        await new Promise((resolve) => setTimeout(resolve, 5000))
+        return await get({ path, query, resultSchema }, repeat + 1)
+      }
+
+      throw error
+    }
+  }
+
+  return {
+    get,
+  }
+}

package/explorer/blockscout/create.ts

@@ -0,0 +1,159 @@
+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 { createBlockscoutClient } from './client'
+import { getBlockNumberByTimestamp } from './getBlockNumberByTimestamp'
+import { getContractCreatorAddressHashAndCreationTransactionHash } from './getContractCreatorAddressHashAndCreationTransactionHash'
+import { getContractSourceCodeForAVerifiedContract } from './getContractSourceCodeForAVerifiedContract'
+import { getEventLogsByAddressAndTopic } from './getEventLogsByAddressAndTopic'
+import { getInternalTransactionsByAddressHash } from './getInternalTransactionsByAddressHash'
+import { getInternalTransactionsByTransactionHash } from './getInternalTransactionsByTransactionHash'
+import { getTokenTransferEventsByAddress } from './getTokenTransferEventsByAddress'
+import { getTransactionsByAddress } from './getTransactionsByAddress'
+
+type CreateBlockscoutParameters = {
+  name: string
+  baseUrl: string
+  apiBaseUrl: string
+}
+
+export const createBlockscout = ({
+  name,
+  baseUrl,
+  apiBaseUrl,
+}: CreateBlockscoutParameters): Explorer => {
+  const client = createBlockscoutClient(apiBaseUrl)
+
+  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 getInternalTransactionsByAddressHash({
+          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 getTransactionsByAddress({
+          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>()
+      let startblock = fromBlock
+      const endblock = toBlock
+      const maxPageSize = 10_000
+      while (true) {
+        const result = await getTokenTransferEventsByAddress({
+          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 }) =>
+      getBlockNumberByTimestamp({
+        client,
+        timestamp: Math.floor(timestamp / 1000),
+      }),
+    getContract: ({ address }) =>
+      getContractSourceCodeForAVerifiedContract({
+        client,
+        address,
+      }),
+    getContractCreations: ({ addresses }) =>
+      getContractCreatorAddressHashAndCreationTransactionHash({
+        client,
+        contractaddresses: addresses,
+      }),
+    getEventLogs: async ({
+      address,
+      topic0,
+      fromBlock: fromBlockParam,
+      toBlock: toBlockParam,
+    }) => {
+      const logs: LogWithBlockNumber[] = []
+      let fromBlock = fromBlockParam ?? 0
+      const toBlock = toBlockParam ?? 'latest'
+      const maxPageSize = 10_000
+      while (true) {
+        const result = await getEventLogsByAddressAndTopic({
+          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/blockscout/getBlockNumberByTimestamp.ts

@@ -0,0 +1,32 @@
+import { z } from 'zod'
+import type { BlockscoutClient } from './client'
+
+type GetBlockNumberByTimestampParameters = {
+  client: BlockscoutClient
+  /** Unix timestamp in seconds */
+  timestamp: number
+  closest?: 'before' | 'after'
+}
+
+const resultSchema = z.object({
+  blockNumber: z.string().regex(/^\d+$/).transform(Number),
+})
+
+/** {@link https://docs.blockscout.com/developer-support/api/rpc-endpoints/block#get-block-number-by-time-stamp} */
+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.blockNumber
+}

package/explorer/blockscout/getContractCreatorAddressHashAndCreationTransactionHash.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 { BlockscoutClient } from './client'
+
+type GetContractCreatorAddressHashAndCreationTransactionHashParameters = {
+  client: BlockscoutClient
+  contractaddresses: Hex[]
+}
+
+const contractCreationSchema = z.object({
+  contractAddress: addressPrimitiveSchema,
+  contractCreator: addressPrimitiveSchema,
+  txHash: lowerHexSchema,
+})
+const resultSchema = z.array(contractCreationSchema)
+
+/** {@link https://docs.blockscout.com/developer-support/api/rpc-endpoints/contract#get-contract-creator-address-hash-and-creation-transaction-hash} */
+export const getContractCreatorAddressHashAndCreationTransactionHash = async ({
+  client,
+  contractaddresses,
+}: GetContractCreatorAddressHashAndCreationTransactionHashParameters): Promise<
+  ContractCreation[]
+> => {
+  const result = await client.get({
+    path: '',
+    query: {
+      module: 'contract',
+      action: 'getcontractcreation',
+      contractaddresses: contractaddresses.join(','),
+    },
+    resultSchema,
+  })
+  return result
+}

package/explorer/blockscout/getContractSourceCodeForAVerifiedContract.ts

@@ -0,0 +1,51 @@
+import { z } from 'zod'
+import type { Hex } from '../../types'
+import type { Contract } from '../types'
+import type { BlockscoutClient } from './client'
+
+type GetContractSourceCodeForAVerifiedContractParameters = {
+  client: BlockscoutClient
+  address: Hex
+}
+
+const resultSchema = z.array(
+  z.object({
+    ABI: z.string().optional(),
+    ContractName: z.string().optional(),
+  }),
+)
+
+/** {@link https://docs.blockscout.com/developer-support/api/rpc-endpoints/contract#get-contract-source-code-for-a-verified-contract} */
+export const getContractSourceCodeForAVerifiedContract = async ({
+  client,
+  address,
+}: GetContractSourceCodeForAVerifiedContractParameters): 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/blockscout/getEventLogsByAddressAndTopic.ts

@@ -0,0 +1,54 @@
+import { z } from 'zod'
+import type { Hex, LowerHex } from '../../types'
+import { addressPrimitiveSchema, lowerHexSchema } from '../../types/primitive'
+import type { LogWithBlockNumber } from '../types'
+import type { BlockscoutClient } from './client'
+
+type GetEventLogsByAddressAndTopicParameters = {
+  client: BlockscoutClient
+  address: Hex
+  topic0: LowerHex
+  fromBlock: number | 'latest'
+  toBlock: number | 'latest'
+}
+
+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.blockscout.com/developer-support/api/rpc-endpoints/logs#get-event-logs-by-address-and-or-topic-s} */
+export const getEventLogsByAddressAndTopic = async ({
+  client,
+  address,
+  topic0,
+  fromBlock,
+  toBlock,
+}: GetEventLogsByAddressAndTopicParameters): Promise<LogWithBlockNumber[]> => {
+  const result = await client.get({
+    path: '',
+    query: {
+      module: 'logs',
+      action: 'getLogs',
+      address,
+      topic0,
+      fromBlock: fromBlock.toString(),
+      toBlock: toBlock.toString(),
+    },
+    resultSchema,
+  })
+  return result
+}

package/explorer/blockscout/getInternalTransactionsByAddressHash.ts

@@ -0,0 +1,101 @@
+import { z } from 'zod'
+import type { Hex } from '../../types'
+import type { InternalTransactionWithIndex } from '../../types/internalTransaction'
+import {
+  addressPrimitiveSchema,
+  bigintTextSchema,
+  lowerHexSchema,
+} from '../../types/primitive'
+import type { BlockscoutClient } from './client'
+
+type GetInternalTransactionsByAddressHashParameters = {
+  client: BlockscoutClient
+  address: Hex
+  startblock?: number
+  endblock?: number
+  page?: number
+  offset?: number
+  sort?: 'asc' | 'desc'
+}
+
+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),
+  ]),
+  transactionHash: lowerHexSchema,
+  value: bigintTextSchema,
+})
+
+const resultSchema = z.array(internalTransactionSchema)
+
+/** {@link https://docs.blockscout.com/developer-support/api/rpc-endpoints/account#get-internal-transactions-by-transaction-or-address-hash} */
+export const getInternalTransactionsByAddressHash = async ({
+  client,
+  address,
+  startblock = 0,
+  endblock,
+  page = 1,
+  offset = 10_000,
+  sort = 'asc',
+}: GetInternalTransactionsByAddressHashParameters): Promise<
+  InternalTransactionWithIndex[]
+> => {
+  try {
+    const result = await client.get({
+      path: '',
+      query: {
+        module: 'account',
+        action: 'txlistinternal',
+        address,
+        startblock: startblock.toString(),
+        ...(endblock === undefined
+          ? {}
+          : {
+              endblock: endblock.toString(),
+            }),
+        page: page.toString(),
+        offset: offset.toString(),
+        sort,
+      },
+      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: v.transactionHash,
+      value: v.value,
+    }))
+  } catch (error) {
+    if (
+      error instanceof Error &&
+      error.message === 'No internal transactions found'
+    ) {
+      return []
+    }
+    throw error
+  }
+}

package/explorer/blockscout/getInternalTransactionsByTransactionHash.ts

@@ -0,0 +1,82 @@
+import { z } from 'zod'
+import type { LowerHex } from '../../types'
+import type { InternalTransactionWithIndex } from '../../types/internalTransaction'
+import {
+  addressPrimitiveSchema,
+  bigintTextSchema,
+  lowerHexSchema,
+} from '../../types/primitive'
+import type { BlockscoutClient } from './client'
+
+type GetInternalTransactionsByTransactionHashParameters = {
+  client: BlockscoutClient
+  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),
+  ]),
+  transactionHash: lowerHexSchema,
+  value: bigintTextSchema,
+})
+
+const resultSchema = z.array(internalTransactionSchema)
+
+/** {@link https://docs.blockscout.com/developer-support/api/rpc-endpoints/account#get-internal-transactions-by-transaction-or-address-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: v.transactionHash,
+      value: v.value,
+    }))
+  } catch (error) {
+    if (
+      error instanceof Error &&
+      error.message === 'No internal transactions found'
+    ) {
+      return []
+    }
+    throw error
+  }
+}

package/explorer/blockscout/getTokenTransferEventsByAddress.ts

@@ -0,0 +1,68 @@
+import { z } from 'zod'
+import { lowerHexSchema } from '../../types/primitive'
+import type { TransactionIndex } from '../../types/transactionIndex'
+import type { BlockscoutClient } from './client'
+
+type GetTokenTransferEventsByAddressParameters = {
+  client: BlockscoutClient
+  address: string
+  startblock?: number
+  endblock?: number
+  page?: number
+  offset?: number
+  sort?: 'asc' | 'desc'
+}
+
+const transferSchema = z.object({
+  blockNumber: z.string().regex(/^\d+$/).transform(Number),
+  hash: lowerHexSchema,
+  timeStamp: z.string().regex(/^\d+$/).transform(Number),
+})
+const resultSchema = z.array(transferSchema)
+
+/** {@link https://docs.blockscout.com/developer-support/api/rpc-endpoints/account#get-token-transfer-events-by-address} */
+export const getTokenTransferEventsByAddress = async ({
+  client,
+  address,
+  startblock = 0,
+  endblock,
+  page = 1,
+  offset = 10_000,
+  sort = 'asc',
+}: GetTokenTransferEventsByAddressParameters): Promise<
+  readonly TransactionIndex[]
+> => {
+  try {
+    const result = await client.get({
+      path: '',
+      query: {
+        module: 'account',
+        action: 'tokentx',
+        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 token transfers found'
+    ) {
+      return []
+    }
+    throw error
+  }
+}