Zeus Research Frontier

Zeus Research Frontier

Open problems where Zeus can advance the state of the art in self-custodial Lightning wallets, plus the standards for claiming anything publicly. Four directions below are maintainer-endorsed (2026-07-06); everything labeled candidate or open is discovery output, not endorsed roadmap.

When to use / When NOT to use

Use this skill when:

• Deciding what research or frontier work to pick up next in this repo.
• Picking up a stalled thread named here (LSPS7 refund UI, bip-321 branch, payLightningInvoiceStreaming, android-16kb-page-size, NUT-15 upstreaming).
• Writing anything external-facing that makes a claim about Zeus (novelty, "first", benchmarks, privacy properties).
• Evaluating whether a feature idea is genuinely novel vs. already known in the ecosystem.

Do NOT use this skill for:

• How to turn a hunch into an accepted change (evidence bar, idea lifecycle) → zeus-research-methodology.
• Concrete analysis recipes (race analysis, dispatch audits, migration proofs) → zeus-proof-and-analysis-toolkit.
• The node-lifecycle-races problem specifically → zeus-node-lifecycle-campaign (it has its own executable campaign).
• Backend capability mechanics and adding an RPC → zeus-backends-and-capabilities.
• Storage/migration changes (several steps below touch defaults or persisted data — those are gated) → zeus-storage-and-migrations and zeus-change-control.
• Domain theory (what BOLT12/LSPS/Cashu are in depth) → zeus-lightning-reference. This skill defines terms only enough to scope the work.

Glossary (first-use definitions)

Direction 1 — Self-custodial UX parity (zero-config receive, background payments, swaps)

Why current SOTA fails. Custodial wallets receive instantly with zero setup and work while the app is closed. Self-custodial mobile wallets need inbound liquidity (a channel) before first receive, and the node is offline whenever the OS suspends the app — so unattended receive/pay is unreliable. No shipping wallet has closed both gaps without custody.

Zeus's specific assets.

• Two embedded node engines behind one UI: embedded-lnd (gomobile AAR/xcframework) and ldk-node (uniffi FFI, ZeusLN fork v0.7.0-zeus-pathfinder-config per fetch-libraries-versions.json).
• A three-generation LSP stack in stores/LSPStore.ts: Olympus Flow 2.0 REST (default https://0conf.lnolymp.us, JIT invoice wrapping via jit_bolt11), LSPS1 over three transports (custom message type 37913, REST, native — chosen per backend via supportsLSPScustomMessage / supportsLSPS1rest / supportsLSPS1native), and LSPS7 lease extension (supportsLSPS7native, currently true only on backends/LdkNode.ts).
• ZEUS Pay lightning address (stores/LightningAddressStore.ts) with three receive modes — zaplocker, cashu, nwc — giving offline receive without custody of keys.
• Boltz-protocol swaps (stores/SwapStore.ts, default host https://swaps.zeuslsp.com/api/v2 defined in stores/SettingsStore.ts) with deterministic rescue keys (DERIVATION_PATH = 'm/44/0/0/0').

First three concrete steps in this repo.

1. Finish LSPS7. The refund-address UI in views/LSPS7/index.tsx is disabled behind {false && ( with the comment TODO add conditions for refund onchain address (search: grep -n "false && (" views/LSPS7/index.tsx). Note state.refundOnchainAddress is ALREADY plumbed into both LSPS7 order paths (stores/LSPStore.ts lines ~1174 and ~1207); because the input is fenced, the value is always ''. The remaining work is defining when the LSP requires a refund address and enabling the fenced input block — not re-implementing the wiring.
2. Measure NWC background delivery before changing it. stores/NostrWalletConnectStore.ts (3232 lines, zero tests) runs the wallet-service side; iOS keep-alive is a background-audio hack (ios/zeus/NWCAudioKeepAlive.m + bundled ambient .m4a files in ios/zeus/), Android uses a persistent foreground service gated by the AsyncStorage flag persistentNWCServicesEnabled (constant NWC_PERSISTENT_SERVICE_ENABLED in the store). Build a delivery-success-rate harness (N payment attempts against a backgrounded device, per platform, per keep-alive mode) so improvements are measurable. Measurement recipes: zeus-diagnostics-and-tooling.
3. Map the fresh-install receive funnel. Instrument the path from new embedded wallet → first receive: views/Wallet/Wallet.tsx post-connect LSP init (getLSPInfo, initChannelAcceptor), Flow JIT wrapping in stores/LSPStore.ts (note: wrapping mutates the invoice amount by subtracting the zero-conf fee and silently degrades to unwrapped on failure), and views/Receive.tsx. Record where users stall and what fees they pay.

You have a result when: a fresh install on both platforms receives a Lightning payment within a bounded time (pick and publish the bound, e.g. 5 minutes) with zero manual channel-management screens, and the measured all-in fee vs. a custodial baseline is documented. Falsified if any step requires the user to understand channels, or if background NWC payment delivery stays below the published target rate.

Direction 2 — Protocol leadership (BOLT12, Cashu NUT-15, CLINK, BIP-321)

Why current SOTA fails. BOLT12 offers barely exist on mobile: receiving to an offer needs an online node with blinded-path support, so most wallets ship nothing. Multimint ecash payments (NUT-15) are unimplemented in mainstream client libraries. Unified payment URIs (BIP-321) are stalled ecosystem-wide.

Zeus's specific assets. Offers already work on two backends — supportsOffers() is true only in backends/CLNRest.ts and backends/LdkNode.ts (verify: grep -rn supportsOffers backends/); Zeus maintains its own ldk-node fork; the Cashu integration is CDK-FFI-based with a working NUT-15 client that CDK itself lacks.

Concrete threads, file-level.

• BOLT12 beyond cln-rest/ldk-node. LDK Node cannot persist offers — listOffers in backends/LdkNode.ts hard-returns { offers: [] } with the comment "LDK Node doesn't store offers natively". Local offer persistence (per-node, keychain- or SQLite-backed) is the missing piece for real offer management on the embedded backend. Any persisted-key addition is a gated storage change → zeus-storage-and-migrations.
• Cashu multimint NUT-15 — upstream or standardize. stores/CashuStore.ts queryMeltQuoteMpp bypasses CDK entirely, POSTing raw {mint}/v1/melt/quote/bolt11 with options.mpp, then classifying rejections (classifyMppRejection). CDK is pinned at 0.14.2 (fetch-libraries-versions.json). Either upstream multimint melt to CDK (removing the bypass) or publish the probe/rejection-classification approach as a client-interop note.
• CLINK/noffer. utils/ClinkUtils.ts: noffer1… bech32 TLV, CLINK_KIND = 21001, NIP-44 encryption, and a hard ONION_NOT_SUPPORTED error (no .onion relay support — overlaps Direction 4).
• BIP-321 pickup. Local branch bip-321 (one commit 3c1210922, 2025-08-20, unmerged: git branch --list bip-321; diff vs master touches views/Receive.tsx, utils/AmountUtils.ts + test, stores/InvoicesStore.ts). Concrete pickup: rebase onto current master and re-test the receive flow.
• payLightningInvoiceStreaming — resolve the dead dispatch. Declared in utils/BackendUtils.ts but implemented by NO backend (verify: grep -rn payLightningInvoiceStreaming backends/ utils/ — only BackendUtils hits). Because missing methods return sync false (see Direction 3), every call would silently no-op. Decide: delete the wrapper, or implement streaming payment progress on the LND family. This is a design decision to surface to the maintainer, not a drive-by fix — payment-path changes must be minimal diffs (zeus-change-control).

First three steps: (1) rebase and revive bip-321; (2) write the maintainer proposal for payLightningInvoiceStreaming (delete vs. implement, with call-site evidence); (3) open the CDK upstream issue for multimint melt with Zeus's queryMeltQuoteMpp as the reference client.

You have a result when: (a) a mainnet BOLT12 offer created on an embedded ldk-node wallet survives app restart and receives a payment from a third-party wallet, or (b) the NUT-15 bypass is deleted because an upstream CDK release covers it, or (c) BIP-321 receive ships and a third-party wallet parses the QR. Each is binary and externally checkable.

Direction 3 — Multi-backend robustness (the 7-backend matrix, crash-free)

Why current SOTA fails. No other wallet drives 7 heterogeneous backends (embedded-lnd, ldk-node, lnd, lightning-node-connect, cln-rest, lndhub, nostr-wallet-connect) behind one UI. The cost is silent capability drift: BackendUtils.call() returns synchronous false when the active backend lacks a method (utils/BackendUtils.ts: if (!cls[funcName]) return false;), so a typo'd or unimplemented dispatch never throws — it no-ops, and false.then(...) crashes at the call site. Missing supports* gates are historically the top cross-backend crash source.

Zeus's specific assets. The supports* capability system already exists: 55 distinct supports* flags dispatched through utils/BackendUtils.ts (count: grep -o 'supports[A-Za-z0-9]*' utils/BackendUtils.ts | sort -u | wc -l), including composites like supportsLightningAddress = supportsCustomPreimages() || supportsCashuWallet() computed in the dispatcher itself.

First three concrete steps in this repo.

1. Dispatch-completeness audit tooling. Mechanically enumerate every wrapper in utils/BackendUtils.ts, check which of the 7 backend classes implement it, and flag call sites lacking a supports* guard. Known true-positive the tool must catch: payLightningInvoiceStreaming (zero implementers); known cosmetic finding: backends/NostrWalletConnect.ts declares supportsLSPS1customMessage (typo — the dispatched name is supportsLSPScustomMessage; harmless only because both resolve to false). The audit recipe with worked examples lives in zeus-proof-and-analysis-toolkit — build the runnable version there, not here.
2. Store test scaffolding. There are zero tests under stores/ today — all 49 test files live in utils/ (45), models/ (2), lndmobile/ (1), plus root check-styles.test.ts (verify: ls stores/*.test.ts → no matches). Start with a keychain-mocking harness for SettingsStore (everything depends on it), then the dispatch-heavy stores. Jest ESM/transform traps → zeus-validation-and-qa.
3. Typed dispatcher (candidate design, not started). Replace the stringly call(funcName: string) with a typed interface over the backend classes so a missing implementation is a compile error, and absence must be expressed as an explicit capability. This changes payment-path plumbing — proposal first, minimal diff, maintainer sign-off (zeus-change-control).

You have a result when: the audit tool runs in CI and reports zero dispatched methods that are both unimplemented on some backend AND unguarded by supports* at every call site — and adding a new unguarded wrapper fails the build. Falsified if the tool exists but the matrix still produces a missing-method crash in release testing.

Direction 4 — Privacy leadership (Tor gaps, TLS defaults, ecash, stealth)

Why current SOTA fails. "Tor support" in wallets is usually partial: some code paths route through Tor, others silently leak to clearnet, and users can't tell the difference. Zeus is closest to full Tor-by-default among self-custodial wallets but has verified gaps.

Verified gaps in this repo (2026-07-06).

Zeus's specific assets. Embedded Tor (react-native-nitro-tor 0.6.0 in package.json); the hardened Tor TLS rule (cert bypass only for HTTPS .onion — the invariant and its incident history belong to zeus-failure-archaeology FA-5); Android Stealth Mode (three disabled-by-default activity-alias app disguises — calculator, VPN, QR scanner — in android/app/src/main/AndroidManifest.xml); an ecash small-balance model already wired (settings.ecash defaults in stores/SettingsStore.ts: enableCashu: false, enableMultiMint: false, automaticallySweep: false, sweepThresholdSats: 10000 — ecash holds small change, auto-sweeps to Lightning above threshold).

First three concrete steps in this repo.

1. Close the .onion LNURL gap: implement Tor fetching of LNURL params at the 3 TODO sites using utils/TorUtils.ts (doTorRequest), respecting the .onion-HTTPS-only TLS rule.
2. Route or fence the WebSocket gap: either proxy backends/LND.ts WS streams through the embedded Tor SOCKS layer, or make the UI state explicitly that streaming falls back to clearnet when Tor is enabled — today it leaks silently.
3. certVerification default-flip campaign: flipping the default to true for existing users is a settings-default change requiring a MOD_KEY migration and maintainer sign-off — scope the breakage first (self-signed home-node certs are the common case), design the migration + UX (pin-on-first-use?), and route through zeus-storage-and-migrations + zeus-change-control. Do not just flip the initializer.

You have a result when: with Tor enabled, a full send+receive+stream session on a device under packet capture shows zero clearnet connections (WS included), and the LNURL flows work against a .onion service. Falsified by a single observed clearnet packet.

Candidate infrastructure problems (discovery output — NOT maintainer-endorsed roadmap)

External positioning: novelty claims and proof obligations

Three things in Zeus are candidates for genuine novelty. For each, the proof obligation before ANY public "first"/"only" claim:

Standing proof obligations for ANY published claim:

1. Prior-art survey artifact — dated, named projects checked, kept with the claim. No survey → no novelty claim.
2. Third-party reproducibility — the demo must work from a public tagged release, on mainnet where applicable, without Zeus-internal infrastructure knowledge.
3. Verifiable builds — Android releases are reproducible via ./build.sh (Docker image pinned by sha256 digest, SOURCE_DATE_EPOCH=0; procedure in docs/ReproducibleBuilds.md — Android only, there is no iOS reproducibility story; don't imply one). Releases/commits are PGP-signed — key fingerprint 96C225207F2137E278C31CF7AAC48DE8AB8DEE84 (long ID AAC48DE8AB8DEE84, PGP.txt).
4. AGPLv3 obligations (see LICENSE): derivative works and network-served modifications must publish source. Any published benchmark/claim about Zeus must be checkable from the public repo.
5. No-oversell rule: "Zeus supports X" is only claimable when a supports* gate returns true on at least one shipping backend AND the feature passed the maintainer's mandatory hands-on iOS+Android testing. Benchmarks ship with methodology. Disabled code ({false && ...}), stalled branches, and dead dispatches are never "supported" — they are "in progress" at most. When in doubt, the framing standard is Bitcoin-Core-style conservatism: understate, link evidence.

Provenance and maintenance

Facts verified 2026-07-06 against master c5fd094fb (v13.1.3-alpha) by direct file reads and read-only commands in this repo. Maintainer endorsement of the four directions dated 2026-07-06. Expensive claims (build reproducibility procedure) verified by source read of build.sh/docs/ReproducibleBuilds.md, not executed.

Re-verify volatile facts before relying on them: