bsv-wallet 0.6.0 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 832766edaf4b3b59b4a5a2bdf47e997972b62336ddbf65614e5445f254615fa4
-  data.tar.gz: c2bb017e369d5b7497c134fde1d5fd729e8952cc8a11bb04c05eaa6ad7f6ebf2
+  metadata.gz: 233e4c969fea0e8bb52110ffffe9d034a953854ccb1098c0a3dd3eb76bb2c034
+  data.tar.gz: e11ab6c70e949cbe62593f620d0367225e80ac84a144f94b07418d02e9383466
 SHA512:
-  metadata.gz: b2861431435b2e6aa871cbb6dfdc020f8a1c010eef487606efa9f0d1de9f8bd5ef6c6f2384eea98c621d72bb9be0175e280de47ac927f3effb4b11e931528d0f
-  data.tar.gz: b08fc27ca7a74a3f98e9df12190d7198296d8e91527848edba41e288066fbc6e164d9b13e793666232489a8edae7dacc514340058542be7d99e060db4eb5e754
+  metadata.gz: 974ffa3042e2bb4fe3c9f7ec94d8503c55ed20e94d5a808a667700339fbb5151eec6b12c185238353ccfd40e62f197477081fdb7b6b9f9ce75da4598a4536b90
+  data.tar.gz: 0af0b5d238c57a1b640ea243b2bce0e5e33fd55932354689a62b1c05dfe3b41d776fdfcd5fe245fa3973de98632d6f0985bbfc4bed99b4d2527494dc16fc2f6f

data/CHANGELOG.md

@@ -5,6 +5,24 @@ All notable changes to the `bsv-wallet` gem are documented here.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/)
 and this gem adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## 0.7.0 — 2026-04-12
+
+### Added
+- Pluggable `BroadcastQueue` interface module — duck-typed, follows the `StorageAdapter` pattern
+- `InlineQueue` synchronous default adapter — consolidates broadcast and no-broadcaster paths
+- `WalletClient` accepts `broadcast_queue:` constructor parameter (auto-creates `InlineQueue` when not provided)
+- `BroadcastQueue.status_for_error` shared helper for consistent broadcast error mapping
+- Integration specs for broadcast/rollback flows (20 specs)
+- MemoryStore production warning — logs to stderr when `RACK_ENV`/`RAILS_ENV` is `production` or `staging`
+
+### Fixed
+- TOCTOU window on change outputs — stored as `:pending` directly, eliminating race with concurrent `auto_fund`
+- Broadcast promotion failure no longer deletes confirmed on-chain outputs — only broadcast failure triggers rollback
+
+### Changed
+- `accept_delayed_broadcast: true` no longer logs "not yet implemented" warning — handled by the queue adapter
+- MemoryStore demoted to test/development only (production use triggers a suppressible warning)
+
 ## 0.6.0 — 2026-04-12
 
 ### Added

data/lib/bsv/wallet_interface/broadcast_queue.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+module BSV
+  module Wallet
+    # 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
+    module BroadcastQueue
+      # 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.
+      #
+      # @param _payload [Hash] broadcast payload (see module-level doc for keys)
+      # @return [Hash] result hash containing at minimum +:txid+
+      # @raise [NotImplementedError] unless overridden by the including class
+      def enqueue(_payload)
+        raise NotImplementedError, "#{self.class}#enqueue not implemented"
+      end
+
+      # Returns +false+ by default, indicating synchronous execution.
+      #
+      # Override and return +true+ in adapters that defer broadcast to a
+      # background worker (e.g. SolidQueue, Sidekiq).
+      #
+      # @return [Boolean]
+      def async?
+        false
+      end
+
+      # Returns the broadcast status for a previously enqueued transaction.
+      #
+      # @param _txid [String] hex transaction identifier
+      # @return [String, nil] the current status string, or +nil+ if unknown
+      # @raise [NotImplementedError] unless overridden by the including class
+      def status(_txid)
+        raise NotImplementedError, "#{self.class}#status not implemented"
+      end
+
+      # 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.
+      #
+      # @param error [StandardError] the exception raised during broadcast
+      # @return [String] one of +'doubleSpend'+, +'invalidTx'+, +'serviceError'+
+      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
+    end
+  end
+end

data/lib/bsv/wallet_interface/inline_queue.rb

@@ -0,0 +1,171 @@
+# frozen_string_literal: true
+
+module BSV
+  module Wallet
+    # Synchronous broadcast queue adapter — the default for +WalletClient+.
+    #
+    # +InlineQueue+ replicates the current wallet broadcast behaviour exactly:
+    #
+    # * With a broadcaster: calls +broadcaster.broadcast+, promotes UTXO state on
+    #   success, rolls back on failure.
+    # * Without a broadcaster: promotes immediately and returns BEEF for the
+    #   caller to broadcast manually (backwards-compatible fallback).
+    #
+    # Because this adapter executes synchronously, +async?+ returns +false+ and
+    # the caller can rely on the returned hash containing the final result.
+    class InlineQueue
+      include BSV::Wallet::BroadcastQueue
+
+      # @param broadcaster [#broadcast, nil] broadcaster object; +nil+ disables broadcasting
+      # @param storage [StorageAdapter] wallet storage adapter
+      def initialize(storage:, broadcaster: nil)
+        @broadcaster = broadcaster
+        @storage = storage
+      end
+
+      # Returns +false+ — this adapter executes synchronously.
+      #
+      # @return [Boolean]
+      def async?
+        false
+      end
+
+      # Returns the broadcast status for a previously enqueued transaction.
+      #
+      # Delegates to storage and returns the action status field, or +nil+ if
+      # the action is not found.
+      #
+      # @param txid [String] hex transaction identifier
+      # @return [String, nil]
+      def status(txid)
+        actions = @storage.find_actions({ txid: txid, limit: 1, offset: 0 })
+        actions.first&.dig(:status)
+      end
+
+      # Broadcasts and promotes (or just promotes) a transaction synchronously.
+      #
+      # Dispatches to +broadcast_and_promote+ when a broadcaster is configured,
+      # or +promote_without_broadcast+ when none is present.
+      #
+      # @param payload [Hash] broadcast payload (see +BroadcastQueue+ module docs)
+      # @return [Hash] result hash containing at minimum +:txid+ and +:tx+
+      def enqueue(payload)
+        if @broadcaster
+          broadcast_and_promote(payload)
+        else
+          promote_without_broadcast(payload)
+        end
+      end
+
+      private
+
+      # Broadcasts the transaction and promotes storage state on success.
+      #
+      # On broadcast failure with outpoints present, rolls back all pending
+      # state (releases locked inputs, deletes change outputs, marks action
+      # failed). On failure without outpoints (finalize path), only updates
+      # the action status.
+      #
+      # INVARIANT: Only broadcast failure triggers rollback. If broadcast
+      # succeeds but promotion raises, the error propagates — confirmed
+      # on-chain outputs must never be deleted.
+      #
+      # @param payload [Hash] broadcast payload
+      # @return [Hash] result hash
+      def broadcast_and_promote(payload)
+        tx               = payload[:tx]
+        txid             = payload[:txid]
+        beef_binary      = payload[:beef_binary]
+        input_outpoints  = payload[:input_outpoints]
+        change_outpoints = payload[:change_outpoints]
+        fund_ref         = payload[:fund_ref]
+
+        begin
+          broadcast_result = @broadcaster.broadcast(tx)
+        rescue StandardError => e
+          if input_outpoints
+            rollback(input_outpoints, change_outpoints, txid, fund_ref)
+          elsif txid
+            @storage.update_action_status(txid, 'failed')
+          end
+          return {
+            txid: txid,
+            tx: beef_binary.unpack('C*'),
+            broadcast_error: e.message,
+            broadcast_status: BroadcastQueue.status_for_error(e)
+          }
+        end
+
+        # Broadcast succeeded — promote all pending state to final.
+        promote(input_outpoints, change_outpoints, txid)
+
+        result = {
+          txid: txid,
+          tx: beef_binary.unpack('C*'),
+          broadcast_result: broadcast_result,
+          broadcast_status: 'success'
+        }
+        result[:competing_txs] = broadcast_result.competing_txs if broadcast_result.respond_to?(:competing_txs) && broadcast_result.competing_txs
+        result
+      end
+
+      # Promotes UTXO state without broadcasting — backwards-compatible fallback
+      # used when no broadcaster is configured.
+      #
+      # If +accept_delayed_broadcast+ is set the action status is +unproven+;
+      # otherwise it is +completed+.
+      #
+      # @param payload [Hash] broadcast payload
+      # @return [Hash] result hash containing +:txid+ and +:tx+
+      def promote_without_broadcast(payload)
+        txid             = payload[:txid]
+        beef_binary      = payload[:beef_binary]
+        input_outpoints  = payload[:input_outpoints]
+        change_outpoints = payload[:change_outpoints]
+        delayed          = payload[:accept_delayed_broadcast]
+
+        final_status = delayed ? 'unproven' : 'completed'
+        promote(input_outpoints, change_outpoints, txid, status: final_status)
+
+        { txid: txid, tx: beef_binary.unpack('C*') }
+      end
+
+      # Promotes UTXO state: marks inputs as +:spent+, change as +:spendable+,
+      # and updates the action status.
+      #
+      # When +outpoints+ arguments are +nil+ (finalize path), UTXO transitions
+      # are skipped and only the action status is updated.
+      #
+      # @param input_outpoints [Array<String>, nil]
+      # @param change_outpoints [Array<String>, nil]
+      # @param txid [String, nil]
+      # @param status [String]
+      def promote(input_outpoints, change_outpoints, txid, status: 'completed')
+        Array(input_outpoints).each { |op| @storage.update_output_state(op, :spent) }
+        Array(change_outpoints).each { |op| @storage.update_output_state(op, :spendable) }
+        @storage.update_action_status(txid, status) if txid
+      end
+
+      # Rolls back a pending auto-funded action.
+      #
+      # Releases locked inputs (only those matching +fund_ref+), deletes phantom
+      # change outputs, and marks the action as +failed+.
+      #
+      # @param input_outpoints [Array<String>] outpoints locked as inputs
+      # @param change_outpoints [Array<String>] change outputs to delete
+      # @param txid [String, nil] action txid
+      # @param fund_ref [String] fund reference used when locking inputs
+      def rollback(input_outpoints, change_outpoints, txid, fund_ref)
+        Array(input_outpoints).each do |op|
+          outputs = @storage.find_outputs({ outpoint: op, include_spent: true, limit: 1, offset: 0 })
+          next if outputs.empty?
+          next unless outputs.first[:pending_reference] == fund_ref
+
+          @storage.update_output_state(op, :spendable)
+        end
+        Array(change_outpoints).each { |op| @storage.delete_output(op) }
+        @storage.update_action_status(txid, 'failed') if txid
+      end
+    end
+  end
+end

data/lib/bsv/wallet_interface/memory_store.rb

@@ -2,9 +2,11 @@
 
 module BSV
   module Wallet
-    # In-memory storage adapter for testing and single-process use.
+    # In-memory storage adapter intended for testing and development only.
     #
     # Stores actions, outputs, and certificates in plain Ruby arrays.
+    # All data is lost when the process exits — do not use in production.
+    # Use PostgresStore (or another persistent adapter) for production wallets.
     #
     # Thread safety: a +Mutex+ serialises all state-mutating operations so that
     # concurrent threads cannot select and mark the same UTXO as pending.
@@ -12,9 +14,29 @@ module BSV
     #
     # NOTE: FileStore is NOT process-safe — concurrent processes share no
     # in-memory lock and may read stale state from disk.
+    #
+    # == Production Warning
+    #
+    # When +RACK_ENV+, +RAILS_ENV+, or +APP_ENV+ is set to +production+ or
+    # +staging+, a warning is emitted to stderr. Suppress it with either:
+    #
+    #   BSV_MEMORY_STORE_OK=1               # environment variable
+    #   MemoryStore.warn_in_production = false  # Ruby flag (e.g. in test setup)
     class MemoryStore
       include StorageAdapter
 
+      # Controls whether the production-environment warning is emitted.
+      # Set to +false+ in test suites to silence the warning globally.
+      #
+      # @return [Boolean]
+      def self.warn_in_production?
+        @warn_in_production != false
+      end
+
+      class << self
+        attr_writer :warn_in_production
+      end
+
       def initialize
         @actions = []
         @outputs = []
@@ -23,6 +45,12 @@ module BSV
         @transactions = {}
         @settings = {}
         @mutex = Mutex.new
+
+        return unless self.class.warn_in_production? && production_env?
+
+        warn '[bsv-wallet] MemoryStore is intended for testing only. ' \
+             'Use PostgresStore for production wallets. ' \
+             'Set BSV_MEMORY_STORE_OK=1 to silence this warning.'
       end
 
       def store_action(action_data)
@@ -255,6 +283,14 @@ module BSV
 
       private
 
+      # Returns true when the process is running in a production or staging
+      # environment and the operator has not explicitly acknowledged MemoryStore
+      # usage via the +BSV_MEMORY_STORE_OK+ environment variable.
+      def production_env?
+        env = ENV['RACK_ENV'] || ENV['RAILS_ENV'] || ENV.fetch('APP_ENV', nil)
+        env && %w[production staging].include?(env) && !ENV['BSV_MEMORY_STORE_OK']
+      end
+
       def filter_actions(query)
         results = @actions
         return results unless query[:labels]

data/lib/bsv/wallet_interface/version.rb

@@ -2,6 +2,6 @@
 
 module BSV
   module WalletInterface
-    VERSION = '0.6.0'
+    VERSION = '0.7.0'
   end
 end

data/lib/bsv/wallet_interface/wallet_client.rb

@@ -42,6 +42,9 @@ module BSV
       # @return [#broadcast, nil] the optional broadcaster (responds to #broadcast(tx))
       attr_reader :broadcaster
 
+      # @return [BroadcastQueue] the broadcast queue used to dispatch transactions
+      attr_reader :broadcast_queue
+
       # @param key [BSV::Primitives::PrivateKey, String, KeyDeriver] signing key
       # @param storage [StorageAdapter] persistence adapter (default: FileStore).
       #   Use +storage: MemoryStore.new+ for tests.
@@ -50,6 +53,7 @@ module BSV
       # @param proof_store [ProofStore, nil] merkle proof store (default: LocalProofStore backed by storage)
       # @param http_client [#request, nil] injectable HTTP client for certificate issuance
       # @param broadcaster [#broadcast, nil] optional broadcaster; any object responding to #broadcast(tx)
+      # @param broadcast_queue [BroadcastQueue, nil] optional broadcast queue; defaults to InlineQueue
       def initialize(
         key,
         storage: FileStore.new,
@@ -60,7 +64,8 @@ module BSV
         fee_estimator: nil,
         coin_selector: nil,
         change_generator: nil,
-        broadcaster: nil
+        broadcaster: nil,
+        broadcast_queue: nil
       )
         super(key)
         @storage = storage
@@ -74,6 +79,10 @@ module BSV
         @injected_fee_estimator    = fee_estimator
         @injected_coin_selector    = coin_selector
         @injected_change_generator = change_generator
+        @broadcast_queue = broadcast_queue || InlineQueue.new(
+          storage: @storage,
+          broadcaster: @broadcaster
+        )
       end
 
       # Returns true when a broadcaster has been configured.
@@ -689,22 +698,12 @@ module BSV
           @storage.store_transaction(txid, tx_hex)
 
           if no_send
-            # Leave inputs as :pending — the caller will either broadcast via
-            # send_with or cancel via abort_action.
-            store_change_outputs(txid, tx, change_outputs, tx_hex)
-
-            # Record change outpoint positions, then mark them :pending so they
-            # are not auto-selected by a concurrent create_action. This matches
-            # the TS SDK where noSend outputs have spendable: false.
-            change_outpoints = []
-            change_outputs.each do |spec|
-              idx = tx.outputs.index { |o| o.instance_variable_get(:@_spec).equal?(spec) }
-              next unless idx
-
-              op = "#{txid}.#{idx}"
-              change_outpoints << op
-              @storage.update_output_state(op, :pending, pending_reference: fund_ref, no_send: true)
-            end
+            # Store change outputs directly as :pending with no_send: true so a
+            # concurrent auto-fund cannot select them. No flip loop needed.
+            change_outpoints = store_change_outputs(
+              txid, tx, change_outputs, tx_hex,
+              state: :pending, pending_reference: fund_ref, no_send: true
+            )
 
             store_action(tx, args, status: 'nosend')
             store_tracked_outputs(txid, tx, caller_outputs)
@@ -724,46 +723,25 @@ module BSV
           else
             # Store everything in pending state first — inputs are already locked
             # as :pending by lock_utxos above, so we match that discipline here.
+            # Change outputs are stored directly as :pending to eliminate the
+            # TOCTOU window where a concurrent auto-fund could select them.
             store_action(tx, args, status: 'pending')
-            store_change_outputs(txid, tx, change_outputs, tx_hex)
-
-            # Record change outpoints and mark them :pending so a concurrent
-            # create_action cannot double-spend them before broadcast completes.
-            change_outpoints = []
-            change_outputs.each do |spec|
-              idx = tx.outputs.index { |o| o.instance_variable_get(:@_spec).equal?(spec) }
-              next unless idx
-
-              op = "#{txid}.#{idx}"
-              change_outpoints << op
-              @storage.update_output_state(op, :pending, pending_reference: fund_ref)
-            end
+            change_outpoints = store_change_outputs(
+              txid, tx, change_outputs, tx_hex,
+              state: :pending, pending_reference: fund_ref
+            )
 
             store_tracked_outputs(txid, tx, caller_outputs)
 
             beef_binary = tx.to_beef
 
-            if broadcast_enabled?
-              broadcast_and_promote(
-                tx, txid, selected_outpoints, change_outpoints, fund_ref, beef_binary
-              )
-            else
-              # No broadcaster configured — promote immediately and return BEEF
-              # for the caller to broadcast (backwards-compatible behaviour).
-              selected_outpoints.each { |op| @storage.update_output_state(op, :spent) }
-              change_outpoints.each { |op| @storage.update_output_state(op, :spendable) }
-
-              final_status = if args.dig(:options, :accept_delayed_broadcast)
-                               warn '[bsv-wallet] accept_delayed_broadcast: true is not yet implemented; ' \
-                                    'falling through to synchronous processing. ' \
-                                    'Background broadcasting is a planned future feature.'
-                               'unproven'
-                             else
-                               'completed'
-                             end
-              @storage.update_action_status(txid, final_status)
-              { txid: txid, tx: beef_binary.unpack('C*') }
-            end
+            @broadcast_queue.enqueue(
+              tx: tx, txid: txid, beef_binary: beef_binary,
+              input_outpoints: selected_outpoints,
+              change_outpoints: change_outpoints,
+              fund_ref: fund_ref,
+              accept_delayed_broadcast: args.dig(:options, :accept_delayed_broadcast)
+            )
           end
         rescue StandardError
           # Release the pending lock so the UTXOs are available for retry.
@@ -913,40 +891,55 @@ module BSV
         tx.add_output(output)
       end
 
-      # Persists change outputs in storage as new spendable UTXOs.
+      # Persists change outputs in storage with the specified state.
       #
       # Each output is stored with full BRC-29 derivation metadata so the
-      # wallet can derive the spending key later, and with +:state+ +:spendable+
-      # so it is eligible for future coin selection.
+      # wallet can derive the spending key later. The +:state+ parameter
+      # controls the initial state — pass +:pending+ with a +:pending_reference+
+      # to store outputs atomically in the correct state and avoid any TOCTOU
+      # window where a concurrent auto-fund could select them as spendable.
       #
       # @param txid [String] hex txid of the signed transaction
       # @param tx [BSV::Transaction::Transaction]
       # @param change_specs [Array<Hash>] change descriptors from {ChangeGenerator}
       # @param tx_hex [String] serialised transaction hex (used as source)
-      def store_change_outputs(txid, tx, change_specs, tx_hex)
+      # @param state [Symbol] initial output state (default: +:spendable+)
+      # @param pending_reference [String, nil] reference tag for pending outputs
+      # @param no_send [Boolean] when +true+, marks the output as no-send pending
+      # @return [Array<String>] list of stored outpoints ("txid.vout" format)
+      def store_change_outputs(txid, tx, change_specs, tx_hex, state: :spendable, pending_reference: nil, no_send: false)
+        outpoints = []
         change_specs.each do |spec|
           actual_idx = tx.outputs.index { |o| o.instance_variable_get(:@_spec).equal?(spec) }
           next unless actual_idx
 
-          locking_script_hex = if spec[:locking_script].is_a?(BSV::Script::Script)
-                                 spec[:locking_script].to_hex
-                               else
-                                 spec[:locking_script]
-                               end
+          entry = change_output_entry(txid, actual_idx, spec, tx_hex, state, pending_reference, no_send)
+          @storage.store_output(entry)
+          outpoints << "#{txid}.#{actual_idx}"
+        end
+        outpoints
+      end
 
-          @storage.store_output({
-                                  outpoint: "#{txid}.#{actual_idx}",
-                                  satoshis: spec[:satoshis],
-                                  locking_script: locking_script_hex,
-                                  basket: 'default',
-                                  tags: [],
-                                  derivation_prefix: spec[:derivation_prefix],
-                                  derivation_suffix: spec[:derivation_suffix],
-                                  sender_identity_key: spec[:sender_identity_key],
-                                  state: :spendable,
-                                  source_tx_hex: tx_hex
-                                })
+      def change_output_entry(txid, idx, spec, tx_hex, state, pending_reference, no_send)
+        locking_script_hex = spec[:locking_script].is_a?(BSV::Script::Script) ? spec[:locking_script].to_hex : spec[:locking_script]
+        entry = {
+          outpoint: "#{txid}.#{idx}",
+          satoshis: spec[:satoshis],
+          locking_script: locking_script_hex,
+          basket: 'default',
+          tags: [],
+          derivation_prefix: spec[:derivation_prefix],
+          derivation_suffix: spec[:derivation_suffix],
+          sender_identity_key: spec[:sender_identity_key],
+          state: state,
+          source_tx_hex: tx_hex
+        }
+        if state == :pending
+          entry[:pending_since] = Time.now.utc.iso8601
+          entry[:pending_reference] = pending_reference if pending_reference
+          entry[:no_send] = true if no_send
         end
+        entry
       end
 
       # Lazy accessors for auto-fund components. Created on first use so the
@@ -1217,8 +1210,11 @@ module BSV
         @storage.update_action_status(txid, action_status) if txid && action_status
       end
 
-      # Broadcasts the transaction and promotes storage state on success.
-      # On failure, rolls back all pending state changes.
+      # Delegates to the broadcast queue for auto-fund promotion.
+      #
+      # Kept as a thin wrapper so +promote_no_send+ callers (send_with path)
+      # remain unaffected. The queue handles broadcast, UTXO promotion, and
+      # rollback.
       #
       # @param tx [Transaction] signed transaction to broadcast
       # @param txid [String] hex transaction id
@@ -1226,21 +1222,15 @@ module BSV
       # @param change_outpoints [Array<String>] change output outpoints
       # @param fund_ref [String] fund reference used when locking
       # @param beef_binary [String] raw BEEF bytes
-      # @return [Hash] result hash with :txid, :tx, :broadcast_result or :broadcast_error, and :broadcast_status
+      # @return [Hash] result hash from +BroadcastQueue#enqueue+
       def broadcast_and_promote(tx, txid, input_outpoints, change_outpoints, fund_ref, beef_binary)
-        broadcast_result = @broadcaster.broadcast(tx)
-
-        # Broadcast succeeded — promote all pending state to final.
-        input_outpoints.each { |op| @storage.update_output_state(op, :spent) }
-        change_outpoints.each { |op| @storage.update_output_state(op, :spendable) }
-        @storage.update_action_status(txid, 'completed')
-
-        result = { txid: txid, tx: beef_binary.unpack('C*'), broadcast_result: broadcast_result, broadcast_status: 'success' }
-        result[:competing_txs] = broadcast_result.competing_txs if broadcast_result.competing_txs
-        result
-      rescue StandardError => e
-        rollback_pending_action(input_outpoints, change_outpoints, txid, fund_ref, action_status: 'failed')
-        { txid: txid, tx: beef_binary.unpack('C*'), broadcast_error: e.message, broadcast_status: broadcast_status_for(e) }
+        @broadcast_queue.enqueue(
+          tx: tx, txid: txid, beef_binary: beef_binary,
+          input_outpoints: input_outpoints,
+          change_outpoints: change_outpoints,
+          fund_ref: fund_ref,
+          accept_delayed_broadcast: false
+        )
       end
 
       # Batch-broadcasts a list of previously no_send transactions.
@@ -1292,10 +1282,29 @@ module BSV
       # Attempts to broadcast and promote a single no_send transaction.
       # Action status is set to 'unproven' (matching TS SDK SendWithResult)
       # because the transaction has been submitted but not yet confirmed.
+      #
+      # INVARIANT: Only broadcast failure triggers rollback. If broadcast succeeds
+      # but promotion raises, the error propagates — confirmed on-chain outputs must
+      # never be deleted. See +broadcast_and_promote+ for the same invariant.
       def promote_no_send(tx, txid, fund_ref, pending_entry)
-        @broadcaster.broadcast(tx)
+        begin
+          @broadcaster.broadcast(tx)
+        rescue StandardError => e
+          rollback_pending_action(
+            pending_entry[:locked_outpoints],
+            pending_entry[:change_outpoints],
+            txid,
+            fund_ref,
+            action_status: 'failed'
+          )
+          @pending.delete(fund_ref)
+          @pending_by_txid.delete(txid)
+          return { txid: txid, status: 'failed', error: e.message }
+        end
 
         # Broadcast succeeded — promote state and remove from pending indices.
+        # Do NOT rescue here: if promotion fails, the transaction is confirmed on-chain
+        # and outputs must not be deleted. Let the error propagate to the caller.
         pending_entry[:locked_outpoints].each { |op| @storage.update_output_state(op, :spent) }
         pending_entry[:change_outpoints].each { |op| @storage.update_output_state(op, :spendable) }
         @storage.update_action_status(txid, 'unproven')
@@ -1303,34 +1312,17 @@ module BSV
         @pending_by_txid.delete(txid)
 
         { txid: txid, status: 'unproven' }
-      rescue StandardError => e
-        rollback_pending_action(
-          pending_entry[:locked_outpoints],
-          pending_entry[:change_outpoints],
-          txid,
-          fund_ref,
-          action_status: 'failed'
-        )
-        @pending.delete(fund_ref)
-        @pending_by_txid.delete(txid)
-
-        { txid: txid, status: 'failed', error: e.message }
       end
 
       # Maps a broadcast exception to a {ReviewActionResultStatus} string.
       #
+      # Delegates to +BroadcastQueue.status_for_error+ for a single source of
+      # truth across all queue adapters.
+      #
       # @param error [StandardError] the exception raised during broadcast
       # @return [String] one of 'doubleSpend', 'invalidTx', 'serviceError'
       def broadcast_status_for(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'
+        BroadcastQueue.status_for_error(error)
       end
 
       def finalize_action(tx, args)
@@ -1355,30 +1347,16 @@ module BSV
 
         if no_send
           result[:no_send_change] = []
-        elsif broadcast_enabled?
-          # Broadcast and promote or rollback — same discipline as auto_fund path.
-          broadcast_result = nil
-          begin
-            broadcast_result = @broadcaster.broadcast(tx)
-            @storage.update_action_status(txid, 'completed')
-            result[:broadcast_result] = broadcast_result
-            result[:broadcast_status] = 'success'
-          rescue StandardError => e
-            @storage.update_action_status(txid, 'failed')
-            result[:broadcast_error] = e.message
-            result[:broadcast_status] = broadcast_status_for(e)
-          end
         else
-          # No broadcaster — promote immediately (backwards compatible).
-          final_status = if delayed
-                           warn '[bsv-wallet] accept_delayed_broadcast: true is not yet implemented; ' \
-                                'falling through to synchronous processing. ' \
-                                'Background broadcasting is a planned future feature.'
-                           'unproven'
-                         else
-                           'completed'
-                         end
-          @storage.update_action_status(txid, final_status)
+          # The queue handles both broadcaster-present and no-broadcaster cases
+          # internally, so no broadcast_enabled? check is needed here.
+          result.merge!(
+            @broadcast_queue.enqueue(
+              tx: tx, txid: txid, beef_binary: beef_binary,
+              input_outpoints: nil, change_outpoints: nil, fund_ref: nil,
+              accept_delayed_broadcast: delayed
+            )
+          )
         end
 
         result

data/lib/bsv/wallet_interface.rb

@@ -12,6 +12,8 @@ module BSV
     autoload :ProtoWallet,      'bsv/wallet_interface/proto_wallet'
     autoload :Validators,       'bsv/wallet_interface/validators'
     autoload :StorageAdapter,    'bsv/wallet_interface/storage_adapter'
+    autoload :BroadcastQueue,    'bsv/wallet_interface/broadcast_queue'
+    autoload :InlineQueue,       'bsv/wallet_interface/inline_queue'
     autoload :MemoryStore,       'bsv/wallet_interface/memory_store'
     autoload :FileStore,         'bsv/wallet_interface/file_store'
     autoload :ProofStore,        'bsv/wallet_interface/proof_store'

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: bsv-wallet
 version: !ruby/object:Gem::Version
-  version: 0.6.0
+  version: 0.7.0
 platform: ruby
 authors:
 - Simon Bettison
 bindir: bin
 cert_chain: []
-date: 2026-04-12 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: base64
@@ -53,6 +53,7 @@ files:
 - LICENSE
 - lib/bsv-wallet.rb
 - lib/bsv/wallet_interface.rb
+- lib/bsv/wallet_interface/broadcast_queue.rb
 - lib/bsv/wallet_interface/certificate_signature.rb
 - lib/bsv/wallet_interface/chain_provider.rb
 - lib/bsv/wallet_interface/change_generator.rb
@@ -65,6 +66,7 @@ files:
 - lib/bsv/wallet_interface/fee_estimator.rb
 - lib/bsv/wallet_interface/fee_model.rb
 - lib/bsv/wallet_interface/file_store.rb
+- lib/bsv/wallet_interface/inline_queue.rb
 - lib/bsv/wallet_interface/interface.rb
 - lib/bsv/wallet_interface/key_deriver.rb
 - lib/bsv/wallet_interface/local_proof_store.rb
@@ -103,7 +105,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.2
+rubygems_version: 4.0.10
 specification_version: 4
 summary: BRC-100 Wallet Interface for the BSV Blockchain
 test_files: []