bsv-sdk 0.8.0 → 0.8.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: efdb265c4e97396d1769a3652cbe04c57ad154035d2d990f118e343bbe7fafa8
-  data.tar.gz: c955e289d5b4316db586980bc02287d29d2e973ac071b5be5ca33298f6e647a5
+  metadata.gz: 534417702a1c6fe35494ff3d7bc028d302452fc21312747cd83167137fab43c7
+  data.tar.gz: d7aca5b47d7f853f41142d2ae9087351bf0160beb0b25959330e7e380bbb5d92
 SHA512:
-  metadata.gz: a2ca1b5d8d35586daa3da201ebf137e5aa01034452b931185b7804add1537c35db0f1d95463676dbb060b1475a41b236fa178dee2bdcd748051b27a6ce9c40ea
-  data.tar.gz: fa8c3e8f7b4a1ad2b5b9870fbccc65c0fbbc85c9b55607f00068dfcf008c4bfee403df05777106ac54c3c7ee0384841bc258f0f8e918a852578fb65309415502
+  metadata.gz: 109f3d7d92f210bb3bc5df4e2defaec5322be06b33a467023109fef27d1c9ffe8ca2f876b865b9a4e9f21ef69e9f5d19dd8fde5b02cefdd58f3ee2ac58cfae41
+  data.tar.gz: 70145605156016e9fbcd6a4c397a317358ad3142c97637d6ad8a849934ac8d356f40c555e55af178280693c3c4d6b1d3f76af8f10df5526e6fde6fefdef928c5

data/CHANGELOG.md

@@ -21,6 +21,185 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and each gem adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html)
 independently.
 
+## sdk-0.8.2 / wallet-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):
+
+- [GHSA-hc36-c89j-5f4j](.security/advisories/2026-0001-acquire-certificate-signature-bypass.md) — F8.15 / F8.16 partial — `acquire_certificate` persists unverified certifier signatures (CWE-347, CVSS 8.1 HIGH)
+- [GHSA-9hfr-gw99-8rhx](.security/advisories/2026-0002-arc-broadcaster-failure-statuses.md) — F5.13 — ARC broadcaster treats failure statuses as success (CWE-754, CVSS 7.5 HIGH)
+
+### Security
+
+- [wallet] **`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).
+
+- [sdk] **`VarInt.encode` now rejects negative integers** and values
+  above 2^64 − 1. Previously `VarInt.encode(-1)` fell into the single-
+  byte branch and emitted `0xFF` (the marker for a 9-byte encoding),
+  silently corrupting the transaction stream with no exception raised.
+  The docstring already required a non-negative integer; the
+  implementation did not enforce it. Closes F1.3.
+
+- [sdk] **ARC broadcaster recognises the full failure status set**. The
+  previous `REJECTED_STATUSES` contained only `REJECTED` and
+  `DOUBLE_SPEND_ATTEMPTED`; responses with txStatus `INVALID`,
+  `MALFORMED`, `MINED_IN_STALE_BLOCK`, or any `ORPHAN`-containing
+  `txStatus` / `extraInfo` were silently treated as successful
+  broadcasts. Callers relying on `broadcast()` to signal failure would
+  trust transactions that were never actually accepted by the network.
+  The new failure set matches the TypeScript reference broadcaster
+  exactly, and case-insensitive matching defends against ARC's
+  documented history of emitting values outside its own OpenAPI enum
+  (TS issue #105). Malformed 2xx responses without a `txid` field
+  also raise, closing the same silent-success class for shape
+  corruption. Closes F5.13.
+
+### Changed
+
+- [sdk] **ARC broadcaster HTTP wire format** brought into line with the
+  TypeScript reference:
+  - Content-Type is now `application/json` (was `application/octet-stream`)
+  - Body is `{"rawTx": hex}` — Extended Format (BRC-30) hex when every
+    input has `source_satoshis` / `source_locking_script` populated
+    (so ARC can validate sighashes without fetching parents), falling
+    back to plain raw-tx hex otherwise
+  - New `XDeployment-ID` header (default: `bsv-ruby-sdk-<random hex>`,
+    overridable via `deployment_id:` constructor kwarg)
+  - New optional `X-CallbackUrl` and `X-CallbackToken` constructor
+    kwargs for ARC status callbacks
+
+- [wallet] **`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
+
+- [sdk] `lib/bsv/network/**/*` added to `Metrics/ClassLength` and
+  `Metrics/ParameterLists` RuboCop exclusion lists to match the
+  existing treatment of `lib/bsv/wallet_interface/**/*`. ARC is
+  HTTP-client boilerplate in the same shape.
+- [wallet] `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.
+- [sdk, wallet] 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
+
+## sdk-0.8.1 — 2026-04-08
+
+### Fixed
+
+- [sdk] **`Transaction#to_beef` strips phantom `txid: true` leaves** —
+  when a proof loaded from a shared `LocalProofStore` carries txid flags
+  for transactions that are not part of the bundle being constructed,
+  `to_beef` now rebuilds each per-block BUMP from only the bundle's own
+  txids instead of propagating the phantoms into the serialised output.
+  ARC previously rejected such BEEFs with misleading parser errors,
+  blocking any wallet workflow that received a BEEF via
+  `internalize_action` and then spent the internalised UTXOs.
+  Closes #302.
+
+### Added
+
+- [sdk] **`MerklePath#extract(txid_hashes)`** — returns a new trimmed
+  compound path covering only the requested txids, reconstructing the
+  minimum set of sibling hashes at each tree level. Raises
+  `ArgumentError` on empty input, unknown txid, or root mismatch.
+  Ported from the TypeScript SDK. Used internally by
+  `Transaction#to_beef` and available for direct use.
+- [sdk] **`MerklePath#trim`** — removes internal nodes not required by
+  level-zero txid leaves. Called implicitly by `#combine` and `#extract`
+  and rarely needs to be invoked directly. Ported from the TypeScript
+  SDK.
+- [sdk] **`MerklePath#initialize_copy`** — `.dup` now produces a new
+  MerklePath whose outer and level arrays are independent of the
+  source, so the copy can be freely mutated via `#combine`, `#trim`,
+  or `#extract` without affecting the original. `PathElement`s
+  remain immutable and are shared between source and copy.
+
+### Changed
+
+- [sdk] **`MerklePath#combine`** now calls `#trim` at the end so merged
+  paths stay minimal across repeated merges, matching the TypeScript
+  SDK. Combined paths are strictly smaller than before — external
+  callers that inspected `mp.path` after `#combine` may see fewer
+  nodes, though every txid leaf's merkle proof is preserved.
+- [sdk] **`MerklePath#combine`** also preserves `txid: true` flags when
+  the incoming leaf is flagged and the existing leaf at the same offset
+  isn't, so merging an ancestor's single-leaf proof into a compound
+  that already contains the same offset as a sibling no longer loses
+  the txid flag.
+- [sdk] **`Transaction#to_beef`** now raises `ArgumentError` if an
+  ancestor's merkle path doesn't actually contain that transaction's
+  txid, or if the rebuilt BUMP's root doesn't match the source root.
+  Previously such corrupt proof data would silently emit a broken BEEF.
+  Callers relying on `to_beef` not raising on valid data are
+  unaffected; the new exception only triggers on corrupt proof stores.
+
+### Internal
+
+- [sdk] **`Beef#merge_transaction`** indirectly benefits from the
+  tighter `#combine` + `#trim` behaviour: compound BUMPs no longer
+  accumulate dead sibling hashes across repeated merges.
+- [sdk] On the real-world `#302` regression fixture, the cleaned BUMP
+  shrinks from 2476 B to 1300 B (47% reduction) as a side effect of
+  `#extract` removing intermediate siblings that are no longer needed
+  once phantom leaves are gone.
+
 ## sdk-0.8.0 — 2026-04-08
 
 ### Added

data/lib/bsv/network/arc.rb

@@ -3,6 +3,7 @@
 require 'net/http'
 require 'json'
 require 'uri'
+require 'securerandom'
 
 module BSV
   module Network
@@ -14,16 +15,48 @@ module BSV
     # The HTTP client is injectable for testability. It must respond to
     # #request(uri, request) and return an object with #code and #body.
     class ARC
-      REJECTED_STATUSES = %w[REJECTED DOUBLE_SPEND_ATTEMPTED].freeze
-
-      def initialize(url, api_key: nil, http_client: nil)
+      # ARC response statuses that indicate the transaction was NOT accepted.
+      # Matches the TypeScript SDK's ARC broadcaster failure set (issue #305,
+      # finding F5.13). Prior to this fix, Ruby only recognised REJECTED and
+      # DOUBLE_SPEND_ATTEMPTED, silently treating INVALID / MALFORMED /
+      # MINED_IN_STALE_BLOCK responses as successful broadcasts.
+      REJECTED_STATUSES = %w[
+        REJECTED
+        DOUBLE_SPEND_ATTEMPTED
+        INVALID
+        MALFORMED
+        MINED_IN_STALE_BLOCK
+      ].freeze
+
+      # Substring match for orphan detection in txStatus or extraInfo fields.
+      ORPHAN_MARKER = 'ORPHAN'
+
+      # @param url [String] ARC base URL (without trailing slash)
+      # @param api_key [String, nil] optional bearer token for Authorization
+      # @param deployment_id [String, nil] optional deployment identifier for
+      #   the +XDeployment-ID+ header; defaults to a per-instance random value
+      # @param callback_url [String, nil] optional +X-CallbackUrl+ for ARC
+      #   status callbacks
+      # @param callback_token [String, nil] optional +X-CallbackToken+ for
+      #   ARC status callback authentication
+      # @param http_client [#request, nil] injectable HTTP client for testing
+      def initialize(url, api_key: nil, deployment_id: nil, callback_url: nil,
+                     callback_token: nil, http_client: nil)
         @url = url.chomp('/')
         @api_key = api_key
+        @deployment_id = deployment_id || "bsv-ruby-sdk-#{SecureRandom.hex(8)}"
+        @callback_url = callback_url
+        @callback_token = callback_token
         @http_client = http_client
       end
 
       # Submit a transaction to ARC.
       #
+      # The transaction is encoded as Extended Format (BRC-30) hex when every
+      # input has +source_satoshis+ and +source_locking_script+ populated,
+      # which lets ARC validate sighashes without fetching parents. Falls back
+      # to plain raw-tx hex when EF is unavailable.
+      #
       # @param tx [Transaction] the transaction to broadcast
       # @param wait_for [String, nil] ARC wait condition — one of
       #   'RECEIVED', 'STORED', 'ANNOUNCED_TO_NETWORK',
@@ -31,14 +64,18 @@ module BSV
       #   connection open until the transaction reaches the requested
       #   state (or times out). Defaults to nil (no wait).
       # @return [BroadcastResponse]
-      # @raise [BroadcastError]
+      # @raise [BroadcastError] when ARC returns a non-2xx HTTP status or a
+      #   rejected/orphan +txStatus+
       def broadcast(tx, wait_for: nil)
         uri = URI("#{@url}/v1/tx")
         request = Net::HTTP::Post.new(uri)
-        request['Content-Type'] = 'application/octet-stream'
+        request['Content-Type'] = 'application/json'
+        request['XDeployment-ID'] = @deployment_id
         request['X-WaitFor'] = wait_for if wait_for
+        request['X-CallbackUrl'] = @callback_url if @callback_url
+        request['X-CallbackToken'] = @callback_token if @callback_token
         apply_auth_header(request)
-        request.body = tx.to_binary
+        request.body = JSON.generate(rawTx: raw_tx_hex(tx))
 
         response = execute(uri, request)
         handle_broadcast_response(response)
@@ -49,6 +86,7 @@ module BSV
       def status(txid)
         uri = URI("#{@url}/v1/tx/#{txid}")
         request = Net::HTTP::Get.new(uri)
+        request['XDeployment-ID'] = @deployment_id
         apply_auth_header(request)
 
         response = execute(uri, request)
@@ -57,6 +95,15 @@ module BSV
 
       private
 
+      # Prefer Extended Format (BRC-30) hex so ARC can validate sighashes
+      # without fetching parent transactions. Falls back to plain raw-tx hex
+      # when any input lacks source_satoshis / source_locking_script.
+      def raw_tx_hex(tx)
+        tx.to_ef_hex
+      rescue ArgumentError
+        tx.to_hex
+      end
+
       def apply_auth_header(request)
         request['Authorization'] = "Bearer #{@api_key}" if @api_key
       end
@@ -83,20 +130,45 @@ module BSV
           )
         end
 
-        tx_status = body['txStatus']
-        if rejected_status?(tx_status)
+        if rejected_status?(body)
           raise BroadcastError.new(
-            body['detail'] || body['title'] || tx_status,
+            body['detail'] || body['title'] || body['txStatus'],
             status_code: code,
             txid: body['txid']
           )
         end
 
+        # A 2xx response without a txid is a malformed ARC reply —
+        # `parse_json` falls back to `{'detail' => raw}` on non-JSON,
+        # which would otherwise produce a `BroadcastResponse` full of
+        # `nil`s and `success? => true`. That's the same silent
+        # success-as-failure class of bug F5.13 closed for explicit
+        # error statuses; closing it here for shape corruption too.
+        unless body['txid']
+          raise BroadcastError.new(
+            'ARC returned a malformed 2xx response',
+            status_code: code
+          )
+        end
+
         build_response(body)
       end
 
-      def rejected_status?(tx_status)
-        REJECTED_STATUSES.include?(tx_status)
+      def rejected_status?(body)
+        # Case-insensitive match — the TypeScript reference
+        # (`ts-sdk/src/transaction/broadcasters/ARC.ts:155-166`) explicitly
+        # `.toUpperCase()`s both fields before membership / substring checks.
+        # ARC has a documented history of emitting values outside its own
+        # OpenAPI enum (e.g. `txStatus: "success"` for orphans in TS issue
+        # #105), so case normalisation is the defensive choice.
+        tx_status = body['txStatus'].to_s.upcase
+        return true if REJECTED_STATUSES.include?(tx_status)
+        return true if tx_status.include?(ORPHAN_MARKER)
+
+        extra_info = body['extraInfo'].to_s.upcase
+        return true if extra_info.include?(ORPHAN_MARKER)
+
+        false
       end
 
       def parse_json(raw)

data/lib/bsv/transaction/merkle_path.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require 'set'
+
 module BSV
   module Transaction
     # A BRC-74 merkle path (BUMP — Bitcoin Unified Merkle Path).
@@ -50,6 +52,19 @@ module BSV
         @path = path
       end
 
+      # Produce an independent copy: a new MerklePath whose outer +path+
+      # array and each inner level array can be mutated (via {#combine},
+      # {#trim}, {#extract}) without affecting the original. PathElements
+      # themselves are immutable and are shared between the original and
+      # the copy.
+      #
+      # @param source [MerklePath] the MerklePath being copied from
+      # @return [void]
+      def initialize_copy(source)
+        super
+        @path = source.path.map(&:dup)
+      end
+
       # --- Binary serialisation (BRC-74) ---
 
       # Deserialise a merkle path from BRC-74 binary format.
@@ -270,7 +285,11 @@ module BSV
       # Merge another merkle path into this one.
       #
       # Both paths must share the same block height and merkle root.
-      # After combining, this path contains the union of all leaves.
+      # After combining, this path contains the union of all leaves,
+      # trimmed to the minimum set required to prove every txid-flagged
+      # leaf. The trim matches the TS SDK's +combine+ behaviour and
+      # prevents accumulation of unnecessary sibling hashes across
+      # repeated merges.
       #
       # @param other [MerklePath] the path to merge in
       # @return [self] for chaining
@@ -289,16 +308,182 @@ module BSV
 
           existing = @path[h].to_h { |e| [e.offset, e] }
           other.path[h].each do |elem|
-            existing[elem.offset] ||= elem
+            # Preserve txid flag when combining: if the incoming leaf is
+            # flagged, never downgrade an existing entry.
+            if existing.key?(elem.offset)
+              existing_elem = existing[elem.offset]
+              if elem.txid && !existing_elem.txid
+                existing[elem.offset] = PathElement.new(
+                  offset: existing_elem.offset,
+                  hash: existing_elem.hash,
+                  txid: true,
+                  duplicate: existing_elem.duplicate
+                )
+              end
+            else
+              existing[elem.offset] = elem
+            end
           end
           @path[h] = existing.values.sort_by(&:offset)
         end
 
+        trim
         self
       end
 
+      # --- Trim ---
+
+      # Remove all internal nodes that are not required by level zero
+      # txid-flagged leaves. Assumes the path has at least the minimum
+      # set of sibling hashes needed to prove every txid leaf. Leaves
+      # each level sorted by increasing offset.
+      #
+      # This is the Ruby port of the TypeScript SDK's +MerklePath.trim+.
+      # It is called implicitly by {#combine} and {#extract} and rarely
+      # needs to be invoked directly.
+      #
+      # @return [self] for chaining
+      def trim
+        @path.each { |level| level.sort_by!(&:offset) }
+
+        computed_offsets = []
+        drop_offsets = []
+
+        @path[0].each_with_index do |node, i|
+          if node.txid
+            # level 0 must enable computing level 1 for every txid node
+            trim_push_if_new(computed_offsets, node.offset >> 1)
+          else
+            # Array-index peer — works for well-formed compound BUMPs
+            # where level 0 is a sequence of adjacent (txid, sibling) pairs.
+            peer_index = node.offset.odd? ? i - 1 : i + 1
+            peer = @path[0][peer_index] if peer_index.between?(0, @path[0].length - 1)
+            # Drop non-txid level 0 nodes whose peer is also non-txid
+            trim_push_if_new(drop_offsets, peer.offset) if peer && !peer.txid
+          end
+        end
+
+        trim_drop_offsets_from_level(drop_offsets, 0)
+
+        (1...@path.length).each do |h|
+          drop_offsets = computed_offsets
+          computed_offsets = trim_next_computed_offsets(computed_offsets)
+          trim_drop_offsets_from_level(drop_offsets, h)
+        end
+
+        self
+      end
+
+      # --- Extract ---
+
+      # Extract a minimal compound MerklePath covering only the specified
+      # transaction IDs.
+      #
+      # Given a compound path (e.g. one merged from multiple single-leaf
+      # proofs in the same block), this method reconstructs the minimum
+      # set of sibling hashes at each tree level for every requested txid,
+      # assembles them into a new trimmed compound path, and verifies
+      # that the extracted path computes the same merkle root as the
+      # source.
+      #
+      # The primary use case is +Transaction#to_beef+: when a BUMP loaded
+      # from a proof store carries +txid: true+ flags for transactions
+      # that are not part of the current BEEF bundle, extracting only the
+      # bundled txids strips the phantom flags (and the now-unneeded
+      # sibling nodes) from the serialised output. See issue #302 for
+      # background.
+      #
+      # Matches the TS SDK's +MerklePath.extract+ behaviour.
+      #
+      # @param txid_hashes [Array<String>] 32-byte txids in internal byte
+      #   order (reverse of display order). To pass hex strings, use
+      #   +txid_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
+      #   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?
+
+        original_root = compute_root
+        indexed = build_indexed_path
+
+        # Build a level-0 hash → offset lookup
+        txid_to_offset = {}
+        @path[0].each do |leaf|
+          txid_to_offset[leaf.hash] = leaf.offset if leaf.hash
+        end
+
+        max_offset = @path[0].map(&:offset).max || 0
+        tree_height = [@path.length, max_offset.bit_length].max
+
+        needed = Array.new(tree_height) { {} }
+
+        txid_hashes.each do |txid|
+          tx_offset = txid_to_offset[txid]
+          if tx_offset.nil?
+            raise ArgumentError,
+                  "transaction ID #{txid.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)
+          sib0_offset = tx_offset ^ 1
+          unless needed[0].key?(sib0_offset)
+            sib = offset_leaf(indexed, 0, sib0_offset)
+            needed[0][sib0_offset] = sib if sib
+          end
+
+          # Higher levels: just the sibling at each height
+          (1...tree_height).each do |h|
+            sib_offset = (tx_offset >> h) ^ 1
+            next if needed[h].key?(sib_offset)
+
+            sib = offset_leaf(indexed, h, sib_offset)
+            if sib
+              needed[h][sib_offset] = sib
+            elsif (tx_offset >> h) == (max_offset >> h)
+              # Rightmost path in a tree whose last leaf has no real sibling —
+              # BRC-74 represents this as a duplicate marker.
+              needed[h][sib_offset] = PathElement.new(offset: sib_offset, duplicate: true)
+            end
+          end
+        end
+
+        compound_path = needed.map { |level| level.values.sort_by(&:offset) }
+        compound = self.class.new(block_height: @block_height, path: compound_path)
+        compound.trim
+
+        extracted_root = compound.compute_root
+        unless extracted_root == original_root
+          raise ArgumentError,
+                "extracted path root #{extracted_root.reverse.unpack1('H*')} " \
+                "does not match source root #{original_root.reverse.unpack1('H*')}"
+        end
+
+        compound
+      end
+
       private
 
+      def trim_push_if_new(arr, value)
+        arr << value if arr.empty? || arr.last != value
+      end
+
+      def trim_drop_offsets_from_level(drop_offsets, level)
+        return if drop_offsets.empty?
+
+        drop_set = drop_offsets.to_set
+        @path[level].reject! { |node| drop_set.include?(node.offset) }
+      end
+
+      def trim_next_computed_offsets(offsets)
+        next_offsets = []
+        offsets.each { |o| trim_push_if_new(next_offsets, o >> 1) }
+        next_offsets
+      end
+
       def build_indexed_path
         @path.map do |level|
           level.to_h { |elem| [elem.offset, elem] }

data/lib/bsv/transaction/transaction.rb

@@ -299,24 +299,36 @@ module BSV
       # Transactions with a `merkle_path` are treated as proven leaves — their
       # ancestors are not traversed further.
       #
+      # Proven ancestors that share a block are combined into a single BUMP per
+      # block, then trimmed via {MerklePath#extract} so the serialised bundle
+      # carries only the +txid: true+-flagged leaves that correspond to
+      # transactions in this BEEF. This prevents "phantom" txid leaves carried
+      # over from a shared {LocalProofStore} entry (issue #302) and also
+      # shrinks the BEEF by dropping intermediate sibling hashes that are no
+      # longer needed.
+      #
+      # Ancestor +merkle_path+ objects are not mutated: paths are deep-copied
+      # before any combine/trim work.
+      #
       # @return [String] raw BEEF V1 binary
+      # @raise [ArgumentError] if an ancestor's merkle_path does not actually
+      #   contain that transaction's txid, or if the cleaned BUMP's root does
+      #   not match the source root (both indicate corrupt proof data)
       def to_beef
         beef = Beef.new
         ancestors = collect_ancestors
 
+        bump_index_by_height = build_beef_bumps(beef, ancestors)
+
         ancestors.each do |tx|
           entry = if tx.merkle_path
-                    bump_idx = beef.merge_bump(tx.merkle_path)
                     Beef::BeefTx.new(
                       format: Beef::FORMAT_RAW_TX_AND_BUMP,
                       transaction: tx,
-                      bump_index: bump_idx
+                      bump_index: bump_index_by_height.fetch(tx.merkle_path.block_height)
                     )
                   else
-                    Beef::BeefTx.new(
-                      format: Beef::FORMAT_RAW_TX,
-                      transaction: tx
-                    )
+                    Beef::BeefTx.new(format: Beef::FORMAT_RAW_TX, transaction: tx)
                   end
           beef.transactions << entry
         end
@@ -724,6 +736,35 @@ module BSV
         result << tx
       end
 
+      # Group proven ancestors by block height, combine each group into a
+      # single compound merkle path (without mutating the source paths), then
+      # extract just the txids actually in the bundle. The resulting clean
+      # BUMPs are appended to +beef.bumps+, one per block height.
+      #
+      # @return [Hash{Integer => Integer}] block height → bump index mapping
+      def build_beef_bumps(beef, ancestors)
+        proven_by_height = ancestors.each_with_object({}) do |tx, h|
+          next unless tx.merkle_path
+
+          (h[tx.merkle_path.block_height] ||= []) << tx
+        end
+
+        bump_index_by_height = {}
+        proven_by_height.each do |height, txs|
+          # Deep-dup the first source so combine/trim can't mutate caller state
+          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)
+
+          bump_index_by_height[height] = beef.bumps.length
+          beef.bumps << clean
+        end
+
+        bump_index_by_height
+      end
+
       def compute_fee_sats(model_or_fee)
         case model_or_fee
         when nil

data/lib/bsv/transaction/var_int.rb

@@ -10,11 +10,18 @@ module BSV
     module VarInt
       module_function
 
+      # Maximum value representable by a Bitcoin VarInt (unsigned 64-bit).
+      MAX_UINT64 = 0xFFFF_FFFF_FFFF_FFFF
+
       # Encode an integer as a Bitcoin VarInt.
       #
-      # @param value [Integer] non-negative integer to encode
+      # @param value [Integer] non-negative integer to encode (0..2^64-1)
       # @return [String] encoded binary bytes
+      # @raise [ArgumentError] if +value+ is negative or exceeds 2^64-1
       def encode(value)
+        raise ArgumentError, "varint requires non-negative integer, got #{value}" if value.negative?
+        raise ArgumentError, "varint value #{value} exceeds uint64 max (#{MAX_UINT64})" if value > MAX_UINT64
+
         if value < 0xFD
           [value].pack('C')
         elsif value <= 0xFFFF

data/lib/bsv/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: bsv-sdk
 version: !ruby/object:Gem::Version
-  version: 0.8.0
+  version: 0.8.2
 platform: ruby
 authors:
 - Simon Bettison