Merge pull request #417 from sgbett/feat/390-attest-create-action

feat: rework bsv-attest to use wallet create_action

Author: sgbett

.claude/plans/20260412-attest-create-action.md

@@ -0,0 +1,183 @@
+# Plan: Rework bsv-attest to use wallet create_action (#390)
+
+## Context
+
+`bsv-attest` v0.1.0 was written before `bsv-wallet` existed. Its `publish` method calls `wallet.fund_and_sign(tx)` (doesn't exist) and requires a separate `broadcaster:`. The x402-rack companion gem demonstrates the correct pattern: delegate to `wallet.create_action`, letting the wallet handle funding, signing, broadcasting, and UTXO state.
+
+This is an integration rework — the core hash/verify logic is sound and unchanged.
+
+The gem's scope is deliberately narrow: OP_RETURN attestation with the simplicity that entails. Hash data, publish the hash, verify it by txid. No BEEF, no merkle proofs, no proof documents. A future archival service can layer proof-based verification on top using the wallet's BEEF output directly — that's not this gem's concern.
+
+## Tasks
+
+### Task 1: Update Configuration — remove `broadcaster:`, keep `wallet:` and `provider:`
+
+**File:** `gem/bsv-attest/lib/bsv/attest/configuration.rb`
+
+Remove `broadcaster` from `attr_accessor`. Configuration becomes:
+```ruby
+attr_accessor :wallet, :provider
+```
+
+**File:** `gem/bsv-attest/spec/bsv/attest/configuration_spec.rb`
+
+Remove broadcaster-related specs, update the "supports setting all attributes" spec to cover only `wallet` and `provider`.
+
+### Task 2: Update Response — drop `transaction`, keep it simple
+
+**File:** `gem/bsv-attest/lib/bsv/attest/response.rb`
+
+Current: `attr_reader :hash, :transaction, :txid`
+
+New:
+```ruby
+attr_reader :hash, :txid
+
+def initialize(hash:, txid:)
+  @hash = hash
+  @txid = txid
+end
+```
+
+- Drop `transaction` — we no longer build the Transaction object ourselves
+- No BEEF, no broadcast_status — the gem returns what the caller needs: the hash and where to find it
+- `hash_hex` stays the same
+
+**File:** `gem/bsv-attest/spec/bsv/attest/response_spec.rb`
+
+Update to test the new attributes (just `hash` and `txid`), remove `transaction` specs.
+
+### Task 3: Add BroadcastError class
+
+**File:** `gem/bsv-attest/lib/bsv/attest/broadcast_error.rb` (new)
+
+```ruby
+class BroadcastError < StandardError; end
+```
+
+Raised when `create_action` returns a `broadcast_error` in its result. This gives callers a distinct exception type for broadcast failures vs argument errors.
+
+**File:** `gem/bsv-attest/lib/bsv/attest.rb` — add autoload entry.
+
+### Task 4: Rewrite `publish` to use `wallet.create_action`
+
+**File:** `gem/bsv-attest/lib/bsv/attest.rb`
+
+Current signature: `publish(data, wallet: nil, broadcaster: nil)`
+New signature: `publish(data, wallet: nil, description: nil)`
+
+Implementation:
+```ruby
+def publish(data, wallet: nil, description: nil)
+  w = wallet || configuration.wallet
+  raise ArgumentError, 'wallet is required' unless w
+
+  digest = hash(data)
+  script = BSV::Script::Script.op_return(digest)
+
+  desc = description || 'Attest data hash to chain'
+
+  result = w.create_action(
+    description: desc,
+    outputs: [{
+      locking_script: script.to_hex,
+      satoshis: 0,
+      output_description: 'Attestation hash'
+    }],
+    options: { randomize_outputs: false }
+  )
+
+  if result[:broadcast_error]
+    raise BroadcastError, result[:broadcast_error]
+  end
+
+  Response.new(hash: digest, txid: result[:txid])
+end
+```
+
+Key decisions:
+- **No `broadcaster:` parameter** — wallet owns broadcasting
+- **`description:` parameter** — optional override for the wallet action description (default: 'Attest data hash to chain', 26 chars, within 5-50 limit)
+- **`randomize_outputs: false`** — deterministic output ordering (OP_RETURN first, then change)
+- **BroadcastError on failure** — if the wallet returns broadcast_error, raise rather than return a partial response
+- **Response is just hash + txid** — no BEEF, no broadcast metadata; the gem returns what you need to verify later
+- **`verify` unchanged** — provider-based verification is independent of the publish rework
+
+### Task 5: Update gemspec and version
+
+**File:** `gem/bsv-attest/bsv-attest.gemspec`
+
+```ruby
+spec.add_dependency 'bsv-sdk', '>= 0.11.0', '< 1.0'
+spec.add_dependency 'bsv-wallet', '>= 0.7.0', '< 1.0'
+```
+
+The wallet is a runtime dependency because `publish` calls `create_action` directly. Version floors match current releases.
+
+**File:** `gem/bsv-attest/lib/bsv/attest/version.rb`
+
+Bump to `0.2.0` — breaking change (dropped broadcaster, changed Response shape).
+
+### Task 6: Rewrite specs
+
+**File:** `gem/bsv-attest/spec/bsv/attest_spec.rb`
+
+**publish specs** — replace mock wallet/broadcaster with a mock that responds to `create_action`:
+
+```ruby
+let(:mock_wallet) do
+  Class.new do
+    def create_action(args)
+      { txid: 'bb' * 32 }
+    end
+  end.new
+end
+```
+
+Update specs:
+- "builds an OP_RETURN transaction" → "delegates to create_action and returns Response"
+- "includes the hash in an OP_RETURN output" → verify the create_action args include correct locking_script (spy mock)
+- Remove "raises ArgumentError without broadcaster"
+- Add "raises BroadcastError on broadcast failure"
+- Add "passes custom description to create_action"
+- Update per-call override spec (wallet only, no broadcaster)
+- Update fallback spec (wallet only)
+- Keep verify specs unchanged (they test provider, not wallet)
+
+To verify create_action receives the correct output spec, use a spy-style mock:
+
+```ruby
+let(:spy_wallet) do
+  Class.new do
+    attr_reader :last_args
+    def create_action(args)
+      @last_args = args
+      { txid: 'bb' * 32 }
+    end
+  end.new
+end
+```
+
+Then assert `spy_wallet.last_args[:outputs].first[:locking_script]` contains the expected OP_RETURN hex.
+
+## Files Modified
+
+| File | Action |
+|------|--------|
+| `gem/bsv-attest/lib/bsv/attest.rb` | Edit: rewrite publish, add autoloads |
+| `gem/bsv-attest/lib/bsv/attest/configuration.rb` | Edit: remove broadcaster |
+| `gem/bsv-attest/lib/bsv/attest/response.rb` | Edit: simplify to hash + txid only |
+| `gem/bsv-attest/lib/bsv/attest/broadcast_error.rb` | New: BroadcastError class |
+| `gem/bsv-attest/lib/bsv/attest/version.rb` | Edit: bump to 0.2.0 |
+| `gem/bsv-attest/bsv-attest.gemspec` | Edit: add bsv-wallet dep, pin bsv-sdk |
+| `gem/bsv-attest/spec/bsv/attest_spec.rb` | Edit: rewrite publish specs |
+| `gem/bsv-attest/spec/bsv/attest/configuration_spec.rb` | Edit: remove broadcaster specs |
+| `gem/bsv-attest/spec/bsv/attest/response_spec.rb` | Edit: test simplified attributes |
+
+## Verification
+
+```bash
+cd gem/bsv-attest && bundle exec rspec    # all specs pass
+bundle exec rubocop gem/bsv-attest        # no offences
+cd gem/bsv-attest && gem build bsv-attest.gemspec  # gem builds
+```

gem/bsv-attest/bsv-attest.gemspec

@@ -27,5 +27,6 @@ Gem::Specification.new do |spec|
   end + %w[LICENSE CHANGELOG.md]
   spec.require_paths = ['lib']
 
-  spec.add_dependency 'bsv-sdk'
+  spec.add_dependency 'bsv-sdk', '>= 0.11.0', '< 1.0'
+  spec.add_dependency 'bsv-wallet', '>= 0.7.0', '< 1.0'
 end

gem/bsv-attest/lib/bsv/attest.rb

@@ -2,6 +2,7 @@
 
 module BSV
   module Attest
+    autoload :BroadcastError,    'bsv/attest/broadcast_error'
     autoload :Configuration,     'bsv/attest/configuration'
     autoload :Response,          'bsv/attest/response'
     autoload :VerificationError, 'bsv/attest/verification_error'
@@ -24,25 +25,30 @@ def hash(data)
         BSV::Primitives::Digest.sha256(data)
       end
 
-      def publish(data, wallet: nil, broadcaster: nil)
+      def publish(data, wallet: nil, description: nil)
         w = wallet || configuration.wallet
-        b = broadcaster || configuration.broadcaster
         raise ArgumentError, 'wallet is required' unless w
-        raise ArgumentError, 'broadcaster is required' unless b
 
         digest = hash(data)
-
         script = BSV::Script::Script.op_return(digest)
-        output = BSV::Transaction::TransactionOutput.new(satoshis: 0, locking_script: script)
 
-        tx = BSV::Transaction::Transaction.new
-        tx.add_output(output)
+        desc = description || 'Attest data hash to chain'
 
-        w.fund_and_sign(tx)
+        result = w.create_action(
+          {
+            description: desc,
+            outputs: [{
+              locking_script: script.to_hex,
+              satoshis: 0,
+              output_description: 'Attestation hash'
+            }],
+            options: { randomize_outputs: false }
+          }
+        )
 
-        broadcast_response = b.broadcast(tx)
+        raise BroadcastError, result[:broadcast_error] if result[:broadcast_error]
 
-        Response.new(hash: digest, transaction: tx, txid: broadcast_response.txid)
+        Response.new(hash: digest, txid: result[:txid])
       end
 
       def verify(data, txid, provider: nil)

gem/bsv-attest/lib/bsv/attest/broadcast_error.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module BSV
+  module Attest
+    class BroadcastError < StandardError; end
+  end
+end

gem/bsv-attest/lib/bsv/attest/configuration.rb

@@ -3,7 +3,7 @@
 module BSV
   module Attest
     class Configuration
-      attr_accessor :wallet, :broadcaster, :provider
+      attr_accessor :wallet, :provider
     end
   end
 end

gem/bsv-attest/lib/bsv/attest/response.rb

@@ -3,11 +3,10 @@
 module BSV
   module Attest
     class Response
-      attr_reader :hash, :transaction, :txid
+      attr_reader :hash, :txid
 
-      def initialize(hash:, transaction:, txid:)
+      def initialize(hash:, txid:)
         @hash = hash
-        @transaction = transaction
         @txid = txid
       end
 

gem/bsv-attest/lib/bsv/attest/version.rb

@@ -2,6 +2,6 @@
 
 module BSV
   module Attest
-    VERSION = '0.1.0'
+    VERSION = '0.2.0'
   end
 end

gem/bsv-attest/spec/bsv/attest/broadcast_error_spec.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+
+require 'bsv-attest'
+
+RSpec.describe BSV::Attest::BroadcastError do
+  it 'is a StandardError subclass' do
+    expect(described_class).to be < StandardError
+  end
+
+  it 'stores a message' do
+    error = described_class.new('broadcast failed')
+    expect(error.message).to eq('broadcast failed')
+  end
+end

gem/bsv-attest/spec/bsv/attest/configuration_spec.rb

@@ -11,25 +11,22 @@
     expect(config.wallet).to be_nil
   end
 
-  it 'defaults broadcaster to nil' do
-    expect(config.broadcaster).to be_nil
-  end
-
   it 'defaults provider to nil' do
     expect(config.provider).to be_nil
   end
 
-  it 'supports setting all three attributes' do
+  it 'supports setting all attributes' do
     wallet = Object.new
-    broadcaster = Object.new
     provider = Object.new
 
     config.wallet = wallet
-    config.broadcaster = broadcaster
     config.provider = provider
 
     expect(config.wallet).to eq(wallet)
-    expect(config.broadcaster).to eq(broadcaster)
     expect(config.provider).to eq(provider)
   end
+
+  it 'does not respond to broadcaster' do
+    expect(config).not_to respond_to(:broadcaster)
+  end
 end

gem/bsv-attest/spec/bsv/attest/response_spec.rb

@@ -6,25 +6,24 @@
 
 RSpec.describe BSV::Attest::Response do
   subject(:response) do
-    described_class.new(hash: hash_bytes, transaction: transaction, txid: txid)
+    described_class.new(hash: hash_bytes, txid: txid)
   end
 
   let(:hash_bytes) { BSV::Primitives::Digest.sha256('test data') }
-  let(:transaction) { BSV::Transaction::Transaction.new }
   let(:txid) { 'aa' * 32 }
 
   it 'stores the hash' do
     expect(response.hash).to eq(hash_bytes)
   end
 
-  it 'stores the transaction' do
-    expect(response.transaction).to eq(transaction)
-  end
-
   it 'stores the txid' do
     expect(response.txid).to eq(txid)
   end
 
+  it 'does not respond to transaction' do
+    expect(response).not_to respond_to(:transaction)
+  end
+
   describe '#hash_hex' do
     it 'returns a 64-character hex string' do
       hex = response.hash_hex