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

**Inherits:** `Object`
**Includes:** `BSV::Wallet::Interface::Hydrator`

Hydration over the persisted proof store.

Given a signed transaction and the action it belongs to, the Hydrator walks
the ProofStore recursively until every input's `source_transaction` graph
terminates at a merkle-proven leaf, then assembles the Atomic BEEF the wallet
ships to its peer and proves it structurally valid before handoff. See
<code>Interface::Hydrator</code> for the full contract.

Store-reading (in deliberate contrast with `TxBuilder`'s store-free shape):
the <code>store:</code> handle is the only dependency.
<code>validate_for_handoff!</code> self-constructs its own
`TrustedSelfChainTracker` — the egress self-trust model the Hydrator owns, not
an engine dependency.

`wire_ancestor` is public — the one-way primitive the later BeefImporter
(ingress) extraction consumes for trustSelf hydration of incoming BEEFs.

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

## Public Instance Methods
### `build_atomic_beef(raw_tx, action_id)` <a id="method-i-build_atomic_beef"></a> <a id="build_atomic_beef-instance_method"></a>
See +Interface::Hydrator#build_atomic_beef+.

Outgoing BEEF: constructed from our own ProofStore —verification is for
incoming untrusted data only (see
+BeefImporter#verify_incoming_transaction!+).

### `initialize(store:, cache: = nil)` <a id="method-i-initialize"></a> <a id="initialize-instance_method"></a>
Construct a hydrator. Explicit DI: no engine back-reference, no
`chain_tracker` injection. The hydrator reads the store via `find_proof`
(during `wire_ancestor`) and `resolve_inputs_for_signing` (during
`build_atomic_beef`).

`cache` is the shared `HydratedTxCache` (#296 Phase D) the deep walk reads
through and proof-arrival enriches. Defaults to a private cache so a bare
+Hydrator.new(store:)+ still memoises; the daemon/engine inject a single
shared instance so the same substrate serves `Broadcast` (EF) and proof
acquisition.
- **@return** [Hydrator] a new instance of Hydrator

### `proof_arrived(wtxid:, raw_tx:, merkle_path:)` <a id="method-i-proof_arrived"></a> <a id="proof_arrived-instance_method"></a>
See +Interface::Hydrator#proof_arrived+.

### `validate_for_handoff!(atomic_beef, subject_wtxid, allow_txid_only: = false)` <a id="method-i-validate_for_handoff-21"></a> <a id="validate_for_handoff!-instance_method"></a>
See +Interface::Hydrator#validate_for_handoff!+.

The wallet trusts its own persisted proofs (those were validated against a
real chain_tracker at proof-arrival time), so a structural-only verify with
`TrustedSelfChainTracker` is sufficient and correct here: pass iff every leaf
in the BEEF terminates at a `merkle_path` or wires through to one (or, when
<code>allow_txid_only:</code> is set, at a `TxidOnlyEntry` the peer will fill
from local state). Failure means the wallet's state cannot produce a valid
handoff BEEF — almost always an upstream proof-closure gap that should have
been caught at import or `save_beef_proofs` time.

+Beef#verify+ (vs +Tx#verify+) is the deliberate primitive: +Tx#verify+ does
not accept <code>allow_txid_only:</code>, so a trimmed BEEF (HLR #385, Task 3
/ #388) would always reject. +Beef#verify+ returns a Boolean; coarser than the
+VerificationError#code+ the previous implementation surfaced. Callers wanting
richer diagnostics should log around the call site (the trade-off is accepted
in #385 Task 4 / #389).
- **@raise** [BSV::Wallet::EgressBeefInvalidError]

### `wire_ancestor(wtxid, visited: = Set.new)` <a id="method-i-wire_ancestor"></a> <a id="wire_ancestor-instance_method"></a>
See +Interface::Hydrator#wire_ancestor+.