Skip to content

Make RLN persistence crash-consistent - #138

Merged
gofman8 merged 13 commits into
UTEXO-Protocol:devfrom
Jainakin:hardik/rln-kv-vss-durability
Aug 17, 2026
Merged

Make RLN persistence crash-consistent#138
gofman8 merged 13 commits into
UTEXO-Protocol:devfrom
Jainakin:hardik/rln-kv-vss-durability

Conversation

@Jainakin

@Jainakin Jainakin commented Aug 10, 2026

Copy link
Copy Markdown

What

Make RLN local KV and VSS replication path crash-consistent.

  • commit a local mutation and its durable VSS retry intent in one SQLite transaction
  • reject new distinct mutations when the retry backlog is full instead of evicting recovery evidence
  • serialize remote mutations through the shutdown fence and preserve per-key ordering
  • require a VSS acknowledgement for persisted RGB funding boundaries that must survive device loss
  • make VSS fence ownership explicit across failed unlock, lock, shutdown, and stale-owner cleanup
  • cover persistence behavior with deterministic process-kill and fault-injection tests

Why

The previous best-effort sequence could persist a new local value without its retry intent, evict an older intent when the queue reached capacity, or allow shutdown to race an in-flight remote mutation. Any of those outcomes can make a restored node silently older than the local state.

This PR establishes the durability contract only. The transactional RGB funding state machine remains separate and WIP in #139.

Independently reproduced gaps

The deterministic tests from #142 were cherry-picked into this branch. They cover three concrete invariants:

  1. a crash between local write and retry-intent persistence must not leave an unreplicable local value
  2. a full retry queue must not evict existing recovery evidence
  3. shutdown must not release the VSS fence while a remote put is still in flight

A fourth deterministic regression added during review proves that a retry drain which passed its initial admission check cannot begin a remote mutation after stop() returns.

Independent CI evidence from the test PR:

The tests now live with the fix and are invoked explicitly by the normal vss-tests workflow, so future changes cannot regress these properties silently.

Safety properties

  • a killed process observes either the complete old state or the complete new local value plus retry intent
  • a failed VSS write cannot silently discard its recovery intent
  • funding-critical namespaces fail closed when VSS is configured and does not acknowledge the transition
  • queue capacity is enforced before mutation; existing entries are never evicted
  • shutdown waits out remote mutations before releasing the VSS single-writer fence

Validation

Local validation on the current rebased head:

  • cargo fmt --check
  • SKIP_INIT=1 cargo test --features vss "test::vss::tests" -- --test-threads=1
    • 27 passed, 0 failed, 2 ignored helper/OS-kill tests
  • SKIP_INIT=1 cargo test --features vss "test::vss_durability_gaps" -- --test-threads=1
    • 4 passed, 0 failed
  • SKIP_INIT=1 cargo test --features vss "test::vss_unreachable_openchannel::openchannel_refused_while_vss_unreachable" -- --exact --nocapture --test-threads=1
    • 1 passed, 0 failed
  • SKIP_INIT=1 cargo test --features "uniffi,test-utils,vls,vss" --lib kv_store_os_kill_matrix -- --test-threads=1
    • 1 passed, 0 failed
  • SKIP_INIT=1 cargo test --features "uniffi,test-utils,vls,vss" --bin rgb-lightning-node synced_kv_os_kill_matrix -- --ignored --test-threads=1
    • 1 passed, 0 failed

The current GitHub matrix is running after rebasing onto latest dev and force-pushing the branch. Full CI remains a merge gate: https://github.com/UTEXO-Protocol/rgb-lightning-node/pull/138/checks

Review and rollout notes

  • namespace names in SyncedKvStore are persisted protocol contracts
  • VSS unavailability is deliberately surfaced for funding-critical transitions, favoring recoverability over availability at the broadcast boundary
  • physical iOS/Android sudden-power-loss and filesystem-behavior validation remains a release gate; deterministic process termination is strong evidence but is not claimed to be identical to device power loss
  • this PR does not expose new public funding-recovery APIs and does not include the WIP funding continuation from Make RGB channel funding restart-safe #139

@Jainakin
Jainakin force-pushed the hardik/rln-kv-vss-durability branch from be65cbc to 249ba32 Compare August 13, 2026 08:20
@dcorral
dcorral marked this pull request as ready for review August 17, 2026 09:07
@dcorral
dcorral self-requested a review August 17, 2026 09:11
@gofman8
gofman8 merged commit 5f13bfb into UTEXO-Protocol:dev Aug 17, 2026
50 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants