@0xtorch/evm 0.0.1

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

@@ -0,0 +1,133 @@
+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 GetErc1155TokenTransfersByAddressParameters = {
+  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 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')),
+  tokenID: z.string().regex(/^\d+$/).transform(BigInt),
+  tokenValue: z.string().regex(/^\d+$/).transform(BigInt),
+  tokenName: z.string(),
+  tokenSymbol: z.string(),
+  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.etherscan.io/api-endpoints/accounts#get-a-list-of-erc1155-token-transfer-events-by-address}
+ */
+export const getErc1155TokenTransfersByAddress = async ({
+  apiEndpoint,
+  apiKey,
+  address,
+  startBlock = 0n,
+  endBlock,
+  page = 1,
+  offset = 10_000,
+  sort = 'asc',
+  logger,
+}: GetErc1155TokenTransfersByAddressParameters): Promise<ReturnType> => {
+  try {
+    const { status, message, result } = await createEtherscanClient(
+      apiEndpoint,
+      apiKey,
+    ).get(
+      '',
+      {
+        module: 'account',
+        action: 'token1155tx',
+        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 []
+      }
+      if (
+        message ===
+        'Query Timeout occured. Please select a smaller result dataset'
+      ) {
+        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 getErc1155TokenTransfersByAddress({
+        apiEndpoint,
+        apiKey,
+        address,
+        startBlock,
+        endBlock,
+        page,
+        offset,
+        sort,
+        logger,
+      })
+    }
+    throw error
+  }
+}

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

@@ -0,0 +1,125 @@
+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 GetErc20TokenTransfersByAddressParameters = {
+  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 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),
+  tokenName: z.string(),
+  tokenSymbol: z.string(),
+  tokenDecimal: z.string().regex(/^\d+$/).transform(Number),
+  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.etherscan.io/api-endpoints/accounts#get-a-list-of-erc20-token-transfer-events-by-address} */
+export const getErc20TokenTransfersByAddress = async ({
+  apiEndpoint,
+  apiKey,
+  address,
+  startBlock = 0n,
+  endBlock,
+  page = 1,
+  offset = 10_000,
+  sort = 'asc',
+  logger,
+}: GetErc20TokenTransfersByAddressParameters): Promise<ReturnType> => {
+  try {
+    const { status, message, result } = await createEtherscanClient(
+      apiEndpoint,
+      apiKey,
+    ).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') {
+        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 getErc20TokenTransfersByAddress({
+        apiEndpoint,
+        apiKey,
+        address,
+        startBlock,
+        endBlock,
+        page,
+        offset,
+        sort,
+        logger,
+      })
+    }
+    throw error
+  }
+}

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

@@ -0,0 +1,125 @@
+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 GetErc721TokenTransfersByAddressParameters = {
+  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 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')),
+  tokenID: z.string().regex(/^\d+$/).transform(BigInt),
+  tokenName: z.string(),
+  tokenSymbol: z.string(),
+  tokenDecimal: z.string().regex(/^\d+$/).transform(Number),
+  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.etherscan.io/api-endpoints/accounts#get-a-list-of-erc721-token-transfer-events-by-address} */
+export const getErc721TokenTransfersByAddress = async ({
+  apiEndpoint,
+  apiKey,
+  address,
+  startBlock = 0n,
+  endBlock,
+  page = 1,
+  offset = 10_000,
+  sort = 'asc',
+  logger,
+}: GetErc721TokenTransfersByAddressParameters): Promise<ReturnType> => {
+  try {
+    const { status, message, result } = await createEtherscanClient(
+      apiEndpoint,
+      apiKey,
+    ).get(
+      '',
+      {
+        module: 'account',
+        action: 'tokennfttx',
+        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 getErc721TokenTransfersByAddress({
+        apiEndpoint,
+        apiKey,
+        address,
+        startBlock,
+        endBlock,
+        page,
+        offset,
+        sort,
+        logger,
+      })
+    }
+    throw error
+  }
+}

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

@@ -0,0 +1,117 @@
+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 GetInternalTransactionsByAddressParameters = {
+  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')),
+  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[]
+
+export const getInternalTransactionsByAddress = async ({
+  apiEndpoint,
+  apiKey,
+  address,
+  startBlock = 0n,
+  endBlock,
+  page = 1,
+  offset = 10_000,
+  sort = 'asc',
+  logger,
+}: GetInternalTransactionsByAddressParameters): Promise<ReturnType> => {
+  try {
+    const { status, message, result } = await createEtherscanClient(
+      apiEndpoint,
+      apiKey,
+    ).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') {
+        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,
+        apiKey,
+        address,
+        startBlock,
+        endBlock,
+        page,
+        offset,
+        sort,
+        logger,
+      })
+    }
+    throw error
+  }
+}

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

@@ -0,0 +1,91 @@
+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 GetInternalTransactionsByTransactionHashParameters = {
+  readonly apiEndpoint: string
+  readonly apiKey: 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.etherscan.io/api-endpoints/accounts#get-internal-transactions-by-transaction-hash} */
+export const getInternalTransactionsByTransactionHash = async ({
+  apiEndpoint,
+  apiKey,
+  transactionHash,
+  logger,
+}: GetInternalTransactionsByTransactionHashParameters): Promise<ReturnType> => {
+  try {
+    const { status, message, result } = await createEtherscanClient(
+      apiEndpoint,
+      apiKey,
+    ).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,
+        apiKey,
+        transactionHash,
+        logger,
+      })
+    }
+    throw error
+  }
+}