bsv-wallet 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e7f0eba4cf58a9a63db79d2b731700f5d2d3ae04b82416ccc0288a1c5659a365
-  data.tar.gz: 2453264034fbbe664ced66bd853e8e5b4a52eb668e87a6eb01fd71e5b589d61b
+  metadata.gz: bf66409b10a18ba1c43a05efb6e7909e4ba83a87d4421a68248f3f3174a8483d
+  data.tar.gz: 2ae27d6080353acb67b11e557e5e38c063abd243e1a36e2bc4c6ee6fa43fc885
 SHA512:
-  metadata.gz: '092fa8e32a2ac7b7b4429c0fe715858ba16bba9869530cb97c4dfab0ff5730b2b2ff018da87a60cea5c5beaf7e527945c1158127e27806825db8ba29e895e2ed'
-  data.tar.gz: 68c27f04fa860ce116c7ddaa1a76a25b4ccfc56ab4b8b3af454dbbf5b2f452c719b884df92497b01ff6b74dbcb4eced994fbe519a51443bf7200a87cdaed65df
+  metadata.gz: ad6a39da955d05c18460291ec2f1e7f56cae7c3a82d32da175477ea62c3e82bfd4dcce11bd9c4a53236b38b6091176badb55b264e05489e71722ab6ca8a651df
+  data.tar.gz: 3724b1e7cbb060a750eb865688b2859645a7837e05fd964214f2c8852ebd4aa515c8ee1afa51bd9fd50fd7bde0c9aa8299e0766057c40196b169e5f595db82fc

data/CHANGELOG-wallet.md

@@ -5,6 +5,71 @@ 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.5.0 — 2026-04-11
+
+Native UTXO management, coin selection, and automatic change handling.
+The wallet can now fund transactions end-to-end without an external
+wallet server — `create_action` with outputs but no inputs triggers
+automatic UTXO selection, fee estimation, and change generation.
+
+### Added
+
+- **UTXO management pipeline** (#264, #265–#272): complete transaction-
+  funding pipeline with `CoinSelector` (exact-match, smallest-sufficient,
+  largest-first strategies), `ChangeGenerator` (BRC-29 multi-output change
+  with dust consolidation, randomised splits, pool-health-aware output
+  caps), and `FeeEstimator` (size-based sats/kB with ceil rounding).
+- **`WhatsOnChainProvider`**: chain UTXO discovery via the WhatsOnChain API,
+  implementing `sync_utxos` for on-chain balance loading.
+- **StorageAdapter extensions**: 6 new interface methods —
+  `update_output_state`, `lock_utxos`, `find_spendable_outputs`,
+  `release_stale_pending!`, `store_setting`, `find_setting`. All default
+  to `NotImplementedError`; `MemoryStore` and `FileStore` implement them.
+- **Atomic UTXO locking**: `lock_utxos` checks and marks outputs as
+  `:pending` within a single mutex hold, closing the TOCTOU race where two
+  threads could select the same UTXO.
+- **Pending state management**: outputs transition through `:spendable` →
+  `:pending` → `:spent`, with timestamps and caller references for stale
+  lock recovery.
+- **Auto-funding in `create_action`**: when given outputs without inputs,
+  the wallet selects UTXOs, estimates fees, generates change outputs, and
+  locks inputs automatically.
+- **`set_wallet_change_params`**: configures target UTXO count and value
+  for the change pool.
+
+### Fixed
+
+- **Identity UTXO filter alignment**: `sync_utxos` stores
+  `derivation_type: :identity` but auto-fund filtered on a field that was
+  never set. Fixed the filter and added a signing branch that uses
+  `root_key` directly for identity UTXOs.
+- **`tx_pos` bounds validation in `sync_utxos`**: untrusted WhatsOnChain
+  API responses with negative or out-of-bounds `tx_pos` could exploit
+  Ruby's negative array indexing or raise `NoMethodError` on nil. Now
+  validates before use.
+- **Stale pending recovery rate-limited**: `release_stale_pending!` now
+  skips if invoked within 30 seconds, preventing O(n) output scans on
+  every `create_action` call.
+- **`no_send` change outputs stored as `:pending`**, matching the TS SDK
+  where `noSend` outputs have `spendable: false`. Prevents them from
+  being auto-selected by concurrent `create_action` calls.
+- **`abort_action` cleans up change outputs** created by the aborted
+  transaction, matching TS SDK behaviour.
+- **Nil state guard**: `effective_state` handles `state: nil` (from NULL
+  DB column) without raising `NoMethodError`.
+- **`change_params` wiring**: stored change params and pool size are now
+  wired into `converge_change` so `set_wallet_change_params` actually
+  affects auto-fund output count.
+
+### Changed
+
+- **`FeeModel` consolidated into `FeeEstimator`**: `FeeModel` is now a
+  backward-compatible alias for `FeeEstimator`, which is the canonical
+  implementation with dust floor, varint handling, and extra-bytes
+  support.
+- **`BRC29_PROTOCOL_ID` constant** replaces hardcoded protocol ID in
+  `internalize_payment`.
+
 ## 0.4.0 — 2026-04-10
 
 ### Added

data/lib/bsv/wallet_interface/chain_provider.rb

@@ -32,6 +32,20 @@ module BSV
       def get_header(_height)
         raise NotImplementedError, "#{self.class}#get_header not implemented"
       end
+
+      # Returns unspent transaction outputs for the given address.
+      # @param _address [String] BSV address
+      # @return [Array<Hash>] array of hashes with :tx_hash, :tx_pos, :value keys
+      def get_utxos(_address)
+        raise NotImplementedError, "#{self.class}#get_utxos not implemented"
+      end
+
+      # Returns the raw transaction hex for the given txid.
+      # @param _txid [String] transaction ID (hex)
+      # @return [String] raw transaction hex string
+      def get_transaction(_txid)
+        raise NotImplementedError, "#{self.class}#get_transaction not implemented"
+      end
     end
   end
 end

data/lib/bsv/wallet_interface/change_generator.rb

@@ -0,0 +1,192 @@
+# frozen_string_literal: true
+
+require 'securerandom'
+
+module BSV
+  module Wallet
+    # Generates BRC-29 change outputs for excess satoshis in a transaction.
+    #
+    # Handles the full lifecycle of change output creation:
+    #   - Dust-floor enforcement (a change output is only worthwhile if its
+    #     value covers at least 2× the cost to spend it later)
+    #   - Optional distribution across multiple outputs with randomised splits
+    #   - BRC-29 key derivation metadata attached to each output so the wallet
+    #     can later identify and spend the change
+    #
+    # @example Single change output
+    #   generator = BSV::Wallet::ChangeGenerator.new(key_deriver: deriver, fee_estimator: estimator)
+    #   outputs = generator.generate(excess_satoshis: 5000)
+    #   # => [{ satoshis: 5000, locking_script: ..., derivation_prefix: ..., ... }]
+    #
+    # @example Spread across multiple outputs
+    #   generator = BSV::Wallet::ChangeGenerator.new(key_deriver: deriver, fee_estimator: estimator, max_outputs: 4)
+    #   outputs = generator.generate(excess_satoshis: 10_000)
+    #   # => up to 4 outputs summing to 10_000
+    class ChangeGenerator
+      # BRC-29 protocol identifier used for change key derivation.
+      BRC29_PROTOCOL_ID = [2, '3241645161d8'].freeze
+
+      # @return [Integer] maximum number of change outputs that may be created
+      attr_reader :max_outputs
+
+      # @param key_deriver [BSV::Wallet::KeyDeriver] derives child keys for each change output
+      # @param fee_estimator [BSV::Wallet::FeeEstimator] used to compute the dust floor
+      #   (also accepted as +fee_model:+ for backwards compatibility)
+      # @param identity_key [String, nil] override identity key for change derivation;
+      #   defaults to key_deriver.identity_key when nil
+      # @param max_outputs [Integer] upper bound on change outputs (default: 8)
+      # @raise [ArgumentError] if max_outputs is less than 1
+      def initialize(key_deriver:, fee_estimator: nil, fee_model: nil, identity_key: nil, max_outputs: 8)
+        raise ArgumentError, 'max_outputs must be at least 1' unless max_outputs >= 1
+        raise ArgumentError, 'provide fee_estimator: or fee_model:, not both' if fee_estimator && fee_model
+
+        @key_deriver = key_deriver
+        @fee_model = fee_estimator || fee_model || raise(ArgumentError, 'fee_estimator: (or fee_model:) is required')
+        @identity_key_override = identity_key
+        @max_outputs = max_outputs
+      end
+
+      # Generates change outputs for the given excess satoshis.
+      #
+      # Returns an empty array when the excess is zero or below the dust floor.
+      # Otherwise returns between 1 and {#max_outputs} output hashes, each with:
+      #   - +:satoshis+ — value of the output
+      #   - +:locking_script+ — P2PKH locking script for the derived key
+      #   - +:derivation_prefix+ — random hex string for BRC-29 key derivation
+      #   - +:derivation_suffix+ — random hex string for BRC-29 key derivation
+      #   - +:sender_identity_key+ — wallet's own identity key (self-payment)
+      #
+      # When +pool_size:+ and +change_params:+ are both provided, the number of
+      # change outputs is adjusted based on the pool's health:
+      #   - Pool below target count: produce more outputs (up to +max_outputs+)
+      #     to build up the UTXO pool.
+      #   - Pool at or above target count: produce fewer outputs (1-2) to avoid
+      #     unnecessary fragmentation.
+      #
+      # @param excess_satoshis [Integer] satoshis remaining after inputs minus outputs minus fee
+      # @param num_existing_outputs [Integer] number of outputs already in the transaction
+      #   (unused here but kept for interface symmetry with future callers)
+      # @param pool_size [Integer, nil] current number of spendable UTXOs in the pool
+      # @param change_params [Hash, nil] pool targets with +:count+ and +:satoshis+ keys
+      # @return [Array<Hash>] change output descriptors (may be empty)
+      def generate(excess_satoshis:, num_existing_outputs: 0, pool_size: nil, change_params: nil) # rubocop:disable Lint/UnusedMethodArgument
+        return [] if excess_satoshis <= 0
+        return [] if excess_satoshis < dust_floor
+
+        effective_max = pool_aware_max_outputs(pool_size, change_params)
+        amounts = split_amounts(excess_satoshis, effective_max)
+        amounts.map { |amount| build_output(amount) }
+      end
+
+      private
+
+      # The minimum value a change output must carry to be economically viable.
+      # Set to 2× the estimated fee to spend a single P2PKH input, ensuring the
+      # recipient never loses money by spending the output.
+      #
+      # @return [Integer] dust floor in satoshis (minimum 2)
+      def dust_floor
+        @dust_floor ||= [2, @fee_model.estimate(p2pkh_inputs: 1, p2pkh_outputs: 1) * 2].max
+      end
+
+      # Determines the effective maximum number of change outputs to produce,
+      # taking pool health into account when +pool_size+ and +change_params+
+      # are both present.
+      #
+      # - Pool below target: use full +max_outputs+ to build up the pool.
+      # - Pool at/above target: cap at 2 to avoid unnecessary fragmentation.
+      # - No params: return +max_outputs+ unchanged.
+      #
+      # @param pool_size [Integer, nil]
+      # @param change_params [Hash, nil] hash with +:count+ key
+      # @return [Integer]
+      def pool_aware_max_outputs(pool_size, change_params)
+        return @max_outputs unless pool_size && change_params
+
+        target_count = change_params[:count] || change_params['count']
+        return @max_outputs unless target_count
+
+        pool_size < target_count ? @max_outputs : [2, @max_outputs].min
+      end
+
+      # Splits +excess+ across up to +cap+ amounts, each at least
+      # {#dust_floor} satoshis. Any sub-dust remainder is folded into the largest
+      # output.
+      #
+      # @param excess [Integer] total satoshis to split
+      # @param cap [Integer] maximum number of outputs (defaults to +max_outputs+)
+      # @return [Array<Integer>] per-output satoshi amounts
+      def split_amounts(excess, cap = @max_outputs)
+        return [excess] if cap == 1
+
+        # Determine the maximum number of outputs we can afford given the dust floor.
+        max_possible = [excess / dust_floor, cap].min
+        num_outputs = [max_possible, 1].max
+
+        return [excess] if num_outputs == 1
+
+        distribute(excess, num_outputs)
+      end
+
+      # Randomly distributes +total+ satoshis across +count+ buckets, each
+      # guaranteed to be at least {#dust_floor} satoshis. Any remainder below the
+      # dust floor is consolidated into the largest bucket.
+      #
+      # @param total [Integer]
+      # @param count [Integer] number of output buckets (>= 2)
+      # @return [Array<Integer>]
+      def distribute(total, count)
+        # Reserve the dust floor for every bucket, then distribute the surplus.
+        reserved = dust_floor * count
+        surplus = total - reserved
+
+        # Generate (count - 1) random cut-points within the surplus range,
+        # then derive bucket sizes from the gaps between cut-points.
+        cuts = Array.new(count - 1) { rand(surplus + 1) }.sort
+        gaps = [cuts.first] + cuts.each_cons(2).map { |a, b| b - a } + [surplus - cuts.last]
+
+        amounts = gaps.map { |g| g + dust_floor }
+
+        consolidate_sub_dust(amounts)
+      end
+
+      # Folds any amounts that fell below the dust floor into the largest output.
+      # This should be rare given the reservation logic, but guards against edge
+      # cases from integer rounding.
+      #
+      # @param amounts [Array<Integer>]
+      # @return [Array<Integer>]
+      def consolidate_sub_dust(amounts)
+        valid, sub_dust = amounts.partition { |a| a >= dust_floor }
+        return amounts if sub_dust.empty?
+
+        remainder = sub_dust.sum
+        max_index = valid.each_with_index.max_by { |a, _| a }[1]
+        valid[max_index] += remainder
+        valid
+      end
+
+      # Builds a single change output hash with a freshly derived BRC-29 key.
+      #
+      # @param satoshis [Integer]
+      # @return [Hash]
+      def build_output(satoshis)
+        prefix = SecureRandom.hex(16)
+        suffix = SecureRandom.hex(16)
+        identity_key = @identity_key_override || @key_deriver.identity_key
+        key_id = "#{prefix} #{suffix}"
+
+        pub_key = @key_deriver.derive_public_key(BRC29_PROTOCOL_ID, key_id, identity_key, for_self: true)
+        locking_script = BSV::Script::Script.p2pkh_lock(pub_key.hash160)
+
+        {
+          satoshis: satoshis,
+          locking_script: locking_script,
+          derivation_prefix: prefix,
+          derivation_suffix: suffix,
+          sender_identity_key: identity_key
+        }
+      end
+    end
+  end
+end

data/lib/bsv/wallet_interface/coin_selector.rb

@@ -0,0 +1,132 @@
+# frozen_string_literal: true
+
+module BSV
+  module Wallet
+    # Selects UTXOs from an available pool to fund a transaction.
+    #
+    # Given a target amount and a fee model, the selector chooses the minimum
+    # set of UTXOs needed to cover `target + fee`. It supports two strategies:
+    #
+    # - `:standard` — tries an exact match, then smallest-sufficient, then
+    #   falls back to largest-first accumulation.
+    # - `:largest_first` — skips exact/smallest checks and goes straight to
+    #   largest-first accumulation.
+    #
+    # Fee estimation uses {BSV::Wallet::FeeEstimator} with P2PKH size constants.
+    # During accumulation a potential change output is included in the fee
+    # estimate, so the caller can always produce change if needed.
+    #
+    # @example
+    #   estimator = BSV::Wallet::FeeEstimator.new(sats_per_kb: 1)
+    #   selector  = BSV::Wallet::CoinSelector.new(fee_estimator: estimator)
+    #   result    = selector.select(available: utxos, target_satoshis: 1000, num_outputs: 1)
+    #   # => { inputs: [...], fee: 1, total_satoshis: 1001, excess: 0 }
+    class CoinSelector
+      VALID_STRATEGIES = %i[standard largest_first].freeze
+
+      # @param fee_estimator [BSV::Wallet::FeeEstimator] fee estimation model
+      #   (also accepted as +fee_model:+ for backwards compatibility)
+      # @param strategy      [Symbol] selection strategy — `:standard` or `:largest_first`
+      # @raise [ArgumentError] if strategy is not recognised
+      def initialize(fee_estimator: nil, fee_model: nil, strategy: :standard)
+        raise ArgumentError, "unknown strategy #{strategy.inspect}; use :standard or :largest_first" unless VALID_STRATEGIES.include?(strategy)
+        raise ArgumentError, 'provide fee_estimator: or fee_model:, not both' if fee_estimator && fee_model
+
+        @fee_model = fee_estimator || fee_model || raise(ArgumentError, 'fee_estimator: (or fee_model:) is required')
+        @strategy  = strategy
+      end
+
+      # Selects UTXOs to cover +target_satoshis+ plus estimated fees.
+      #
+      # @param available       [Array<Hash>] pool of UTXOs; each hash must have a +:satoshis+ key
+      # @param target_satoshis [Integer]     amount to fund (excluding fee)
+      # @param num_outputs     [Integer]     number of recipient outputs in the transaction
+      # @return [Hash] with keys +:inputs+, +:fee+, +:total_satoshis+, +:excess+
+      # @raise [BSV::Wallet::InsufficientFundsError] when the pool cannot cover target + fees
+      def select(available:, target_satoshis:, num_outputs:)
+        raise InsufficientFundsError.new(available: 0, required: target_satoshis) if available.empty?
+
+        result = case @strategy
+                 when :standard then standard_select(available, target_satoshis, num_outputs)
+                 when :largest_first then accumulate(available, target_satoshis, num_outputs)
+                 end
+
+        result || raise_insufficient(available, target_satoshis)
+      end
+
+      private
+
+      # Tries exact match → smallest sufficient → accumulation.
+      def standard_select(available, target_satoshis, num_outputs)
+        exact_match(available, target_satoshis, num_outputs) ||
+          smallest_sufficient(available, target_satoshis, num_outputs) ||
+          accumulate(available, target_satoshis, num_outputs)
+      end
+
+      # Returns a result if a single UTXO covers exactly target + fee (no change).
+      def exact_match(available, target_satoshis, num_outputs)
+        fee = @fee_model.estimate(p2pkh_inputs: 1, p2pkh_outputs: num_outputs)
+        needed = target_satoshis + fee
+
+        utxo = available.find { |u| u[:satoshis] == needed }
+        return unless utxo
+
+        build_result([utxo], target_satoshis, fee)
+      end
+
+      # Returns the smallest single UTXO that is ≥ target + fee.
+      def smallest_sufficient(available, target_satoshis, num_outputs)
+        fee = @fee_model.estimate(p2pkh_inputs: 1, p2pkh_outputs: num_outputs)
+        needed = target_satoshis + fee
+
+        utxo = available
+               .select { |u| u[:satoshis] >= needed }
+               .min_by { |u| u[:satoshis] }
+        return unless utxo
+
+        build_result([utxo], target_satoshis, fee)
+      end
+
+      # Accumulates UTXOs largest-first until total ≥ target + fee.
+      # Fee is recalculated with each additional input and includes one
+      # potential change output (+1 to num_outputs).
+      def accumulate(available, target_satoshis, num_outputs)
+        sorted   = available.sort_by { |u| -u[:satoshis] }
+        selected = []
+        total    = 0
+
+        sorted.each do |utxo|
+          selected << utxo
+          total += utxo[:satoshis]
+
+          fee = @fee_model.estimate(
+            p2pkh_inputs: selected.size,
+            p2pkh_outputs: num_outputs + 1
+          )
+
+          return build_result(selected, target_satoshis, fee) if total >= target_satoshis + fee
+        end
+
+        nil
+      end
+
+      def build_result(inputs, target_satoshis, fee)
+        total = inputs.sum { |u| u[:satoshis] }
+        {
+          inputs: inputs,
+          fee: fee,
+          total_satoshis: total,
+          excess: total - target_satoshis - fee
+        }
+      end
+
+      def raise_insufficient(available, target_satoshis)
+        total_available = available.sum { |u| u[:satoshis] }
+        raise InsufficientFundsError.new(
+          available: total_available,
+          required: target_satoshis
+        )
+      end
+    end
+  end
+end

data/lib/bsv/wallet_interface/fee_estimator.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+module BSV
+  module Wallet
+    # Estimates transaction fees before a {BSV::Transaction::Transaction} object exists.
+    #
+    # Wraps {BSV::Transaction::FeeModels::SatoshisPerKilobyte} to provide pre-construction
+    # fee estimation given only input and output counts. Once a real {Transaction} is
+    # available, delegates directly to the underlying SDK fee model via {#estimate_for_tx}.
+    #
+    # The default rate is 1 sat/kB — the current BSV network standard. The SDK's own
+    # {SatoshisPerKilobyte} defaults to 100 sat/kB; this class intentionally differs.
+    #
+    # @example Pre-construction estimate
+    #   estimator = BSV::Wallet::FeeEstimator.new
+    #   fee = estimator.estimate(p2pkh_inputs: 2, p2pkh_outputs: 3)
+    #   # => 1 (at 1 sat/kB, ceil(408/1000 * 1) = 1)
+    #
+    # @example Custom rate
+    #   estimator = BSV::Wallet::FeeEstimator.new(sats_per_kb: 50)
+    #   fee = estimator.estimate(p2pkh_inputs: 1, p2pkh_outputs: 1)
+    #   # => 10 (ceil(192/1000 * 50) = 10)
+    class FeeEstimator
+      # Estimated size in bytes of an unsigned P2PKH input.
+      # Matches {BSV::Transaction::Transaction::UNSIGNED_P2PKH_INPUT_SIZE}.
+      P2PKH_INPUT_SIZE = BSV::Transaction::Transaction::UNSIGNED_P2PKH_INPUT_SIZE
+
+      # Estimated size in bytes of a P2PKH output (8 satoshis + varint(25) + 25-byte script).
+      P2PKH_OUTPUT_SIZE = 34
+
+      # Fixed overhead in bytes for version (4) and lock_time (4).
+      FIXED_OVERHEAD = 8
+
+      # Approximate overhead including typical 1-byte varints for input/output
+      # counts. Retained for backward compatibility with code that referenced
+      # +FeeModel::OVERHEAD+.
+      OVERHEAD = 10
+
+      # @return [Integer] the satoshis-per-kilobyte rate used for estimation
+      attr_reader :sats_per_kb
+
+      # @param sats_per_kb [Integer] fee rate in satoshis per kilobyte (default: 1)
+      # @raise [ArgumentError] if sats_per_kb is zero or negative
+      def initialize(sats_per_kb: 1)
+        raise ArgumentError, 'sats_per_kb must be greater than zero' unless sats_per_kb.positive?
+
+        @sats_per_kb = sats_per_kb
+        @sdk_model = BSV::Transaction::FeeModels::SatoshisPerKilobyte.new(value: sats_per_kb)
+      end
+
+      # Estimate the fee for a transaction described by input and output counts.
+      #
+      # Computes the serialised byte size using standard P2PKH sizes and correct
+      # Bitcoin varint encoding for the input/output count fields, then applies
+      # the configured sat/kB rate. Returns at least 1 satoshi.
+      #
+      # @param p2pkh_inputs [Integer] number of P2PKH inputs
+      # @param p2pkh_outputs [Integer] number of P2PKH outputs
+      # @param extra_bytes [Integer] additional bytes to include (e.g. OP_RETURN data)
+      # @return [Integer] estimated fee in satoshis (minimum 1)
+      def estimate(p2pkh_inputs:, p2pkh_outputs:, extra_bytes: 0)
+        total_bytes = byte_size(p2pkh_inputs, p2pkh_outputs) + extra_bytes
+        fee = (total_bytes / 1000.0 * @sats_per_kb).ceil
+        [1, fee].max
+      end
+
+      # Compute the fee for a fully-constructed transaction.
+      #
+      # Delegates to the underlying {BSV::Transaction::FeeModels::SatoshisPerKilobyte}
+      # model, which uses {BSV::Transaction::Transaction#estimated_size} internally.
+      #
+      # @param tx [BSV::Transaction::Transaction] the transaction to compute the fee for
+      # @return [Integer] fee in satoshis
+      def estimate_for_tx(tx)
+        @sdk_model.compute_fee(tx)
+      end
+
+      # Alias for {#estimate_for_tx} — matches the SDK's +compute_fee+ naming.
+      alias compute estimate_for_tx
+
+      # Minimum viable change output value at the configured rate.
+      #
+      # An output is economically viable only if its value exceeds twice the cost of
+      # spending it. The cost to spend a single P2PKH input is estimated as the fee
+      # for a minimal 1-input / 1-output transaction.
+      #
+      # @return [Integer] minimum satoshis for a change output to be worth creating
+      def dust_floor
+        cost = (spend_one_p2pkh_bytes / 1000.0 * @sats_per_kb).ceil
+        [1, cost * 2].max
+      end
+
+      private
+
+      # Total byte size for a transaction with the given input/output counts.
+      def byte_size(input_count, output_count)
+        FIXED_OVERHEAD +
+          varint_size(input_count) +
+          (input_count * P2PKH_INPUT_SIZE) +
+          varint_size(output_count) +
+          (output_count * P2PKH_OUTPUT_SIZE)
+      end
+
+      # Byte size of a minimal single-input, single-output transaction.
+      # Used to compute the cost of spending one P2PKH UTXO.
+      def spend_one_p2pkh_bytes
+        byte_size(1, 1)
+      end
+
+      # Number of bytes required to encode +n+ as a Bitcoin varint.
+      def varint_size(n)
+        if n < 0xFD
+          1
+        elsif n <= 0xFFFF
+          3
+        elsif n <= 0xFFFF_FFFF
+          5
+        else
+          9
+        end
+      end
+    end
+  end
+end

data/lib/bsv/wallet_interface/fee_model.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+require_relative 'fee_estimator'
+
+module BSV
+  module Wallet
+    # Backward-compatible alias for {FeeEstimator}.
+    #
+    # All fee estimation is consolidated in {FeeEstimator}, which provides
+    # both pre-construction estimation (+estimate+) and post-construction
+    # delegation (+compute+ / +estimate_for_tx+). This alias ensures
+    # existing code referencing +FeeModel+ continues to work.
+    #
+    # @example
+    #   model = BSV::Wallet::FeeModel.new(sats_per_kb: 50)
+    #   model.estimate(p2pkh_inputs: 2, p2pkh_outputs: 3)
+    #   model.compute(transaction)
+    #   model.dust_floor
+    FeeModel = FeeEstimator
+  end
+end

data/lib/bsv/wallet_interface/file_store.rb

@@ -60,6 +60,18 @@ module BSV
         result
       end
 
+      def update_output_state(outpoint, new_state, pending_reference: nil, no_send: nil)
+        result = super
+        save_outputs
+        result
+      end
+
+      def lock_utxos(outpoints, reference:, no_send: false)
+        locked = super
+        save_outputs unless locked.empty?
+        locked
+      end
+
       def store_certificate(cert_data)
         result = super
         save_certificates
@@ -82,6 +94,11 @@ module BSV
         save_transactions
       end
 
+      def store_setting(key, value)
+        super
+        save_settings
+      end
+
       private
 
       def proofs_path
@@ -99,7 +116,7 @@ module BSV
                        'Other users may be able to access wallet data.')
         end
 
-        [actions_path, outputs_path, certificates_path, proofs_path, transactions_path].each do |path|
+        [actions_path, outputs_path, certificates_path, proofs_path, transactions_path, settings_path].each do |path|
           next unless File.exist?(path)
 
           file_mode = File.stat(path).mode & 0o777
@@ -114,6 +131,10 @@ module BSV
         File.join(@dir, 'actions.json')
       end
 
+      def settings_path
+        File.join(@dir, 'settings.json')
+      end
+
       def outputs_path
         File.join(@dir, 'outputs.json')
       end
@@ -128,6 +149,7 @@ module BSV
         @certificates = load_file(certificates_path)
         @proofs = load_proofs_file
         @transactions = load_transactions_file
+        @settings = load_settings_file
       end
 
       def load_file(path)
@@ -186,6 +208,22 @@ module BSV
         {}
       end
 
+      def save_settings
+        json = JSON.pretty_generate(stringify_keys_deep(@settings))
+        tmp = "#{settings_path}.tmp"
+        File.open(tmp, File::WRONLY | File::CREAT | File::TRUNC, 0o600) { |f| f.write(json) }
+        File.rename(tmp, settings_path)
+      end
+
+      def load_settings_file
+        return {} unless File.exist?(settings_path)
+
+        data = JSON.parse(File.read(settings_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"