Skip to content

Class BSV::Network::WhatsOnChain

Inherits: Object

WhatsOnChain chain data provider for reading transactions and UTXOs from the BSV network.

Any object responding to #fetch_utxos(address), #fetch_transaction(txid),

current_height, #get_block_header(height), and optionally

valid_root_for_height?(root_hex, height) can serve as a chain data source;

this class implements that contract by delegating to Protocols::WoCREST.

The HTTP client is injectable for testability. It must respond to

request(uri, request) and return an object with #code and #body.

Public Class Methods

default(testnet: = false, **opts)

Returns a WhatsOnChain instance using the provider default. - @param testnet [Boolean] when true, uses the testnet endpoint - @param opts [Hash] forwarded to the underlying protocol (e.g. +api_key:+, +http_client:+) - @return [WhatsOnChain]

Public Instance Methods

current_height()

Return the current blockchain height. - @raise [BSV::Network::ChainProviderError] on network or API error - @return [Integer]

fetch_transaction(txid)

Fetch a raw transaction by its txid and parse it. - @param txid [String] transaction ID (hex) - @return [BSV::Transaction::Transaction]

fetch_utxos(address)

Fetch unspent transaction outputs for an address. - @param address [String] BSV address - @return [Array]

get_block_header(height)

Fetch the block header for a given height. - @param height [Integer] block height - @raise [BSV::Network::ChainProviderError] on network or API error - @return [Hash] parsed block header JSON

initialize(network: = :mainnet, http_client: = nil, protocol: = nil)

  • @param network [Symbol] :main, :mainnet, :test, :testnet, :stn (legacy compat)
  • @param http_client [#request, nil] injectable HTTP client
  • @param protocol [BSV::Network::Protocols::WoCREST, nil] pre-configured protocol
  • @return [WhatsOnChain] a new instance of WhatsOnChain

valid_root_for_height?(root, height)

Verify that a merkle root is valid for the given block height. Returns false when the block is not found (404); raises on other errors. - @param root [String] expected merkle root as hex - @param height [Integer] block height - @raise [BSV::Network::ChainProviderError] on network or non-404 API error - @return [Boolean]