@bigmi/core 0.2.0 → 0.3.0-beta.0

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

@@ -0,0 +1,27 @@
+{
+  "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_hash": "4b6ee974f1dd179071d027562e1fd1c83965efa4a171ec84f00b6c638e36fa4e",
+      "block_height": 897002,
+      "tx_input_n": -1,
+      "tx_output_n": 2,
+      "value": 33206,
+      "ref_balance": 80786,
+      "spent": false,
+      "confirmations": 526,
+      "confirmed": "2025-05-16T19:17:40Z",
+      "double_spend": false,
+      "script": "00140b2cfb49a87dbb35f0a2f1c02f2016a441aac7bc"
+    }
+  ],
+  "tx_url": "https://api.blockcypher.com/v1/btc/main/txs/"
+}

package/src/transports/blockcypher/blockcyper.spec.ts

@@ -0,0 +1,122 @@
+import { beforeEach } from 'node:test'
+import { describe, expect, it, vi } from 'vitest'
+import { getBalance } from '../../actions/getBalance.js'
+import { getUTXOs } from '../../actions/getUTXOs.js'
+import { bitcoin } from '../../chains/bitcoin.js'
+import { NotEnoughUTXOError } from '../../errors/address.js'
+import { createClient, rpcSchema } from '../../factories/createClient.js'
+import { createMockResponse } from '../../test/utils.js'
+import type { UTXOSchema } from '../types.js'
+import getBalanceInValidResponse from './__mocks__/getBalance/invalid.json'
+import getBalanceValidResponse from './__mocks__/getBalance/valid.json'
+import getUTXOsEmptyReponse from './__mocks__/getUTXOs/empty.json'
+import getUTXOsPaginatedReponse from './__mocks__/getUTXOs/paginated.json'
+import getUTXOsValidReponse from './__mocks__/getUTXOs/valid.json'
+import { blockcypher } from './blockcypher.js'
+import type {
+  BlockcypherBalanceResponse,
+  BlockcypherErrorResponse,
+  BlockcypherUTXOsResponse,
+} from './blockcypher.types.js'
+
+const apiKey = import.meta.env.VITE_TEST_BLOCKCYPHER_API_KEY
+
+const publicClient = createClient({
+  chain: bitcoin,
+  rpcSchema: rpcSchema<UTXOSchema>(),
+  transport: blockcypher({
+    apiKey,
+  }),
+})
+
+const address = import.meta.env.VITE_TEST_ADDRESS
+
+describe('Blockcypher Transport', () => {
+  beforeEach(() => {
+    vi.restoreAllMocks()
+  })
+
+  describe('getBalance action', () => {
+    it('should fetch correct balance', async () => {
+      vi.spyOn(global, 'fetch').mockResolvedValue(
+        createMockResponse(
+          getBalanceValidResponse as BlockcypherBalanceResponse
+        )
+      )
+      const balance = await getBalance(publicClient, { address })
+      expect(balance).toBeTypeOf('bigint')
+    })
+
+    it('should throw an error for invalid address response', async () => {
+      vi.spyOn(global, 'fetch').mockResolvedValue(
+        createMockResponse(
+          getBalanceInValidResponse as BlockcypherErrorResponse
+        )
+      )
+
+      const nonExistentAddress =
+        '1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNaNUIBNSUENopnoidsacn'
+      await expect(
+        getBalance(publicClient, { address: nonExistentAddress })
+      ).rejects.toThrow()
+    })
+  })
+
+  describe('getUTXOs action', async () => {
+    it('should return utxos with correct structure', async () => {
+      vi.spyOn(global, 'fetch').mockResolvedValue(
+        createMockResponse(getUTXOsValidReponse as BlockcypherUTXOsResponse)
+      )
+      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').mockResolvedValue(
+        createMockResponse(getUTXOsValidReponse as BlockcypherUTXOsResponse)
+      )
+      const hugeValue = 999999999999999999n
+      await expect(
+        getUTXOs(publicClient, {
+          address,
+          minValue: Number(hugeValue),
+        })
+      ).rejects.toThrow(NotEnoughUTXOError)
+    })
+
+    it('should handle empty UTXO', async () => {
+      vi.spyOn(global, 'fetch').mockResolvedValue(
+        createMockResponse(getUTXOsEmptyReponse as BlockcypherBalanceResponse)
+      )
+      const emptyAddress = '12LRT14SgNFFQ3hMRThAyXNao24BBy5cyU'
+      const utxos = await getUTXOs(publicClient, { address: emptyAddress })
+      expect(utxos.length).toBe(0)
+    })
+
+    it('should handle pagination correcly', async () => {
+      const addressWithManyUTXOs = '1GrwDkr33gT6LuumniYjKEGjTLhsL5kmqC'
+      const minValue = 5_610_592_350
+      vi.spyOn(global, 'fetch').mockResolvedValue(
+        createMockResponse(getUTXOsPaginatedReponse as BlockcypherUTXOsResponse)
+      )
+
+      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/blockcypher/blockcypher.ts

@@ -0,0 +1,13 @@
+import type { HttpTransportConfig } from '../http.js'
+import { utxo } from '../utxo.js'
+
+type BlockcypherConfig = {
+  baseUrl?: string
+  apiKey?: string
+} & HttpTransportConfig
+
+export const blockcypher = (config?: BlockcypherConfig) =>
+  utxo(config?.baseUrl || 'https://api.blockcypher.com/v1/btc/main', {
+    key: 'blockcypher',
+    ...config,
+  })

package/src/transports/blockcypher/blockcypher.types.ts

@@ -0,0 +1,35 @@
+export type BlockcypherErrorResponse = {
+  error: string
+}
+
+export type BlockcypherBalanceResponse = {
+  address: string
+  total_received: number
+  total_sent: number
+  balance: number
+  unconfirmed_balance: number
+  final_balance: number
+  n_tx: number
+  unconfirmed_n_tx: number
+  final_n_tx: number
+  error?: string
+  hasMore?: boolean
+}
+
+export type BlockcypherUTXO = {
+  tx_hash: string
+  block_height: number
+  tx_input_n: number
+  tx_output_n: number
+  value: number
+  ref_balance: number
+  spent: boolean
+  confirmations: number
+  confirmed: string
+  double_spend: boolean
+  script: string
+}
+
+export type BlockcypherUTXOsResponse = BlockcypherBalanceResponse & {
+  txrefs: BlockcypherUTXO[]
+}

package/src/transports/blockcypher/getBalance.ts

@@ -0,0 +1,25 @@
+import { urlWithParams } from '../../utils/url.js'
+import type { RpcMethodHandler } from '../types.js'
+import type { BlockcypherBalanceResponse } from './blockcypher.types.js'
+
+export const getBalance: RpcMethodHandler<'getBalance'> = async (
+  client,
+  { baseUrl, apiKey },
+  { address }
+) => {
+  const apiUrl = urlWithParams(`${baseUrl}/addrs/${address}`, {
+    token: apiKey,
+  })
+  const response = (await client.request({
+    url: apiUrl,
+    fetchOptions: { method: 'GET' },
+  })) as unknown as BlockcypherBalanceResponse
+  if (response.error) {
+    return {
+      error: { code: -1, message: response.error },
+    }
+  }
+  return {
+    result: BigInt(response.balance),
+  }
+}

package/src/transports/blockcypher/getUTXOs.ts

@@ -0,0 +1,100 @@
+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 {
+  BlockcypherUTXO,
+  BlockcypherUTXOsResponse,
+} from './blockcypher.types.js'
+
+const blockchairUTXOTransformer = (utxo: BlockcypherUTXO): UTXO => ({
+  blockHeight: utxo.block_height,
+  isConfirmed: Boolean(utxo.confirmations),
+  confirmations: utxo.confirmations,
+  value: utxo.value,
+  vout: utxo.tx_output_n,
+  txId: utxo.tx_hash,
+  scriptHex: utxo.script,
+})
+
+const MAX_API_LIMIT = 2000
+
+export const getUTXOs: RpcMethodHandler<'getUTXOs'> = async (
+  client,
+  { baseUrl, apiKey },
+  { address, minValue }
+) => {
+  async function* fetchUTXOs() {
+    let hasMore = true
+    let beforeBlock = undefined
+
+    while (hasMore) {
+      const apiUrl = urlWithParams(`${baseUrl}/addrs/${address}`, {
+        token: apiKey,
+        unspentOnly: 'true',
+        includeScript: 'true',
+        before: beforeBlock,
+        limit: MAX_API_LIMIT,
+      })
+      const response = (await client.request({
+        url: apiUrl,
+        fetchOptions: { method: 'GET' },
+      })) as unknown as BlockcypherUTXOsResponse
+
+      if (response.error) {
+        throw new RpcRequestError({
+          url: apiUrl,
+          body: {
+            method: 'fetchUTXOs',
+            params: {
+              address,
+              minValue,
+            },
+          },
+          error: {
+            code: -1,
+            message: response.error,
+          },
+        })
+      }
+
+      if (minValue && minValue > response.final_balance) {
+        throw new InsufficientUTXOBalanceError({
+          minValue,
+          address,
+          balance: response.final_balance,
+        })
+      }
+
+      if (!response.txrefs || response.txrefs.length === 0) {
+        hasMore = false
+        continue
+      }
+
+      const { hasMore: apiHasMore } = response
+
+      hasMore = Boolean(apiHasMore)
+      beforeBlock = response.txrefs[response.txrefs.length - 1].block_height
+
+      yield response.txrefs
+    }
+  }
+
+  const utxos: UTXO[] = []
+  let valueCount = 0
+
+  for await (const batch of fetchUTXOs()) {
+    const utxoBatch = batch.map(blockchairUTXOTransformer)
+    utxos.push(...utxoBatch)
+
+    if (minValue) {
+      valueCount += utxoBatch.reduce((sum, utxo) => sum + utxo.value, 0)
+      if (valueCount >= minValue) {
+        break
+      }
+    }
+  }
+
+  return { result: utxos }
+}

package/src/transports/blockcypher/methods.ts

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

package/src/transports/fallback.ts

@@ -1,4 +1,5 @@
 import { RpcErrorCode } from '../errors/rpc.js'
+import { TransportMethodNotSupportedError } from '../errors/transport.js'
 import type { ErrorType } from '../errors/utils.js'
 import { createTransport } from '../factories/createTransport.js'
 import type { Chain } from '../types/chain.js'
@@ -121,10 +122,25 @@ export function fallback<const transports extends readonly Transport[]>(
         key,
         name,
         async request({ method, params }) {
-          let includes: boolean | undefined
+          // Filter transports to only those that support the requested method
+          const supportedTransports = transports.filter((transport) => {
+            const { include, exclude } =
+              transport({ chain }).config.methods || {}
+            if (include) {
+              return include.includes(method)
+            }
+            if (exclude) {
+              return !exclude.includes(method)
+            }
+            return true
+          })
+
+          if (!supportedTransports.length) {
+            throw new TransportMethodNotSupportedError({ method })
+          }
 
           const fetch = async (i = 0): Promise<any> => {
-            const transport = transports[i]({
+            const transport = supportedTransports[i]({
               ...rest,
               chain,
               retryCount: 0,
@@ -163,22 +179,6 @@ export function fallback<const transports extends readonly Transport[]>(
                 throw err
               }
 
-              // Check if at least one other transport includes the method
-              includes ??= transports.slice(i + 1).some((transport) => {
-                const { include, exclude } =
-                  transport({ chain }).config.methods || {}
-                if (include) {
-                  return include.includes(method)
-                }
-                if (exclude) {
-                  return !exclude.includes(method)
-                }
-                return true
-              })
-              if (!includes) {
-                throw err
-              }
-
               // Otherwise, try the next fallback.
               return fetch(i + 1)
             }

package/src/transports/getRpcProviderMethods.ts

@@ -1,12 +1,12 @@
-import { ankrMethods } from './ankr.js'
-import { blockchairMethods } from './blockchair.js'
-import { blockcypherMethods } from './blockcypher.js'
-import { mempoolMethods } from './mempool.js'
+import { ankrMethods } from './ankr/methods.js'
+import { blockchairMethods } from './blockchair/methods.js'
+import { blockcypherMethods } from './blockcypher/methods.js'
+import { mempoolMethods } from './mempool/methods.js'
 import type { RpcMethods } from './types.js'
 
-export function getRpcProviderMethods(
-  key: 'blockchair' | 'ankr' | 'blockcypher' | 'mempool' | string
-): RpcMethods | null {
+type providers = 'blockchair' | 'ankr' | 'blockcypher' | 'mempool' | string
+
+export function getRpcProviderMethods(key: providers): RpcMethods | null {
   switch (key) {
     case 'blockchair':
       return blockchairMethods

package/src/transports/http.ts

@@ -17,6 +17,7 @@ import {
   type RpcRequest,
   getHttpRpcClient,
 } from './getHttpRpcClient.js'
+import { UTXOAPISchemaMethods } from './types.js'
 
 export type HttpTransportConfig<
   rpcSchema extends RpcSchema | undefined = undefined,
@@ -94,7 +95,7 @@ export function http<
     batch,
     fetchOptions,
     key = 'http',
-    methods,
+    methods = { exclude: UTXOAPISchemaMethods },
     name = 'HTTP JSON-RPC',
     onFetchRequest,
     onFetchResponse,

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

@@ -0,0 +1 @@
+"Invalid Bitcoin address"

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

@@ -0,0 +1,17 @@
+{
+  "address": "bc1qpvk0kjdg0kantu9z78qz7gqk53q643auz33yaw",
+  "chain_stats": {
+    "funded_txo_count": 18,
+    "funded_txo_sum": 424052,
+    "spent_txo_count": 17,
+    "spent_txo_sum": 390846,
+    "tx_count": 19
+  },
+  "mempool_stats": {
+    "funded_txo_count": 0,
+    "funded_txo_sum": 0,
+    "spent_txo_count": 0,
+    "spent_txo_sum": 0,
+    "tx_count": 0
+  }
+}