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’



88
89
90
91
92
93
94
95
96
97
98
 
# File 'lib/bsv/wallet_interface/broadcast_queue.rb', line 88

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

#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



76
77
78
 
# File 'lib/bsv/wallet_interface/broadcast_queue.rb', line 76

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