@bigmi/core 0.2.1 → 0.3.0-beta.0

package/src/transports/blockchair/blockchair.spec.ts

@@ -0,0 +1,194 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { getBalance } from '../../actions/getBalance'
+import { getUTXOs } from '../../actions/getUTXOs'
+import { bitcoin } from '../../chains/bitcoin'
+import { BaseError } from '../../errors/base'
+import { InsufficientUTXOBalanceError } from '../../errors/utxo'
+import { createClient, rpcSchema } from '../../factories/createClient'
+import { createMockResponse } from '../../test/utils'
+import type { UTXOSchema } from '../types'
+import getInvalidBalanceReponse from './__mocks__/getBalance/invalidAddress.json'
+import getBalanceReponse from './__mocks__/getBalance/valid.json'
+import getUTXOsInvalidResponse from './__mocks__/getUTXOs/invalidAddress.json'
+import getUTXOsResponse from './__mocks__/getUTXOs/valid.json'
+import getUTXOsPaginatedResponse from './__mocks__/getUTXOs/validPaginated.json'
+import { blockchair } from './blockchair.js'
+import type {
+  BlockChairDashboardAddressResponse,
+  BlockchairAddressBalanceData,
+  BlockchairResponse,
+} from './blockchair.types'
+
+const address = import.meta.env.VITE_TEST_ADDRESS
+const apiKey = import.meta.env.VITE_TEST_BLOCKCHAIR_KEY
+
+const publicClient = createClient({
+  chain: bitcoin,
+  rpcSchema: rpcSchema<UTXOSchema>(),
+  transport: blockchair({
+    apiKey,
+  }),
+})
+
+describe('Blockchair Transport', () => {
+  beforeEach(() => {
+    vi.restoreAllMocks()
+  })
+
+  describe('getBalance', () => {
+    it('should fetch correct balance for valid address', async () => {
+      vi.spyOn(global, 'fetch').mockResolvedValue(
+        createMockResponse(getBalanceReponse as BlockchairAddressBalanceData)
+      )
+
+      const balance = await getBalance(publicClient, { address })
+      expect(balance).toBeTypeOf('bigint')
+    })
+
+    it('should throw error for non-existent address', async () => {
+      vi.spyOn(global, 'fetch').mockResolvedValue(
+        createMockResponse(
+          getInvalidBalanceReponse as BlockchairAddressBalanceData
+        )
+      )
+
+      const nonExistentAddress =
+        '1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNaNUIBNSUENopnoidsacn'
+      await expect(
+        getBalance(publicClient, { address: nonExistentAddress })
+      ).rejects.toThrow()
+    })
+  })
+
+  describe('getUTXOs', () => {
+    it('should return utxos with correct structure', async () => {
+      vi.spyOn(global, 'fetch').mockResolvedValue(
+        createMockResponse(
+          getUTXOsResponse as BlockchairResponse<BlockChairDashboardAddressResponse>
+        )
+      )
+
+      const utxos = await getUTXOs(publicClient, { address })
+
+      expect(utxos.length).toBeGreaterThan(0)
+      expect(utxos[0]).toMatchObject({
+        blockHeight: expect.any(Number),
+        scriptHex: expect.any(String),
+        txId: expect.any(String),
+        value: expect.any(Number),
+        vout: expect.any(Number),
+      })
+    })
+
+    it('should throw error when minValue exceeds balance', async () => {
+      vi.spyOn(global, 'fetch').mockImplementation((request) => {
+        const url = new URL(request.toString())
+
+        if (url.pathname.includes('/addresses/balances')) {
+          return Promise.resolve(
+            createMockResponse(
+              getBalanceReponse as BlockchairAddressBalanceData
+            )
+          )
+        }
+
+        if (url.pathname.includes('/dashboards/addresses')) {
+          return Promise.resolve(
+            createMockResponse(
+              getUTXOsResponse as BlockchairResponse<BlockChairDashboardAddressResponse>
+            )
+          )
+        }
+
+        throw new BaseError(`Unexpected URL: ${url.pathname}`)
+      })
+
+      const hugeValue = 999999999999999999n
+      await expect(
+        getUTXOs(publicClient, {
+          address,
+          minValue: Number(hugeValue),
+        })
+      ).rejects.toThrow(InsufficientUTXOBalanceError)
+    })
+
+    it('should handle empty UTXO response', async () => {
+      vi.spyOn(global, 'fetch').mockResolvedValue(
+        createMockResponse(getUTXOsInvalidResponse as BlockchairResponse<null>)
+      )
+
+      const emptyAddress = '12LRT14SgNFFQ3hMRThAyXNao24BBy5cyU'
+      const utxos = await getUTXOs(publicClient, { address: emptyAddress })
+
+      expect(utxos.length).toBe(0)
+    })
+
+    describe('pagination', () => {
+      const addressWithManyUTXOs = '1GrwDkr33gT6LuumniYjKEGjTLhsL5kmqC'
+      const minValue = 5_610_592_350
+
+      const createPaginatedMockResponse = (offset: number, limit: number) => ({
+        ...getUTXOsPaginatedResponse,
+        data: {
+          ...getUTXOsPaginatedResponse.data,
+          utxo: getUTXOsPaginatedResponse.data.utxo.slice(
+            offset,
+            offset + limit
+          ),
+          addresses: {
+            [addressWithManyUTXOs]: {
+              ...getUTXOsPaginatedResponse.data.addresses[addressWithManyUTXOs],
+              unspent_output_count: getUTXOsPaginatedResponse.data.utxo.length,
+            },
+          },
+        },
+      })
+
+      it('should handle pagination correctly', async () => {
+        vi.spyOn(global, 'fetch').mockImplementation((request) => {
+          const url = new URL(request.toString())
+
+          if (url.pathname.includes('/addresses/balances')) {
+            return Promise.resolve(
+              createMockResponse({
+                data: {
+                  [addressWithManyUTXOs]: 1000000000000,
+                },
+                context: { code: 200 },
+              } as BlockchairResponse<BlockchairAddressBalanceData>)
+            )
+          }
+
+          if (url.pathname.includes('/dashboards/addresses')) {
+            const offset = Number.parseInt(
+              url.searchParams.get('offset')?.split(',')[1] || '0'
+            )
+            const limit = 100
+            return Promise.resolve(
+              createMockResponse(
+                createPaginatedMockResponse(
+                  offset,
+                  limit
+                ) as BlockchairResponse<BlockChairDashboardAddressResponse>
+              )
+            )
+          }
+
+          throw new BaseError(`Unexpected URL: ${url.pathname}`)
+        })
+
+        const utxos = await getUTXOs(publicClient, {
+          address: addressWithManyUTXOs,
+          minValue,
+        })
+
+        expect(utxos.length).toBeGreaterThan(0)
+        expect(new Set(utxos.map((utxo) => utxo.txId)).size).toBe(utxos.length)
+        expect(global.fetch).toHaveBeenCalled()
+
+        const totalValue = utxos.reduce((sum, utxo) => sum + utxo.value, 0)
+        expect(totalValue).toBeGreaterThanOrEqual(minValue)
+      })
+    })
+  })
+})

package/src/transports/blockchair/blockchair.ts

@@ -0,0 +1,14 @@
+import type { HttpTransportConfig } from '../http.js'
+import { utxo } from '../utxo.js'
+
+type BlockchairConfig = {
+  baseUrl?: string
+  apiKey?: string
+} & HttpTransportConfig
+
+export const blockchair = (config: BlockchairConfig) =>
+  utxo(config?.baseUrl || 'https://api.blockchair.com', {
+    key: 'blockchair',
+    includeChainToURL: true,
+    ...config,
+  })

package/src/transports/blockchair/blockchair.types.ts

@@ -0,0 +1,59 @@
+export type BlockchairUTXO = {
+  block_id: number
+  transaction_hash: string
+  index: number
+  value: number
+  address: string
+}
+
+export type BlockChairDashboardAddressResponse = {
+  set: BlockChairDashboardSet
+  addresses: Record<string, BlockchairDashboardAddress>
+  transactions: Array<string>
+  utxo: Array<BlockchairUTXO>
+}
+
+export type BlockChairDashboardSet = {
+  address_count: number
+  balance: number
+  balance_usd: number
+  received: number
+  spent: number
+  output_count: number
+  unspent_output_count: number
+  first_seen_receiving: string
+  last_seen_receiving: string
+  first_seen_spending: string
+  last_seen_spending: string
+  transaction_count: number
+}
+
+export type BlockchairDashboardAddress = {
+  type: string
+  script_hex: string
+  balance: number
+  balance_usd: number
+  received: number
+  received_usd: number
+  spent: number
+  spent_usd: number
+  output_count: number
+  unspent_output_count: number
+  first_seen_receiving: string
+  last_seen_receiving: string
+  first_seen_spending: string
+  last_seen_spending: string
+}
+
+export type BlockchairAddressBalanceData<T = any> = Record<string, T>
+
+export type BlockchairResponse<T = any> = {
+  data: T
+  context: {
+    code: number
+    error?: string
+    limit?: number | string
+    offset?: number | string
+    total_rows?: number
+  }
+}

package/src/transports/blockchair/getBalance.ts

@@ -0,0 +1,32 @@
+import { urlWithParams } from '../../utils/url.js'
+import type { RpcMethodHandler } from '../types.js'
+import type {
+  BlockchairAddressBalanceData,
+  BlockchairResponse,
+} from './blockchair.types.js'
+
+export const getBalance: RpcMethodHandler<'getBalance'> = async (
+  client,
+  { baseUrl, apiKey },
+  { address }
+) => {
+  const apiUrl = urlWithParams(`${baseUrl}/addresses/balances`, {
+    key: apiKey,
+    addresses: address,
+  })
+  const response = (await client.request({
+    url: apiUrl,
+    fetchOptions: { method: 'GET' },
+  })) as unknown as BlockchairResponse<BlockchairAddressBalanceData>
+  if (response.context?.code !== 200) {
+    return {
+      error: {
+        code: response.context?.code,
+        message: response.context?.error,
+      },
+    }
+  }
+  return {
+    result: BigInt(response.data[address]),
+  }
+}

package/src/transports/blockchair/getUTXOs.ts

@@ -0,0 +1,121 @@
+import { RpcRequestError } from '../../errors/request.js'
+import { InsufficientUTXOBalanceError } from '../../errors/utxo.js'
+import type { UTXO } from '../../types/transaction.js'
+
+import { urlWithParams } from '../../utils/url.js'
+import type { RpcMethodHandler } from '../types.js'
+import type {
+  BlockChairDashboardAddressResponse,
+  BlockchairResponse,
+  BlockchairUTXO,
+} from './blockchair.types.js'
+import { getBalance } from './getBalance.js'
+
+const blockChairUTXOTransformer =
+  (scriptHex: string) =>
+  (data: BlockchairUTXO): UTXO => ({
+    blockHeight: data.block_id,
+    scriptHex,
+    txId: data.transaction_hash,
+    value: data.value,
+    vout: data.index,
+  })
+
+const MAX_API_LIMIT = '100,100'
+
+export const getUTXOs: RpcMethodHandler<'getUTXOs'> = async (
+  client,
+  { baseUrl, apiKey },
+  { address, minValue }
+) => {
+  async function* fetchUTXOs() {
+    let offset = 0
+    let hasMore = true
+
+    while (hasMore) {
+      const apiUrl = urlWithParams(
+        `${baseUrl}/dashboards/addresses/${address}`,
+        {
+          key: apiKey,
+          offset: `0,${offset}`,
+          limit: MAX_API_LIMIT,
+        }
+      )
+      const response = (await client.request({
+        url: apiUrl,
+        fetchOptions: { method: 'GET' },
+      })) as unknown as BlockchairResponse<BlockChairDashboardAddressResponse>
+
+      if (response.context?.code !== 200 && response.context?.code !== 404) {
+        throw new RpcRequestError({
+          url: apiUrl,
+          body: {
+            method: 'fetchUTXOs',
+            params: {
+              address,
+              minValue,
+            },
+          },
+          error: {
+            code: response.context.code,
+            message: response.context.error || 'Error fetching utxos',
+          },
+        })
+      }
+
+      if (!response.data || response.data.utxo.length === 0) {
+        hasMore = false
+        continue
+      }
+
+      const { limit } = response.context
+      const totalRows = response.data.addresses[address].unspent_output_count
+      if (limit && totalRows) {
+        const [, utxoLimit] = String(limit)
+          .split(',')
+          .map((val) => Number(val))
+        hasMore = offset + utxoLimit < totalRows
+        offset += utxoLimit
+      } else {
+        hasMore = false
+        offset += 0
+      }
+
+      yield response.data
+    }
+  }
+
+  if (minValue) {
+    const { result: balance } = await getBalance(
+      client,
+      { baseUrl, apiKey },
+      { address }
+    )
+    if (minValue > Number(balance)) {
+      throw new InsufficientUTXOBalanceError({
+        minValue,
+        address,
+        balance: Number(balance),
+      })
+    }
+  }
+  const utxos: UTXO[] = []
+  let valueCount = 0
+
+  for await (const batch of fetchUTXOs()) {
+    const addressScriptHex = batch.addresses[address].script_hex
+    const utxoBatch = batch.utxo.map(
+      blockChairUTXOTransformer(addressScriptHex)
+    )
+    utxos.push(...utxoBatch)
+
+    if (minValue) {
+      valueCount += utxoBatch.reduce((sum, utxo) => sum + utxo.value, 0)
+      if (valueCount >= minValue) {
+        break
+      }
+    }
+  }
+
+  return { result: utxos }
+}

package/src/transports/blockchair/methods.ts

@@ -0,0 +1,8 @@
+import type { RpcMethods } from '../types.js'
+import { getBalance } from './getBalance.js'
+import { getUTXOs } from './getUTXOs.js'
+
+export const blockchairMethods: RpcMethods = {
+  getBalance,
+  getUTXOs,
+}

package/src/transports/blockcypher/__mocks__/getBalance/invalid.json

@@ -0,0 +1,3 @@
+{
+  "error": "Address 1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNaNUIBNSUENopnoidsacn is invalid: Address 1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNaNUIBNSUENopnoidsacn is of unknown size."
+}

package/src/transports/blockcypher/__mocks__/getBalance/valid.json

@@ -0,0 +1,13 @@
+{
+  "address": "bc1qpvk0kjdg0kantu9z78qz7gqk53q643auz33yaw",
+  "total_received": 190653,
+  "total_sent": 157447,
+  "balance": 33206,
+  "unconfirmed_balance": 0,
+  "final_balance": 33206,
+  "n_tx": 19,
+  "unconfirmed_n_tx": 0,
+  "final_n_tx": 19,
+  "txrefs": [],
+  "tx_url": "https://api.blockcypher.com/v1/btc/main/txs/"
+}

package/src/transports/blockcypher/__mocks__/getUTXOs/empty.json

@@ -0,0 +1,12 @@
+{
+  "address": "12LRT14SgNFFQ3hMRThAyXNao24BBy5cyU",
+  "total_received": 0,
+  "total_sent": 0,
+  "balance": 0,
+  "unconfirmed_balance": 0,
+  "final_balance": 0,
+  "n_tx": 0,
+  "unconfirmed_n_tx": 0,
+  "final_n_tx": 0,
+  "tx_url": "https://api.blockcypher.com/v1/btc/main/txs/"
+}