@0xtorch/evm 0.0.1

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

@@ -0,0 +1,122 @@
+import type { Logger } from '@0xtorch/core'
+import { z } from 'zod'
+import type { Hex } from '../../../types'
+import { isHex, toLowerHex } from '../../../types'
+import { createEtherscanClient } from './middleware'
+
+type GetNormalTransactionsByAddressParameters = {
+  readonly apiEndpoint: string
+  readonly apiKey: 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(),
+  methodId: z.string(),
+  functionName: 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.etherscan.io/api-endpoints/accounts#get-a-list-of-normal-transactions-by-address} */
+export const getNormalTransactionsByAddress = async ({
+  apiEndpoint,
+  apiKey,
+  address,
+  startBlock = 0n,
+  endBlock,
+  page = 1,
+  offset = 10_000,
+  sort = 'asc',
+  logger,
+}: GetNormalTransactionsByAddressParameters): Promise<ReturnType> => {
+  try {
+    const { status, message, result } = await createEtherscanClient(
+      apiEndpoint,
+      apiKey,
+    ).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,
+        apiKey,
+        address,
+        startBlock,
+        endBlock,
+        page,
+        offset,
+        sort,
+        logger,
+      })
+    }
+    throw error
+  }
+}

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

@@ -0,0 +1,8 @@
+export { getBlockNumberOfTimestamp } from './getBlockNumberOfTimestamp'
+export { getContractByAddress } from './getContractByAddress'
+export { getErc1155TokenTransfersByAddress } from './getErc1155TokenTransfersByAddress'
+export { getErc20TokenTransfersByAddress } from './getErc20TokenTransfersByAddress'
+export { getErc721TokenTransfersByAddress } from './getErc721TokenTransfersByAddress'
+export { getInternalTransactionsByAddress } from './getInternalTransactionsByAddress'
+export { getInternalTransactionsByTransactionHash } from './getInternalTransactionsByTransactionHash'
+export { getNormalTransactionsByAddress } from './getNormalTransactionsByAddress'

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

@@ -0,0 +1,77 @@
+import type { Logger, Schema } from '@0xtorch/core'
+import { rest } from '@0xtorch/core'
+
+export const createEtherscanClient = (() => {
+  const mut_RequestTimestamps: { [key: string]: number[] | undefined } = {}
+
+  const createGet =
+    (endpoint: string, apiKey: string) =>
+    async <TData>(
+      url: string,
+      query: { [key: string]: string },
+      responseSchema: Schema<TData>,
+      logger?: Logger,
+    ) => {
+      const key = `${endpoint}?apikey=${apiKey}`
+      const mut_KeyRequestTimestamps = mut_RequestTimestamps[key]
+
+      // 1 日の request 回数が 100,000 回を超えたらエラーを返す
+      const dayLimit = 100_000
+      const time1DayAgo = Date.now() - 1000 * 60 * 60 * 24
+      if (
+        mut_KeyRequestTimestamps !== undefined &&
+        mut_KeyRequestTimestamps.filter((t) => t >= time1DayAgo).length >=
+          dayLimit
+      ) {
+        throw new Error('Daily API limit exceeded')
+      }
+
+      // 1 秒以内の  request 回数が 5 回以上だったら 1 秒待つ
+      const secondLimit = 5
+      const time1SecondAgo = Date.now() - 1000
+      if (
+        mut_KeyRequestTimestamps !== undefined &&
+        mut_KeyRequestTimestamps.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_KeyRequestTimestamps !== undefined &&
+              mut_KeyRequestTimestamps.filter((t) => t >= time1SecondAgo)
+                .length < secondLimit
+            ) {
+              clearInterval(intervalId)
+              resolve()
+              return
+            }
+            console.debug('wait 1 second')
+          }, 1000)
+        })
+      }
+
+      // requestTimestamps に追加
+      if (mut_KeyRequestTimestamps === undefined) {
+        mut_RequestTimestamps[key] = [Date.now()]
+      } else {
+        mut_KeyRequestTimestamps.push(Date.now())
+      }
+
+      const urlObject = new URL(`${endpoint}${url}`)
+      urlObject.searchParams.append('apikey', apiKey)
+      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, apiKey: string) => ({
+    get: createGet(apiEndpoint, apiKey),
+  })
+})()

package/src/explorers/externals/roninExplorer/getInternalTransactionByHash.ts

@@ -0,0 +1,80 @@
+import type { Logger } from '@0xtorch/core'
+import { rest } from '@0xtorch/core'
+import { z } from 'zod'
+import type { Hex } from '../../../types'
+import { isHex, toLowerHex } from '../../../types'
+
+type GetInternalTransactionByHashParameters = {
+  readonly apiEndpoint: string
+  readonly apiKey: string
+  readonly hash: Hex
+  readonly logger?: Logger
+}
+
+const transactionSchema = z.object({
+  tx_hash: z
+    .string()
+    .regex(/^0x[\da-f]{64}$/)
+    .transform((x) => (isHex(x) ? toLowerHex(x) : '0x')),
+  hash: 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),
+  input: z.string(),
+  index: z.number().int(),
+  success: z.boolean(),
+  block_number: z.number().int(),
+  block_hash: z.string(),
+  timestamp: z.number().int(),
+  tx_type: z.string(),
+})
+const responseSchema = z.object({
+  results: z.array(transactionSchema),
+  total: z.number().int(),
+})
+
+type Transaction = Readonly<z.infer<typeof transactionSchema>>
+type ReturnType = {
+  readonly total: number
+  readonly transactions: readonly Transaction[]
+}
+
+export const getInternalTransactionByHash = async ({
+  apiEndpoint,
+  apiKey,
+  hash,
+  logger,
+}: GetInternalTransactionByHashParameters): Promise<ReturnType> => {
+  try {
+    const { total, results } = await rest(
+      `${apiEndpoint}/explorer/tx/${hash}/internal?size=100`,
+      {
+        fetchOptions: {
+          headers: {
+            'X-API-KEY': apiKey,
+          },
+        },
+        schema: responseSchema,
+        logger,
+      },
+    )
+    return { total, transactions: results }
+  } catch (error) {
+    if (error instanceof Error && error.message === 'Max rate limit reached') {
+      await new Promise((resolve) => setTimeout(resolve, 1000))
+      return await getInternalTransactionByHash({
+        apiEndpoint,
+        apiKey,
+        hash,
+        logger,
+      })
+    }
+    throw error
+  }
+}

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

@@ -0,0 +1,79 @@
+import type { Logger } from '@0xtorch/core'
+import { z } from 'zod'
+import type { Hex } from '../../../types'
+import { isHex, toLowerHex } from '../../../types'
+import { createRoninExplorerClient } from './middleware'
+
+type GetNormalTransactionsByAddressParameters = {
+  readonly apiEndpoint: string
+  readonly address: Hex
+  readonly size?: number
+  readonly from?: number
+  readonly logger?: Logger
+}
+
+const transactionSchema = z.object({
+  hash: z
+    .string()
+    .regex(/^0x[\da-f]{64}$/)
+    .transform((x) => (isHex(x) ? toLowerHex(x) : '0x')),
+  block_hash: z.string(),
+  block_number: z.number().int(),
+  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)),
+  gas: z.string().regex(/^\d+$/).transform(BigInt),
+  gas_price: z.string().regex(/^\d+$/).transform(BigInt),
+  input: z.string().regex(/^0x[\da-f]*$/),
+  nonce: z.number().int(),
+  tx_index: z.number().int(),
+  value: z.string().regex(/^\d+$/).transform(BigInt),
+  gas_used: z.string().regex(/^\d+$/).transform(BigInt),
+  cumulative_gas_used: z.string().regex(/^\d+$/).transform(BigInt),
+  contract_address: z
+    .string()
+    .transform((x) => (isHex(x) ? toLowerHex(x) : undefined)),
+  status: z.number().int(),
+  timestamp: z.number().int(),
+})
+const responseSchema = z.object({
+  results: z.array(transactionSchema),
+  total: z.number().int(),
+})
+
+type Transaction = Readonly<z.infer<typeof transactionSchema>>
+type ReturnType = {
+  readonly total: number
+  readonly transactions: readonly Transaction[]
+}
+
+export const getNormalTransactionsByAddress = async ({
+  apiEndpoint,
+  address,
+  size = 100,
+  from = 0,
+  logger,
+}: GetNormalTransactionsByAddressParameters): Promise<ReturnType> => {
+  try {
+    const { results, total } = await createRoninExplorerClient().get(
+      `${apiEndpoint}/txs/${address}?from=${from}&size=${size}`,
+      responseSchema,
+      logger,
+    )
+    return { total, transactions: results }
+  } catch (error) {
+    if (error instanceof Error && error.message === 'Max rate limit reached') {
+      await new Promise((resolve) => setTimeout(resolve, 1000))
+      return await getNormalTransactionsByAddress({
+        apiEndpoint,
+        address,
+        size,
+        from,
+        logger,
+      })
+    }
+    throw error
+  }
+}

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

@@ -0,0 +1,81 @@
+import type { Logger } from '@0xtorch/core'
+import { z } from 'zod'
+import type { Hex } from '../../../types'
+import { isHex, toLowerHex } from '../../../types'
+import { createRoninExplorerClient } from './middleware'
+
+type GetTokenTransfersByAddressParameters = {
+  readonly apiEndpoint: string
+  readonly address: Hex
+  readonly size?: number
+  readonly from?: number
+  readonly logger?: Logger
+}
+
+const transferSchema = z.object({
+  from: 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),
+  log_index: z.string(),
+  tx_hash: z
+    .string()
+    .regex(/^0x[\da-f]{64}$/)
+    .transform((x) => (isHex(x) ? toLowerHex(x) : '0x')),
+  block_number: z.number().int(),
+  token_address: z
+    .string()
+    .regex(/^0x[\da-f]{40}$/)
+    .transform((x) => (isHex(x) ? toLowerHex(x) : '0x')),
+  token_decimals: z.number().int(),
+  token_name: z.string(),
+  token_symbol: z.string(),
+  token_type: z.string(),
+  token_id: z.string(),
+  block_hash: z.string(),
+  timestamp: z.number().int(),
+})
+const responseSchema = z.object({
+  results: z.array(transferSchema),
+  total: z.number().int(),
+})
+
+type Transfer = Readonly<z.infer<typeof transferSchema>>
+type ReturnType = {
+  readonly total: number
+  readonly transfers: readonly Transfer[]
+}
+
+export const getTokenTransfersByAddress = async ({
+  apiEndpoint,
+  address,
+  size = 100,
+  from = 0,
+  logger,
+}: GetTokenTransfersByAddressParameters): Promise<ReturnType> => {
+  try {
+    const { results, total } = await createRoninExplorerClient().get(
+      `${apiEndpoint}/tokentxs?addr=${address}&from=${from}&size=${size}`,
+      responseSchema,
+      logger,
+    )
+    return { total, transfers: results }
+  } catch (error) {
+    if (error instanceof Error && error.message === 'Max rate limit reached') {
+      await new Promise((resolve) => setTimeout(resolve, 1000))
+      return await getTokenTransfersByAddress({
+        apiEndpoint,
+        address,
+        size,
+        from,
+        logger,
+      })
+    }
+    throw error
+  }
+}

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

@@ -0,0 +1,3 @@
+export { getInternalTransactionByHash } from './getInternalTransactionByHash'
+export { getNormalTransactionsByAddress } from './getNormalTransactionsByAddress'
+export { getTokenTransfersByAddress } from './getTokenTransfersByAddress'

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

@@ -0,0 +1,49 @@
+import type { Logger, Schema } from '@0xtorch/core'
+import { rest } from '@0xtorch/core'
+
+export const createRoninExplorerClient = (() => {
+  const mut_RequestTimestamps: number[] = []
+
+  const get = async <TData>(
+    url: string,
+    responseSchema: Schema<TData>,
+    logger?: Logger,
+  ) => {
+    // 1 秒以内の  request 回数が 1 回以上だったら 1 秒待つ
+    const secondLimit = 1
+    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())
+
+    return await rest(url, {
+      schema: responseSchema,
+      logger,
+    })
+    // TODO error handling
+  }
+
+  return () => ({
+    get,
+  })
+})()

package/src/explorers/index.ts

@@ -0,0 +1,7 @@
+export {
+  createBlockscout,
+  createEtherscan,
+  createRoninExplorer,
+  createRoutescan,
+} from './definitions'
+export type { Explorer } from './types'

package/src/explorers/types.ts

@@ -0,0 +1,56 @@
+import type { CryptoCurrency, Logger } from '@0xtorch/core'
+import type { Hex, InternalTransaction } from '../types'
+
+export type Explorer = {
+  readonly name: string
+  readonly url: string
+  readonly apiUrl: string
+  readonly getAddressTransactionHashes: FunctionGetAddressTransactionHashes
+  readonly getAddressInternalTransactions: FunctionGetAddressInternalTransactions
+  readonly getAddressTokenTransferHashes: FunctionGetAddressTokenTransferHashes
+  readonly getBlockNumberOfTimestamp: (
+    timestamp: number,
+    logger?: Logger,
+  ) => Promise<bigint>
+  readonly getContract: FunctionGetContract
+  readonly getInternalTransactionOfTransaction: FunctionGetInternalTransactionOfTransaction
+}
+
+type FunctionGetAddressTransactionHashes = (parameters: {
+  readonly address: Hex
+  readonly startBlock?: bigint
+  readonly endBlock?: bigint
+  readonly logger?: Logger
+}) => Promise<readonly Hex[]>
+
+type FunctionGetAddressInternalTransactions = (parameters: {
+  readonly address: Hex
+  readonly startBlock?: bigint
+  readonly endBlock?: bigint
+  readonly nativeCurrency: CryptoCurrency
+  readonly logger?: Logger
+}) => Promise<readonly InternalTransaction<undefined>[]>
+
+type FunctionGetAddressTokenTransferHashes = (parameters: {
+  readonly address: Hex
+  readonly startBlock?: bigint
+  readonly endBlock?: bigint
+  readonly logger?: Logger
+}) => Promise<readonly Hex[]>
+
+type FunctionGetContract = (
+  address: Hex,
+  logger?: Logger,
+) => Promise<
+  | {
+      readonly name: string
+      readonly abi: string
+    }
+  | undefined
+>
+
+type FunctionGetInternalTransactionOfTransaction = (parameters: {
+  readonly hash: Hex
+  readonly nativeCurrency: CryptoCurrency
+  readonly logger?: Logger
+}) => Promise<readonly InternalTransaction<undefined>[]>

package/src/getAccountsTransactionFulls/getAccountsTransactionFulls.test.ts

@@ -0,0 +1,22 @@
+import { describe, expect, it } from 'bun:test'
+import { createEthereumChain } from '../chains'
+import { isIntegrationTest } from '../tests'
+import { getAccountsTransactionFulls } from './getAccountsTransactionFulls'
+
+describe.if(isIntegrationTest)('getAccountsTransactionFulls', () => {
+  it('should get accounts transaction fulls', async () => {
+    const chain = createEthereumChain(process.env.ETHERSCAN_API_KEY ?? '')
+    const addresses = ['0xd8da6bf26964af9d7eed9e03e53415d37aa96045'] as const
+    const fromBlock = 19_080_000n
+    const toBlock = 19_088_000n
+
+    const transactions = await getAccountsTransactionFulls({
+      chain,
+      addresses,
+      fromBlock,
+      toBlock,
+    })
+
+    expect(transactions).toHaveLength(12)
+  }, 60_000)
+})

package/src/getAccountsTransactionFulls/getAccountsTransactionFulls.ts

@@ -0,0 +1,46 @@
+import type { Config, FiatCurrency } from '@0xtorch/core'
+import { coingeckoCryptoCurrencyDataSource, usd } from '@0xtorch/core'
+import { analyzer } from '../analyzer'
+import type { Chain } from '../chains'
+import { decoder } from '../decoder'
+import type { LowerHex } from '../types'
+import { getAccountsTransactionFullsCustom } from './getAccountsTransactionFullsCustom'
+
+type GetAccountsTransactionFullsParameters = {
+  readonly chain: Chain
+  readonly addresses: readonly LowerHex[]
+  readonly fromBlock: bigint
+  readonly toBlock: bigint
+  readonly fiat?: FiatCurrency
+  readonly onFetchHashes?: (hashes: readonly LowerHex[]) => void
+  readonly onFetchTransaction?: (hash: LowerHex) => void
+}
+
+export const getAccountsTransactionFulls = async (
+  {
+    chain,
+    addresses,
+    fromBlock,
+    toBlock,
+    fiat = usd,
+    onFetchHashes,
+    onFetchTransaction,
+  }: GetAccountsTransactionFullsParameters,
+  config?: Config,
+) =>
+  await getAccountsTransactionFullsCustom(
+    {
+      chain,
+      addresses,
+      fromBlock,
+      toBlock,
+      appDataSource: undefined,
+      priceDataSource: coingeckoCryptoCurrencyDataSource,
+      fiat,
+      decoder,
+      analyzer,
+      onFetchHashes,
+      onFetchTransaction,
+    },
+    config,
+  )