bsv-wallet 0.5.1 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3ec8e4dbc04e014ab716a010b3059fa9134ba25718306ede7541bae3f7f3df94
-  data.tar.gz: 6b7727694dcaa8136a919f3abe06f65f5b238264a12a395863ddf3cf8c1f3533
+  metadata.gz: 832766edaf4b3b59b4a5a2bdf47e997972b62336ddbf65614e5445f254615fa4
+  data.tar.gz: c2bb017e369d5b7497c134fde1d5fd729e8952cc8a11bb04c05eaa6ad7f6ebf2
 SHA512:
-  metadata.gz: 2288b14436eaf937e99c82b79c5c3d001d6e80f28d47d0848da1db309a5714c92398cf50ef1ff30bcaaa17d1f784f70ac8f3ae22340b6ed23276b3bd866e954b
-  data.tar.gz: 8adc0b4b11cde0e99727ce95c448b2c724f1cd72ea8835bd27e7ca28c19a6ac27f65fd9a6b1455f5ecd0110f7026c214e9adb8da33ebb1b7f89c8f26cbc64769
+  metadata.gz: b2861431435b2e6aa871cbb6dfdc020f8a1c010eef487606efa9f0d1de9f8bd5ef6c6f2384eea98c621d72bb9be0175e280de47ac927f3effb4b11e931528d0f
+  data.tar.gz: b08fc27ca7a74a3f98e9df12190d7198296d8e91527848edba41e288066fbc6e164d9b13e793666232489a8edae7dacc514340058542be7d99e060db4eb5e754

data/CHANGELOG.md

@@ -5,6 +5,34 @@ 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.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/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/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

@@ -30,6 +30,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

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.6.0'
   end
 end

data/lib/bsv/wallet_interface/wallet_client.rb

@@ -39,6 +39,9 @@ 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
+
       # @param key [BSV::Primitives::PrivateKey, String, KeyDeriver] signing key
       # @param storage [StorageAdapter] persistence adapter (default: FileStore).
       #   Use +storage: MemoryStore.new+ for tests.
@@ -46,6 +49,7 @@ 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)
       def initialize(
         key,
         storage: FileStore.new,
@@ -55,7 +59,8 @@ module BSV
         http_client: nil,
         fee_estimator: nil,
         coin_selector: nil,
-        change_generator: nil
+        change_generator: nil,
+        broadcaster: nil
       )
         super(key)
         @storage = storage
@@ -63,12 +68,19 @@ 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
       end
 
+      # Returns true when a broadcaster has been configured.
+      def broadcast_enabled?
+        !@broadcaster.nil?
+      end
+
       # --- Transaction Operations ---
 
       # Creates a new Bitcoin transaction.
@@ -92,11 +104,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 +155,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 +181,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 +388,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 +654,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)
@@ -668,26 +709,61 @@ module BSV
             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 everything in pending state first — inputs are already locked
+            # as :pending by lock_utxos above, so we match that discipline here.
+            store_action(tx, args, status: 'pending')
             store_change_outputs(txid, tx, change_outputs, tx_hex)
-            store_tracked_outputs(txid, tx, caller_outputs)
 
-            # Promote from :pending to :spent now that all storage writes are done.
-            selected_outpoints.each { |op| @storage.update_output_state(op, :spent) }
+            # 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
+
+            store_tracked_outputs(txid, tx, caller_outputs)
 
             beef_binary = tx.to_beef
-            { txid: txid, tx: beef_binary.unpack('C*') }
+
+            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
           end
         rescue StandardError
           # Release the pending lock so the UTXOs are available for retry.
@@ -803,7 +879,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(
@@ -897,7 +973,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 +1200,151 @@ 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
+
+      # Broadcasts the transaction and promotes storage state on success.
+      # On failure, rolls back all pending state changes.
+      #
+      # @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 with :txid, :tx, :broadcast_result or :broadcast_error, and :broadcast_status
+      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) }
+      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.
+      def promote_no_send(tx, txid, fund_ref, pending_entry)
+        @broadcaster.broadcast(tx)
+
+        # Broadcast succeeded — promote state and remove from pending indices.
+        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' }
+      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.
+      #
+      # @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'
+      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 +1352,35 @@ 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] = []
+        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)
+        end
+
         result
       end
 
@@ -1281,6 +1529,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,

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: bsv-wallet
 version: !ruby/object:Gem::Version
-  version: 0.5.1
+  version: 0.6.0
 platform: ruby
 authors:
 - Simon Bettison
 bindir: bin
 cert_chain: []
-date: 2026-04-11 00:00:00.000000000 Z
+date: 2026-04-12 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: base64