bsv-wallet 0.8.0 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c71d9a7e4b68e5d47c4d95e3a8bcd6c23c698a92ca3faa4809a9a7abf1171b8e
-  data.tar.gz: f61618ef74ba89eae855dc710244f5a9208bff34a2244f4bb2ab6425d6774fea
+  metadata.gz: 7959ebc47fc5d89d3d0db18f4136c925e228f6ea483553decffd4b9e7de9defc
+  data.tar.gz: 2365a17193357b64d50c15a61aa12422b966b8f0155a6ab989b3bacb700a0929
 SHA512:
-  metadata.gz: 9c9d6badbfaac1bb19ed0bf5745ccfe21aba5372822e692be72f1065df56175481277e8f1b41daf4c17dd0acc758e43a2dcf73d4e8c96147d982dafd7b7a7ca3
-  data.tar.gz: 161733d4e9c277c55d4e3b1d89eab89bf156d066575c3f924e066c636d55f65606cd1e4df7afdbbdf0ff8cea615d5d6c09c30aafc63773294370c22659a3bf85
+  metadata.gz: 895d3c7a661e00b7d70dd833d12e4dd0e17ca2a8d0d8ba6a2c0ef622dfbac6bc0d6fb534a3fe06c14c0b1747981f1e0c9b8b61e9f164e3cc8fea222e5f9e70c1
+  data.tar.gz: 3086ff6e236c57d903c947ac7c230148104993837b3d2f46ddef3a09a9b43da42bab1a5ea6f1c7b375b105cc7e8feffe2c8defbd83a325ec7ca0775dbd1f2ea1

data/CHANGELOG.md

@@ -5,6 +5,47 @@ 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.9.0 — 2026-04-16
+
+### Changed — **Breaking**
+
+#### Action status taxonomy aligned with BRC-100 reference SDK (HLR #455)
+
+This release realigns the action status values with the wallet-toolbox reference
+implementation. The meaning of `'completed'` has changed — **consumers must
+update any code that checks for `'completed'` as the post-broadcast success
+state**.
+
+| Status | Old meaning | New meaning |
+|--------|-------------|-------------|
+| `'nosend'` | No change | Transaction built but not broadcast (`no_send: true`) |
+| `'sending'` | No change | Async queue accepted; worker has not yet attempted broadcast |
+| `'unproven'` | *(new)* | Broadcast succeeded; awaiting merkle proof |
+| `'completed'` | Broadcast succeeded | **Merkle proof received and stored** |
+| `'failed'` | No change | Broadcast rejected or transaction invalid |
+
+**Migration:**
+
+- Code querying `list_actions(status: 'completed')` will return fewer results
+  until a proof-watcher is implemented (out of scope for this release). To find
+  successfully-broadcast actions that have not yet received a proof, query
+  `status: 'unproven'` instead.
+- `create_action` and `sign_action` now raise `BSV::Wallet::WalletError` when
+  no broadcaster is configured and `options: { no_send: true }` is not set.
+  Previously these calls succeeded silently. To resolve: pass
+  `broadcaster: BSV::Network::ARC.default` to `WalletClient.new`, or pass
+  `options: { no_send: true }` to `create_action` to build without
+  broadcasting.
+- `internalize_action` now sets status to `'completed'` only when the supplied
+  BEEF contains a merkle proof for the subject transaction. Plain BEEF (raw
+  transaction, no BUMP) results in status `'unproven'`.
+- Wallets configured with a `SolidQueueAdapter` satisfy the broadcaster
+  requirement if the adapter carries an embedded `broadcaster:` — the
+  `WalletClient` itself does not need one.
+
+**Related upstream incidents:** x402-rack #148, x402-rack #158, x402-doom #196.
+**Tracking issue:** #455.
+
 ## 0.8.0 — 2026-04-15
 
 ### Added

data/lib/bsv/wallet_interface/broadcast_queue.rb

@@ -68,6 +68,21 @@ module BSV
         false
       end
 
+      # Returns +false+ by default — adapters without a broadcaster cannot
+      # broadcast on-chain.
+      #
+      # Override in adapters that hold a broadcaster reference so that
+      # +WalletClient+ can determine broadcast availability from the queue
+      # alone. This is the correct delegation point because users may pass a
+      # broadcaster-equipped queue (e.g.
+      # +SolidQueueAdapter.new(broadcaster: arc)+) without also passing
+      # +broadcaster:+ directly to +WalletClient+.
+      #
+      # @return [Boolean]
+      def broadcast_enabled?
+        false
+      end
+
       # Returns the broadcast status for a previously enqueued transaction.
       #
       # @param _txid [String] hex transaction identifier

data/lib/bsv/wallet_interface/inline_queue.rb

@@ -30,6 +30,17 @@ module BSV
         false
       end
 
+      # Returns +true+ when a broadcaster has been configured.
+      #
+      # +WalletClient+ delegates its own +broadcast_enabled?+ to this method
+      # so the check works correctly when the broadcaster is embedded in the
+      # queue rather than passed directly to the wallet.
+      #
+      # @return [Boolean]
+      def broadcast_enabled?
+        !@broadcaster.nil?
+      end
+
       # Returns the broadcast status for a previously enqueued transaction.
       #
       # Delegates to storage and returns the action status field, or +nil+ if
@@ -96,8 +107,10 @@ module BSV
           }
         end
 
-        # Broadcast succeeded — promote all pending state to final.
-        promote(input_outpoints, change_outpoints, txid)
+        # Broadcast succeeded — promote all pending state; set status to
+        # 'unproven' (transaction is on-chain but lacks a merkle proof).
+        # 'completed' is reserved for transactions confirmed by a proof-watcher.
+        promote(input_outpoints, change_outpoints, txid, status: 'unproven')
 
         result = {
           txid: txid,
@@ -109,14 +122,24 @@ module BSV
         result
       end
 
-      # Promotes UTXO state without broadcasting — backwards-compatible fallback
-      # used when no broadcaster is configured.
+      # Promotes UTXO state without broadcasting.
       #
-      # If +accept_delayed_broadcast+ is set the action status is +unproven+;
-      # otherwise it is +completed+.
+      # This path is reached when no broadcaster is configured. It is only
+      # valid when +accept_delayed_broadcast+ is set on the create_action
+      # call — the caller explicitly accepts that the transaction will be
+      # broadcast out-of-band. Action status is set to +unproven+.
+      #
+      # +completed+ is reserved for transactions that have received a merkle
+      # proof (set by +internalize_action+ or a future proof-watcher).
+      #
+      # Defensive guard: raises +WalletError+ if reached without
+      # +accept_delayed_broadcast+. The normal entry point for this guard is
+      # the +create_action+ validation added in Task 1 (#456), but this guard
+      # protects against other code paths that bypass it.
       #
       # @param payload [Hash] broadcast payload
       # @return [Hash] result hash containing +:txid+ and +:tx+
+      # @raise [BSV::Wallet::WalletError] if +accept_delayed_broadcast+ is not set
       def promote_without_broadcast(payload)
         txid             = payload[:txid]
         beef_binary      = payload[:beef_binary]
@@ -124,8 +147,14 @@ module BSV
         change_outpoints = payload[:change_outpoints]
         delayed          = payload[:accept_delayed_broadcast]
 
-        final_status = delayed ? 'unproven' : 'completed'
-        promote(input_outpoints, change_outpoints, txid, status: final_status)
+        unless delayed
+          raise BSV::Wallet::WalletError,
+                'InlineQueue cannot promote without a broadcaster unless ' \
+                'accept_delayed_broadcast is set. This indicates a bypass of ' \
+                'the create_action guard — report as a bug.'
+        end
+
+        promote(input_outpoints, change_outpoints, txid, status: 'unproven')
 
         { txid: txid, tx: beef_binary.unpack('C*') }
       end

data/lib/bsv/wallet_interface/version.rb

@@ -2,6 +2,6 @@
 
 module BSV
   module Wallet
-    VERSION = '0.8.0'
+    VERSION = '0.9.0'
   end
 end

data/lib/bsv/wallet_interface/wallet_client.rb

@@ -94,9 +94,13 @@ module BSV
         )
       end
 
-      # Returns true when a broadcaster has been configured.
+      # Returns +true+ when broadcast is available.
+      #
+      # Delegates to the broadcast queue so that queue-embedded broadcasters
+      # (e.g. +SolidQueueAdapter.new(broadcaster: arc)+) are recognised even
+      # when no +broadcaster:+ was passed directly to +WalletClient+.
       def broadcast_enabled?
-        !@broadcaster.nil?
+        @broadcast_queue.broadcast_enabled?
       end
 
       # --- Transaction Operations ---
@@ -123,6 +127,7 @@ module BSV
         return @substrate.create_action(args, originator: originator) if @substrate
 
         validate_create_action!(args)
+        validate_broadcast_configuration!(args)
 
         send_with_txids = Array(args.dig(:options, :send_with))
 
@@ -185,6 +190,11 @@ module BSV
                       else
                         pending[:args]
                       end
+
+        # Re-validate broadcast configuration on merged args — options may have
+        # been flipped between create_action and sign_action (e.g. no_send toggled).
+        validate_broadcast_configuration!(merged_args)
+
         finalize_action(tx, merged_args)
       end
 
@@ -303,7 +313,8 @@ module BSV
         store_proofs_from_beef(beef)
         @storage.store_transaction(tx.txid_hex, tx.to_hex)
         process_internalize_outputs(tx, args[:outputs])
-        store_action(tx, args, status: 'completed')
+        has_proof = !beef.find_bump(tx.txid).nil?
+        store_action(tx, args, status: has_proof ? 'completed' : 'unproven')
         { accepted: true }
       end
 
@@ -1068,6 +1079,25 @@ module BSV
 
       # --- Validation ---
 
+      # Raises +WalletError+ when a broadcast is required but unavailable.
+      #
+      # Broadcast is required whenever +no_send+ is absent or false. Callers
+      # that do not intend to broadcast on-chain must pass
+      # +options: { no_send: true }+ to opt out.
+      #
+      # @param args [Hash] action arguments (merged, as seen at call site)
+      # @raise [WalletError] if broadcast is needed but +broadcast_enabled?+ is false
+      def validate_broadcast_configuration!(args)
+        no_send = args.dig(:options, :no_send)
+        return if no_send
+        return if broadcast_enabled?
+
+        raise WalletError,
+              'create_action requires a broadcaster for on-chain broadcast. ' \
+              'Pass broadcaster: BSV::Network::ARC.default to WalletClient.new, ' \
+              'or options: { no_send: true } to build a transaction without broadcasting.'
+      end
+
       def validate_create_action!(args)
         Validators.validate_description!(args[:description])
         inputs_present = args[:inputs] && !args[:inputs].empty?

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: bsv-wallet
 version: !ruby/object:Gem::Version
-  version: 0.8.0
+  version: 0.9.0
 platform: ruby
 authors:
 - Simon Bettison