Join wallet restoration and computed balances with snapshot recovery

[a-shannon]

Release alignment and current review increment

This combined wallet review follows #2424, which now targets v6.0.7. Its own base remains the ergoplatform#2424 feature branch, keeping the integration increment visible. #2496 and selected P2P corrections remain the proposed 6.0.6 priorities; maintainers retain final release selection. The tracker records that order.

Compatibility review for #2424, #2409 and #2466, including its retention/scan follow-up. Current head 033992019219fb63ddca36bdc0888d7c1c6d153d is based on ergoplatform#2424 c9c6b760cee17c93edbc3064f2434af65b956918. The 26-file comparison (+2737/-440) retains those feature owners and adds the shared header/body-cache wake-up correction owned by upstream #2549.

The prior release alignment changed only the API and handshake version markers from 6.0.5 to 6.0.7, with no merge conflicts. Its 22-file increment exactly matched the previous 22-file patch. Those source comparisons and earlier eight-job successes apply to their historical inputs.

The prior three-file diagnostic increment preserves the two-minute initial-seed assertion, mining targets, isolation and twenty-minute overall deadline. Eight or ten concurrent endpoint observations use a separate three-second post-failure budget and rethrow the original timeout; passing runs add no requests. Integration compilation and five direct tests passed, with independent source review. Those diagnostics remain in the current tree; the earlier production-unchanged claim applies only to that diagnostic increment.

The latest two-path increment reuses exact common commit X a772a5cbf666584db3ed981838dbc11223d502ed, whose sole upstream owner is #2549. Remote body sections could arrive before their header, enter the cache and stop delivery retries, then remain unapplied when header-only processing did not revisit that cache. Header processing now drains the existing body cache after its header cache, through unchanged validation and application paths. The real UTXO/Digest holder cases were 0/2 before the fix and 2/2 after it with unchanged tests; the actual v6.0.6 owner composition also passed 2/2. Independent source and composition review found no must-fix issue. The tests prove persistence and state version/root advancement after header-only delivery; they do not execute network negotiation or establish exclusive causality for earlier CI stalls.

Current CI, observed 2026-09-13 01:17 UTC at 033992019219fb63ddca36bdc0888d7c1c6d153d, is 7/8; node job running. Integration passed 50/50 cases across 12 suites, with none ignored. The upstream ergoplatform#2549 owner passed all eight checks, including integration 22/22 across 12 suites, with one ignored. Historical 9bbc run 34727875148 completed with four successful jobs, two failures and two wallet cancellations: 49 of 50 integration cases passed; the initial-seed readiness case failed, while wallet Scala 2.11 failed setup before tests. The specific setup cause is unproven. Earlier a33c44ae attempt 1 had matching headers at 32 and full-block heights A32/B18; attempt 2 had headers at 31 and full-block heights A31/B30. Mining was disabled and isolation had not started; each had 44 of 45 cases pass, including UTXO convergence. Current CI qualification remains separate from all historical results.

Two interactions require corrections. First, ergoplatform#2466's one-time startup request can be rejected while ergoplatform#2424 is still aligning the wallet. Register one correlated restoration request instead, then fulfill it after the wallet actually becomes operational. A coalesced self-message checks the current guards after the enclosing transition finishes. The holder accepts only the matching request ID from its current wallet actor and reuses that pending ID when a restarted wallet requests its current view. Transactions still go through the existing admission path. The existing read API is preserved; this is at most one accepted restoration response per holder incarnation, not an exactly-once guarantee across arbitrary restarts.

Ordinary-bootstrap prerequisite now included: #2545 supplies the existing #2496 owner correction. Updated ergoplatform#2424 and this branch reuse d0f09d6 and the fixture-directory follow-up 7c92f54. A fresh header appended through the ordinary path now sets the existing headers-synchronized flag while snapshot bootstrap is pending. The branch still returns no block sections and does not advance the full-block retention floor. The previously reported transition blocker is corrected on these pinned heads.

Second, ergoplatform#2409 derives wallet projections lazily from the current mempool, while ergoplatform#2424 must verify reconciliation before releasing recovery guards. Evaluate the final state after its copies and reader updates, before clearing rollback intent, completing snapshot status or reopening operational APIs. Preserve the concrete two-argument reconciliation API and its explicitly supplied dust limit, including None. Keep persisted-input reservations separate from current-mempool outputs and balances. Cleanup after an actual successful scan returns its refreshed state; mandatory past/snapshot scans also require height acknowledgement. A missing block, failed scan or failed materialization cannot release these recovery gates.

Review history:

• a179130c: snapshot/persistence join, readiness registration and actual scan cleanup.
• 174a7b760: incorporates the projection/persistence composition from this review at 0fb498c2 and reconciles the final computed states.
• 1546fa0cb: retains exact shared support #2535 at e18df9692. Seven test-only files change; production is unchanged. This tree uses the matching newer 20-case candidate suite, rather than the older-suite backports on the projection-only branch.

Validation at the composed 1546fa0cb tree: 81/81 local tests passed, comprising 20 candidate, 14 wallet-service, nine wallet-actor, one API compatibility, four ordinary restart, eight projection, 20 scan/registration and five holder-registration cases. All wallet cases were rerun after the shared-generator inputs changed. Integration sources compile. The later b4e21d1f6 fixture follow-up had eight successful checks (run); that is prior-head evidence. Independent source, fixture, consumer and exact-composition reviews completed. The proposed integration target is the final combined tree; the earlier pair commits are evidence of narrower joins.

The tests include actual reader/reservation-read failures after state copies, warmed reservations through the real snapshot catch-up handler, delayed alignment, stale/foreign responses and a controlled wallet-actor restart. That restart fixture explicitly closes its stores and does not establish general store-handle recovery. Known closed-store diagnostics during candidate-fixture shutdown remain; no error-free-teardown or OS power-loss claim is made. TTL, Invalidated policy and external-scan policy are unchanged.

Review shared prerequisites once and coordinate their actual merge/rebase order through the tracker. This compatibility branch does not replace the original feature reviews.

The first hosted run passed integration but exposed two wallet fixture contracts and shared synchronizer storage paths. The two-file follow-up gives each synchronizer node fixture isolated data/keystore roots, adds the actual mempool event before the existing balance assertion, and supplies the established fresh-state hook to one metadata-only snapshot reader. The 31-case synchronizer suite and both affected wallet cases pass; assertions and deadlines are preserved. Independent source review completed. Production code is unchanged. All eight checks passed at b4e21d1f6 (run). That result belongs to the previous head; the ordinary-bootstrap correction is now included as described below.

Previous ordinary-bootstrap checkpoint

Head 23d045d7835c904179685448138f095c47068095 incorporates ergoplatform#2424 at 24461867ec4e4a14320d32d7a55012a122d6f56b while retaining the original feature owners. Review the historical propagation and the historical 29-file comparison. Shared commits d0f09d6ded54323cc4a8fe7ae017a3427d02fe78 and 7c92f54fd7ddadf3d3007d515ece528763834b89 occur in the ancestry of ergoplatform#2545, ergoplatform#2424 and this composition; ergoplatform#2496's separate history-restart predicate and proof-verifier changes are not imported.

The bootstrap consumer closure passed 36/36 on tree 56d3e17c4c463be0b2b12400fa8219a6c1773078, with independent composition review. Earlier 81/81 and 33/33 results remain evidence for unchanged wallet/candidate and fixture inputs; they are not presented as reruns of this bootstrap change. The shared positive-retention regression first failed at the intended synchronization flag and rejects a floor-advancing mutation. The Linux fixture-directory follow-up creates the required state directory before native-store opening.

All eight checks passed at the previous head 23d045d7835c904179685448138f095c47068095 (run 34392881476); this is historical evidence for the ordinary-bootstrap increment.

Digest snapshot checkpoint

Head 88a85d685a2de1c251f41c772e7321d85713b28b merges exact ergoplatform#2424 commit c18d0812e727ee0ea5cffa596ac8217ca324a31d once. Review the new propagation after the core correction in #2546 and its wallet/finalization adaptation in ergoplatform#2424. The conflict resolution retains both the configured state reader and final projection materialization before recovery guards clear.

53/53 local tests passed: three real snapshot/wallet producer cases, seven node bootstrap cases, five holder-registration cases, eight projection cases, 20 scan/registration cases, four ordinary restart cases and six focused wallet recovery cases. Independent production and fixture review is complete. The new UTXO case signs and admits a transaction spending the snapshot-owned payment, verifies its durable bytes and first-seen height after store closure, then observes automatic readmission before the first full block. It preserves that record through the successor and a second restart, without seeding storage or resubmitting the transaction. The original owned-payment cases still cover both UTXO and Digest modes; this does not assert Digest mempool admission.

All eight checks passed for checkpoint head 88a85d685a2de1c251f41c772e7321d85713b28b (run 34415289188); this is historical evidence for that head. Small fake-PoW fixtures exercise real storage and block processing.

Historical snapshot receive checkpoint

Historical checkpoint fc8b90af23ed0e40714286dca8e70724a7502061 merges exact ergoplatform#2424 receive follow-up f5c3c797773038679877e5415af77de20a6b759b without conflicts. The two-file propagation retains the correction owned by #2546: Digest accepts requested detached chunks without gaining UTXO snapshot-serving capabilities. Snapshot parsing, current-anchor checks, durable-write acknowledgement and retries remain intact.

35/35 local receive/synchronizer cases passed on this composition. The 12 download-flow/retry cases retain their exactly matched ergoplatform#2424 inputs; the earlier 53 wallet/recovery cases retain their unchanged input closure. Independent source/fixture review and composition checks are complete. The four receive cases use real nonempty depth-14 chunks, serialized actor messages and actual history storage. They directly register manifest/request state and observe initialization through a holder probe, so full wire negotiation, TCP framing and same-fixture state import remain separate. OS power-loss recovery and production-network qualification are not established.

The CI run at fc8b90af failed on attempt 1 and passed all eight checks on attempt 2. Both results belong to that historical checkpoint.

Historical shared-seed checkpoint

Historical checkpoint 957320338bd86a6d913f61b95f404b1715da8c5d merges exact ergoplatform#2424 head 62bde27815597fa6ea5d34ad3ad1ceba73c79f08. The three-file propagation from fc8b90af changes only DeepRollBackSpec.scala, ConvergenceObservations.scala and ConvergenceObservationsSpec.scala. All production and unit-test blobs are unchanged from fc8b90af.

The complete, non-mining initial shared seed is owned by #2535 at exact commit 5eedfdc91d7a515f66822643e730b4ca9b3197df. The composition preserves ergoplatform#2511's stronger isolation controls, finite request timeouts, 50/200 height targets and the existing 20-minute overall rollback-test deadline and ten-minute final-convergence deadline.

All 32 pure integration-support tests passed, and integration compilation passed. Independent composition review is clear. The earlier 53 wallet/recovery and 35 receive/synchronizer cases retain their unchanged input closure; these results are reused, not presented as new executions of this three-file update.

CI at checkpoint 957320338 passed all eight checks. The upstream f5c3c797 checkpoint's 21/22 integration result and unproven DeepRollBackSpec terminal cause remain historical; the shared seed update does not establish that cause.

Historical prerequisite alignment and CI

Historical head 8e475916a0cade7b2dd5ed37607b6a77a47c35d2 merges exact ergoplatform#2424 head 72140e5dea0934b9f5752a70a458ae4ac863237b, including #2535's synchronizer directory isolation at 99f8bd2ff811a94219279da746d24ec807761900. The propagation from 957320338 changes no files: both commits have tree 1a0ff011d6e9b36cfeea500eae3ebcbd3f4ace3f. The fixture was already present, so that merge aligned prerequisite ownership without changing its content.

No new local tests were run for that unchanged historical tree. The prior 32 pure integration-support, 53 wallet/recovery and 35 receive/synchronizer results retain their unchanged input closures. All eight checks passed for that historical head (run 34427242334). Current alignment and CI are listed at the top. Owner-review questions are recorded in the tracker.