@0xtorch/evm 0.0.1

package/src/explorers/definitions/etherscan.ts

@@ -0,0 +1,279 @@
+import type { Logger } from '@0xtorch/core'
+import type { InternalTransaction, LowerHex } from '../../types'
+import {
+  getBlockNumberOfTimestamp,
+  getContractByAddress,
+  getErc1155TokenTransfersByAddress,
+  getErc20TokenTransfersByAddress,
+  getErc721TokenTransfersByAddress,
+  getInternalTransactionsByAddress,
+  getInternalTransactionsByTransactionHash,
+  getNormalTransactionsByAddress,
+} from '../externals/etherscan'
+import { defineExplorer } from './defineExplorer'
+
+type CreateEtherscanExplorerParameters<
+  TName extends string,
+  TUrl extends string,
+  TApiUrl extends string,
+> = {
+  readonly name: TName
+  readonly url: TUrl
+  readonly apiUrl: TApiUrl
+  readonly apiKey: string
+}
+
+export const createEtherscan = <
+  TName extends string,
+  TUrl extends string,
+  TApiUrl extends string,
+>({
+  name,
+  url,
+  apiUrl,
+  apiKey,
+}: CreateEtherscanExplorerParameters<TName, TUrl, TApiUrl>) =>
+  defineExplorer({
+    name,
+    url,
+    apiUrl,
+    getAddressTransactionHashes: async ({
+      address,
+      startBlock,
+      endBlock,
+      logger,
+    }) => {
+      const loop = true
+      const hashSet = new Set<LowerHex>()
+      let mut_startBlock = startBlock
+      while (loop) {
+        const transactions = await getNormalTransactionsByAddress({
+          apiEndpoint: apiUrl,
+          apiKey,
+          address,
+          startBlock: mut_startBlock,
+          endBlock,
+          logger,
+        })
+        for (const { hash } of transactions) {
+          hashSet.add(hash)
+        }
+        if (transactions.length < 10_000) {
+          break
+        }
+        const maxTxBlockNumber = transactions.reduce(
+          (max, { blockNumber }) =>
+            max < BigInt(blockNumber) ? BigInt(blockNumber) : max,
+          0n,
+        )
+        if (maxTxBlockNumber === 0n || maxTxBlockNumber === mut_startBlock) {
+          break
+        }
+        mut_startBlock = maxTxBlockNumber
+      }
+      return [...hashSet]
+    },
+    getAddressInternalTransactions: async ({
+      address,
+      startBlock,
+      endBlock,
+      nativeCurrency,
+      logger,
+    }) => {
+      const loop = true
+      const mut_internalTransactions: InternalTransaction<undefined>[] = []
+      let mut_startBlock = startBlock
+      while (loop) {
+        const transactions = await getInternalTransactionsByAddress({
+          apiEndpoint: apiUrl,
+          apiKey,
+          address,
+          startBlock: mut_startBlock,
+          endBlock,
+          logger,
+        })
+        for (const transaction of transactions) {
+          if (
+            mut_internalTransactions.some(
+              ({ transactionHash, from, to, value }) =>
+                transaction.hash === transactionHash &&
+                transaction.from === from &&
+                transaction.to === to &&
+                transaction.value === value,
+            )
+          ) {
+            continue
+          }
+          mut_internalTransactions.push({
+            ...transaction,
+            type: 'InternalTransaction',
+            transactionHash: transaction.hash,
+            to: transaction.to,
+            contractAddress: transaction.contractAddress,
+            txType: transaction.type,
+            currency: nativeCurrency,
+            price: undefined,
+          })
+        }
+        if (transactions.length < 10_000) {
+          break
+        }
+        const maxTxBlockNumber = transactions.reduce(
+          (max, { blockNumber }) =>
+            max < BigInt(blockNumber) ? BigInt(blockNumber) : max,
+          0n,
+        )
+        if (maxTxBlockNumber === 0n || maxTxBlockNumber === mut_startBlock) {
+          break
+        }
+        mut_startBlock = maxTxBlockNumber
+      }
+      return mut_internalTransactions
+    },
+
+    getAddressTokenTransferHashes: async ({
+      address,
+      startBlock,
+      endBlock,
+      logger,
+    }) => {
+      const loop = true
+      const hashSet = new Set<LowerHex>()
+
+      // erc20 transfer
+      let mut_erc20StartBlock = startBlock
+      while (loop) {
+        const transfers = await getErc20TokenTransfersByAddress({
+          apiEndpoint: apiUrl,
+          apiKey,
+          address,
+          startBlock: mut_erc20StartBlock,
+          endBlock,
+          logger,
+        })
+        for (const { hash } of transfers) {
+          hashSet.add(hash)
+        }
+        if (transfers.length < 10_000) {
+          break
+        }
+        const maxTxBlockNumber = transfers.reduce(
+          (max, { blockNumber }) =>
+            max < BigInt(blockNumber) ? BigInt(blockNumber) : max,
+          0n,
+        )
+        if (
+          maxTxBlockNumber === 0n ||
+          maxTxBlockNumber === mut_erc20StartBlock
+        ) {
+          break
+        }
+        mut_erc20StartBlock = maxTxBlockNumber
+      }
+      // erc721 transfer
+      let mut_erc721StartBlock = startBlock
+      while (loop) {
+        const transfers = await getErc721TokenTransfersByAddress({
+          apiEndpoint: apiUrl,
+          apiKey,
+          address,
+          startBlock: mut_erc721StartBlock,
+          endBlock,
+          logger,
+        })
+        for (const { hash } of transfers) {
+          hashSet.add(hash)
+        }
+        if (transfers.length < 10_000) {
+          break
+        }
+        const maxTxBlockNumber = transfers.reduce(
+          (max, { blockNumber }) =>
+            max < BigInt(blockNumber) ? BigInt(blockNumber) : max,
+          0n,
+        )
+        if (
+          maxTxBlockNumber === 0n ||
+          maxTxBlockNumber === mut_erc721StartBlock
+        ) {
+          break
+        }
+        mut_erc721StartBlock = maxTxBlockNumber
+      }
+      // erc1155 transfer
+      let mut_erc1155StartBlock = startBlock
+      while (loop) {
+        const transfers = await getErc1155TokenTransfersByAddress({
+          apiEndpoint: apiUrl,
+          apiKey,
+          address,
+          startBlock: mut_erc1155StartBlock,
+          endBlock,
+          logger,
+        })
+        for (const { hash } of transfers) {
+          hashSet.add(hash)
+        }
+        if (transfers.length < 10_000) {
+          break
+        }
+        const maxTxBlockNumber = transfers.reduce(
+          (max, { blockNumber }) =>
+            max < BigInt(blockNumber) ? BigInt(blockNumber) : max,
+          0n,
+        )
+        if (
+          maxTxBlockNumber === 0n ||
+          maxTxBlockNumber === mut_erc1155StartBlock
+        ) {
+          break
+        }
+        mut_erc1155StartBlock = maxTxBlockNumber
+      }
+      return [...hashSet]
+    },
+    getBlockNumberOfTimestamp: async (timestamp, logger?: Logger) =>
+      await getBlockNumberOfTimestamp({
+        apiEndpoint: apiUrl,
+        apiKey,
+        timestamp,
+        logger,
+      }),
+    getContract: async (address, logger?: Logger) => {
+      const contract = await getContractByAddress({
+        apiEndpoint: apiUrl,
+        apiKey,
+        address,
+        logger,
+      })
+      if (contract === undefined) {
+        return
+      }
+      return {
+        name: contract.ContractName,
+        abi: contract.ABI,
+      }
+    },
+    getInternalTransactionOfTransaction: async ({
+      hash,
+      nativeCurrency,
+      logger,
+    }) => {
+      const transactions = await getInternalTransactionsByTransactionHash({
+        apiEndpoint: apiUrl,
+        apiKey,
+        transactionHash: hash,
+        logger,
+      })
+      return transactions.map((transaction) => ({
+        ...transaction,
+        type: 'InternalTransaction',
+        transactionHash: hash,
+        to: transaction.to,
+        contractAddress: transaction.contractAddress,
+        txType: transaction.type,
+        currency: nativeCurrency,
+        price: undefined,
+      }))
+    },
+  })

package/src/explorers/definitions/index.ts

@@ -0,0 +1,4 @@
+export { createBlockscout } from './blockscout'
+export { createEtherscan } from './etherscan'
+export { createRoninExplorer } from './roninExplorer'
+export { createRoutescan } from './routescan'

package/src/explorers/definitions/roninExplorer.ts

@@ -0,0 +1,150 @@
+import type { Hex } from 'viem'
+import {
+  getInternalTransactionByHash,
+  getNormalTransactionsByAddress,
+  getTokenTransfersByAddress,
+} from '../externals/roninExplorer'
+import { defineExplorer } from './defineExplorer'
+
+type CreateRoninExplorerParameters<
+  TName extends string,
+  TUrl extends string,
+  TApiUrl extends string,
+> = {
+  readonly name: TName
+  readonly url: TUrl
+  readonly apiUrl: TApiUrl
+  readonly apiKey: string
+  readonly explorerApiUrl: string
+}
+
+export const createRoninExplorer = <
+  TName extends string,
+  TUrl extends string,
+  TApiUrl extends string,
+>({
+  name,
+  url,
+  apiUrl,
+  apiKey,
+  explorerApiUrl,
+}: CreateRoninExplorerParameters<TName, TUrl, TApiUrl>) =>
+  defineExplorer({
+    name,
+    url,
+    apiUrl,
+    getAddressTransactionHashes: async ({
+      address,
+      startBlock,
+      endBlock,
+      logger,
+    }) => {
+      const hashSet = new Set<Hex>()
+      let mut_from = 0
+      while (mut_from >= 0) {
+        const { total, transactions } = await getNormalTransactionsByAddress({
+          apiEndpoint: explorerApiUrl,
+          address,
+          size: 100,
+          from: mut_from,
+          logger,
+        })
+        for (const transaction of transactions) {
+          if (
+            startBlock !== undefined &&
+            BigInt(transaction.block_number) < startBlock
+          ) {
+            return [...hashSet]
+          }
+          if (
+            endBlock === undefined ||
+            BigInt(transaction.block_number) <= endBlock
+          ) {
+            hashSet.add(transaction.hash)
+          }
+        }
+        mut_from += transactions.length
+        if (mut_from + transactions.length >= total) {
+          break
+        }
+      }
+      return [...hashSet]
+    },
+    getAddressInternalTransactions: ({ logger }) => {
+      if (logger !== undefined) {
+        logger.info('getAddressInternalTransactions is not implemented')
+      }
+      return Promise.resolve([])
+    },
+    getAddressTokenTransferHashes: async ({
+      address,
+      startBlock,
+      endBlock,
+      logger,
+    }) => {
+      const hashSet = new Set<Hex>()
+      let mut_from = 0
+      while (mut_from >= 0) {
+        const { total, transfers } = await getTokenTransfersByAddress({
+          apiEndpoint: explorerApiUrl,
+          address,
+          size: 100,
+          from: mut_from,
+          logger,
+        })
+        for (const transfer of transfers) {
+          if (
+            startBlock !== undefined &&
+            BigInt(transfer.block_number) < startBlock
+          ) {
+            return [...hashSet]
+          }
+          if (
+            endBlock === undefined ||
+            BigInt(transfer.block_number) <= endBlock
+          ) {
+            hashSet.add(transfer.tx_hash)
+          }
+        }
+        mut_from += transfers.length
+        if (mut_from + transfers.length >= total) {
+          break
+        }
+      }
+      return [...hashSet]
+    },
+    getBlockNumberOfTimestamp: () => {
+      throw new Error('getBlockNumberOfTimestamp is not implemented')
+    },
+    getContract: (_, logger) => {
+      if (logger !== undefined) {
+        logger.info('getContract is not implemented')
+      }
+      return Promise.resolve(undefined)
+    },
+    getInternalTransactionOfTransaction: async ({
+      hash,
+      nativeCurrency,
+      logger,
+    }) => {
+      const { transactions } = await getInternalTransactionByHash({
+        apiEndpoint: apiUrl,
+        apiKey,
+        hash,
+        logger,
+      })
+      return transactions.map((transaction) => ({
+        ...transaction,
+        type: 'InternalTransaction',
+        transactionHash: hash,
+        to: transaction.to,
+        contractAddress: undefined,
+        txType: transaction.tx_type,
+        gas: 0n,
+        gasUsed: 0n,
+        isError: transaction.success,
+        currency: nativeCurrency,
+        price: undefined,
+      }))
+    },
+  })

package/src/explorers/definitions/routescan.ts

@@ -0,0 +1,57 @@
+import { defineExplorer } from './defineExplorer'
+
+type CreateRoutescanExplorerParameters<
+  TName extends string,
+  TUrl extends string,
+  TApiUrl extends string,
+> = {
+  readonly name: TName
+  readonly url: TUrl
+  readonly apiUrl: TApiUrl
+  readonly apiKey: string
+}
+
+export const createRoutescan = <
+  TName extends string,
+  TUrl extends string,
+  TApiUrl extends string,
+>({
+  name,
+  url,
+  apiUrl,
+}: CreateRoutescanExplorerParameters<TName, TUrl, TApiUrl>) =>
+  defineExplorer({
+    name,
+    url,
+    apiUrl,
+    getAddressTransactionHashes: async () => {
+      // TODO implement
+      await new Promise((resolve) => setTimeout(resolve))
+      throw new Error('not implemented')
+    },
+    getAddressInternalTransactions: async () => {
+      // TODO implement
+      await new Promise((resolve) => setTimeout(resolve))
+      throw new Error('not implemented')
+    },
+    getAddressTokenTransferHashes: async () => {
+      // TODO implement
+      await new Promise((resolve) => setTimeout(resolve))
+      throw new Error('not implemented')
+    },
+    getBlockNumberOfTimestamp: async () => {
+      // TODO implement
+      await new Promise((resolve) => setTimeout(resolve))
+      throw new Error('not implemented')
+    },
+    getContract: async () => {
+      // TODO implement
+      await new Promise((resolve) => setTimeout(resolve))
+      throw new Error('not implemented')
+    },
+    getInternalTransactionOfTransaction: async () => {
+      // TODO implement
+      await new Promise((resolve) => setTimeout(resolve))
+      throw new Error('not implemented')
+    },
+  })

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

@@ -0,0 +1,67 @@
+import type { Logger } from '@0xtorch/core'
+import { z } from 'zod'
+import { createBlockscoutClient } from './middleware'
+
+type GetBlockNumberOfTimestampParameters = {
+  readonly apiEndpoint: 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.object({
+        blockNumber: z.string().regex(/^\d+$/).transform(BigInt),
+      }),
+      z.string(),
+    ])
+    .nullable(),
+})
+
+/** {@link https://docs.blockscout.com/for-users/api/rpc-endpoints/block#get-block-number-by-time-stamp} */
+export const getBlockNumberOfTimestamp = async ({
+  apiEndpoint,
+  timestamp,
+  closest = 'before',
+  logger,
+}: GetBlockNumberOfTimestampParameters): Promise<bigint> => {
+  try {
+    const { status, message, result } = await createBlockscoutClient(
+      apiEndpoint,
+    ).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.blockNumber
+  } catch (error) {
+    if (error instanceof Error && error.message === 'Max rate limit reached') {
+      await new Promise((resolve) => setTimeout(resolve, 1000))
+      return await getBlockNumberOfTimestamp({
+        apiEndpoint,
+        timestamp,
+        closest,
+        logger,
+      })
+    }
+    throw error
+  }
+}

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

@@ -0,0 +1,81 @@
+import type { Logger } from '@0xtorch/core'
+import { z } from 'zod'
+import type { Hex } from '../../../types'
+import { createBlockscoutClient } from './middleware'
+
+type GetContractByAddressParameters = {
+  readonly apiEndpoint: string
+  readonly address: Hex
+  readonly logger?: Logger
+}
+
+const sourceCodeSchema = z.object({
+  ABI: z.string(),
+  ContractName: z.string(),
+  CompilerVersion: z.string(),
+  OptimizationUsed: z.string(),
+})
+
+const responseSchema = z.object({
+  status: z.string(),
+  message: z.string(),
+  result: z
+    .union([
+      z.array(sourceCodeSchema),
+      z.array(z.object({})).transform(() => undefined),
+      z.string(),
+    ])
+    .nullable(),
+})
+
+type SourceCode = Readonly<z.infer<typeof sourceCodeSchema>>
+type ReturnType = SourceCode | undefined
+
+/** {@link https://docs.blockscout.com/for-users/api/rpc-endpoints/contract#get-contract-source-code-for-a-verified-contract} */
+export const getContractByAddress = async ({
+  apiEndpoint,
+  address,
+  logger,
+}: GetContractByAddressParameters): Promise<ReturnType> => {
+  try {
+    const { status, message, result } = await createBlockscoutClient(
+      apiEndpoint,
+    ).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 === undefined || 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,
+        address,
+        logger,
+      })
+    }
+    throw error
+  }
+}