Module: BSV::Wallet::BroadcastQueue

Included in:
InlineQueue
Defined in:
lib/bsv/wallet_interface/broadcast_queue.rb

Overview

Duck-typed broadcast queue interface for wallet transaction dispatch.

Include this module in broadcast queue adapters and override all instance methods that raise NotImplementedError. The async? method may be overridden to return true for adapters that defer execution to a background worker.

Payload contract

The enqueue method receives a Hash with the following keys:

{
  tx:                       BSV::Transaction,  # signed transaction object
  txid:                     String,            # hex txid
  beef_binary:              String,            # raw BEEF bytes
  input_outpoints:          Array<String>,     # locked input outpoints (nil on finalize path)
  change_outpoints:         Array<String>,     # change outpoints (nil on finalize path)
  fund_ref:                 String,            # fund reference for rollback (nil on finalize path)
  accept_delayed_broadcast: Boolean            # from caller options
}

When input_outpoints is nil, the caller is on the finalize path and the adapter must skip UTXO state transitions.

Example

class MyQueue
  include BSV::Wallet::BroadcastQueue

  def async?
    true
  end

  def enqueue(payload)
    MyWorker.perform_later(payload[:txid])
    { txid: payload[:txid] }
  end

  def status(txid)
    MyWorker.status_for(txid)
  end
end

Class Method Summary collapse

Instance Method Summary collapse

Class Method Details

.status_for_error(error) ⇒ String

Maps a broadcast exception to a ReviewActionResultStatus string.

This shared helper is extracted from WalletClient#broadcast_status_for so all queue adapters can produce consistent status strings without duplicating the mapping logic.

Parameters:

  • error (StandardError) —

    the exception raised during broadcast

Returns:

  • (String) —

    one of ‘doubleSpend’, ‘invalidTx’, ‘serviceError’



103
104
105
106
107
108
109
110
111
112
113
 
# File 'lib/bsv/wallet_interface/broadcast_queue.rb', line 103

def self.status_for_error(error)
  return 'serviceError' unless error.is_a?(BSV::Network::BroadcastError)

  arc_status = error.arc_status.to_s.upcase
  return 'doubleSpend' if arc_status == 'DOUBLE_SPEND_ATTEMPTED'

  invalid_statuses = %w[REJECTED INVALID MALFORMED MINED_IN_STALE_BLOCK]
  return 'invalidTx' if invalid_statuses.include?(arc_status) || arc_status.include?('ORPHAN')

  'serviceError'
end

Instance Method Details

#async? ⇒ Boolean

Returns false by default, indicating synchronous execution.

Override and return true in adapters that defer broadcast to a background worker (e.g. SolidQueue, Sidekiq).

Returns:

  • (Boolean) 


67
68
69
 
# File 'lib/bsv/wallet_interface/broadcast_queue.rb', line 67

def async?
  false
end

#broadcast_enabled? ⇒ Boolean

Returns false by default — adapters without a broadcaster cannot broadcast on-chain.

Override in adapters that hold a broadcaster reference so that WalletClient can determine broadcast availability from the queue alone. This is the correct delegation point because users may pass a broadcaster-equipped queue (e.g. SolidQueueAdapter.new(broadcaster: arc)) without also passing broadcaster: directly to WalletClient.

Returns:

  • (Boolean) 


82
83
84
 
# File 'lib/bsv/wallet_interface/broadcast_queue.rb', line 82

def broadcast_enabled?
  false
end

#enqueue(_payload) ⇒ Hash

Enqueues a transaction for broadcast and state promotion.

For synchronous adapters this executes immediately and returns the result. For asynchronous adapters this persists the job and returns a partial result; the caller should treat the action as pending.

Parameters:

  • _payload (Hash) —

    broadcast payload (see module-level doc for keys)

Returns:

  • (Hash) —

    result hash containing at minimum :txid

Raises:

  • (NotImplementedError) —

    unless overridden by the including class



57
58
59
 
# File 'lib/bsv/wallet_interface/broadcast_queue.rb', line 57

def enqueue(_payload)
  raise NotImplementedError, "#{self.class}#enqueue not implemented"
end

#status(_txid) ⇒ String?

Returns the broadcast status for a previously enqueued transaction.

Parameters:

  • _txid (String) —

    hex transaction identifier

Returns:

  • (String, nil) —

    the current status string, or nil if unknown

Raises:

  • (NotImplementedError) —

    unless overridden by the including class



91
92
93
 
# File 'lib/bsv/wallet_interface/broadcast_queue.rb', line 91

def status(_txid)
  raise NotImplementedError, "#{self.class}#status not implemented"
end