bsv-wallet 0.3.4 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1f3c7d9f919b64229f0c2c9c99a05fbd58850803af74861157f884ade90f7af6
-  data.tar.gz: c655fbf296f6a4a3ed554681b8ab673c8dd3d108d37e6832cbf48814b3ed2169
+  metadata.gz: bf66409b10a18ba1c43a05efb6e7909e4ba83a87d4421a68248f3f3174a8483d
+  data.tar.gz: 2ae27d6080353acb67b11e557e5e38c063abd243e1a36e2bc4c6ee6fa43fc885
 SHA512:
-  metadata.gz: 87e2b8653d787445a281fb78393e380857799852908487cbef82af26a3e1e04f16df5f67ce295ed4162742527d7ebc5d1380b4670f8a949b78d4c44524e6ab66
-  data.tar.gz: 9d288d1787f7448278eb95de1e96e41384e0c06141c755812549b9bc693c0269b8361cf31982f6b38472be3418ef575e7f373bde11d3ef0892743041c14dab10
+  metadata.gz: ad6a39da955d05c18460291ec2f1e7f56cae7c3a82d32da175477ea62c3e82bfd4dcce11bd9c4a53236b38b6091176badb55b264e05489e71722ab6ca8a651df
+  data.tar.gz: 3724b1e7cbb060a750eb865688b2859645a7837e05fd964214f2c8852ebd4aa515c8ee1afa51bd9fd50fd7bde0c9aa8299e0766057c40196b169e5f595db82fc

data/CHANGELOG-wallet.md

@@ -0,0 +1,332 @@
+# Changelog — bsv-wallet
+
+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
+
+- **Protocol-ID normalisation** (F8.7): `Validators.validate_protocol_id!` now
+  strips and downcases the name before applying rules, so `' MyProtocol '` and
+  `'myprotocol'` are treated identically and cannot silently fork to different
+  key-derivation paths.
+- **Permission-rule constants** (F8.8): Reserved prefix/suffix strings are now
+  named constants on `BSV::Wallet::Validators` (`RESERVED_PROTOCOL_PREFIXES`,
+  `RESERVED_PROTOCOL_SUFFIX`, `RESERVED_BASKET_PREFIXES`, `RESERVED_BASKET_SUFFIX`,
+  `RESERVED_BASKET_NAME`), making them discoverable and documentable.
+- **BEEF verification in `internalize_action`** (F8.14): The BEEF bundle is now
+  verified via `Beef#verify` before any outputs are stored. If the bundle is
+  structurally invalid, a `WalletError` is raised rather than storing unverified
+  data. When the chain provider supports `valid_root_for_height?`, full SPV
+  verification is performed.
+- **Depth cap and cycle detection in `wire_source_tx_ancestors`** (F8.18):
+  Recursion is now bounded by `WalletClient::ANCESTOR_DEPTH_CAP` (64 levels)
+  and a visited-txid `Set`, preventing stack overflow on deep or cyclic
+  transaction ancestry chains.
+
+### Changed
+
+- **`ProtoWallet#create_signature` default counterparty** (P305.1): The default
+  value for `counterparty` has changed from `'self'` to `'anyone'`, matching the
+  behaviour of `ts-sdk`'s `ProtoWallet.createSignature`. Callers that rely on
+  the `'self'` derivation path when omitting `counterparty:` must now pass
+  `counterparty: 'self'` explicitly.
+
+### Migration notes
+
+**P305.1 — `create_signature` counterparty default change (breaking)**
+
+Previously, calling `wallet.create_signature({ protocol_id: ..., key_id: ...,
+data: ... })` without a `counterparty:` key would derive using `'self'`. It now
+derives using `'anyone'`. This changes the resulting private key and therefore
+the signature. If your application omits `counterparty:`, add
+`counterparty: 'self'` to preserve the old behaviour.
+
+**F8.14 — BEEF verification now mandatory in `internalize_action`**
+
+Calls to `internalize_action` that previously succeeded with a malformed or
+unverifiable BEEF will now raise `BSV::Wallet::WalletError`. In practice this
+only affects callers passing synthetic or hand-crafted BEEF bytes; legitimate
+BEEF produced by `create_action` or broadcast round-trips will continue to work.
+
+### Added
+
+- **Shared conformance suite** for `StorageAdapter`
+  implementations at `spec/support/shared_examples_for_storage_adapter.rb`.
+  `MemoryStore` and `FileStore` now both drive their behavioural
+  tests through `it_behaves_like 'a storage adapter'`, and the
+  extraction backfilled previously-missing coverage (certificate
+  `:attributes` filter, `count_certificates`, proof and transaction
+  round-trip, pagination ordering).
+
+## 0.3.4 — 2026-04-08
+
+Paired security patch release. Three P0 findings from the
+[2026-04-08 cross-SDK compliance review](.architecture/reviews/20260408-cross-sdk-compliance-review.md)
+plus follow-up hardening from the PR review pass. Must be installed
+together — the `bsv-wallet` gemspec now pins its `bsv-sdk` dependency
+to `>= 0.8.2, < 1.0` to enforce the paired upgrade and prevent a stale
+pair where one gem has its fixes and the other doesn't.
+
+Two GitHub Security Advisories accompany this release (draft until
+CVE IDs return from MITRE):
+
+
+### Security
+
+- **`acquire_certificate` now verifies certifier signatures** before
+  persisting (BRC-52). Both the `'direct'` and `'issuance'` acquisition
+  paths previously wrote user-supplied `signature:` values to storage
+  without any verification — a caller could forge a certificate that
+  `list_certificates` / `prove_certificate` would later treat as
+  authentic. This was a credential forgery primitive masquerading as
+  an API finding. The new `BSV::Wallet::CertificateSignature` module
+  builds the canonical BRC-52 preimage (matching the TS reference
+  `Certificate#toBinary(false)` byte-for-byte) and delegates to
+  `ProtoWallet#verify_signature`. Invalid certificates raise
+  `BSV::Wallet::CertificateSignature::InvalidError` and are not
+  persisted. Closes F8.15 (and the verification aspect of F8.16).
+
+
+
+### Changed
+
+- **`bsv-wallet.gemspec` bsv-sdk dependency pinned** to
+  `>= 0.8.2, < 1.0`. The previous `~> 0.4` constraint was stale (wallet
+  hasn't been tested against bsv-sdk 0.4.x in months) and would have
+  let a user install `bsv-wallet 0.3.4` against an old `bsv-sdk` that
+  was missing F1.3 and F5.13. Technically breaking — any consumer
+  pinned to `bsv-sdk < 0.8.2` must upgrade — but un-breaking in
+  practice: it forces users to the known-good pair rather than a
+  silently-broken combination.
+
+### Internal
+
+- `lib/bsv/wallet_interface/**/*` added to the
+  `Metrics/ModuleLength` exclusion list (was previously only excluded
+  from `Metrics/ClassLength`). The new `CertificateSignature` module
+  triggered the discrepancy.
+- Review-feedback hardening bundled into the same PR to
+  keep the security-patch window small: case-insensitive ARC failure
+  matching, `Base64.strict_decode64` on BRC-52 preimage fields,
+  `EncodingError` rescue in `CertificateSignature.verify!`, rejection
+  of mixed string / symbol duplicate field names, malformed 2xx
+  rejection in ARC, and even-length guard on hex signatures.
+
+### Migration notes
+
+- **Existing `bsv-wallet` users** pinned to `bsv-sdk ~> 0.4` will need
+  to relax their constraint or upgrade. Anything installed before
+  `bsv-wallet 0.3.4` is vulnerable to the F8.15 certificate forgery
+  primitive.
+- **Callers passing negative integers to `VarInt.encode`** (unlikely —
+  the docstring already disallowed it) will now get an `ArgumentError`
+  instead of silent corruption. Fix: pass non-negative values.
+- **Callers relying on ARC broadcaster silently succeeding for INVALID
+  / MALFORMED / MINED_IN_STALE_BLOCK / ORPHAN responses** will now see
+  `BroadcastError` raised. Fix: handle the error — the previous
+  behaviour was objectively wrong and any downstream logic that
+  tolerated it was silently corrupt.
+- **Callers of `acquire_certificate` with a fake or untrusted
+  `signature:` field** will now see
+  `BSV::Wallet::CertificateSignature::InvalidError`. Fix: ensure the
+  certificate has been properly signed by the declared certifier.
+
+### Test suite
+
+- 3112 examples, 0 failures (up from 3080 on 0.8.1)
+- 16 new regression tests for F1.3, F5.13, and F8.15
+- 16 further regression tests for the review-feedback hardening
+- Ruby 2.7 — 3.4 matrix green
+- CodeQL clean; RuboCop clean across 266 files
+
+## 0.3.3 — 2026-04-06
+
+### Fixed
+
+- `finalize_action` now stores the spending transaction so subsequent
+  `internalize_action` / proof resolution flows can find it. Previously the
+  wallet remembered the inputs and outputs but not the finalised tx itself.
+
+## 0.3.2 — 2026-04-06
+
+### Fixed
+
+- `internalize_action` now stores **all** transactions from the
+  incoming BEEF, not just the proven ones. Unproven ancestors are needed for
+  later BEEF reconstruction in `create_action` → `to_beef`.
+
+## 0.3.1 — 2026-04-06
+
+### Fixed
+
+- `internalize_action` now stores the subject transaction hex (not
+  just its proof and outputs), so the wallet can rebuild BEEF for spends of
+  the inbound outputs without re-fetching the tx.
+
+## 0.3.0 — 2026-04-06
+
+### Added
+
+- **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.
+- `StorageAdapter` gains `store_proof`, `find_proof`,
+  `store_transaction`, `find_transaction` methods, implemented in both
+  `MemoryStore` and `FileStore`.
+
+### Fixed
+
+- `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.2.2 — 2026-04-06
+
+### Fixed
+
+- `to_beef` now includes source transactions in the BEEF output, not
+  just the subject transaction. Without ancestors, ARC could not validate the
+  spend graph.
+
+## 0.2.1 — 2026-04-06
+
+### Added
+
+- `WalletClient#create_action` now accepts `UnlockingScriptTemplate`
+  objects (e.g. `P2PKH`) as input unlocking scripts, enabling template-based
+  signing without BEEF.
+- `wire_source_from_storage` fallback populates `source_satoshis`
+  and `source_locking_script` from wallet storage when BEEF is absent or
+  incomplete, enabling BIP-143 sighash computation for wallet-tracked
+  outputs.
+- `finalize_action` resolves template inputs via `sign_all` before
+  serialisation.
+- `MemoryStore#filter_outputs` supports outpoint filtering for
+  efficient single-output lookups.
+
+The sdk gem was re-released alongside this wallet change with no
+behavioural changes of its own.
+
+## 0.2.0 — 2026-04-01
+
+### Added
+
+#### Primitives
+
+
+#### Transaction
+
+
+#### Wallet
+
+- **FileStore** — JSON file-backed persistent storage, now the
+  default for `WalletClient`. Data survives process restarts. `MemoryStore`
+  becomes explicit opt-in for tests.
+- **File permissions** — directory created with 0700, files with
+  0600. Warns via Logger on startup if permissions are too open.
+
+## 0.1.2 — 2026-03-30
+
+### Added
+
+#### Script
+
+
+#### Transaction
+
+
+#### Wallet
+
+- **BRC-31 Auth/Peer** — mutual authentication with nonce-based
+  challenges, ECDSA signatures, and session management.
+- **BRC-100 wire protocol** — binary ABI serialisation for all 28
+  BRC-100 methods (call codes 1-28, VarInt encoding).
+- **Certificate issuance** — `acquire_certificate` with
+  `'issuance'` protocol (POST to certifier URL).
+
+### Fixed
+
+- Subject and certifier pinned in certificate issuance response
+  (not overridable by remote certifier).
+- Wire reader negative `privileged_reason` length crash.
+
+This was the first formal `bsv-wallet` gem release tag. Wallet code that
+landed in master before this date (notably the BRC-100 identity certificate
+methods and the BRC-100 blockchain-data / authentication methods committed
+during the sdk-0.3.1 window) is part of this gem's initial released state.

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