bsv-sdk 0.17.0 → 0.18.1

data/lib/bsv/transaction/beef.rb

@@ -36,60 +36,119 @@ module BSV
 
       # @!endgroup
 
-      # A single entry in a BEEF bundle, wrapping a transaction with its format metadata.
+      # Abstract base class for a single entry in a BEEF bundle.
+      #
+      # Subclasses represent the three wire formats:
+      # - {RawTxEntry}    — raw transaction without a merkle proof
+      # - {ProvenTxEntry} — raw transaction with an associated BUMP index
+      # - {TxidOnlyEntry} — transaction ID only (no raw data)
+      #
+      # @abstract Subclass and implement {#wtxid} and {#format_flag}.
       class BeefTx
-        # @return [Integer] format flag (FORMAT_RAW_TX, FORMAT_RAW_TX_AND_BUMP, or FORMAT_TXID_ONLY)
-        attr_reader :format
+        def initialize; end
+
+        # Wire-order transaction ID.
+        # @return [String, nil] 32-byte wtxid
+        # @abstract
+        def wtxid
+          raise NotImplementedError, "#{self.class}#wtxid is not implemented"
+        end
 
-        # @return [Transaction, nil] the transaction (nil for TXID-only entries)
+        # Display-order transaction ID as a hex string.
+        #
+        # +dtxid+ always returns a 64-char hex string suitable for JSON
+        # and UI boundaries.
+        #
+        # @return [String, nil] hex-encoded transaction ID (display order)
+        def dtxid
+          wtxid&.reverse&.unpack1('H*')
+        end
+
+        # Wire-protocol format integer for serialisation.
+        # @return [Integer]
+        # @abstract
+        def format_flag
+          raise NotImplementedError, "#{self.class}#format_flag is not implemented"
+        end
+      end
+
+      # A BEEF entry containing a raw transaction without a merkle proof.
+      class RawTxEntry < BeefTx
+        # @return [Transaction] the transaction
         attr_reader :transaction
 
-        # @return [String, nil] 32-byte wire-order wtxid for TXID-only entries
-        attr_reader :known_wtxid
+        # @param transaction [Transaction] the transaction
+        # @raise [ArgumentError] if transaction is nil
+        def initialize(transaction:)
+          raise ArgumentError, 'RawTxEntry requires a transaction' if transaction.nil?
+
+          super()
+          @transaction = transaction
+        end
 
-        # @return [Integer, nil] index into the BEEF bumps array
+        # @return [String] wire-order wtxid delegated to the transaction
+        def wtxid
+          @transaction.wtxid
+        end
+
+        # @return [Integer] FORMAT_RAW_TX wire-protocol flag
+        def format_flag
+          FORMAT_RAW_TX
+        end
+      end
+
+      # A BEEF entry containing a raw transaction with an associated BUMP index.
+      class ProvenTxEntry < BeefTx
+        # @return [Transaction] the transaction
+        attr_reader :transaction
+
+        # @return [Integer] index into the BEEF bumps array
         attr_reader :bump_index
 
-        # @param format [Integer] format flag
-        # @param transaction [Transaction, nil] the transaction
-        # @param known_wtxid [String, nil] 32-byte wire-order wtxid for TXID-only entries
-        # @param bump_index [Integer, nil] index into the bumps array
-        # @raise [ArgumentError] if format is FORMAT_RAW_TX_AND_BUMP without a bump_index
-        def initialize(format:, transaction: nil, known_wtxid: nil, bump_index: nil)
-          raise ArgumentError, 'FORMAT_RAW_TX_AND_BUMP requires a bump_index' if format == FORMAT_RAW_TX_AND_BUMP && bump_index.nil?
+        # @param transaction [Transaction] the transaction
+        # @param bump_index [Integer] index into the bumps array
+        # @raise [ArgumentError] if transaction or bump_index is nil
+        def initialize(transaction:, bump_index:)
+          raise ArgumentError, 'ProvenTxEntry requires a transaction' if transaction.nil?
+          raise ArgumentError, 'ProvenTxEntry requires a bump_index' if bump_index.nil?
 
-          BSV::Primitives::Hex.validate_wtxid!(known_wtxid, name: 'known_wtxid') if known_wtxid
-          @format = format
+          super()
           @transaction = transaction
-          @known_wtxid = known_wtxid
           @bump_index = bump_index
         end
 
-        # Wire-order transaction ID.
-        # @return [String, nil] 32-byte wtxid
+        # @return [String] wire-order wtxid delegated to the transaction
         def wtxid
-          case @format
-          when FORMAT_TXID_ONLY
-            @known_wtxid
-          else
-            @transaction&.wtxid
-          end
+          @transaction.wtxid
         end
 
-        # Display-order transaction ID as binary bytes.
-        # @return [String, nil] 32-byte display-order txid
-        def txid
-          wtxid&.reverse
+        # @return [Integer] FORMAT_RAW_TX_AND_BUMP wire-protocol flag
+        def format_flag
+          FORMAT_RAW_TX_AND_BUMP
         end
+      end
 
-        # Display-order transaction ID as a hex string.
-        #
-        # +dtxid+ always returns a 64-char hex string suitable for JSON
-        # and UI boundaries.
-        #
-        # @return [String, nil] hex-encoded transaction ID (display order)
-        def dtxid
-          wtxid&.reverse&.unpack1('H*')
+      # A BEEF entry containing only a transaction ID (no raw data).
+      class TxidOnlyEntry < BeefTx
+        # @return [String] 32-byte wire-order wtxid
+        attr_reader :known_wtxid
+
+        # @param known_wtxid [String] 32-byte wire-order wtxid
+        # @raise [ArgumentError] if known_wtxid is invalid
+        def initialize(known_wtxid:)
+          BSV::Primitives::Hex.validate_wtxid!(known_wtxid, name: 'known_wtxid')
+          super()
+          @known_wtxid = known_wtxid
+        end
+
+        # @return [String] the stored wire-order wtxid
+        def wtxid
+          @known_wtxid
+        end
+
+        # @return [Integer] FORMAT_TXID_ONLY wire-protocol flag
+        def format_flag
+          FORMAT_TXID_ONLY
         end
       end
 
@@ -105,12 +164,6 @@ module BSV
       # @return [String, nil] 32-byte wire-order subject txid (Atomic BEEF only)
       attr_reader :subject_wtxid
 
-      # Display-order subject txid as binary bytes (Atomic BEEF only).
-      # @return [String, nil] 32-byte display-order txid, or nil
-      def subject_txid
-        @subject_wtxid&.reverse
-      end
-
       # Display-order subject txid as a hex string (Atomic BEEF only).
       #
       # @return [String, nil] hex-encoded display-order txid, or nil
@@ -214,7 +267,7 @@ module BSV
       #   any FORMAT_TXID_ONLY entries (V1 / BRC-62 has no TXID-only format;
       #   pass +version: BEEF_V2+ to serialise such bundles)
       def to_binary(version: BEEF_V1)
-        if version == BEEF_V1 && @transactions.any? { |bt| bt.format == FORMAT_TXID_ONLY }
+        if version == BEEF_V1 && @transactions.any?(TxidOnlyEntry)
           raise ArgumentError,
                 'BEEF V1 (BRC-62) does not support FORMAT_TXID_ONLY entries; pass version: BEEF_V2 to serialise this bundle'
         end
@@ -274,6 +327,7 @@ module BSV
         BSV::Primitives::Hex.validate_wtxid!(wtxid, name: 'wtxid')
         BSV.logger&.debug { "[Beef] find_transaction: #{wtxid.reverse.unpack1('H*')} in #{@transactions.length} entries" }
         @transactions.each do |beef_tx|
+          next if beef_tx.is_a?(TxidOnlyEntry)
           return beef_tx.transaction if beef_tx.wtxid == wtxid
         end
         nil
@@ -289,8 +343,8 @@ module BSV
       def find_bump(wtxid)
         BSV::Primitives::Hex.validate_wtxid!(wtxid, name: 'wtxid')
         # Check transaction-table entries first (fast path)
-        bt = @transactions.find { |entry| entry.wtxid == wtxid && entry.format == FORMAT_RAW_TX_AND_BUMP }
-        return bt.transaction&.merkle_path || (bt.bump_index && @bumps[bt.bump_index]) if bt
+        bt = @transactions.find { |entry| entry.wtxid == wtxid && entry.is_a?(ProvenTxEntry) }
+        return bt.transaction.merkle_path || @bumps[bt.bump_index] if bt
 
         # F5.8: also scan @bumps directly for a path containing the wtxid leaf
         @bumps.find do |bump|
@@ -371,15 +425,11 @@ module BSV
         level0_leaves = bump.path[0] || []
         level0_internal = level0_leaves.map(&:hash).compact.to_set
         @transactions.each_with_index do |bt, i|
-          next unless bt.format == FORMAT_RAW_TX && bt.transaction
-          next unless level0_internal.include?(bt.transaction.wtxid)
+          next unless bt.is_a?(RawTxEntry)
+          next unless level0_internal.include?(bt.wtxid)
 
           bt.transaction.merkle_path ||= bump
-          @transactions[i] = BeefTx.new(
-            format: FORMAT_RAW_TX_AND_BUMP,
-            transaction: bt.transaction,
-            bump_index: idx
-          )
+          @transactions[i] = ProvenTxEntry.new(transaction: bt.transaction, bump_index: idx)
         end
 
         idx
@@ -414,9 +464,9 @@ module BSV
         # Merge this transaction's BUMP if it has one
         entry = if tx.merkle_path
                   bump_idx = merge_bump(tx.merkle_path)
-                  BeefTx.new(format: FORMAT_RAW_TX_AND_BUMP, transaction: tx, bump_index: bump_idx)
+                  ProvenTxEntry.new(transaction: tx, bump_index: bump_idx)
                 else
-                  BeefTx.new(format: FORMAT_RAW_TX, transaction: tx)
+                  RawTxEntry.new(transaction: tx)
                 end
         @transactions << entry
         entry
@@ -451,9 +501,9 @@ module BSV
         end
 
         entry = if bump_index
-                  BeefTx.new(format: FORMAT_RAW_TX_AND_BUMP, transaction: tx, bump_index: bump_index)
+                  ProvenTxEntry.new(transaction: tx, bump_index: bump_index)
                 else
-                  BeefTx.new(format: FORMAT_RAW_TX, transaction: tx)
+                  RawTxEntry.new(transaction: tx)
                 end
         @transactions << entry
         entry
@@ -479,15 +529,15 @@ module BSV
         # Merge transactions with remapped BUMP indices, constructing new
         # BeefTx instances rather than sharing source references (F5.9).
         other.transactions.each do |beef_tx|
-          case beef_tx.format
-          when FORMAT_TXID_ONLY
+          case beef_tx
+          when TxidOnlyEntry
             next if @transactions.any? { |bt| bt.wtxid == beef_tx.known_wtxid }
 
-            @transactions << BeefTx.new(format: FORMAT_TXID_ONLY, known_wtxid: beef_tx.known_wtxid)
+            @transactions << TxidOnlyEntry.new(known_wtxid: beef_tx.known_wtxid)
           else
             next if @transactions.any? { |bt| bt.wtxid == beef_tx.wtxid }
 
-            if beef_tx.format == FORMAT_RAW_TX_AND_BUMP && beef_tx.bump_index
+            if beef_tx.is_a?(ProvenTxEntry) && beef_tx.bump_index
               new_idx = bump_remap[beef_tx.bump_index]
               if new_idx.nil?
                 raise ArgumentError,
@@ -499,13 +549,9 @@ module BSV
               # so mutations to the merged bundle don't affect the source.
               tx = beef_tx.transaction.dup
               tx.merkle_path = @bumps[new_idx]
-              @transactions << BeefTx.new(
-                format: FORMAT_RAW_TX_AND_BUMP,
-                transaction: tx,
-                bump_index: new_idx
-              )
+              @transactions << ProvenTxEntry.new(transaction: tx, bump_index: new_idx)
             else
-              @transactions << BeefTx.new(format: FORMAT_RAW_TX, transaction: beef_tx.transaction.dup)
+              @transactions << RawTxEntry.new(transaction: beef_tx.transaction.dup)
             end
           end
         end
@@ -522,7 +568,7 @@ module BSV
         idx = @transactions.index { |bt| bt.wtxid == wtxid }
         return unless idx
 
-        @transactions[idx] = BeefTx.new(format: FORMAT_TXID_ONLY, known_wtxid: wtxid)
+        @transactions[idx] = TxidOnlyEntry.new(known_wtxid: wtxid)
       end
 
       # --- Validation ---
@@ -541,20 +587,20 @@ module BSV
       # @return [Boolean] true if structurally valid
       def valid?(allow_txid_only: false)
         # TXID-only entries are invalid unless explicitly allowed
-        has_txid_only = @transactions.any? { |bt| bt.format == FORMAT_TXID_ONLY }
+        has_txid_only = @transactions.any?(TxidOnlyEntry)
         return false if has_txid_only && !allow_txid_only
 
         # F5.4: verify BUMP linkage and computed root for each proven transaction
         @transactions.each do |bt|
-          next unless bt.format == FORMAT_RAW_TX_AND_BUMP
+          next unless bt.is_a?(ProvenTxEntry)
 
           # Must have a BUMP
-          bump = bt.transaction&.merkle_path || (bt.bump_index && @bumps[bt.bump_index])
+          bump = bt.transaction.merkle_path || @bumps[bt.bump_index]
           return false unless bump
 
           # The txid must appear as a leaf in the BUMP and compute a valid root
           begin
-            bump.compute_root(bt.transaction.wtxid)
+            bump.compute_root(bt.wtxid)
           rescue ArgumentError
             return false
           end
@@ -562,7 +608,7 @@ module BSV
 
         known_wtxids = build_known_wtxids(allow_txid_only)
 
-        pending = @transactions.select { |bt| bt.transaction && !known_wtxids.include?(bt.wtxid) }
+        pending = @transactions.reject { |bt| bt.is_a?(TxidOnlyEntry) || known_wtxids.include?(bt.wtxid) }
 
         # Iteratively resolve: if all inputs of a tx are known, it becomes known
         changed = true
@@ -626,7 +672,7 @@ module BSV
         dependents = Array.new(@transactions.length) { [] }
 
         @transactions.each_with_index do |bt, i|
-          next unless bt.transaction
+          next if bt.is_a?(TxidOnlyEntry)
 
           bt.transaction.inputs.each do |input|
             dep_idx = wtxid_index[input.prev_wtxid]
@@ -701,20 +747,18 @@ module BSV
 
               known_wtxid = data.byteslice(offset, 32)
               offset += 32
-              beef.transactions << BeefTx.new(format: FORMAT_TXID_ONLY, known_wtxid: known_wtxid)
+              beef.transactions << TxidOnlyEntry.new(known_wtxid: known_wtxid)
             when FORMAT_RAW_TX_AND_BUMP
               bump_index, vi_size = VarInt.decode(data, offset)
               offset += vi_size
               tx, consumed = Transaction.from_binary_with_offset(data, offset)
               offset += consumed
               tx.merkle_path = beef.bumps[bump_index] if bump_index < beef.bumps.length
-              beef.transactions << BeefTx.new(
-                format: FORMAT_RAW_TX_AND_BUMP, transaction: tx, bump_index: bump_index
-              )
+              beef.transactions << ProvenTxEntry.new(transaction: tx, bump_index: bump_index)
             when FORMAT_RAW_TX
               tx, consumed = Transaction.from_binary_with_offset(data, offset)
               offset += consumed
-              beef.transactions << BeefTx.new(format: FORMAT_RAW_TX, transaction: tx)
+              beef.transactions << RawTxEntry.new(transaction: tx)
             end
           end
 
@@ -733,14 +777,12 @@ module BSV
             offset += 1
 
             if has_bump.zero?
-              beef.transactions << BeefTx.new(format: FORMAT_RAW_TX, transaction: tx)
+              beef.transactions << RawTxEntry.new(transaction: tx)
             else
               bump_index, vi_size = VarInt.decode(data, offset)
               offset += vi_size
               tx.merkle_path = beef.bumps[bump_index] if bump_index < beef.bumps.length
-              beef.transactions << BeefTx.new(
-                format: FORMAT_RAW_TX_AND_BUMP, transaction: tx, bump_index: bump_index
-              )
+              beef.transactions << ProvenTxEntry.new(transaction: tx, bump_index: bump_index)
             end
           end
 
@@ -750,7 +792,7 @@ module BSV
         def wire_source_transactions(beef)
           tx_map = {}
           beef.transactions.each do |beef_tx|
-            next unless beef_tx.transaction
+            next if beef_tx.is_a?(TxidOnlyEntry)
 
             # Wire inputs to ancestors already in the map (BEEF is dependency-ordered).
             # Both prev_wtxid and wtxid are wire-order — no conversion needed.
@@ -765,7 +807,7 @@ module BSV
               end
             end
 
-            tx_map[beef_tx.transaction.wtxid] = beef_tx.transaction
+            tx_map[beef_tx.wtxid] = beef_tx.transaction
           end
         end
       end
@@ -790,33 +832,28 @@ module BSV
         effective_bump_idx = bump_index
         effective_bump_idx = merge_bump(tx.merkle_path) if effective_bump_idx.nil? && tx&.merkle_path
 
-        case existing.format
-        when FORMAT_TXID_ONLY
+        case existing
+        when TxidOnlyEntry
           if effective_bump_idx
-            BeefTx.new(format: FORMAT_RAW_TX_AND_BUMP, transaction: tx, bump_index: effective_bump_idx)
+            ProvenTxEntry.new(transaction: tx, bump_index: effective_bump_idx)
           elsif tx
-            BeefTx.new(format: FORMAT_RAW_TX, transaction: tx)
+            RawTxEntry.new(transaction: tx)
           end
-        when FORMAT_RAW_TX
+        when RawTxEntry
           if effective_bump_idx
             tx_to_use = tx || existing.transaction
             tx_to_use.merkle_path ||= @bumps[effective_bump_idx]
-            BeefTx.new(format: FORMAT_RAW_TX_AND_BUMP, transaction: tx_to_use, bump_index: effective_bump_idx)
+            ProvenTxEntry.new(transaction: tx_to_use, bump_index: effective_bump_idx)
           end
         end
-        # FORMAT_RAW_TX_AND_BUMP is already the strongest — no upgrade needed
+        # ProvenTxEntry is already the strongest — no upgrade needed
       end
 
       # Build a set of wire-order wtxids that are "known" (proven or txid-only).
       def build_known_wtxids(allow_txid_only)
         known = Set.new
         @transactions.each do |bt|
-          case bt.format
-          when FORMAT_RAW_TX_AND_BUMP
-            known.add(bt.wtxid)
-          when FORMAT_TXID_ONLY
-            known.add(bt.wtxid) if allow_txid_only
-          end
+          known.add(bt.wtxid) if bt.is_a?(ProvenTxEntry) || (bt.is_a?(TxidOnlyEntry) && allow_txid_only)
         end
         known
       end
@@ -846,7 +883,7 @@ module BSV
       # V1 (BRC-62): raw_tx + has_bump(byte) [+ bump_index(varint)]
       def write_v1_tx(buf, beef_tx)
         buf << beef_tx.transaction.to_binary
-        if beef_tx.format == FORMAT_RAW_TX_AND_BUMP
+        if beef_tx.is_a?(ProvenTxEntry)
           buf << [1].pack('C')
           buf << VarInt.encode(beef_tx.bump_index)
         else
@@ -856,12 +893,12 @@ module BSV
 
       # V2 (BRC-96): format_byte [+ bump_index(varint)] + raw_tx
       def write_v2_tx(buf, beef_tx)
-        case beef_tx.format
-        when FORMAT_TXID_ONLY
+        case beef_tx
+        when TxidOnlyEntry
           buf << [FORMAT_TXID_ONLY].pack('C')
           # known_wtxid is already wire (internal) byte order.
           buf << beef_tx.known_wtxid
-        when FORMAT_RAW_TX_AND_BUMP
+        when ProvenTxEntry
           buf << [FORMAT_RAW_TX_AND_BUMP].pack('C')
           buf << VarInt.encode(beef_tx.bump_index)
           buf << beef_tx.transaction.to_binary

data/lib/bsv/transaction/transaction.rb

@@ -337,13 +337,12 @@ module BSV
 
         ancestors.each do |tx|
           entry = if tx.merkle_path
-                    Beef::BeefTx.new(
-                      format: Beef::FORMAT_RAW_TX_AND_BUMP,
+                    Beef::ProvenTxEntry.new(
                       transaction: tx,
                       bump_index: bump_index_by_height.fetch(tx.merkle_path.block_height)
                     )
                   else
-                    Beef::BeefTx.new(format: Beef::FORMAT_RAW_TX, transaction: tx)
+                    Beef::RawTxEntry.new(transaction: tx)
                   end
           beef.transactions << entry
         end
@@ -362,11 +361,11 @@ module BSV
       # full ancestry wired, including late-bound BUMP attachment.
       #
       # For Atomic BEEFs (BRC-95), the subject transaction is identified by
-      # the embedded subject_txid field. For plain BEEFs, the last transaction
-      # with a raw tx entry is used as the subject.
+      # the embedded +subject_wtxid+ field. For plain BEEFs, the last
+      # transaction with a raw tx entry is used as the subject.
       #
       # Uses +find_atomic_transaction+ so that FORMAT_RAW_TX ancestors whose
-      # txid appears as a leaf in a separately-stored BUMP get their
+      # wtxid appears as a leaf in a separately-stored BUMP get their
       # +merkle_path+ wired correctly — a gap not covered by the initial
       # +wire_source_transactions+ pass in +Beef.from_binary+.
       #
@@ -376,7 +375,7 @@ module BSV
       def self.from_beef(data)
         beef = Beef.from_binary(data)
         subject_wtxid = beef.subject_wtxid ||
-                        beef.transactions.reverse.find(&:transaction)&.transaction&.wtxid
+                        beef.transactions.reverse.find { |bt| !bt.is_a?(Beef::TxidOnlyEntry) }&.wtxid
         return nil unless subject_wtxid
 
         beef.find_atomic_transaction(subject_wtxid)
@@ -405,21 +404,11 @@ module BSV
         id
       end
 
-      # Display-order transaction ID (reversed from the natural SHA-256d hash).
-      #
-      # This is the conventional human-readable representation used in block
-      # explorers, wallets, and all user-facing contexts.
-      #
-      # @return [String] 32-byte transaction ID in display byte order
-      def txid
-        wtxid.reverse
-      end
-
       # The transaction ID as a hex string (display byte order).
       #
-      # @return [String] hex-encoded transaction ID
+      # @return [String] 64-char hex-encoded transaction ID (display order)
       def txid_hex
-        txid.unpack1('H*')
+        wtxid.reverse.unpack1('H*')
       end
 
       # Display-order transaction ID as a hex string.
@@ -450,6 +439,29 @@ module BSV
         raise ArgumentError, 'only SIGHASH_FORKID types are supported' unless sighash_type & Sighash::FORK_ID != 0
 
         input = @inputs[input_index]
+        raise ArgumentError, "no input at index #{input_index}" if input.nil?
+
+        # Resolve source data from wired source_transaction when not explicitly set.
+        if input.source_transaction
+          source_output = input.source_transaction.outputs[input.prev_tx_out_index]
+          if source_output
+            input.source_satoshis       ||= source_output.satoshis
+            input.source_locking_script ||= source_output.locking_script
+          end
+        end
+
+        if input.source_satoshis.nil?
+          raise ArgumentError,
+                "input #{input_index} has nil source_satoshis — " \
+                'set it or wire source_transaction before computing sighash'
+        end
+
+        unless subscript || input.source_locking_script
+          raise ArgumentError,
+                "input #{input_index} has nil source_locking_script — " \
+                'set it or wire source_transaction before computing sighash'
+        end
+
         base_type = sighash_type & Sighash::MASK
         anyone = sighash_type.anybits?(Sighash::ANYONE_CAN_PAY)
 

data/lib/bsv/version.rb

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

data/lib/bsv/wallet/proto_wallet.rb

@@ -8,15 +8,51 @@ module BSV
   module Wallet
     # Minimal cryptographic wallet implementing the BRC-100 interface.
     #
-    # ProtoWallet provides signing, encryption, HMAC, and key derivation
-    # without transactions, storage, or blockchain interaction. It is the
-    # direct implementation of the BRC-100 crypto methods, not a delegating
-    # client. This makes it suitable for use in the SDK's Auth module without
-    # depending on the bsv-wallet gem.
+    # ProtoWallet is a direct, in-process implementation of the BRC-100 crypto
+    # operations. It requires no external gem, no storage, and no blockchain
+    # access — making it suitable for use inside the SDK itself (e.g. the Auth
+    # module) as well as lightweight applications that need cryptographic
+    # operations without full wallet infrastructure.
     #
-    # Includes +BSV::Wallet::Interface::BRC100+ — methods it supports are
-    # overridden; unsupported methods (transactions, blockchain, authentication)
-    # fall through to +NotImplementedError+.
+    # == Supported BRC-100 areas
+    #
+    # - *Public key management* — {#get_public_key}, {#reveal_counterparty_key_linkage},
+    #   {#reveal_specific_key_linkage}
+    # - *Cryptography* — {#encrypt}, {#decrypt}, {#create_hmac}, {#verify_hmac},
+    #   {#create_signature}, {#verify_signature}
+    # - *Certificates (read-only stub)* — {#list_certificates} returns an empty list;
+    #   {#prove_certificate} raises {UnsupportedActionError}
+    #
+    # == NOT supported
+    #
+    # The following BRC-100 areas are not implemented and will raise
+    # +NotImplementedError+:
+    #
+    # - Transactions (+create_action+, +sign_action+, +list_actions+, etc.)
+    # - Output management (+list_outputs+, +relinquish_output+, etc.)
+    # - Authentication (+authenticated?+, +wait_for_authentication+)
+    # - Blockchain / network data (+get_height+, +get_header_for_height+, etc.)
+    # - Certificate acquisition / discovery (+acquire_certificate+,
+    #   +discover_by_identity_key+, etc.)
+    #
+    # For full wallet functionality, use the +bsv-wallet+ gem. See
+    # +docs/sdk/wallet.md+ for usage guidance.
+    #
+    # == Construction
+    #
+    # Pass a {BSV::Primitives::PrivateKey} or the special string <tt>'anyone'</tt>.
+    # The <tt>'anyone'</tt> variant uses a well-known key (private key = 1) and is
+    # suitable for verifying or encrypting data that should be readable by
+    # any party — it must not be used where secrecy is required.
+    #
+    # @example Normal usage
+    #   wallet = BSV::Wallet::ProtoWallet.new(BSV::Primitives::PrivateKey.generate)
+    #   sig = wallet.create_signature(protocol_id: [1, 'my-app'], key_id: 'msg-1',
+    #                                 data: 'hello'.bytes)
+    #
+    # @example Anyone wallet
+    #   wallet = BSV::Wallet::ProtoWallet.new('anyone')
+    #   pub = wallet.get_public_key(identity_key: true)
     #
     class ProtoWallet
       include Interface::BRC100