bsv-sdk 0.15.0 → 0.17.0

data/lib/bsv/transaction/merkle_path.rb

@@ -21,7 +21,8 @@ module BSV
       # @!attribute [r] hash
       #   @return [String, nil] 32-byte hash (nil when duplicate)
       # @!attribute [r] txid
-      #   @return [Boolean] whether this leaf is a transaction ID
+      #   @return [Boolean] BRC-74 flag — whether this leaf represents a transaction in
+      #     the merkle tree (the 0x02 bit in the BRC-74 serialisation). Not a txid value.
       # @!attribute [r] duplicate
       #   @return [Boolean] whether this leaf duplicates its sibling
       class PathElement
@@ -29,7 +30,9 @@ module BSV
 
         # @param offset [Integer] position index within the tree level
         # @param hash [String, nil] 32-byte hash (nil when duplicate)
-        # @param txid [Boolean] whether this leaf is a transaction ID
+        # @param txid [Boolean] BRC-74 flag — true when this leaf represents a transaction
+        #   in the tree (the 0x02 bit in the BRC-74 serialisation). This is NOT a txid
+        #   value; it is a boolean presence flag mandated by the BRC-74 specification.
         # @param duplicate [Boolean] whether this leaf duplicates its sibling
         def initialize(offset:, hash: nil, txid: false, duplicate: false)
           @offset = offset
@@ -147,25 +150,26 @@ module BSV
       # @example Convert a WoC TSC proof
       #   tsc = JSON.parse(woc_response).first
       #   mp = BSV::Transaction::MerklePath.from_tsc(
-      #     txid:         tsc['txOrId'],
+      #     dtxid_hex:    tsc['txOrId'],
       #     index:        tsc['index'],
       #     nodes:        tsc['nodes'],
       #     block_height: 612_251
       #   )
       #   mp.compute_root_hex(tsc['txOrId']) #=> the block's merkle root
       #
-      # @param txid [String] hex-encoded transaction ID in display byte order
+      # @param dtxid_hex [String] hex-encoded transaction ID in display byte order
       # @param index [Integer] the transaction's position in the block
       # @param nodes [Array<String>] sibling hashes leaf-to-root, each a 32-byte
       #   hex string in display byte order, or +"*"+ for a duplicate node
       # @param block_height [Integer] the block's height (TSC carries the block
       #   hash; the caller must look up the height separately)
       # @return [MerklePath] a BRC-74 merkle path equivalent to the TSC proof
-      def self.from_tsc(txid:, index:, nodes:, block_height:)
-        txid_bytes = [txid].pack('H*').reverse
+      def self.from_tsc(dtxid_hex:, index:, nodes:, block_height:)
+        BSV::Primitives::Hex.validate_dtxid_hex!(dtxid_hex, name: 'dtxid_hex')
+        wtxid = [dtxid_hex].pack('H*').reverse
 
         # Level 0 always contains the txid leaf.
-        level0 = [PathElement.new(offset: index, hash: txid_bytes, txid: true)]
+        level0 = [PathElement.new(offset: index, hash: wtxid, txid: true)]
 
         # A single-tx block has no siblings — the txid IS the merkle root.
         return new(block_height: block_height, path: [level0]) if nodes.empty?
@@ -193,6 +197,7 @@ module BSV
         if node == '*'
           PathElement.new(offset: offset, duplicate: true)
         else
+          BSV::Primitives::Hex.validate_dtxid_hex!(node, name: "TSC merkle node at offset #{offset}")
           PathElement.new(offset: offset, hash: [node].pack('H*').reverse)
         end
       end
@@ -240,17 +245,22 @@ module BSV
 
       # Recompute the merkle root from this path and a transaction ID.
       #
-      # @param txid [String, nil] 32-byte txid in internal byte order (auto-detected if nil)
-      # @return [String] 32-byte merkle root in internal byte order
-      # @raise [ArgumentError] if the txid is not found in the path
-      def compute_root(txid = nil)
-        txid ||= @path[0].find(&:hash)&.hash
-        return txid if @path.length == 1 && @path[0].length == 1
+      # @param wtxid [String, nil] 32-byte txid in wire byte order (auto-detected if nil)
+      # @return [String] 32-byte merkle root in wire byte order
+      # @raise [ArgumentError] if the wtxid is not found in the path
+      def compute_root(wtxid = nil)
+        wtxid ||= @path[0].find(&:hash)&.hash
+        BSV::Primitives::Hex.validate_wtxid!(wtxid, name: 'wtxid') if wtxid
+        BSV.logger&.debug do
+          dtxid = wtxid&.reverse&.unpack1('H*')
+          "[MerklePath] compute_root: dtxid=#{dtxid} block_height=#{@block_height} levels=#{@path.length}"
+        end
+        return wtxid if @path.length == 1 && @path[0].length == 1
 
         indexed = build_indexed_path
 
-        tx_leaf = @path[0].find { |l| l.hash == txid }
-        raise ArgumentError, 'the BUMP does not contain the txid' unless tx_leaf
+        tx_leaf = @path[0].find { |l| l.hash == wtxid }
+        raise ArgumentError, 'the BUMP does not contain the given wtxid' unless tx_leaf
 
         working = tx_leaf.hash
         index = tx_leaf.offset
@@ -289,11 +299,12 @@ module BSV
 
       # Recompute the merkle root and return it as a hex string.
       #
-      # @param txid_hex [String, nil] hex-encoded txid (display order)
+      # @param dtxid_hex [String, nil] hex-encoded txid (display order)
       # @return [String] hex-encoded merkle root (display order)
-      def compute_root_hex(txid_hex = nil)
-        txid = txid_hex ? [txid_hex].pack('H*').reverse : nil
-        compute_root(txid).reverse.unpack1('H*')
+      def compute_root_hex(dtxid_hex = nil)
+        BSV::Primitives::Hex.validate_dtxid_hex!(dtxid_hex, name: 'compute_root_hex dtxid_hex') if dtxid_hex
+        wtxid = dtxid_hex ? [dtxid_hex].pack('H*').reverse : nil
+        compute_root(wtxid).reverse.unpack1('H*')
       end
 
       # --- Verification ---
@@ -312,22 +323,27 @@ module BSV
       # and accepts immature ones — the opposite of the intended behaviour. The correct
       # logic is: reject when `current_height - block_height < 100` (immature).
       #
-      # @param txid_hex [String] hex-encoded transaction ID (display order)
+      # @param dtxid_hex [String] hex-encoded transaction ID (display order)
       # @param chain_tracker [ChainTracker] chain tracker to verify the root against
       # @return [Boolean] true if the computed root matches the block at this height
-      def verify(txid_hex, chain_tracker)
-        txid_bytes = [txid_hex].pack('H*').reverse
-        txid_leaf = @path[0].find { |l| l.hash == txid_bytes }
+      def verify(dtxid_hex, chain_tracker)
+        BSV::Primitives::Hex.validate_dtxid_hex!(dtxid_hex, name: 'dtxid_hex')
+        wtxid = [dtxid_hex].pack('H*').reverse
+        tx_leaf = @path[0].find { |l| l.hash == wtxid }
 
         # Offset 0 in a block's merkle tree is always the coinbase transaction —
         # a Bitcoin protocol invariant. Apply the 100-block maturity check.
-        if txid_leaf&.offset&.zero?
+        if tx_leaf&.offset&.zero?
           current = chain_tracker.current_height
           return false if current - @block_height < 100
         end
 
-        root_hex = compute_root_hex(txid_hex)
-        chain_tracker.valid_root_for_height?(root_hex, @block_height)
+        root_hex = compute_root_hex(dtxid_hex)
+        valid = chain_tracker.valid_root_for_height?(root_hex, @block_height)
+        BSV.logger&.debug do
+          "[MerklePath] verify: dtxid=#{dtxid_hex} height=#{@block_height} root=#{root_hex} valid=#{valid}"
+        end
+        valid
       end
 
       # --- Combine ---
@@ -445,24 +461,24 @@ module BSV
       #
       # Matches the TS SDK's +MerklePath.extract+ behaviour.
       #
-      # @param txid_hashes [Array<String>] 32-byte txids in internal byte
+      # @param wtxid_hashes [Array<String>] 32-byte txids in wire byte
       #   order (reverse of display order). To pass hex strings, use
-      #   +txid_hexes.map { |h| [h].pack('H*').reverse }+.
+      #   +dtxid_hexes.map { |h| [h].pack('H*').reverse }+.
       # @return [MerklePath] a new trimmed compound path proving only the
       #   requested txids
-      # @raise [ArgumentError] if +txid_hashes+ is empty, any requested
+      # @raise [ArgumentError] if +wtxid_hashes+ is empty, any requested
       #   txid is not present in the source path's level 0, or the
       #   extracted path's root does not match the source root
-      def extract(txid_hashes)
-        raise ArgumentError, 'at least one txid must be provided to extract' if txid_hashes.empty?
+      def extract(wtxid_hashes)
+        raise ArgumentError, 'at least one wtxid must be provided to extract' if wtxid_hashes.empty?
 
         original_root = compute_root
         indexed = build_indexed_path
 
         # Build a level-0 hash → offset lookup
-        txid_to_offset = {}
+        wtxid_to_offset = {}
         @path[0].each do |leaf|
-          txid_to_offset[leaf.hash] = leaf.offset if leaf.hash
+          wtxid_to_offset[leaf.hash] = leaf.offset if leaf.hash
         end
 
         max_offset = @path[0].map(&:offset).max || 0
@@ -470,15 +486,15 @@ module BSV
 
         needed = Array.new(tree_height) { {} }
 
-        txid_hashes.each do |txid|
-          tx_offset = txid_to_offset[txid]
+        wtxid_hashes.each do |wtxid_hash|
+          tx_offset = wtxid_to_offset[wtxid_hash]
           if tx_offset.nil?
             raise ArgumentError,
-                  "transaction ID #{txid.reverse.unpack1('H*')} not found in the Merkle Path"
+                  "wtxid #{wtxid_hash.reverse.unpack1('H*')} not found in the Merkle Path"
           end
 
-          # Level 0: the txid leaf itself + its tree sibling
-          needed[0][tx_offset] = PathElement.new(offset: tx_offset, hash: txid, txid: true)
+          # Level 0: the transaction leaf itself + its tree sibling
+          needed[0][tx_offset] = PathElement.new(offset: tx_offset, hash: wtxid_hash, txid: true)
           sib0_offset = tx_offset ^ 1
           unless needed[0].key?(sib0_offset)
             sib = offset_leaf(indexed, 0, sib0_offset)

data/lib/bsv/transaction/transaction.rb

@@ -329,6 +329,11 @@ module BSV
         ancestors = collect_ancestors
 
         bump_index_by_height = build_beef_bumps(beef, ancestors)
+        BSV.logger&.debug do
+          proven = ancestors.count(&:merkle_path)
+          "[Transaction] BEEF: #{ancestors.length} ancestors, #{proven} proven " \
+            "across #{bump_index_by_height.length} block heights"
+        end
 
         ancestors.each do |tx|
           entry = if tx.merkle_path
@@ -370,11 +375,11 @@ module BSV
       #   or nil if the BEEF is empty or contains no raw transaction entries
       def self.from_beef(data)
         beef = Beef.from_binary(data)
-        subject_txid = beef.subject_txid ||
-                       beef.transactions.reverse.find(&:transaction)&.transaction&.txid
-        return nil unless subject_txid
+        subject_wtxid = beef.subject_wtxid ||
+                        beef.transactions.reverse.find(&:transaction)&.transaction&.wtxid
+        return nil unless subject_wtxid
 
-        beef.find_atomic_transaction(subject_txid)
+        beef.find_atomic_transaction(subject_wtxid)
       end
 
       # Parse a BEEF hex string and return the subject transaction.
@@ -388,15 +393,26 @@ module BSV
 
       # --- Transaction ID ---
 
-      # Compute the transaction ID (double-SHA-256 of the serialised tx, byte-reversed).
+      # Wire-order transaction ID (raw SHA-256d of the serialised tx).
+      #
+      # Used by BEEF, BUMPs, and merkle paths, which all work in wire byte order
+      # to match {TransactionInput#prev_wtxid}.
+      #
+      # @return [String] 32-byte transaction ID in wire byte order
+      def wtxid
+        id = BSV::Primitives::Digest.sha256d(to_binary)
+        BSV.logger&.debug { "[Transaction] wtxid computed (dtxid=#{id.reverse.unpack1('H*')})" }
+        id
+      end
+
+      # Display-order transaction ID (reversed from the natural SHA-256d hash).
       #
-      # Returns display byte order (reversed from the natural hash).
-      # Compare with {TransactionInput#prev_tx_id} which stores wire byte
-      # order (natural hash). Use +.reverse+ to convert between the two.
+      # 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
-        BSV::Primitives::Digest.sha256d(to_binary).reverse
+        wtxid.reverse
       end
 
       # The transaction ID as a hex string (display byte order).
@@ -406,6 +422,19 @@ module BSV
         txid.unpack1('H*')
       end
 
+      # Display-order transaction ID as a hex string.
+      #
+      # Mirrors the wallet gem's +DisplayTxid+ pattern. +dtxid+ always returns
+      # a 64-char hex string suitable for JSON and UI boundaries.
+      #
+      # @return [String] hex-encoded transaction ID (display order)
+      alias dtxid txid_hex
+
+      # Display-order transaction ID as a hex string (alias for {#dtxid}).
+      #
+      # @return [String] hex-encoded transaction ID (display order)
+      alias dtxid_hex txid_hex
+
       # --- Sighash (BIP-143 with FORKID) ---
 
       # Build the BIP-143 sighash preimage for an input.
@@ -456,6 +485,19 @@ module BSV
         # 10. sighash type (4 LE) — includes FORKID flag
         buf << [sighash_type].pack('V')
 
+        BSV.logger&.debug do
+          hp = buf.byteslice(4, 32).unpack1('H*')
+          hs = buf.byteslice(36, 32).unpack1('H*')
+          op = input.outpoint_binary.unpack1('H*')
+          sc = script_bytes.unpack1('H*')
+          ho = buf.byteslice(-40, 32).unpack1('H*')
+          "[Sighash] input=#{input_index} type=0x#{format('%02x', sighash_type)} " \
+            "version=#{@version} hashPrevouts=#{hp} hashSequence=#{hs} " \
+            "outpoint=#{op} scriptCode=#{sc[0, 40]}#{'...' if sc.length > 40} " \
+            "value=#{input.source_satoshis} seq=#{input.sequence} " \
+            "hashOutputs=#{ho} locktime=#{@lock_time}"
+        end
+
         buf
       end
 
@@ -466,7 +508,9 @@ module BSV
       # @param subscript [Script::Script, nil] override locking script for the input
       # @return [String] 32-byte sighash digest
       def sighash(input_index, sighash_type = Sighash::ALL_FORK_ID, subscript: nil)
-        BSV::Primitives::Digest.sha256d(sighash_preimage(input_index, sighash_type, subscript: subscript))
+        digest = BSV::Primitives::Digest.sha256d(sighash_preimage(input_index, sighash_type, subscript: subscript))
+        BSV.logger&.debug { "[Sighash] digest=#{digest.unpack1('H*')}" }
+        digest
       end
 
       # --- Signing ---
@@ -580,17 +624,17 @@ module BSV
 
         until queue.empty?
           tx = queue.shift
-          tx_id = tx.txid_hex
-          next if verified[tx_id]
+          wtxid = tx.wtxid
+          next if verified[wtxid]
 
           # Merkle path short-circuit: proven transaction needs no input verification
           if tx.merkle_path
-            unless tx.merkle_path.verify(tx_id, chain_tracker)
+            unless tx.merkle_path.verify(tx.txid_hex, chain_tracker)
               raise VerificationError.new(:invalid_merkle_proof,
-                                          "invalid merkle proof for transaction #{tx_id}")
+                                          "invalid merkle proof for transaction #{tx.txid_hex}")
             end
 
-            verified[tx_id] = true
+            verified[wtxid] = true
             next
           end
 
@@ -622,13 +666,13 @@ module BSV
 
             # Enqueue source transaction for verification if not yet verified
             source_tx = input.source_transaction
-            queue << source_tx if source_tx && !verified[source_tx.txid_hex]
+            queue << source_tx if source_tx && !verified[source_tx.wtxid]
           end
 
           # Output ≤ input check
           verify_output_constraint(tx)
 
-          verified[tx_id] = true
+          verified[wtxid] = true
         end
 
         true
@@ -777,19 +821,19 @@ module BSV
       end
 
       def verify_input_requirements(tx, input, index)
-        tx_id = tx.txid_hex
+        dtxid_hex = tx.txid_hex
         if input.unlocking_script.nil?
           raise VerificationError.new(:missing_source,
-                                      "input #{index} of transaction #{tx_id} has no unlocking script")
+                                      "input #{index} of transaction #{dtxid_hex} has no unlocking script")
         end
         if input.source_locking_script.nil?
           raise VerificationError.new(:missing_source,
-                                      "input #{index} of transaction #{tx_id} has no source locking script")
+                                      "input #{index} of transaction #{dtxid_hex} has no source locking script")
         end
         return unless input.source_satoshis.nil?
 
         raise VerificationError.new(:missing_source,
-                                    "input #{index} of transaction #{tx_id} has no source satoshis")
+                                    "input #{index} of transaction #{dtxid_hex} has no source satoshis")
       end
 
       def verify_fee(fee_model)
@@ -843,7 +887,7 @@ module BSV
 
       # Collect this transaction and all its ancestors in dependency order
       # (ancestors first, self last). Stops recursion at transactions with
-      # a merkle_path (proven leaves). Deduplicates by txid.
+      # a merkle_path (proven leaves). Deduplicates by wtxid (wire-order bytes).
       def collect_ancestors
         seen = {}
         result = []
@@ -852,18 +896,25 @@ module BSV
       end
 
       def collect_ancestors_recursive(tx, seen, result)
-        txid = tx.txid
-        return if seen.key?(txid)
+        wtxid = tx.wtxid
+        return if seen.key?(wtxid)
 
-        unless tx.merkle_path
-          tx.inputs.each do |input|
-            next unless input.source_transaction
+        if tx.merkle_path
+          BSV.logger&.debug do
+            "[Transaction] ancestor: #{tx.dtxid_hex} proven at height #{tx.merkle_path.block_height} (leaf stop)"
+          end
+        else
+          tx.inputs.each_with_index do |input, idx|
+            unless input.source_transaction
+              BSV.logger&.debug { "[Transaction] ancestor: #{tx.dtxid_hex} input #{idx} has no source_transaction (skipped)" }
+              next
+            end
 
             collect_ancestors_recursive(input.source_transaction, seen, result)
           end
         end
 
-        seen[txid] = true
+        seen[wtxid] = true
         result << tx
       end
 
@@ -886,8 +937,8 @@ module BSV
           merged = txs.first.merkle_path.dup
           txs.drop(1).each { |t| merged.combine(t.merkle_path) }
 
-          txid_hashes = txs.map { |t| t.txid.reverse }
-          clean = merged.extract(txid_hashes)
+          wtxid_hashes = txs.map(&:wtxid)
+          clean = merged.extract(wtxid_hashes)
 
           bump_index_by_height[height] = beef.bumps.length
           beef.bumps << clean

data/lib/bsv/transaction/transaction_input.rb

@@ -8,8 +8,8 @@ module BSV
     # output index (the "outpoint"), and provide an unlocking script to
     # satisfy the locking script conditions.
     class TransactionInput
-      # @return [String] 32-byte transaction ID of the output being spent (internal byte order)
-      attr_reader :prev_tx_id
+      # @return [String] 32-byte wire-order transaction ID of the output being spent
+      attr_reader :prev_wtxid
 
       # @return [Integer] index of the output within the previous transaction
       attr_reader :prev_tx_out_index
@@ -32,15 +32,17 @@ module BSV
       # @return [UnlockingScriptTemplate, nil] template for deferred signing
       attr_accessor :unlocking_script_template
 
-      # @param prev_tx_id [String] 32-byte transaction ID (internal byte order)
+      # @param prev_wtxid [String] 32-byte wire-order transaction ID
       # @param prev_tx_out_index [Integer] output index in the previous transaction
       # @param unlocking_script [Script::Script, nil] unlocking script (nil if unsigned)
       # @param sequence [Integer] sequence number
-      def initialize(prev_tx_id:, prev_tx_out_index:, unlocking_script: nil, sequence: 0xFFFFFFFF)
-        @prev_tx_id = prev_tx_id.b
+      def initialize(prev_wtxid:, prev_tx_out_index:, unlocking_script: nil, sequence: 0xFFFFFFFF)
+        BSV::Primitives::Hex.validate_wtxid!(prev_wtxid, name: 'prev_wtxid')
+        @prev_wtxid = prev_wtxid.b
         @prev_tx_out_index = prev_tx_out_index
         @unlocking_script = unlocking_script
         @sequence = sequence
+        BSV.logger&.debug { "[TransactionInput] prev_wtxid set: #{dtxid_hex}:#{@prev_tx_out_index}" }
       end
 
       # Serialise the input to its binary wire format.
@@ -48,7 +50,7 @@ module BSV
       # @return [String] binary input (outpoint + varint + script + sequence)
       def to_binary
         script_bytes = @unlocking_script ? @unlocking_script.to_binary : ''.b
-        @prev_tx_id +
+        @prev_wtxid +
           [@prev_tx_out_index].pack('V') +
           VarInt.encode(script_bytes.bytesize) +
           script_bytes +
@@ -66,7 +68,7 @@ module BSV
                 "truncated input: need 36 bytes for outpoint at offset #{offset}, got #{data.bytesize - offset}"
         end
 
-        prev_tx_id = data.byteslice(offset, 32)
+        prev_wtxid = data.byteslice(offset, 32)
         prev_tx_out_index = data.byteslice(offset + 32, 4).unpack1('V')
         offset += 36
 
@@ -90,7 +92,7 @@ module BSV
 
         total = 36 + vi_size + script_len + 4
         input = new(
-          prev_tx_id: prev_tx_id,
+          prev_wtxid: prev_wtxid,
           prev_tx_out_index: prev_tx_out_index,
           unlocking_script: unlocking_script,
           sequence: sequence
@@ -98,26 +100,29 @@ module BSV
         [input, total]
       end
 
-      # Convert a hex transaction ID to internal byte order (reversed).
+      # Convert a display-order hex transaction ID to wire-order bytes.
       #
       # @param hex [String] hex-encoded transaction ID (display order)
-      # @return [String] 32-byte transaction ID in internal byte order
-      def self.txid_from_hex(hex)
-        [hex].pack('H*').reverse
+      # @return [String] 32-byte transaction ID in wire byte order
+      def self.wtxid_from_hex(hex)
+        BSV::Primitives::Hex.validate_dtxid_hex!(hex, name: 'wtxid_from_hex input')
+        wtxid = [hex].pack('H*').reverse
+        BSV.logger&.debug { "[TransactionInput] wtxid_from_hex: #{hex} -> #{wtxid.bytesize}B wire-order" }
+        wtxid
       end
 
-      # Serialise the outpoint (prev_tx_id + output index) as binary.
+      # Serialise the outpoint (prev_wtxid + output index) as binary.
       #
       # @return [String] 36-byte outpoint
       def outpoint_binary
-        @prev_tx_id + [@prev_tx_out_index].pack('V')
+        @prev_wtxid + [@prev_tx_out_index].pack('V')
       end
 
-      # The previous transaction ID in hex (display order).
+      # The previous transaction ID in display-order hex.
       #
-      # @return [String] hex-encoded transaction ID
-      def txid_hex
-        @prev_tx_id.reverse.unpack1('H*')
+      # @return [String] hex-encoded transaction ID (display order)
+      def dtxid_hex
+        @prev_wtxid.reverse.unpack1('H*')
       end
     end
   end

data/lib/bsv/version.rb

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

data/lib/bsv/wallet/errors.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module BSV
+  module Wallet
+    # Base error for all wallet operations. Carries a machine-readable code
+    # per the BRC-100 error structure.
+    class Error < StandardError
+      attr_reader :code
+
+      def initialize(message, code = 1)
+        @code = code
+        super(message)
+      end
+    end
+
+    # Raised when a required parameter is missing or invalid.
+    class InvalidParameterError < Error
+      attr_reader :parameter
+
+      def initialize(parameter, must_be = 'valid')
+        @parameter = parameter
+        super("the #{parameter} parameter must be #{must_be}", 6)
+      end
+    end
+
+    # Raised when an HMAC fails to verify.
+    class InvalidHmacError < Error
+      def initialize(message = 'the provided HMAC is invalid')
+        super(message, 3)
+      end
+    end
+
+    # Raised when a signature fails to verify.
+    class InvalidSignatureError < Error
+      def initialize(message = 'the provided signature is invalid')
+        super(message, 4)
+      end
+    end
+
+    # Raised when an operation is not supported by this wallet implementation.
+    class UnsupportedActionError < Error
+      def initialize(method_name = 'this method')
+        super("#{method_name} is not supported by this wallet implementation", 2)
+      end
+    end
+  end
+end