@0xtorch/evm 0.0.1

package/src/explorers/externals/blockscout/getInternalTransactionsByAddress.ts

@@ -0,0 +1,120 @@
+import type { Logger } from '@0xtorch/core'
+import { z } from 'zod'
+import type { Hex } from '../../../types'
+import { isHex, toLowerHex } from '../../../types'
+import { createBlockscoutClient } from './middleware'
+
+type GetInternalTransactionsByAddressParameters = {
+  readonly apiEndpoint: string
+  readonly address: Hex
+  readonly startBlock?: bigint
+  readonly endBlock?: bigint
+  readonly page?: number
+  readonly offset?: number
+  readonly sort?: 'asc' | 'desc'
+  readonly logger?: Logger
+}
+
+const transactionSchema = z.object({
+  blockNumber: z.string().regex(/^\d+$/).transform(BigInt),
+  timeStamp: z.string().regex(/^\d+$/).transform(Number),
+  transactionHash: z
+    .string()
+    .regex(/^0x[\da-f]{64}$/)
+    .transform((x) => (isHex(x) ? toLowerHex(x) : '0x')),
+  from: z
+    .string()
+    .regex(/^0x[\da-f]{40}$/)
+    .transform((x) => (isHex(x) ? toLowerHex(x) : '0x')),
+  to: z.string().transform((x) => (isHex(x) ? toLowerHex(x) : undefined)),
+  value: z.string().regex(/^\d+$/).transform(BigInt),
+  contractAddress: z
+    .string()
+    .transform((x) => (isHex(x) ? toLowerHex(x) : undefined)),
+  input: z.string(),
+  type: z.string(),
+  gas: z.string().regex(/^\d+$/).transform(BigInt),
+  gasUsed: z
+    .string()
+    .regex(/^\d*$/)
+    .transform((x) => (x.length === 0 ? 0n : BigInt(x))),
+  isError: z
+    .string()
+    .regex(/^\d+$/)
+    .transform((x) => (x === '1' ? true : false)),
+  errCode: z.string(),
+})
+const responseSchema = z.object({
+  status: z.string(),
+  message: z.string(),
+  result: z.union([z.array(transactionSchema), z.string()]).nullable(),
+})
+
+type Transaction = Readonly<z.infer<typeof transactionSchema>>
+type ReturnType = readonly Transaction[]
+
+/** {@link https://docs.blockscout.com/for-users/api/rpc-endpoints/account#get-internal-transactions-by-transaction-or-address-hash} */
+export const getInternalTransactionsByAddress = async ({
+  apiEndpoint,
+  address,
+  startBlock = 0n,
+  endBlock,
+  page = 1,
+  offset = 10_000,
+  sort = 'asc',
+  logger,
+}: GetInternalTransactionsByAddressParameters): Promise<ReturnType> => {
+  try {
+    const { status, message, result } = await createBlockscoutClient(
+      apiEndpoint,
+    ).get(
+      '',
+      {
+        module: 'account',
+        action: 'txlistinternal',
+        address,
+        startBlock: startBlock.toString(),
+        ...(endBlock === undefined
+          ? {}
+          : {
+              endblock: endBlock.toString(),
+            }),
+        page: page.toString(),
+        offset: offset.toString(),
+        sort,
+      },
+      responseSchema,
+      logger,
+    )
+    if (status !== '1' || result === null) {
+      if (
+        message === 'No transactions found' ||
+        message === 'No internal transactions found'
+      ) {
+        return []
+      }
+      const error =
+        typeof result === 'string' ? new Error(result) : new Error(message)
+      throw error
+    }
+    if (typeof result === 'string') {
+      throw new TypeError(result)
+    }
+    return result
+  } catch (error) {
+    if (error instanceof Error && error.message === 'Max rate limit reached') {
+      await new Promise((resolve) => setTimeout(resolve, 1000))
+      return await getInternalTransactionsByAddress({
+        apiEndpoint,
+        address,
+        startBlock,
+        endBlock,
+        page,
+        offset,
+        sort,
+        logger,
+      })
+    }
+    throw error
+  }
+}

package/src/explorers/externals/blockscout/getInternalTransactionsByTransactionHash.ts

@@ -0,0 +1,87 @@
+import type { Logger } from '@0xtorch/core'
+import { z } from 'zod'
+import type { Hex } from '../../../types'
+import { isHex, toLowerHex } from '../../../types'
+import { createBlockscoutClient } from './middleware'
+
+type GetInternalTransactionsByTransactionHashParameters = {
+  readonly apiEndpoint: string
+  readonly transactionHash: Hex
+  readonly logger?: Logger
+}
+
+const transactionSchema = z.object({
+  blockNumber: z.string().regex(/^\d+$/).transform(BigInt),
+  timeStamp: z.string().regex(/^\d+$/).transform(Number),
+  from: z
+    .string()
+    .regex(/^0x[\da-f]{40}$/)
+    .transform((x) => (isHex(x) ? toLowerHex(x) : '0x')),
+  to: z.string().transform((x) => (isHex(x) ? toLowerHex(x) : undefined)),
+  value: z.string().regex(/^\d+$/).transform(BigInt),
+  contractAddress: z
+    .string()
+    .transform((x) => (isHex(x) ? toLowerHex(x) : undefined)),
+  input: z.string(),
+  type: z.string(),
+  gas: z.string().regex(/^\d+$/).transform(BigInt),
+  gasUsed: z.string().regex(/^\d+$/).transform(BigInt),
+  isError: z
+    .string()
+    .regex(/^\d+$/)
+    .transform((x) => (x === '1' ? true : false)),
+  errCode: z.string(),
+})
+const responseSchema = z.object({
+  status: z.string(),
+  message: z.string(),
+  result: z.union([z.array(transactionSchema), z.string()]).nullable(),
+})
+
+type Transaction = Readonly<z.infer<typeof transactionSchema>>
+type ReturnType = readonly Transaction[]
+
+/** {@link https://docs.blockscout.com/for-users/api/rpc-endpoints/account#get-internal-transactions-by-transaction-or-address-hash} */
+export const getInternalTransactionsByTransactionHash = async ({
+  apiEndpoint,
+  transactionHash,
+  logger,
+}: GetInternalTransactionsByTransactionHashParameters): Promise<ReturnType> => {
+  try {
+    const { status, message, result } = await createBlockscoutClient(
+      apiEndpoint,
+    ).get(
+      '',
+      {
+        module: 'account',
+        action: 'txlistinternal',
+        txhash: transactionHash,
+      },
+      responseSchema,
+      logger,
+    )
+
+    if (status !== '1' || result === null) {
+      if (message === 'No transactions found') {
+        return []
+      }
+      const error =
+        typeof result === 'string' ? new Error(result) : new Error(message)
+      throw error
+    }
+    if (typeof result === 'string') {
+      throw new TypeError(result)
+    }
+    return result
+  } catch (error) {
+    if (error instanceof Error && error.message === 'Max rate limit reached') {
+      await new Promise((resolve) => setTimeout(resolve, 1000))
+      return getInternalTransactionsByTransactionHash({
+        apiEndpoint,
+        transactionHash,
+        logger,
+      })
+    }
+    throw error
+  }
+}

package/src/explorers/externals/blockscout/getNormalTransactionsByAddress.ts

@@ -0,0 +1,116 @@
+import type { Logger } from '@0xtorch/core'
+import { z } from 'zod'
+import type { Hex } from '../../../types'
+import { isHex, toLowerHex } from '../../../types'
+import { createBlockscoutClient } from './middleware'
+
+type GetNormalTransactionsByAddressParameters = {
+  readonly apiEndpoint: string
+  readonly address: Hex
+  readonly startBlock?: bigint
+  readonly endBlock?: bigint
+  readonly page?: number
+  readonly offset?: number
+  readonly sort?: 'asc' | 'desc'
+  readonly logger?: Logger
+}
+
+const transactionSchema = z.object({
+  blockNumber: z.string().regex(/^\d+$/).transform(BigInt),
+  timeStamp: z.string().regex(/^\d+$/).transform(Number),
+  hash: z
+    .string()
+    .regex(/^0x[\da-f]{64}$/)
+    .transform((x) => (isHex(x) ? toLowerHex(x) : '0x')),
+  nonce: z.string().regex(/^\d+$/).transform(Number),
+  blockHash: z.string(),
+  transactionIndex: z.string().regex(/^\d+$/).transform(Number),
+  from: z
+    .string()
+    .regex(/^0x[\da-f]{40}$/)
+    .transform((x) => (isHex(x) ? toLowerHex(x) : '0x')),
+  to: z.string().transform((x) => (isHex(x) ? toLowerHex(x) : undefined)),
+  value: z.string().regex(/^\d+$/).transform(BigInt),
+  gas: z.string().regex(/^\d+$/).transform(BigInt),
+  gasPrice: z.string().regex(/^\d+$/).transform(BigInt),
+  isError: z.string(),
+  txreceipt_status: z.string(),
+  input: z.string(),
+  contractAddress: z
+    .string()
+    .transform((x) => (isHex(x) ? toLowerHex(x) : undefined)),
+  cumulativeGasUsed: z.string().regex(/^\d+$/).transform(BigInt),
+  gasUsed: z.string().regex(/^\d+$/).transform(BigInt),
+  confirmations: z.string(),
+})
+const responseSchema = z.object({
+  status: z.string(),
+  message: z.string(),
+  result: z.union([z.array(transactionSchema), z.string()]).nullable(),
+})
+
+type Transaction = Readonly<z.infer<typeof transactionSchema>>
+type ReturnType = readonly Transaction[]
+
+/** {@link https://docs.blockscout.com/for-users/api/rpc-endpoints/account#get-transactions-by-address} */
+export const getNormalTransactionsByAddress = async ({
+  apiEndpoint,
+  address,
+  startBlock = 0n,
+  endBlock,
+  page = 1,
+  offset = 10_000,
+  sort = 'asc',
+  logger,
+}: GetNormalTransactionsByAddressParameters): Promise<ReturnType> => {
+  try {
+    const { status, message, result } = await createBlockscoutClient(
+      apiEndpoint,
+    ).get(
+      '',
+      {
+        module: 'account',
+        action: 'txlist',
+        address,
+        startblock: startBlock.toString(),
+        ...(endBlock === undefined
+          ? {}
+          : {
+              endblock: endBlock.toString(),
+            }),
+        page: page.toString(),
+        offset: offset.toString(),
+        sort,
+      },
+      responseSchema,
+      logger,
+    )
+    if (status !== '1' || result === null) {
+      if (message === 'No transactions found') {
+        return []
+      }
+      const error =
+        typeof result === 'string' ? new Error(result) : new Error(message)
+      throw error
+    }
+    if (typeof result === 'string') {
+      throw new TypeError(result)
+    }
+    return result
+  } catch (error) {
+    if (error instanceof Error && error.message === 'Max rate limit reached') {
+      await new Promise((resolve) => setTimeout(resolve, 1000))
+      return await getNormalTransactionsByAddress({
+        apiEndpoint,
+        address,
+        startBlock,
+        endBlock,
+        page,
+        offset,
+        sort,
+        logger,
+      })
+    }
+    throw error
+  }
+}

package/src/explorers/externals/blockscout/getTokenTransfersByAddress.ts

@@ -0,0 +1,127 @@
+import type { Logger } from '@0xtorch/core'
+import { z } from 'zod'
+import type { Hex } from '../../../types'
+import { isHex, toLowerHex } from '../../../types'
+import { createBlockscoutClient } from './middleware'
+
+type GetTokenTransfersByAddressParameters = {
+  readonly apiEndpoint: string
+  readonly address: Hex
+  readonly startBlock?: bigint
+  readonly endBlock?: bigint
+  readonly page?: number
+  readonly offset?: number
+  readonly sort?: 'asc' | 'desc'
+  readonly logger?: Logger
+}
+
+const transferSchema = z.object({
+  blockNumber: z.string().regex(/^\d+$/).transform(BigInt),
+  timeStamp: z.string().regex(/^\d+$/).transform(Number),
+  hash: z
+    .string()
+    .regex(/^0x[\da-f]{64}$/)
+    .transform((x) => (isHex(x) ? toLowerHex(x) : '0x')),
+  nonce: z.string().regex(/^\d+$/).transform(Number),
+  blockHash: z.string(),
+  from: z
+    .string()
+    .regex(/^0x[\da-f]{40}$/)
+    .transform((x) => (isHex(x) ? toLowerHex(x) : '0x')),
+  contractAddress: z
+    .string()
+    .regex(/^0x[\da-f]{40}$/)
+    .transform((x) => (isHex(x) ? toLowerHex(x) : '0x')),
+  to: z
+    .string()
+    .regex(/^0x[\da-f]{40}$/)
+    .transform((x) => (isHex(x) ? toLowerHex(x) : '0x')),
+  value: z.string().regex(/^\d+$/).transform(BigInt).optional(),
+  tokenName: z.string(),
+  tokenSymbol: z.string(),
+  tokenDecimal: z
+    .string()
+    .regex(/^\d*$/)
+    .transform((x) => (x.length === 0 ? undefined : Number(x))),
+  transactionIndex: z.string().regex(/^\d+$/).transform(Number),
+  gas: z.string().regex(/^\d+$/).transform(BigInt),
+  gasPrice: z.string().regex(/^\d+$/).transform(BigInt),
+  gasUsed: z.string().regex(/^\d+$/).transform(BigInt),
+  cumulativeGasUsed: z.string().regex(/^\d+$/).transform(BigInt),
+  input: z.string(),
+  confirmations: z.string(),
+})
+const responseSchema = z.object({
+  status: z.string(),
+  message: z.string(),
+  result: z.union([z.array(transferSchema), z.string()]).nullable(),
+})
+
+type Transfer = Readonly<z.infer<typeof transferSchema>>
+type ReturnType = readonly Transfer[]
+
+/** {@link https://docs.blockscout.com/for-users/api/rpc-endpoints/account#get-token-transfer-events-by-address} */
+export const getTokenTransfersByAddress = async ({
+  apiEndpoint,
+  address,
+  startBlock = 0n,
+  endBlock,
+  page = 1,
+  offset = 10_000,
+  sort = 'asc',
+  logger,
+}: GetTokenTransfersByAddressParameters): Promise<ReturnType> => {
+  try {
+    const { status, message, result } = await createBlockscoutClient(
+      apiEndpoint,
+    ).get(
+      '',
+      {
+        module: 'account',
+        action: 'tokentx',
+        address,
+        startblock: startBlock.toString(),
+        ...(endBlock === undefined
+          ? {}
+          : {
+              endblock: endBlock.toString(),
+            }),
+        page: page.toString(),
+        offset: offset.toString(),
+        sort,
+      },
+      responseSchema,
+      logger,
+    )
+    if (status !== '1' || result === null) {
+      if (
+        message === 'No transactions found' ||
+        message === 'No token transfers found'
+      ) {
+        return []
+      }
+      const error =
+        typeof result === 'string' ? new Error(result) : new Error(message)
+      throw error
+    }
+    if (typeof result === 'string') {
+      throw new TypeError(result)
+    }
+    return result
+  } catch (error) {
+    if (error instanceof Error && error.message === 'Max rate limit reached') {
+      await new Promise((resolve) => setTimeout(resolve, 1000))
+      return await getTokenTransfersByAddress({
+        apiEndpoint,
+        address,
+        startBlock,
+        endBlock,
+        page,
+        offset,
+        sort,
+        logger,
+      })
+    }
+    throw error
+  }
+}

package/src/explorers/externals/blockscout/index.ts

@@ -0,0 +1,6 @@
+export { getBlockNumberOfTimestamp } from './getBlockNumberOfTimestamp'
+export { getContractByAddress } from './getContractByAddress'
+export { getInternalTransactionsByAddress } from './getInternalTransactionsByAddress'
+export { getInternalTransactionsByTransactionHash } from './getInternalTransactionsByTransactionHash'
+export { getNormalTransactionsByAddress } from './getNormalTransactionsByAddress'
+export { getTokenTransfersByAddress } from './getTokenTransfersByAddress'

package/src/explorers/externals/blockscout/middleware.ts

@@ -0,0 +1,56 @@
+import type { Logger, Schema } from '@0xtorch/core'
+import { rest } from '@0xtorch/core'
+
+export const createBlockscoutClient = (() => {
+  const mut_requestTimestamps: number[] = []
+
+  const createGet =
+    (endpoint: string) =>
+    async <TData>(
+      url: string,
+      query: { [key: string]: string },
+      responseSchema: Schema<TData>,
+      logger?: Logger,
+    ) => {
+      // 1 秒以内の  request 回数が 5 回以上だったら 1 秒待つ
+      const secondLimit = 5
+      const time1SecondAgo = Date.now() - 1000
+      if (
+        mut_requestTimestamps.filter((t) => t >= time1SecondAgo).length >=
+        secondLimit
+      ) {
+        console.debug('wait 1 second')
+        await new Promise<void>((resolve) => {
+          const intervalId = setInterval(() => {
+            const time1SecondAgo = Date.now() - 1000
+            if (
+              mut_requestTimestamps.filter((t) => t >= time1SecondAgo).length <
+              secondLimit
+            ) {
+              clearInterval(intervalId)
+              resolve()
+              return
+            }
+            console.debug('wait 1 second')
+          }, 1000)
+        })
+      }
+
+      // requestTimestamps に追加
+      mut_requestTimestamps.push(Date.now())
+
+      const urlObject = new URL(`${endpoint}${url}`)
+      for (const [key, value] of Object.entries(query)) {
+        urlObject.searchParams.append(key, value)
+      }
+      return await rest(urlObject.toString(), {
+        schema: responseSchema,
+        logger,
+      })
+      // TODO error handling
+    }
+
+  return (apiEndpoint: string) => ({
+    get: createGet(apiEndpoint),
+  })
+})()

package/src/explorers/externals/defillama/getBlockNumberOfTimestamp.ts

@@ -0,0 +1,28 @@
+import type { Logger } from '@0xtorch/core'
+import { rest } from '@0xtorch/core'
+import { z } from 'zod'
+
+type GetBlockNumberOfTimestampParameters = {
+  readonly apiEndpoint: string
+  readonly chain: string
+  readonly timestampSeconds: number
+  readonly logger?: Logger
+}
+
+const responseSchema = z.object({
+  height: z.number().int(),
+  timestamp: z.number().int(),
+})
+
+export const getBlockNumberOfTimestamp = async ({
+  apiEndpoint,
+  chain,
+  timestampSeconds,
+  logger,
+}: GetBlockNumberOfTimestampParameters): Promise<bigint> => {
+  const response = await rest(
+    `${apiEndpoint}/block/${chain}/${timestampSeconds}`,
+    { schema: responseSchema, logger },
+  )
+  return BigInt(response.height)
+}

package/src/explorers/externals/defillama/index.ts

@@ -0,0 +1 @@
+export { getBlockNumberOfTimestamp } from './getBlockNumberOfTimestamp'

package/src/explorers/externals/etherscan/getBlockNumberOfTimestamp.ts

@@ -0,0 +1,66 @@
+import type { Logger } from '@0xtorch/core'
+import { z } from 'zod'
+import { createEtherscanClient } from './middleware'
+
+type GetBlockNumberOfTimestampParameters = {
+  readonly apiEndpoint: string
+  readonly apiKey: string
+  readonly timestamp: number
+  readonly closest?: 'before' | 'after'
+  readonly logger?: Logger
+}
+
+const responseSchema = z.object({
+  status: z.string(),
+  message: z.string(),
+  result: z
+    .union([z.string().regex(/^\d+$/).transform(BigInt), z.string()])
+    .nullable(),
+})
+
+/** {@link https://docs.etherscan.io/api-endpoints/blocks#get-block-number-by-timestamp} */
+export const getBlockNumberOfTimestamp = async ({
+  apiEndpoint,
+  apiKey,
+  timestamp,
+  closest = 'before',
+  logger,
+}: GetBlockNumberOfTimestampParameters): Promise<bigint> => {
+  try {
+    const { status, message, result } = await createEtherscanClient(
+      apiEndpoint,
+      apiKey,
+    ).get(
+      '',
+      {
+        module: 'block',
+        action: 'getblocknobytime',
+        timestamp: timestamp.toString(),
+        closest,
+      },
+      responseSchema,
+      logger,
+    )
+    if (status !== '1' || result === null) {
+      const error =
+        typeof result === 'string' ? new Error(result) : new Error(message)
+      throw error
+    }
+    if (typeof result === 'string') {
+      throw new TypeError(result)
+    }
+    return result
+  } catch (error) {
+    if (error instanceof Error && error.message === 'Max rate limit reached') {
+      await new Promise((resolve) => setTimeout(resolve, 1000))
+      return await getBlockNumberOfTimestamp({
+        apiEndpoint,
+        apiKey,
+        timestamp,
+        closest,
+        logger,
+      })
+    }
+    throw error
+  }
+}

package/src/explorers/externals/etherscan/getContractByAddress.ts

@@ -0,0 +1,86 @@
+import type { Logger } from '@0xtorch/core'
+import { z } from 'zod'
+import type { Hex } from '../../../types'
+import { createEtherscanClient } from './middleware'
+
+type GetContractByAddressParameters = {
+  readonly apiEndpoint: string
+  readonly apiKey: string
+  readonly address: Hex
+  readonly logger?: Logger
+}
+
+const sourceCodeSchema = z.object({
+  ABI: z.string(),
+  ContractName: z.string(),
+  CompilerVersion: z.string(),
+  OptimizationUsed: z.string(),
+  Runs: z.string(),
+  ConstructorArguments: z.string(),
+  EVMVersion: z.string(),
+  Library: z.string(),
+  LicenseType: z.string(),
+  Proxy: z.string(),
+  Implementation: z.string(),
+  SwarmSource: z.string(),
+})
+
+const responseSchema = z.object({
+  status: z.string(),
+  message: z.string(),
+  result: z.union([z.array(sourceCodeSchema), z.string()]).nullable(),
+})
+
+type SourceCode = Readonly<z.infer<typeof sourceCodeSchema>>
+type ReturnType = SourceCode | undefined
+
+/** {@link https://docs.etherscan.io/api-endpoints/contracts#get-contract-source-code-for-verified-contract-source-codes} */
+export const getContractByAddress = async ({
+  apiEndpoint,
+  apiKey,
+  address,
+  logger,
+}: GetContractByAddressParameters): Promise<ReturnType> => {
+  try {
+    const { status, message, result } = await createEtherscanClient(
+      apiEndpoint,
+      apiKey,
+    ).get(
+      '',
+      {
+        module: 'contract',
+        action: 'getsourcecode',
+        address,
+      },
+      responseSchema,
+      logger,
+    )
+    if (status !== '1' || result === null) {
+      const error =
+        typeof result === 'string' ? new Error(result) : new Error(message)
+      throw error
+    }
+    if (typeof result === 'string') {
+      throw new TypeError(result)
+    }
+    if (result.length === 0) {
+      return undefined
+    }
+    const contract = result[0]
+    if (contract.ABI === 'Contract source code not verified') {
+      return undefined
+    }
+    return contract
+  } catch (error) {
+    if (error instanceof Error && error.message === 'Max rate limit reached') {
+      await new Promise((resolve) => setTimeout(resolve, 1000))
+      return await getContractByAddress({
+        apiEndpoint,
+        apiKey,
+        address,
+        logger,
+      })
+    }
+    throw error
+  }
+}