Module: BSV::Wallet::Interface::BroadcastQueue

Defined in:
lib/bsv/wallet/interface/broadcast_queue.rb

Overview

Transaction broadcast lifecycle management.

The wallet owns broadcast — the SDK provides the protocol (ARC message formatting/parsing), but the wallet decides when and how to broadcast.

Backed by the broadcasts table. Each action has at most one broadcast record. The broadcast lifecycle follows ARC’s status progression:

UNKNOWN → RECEIVED → SENT_TO_NETWORK → ACCEPTED_BY_NETWORK
  → SEEN_ON_NETWORK → MINED → IMMUTABLE

The wallet engine handles promotion (Phase 4) based on broadcast results — the queue handles network I/O only.

Instance Method Summary collapse

Instance Method Details

#handle_event(event) ⇒ Hash?

Process an incoming ARC status update.

Called by the callback endpoint (Rack app) or SSE listener when ARC delivers a TransactionStatus event. Updates the broadcast record and returns the result so the engine can decide whether to promote.

Parameters:

  • event (Hash) —

    parsed TransactionStatus: :wtxid (binary, wire byte order), :tx_status, :status, :block_hash (binary), :block_height, :merkle_path (binary), :extra_info, :competing_txs

Returns:

  • (Hash, nil) —

    :action_id, :tx_status, and proof data, or nil if the event doesn’t match a known broadcast

Raises:

  • (NotImplementedError) 


61
62
63
 
# File 'lib/bsv/wallet/interface/broadcast_queue.rb', line 61

def handle_event(event)
  raise NotImplementedError
end

#process_pending(limit: 100) ⇒ Array<Hash>

Post pending broadcasts to the network.

Finds broadcast records without a response and posts them. Returns results so the wallet engine can promote accepted actions.

Parameters:

  • limit (Integer) (defaults to: 100) —

    maximum number to process

Returns:

  • (Array<Hash>) —

    per-broadcast results: :action_id, :tx_status, :block_hash, :block_height, :merkle_path

Raises:

  • (NotImplementedError) 


44
45
46
 
# File 'lib/bsv/wallet/interface/broadcast_queue.rb', line 44

def process_pending(limit: 100)
  raise NotImplementedError
end

#status(action_id:) ⇒ Hash?

Query broadcast status for an action.

Parameters:

  • action_id (Integer)

Returns:

  • (Hash, nil) —

    :tx_status, :arc_status, :broadcast_at, or nil if no broadcast

Raises:

  • (NotImplementedError) 


69
70
71
 
# File 'lib/bsv/wallet/interface/broadcast_queue.rb', line 69

def status(action_id:)
  raise NotImplementedError
end

#submit(action_id:, raw_tx:, immediate: false) ⇒ Hash

Submit a transaction for broadcast.

Creates a broadcast record. If immediate, posts to the network and returns the result. Otherwise, queues for background processing.

Parameters:

  • action_id (Integer)
  • raw_tx (String) —

    binary-encoded signed transaction

  • immediate (Boolean) (defaults to: false) —

    broadcast synchronously if true

Returns:

  • (Hash) —

    :tx_status, :arc_status, and any proof data returned by the network

Raises:

  • (NotImplementedError) 


32
33
34
 
# File 'lib/bsv/wallet/interface/broadcast_queue.rb', line 32

def submit(action_id:, raw_tx:, immediate: false)
  raise NotImplementedError
end