bsv-sdk 0.6.2 → 0.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b3a34503ada1c79e20bfafede1357f26715000394c5b286e21bc40374c040729
-  data.tar.gz: 594a0b52441b9a7c0e1dc8590174f06f27e196ce573a4244d722d1c5381636d3
+  metadata.gz: 27f8c2431bb1d2a33a2f068fc4f46a616eb1ce000b1e61309819a745b596d57f
+  data.tar.gz: 172cb6b1dd0eeff2cbaa2887ccef5454df6dd8f18ebf7be7b16fb342d09fa749
 SHA512:
-  metadata.gz: 87b8c8198f8f6a29f783364a83d4983b77ea7119b316f1b4cce77b4bb60333cc3fb8134aecb9cc58327558fac3368803811f77dab6ec2a91a8f9cfabbb19418e
-  data.tar.gz: ebaead0b459cc6fda02b8d6b233de420505dd4aa5f173f314d04cc24a2dc501744dfa3a62aab046ce2571ed3dba044cef5a1534ed33cf85fc4584357c52d9c50
+  metadata.gz: ec1fc0e96520b641f9d42d37fe88507f835c434304ea550b26b38544805ae318b5ccccd8fb3d4246ba798855af5a688e54ea865f20bcf2415dabed0bda46378e
+  data.tar.gz: f41066e6683556f6d09e17a4211b02d304880dad99104ea67b555a823af8d6adb9ff7f7ce526c9a18cc67602abab3e47408fc078fc624d15b9c105f1f9a73ca0

data/CHANGELOG.md

@@ -5,6 +5,25 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.7.0] - 2026-04-06
+
+### Added
+
+- **Wallet** — pluggable proof store for merkle proof persistence. The wallet is now a lightweight SPV node: `internalize_action` extracts and stores merkle proofs from incoming BEEF; `create_action` reattaches them to produce valid BEEF with BUMPs for ARC broadcast.
+  - `ProofStore` interface with `store_proof` / `resolve_proof`
+  - `LocalProofStore` default implementation using `StorageAdapter`
+  - `WalletClient` accepts injectable `proof_store:` parameter
+  - Transaction caching (`store_transaction` / `find_transaction`) for ancestry reconstruction
+- **Wallet** — `StorageAdapter` gains `store_proof`, `find_proof`, `store_transaction`, `find_transaction` methods, implemented in both `MemoryStore` and `FileStore`.
+
+### Changed
+
+- **Transaction** — `Beef#to_binary` now defaults to BEEF V1 (BRC-62) format, matching the TS reference SDK's `Transaction#toBEEF()`. ARC's parser does not support V2. Pass `version: BEEF_V2` for BRC-96 format. Atomic BEEF (BRC-95) inner envelope remains V2 per spec.
+
+### Fixed
+
+- **Wallet** — `wire_source_from_storage` resolves merkle proofs via proof store so `to_beef` produces valid BEEF that ARC accepts. Previously, BEEF contained source transactions without proofs, causing ARC 463/468 rejections.
+
 ## [0.6.2] - 2026-04-06
 
 ### Added

data/lib/bsv/transaction/beef.rb

@@ -152,35 +152,30 @@ module BSV
         from_binary([hex].pack('H*'))
       end
 
-      # --- Serialisation (always V2) ---
+      # --- Serialisation ---
 
-      # Serialise the BEEF bundle to V2 (BRC-96) binary format.
+      # Serialise the BEEF bundle to binary format.
       #
+      # Defaults to V1 (BRC-62) for compatibility with ARC and the
+      # reference TS SDK. Pass +version: BEEF_V2+ for BRC-96 format.
+      #
+      # @param version [Integer] BEEF_V1 (default) or BEEF_V2
       # @return [String] raw BEEF binary
-      def to_binary
+      def to_binary(version: BEEF_V1)
         bump_map = build_bump_map
         bumps_to_write = bump_map.values.sort_by { |entry| entry[:index] }.map { |entry| entry[:bump] }
 
-        buf = [BEEF_V2].pack('V')
+        buf = [version].pack('V')
 
         buf << VarInt.encode(bumps_to_write.length)
         bumps_to_write.each { |bump| buf << bump.to_binary }
 
         buf << VarInt.encode(@transactions.length)
         @transactions.each do |beef_tx|
-          case beef_tx.format
-          when FORMAT_TXID_ONLY
-            buf << [FORMAT_TXID_ONLY].pack('C')
-            buf << beef_tx.known_txid
-          when FORMAT_RAW_TX_AND_BUMP
-            buf << [FORMAT_RAW_TX_AND_BUMP].pack('C')
-            mp = beef_tx.transaction.merkle_path
-            idx = bump_map[mp][:index]
-            buf << VarInt.encode(idx)
-            buf << beef_tx.transaction.to_binary
+          if version == BEEF_V2
+            write_v2_tx(buf, beef_tx, bump_map)
           else
-            buf << [FORMAT_RAW_TX].pack('C')
-            buf << beef_tx.transaction.to_binary
+            write_v1_tx(buf, beef_tx, bump_map)
           end
         end
 
@@ -203,7 +198,8 @@ module BSV
         # Write subject txid in internal byte order (reverse of display order),
         # matching JS and Go SDK conventions for Bitcoin binary formats.
         buf << subject_txid.b.reverse
-        buf << to_binary
+        # BRC-95: inner envelope is always V2
+        buf << to_binary(version: BEEF_V2)
         buf
       end
 
@@ -606,6 +602,37 @@ module BSV
         end
       end
 
+      # V1 (BRC-62): raw_tx + has_bump(byte) [+ bump_index(varint)]
+      def write_v1_tx(buf, beef_tx, bump_map)
+        buf << beef_tx.transaction.to_binary
+        if beef_tx.format == FORMAT_RAW_TX_AND_BUMP
+          mp = beef_tx.transaction.merkle_path
+          idx = bump_map[mp][:index]
+          buf << [1].pack('C')
+          buf << VarInt.encode(idx)
+        else
+          buf << [0].pack('C')
+        end
+      end
+
+      # V2 (BRC-96): format_byte [+ bump_index(varint)] + raw_tx
+      def write_v2_tx(buf, beef_tx, bump_map)
+        case beef_tx.format
+        when FORMAT_TXID_ONLY
+          buf << [FORMAT_TXID_ONLY].pack('C')
+          buf << beef_tx.known_txid
+        when FORMAT_RAW_TX_AND_BUMP
+          buf << [FORMAT_RAW_TX_AND_BUMP].pack('C')
+          mp = beef_tx.transaction.merkle_path
+          idx = bump_map[mp][:index]
+          buf << VarInt.encode(idx)
+          buf << beef_tx.transaction.to_binary
+        else
+          buf << [FORMAT_RAW_TX].pack('C')
+          buf << beef_tx.transaction.to_binary
+        end
+      end
+
       def build_bump_map
         map = {}.compare_by_identity
         idx = 0

data/lib/bsv/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module BSV
-  VERSION = '0.6.2'
+  VERSION = '0.7.0'
 end

data/lib/bsv/wallet_interface/file_store.rb

@@ -72,8 +72,26 @@ module BSV
         result
       end
 
+      def store_proof(txid, bump_hex)
+        super
+        save_proofs
+      end
+
+      def store_transaction(txid, tx_hex)
+        super
+        save_transactions
+      end
+
       private
 
+      def proofs_path
+        File.join(@dir, 'proofs.json')
+      end
+
+      def transactions_path
+        File.join(@dir, 'transactions.json')
+      end
+
       def check_permissions
         dir_mode = File.stat(@dir).mode & 0o777
         if dir_mode != 0o700
@@ -81,7 +99,7 @@ module BSV
                        'Other users may be able to access wallet data.')
         end
 
-        [actions_path, outputs_path, certificates_path].each do |path|
+        [actions_path, outputs_path, certificates_path, proofs_path, transactions_path].each do |path|
           next unless File.exist?(path)
 
           file_mode = File.stat(path).mode & 0o777
@@ -108,6 +126,8 @@ module BSV
         @actions = load_file(actions_path)
         @outputs = load_file(outputs_path)
         @certificates = load_file(certificates_path)
+        @proofs = load_proofs_file
+        @transactions = load_transactions_file
       end
 
       def load_file(path)
@@ -134,6 +154,38 @@ module BSV
         write_file(certificates_path, @certificates)
       end
 
+      def save_proofs
+        json = JSON.pretty_generate(@proofs)
+        tmp = "#{proofs_path}.tmp"
+        File.open(tmp, File::WRONLY | File::CREAT | File::TRUNC, 0o600) { |f| f.write(json) }
+        File.rename(tmp, proofs_path)
+      end
+
+      def load_proofs_file
+        return {} unless File.exist?(proofs_path)
+
+        data = JSON.parse(File.read(proofs_path))
+        data.is_a?(Hash) ? data : {}
+      rescue JSON::ParserError
+        {}
+      end
+
+      def save_transactions
+        json = JSON.pretty_generate(@transactions)
+        tmp = "#{transactions_path}.tmp"
+        File.open(tmp, File::WRONLY | File::CREAT | File::TRUNC, 0o600) { |f| f.write(json) }
+        File.rename(tmp, transactions_path)
+      end
+
+      def load_transactions_file
+        return {} unless File.exist?(transactions_path)
+
+        data = JSON.parse(File.read(transactions_path))
+        data.is_a?(Hash) ? data : {}
+      rescue JSON::ParserError
+        {}
+      end
+
       def write_file(path, data)
         json = JSON.pretty_generate(stringify_keys_deep(data))
         tmp = "#{path}.tmp"

data/lib/bsv/wallet_interface/local_proof_store.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module BSV
+  module Wallet
+    # Default proof store — persists serialised merkle proofs via a
+    # {StorageAdapter}. Requires no external services.
+    #
+    # @example Using the default local proof store
+    #   store   = BSV::Wallet::MemoryStore.new
+    #   proofs  = BSV::Wallet::LocalProofStore.new(store)
+    #   proofs.store_proof(txid_hex, merkle_path)
+    #   proof   = proofs.resolve_proof(txid_hex)
+    class LocalProofStore
+      include ProofStore
+
+      # @param storage [StorageAdapter] the underlying persistence adapter
+      def initialize(storage)
+        @storage = storage
+      end
+
+      # Serialise and store a merkle proof.
+      #
+      # @param txid [String] hex transaction ID
+      # @param merkle_path [BSV::Transaction::MerklePath] the proof to store
+      # @return [void]
+      def store_proof(txid, merkle_path)
+        @storage.store_proof(txid, merkle_path.to_hex)
+      end
+
+      # Resolve and deserialise a merkle proof.
+      #
+      # @param txid [String] hex transaction ID
+      # @return [BSV::Transaction::MerklePath, nil] the proof, or nil if unknown
+      def resolve_proof(txid)
+        bump_hex = @storage.find_proof(txid)
+        return unless bump_hex
+
+        BSV::Transaction::MerklePath.from_hex(bump_hex)
+      end
+    end
+  end
+end

data/lib/bsv/wallet_interface/memory_store.rb

@@ -13,6 +13,8 @@ module BSV
         @actions = []
         @outputs = []
         @certificates = []
+        @proofs = {}
+        @transactions = {}
       end
 
       def store_action(action_data)
@@ -62,6 +64,22 @@ module BSV
         filter_certificates(query).length
       end
 
+      def store_proof(txid, bump_hex)
+        @proofs[txid] = bump_hex
+      end
+
+      def find_proof(txid)
+        @proofs[txid]
+      end
+
+      def store_transaction(txid, tx_hex)
+        @transactions[txid] = tx_hex
+      end
+
+      def find_transaction(txid)
+        @transactions[txid]
+      end
+
       def delete_certificate(type:, serial_number:, certifier:)
         idx = @certificates.index do |c|
           c[:type] == type && c[:serial_number] == serial_number && c[:certifier] == certifier

data/lib/bsv/wallet_interface/proof_store.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module BSV
+  module Wallet
+    # Duck-typed interface for merkle proof persistence.
+    #
+    # Include this module in proof store implementations and override all
+    # methods. The default implementations raise NotImplementedError.
+    #
+    # Two implementations ship with the SDK:
+    # - {LocalProofStore} — persists proofs via a {StorageAdapter} (default)
+    # - Future: ChaintracksProofStore — resolves proofs from an external service
+    module ProofStore
+      # Store a merkle proof for a transaction.
+      #
+      # @param _txid [String] hex transaction ID
+      # @param _merkle_path [BSV::Transaction::MerklePath] the proof to store
+      # @return [void]
+      def store_proof(_txid, _merkle_path)
+        raise NotImplementedError, "#{self.class}#store_proof not implemented"
+      end
+
+      # Resolve a merkle proof for a transaction.
+      #
+      # @param _txid [String] hex transaction ID
+      # @return [BSV::Transaction::MerklePath, nil] the proof, or nil if unknown
+      def resolve_proof(_txid)
+        raise NotImplementedError, "#{self.class}#resolve_proof not implemented"
+      end
+    end
+  end
+end

data/lib/bsv/wallet_interface/storage_adapter.rb

@@ -50,6 +50,22 @@ module BSV
       def count_certificates(_query)
         raise NotImplementedError, "#{self.class}#count_certificates not implemented"
       end
+
+      def store_proof(_txid, _bump_hex)
+        raise NotImplementedError, "#{self.class}#store_proof not implemented"
+      end
+
+      def find_proof(_txid)
+        raise NotImplementedError, "#{self.class}#find_proof not implemented"
+      end
+
+      def store_transaction(_txid, _tx_hex)
+        raise NotImplementedError, "#{self.class}#store_transaction not implemented"
+      end
+
+      def find_transaction(_txid)
+        raise NotImplementedError, "#{self.class}#find_transaction not implemented"
+      end
     end
   end
 end

data/lib/bsv/wallet_interface/version.rb

@@ -2,6 +2,6 @@
 
 module BSV
   module WalletInterface
-    VERSION = '0.2.0'
+    VERSION = '0.3.0'
   end
 end

data/lib/bsv/wallet_interface/wallet_client.rb

@@ -35,17 +35,22 @@ module BSV
       # @return [String] the network ('mainnet' or 'testnet')
       attr_reader :network
 
+      # @return [ProofStore] the merkle proof persistence store
+      attr_reader :proof_store
+
       # @param key [BSV::Primitives::PrivateKey, String, KeyDeriver] signing key
       # @param storage [StorageAdapter] persistence adapter (default: FileStore).
       #   Use +storage: MemoryStore.new+ for tests.
       # @param network [String] 'mainnet' (default) or 'testnet'
       # @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
-      def initialize(key, storage: FileStore.new, network: 'mainnet', chain_provider: NullChainProvider.new, http_client: nil)
+      def initialize(key, storage: FileStore.new, network: 'mainnet', chain_provider: NullChainProvider.new, proof_store: nil, http_client: nil)
         super(key)
         @storage = storage
         @network = network
         @chain_provider = chain_provider
+        @proof_store = proof_store || LocalProofStore.new(storage)
         @http_client = http_client
         @pending = {}
       end
@@ -177,6 +182,7 @@ module BSV
         beef = BSV::Transaction::Beef.from_binary(beef_binary)
         tx = extract_subject_transaction(beef)
 
+        store_proofs_from_beef(beef)
         process_internalize_outputs(tx, args[:outputs])
         store_action(tx, args, status: 'completed')
         { accepted: true }
@@ -520,6 +526,35 @@ module BSV
 
         input.source_satoshis = stored[:satoshis]
         input.source_locking_script = BSV::Script::Script.from_hex(stored[:locking_script])
+
+        return unless stored[:source_tx_hex]
+
+        source_tx = BSV::Transaction::Transaction.from_hex(stored[:source_tx_hex])
+        txid_hex = outpoint.split('.').first
+        proof = @proof_store.resolve_proof(txid_hex)
+        source_tx.merkle_path = proof if proof
+
+        # Recursively wire ancestors of the source tx so to_beef can build a
+        # complete, valid BEEF with the full proof chain.
+        wire_source_tx_ancestors(source_tx) unless source_tx.merkle_path
+
+        input.source_transaction = source_tx
+      end
+
+      def wire_source_tx_ancestors(tx)
+        tx.inputs.each do |inp|
+          next if inp.source_transaction
+
+          ancestor_txid_hex = inp.prev_tx_id.reverse.unpack1('H*')
+          tx_hex = @storage.find_transaction(ancestor_txid_hex)
+          next unless tx_hex
+
+          ancestor_tx = BSV::Transaction::Transaction.from_hex(tx_hex)
+          proof = @proof_store.resolve_proof(ancestor_txid_hex)
+          ancestor_tx.merkle_path = proof if proof
+          wire_source_tx_ancestors(ancestor_tx) unless ancestor_tx.merkle_path
+          inp.source_transaction = ancestor_tx
+        end
       end
 
       def build_outputs(tx, outputs)
@@ -601,6 +636,8 @@ module BSV
       def store_tracked_outputs(txid, tx, output_specs)
         return unless output_specs
 
+        tx_hex = tx.to_hex
+
         output_specs.each do |spec|
           next unless spec[:basket]
 
@@ -617,7 +654,8 @@ module BSV
                                   basket: spec[:basket],
                                   tags: spec[:tags] || [],
                                   custom_instructions: spec[:custom_instructions],
-                                  spendable: true
+                                  spendable: true,
+                                  source_tx_hex: tx_hex
                                 })
         end
       end
@@ -644,6 +682,16 @@ module BSV
 
       # --- Internalize helpers ---
 
+      def store_proofs_from_beef(beef)
+        beef.transactions.each do |beef_tx|
+          next unless beef_tx.transaction&.merkle_path
+
+          txid_hex = beef_tx.transaction.txid_hex
+          @proof_store.store_proof(txid_hex, beef_tx.transaction.merkle_path)
+          @storage.store_transaction(txid_hex, beef_tx.transaction.to_hex)
+        end
+      end
+
       def extract_subject_transaction(beef)
         return find_by_subject_txid(beef) if beef.subject_txid
 
@@ -660,6 +708,7 @@ module BSV
 
       def process_internalize_outputs(tx, output_specs)
         txid = tx.txid_hex
+        tx_hex = tx.to_hex
 
         output_specs.each do |spec|
           output_index = spec[:output_index]
@@ -668,16 +717,16 @@ module BSV
 
           case spec[:protocol]
           when 'wallet payment'
-            internalize_payment(txid, output_index, tx_output, spec[:payment_remittance])
+            internalize_payment(txid, output_index, tx_output, spec[:payment_remittance], tx_hex)
           when 'basket insertion'
-            internalize_basket(txid, output_index, tx_output, spec[:insertion_remittance])
+            internalize_basket(txid, output_index, tx_output, spec[:insertion_remittance], tx_hex)
           else
             raise InvalidParameterError.new('protocol', '"wallet payment" or "basket insertion"')
           end
         end
       end
 
-      def internalize_payment(txid, output_index, tx_output, remittance)
+      def internalize_payment(txid, output_index, tx_output, remittance, tx_hex = nil)
         unless remittance
           raise InvalidParameterError.new('payment_remittance',
                                           'present for wallet payment protocol')
@@ -705,11 +754,12 @@ module BSV
                                 spendable: true,
                                 sender_identity_key: sender_key,
                                 derivation_prefix: prefix,
-                                derivation_suffix: suffix
+                                derivation_suffix: suffix,
+                                source_tx_hex: tx_hex
                               })
       end
 
-      def internalize_basket(txid, output_index, tx_output, remittance)
+      def internalize_basket(txid, output_index, tx_output, remittance, tx_hex = nil)
         unless remittance
           raise InvalidParameterError.new('insertion_remittance',
                                           'present for basket insertion protocol')
@@ -724,7 +774,8 @@ module BSV
                                 basket: remittance[:basket],
                                 tags: remittance[:tags] || [],
                                 custom_instructions: remittance[:custom_instructions],
-                                spendable: true
+                                spendable: true,
+                                source_tx_hex: tx_hex
                               })
       end
 

data/lib/bsv/wallet_interface.rb

@@ -14,6 +14,8 @@ module BSV
     autoload :StorageAdapter,    'bsv/wallet_interface/storage_adapter'
     autoload :MemoryStore,       'bsv/wallet_interface/memory_store'
     autoload :FileStore,         'bsv/wallet_interface/file_store'
+    autoload :ProofStore,        'bsv/wallet_interface/proof_store'
+    autoload :LocalProofStore,   'bsv/wallet_interface/local_proof_store'
     autoload :ChainProvider,     'bsv/wallet_interface/chain_provider'
     autoload :NullChainProvider, 'bsv/wallet_interface/null_chain_provider'
     autoload :WalletClient,      'bsv/wallet_interface/wallet_client'

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: bsv-sdk
 version: !ruby/object:Gem::Version
-  version: 0.6.2
+  version: 0.7.0
 platform: ruby
 authors:
 - Simon Bettison
 bindir: bin
 cert_chain: []
-date: 2026-04-05 00:00:00.000000000 Z
+date: 2026-04-06 00:00:00.000000000 Z
 dependencies: []
 description: A Ruby library for interacting with the BSV Blockchain — keys, scripts,
   transactions, and more.
@@ -130,8 +130,10 @@ files:
 - lib/bsv/wallet_interface/file_store.rb
 - lib/bsv/wallet_interface/interface.rb
 - lib/bsv/wallet_interface/key_deriver.rb
+- lib/bsv/wallet_interface/local_proof_store.rb
 - lib/bsv/wallet_interface/memory_store.rb
 - lib/bsv/wallet_interface/null_chain_provider.rb
+- lib/bsv/wallet_interface/proof_store.rb
 - lib/bsv/wallet_interface/proto_wallet.rb
 - lib/bsv/wallet_interface/storage_adapter.rb
 - lib/bsv/wallet_interface/validators.rb