Zeus Storage And Migrations

Zeus Storage and Migrations

Persistence contracts for the ZEUS wallet (React Native, Bitcoin/Lightning) and the safety protocol for changing them. Storage/keychain integrity is one of the two hardest live problem areas in this repo (maintainer, 2026-07-06). Bugs here lose users' wallet configurations, seeds, and money-adjacent data. Treat every change as high-risk.

The maintainer's gate (non-negotiable): anything touching zeus-settings-v2, keychain keys, or migrations requires maintainer sign-off plus a written migration plan BEFORE implementation. See the zeus-change-control skill for the gating process; this skill tells you what to write in that plan and how to not corrupt data while executing it.

When to use / When NOT to use

Use this skill when you are:

• Reading or writing anything through storage/index.ts, react-native-encrypted-storage, or AsyncStorage
• Adding, renaming, or removing a persisted key
• Modifying SettingsStore (setSettings, updateSettings, getSettings), the Settings/Node shapes, or a settings default that existing users already have
• Writing or reviewing a migration in utils/MigrationUtils.ts
• Touching wipe/recovery paths: utils/DataClearUtils.ts, utils/KeychainRecoveryUtils.ts, duress PIN, wallet deletion
• Debugging lost/duplicated/stale persisted data

Do NOT use this skill for:

• The catalog of settings options/defaults and the add-a-setting UI checklist → zeus-config-and-flags
• The change-classification/review/PR process itself → zeus-change-control
• General race analysis or proving a migration correct from first principles → zeus-proof-and-analysis-toolkit
• The history of past storage incidents in narrative form → zeus-failure-archaeology (this skill embeds only what you need to act safely)
• Running/adding Jest tests in general → zeus-validation-and-qa
• Boot sequence and store dependency-injection order → zeus-architecture-contract

Glossary (jargon used below, defined once)

1. The four storage layers — what belongs where

Rules of thumb:

• New persisted app data → keychain via storage/index.ts. No exceptions for "small" or "temporary" data.
• If you find yourself importing react-native-keychain directly outside storage/, MigrationUtils, DataClearUtils, or KeychainRecoveryUtils, stop — you are bypassing the contract.
• Migration flags go in EncryptedStorage (that is their one remaining legitimate home — a flag must survive independently of the keychain data it guards).

2. The storage contract (storage/index.ts, 57 lines — read it)

The canonical wrapper is a singleton Storage with exactly three methods. Its semantics are load-bearing:

3. zeus-settings-v2: one blob, one shallow merge, the #1 data-loss footgun

What's inside (stores/SettingsStore.ts, Settings + Node interfaces): every wallet's connection config and secrets — macaroonHex, rune, pairingPhrase (LNC), nostrWalletConnectUrl, seedPhrase, walletPassword, adminMacaroon, ldkMnemonic, ldkPassphrase — plus app-level pin, passphrase, duressPin, duressPassphrase (stored in plaintext inside the blob; keychain-is-the-boundary is the current model — known/accepted, do not "fix" drive-by), plus every settings group (privacy, display, payments, invoices, channels, pos, ecash, …).

The two write APIs (stores/SettingsStore.ts):

• setSettings(settings) — writes the WHOLE object to Storage.setItem(STORAGE_KEY, settings) and replaces this.settings. Callers must pass a complete settings object.
• updateSettings(newSetting) — does { ...existingSettings, ...newSetting }. This is a SHALLOW top-level merge: any nested group you pass replaces that group wholesale.

// DESTRUCTIVE ANTI-PATTERN — silently deletes every other key in settings.invoices
// (memo, addressType, expiry, routeHints, blindedPaths, ...):
await updateSettings({
    invoices: { receiverName: text }
});

// CORRECT — spread the existing group, then override
// (real example: views/Settings/InvoicesSettings.tsx):
await updateSettings({
    invoices: {
        ...settings.invoices,
        receiverName: text
    }
});

This is the single most likely way to silently destroy user data in this codebase. In review, treat any updateSettings({ group: { ... } }) call without a spread of the existing group as a bug until proven otherwise. Top-level scalar keys (fiat, locale, nodes, …) are safe to pass alone.

Also note: updateSettings internally calls getSettings() first (which can trigger migrations) and sets settingsUpdateInProgress / triggerSettingsRefresh flags — do not call it in tight loops or during boot races.

4. Migrations: load paths and the MOD_KEY recipe

The two load paths (SettingsStore.getSettings)

getSettings()
├── await MigrationsUtils.keychainCloudSyncMigration()   // ALWAYS first, before any settings read
├── Storage.getItem('zeus-settings-v2') exists?
│   ├── YES (modern path): parse → migrateRgsDefaultToZeus() → migrateInvoiceExpiryDisplay()
│   └── NO  (legacy path): EncryptedStorage.getItem('zeus-settings')
│         → legacySettingsMigrations()   // all MOD_KEY blocks + migrateInvoiceExpiryDisplay + migrateRgsDefaultToZeus
│         → storageMigrationV2()         // copies every legacy key into the zeus: keychain namespace
└── updateNodeProperties(settings)

Every settings migration must run on BOTH paths if it can affect users who already migrated to v2. Incident: the invoice-expiry display repair (26d4215ea, 2026-05-30) initially ran only on the legacy path; users already on v2 kept the corrupted "3600 hours" display, and the migration had to be re-shipped two days later on the v2 path — under the ORIGINAL flag key (e8e5b8811, 2026-06-01). When a further miss (pre-Feb-2024 installs) then forced a re-run, the flag key was bumped to invoices-expiry-display-fix-v2 (a7860aa96, merged f7b2c30a8, PR #4149, 2026-06-08) — full narrative: zeus-failure-archaeology FA-3. If your migration missed people, you cannot "re-arm" the old flag — bump the key with a -v2/-v3 suffix and make the migration idempotent.

The MOD_KEY recipe (copy this shape)

One-shot migrations live in utils/MigrationUtils.ts. Pattern (see MOD_KEY7 = 'bimodal-bug-9085' or migrateRgsDefaultToZeus for live examples):

const MOD_KEY_MY_FIX = 'my-fix-v1';                          // flag key, EncryptedStorage
const mod = await EncryptedStorage.getItem(MOD_KEY_MY_FIX);
if (!mod) {
    // ... mutate newSettings in place (idempotently!) ...
    await settingsStore.setSettings(newSettings);            // (a) AWAIT it  (b) pass the OBJECT
    await EncryptedStorage.setItem(MOD_KEY_MY_FIX, 'true');  // set flag ONLY after write succeeds
}

Hard rules, each backed by a shipped incident:

1. Pass a real object to setSettings, never JSON.stringify(settings). A stringified payload briefly turns the MobX settings observable into a string and crashes observers reading nested keys. Incident fixed in 7ed901a10 (issue #4150, merged via PR #4155, 2026-06-09); a regression test now pins this (utils/MigrationUtils.test.ts, "persists the settings object rather than a JSON string"). (Storage.setItem stringifies internally — that is fine; the observable assignment is what breaks.)
2. await the setSettings call. Un-awaited writes let the flag get set before the data lands (or after the app moves on), producing migrations that "ran" but persisted nothing. Fixed across all MOD_KEY blocks in d8e648b58 (2026-05-30).
3. Set the flag AFTER the mutation is persisted, so a crash mid-migration retries next boot instead of skipping forever.
4. Make the mutation idempotent (safe to run twice) — flags can be lost (EncryptedStorage cleared) while keychain data survives.
5. Cover both load paths (see above). For settings-shape migrations that must also hit v2 users, call your function from the modern branch of getSettings too, like migrateInvoiceExpiryDisplay.
6. New defaults need no migration; CHANGED defaults do. Inline defaults in SettingsStore only apply to keys the user has never persisted. To change behavior for existing users you must ship a MOD_KEY migration (details of the settings axes: zeus-config-and-flags).

Add a test in utils/MigrationUtils.test.ts (22 tests passing as of 2026-07-06; run npx jest utils/MigrationUtils.test.ts).

5. Checklist: adding a NEW persisted key

Convention: export the key constant from its owning store/util (e.g. export const NOTES_KEY = 'zeus-notes-v2' in stores/NotesStore.ts) and import it everywhere else — never inline string literals. New keys use a zeus- prefix and -v2 style suffix by convention.

Then register it, or it leaks:

If the key is dynamic (per-node/per-mint, like <nodeDir>-cashu-*), you must ALSO handle enumeration in DataClearUtils (see clearCashuDataForNode) — static lists can't clear keys they can't name.

6. iCloud rules and the orphaned-entry policy

History you must know before "improving" anything here: the multi-attempt iCloud keychain saga (merge → same-day revert → re-land → stale-restore fallout → zeus:-prefix re-keying → deletion disabled). The full dated timeline with hashes is owned by zeus-failure-archaeology FA-1 — do not rely on memory of it; read that entry before touching this area.

Current rules (verified against master 2026-07-06):

1. All writes are cloudSync: false — enforced inside storage/index.ts. Never write app data with cloudSync: true.
2. Orphaned pre-migration entries are retained BY DESIGN. MigrationUtils.deleteFromOldKeychain is a no-op with the delete code commented out. Old unprefixed local AND iCloud-synced entries (including seed copies) persist on purpose: the Keychain Recovery tool (views/Tools/NodeConfigExportImport.tsx + utils/KeychainRecoveryUtils.ts) scans exactly those four sources (current / unprefixed-local / unprefixed-cloud / encrypted-storage) to rescue users' lost wallets. Do not "clean up" orphans — that deletes the recovery path. Re-enabling deletion is maintainer-gated.
3. Explicit purges must clear BOTH sync variants and BOTH namespaces. DataClearUtils.clearKey is the reference: it resets zeus:<key> local + cloud, and unprefixed <key> local + cloud, five calls total. Any new wipe path that clears fewer locations leaves secrets behind.
4. migrateKey uses read → write → verify → delete ordering with 500 ms iOS sleeps around keychain ops (iCloud sync latency, 35aaf8897) — keep that ordering and pacing if you extend it.

7. Caveats — data that does NOT die when you think it does

Per-node Cashu namespacing: always use CashuStore.getNodeDir() (returns ldkNodeDir || 'ldk' for ldk-node, else lndDir || 'lnd') — NOT getLndDir(), which returns 'lnd' for every LDK wallet. That collision mixed ecash funds across LDK wallets; fixed by 1242ce94a (2026-03-20) with a copy migration (migrateLegacyCashuKeysToNodeDir), and again for multimint keys in 35fa31fee (2026-04-08) — incident narrative: zeus-failure-archaeology FA-11. Any new per-node key must be namespaced with getNodeDir().

Node dirs are UUIDs: new embedded wallets get lndDir = uuidv4() / ldkNodeDir = uuidv4() (views/Settings/WalletConfiguration.tsx); old single-wallet installs used the literal 'lnd' — which is why fallbacks and clearCashuDataForNode('lnd') exist.

8. SAFETY PROTOCOL for any storage-touching change

This executes within the gate defined in zeus-change-control (maintainer sign-off + migration plan required, always).

Pre-change checklist (do this BEFORE writing code)

• Written migration plan: what data moves/changes, for which cohorts (legacy-blob users, v2 users, fresh installs), and what happens on crash mid-migration
• Idempotency argument: running the migration twice is harmless
• Both load paths covered (Section 4) — state explicitly which of legacySettingsMigrations / modern getSettings branch calls your code
• Flag key named and versioned (<thing>-<fix>-v1), stored in EncryptedStorage
• New keys registered per Section 5 (all applicable locations)
• No JSON.stringify into setSettings; every setSettings awaited; every updateSettings nested group spread
• No deletion of orphaned/unprefixed/iCloud keychain entries (Section 6 rule 2)
• Jest coverage added in utils/MigrationUtils.test.ts for the new migration logic
• Rollback story written (below)

Mandatory manual test matrix

PR CI never builds the app (test/lint/prettier/tsc only; the Android build workflow is manual workflow_dispatch) and there are zero store-level integration tests — this matrix is hand-executed, and the maintainer requires hands-on testing on BOTH platforms before merge regardless of CI green. Record results in the PR (the PR template's testing section — see zeus-change-control).

Also re-run the automated floor: yarn verify (jest + prettier + tsc + lint — anatomy in zeus-validation-and-qa).

Rollback thinking (revert-first culture)

• Regressions found in release testing get reverted same-day, never forward-fixed under pressure (maintainer rule; observed repeatedly for storage/keychain changes — e.g. #3307 merged and reverted within hours on 2025-11-10).
• Design so a revert is safe: a migration that only ADDS/repairs fields can be reverted without a counter-migration; one that deletes or re-keys data cannot. If your change is not revert-safe, say so in the PR and provide the counter-migration.
• Never reuse a burned flag key after a botched migration — bump the suffix (-v2) so already-flagged users are re-processed by the fixed logic.

Evidence the maintainer expects in the PR

1. The migration plan (cohorts, idempotency, both-paths coverage, revert story)
2. The filled test matrix with device/OS noted per row, iOS AND Android
3. Before/after dumps of the relevant blob section for scenario 3 (redact secrets)
4. New/updated Jest tests passing (npx jest utils/MigrationUtils.test.ts)
5. Explicit statement of which of the Section 5 registration points you touched and why the others don't apply

Provenance and maintenance

Facts verified 2026-07-06 against master c5fd094fb (v13.1.3-alpha) by reading storage/index.ts, stores/SettingsStore.ts, utils/MigrationUtils.ts, utils/DataClearUtils.ts, utils/KeychainRecoveryUtils.ts, utils/LdkNodeUtils.ts, stores/CashuStore.ts, views/Lockscreen.tsx, views/Settings/WalletConfiguration.tsx, views/Tools/*; cited hashes checked with git log/git show; npx jest utils/MigrationUtils.test.ts executed (22/22 pass). Maintainer policy statements dated 2026-07-06.

Re-verification one-liners for volatile facts:

Open/unresolved (do not treat as settled): VSS remote-state deletion (no client delete path); permanent-retention-vs-eventual-deletion of orphaned keychain entries (retention is current policy, revisiting is maintainer-gated); plaintext PIN/passphrase in the blob (accepted debt).