@bigmi/core 0.3.1 → 0.4.0-beta.1

package/src/transports/ankr/getTransactions.ts

@@ -1,36 +1,7 @@
 import { urlWithParams } from '../../utils/url.js'
 import type { RpcMethodHandler } from '../types.js'
 import type { AnkrAddressWithTxnsResponse } from './ankr.types.js'
-
-import type { UTXOTransaction } from '../../types/transaction.js'
-import type { AnkrTransaction } from './ankr.types.js'
-
-export const ankrTransactionTransformer = (
-  txn: AnkrTransaction
-): Partial<UTXOTransaction> => ({
-  blockhash: txn?.blockHash,
-  blocktime: txn.blockTime,
-  confirmations: txn.confirmations,
-  hex: txn.hex,
-  locktime: txn?.coinSpecificData?.locktime,
-  hash: txn.coinSpecificData?.hash,
-  size: txn.size,
-  txid: txn.txid,
-  version: txn.version,
-  vin: txn.vin.map((vin) => ({
-    scriptSig: vin.scriptSig,
-    sequence: vin.sequence,
-    txid: vin.txid,
-    vout: vin.vout,
-    txinwitness: vin.addresses,
-  })),
-  vsize: txn.vsize,
-  vout: txn.vout.map((vout) => ({
-    n: vout.n,
-    scriptPubKey: vout.scriptPubKey,
-    value: vout.value,
-  })),
-})
+import { ankrTransactionTransformer } from './utils.js'
 
 export const getTransactions: RpcMethodHandler<'getTransactions'> = async (
   client,

package/src/transports/ankr/methods.ts

@@ -1,8 +1,10 @@
 import type { RpcMethods } from '../types.js'
 import { getBalance } from './getBalance.js'
+import { getTransactionFee } from './getTransactionFee.js'
 import { getTransactions } from './getTransactions.js'
 
 export const ankrMethods: RpcMethods = {
   getBalance,
   getTransactions,
+  getTransactionFee,
 }

package/src/transports/ankr/utils.ts

@@ -0,0 +1,29 @@
+import type { UTXOTransaction } from '../../types/transaction.js'
+import type { AnkrTransaction } from './ankr.types.js'
+
+export const ankrTransactionTransformer = (
+  txn: AnkrTransaction
+): Partial<UTXOTransaction> => ({
+  blockhash: txn?.blockHash,
+  blocktime: txn.blockTime,
+  confirmations: txn.confirmations,
+  hex: txn.hex,
+  locktime: txn?.coinSpecificData?.locktime,
+  hash: txn.coinSpecificData?.hash,
+  size: txn.size,
+  txid: txn.txid,
+  version: txn.version,
+  vin: txn.vin.map((vin) => ({
+    scriptSig: vin.scriptSig,
+    sequence: vin.sequence,
+    txid: vin.txid,
+    vout: vin.vout,
+    txinwitness: vin.addresses,
+  })),
+  vsize: txn.vsize,
+  vout: txn.vout.map((vout) => ({
+    n: vout.n,
+    scriptPubKey: vout.scriptPubKey,
+    value: vout.value,
+  })),
+})

package/src/transports/blockchair/__mocks__/getTransactionFee/invalid.json

@@ -0,0 +1,7 @@
+{
+  "data": {},
+  "context": {
+    "code": 404,
+    "error": "Transaction not found"
+  }
+}

package/src/transports/blockchair/__mocks__/getTransactionFee/valid.json

@@ -0,0 +1,37 @@
+{
+  "data": {
+    "8f210660cd99c5e6dc77b6cb09d4d522d3fbc5fd97ad3e65403d49aa7aa5dc23": {
+      "transaction": {
+        "block_id": 896390,
+        "id": 123456,
+        "hash": "8f210660cd99c5e6dc77b6cb09d4d522d3fbc5fd97ad3e65403d49aa7aa5dc23",
+        "date": "2024-03-15",
+        "time": "12:00:00",
+        "size": 450,
+        "weight": 1149,
+        "version": 1,
+        "lock_time": 0,
+        "is_coinbase": false,
+        "has_witness": true,
+        "input_count": 2,
+        "output_count": 3,
+        "input_total": 10269002928,
+        "input_total_usd": 102690.02928,
+        "output_total": 10269001908,
+        "output_total_usd": 102690.01908,
+        "fee": 1020,
+        "fee_usd": 1.02,
+        "fee_per_kb": 2266,
+        "fee_per_kb_usd": 2.266,
+        "fee_per_kwu": 887,
+        "fee_per_kwu_usd": 0.887,
+        "cdd_total": 0,
+        "is_rbf": false
+      }
+    }
+  },
+  "context": {
+    "code": 200,
+    "error": null
+  }
+}

package/src/transports/blockchair/__mocks__/getUTXOs/rateLimited.json

@@ -0,0 +1,28 @@
+{
+  "data": null,
+  "context": {
+    "code": 429,
+    "optimized": false,
+    "error": "Rate limit exceeded",
+    "market_price_usd": 102926,
+    "cache": {
+      "live": true,
+      "duration": 120,
+      "since": "2025-05-19 12:22:44",
+      "until": "2025-05-19 12:24:44",
+      "time": null
+    },
+    "api": {
+      "version": "2.0.95-ie",
+      "last_major_update": "2022-11-07 02:00:00",
+      "next_major_update": "2023-11-12 02:00:00",
+      "documentation": "https://blockchair.com/api/docs",
+      "notice": "Try out our new API v.3: https://3xpl.com/data"
+    },
+    "servers": "API4,BTC5",
+    "time": 1.0055019855499268,
+    "render_time": 0.01248788833618164,
+    "full_time": 1.0179898738861084,
+    "request_cost": 0
+  }
+}

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

@@ -1,14 +1,22 @@
 import { beforeEach, describe, expect, it, vi } from 'vitest'
 import { getBalance } from '../../actions/getBalance'
+import { getTransactionFee } from '../../actions/getTransactionFee'
 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 {
+  INVALID_TX_ID,
+  TX_FEE,
+  VALID_TX_ID,
+} from '../__mocks__/getTransactionFee'
 import type { UTXOSchema } from '../types'
 import getInvalidBalanceReponse from './__mocks__/getBalance/invalidAddress.json'
 import getBalanceReponse from './__mocks__/getBalance/valid.json'
+import getTransactionFeeInvalidResponse from './__mocks__/getTransactionFee/invalid.json'
+import getTransactionFeeValidResponse from './__mocks__/getTransactionFee/valid.json'
 import getUTXOsInvalidResponse from './__mocks__/getUTXOs/invalidAddress.json'
 import getUTXOsResponse from './__mocks__/getUTXOs/valid.json'
 import getUTXOsPaginatedResponse from './__mocks__/getUTXOs/validPaginated.json'
@@ -22,6 +30,8 @@ import type {
 const address = import.meta.env.VITE_TEST_ADDRESS
 const apiKey = import.meta.env.VITE_TEST_BLOCKCHAIR_KEY
 
+const USE_MOCK = true
+
 const publicClient = createClient({
   chain: bitcoin,
   rpcSchema: rpcSchema<UTXOSchema>(),
@@ -191,4 +201,43 @@ describe('Blockchair Transport', () => {
       })
     })
   })
+
+  describe('getTransactionFee', () => {
+    it('should fetch correct transaction fee for valid transaction', async () => {
+      if (USE_MOCK) {
+        const mockData = {
+          data: {
+            [VALID_TX_ID]:
+              getTransactionFeeValidResponse.data[
+                '8f210660cd99c5e6dc77b6cb09d4d522d3fbc5fd97ad3e65403d49aa7aa5dc23'
+              ],
+          },
+          context: getTransactionFeeValidResponse.context,
+        }
+
+        mockData.data[VALID_TX_ID].transaction.fee = TX_FEE
+        vi.spyOn(global, 'fetch').mockResolvedValue(
+          createMockResponse(mockData)
+        )
+      }
+
+      const result = await getTransactionFee(publicClient, {
+        txId: VALID_TX_ID,
+      })
+      expect(result).toBeDefined()
+      expect(result).toBe(BigInt(TX_FEE))
+    })
+
+    it('should throw error for non-existent transaction', async () => {
+      if (USE_MOCK) {
+        vi.spyOn(global, 'fetch').mockResolvedValue(
+          createMockResponse(getTransactionFeeInvalidResponse)
+        )
+      }
+
+      await expect(
+        getTransactionFee(publicClient, { txId: INVALID_TX_ID })
+      ).rejects.toThrow()
+    })
+  })
 })

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

@@ -57,3 +57,70 @@ export type BlockchairResponse<T = any> = {
     total_rows?: number
   }
 }
+
+export type BlockchairTransactionResponse = BlockchairResponse<
+  Record<string, BlockchairTransaction>
+>
+
+export type BlockchairTransaction = {
+  transaction: {
+    block_id: number
+    id: number
+    hash: string
+    date: string
+    time: string
+    size: number
+    weight: number
+    version: number
+    lock_time: number
+    is_coinbase: boolean
+    has_witness: boolean
+    input_count: number
+    output_count: number
+    input_total: number
+    input_total_usd: number
+    output_total: number
+    output_total_usd: number
+    fee: number
+    fee_usd: number
+    fee_per_kb: number
+    fee_per_kb_usd: number
+    fee_per_kwu: number
+    fee_per_kwu_usd: number
+    cdd_total: number
+    is_rbf: boolean
+  }
+  inputs: Array<BlockchairVin>
+  outputs: Array<BlockchairVout>
+}
+
+export type BlockchairVin = {
+  block_id: number
+  transaction_id: number
+  index: number
+  transaction_hash: string
+  date: string
+  time: string
+  value: number
+  value_usd: number
+  recipient: string
+  type: string
+  script_hex: string
+  is_from_coinbase: boolean
+  is_spendable: boolean | null
+  is_spent: boolean
+  spending_block_id: number | null
+  spending_transaction_id: number | null
+  spending_index: number | null
+  spending_transaction_hash: string | null
+  spending_date: string | null
+  spending_time: string | null
+  spending_value_usd: number | null
+  spending_sequence: number | null
+  spending_signature_hex: string | null
+  spending_witness: string | null
+  lifespan: number | null
+  cdd: number | null
+}
+
+export type BlockchairVout = BlockchairVin

package/src/transports/blockchair/getTransactionFee.ts

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

package/src/transports/blockchair/methods.ts

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

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

@@ -0,0 +1,3 @@
+{
+  "error": "Transaction not found"
+}

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

@@ -0,0 +1,22 @@
+{
+  "block_height": 896390,
+  "hash": "8f210660cd99c5e6dc77b6cb09d4d522d3fbc5fd97ad3e65403d49aa7aa5dc23",
+  "addresses": [
+    "bc1qpvk0kjdg0kantu9z78qz7gqk53q643auz33yaw",
+    "bc1qjmggdm4r9rqkfq335w72duu47386jhdw6wye0m"
+  ],
+  "total": 10269001908,
+  "fees": 1036,
+  "size": 450,
+  "vsize": 288,
+  "preference": "medium",
+  "relayed_by": "127.0.0.1",
+  "received": "2024-03-15T12:00:00Z",
+  "ver": 1,
+  "double_spend": false,
+  "vin_sz": 2,
+  "vout_sz": 3,
+  "confirmations": 1040,
+  "inputs": [],
+  "outputs": []
+}

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

@@ -0,0 +1,3 @@
+{
+  "error": "Rate limit exceeded"
+}

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

@@ -1,14 +1,21 @@
-import { beforeEach } from 'node:test'
-import { describe, expect, it, vi } from 'vitest'
+import { beforeEach, describe, expect, it, vi } from 'vitest'
 import { getBalance } from '../../actions/getBalance.js'
+import { getTransactionFee } from '../../actions/getTransactionFee.js'
 import { getUTXOs } from '../../actions/getUTXOs.js'
 import { bitcoin } from '../../chains/bitcoin.js'
-import { NotEnoughUTXOError } from '../../errors/address.js'
+import { InsufficientUTXOBalanceError } from '../../errors/utxo.js'
 import { createClient, rpcSchema } from '../../factories/createClient.js'
 import { createMockResponse } from '../../test/utils.js'
+import {
+  INVALID_TX_ID,
+  TX_FEE,
+  VALID_TX_ID,
+} from '../__mocks__/getTransactionFee'
 import type { UTXOSchema } from '../types.js'
 import getBalanceInValidResponse from './__mocks__/getBalance/invalid.json'
 import getBalanceValidResponse from './__mocks__/getBalance/valid.json'
+import getTransactionFeeInvalidResponse from './__mocks__/getTransactionFee/invalid.json'
+import getTransactionFeeValidResponse from './__mocks__/getTransactionFee/valid.json'
 import getUTXOsEmptyReponse from './__mocks__/getUTXOs/empty.json'
 import getUTXOsPaginatedReponse from './__mocks__/getUTXOs/paginated.json'
 import getUTXOsValidReponse from './__mocks__/getUTXOs/valid.json'
@@ -21,6 +28,8 @@ import type {
 
 const apiKey = import.meta.env.VITE_TEST_BLOCKCYPHER_API_KEY
 
+const USE_MOCK = true
+
 const publicClient = createClient({
   chain: bitcoin,
   rpcSchema: rpcSchema<UTXOSchema>(),
@@ -88,7 +97,7 @@ describe('Blockcypher Transport', () => {
           address,
           minValue: Number(hugeValue),
         })
-      ).rejects.toThrow(NotEnoughUTXOError)
+      ).rejects.toThrow(InsufficientUTXOBalanceError)
     })
 
     it('should handle empty UTXO', async () => {
@@ -119,4 +128,34 @@ describe('Blockcypher Transport', () => {
       expect(totalValue).toBeGreaterThanOrEqual(minValue)
     })
   })
+
+  describe('getTransactionFee', () => {
+    it('should fetch correct transaction fee for valid transaction', async () => {
+      if (USE_MOCK) {
+        getTransactionFeeValidResponse.hash = VALID_TX_ID
+        getTransactionFeeValidResponse.fees = TX_FEE
+        vi.spyOn(global, 'fetch').mockResolvedValue(
+          createMockResponse(getTransactionFeeValidResponse)
+        )
+      }
+
+      const result = await getTransactionFee(publicClient, {
+        txId: VALID_TX_ID,
+      })
+      expect(result).toBeDefined()
+      expect(result).toBe(BigInt(TX_FEE))
+    })
+
+    it('should throw error for non-existent transaction', async () => {
+      if (USE_MOCK) {
+        vi.spyOn(global, 'fetch').mockResolvedValue(
+          createMockResponse(getTransactionFeeInvalidResponse)
+        )
+      }
+
+      await expect(
+        getTransactionFee(publicClient, { txId: INVALID_TX_ID })
+      ).rejects.toThrow()
+    })
+  })
 })

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

@@ -33,3 +33,48 @@ export type BlockcypherUTXO = {
 export type BlockcypherUTXOsResponse = BlockcypherBalanceResponse & {
   txrefs: BlockcypherUTXO[]
 }
+
+export type BlockcypherTransactionInput = {
+  prev_hash: string
+  output_index: number
+  script: string
+  output_value: number
+  sequence: number
+  addresses: string[]
+  script_type: string
+}
+
+export type BlockcypherTransactionOutput = {
+  value: number
+  script: string
+  spent_by: string
+  addresses: string[]
+  script_type: string
+}
+
+export type BlockcypherTransaction = {
+  block_hash: string
+  block_height: number
+  hash: string
+  addresses: string[]
+  total: number
+  fees: number
+  size: number
+  vsize: number
+  preference: string
+  relayed_by: string
+  confirmed: string
+  received: string
+  ver: number
+  lock_time: number
+  double_spend: boolean
+  vin_sz: number
+  vout_sz: number
+  confirmations: number
+  inputs: BlockcypherTransactionInput[]
+  outputs: BlockcypherTransactionOutput[]
+}
+
+export type BlockcypherTransactionReponse = BlockcypherTransaction & {
+  error?: string
+}

package/src/transports/blockcypher/getTransactionFee.ts

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

package/src/transports/blockcypher/methods.ts

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

package/src/transports/fallback.spec.ts

@@ -0,0 +1,103 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import { getUTXOs } from '../actions/getUTXOs'
+import { bitcoin } from '../chains/bitcoin'
+import { AllTransportsFailedError } from '../errors/transport'
+import { InsufficientUTXOBalanceError } from '../errors/utxo'
+import { createClient, rpcSchema } from '../factories/createClient'
+import { createMockResponse } from '../test/utils'
+import blockchairLimitedResponse from './blockchair/__mocks__/getUTXOs/rateLimited.json'
+import blockchairValidResponse from './blockchair/__mocks__/getUTXOs/valid.json'
+import { blockchair } from './blockchair/blockchair'
+import blockcypherLimitedResponse from './blockcypher/__mocks__/getUTXOs/rateLimited.json'
+import blockcypherValidResponse from './blockcypher/__mocks__/getUTXOs/valid.json'
+import { blockcypher } from './blockcypher/blockcypher'
+import { fallback } from './fallback'
+import type { UTXOSchema } from './types'
+
+const address = import.meta.env.VITE_TEST_ADDRESS
+const apiKey = import.meta.env.VITE_TEST_BLOCKCHAIR_KEY
+const blockCypherKey = import.meta.env.VITE_TEST_BLOCKCYPHER_API_KEY
+
+const publicClient = createClient({
+  chain: bitcoin,
+  rpcSchema: rpcSchema<UTXOSchema>(),
+  transport: fallback([
+    blockcypher({ apiKey: blockCypherKey }),
+    blockchair({ apiKey }),
+  ]),
+})
+
+describe('Fallback Transport', () => {
+  beforeEach(() => {
+    vi.restoreAllMocks()
+  })
+
+  describe('getUTXOs', () => {
+    it('should use blockcypher when it succeeds', async () => {
+      vi.spyOn(global, 'fetch').mockResolvedValue(
+        createMockResponse(blockcypherValidResponse)
+      )
+
+      const utxos = await getUTXOs(publicClient, { address })
+      expect(utxos.length).toBeGreaterThan(0)
+    })
+
+    it('should fallback to blockchair when blockcypher fails', async () => {
+      vi.spyOn(global, 'fetch').mockImplementation((request) => {
+        const url = new URL(request.toString())
+        if (url.hostname.includes('blockcypher')) {
+          return Promise.resolve(
+            createMockResponse(blockcypherLimitedResponse, { status: 429 })
+          )
+        }
+
+        return Promise.resolve(createMockResponse(blockchairValidResponse))
+      })
+
+      const utxos = await getUTXOs(publicClient, { address })
+      expect(utxos.length).toBeGreaterThan(0)
+    })
+
+    it('should throw error when both transports fail', async () => {
+      vi.spyOn(global, 'fetch').mockImplementation((request) => {
+        const url = new URL(request.toString())
+        if (url.hostname.includes('blockcypher')) {
+          return Promise.resolve(
+            createMockResponse(blockcypherLimitedResponse, { status: 429 })
+          )
+        }
+        return Promise.resolve(
+          createMockResponse(blockchairLimitedResponse, { status: 429 })
+        )
+      })
+
+      await expect(getUTXOs(publicClient, { address })).rejects.toThrow(
+        AllTransportsFailedError
+      )
+    })
+
+    it('should not call blockchair if user has insufficientUTXOs', async () => {
+      const blockchairSpy = vi
+        .spyOn(global, 'fetch')
+        .mockImplementation((request) => {
+          const url = new URL(request.toString())
+          if (url.hostname.includes('blockcypher')) {
+            return Promise.resolve(createMockResponse(blockcypherValidResponse))
+          }
+
+          return Promise.resolve(createMockResponse(blockchairValidResponse))
+        })
+
+      await expect(
+        getUTXOs(publicClient, {
+          address,
+          minValue: 1000000,
+        })
+      ).rejects.toThrow(InsufficientUTXOBalanceError)
+
+      expect(blockchairSpy).not.toHaveBeenCalledWith(
+        expect.stringContaining('blockchair')
+      )
+    })
+  })
+})