Zeus Config And Flags

Zeus Config and Flags

Every user-facing configuration axis in Zeus: where it lives, its options, its default, and the exact checklist for adding or changing a setting. Facts verified 2026-07-06 against master c5fd094fb (v13.1.3-alpha). Defaults drift — re-verify with the commands in the final section before relying on any specific value.

When to use / When NOT to use

USE this skill when you are:

• Adding a new setting/flag, or changing an existing one (checklist below is mandatory).
• Looking up any default value or the full option list for a settings axis.
• Deciding whether config belongs per-node (settings.nodes[]) or global.
• Debugging "my setting change wiped other settings" (shallow-merge trap) or "fresh installs behave differently from upgraded installs" (new-vs-migrated divergence).

Do NOT use this skill for:

• The keychain storage contract, the zeus-settings-v2 blob mechanics, migration recipes, or iCloud rules → zeus-storage-and-migrations (that skill owns the storage layer; this one owns the catalog of what is stored).
• Which backends support which features (supports*() gating) → zeus-backends-and-capabilities.
• The change-approval process for storage-format changes → zeus-change-control. Anything that changes what is persisted (new keys, changed defaults for existing users, removed fields) requires maintainer sign-off plus a migration plan — never route around that.
• Boot sequence / how settings are loaded at startup → zeus-architecture-contract.

Glossary (terms used below, defined once)

1) Where config lives

Rules of thumb:

• Secrets and anything financial → the blob (keychain). Non-sensitive UI-only flags → AsyncStorage. Never put new data in legacy react-native-encrypted-storage (migration flags only).
• Any NEW persisted keychain key must be registered in three registries (utils/DataClearUtils.ts STORAGE_KEYS, utils/KeychainRecoveryUtils.ts OTHER_KEYS, MigrationUtils.keychainCloudSyncMigration migrationKeys) or it leaks on wallet clear/recovery — full recipe in zeus-storage-and-migrations.

Critical load semantics (verified in SettingsStore.getSettings): when a stored blob exists, this.settings = parsedSettings REPLACES the entire inline-default object. There is NO deep merge of defaults into stored blobs. Consequence: a newly added field is undefined for every existing user until they touch its UI control — every consumer must tolerate that (settings?.group?.field ?? fallback, or || fallbacks like getLspConfigForNetwork uses).

2) Per-node axes — settings.nodes[] + settings.selectedNode

Each wallet is a Node object (interface in stores/SettingsStore.ts). selectedNode is the array index of the active wallet. On load/switch, updateNodeProperties copies the selected node's fields onto flat observables (this.host, this.implementation, ...) that the rest of the app reads.

Quirks:

• LNDHub credentials (username, password, lndhubUrl) are read by updateNodeProperties via an any cast but are NOT declared on the Node interface — grep for them before assuming the interface is complete.
• Remote nodes have NO network field; network is detected from getinfo at connect time. Only embedded wallets choose a network.
• Per-node editing UI: views/Settings/WalletConfiguration.tsx (single 3000+ line view handling all 7 implementations); wallet list: views/Settings/Wallets.tsx.

3) Global settings catalog

All defaults below are the inline initializer of @observable settings: Settings in stores/SettingsStore.ts (currently starting near line 1467 — search @observable settings: Settings =). "Nested" groups are replaced wholesale by updateSettings (see checklist); "flat" keys sit at the blob top level.

Top-level scalars (flat)

privacy (nested) — UI: views/Settings/Privacy.tsx, views/Settings/StealthMode.tsx

display (nested) — UI: views/Settings/Display.tsx

payments (nested) — UI: views/Settings/PaymentsSettings.tsx

invoices (nested) — UI: views/Settings/InvoicesSettings.tsx

channels (nested) — UI: views/Settings/ChannelsSettings.tsx

Embedded-node group — FLAT top-level keys — UI: views/Settings/EmbeddedNode/*

LSP group — FLAT top-level keys — UI: views/Settings/LSP.tsx, views/Settings/LSPServicesList.tsx

Per-network TRIPLETS (mainnet/testnet/mutinynet). The canonical resolver is getLspConfigForNetwork(settings, network) in stores/SettingsStore.ts — it accepts a network string or NodeInfo-style flags, and treats 'signet' as testnet. Always use it; never read the triplet fields directly.

swaps (nested) — UI: views/Swaps/Settings.tsx (note: under views/Swaps/, not views/Settings/)

lightningAddress (nested) — UI: views/LightningAddress/LightningAddressSettings.tsx (+ Cashu/NWC variants under views/Cashu/LightningAddress/, views/LightningAddress/NWCAddressSettings.tsx)

bolt12Address (nested) — UI: views/Settings/Bolt12Address.tsx

Single axis: localPart (string, default '') — username for a BOLT12 offer-based address (CLN/LDK backends).

ecash (nested) — UI: views/Settings/EcashSettings.tsx

Cashu is only available on embedded backends — gating rules live in zeus-backends-and-capabilities.

pos (nested) — UI: views/Settings/PointOfSale.tsx

networking (nested) — UI: views/Settings/Networking.tsx

Single axis: disableOfflineCheck (bool, default false) — skips the connectivity probe before requests.

Not a setting: developer mode

There is NO developer-mode toggle. Developer tools are gated purely by supportsDevTools() in utils/BackendUtils.ts (isLNDBased() || this.call('supportsDevTools') — LND-based backends, plus any backend that implements supportsDevTools, currently LndHub and CLNRest). Don't invent a settings flag for it.

4) Deprecated-but-retained flags

All five are marked // deprecated in stores/SettingsStore.ts and MUST stay in the type + defaults:

General rule: removing a persisted field is a storage-format change. Old blobs keep the field forever; migration code and its tests reference it; and TypeScript on those paths breaks if the type disappears. Removal requires the gated process in zeus-change-control plus a migration plan per zeus-storage-and-migrations.

5) New-vs-migrated divergences (document yours if you create one)

Because MOD_KEY migrations in MigrationUtils.legacySettingsMigrations run only for users upgrading from the legacy zeus-settings blob, some settings intentionally differ between fresh installs and migrated installs:

If your change creates such a divergence, it must be stated in the PR description and added to this table.

6) ADD-A-SETTING CHECKLIST

Follow every step; skipping any one has caused real bugs (data loss via shallow merge, "3600 hours" display corruption, leaked keys).

1. Choose the home.
   • Per-wallet behavior → new field on the Node interface (stores/SettingsStore.ts).
   • Global, thematically grouped → the matching nested group interface (PrivacySettings, PaymentsSettings, ...).
   • Global, embedded-node/LSP-style → flat top-level key on Settings.
   • Non-sensitive UI-only flag that shouldn't live in the secrets blob → AsyncStorage (see §1 examples).
2. Type it in stores/SettingsStore.ts. Prefer optional (field?:) — existing blobs won't have it (see §1 load semantics).
3. Add the inline default in the @observable settings: Settings = {...} initializer (search for it; near line 1467 as of 2026-07-06). Remember this default only applies before a stored blob loads — every reader still needs a fallback for undefined.
4. If it's an enumerated axis, add an exported *_KEYS array (key/value/translateKey objects) next to the other pickers so DropdownSetting UIs and tests can consume it.
5. Build the UI in the matching views/Settings/*.tsx (or per-node in WalletConfiguration.tsx). When persisting, use the shallow-merge-safe pattern — SettingsStore.updateSettings merges ONLY the top level, so nested groups are replaced wholesale:

   await updateSettings({
       payments: {
           ...settings.payments, // MANDATORY spread — omitting it silently
           myNewField: value     // destroys every sibling payments setting
       }
   });
   

   Flat top-level keys (updateSettings({ enableLSP: false })) are safe without a spread.
6. Locale strings: add English copy to locales/en.json ONLY (the other 33 locale files are Transifex-managed — rule owned by zeus-change-control). Reference via localeString('views.Settings.<...>').
7. Changing an existing default for existing users? That is a storage-format change: write a one-shot MOD_KEY migration (recipe, ordering, and setSettings-with-a-real-object rules in zeus-storage-and-migrations) and note that it must run on the modern zeus-settings-v2 load path (like migrateRgsDefaultToZeus), not only inside legacySettingsMigrations. Maintainer sign-off required.
8. Creating a fresh-vs-migrated divergence? Document it (§5).
9. New separate keychain key (not in the blob)? Register it in the three registries (§1) — recipe in zeus-storage-and-migrations.
10. Verify: yarn verify (test + prettier + tsc + lint) and fill in the PR template's backend-testing matrix — details in zeus-validation-and-qa / zeus-change-control.

Provenance and maintenance

Facts verified 2026-07-06 against master c5fd094fb (v13.1.3-alpha) by reading stores/SettingsStore.ts, utils/MigrationUtils.ts, utils/LdkNodeUtils.ts, utils/FeeUtils.ts, utils/BackendUtils.ts, backends/LND.ts, stores/UnitsStore.ts, stores/ActivityStore.ts, stores/NostrWalletConnectStore.ts, and views/Settings/*. Defaults are volatile — re-verify before citing: