bsv-wallet 0.5.1 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3ec8e4dbc04e014ab716a010b3059fa9134ba25718306ede7541bae3f7f3df94
-  data.tar.gz: 6b7727694dcaa8136a919f3abe06f65f5b238264a12a395863ddf3cf8c1f3533
+  metadata.gz: 233e4c969fea0e8bb52110ffffe9d034a953854ccb1098c0a3dd3eb76bb2c034
+  data.tar.gz: e11ab6c70e949cbe62593f620d0367225e80ac84a144f94b07418d02e9383466
 SHA512:
-  metadata.gz: 2288b14436eaf937e99c82b79c5c3d001d6e80f28d47d0848da1db309a5714c92398cf50ef1ff30bcaaa17d1f784f70ac8f3ae22340b6ed23276b3bd866e954b
-  data.tar.gz: 8adc0b4b11cde0e99727ce95c448b2c724f1cd72ea8835bd27e7ca28c19a6ac27f65fd9a6b1455f5ecd0110f7026c214e9adb8da33ebb1b7f89c8f26cbc64769
+  metadata.gz: 974ffa3042e2bb4fe3c9f7ec94d8503c55ed20e94d5a808a667700339fbb5151eec6b12c185238353ccfd40e62f197477081fdb7b6b9f9ce75da4598a4536b90
+  data.tar.gz: 0af0b5d238c57a1b640ea243b2bce0e5e33fd55932354689a62b1c05dfe3b41d776fdfcd5fe245fa3973de98632d6f0985bbfc4bed99b4d2527494dc16fc2f6f

data/CHANGELOG.md

@@ -5,6 +5,52 @@ 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
+- Broadcast-before-promote semantics for `create_action` — transactions are
+  broadcast via a configurable `broadcaster:` before promoting state, with
+  automatic rollback on failure to prevent phantom UTXOs (#369, #371)
+- `send_with` for batched broadcast of previously `no_send` transactions,
+  with per-transaction rollback on failure (#373)
+- `accept_delayed_broadcast` option accepted as a stub (defaults to `false`;
+  background broadcasting deferred to a follow-up) (#374)
+- `delete_action` and `update_action_status` on `StorageAdapter`, implemented
+  in MemoryStore, FileStore, and PostgresStore (#370)
+- Broadcast results mapped to `ReviewActionResultStatus` (`success`,
+  `doubleSpend`, `invalidTx`, `serviceError`) and returned in the result
+  hash (#372)
+
+### Fixed
+- EF version marker overhead corrected from 2 to 6 bytes in fee estimation
+- Fee estimation now includes EF overhead for ARC compatibility
+- `FeeEstimator` default raised from 1 sat/kB to 100 sat/kB
+- `internalize_payment` now stores outputs in the default basket
+- `derivation_type` comparison uses string comparison for JSON round-trip
+  safety (#367)
+
+### Changed
+- Extracted `DEFAULT_SATS_PER_KB` constant for fee estimation
+- Specs reorganised into per-gem directories (#363)
+
 ## 0.5.1 — 2026-04-11
 
 ### Fixed

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/fee_estimator.rb

@@ -8,40 +8,56 @@ module BSV
     # fee estimation given only input and output counts. Once a real {Transaction} is
     # available, delegates directly to the underlying SDK fee model via {#estimate_for_tx}.
     #
-    # The default rate is 1 sat/kB — the current BSV network standard. The SDK's own
-    # {SatoshisPerKilobyte} defaults to 100 sat/kB; this class intentionally differs.
+    # The default rate is 100 sat/kB, matching the ARC mining policy endpoint
+    # and the SDK's own {SatoshisPerKilobyte} default.
     #
     # @example Pre-construction estimate
     #   estimator = BSV::Wallet::FeeEstimator.new
     #   fee = estimator.estimate(p2pkh_inputs: 2, p2pkh_outputs: 3)
-    #   # => 1 (at 1 sat/kB, ceil(408/1000 * 1) = 1)
+    #   # => 41 (at 100 sat/kB, ceil(408/1000 * 100) = 41)
     #
     # @example Custom rate
     #   estimator = BSV::Wallet::FeeEstimator.new(sats_per_kb: 50)
     #   fee = estimator.estimate(p2pkh_inputs: 1, p2pkh_outputs: 1)
     #   # => 10 (ceil(192/1000 * 50) = 10)
     class FeeEstimator
-      # Estimated size in bytes of an unsigned P2PKH input.
-      # Matches {BSV::Transaction::Transaction::UNSIGNED_P2PKH_INPUT_SIZE}.
-      P2PKH_INPUT_SIZE = BSV::Transaction::Transaction::UNSIGNED_P2PKH_INPUT_SIZE
+      # Estimated size in bytes of an unsigned P2PKH input in raw format.
+      P2PKH_RAW_INPUT_SIZE = BSV::Transaction::Transaction::UNSIGNED_P2PKH_INPUT_SIZE
+
+      # Extended Format (BRC-30/EF) adds source_satoshis (8 bytes) +
+      # varint(25) (1 byte) + P2PKH locking script (25 bytes) = 34 bytes
+      # per input. ARC validates fees against the EF size, not raw.
+      EF_INPUT_OVERHEAD = 34
+
+      # Total estimated input size including EF overhead. This is the size
+      # ARC sees and charges fees against.
+      P2PKH_INPUT_SIZE = P2PKH_RAW_INPUT_SIZE + EF_INPUT_OVERHEAD
 
       # Estimated size in bytes of a P2PKH output (8 satoshis + varint(25) + 25-byte script).
       P2PKH_OUTPUT_SIZE = 34
 
-      # Fixed overhead in bytes for version (4) and lock_time (4).
-      FIXED_OVERHEAD = 8
+      # EF version marker: 6 bytes (\x00\x00\x00\x00\x00\xEF) follows
+      # the 4-byte version field, adding 6 bytes of fixed overhead.
+      EF_VERSION_OVERHEAD = 6
+
+      # Fixed overhead in bytes for version (4) + EF marker (6) + lock_time (4).
+      FIXED_OVERHEAD = 14
 
       # Approximate overhead including typical 1-byte varints for input/output
       # counts. Retained for backward compatibility with code that referenced
       # +FeeModel::OVERHEAD+.
       OVERHEAD = 10
 
+      # Default fee rate in satoshis per kilobyte, matching ARC's mining
+      # policy endpoint (/v1/policy → miningFee 100/1000).
+      DEFAULT_SATS_PER_KB = 100
+
       # @return [Integer] the satoshis-per-kilobyte rate used for estimation
       attr_reader :sats_per_kb
 
-      # @param sats_per_kb [Integer] fee rate in satoshis per kilobyte (default: 1)
+      # @param sats_per_kb [Integer] fee rate in satoshis per kilobyte
       # @raise [ArgumentError] if sats_per_kb is zero or negative
-      def initialize(sats_per_kb: 1)
+      def initialize(sats_per_kb: DEFAULT_SATS_PER_KB)
         raise ArgumentError, 'sats_per_kb must be greater than zero' unless sats_per_kb.positive?
 
         @sats_per_kb = sats_per_kb

data/lib/bsv/wallet_interface/file_store.rb

@@ -48,6 +48,18 @@ module BSV
         result
       end
 
+      def update_action_status(txid, new_status)
+        result = super
+        save_actions
+        result
+      end
+
+      def delete_action(txid)
+        result = super
+        save_actions if result
+        result
+      end
+
       def store_output(output_data)
         result = super
         save_outputs

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/key_deriver.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require 'openssl'
+
 module BSV
   module Wallet
     # BRC-42/43 key derivation for the wallet interface.

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)
@@ -30,6 +58,22 @@ module BSV
         action_data
       end
 
+      def update_action_status(txid, new_status)
+        action = @actions.find { |a| a[:txid] == txid }
+        raise WalletError, "Action not found: #{txid}" unless action
+
+        action[:status] = new_status
+        action
+      end
+
+      def delete_action(txid)
+        idx = @actions.index { |a| a[:txid] == txid }
+        return false unless idx
+
+        @actions.delete_at(idx)
+        true
+      end
+
       def find_actions(query)
         apply_pagination(filter_actions(query), query)
       end
@@ -239,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/storage_adapter.rb

@@ -67,6 +67,26 @@ module BSV
         raise NotImplementedError, "#{self.class}#find_transaction not implemented"
       end
 
+      # Updates the status field of a stored action identified by txid.
+      #
+      # @param _txid [String] the transaction identifier of the action to update
+      # @param _new_status [String] the new status value (e.g. 'failed', 'completed')
+      # @return [Hash] the updated action hash
+      # @raise [BSV::Wallet::WalletError] if no action with the given txid is found
+      # @raise [NotImplementedError]
+      def update_action_status(_txid, _new_status)
+        raise NotImplementedError, "#{self.class}#update_action_status not implemented"
+      end
+
+      # Removes a stored action by txid.
+      #
+      # @param _txid [String] the transaction identifier of the action to remove
+      # @return [Boolean] true if the action was deleted, false if not found
+      # @raise [NotImplementedError]
+      def delete_action(_txid)
+        raise NotImplementedError, "#{self.class}#delete_action not implemented"
+      end
+
       # Transitions the state of an existing output.
       #
       # When +new_state+ is +:pending+, pass a +pending_reference:+ string to

data/lib/bsv/wallet_interface/version.rb

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

data/lib/bsv/wallet_interface/wallet_client.rb

@@ -39,6 +39,12 @@ module BSV
       # @return [ProofStore] the merkle proof persistence store
       attr_reader :proof_store
 
+      # @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.
@@ -46,6 +52,8 @@ module BSV
       # @param chain_provider [ChainProvider] blockchain data provider (default: NullChainProvider)
       # @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,
@@ -55,7 +63,9 @@ module BSV
         http_client: nil,
         fee_estimator: nil,
         coin_selector: nil,
-        change_generator: nil
+        change_generator: nil,
+        broadcaster: nil,
+        broadcast_queue: nil
       )
         super(key)
         @storage = storage
@@ -63,10 +73,21 @@ module BSV
         @chain_provider = chain_provider
         @proof_store = proof_store || LocalProofStore.new(storage)
         @http_client = http_client
+        @broadcaster = broadcaster
         @pending = {}
+        @pending_by_txid = {}
         @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.
+      def broadcast_enabled?
+        !@broadcaster.nil?
       end
 
       # --- Transaction Operations ---
@@ -92,11 +113,29 @@ module BSV
       def create_action(args, _originator: nil)
         validate_create_action!(args)
 
+        send_with_txids = Array(args.dig(:options, :send_with))
+
         outputs = args[:outputs] || []
         inputs  = args[:inputs]
 
+        # When send_with is provided but no new transaction body is specified,
+        # broadcast only the batched no_send transactions.
+        if !send_with_txids.empty? && outputs.empty? && (inputs.nil? || inputs.empty?)
+          raise WalletError, 'A broadcaster is required to use send_with' unless broadcast_enabled?
+
+          return { send_with_results: broadcast_send_with(send_with_txids) }
+        end
+
         if (inputs.nil? || inputs.empty?) && !outputs.empty? && (args[:auto_fund] || spendable_pool_eligible?)
-          return auto_fund_and_create(args, outputs)
+          result = auto_fund_and_create(args, outputs)
+          # If send_with was also specified, batch-broadcast those alongside the
+          # current transaction's implicit broadcast.
+          unless send_with_txids.empty?
+            raise WalletError, 'A broadcaster is required to use send_with' unless broadcast_enabled?
+
+            result[:send_with_results] = broadcast_send_with(send_with_txids)
+          end
+          return result
         end
 
         beef = parse_input_beef(args[:input_beef])
@@ -125,7 +164,15 @@ module BSV
         tx = pending[:tx]
         apply_spends(tx, args[:spends])
         @pending.delete(reference)
-        finalize_action(tx, pending[:args])
+
+        # Merge sign_action's own options over the original create_action args so
+        # callers can supply accept_delayed_broadcast at sign time.
+        merged_args = if args[:options]
+                        pending[:args].merge(options: (pending[:args][:options] || {}).merge(args[:options]))
+                      else
+                        pending[:args]
+                      end
+        finalize_action(tx, merged_args)
       end
 
       # Aborts a pending signable transaction.
@@ -143,11 +190,14 @@ module BSV
         raise WalletError, 'Transaction not found for the given reference' unless @pending.key?(reference)
 
         pending_entry = @pending.delete(reference)
-        # Release locked input UTXOs back to :spendable.
-        release_pending_utxos(pending_entry[:locked_outpoints], reference) if pending_entry[:locked_outpoints]
-        # Remove change outputs created by the aborted transaction —
-        # they reference an unbroadcast tx and must not remain in storage.
-        Array(pending_entry[:change_outpoints]).each { |op| @storage.delete_output(op) }
+        txid = pending_entry[:tx]&.txid_hex
+        @pending_by_txid.delete(txid) if txid
+        rollback_pending_action(
+          pending_entry[:locked_outpoints],
+          pending_entry[:change_outpoints],
+          txid,
+          reference
+        )
         { aborted: true }
       end
 
@@ -347,7 +397,7 @@ module BSV
       # @return [Integer] total auto-spendable satoshis
       def spendable_balance(basket: nil)
         @storage.find_spendable_outputs(basket: basket)
-                .select { |o| (o[:derivation_prefix] && o[:derivation_suffix] && o[:sender_identity_key]) || o[:derivation_type] == :identity }
+                .select { |o| (o[:derivation_prefix] && o[:derivation_suffix] && o[:sender_identity_key]) || o[:derivation_type]&.to_s == 'identity' }
                 .sum { |o| o[:satoshis].to_i }
       end
 
@@ -613,7 +663,7 @@ module BSV
         all_spendable = @storage.find_spendable_outputs(basket: 'default')
         available = all_spendable.select do |o|
           (o[:derivation_prefix] && o[:derivation_suffix] && o[:sender_identity_key]) ||
-            o[:derivation_type] == :identity
+            o[:derivation_type]&.to_s == 'identity'
         end
 
         selection = auto_fund_select(available, target, caller_outputs.size)
@@ -648,46 +698,50 @@ 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)
 
-            # Register in @pending so abort_action can release inputs and
-            # remove change outputs.
+            # Register in @pending so abort_action (or send_with) can release
+            # inputs and remove change outputs. Secondary index by txid allows
+            # send_with callers to look up pending entries by txid.
             @pending[fund_ref] = {
               tx: tx, args: args,
               locked_outpoints: selected_outpoints,
               change_outpoints: change_outpoints
             }
+            @pending_by_txid[txid] = fund_ref
 
             beef_binary = tx.to_beef
             { txid: txid, tx: beef_binary.unpack('C*'), reference: fund_ref, no_send_change: change_outpoints }
           else
-            store_action(tx, args, status: 'completed')
-            store_change_outputs(txid, tx, change_outputs, tx_hex)
-            store_tracked_outputs(txid, tx, caller_outputs)
+            # 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')
+            change_outpoints = store_change_outputs(
+              txid, tx, change_outputs, tx_hex,
+              state: :pending, pending_reference: fund_ref
+            )
 
-            # Promote from :pending to :spent now that all storage writes are done.
-            selected_outpoints.each { |op| @storage.update_output_state(op, :spent) }
+            store_tracked_outputs(txid, tx, caller_outputs)
 
             beef_binary = tx.to_beef
-            { txid: txid, tx: beef_binary.unpack('C*') }
+
+            @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.
@@ -803,7 +857,7 @@ module BSV
 
         wire_source_from_storage(input, utxo[:outpoint])
 
-        priv = if utxo[:derivation_type] == :identity
+        priv = if utxo[:derivation_type]&.to_s == 'identity'
                  @key_deriver.root_key
                else
                  @key_deriver.derive_private_key(
@@ -837,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
@@ -897,7 +966,10 @@ module BSV
         Validators.validate_description!(args[:description])
         inputs_present = args[:inputs] && !args[:inputs].empty?
         outputs_present = args[:outputs] && !args[:outputs].empty?
-        raise InvalidParameterError.new('inputs/outputs', 'at least one input or output') unless inputs_present || outputs_present
+        send_with_present = args.dig(:options, :send_with) && !Array(args.dig(:options, :send_with)).empty?
+        unless inputs_present || outputs_present || send_with_present
+          raise InvalidParameterError.new('inputs/outputs', 'at least one input or output')
+        end
 
         validate_action_inputs!(args[:inputs]) if args[:inputs]
         validate_action_outputs!(args[:outputs]) if args[:outputs]
@@ -1121,10 +1193,150 @@ module BSV
         end
       end
 
+      # Rolls back a pending auto-funded action.
+      #
+      # Releases locked input UTXOs back to +:spendable+, deletes phantom change
+      # outputs, and optionally updates the action status. Used by both
+      # broadcast failure and +abort_action+ so UTXO state is always consistent.
+      #
+      # @param input_outpoints [Array<String>] outpoints locked as inputs
+      # @param change_outpoints [Array<String>] change outputs to delete
+      # @param txid [String, nil] txid of the action to update (may be nil)
+      # @param ref [String] fund reference used when locking inputs
+      # @param action_status [String, nil] new action status; nil skips the update
+      def rollback_pending_action(input_outpoints, change_outpoints, txid, ref, action_status: nil)
+        release_pending_utxos(input_outpoints, ref)
+        Array(change_outpoints).each { |op| @storage.delete_output(op) }
+        @storage.update_action_status(txid, action_status) if txid && action_status
+      end
+
+      # 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
+      # @param input_outpoints [Array<String>] outpoints locked as inputs
+      # @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 from +BroadcastQueue#enqueue+
+      def broadcast_and_promote(tx, txid, input_outpoints, change_outpoints, fund_ref, beef_binary)
+        @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.
+      #
+      # Each txid must correspond to a pending no_send entry registered in
+      # +@pending_by_txid+. Transactions are broadcast individually so that one
+      # failure does not block the others. On per-tx success the inputs are
+      # promoted to +:spent+ and change outputs to +:spendable+. On failure the
+      # pending state is rolled back via +rollback_pending_action+.
+      #
+      # @param txids [Array<String>] txids of no_send transactions to broadcast
+      # @return [Array<Hash>] per-tx results matching TS SDK +SendWithResult[]+ shape:
+      #   +{ txid: String, status: 'unproven' | 'failed' }+
+      def broadcast_send_with(txids)
+        txids.map { |txid| broadcast_single_no_send(txid) }
+      end
+
+      # Broadcasts one no_send transaction and promotes or rolls back its state.
+      #
+      # @param txid [String] hex txid of the no_send transaction
+      # @return [Hash] +{ txid:, status: }+ result entry
+      def broadcast_single_no_send(txid)
+        fund_ref = @pending_by_txid[txid]
+        return { txid: txid, status: 'failed', error: 'Transaction not found in pending no_send store' } unless fund_ref
+
+        pending_entry = @pending[fund_ref]
+        unless pending_entry
+          @pending_by_txid.delete(txid)
+          return { txid: txid, status: 'failed', error: 'Pending entry expired or already processed' }
+        end
+
+        # Use the original signed transaction from the pending entry — it has
+        # source_satoshis and source_locking_script wired on each input, which
+        # the broadcaster needs for Extended Format (EF/BRC-30) submission.
+        # Reconstructing from stored hex would lose that metadata.
+        tx = pending_entry[:tx]
+        unless tx
+          tx_hex = @storage.find_transaction(txid)
+          return { txid: txid, status: 'failed', error: 'Transaction not found' } unless tx_hex
+
+          tx = BSV::Transaction::Transaction.from_hex(tx_hex)
+        end
+        promote_no_send(tx, txid, fund_ref, pending_entry)
+      rescue StandardError => e
+        # Catch unexpected errors outside the broadcast rescue block.
+        { txid: txid, status: 'failed', error: e.message }
+      end
+
+      # 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)
+        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')
+        @pending.delete(fund_ref)
+        @pending_by_txid.delete(txid)
+
+        { txid: txid, status: 'unproven' }
+      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)
+        BroadcastQueue.status_for_error(error)
+      end
+
       def finalize_action(tx, args)
         tx.sign_all if tx.inputs.any?(&:unlocking_script_template)
         txid = tx.txid_hex
-        status = args.dig(:options, :no_send) ? 'nosend' : 'completed'
+
+        no_send = args.dig(:options, :no_send)
+        delayed = args.dig(:options, :accept_delayed_broadcast)
+
+        status = if no_send
+                   'nosend'
+                 else
+                   'pending'
+                 end
 
         @storage.store_transaction(txid, tx.to_hex)
         store_action(tx, args, status: status)
@@ -1132,7 +1344,21 @@ module BSV
 
         beef_binary = tx.to_beef
         result = { txid: txid, tx: beef_binary.unpack('C*') }
-        result[:no_send_change] = [] if args.dig(:options, :no_send)
+
+        if no_send
+          result[:no_send_change] = []
+        else
+          # 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
       end
 
@@ -1281,6 +1507,7 @@ module BSV
                                 outpoint: "#{txid}.#{output_index}",
                                 satoshis: tx_output.satoshis,
                                 locking_script: tx_output.locking_script.to_hex,
+                                basket: 'default',
                                 spendable: true,
                                 sender_identity_key: sender_key,
                                 derivation_prefix: prefix,

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.5.1
+  version: 0.7.0
 platform: ruby
 authors:
 - Simon Bettison
 bindir: bin
 cert_chain: []
-date: 2026-04-11 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: []