# Class BSV::Wallet::Engine::HydratedTxCache <a id="class-BSV-Wallet-Engine-HydratedTxCache"></a>

**Inherits:** `Object`

Bounded in-process LRU cache for hydration bytes, keyed by `wtxid`
(wire-order, 32-byte binary). Each entry is an immutable +{ raw_tx:,
merkle_path: }+ pair — the same shape a `tx_proofs` row carries — **not** a
<code>Transaction::Tx</code> object. Bytes (not objects) sidestep the mutation
hazard of sharing a wired `source_transaction` graph across concurrent reactor
fibers.

The cache is the shared substrate both egress paths read through:

    - +Hydrator#wire_ancestor+ (deep, BEEF): a hit whose
      +merkle_path+ is present is a proven terminal — return without
      descending. A hit without one is recursed over. A miss reads
      +Store#find_proof+ and populates the entry.
    - +Broadcast#hydrated_transaction_for+ (shallow, EF): a hit on an
      input's parent wtxid supplies that input's source satoshis +
      locking script (from +outputs[vout]+) without the
      +resolve_inputs_for_signing+ JOIN — which stays the floor on a
      miss.

## Monotonic enrichment, no invalidation

State only ever progresses: entries are added; an entry's `merkle_path` is
filled in place when a proof arrives (+Hydrator#proof_arrived+ → `put`);
nothing degrades except by LRU age-out under memory pressure. `put` never
clears a `merkle_path` that is already set, so a proven terminal stays proven
regardless of call order. There are no lifecycle eviction hooks — broadcast
outcome is irrelevant to the cache (cf. #269, which this inverts).

## Principle of state

The cache is a pure projection over the proof store: each value mirrors a
`tx_proofs` row. Drop the cache and rebuild from the DB and behaviour is
identical — correctness rides on the DB, performance rides on the cache. See
<code>docs/reference/principle-of-state.md</code>.

Implementation: Ruby's `Hash` preserves insertion order (MRI 1.9+), so
<code>#delete</code>-then-<code>#[]=</code> moves an entry to the MRU end; LRU
eviction is a <code>#shift</code> of the oldest entries when over capacity. A
`Mutex` guards every operation; under the daemon's Async reactor an
uncontended Mutex acquire does not park the reactor.

## Constants
### `DEFAULT_CAPACITY` <a id="constant-DEFAULT_CAPACITY"></a> <a id="DEFAULT_CAPACITY-constant"></a>
Not documented.

## Attributes
### `capacity` [R] <a id="attribute-i-capacity"></a> <a id="capacity-instance_method"></a>
Returns the value of attribute capacity.

## Public Class Methods
### `from_config()` <a id="method-c-from_config"></a> <a id="from_config-class_method"></a>
Construct from the central config
(<code>BSV::Wallet.config.tx_cache_size</code>).

## Public Instance Methods
### `empty?()` <a id="method-i-empty-3F"></a> <a id="empty?-instance_method"></a>
- **@return** [Boolean]

### `get(wtxid)` <a id="method-i-get"></a> <a id="get-instance_method"></a>
- **@param** `wtxid` [String] 32-byte wire-order wtxid
- **@return** [Hash, nil] frozen +{ raw_tx:, merkle_path: }+ or nil on miss

### `initialize(capacity: = DEFAULT_CAPACITY)` <a id="method-i-initialize"></a> <a id="initialize-instance_method"></a>
- **@param** `capacity` [Integer] maximum number of entries; 0 disables
storage (always-miss cache, useful for tests).
- **@raise** [ArgumentError]
- **@return** [HydratedTxCache] a new instance of HydratedTxCache

### `put(wtxid, raw_tx:, merkle_path: = nil)` <a id="method-i-put"></a> <a id="put-instance_method"></a>
Insert or update the entry for `wtxid`. Monotonic on `merkle_path`: a `nil`
argument never clears an already-present path, so callers that only hold
`raw_tx` (an unconfirmed wire-up) cannot regress a proven terminal. `raw_tx`
is immutable for a given wtxid, so overwriting it is a no-op in practice.
Promotes the entry to MRU.
- **@param** `wtxid` [String] 32-byte wire-order wtxid
- **@param** `raw_tx` [String] transaction bytes (wire format)
- **@param** `merkle_path` [String, nil] serialized merkle path, or nil

### `size()` <a id="method-i-size"></a> <a id="size-instance_method"></a>
- **@return** [Integer] current entry count.