zeus-change-control

Zeus Change Control

How to get a change into Zeus (a React Native Bitcoin/Lightning wallet) without losing user funds, corrupting user data, or getting your PR closed. Zeus moves money; process rules here exist because each one was paid for by a real incident.

Glossary used throughout (defined once):

• PR — GitHub pull request. CI — continuous integration; the automated checks GitHub runs on every PR.
• Lightning — Bitcoin's payment-channel network; Zeus is a wallet for it. LND / CLN — the two major Lightning node implementations Zeus talks to. Macaroon — LND's bearer-token auth credential (a secret; leaking one can drain a node).
• Keychain — the OS-level secure credential store (iOS Keychain / Android Keystore) where Zeus persists ALL wallet secrets in one JSON blob under key zeus-settings-v2.
• Squash / fixup — git operations that fold review-fix commits into the original commit before merge.
• Backend — one of the 7 node implementations Zeus can drive (embedded LND, LDK Node, remote LND REST, Lightning Node Connect, CLNRest, LndHub, Nostr Wallet Connect).

When to use / When NOT to use

USE this skill for: change classification and approval gates, commit-message style, PR template and review process, CI-check expectations, dependency policy, locale rules, revert policy, docs/license/signing house rules.

Do NOT use this skill for — go to the sibling instead:

Authoritative in-repo documents this skill summarizes (read them for full text; nothing here overrides them): CONTRIBUTING.md, CODE_REVIEW.md, .github/PULL_REQUEST_TEMPLATE.md.

1. The four maintainer non-negotiables (UNWRITTEN rules)

These four rules are maintainer-stated (2026-07-06) and appear in NO repo document. They bind anyway. Each has a paid-for rationale.

Rule 1 — Storage/keychain changes are gated

Anything touching the zeus-settings-v2 blob, keychain keys, storage/index.ts, or migrations (utils/MigrationUtils.ts, stores/SettingsStore.ts persistence paths) requires maintainer sign-off plus a written migration plan, always — before you write code. Never route around this by "just changing the format".

• WHY: every wallet's seed, macaroon, and PIN live in one keychain JSON blob. A bad write or migration bricks wallets or leaks seeds; there is no server-side undo.
• INCIDENTS: the iCloud keychain saga — PR #3307 (merged as 5f533bb12, 2025-11-10) was reverted the same day (7d8678457, via revert PR #3354); the proper fix took two more PRs (merges e808fd71a + ed161541a, 2025-12-01) and STILL left stale iCloud-synced wallet copies on new devices, requiring a third migration (46f2bac00, 2026-01-14). Separately, a settings migration passed a JSON.stringify'd object to setSettings, corrupting MobX observables — issue #4150, fixed by 7ed901a10 (2026-06-09). Recipes and the safety protocol: zeus-storage-and-migrations; full narratives: zeus-failure-archaeology.

Rule 2 — Revert-first near releases

A regression found during release testing gets reverted the same day, never forward-fixed under pressure. If your merged change is implicated, expect a revert-<PR#>-<branch> PR with an empty body; don't argue for a hotfix, re-land properly later.

• WHY: forward-fixes under release pressure ship untested code into a funds-handling app.
• INCIDENTS: NWC txlist fix #3432 merged and reverted (#3444) on the same day, 2025-12-15 (28bc50f5e); iCloud #3307 reverted same day 2025-11-10; sat-rounding #1568 (2023-08-04) reverted next day by #1587; app-lock-timeout #1679 reverted by #1773 (2023-10).
• Practical consequence: before trusting any merged fix as final, check git log --grep='revert-<PR#>'.

Rule 3 — No refactors of payment paths

Changes to send/receive/payment-handling code (views/Send.tsx, views/PaymentRequest.tsx, stores/TransactionsStore.ts, backends/*, utils/BackendUtils.ts dispatch) must be minimal diffs. No drive-by refactoring, renaming, or "cleanup" inside a funds-touching change.

• WHY: stores, views, components, and backends have zero automated test coverage — only utils/, models/, and lndmobile/ have tests (plus the root check-styles.test.ts; see zeus-validation-and-qa). A refactor there is reviewed and safety-netted by human eyeballs alone, across 7 backends.
• INCIDENT (refactors bite even outside payment code): fdad118ed (2025-10-24), a "replace UNSAFE React lifecycle methods" refactor, caused an infinite-loading regression fixed only 3 weeks later by 93227029e (2025-11-12, which cites the offending hash in its subject).

Rule 4 — Manual two-platform testing is mandatory

No merge without hands-on testing by the author on both iOS and Android, regardless of green CI.

• WHY: PR CI runs only unit tests, lint, formatting, and type-check on Linux (Section 5) — it never builds or launches the mobile app. Rendering, native modules, and navigation differ per platform; CI green proves almost nothing about runtime behavior. CONTRIBUTING.md says "when possible"; the maintainer standard is stricter: do it.
• The PR template's platform and backend checkboxes (Section 3) are how you attest to this.

2. Change classification and gates

Classify every change before starting. When a change spans classes, the strictest gate applies.

3. PR process

The template is sacred

.github/PULL_REQUEST_TEMPLATE.md — never delete or replace it; fill in every section (CONTRIBUTING.md states this explicitly). Its required sections, as of 2026-07-06:

1. Description — issue reference (ZEUS-0000 placeholder), description + screenshots.
2. Category checkboxes — new feature / bug fix / code refactor / configuration change / locales update / quality assurance / other.
3. Checklist — you ran yarn run tsc, yarn run lint, yarn run prettier, yarn run test (i.e. everything yarn verify runs).
4. Testing — did you add unit tests for modified utility files (options: "No, I'm a fool" / Yes / N/A).
5. Platform matrix — Android and iOS checkboxes, with OS version and phone model/VM. This is where Rule 4 is attested.
6. Backend testing matrix — which of the 7 node types you tested against, with node/API versions: On-device: LDK Node, Embedded LND; Remote: LND (REST), LND (Lightning Node Connect), Core Lightning (CLNRest), Nostr Wallet Connect, LndHub.
7. Locales — new translatable text flagged; acknowledgment that translations happen on Transifex, not in-repo. (The template's "Transfix" spelling is a known typo — leave it.)
8. Third-party dependencies — whether contributors must re-run yarn, whether package.json/yarn.lock changed, both-platform install verified.
9. Other — README or onboarding updates needed?

First-time contributors: proof of work

Per CONTRIBUTING.md: first-time contributors submitting features or UI changes must attach screenshot or video evidence that the change works, directly in the PR description. PRs without it are closed within 24 hours; repeat offenders are blocked. Also: no trivial typo/whitespace first PRs; issue assignment is team-only — just comment that you've started.

Review vocabulary (Bitcoin-Core style, defined in CODE_REVIEW.md)

Review flow

• Fetch a PR locally: git fetch origin pull/<N>/head:pr-<N> then git checkout pr-<N> (from CODE_REVIEW.md).
• During review, push fixup commits (easy to re-review); squash before merge. Rebase on master; no merge commits in the branch.
• Merge requirements (CONTRIBUTING.md): all CI checks pass, ≥1 maintainer approval, no unresolved conversations, up to date with base.
• Review checklist highlights (full list in CODE_REVIEW.md): no sensitive data (keys, macaroons, seeds) logged or exposed; inputs validated on payment paths; no potential fund-loss scenarios; no unnecessary any types; works across themes/locales/font sizes; commits atomic. Separately, CONTRIBUTING.md ("Test Coverage") requires that bug fixes include a test that would have caught the bug.

4. Commit style

CONTRIBUTING.md prescribes component: prefixes (views:, stores:, backends:, utils:, build:, docs:, tests:) — that is the written rule and this skill does not override it. Master history additionally shows conventional-commit-ish prefixes being accepted in practice (122 of the last 200 commit subjects at c5fd094fb use them; most of the rest are merge commits), so either observed style is tolerated in review — but absent a maintainer statement authorizing otherwise, default to the CONTRIBUTING.md component prefixes. Real examples from git log:

fix(migrations): pass object to setSettings to avoid MobX observable corruption (#4150)
fix(utxo-picker): restore UTXO labels and keep Set button above gesture bar
ui: Receive: prevent input field flash on initial load via initialLoad state
refactor: Receive: extract skipOnchain into helper
docs: fix NWC service link in README (#4179)
chore(deps): bump concurrent-ruby from 1.3.3 to 1.3.7

Rules:

• Subject ≤ ~50 chars where possible; body wrapped at 72, explaining problem + why this approach (CONTRIBUTING.md).
• Atomic commits; each should ideally pass yarn verify independently.
• Version bumps are exactly Version bump: vX.Y.Z[-alpha|-beta1] (e.g. Version bump: v13.1.3-alpha) — maintainer-only.
• NO AI co-author lines (Co-Authored-By: Claude ... or similar) in any commit — maintainer rule, stated 2026-07-06, not in any doc.
• Branch names: feature/..., fix/..., refactor/....
• When citing hashes in commit messages or discussions, use first-parent master hashes: git log --all contains duplicated/grafted merge hashes (e.g. PR #3444 appears as both 28bc50f5e and f47ef1acf).

5. CI reality: green PR = exactly 4 checks

Verified in .github/workflows/ at c5fd094fb: exactly four workflows trigger on pull_request —

All four = yarn verify locally (package.json: concurrently "yarn test" "yarn prettier" "yarn tsc" "yarn lint"). Run yarn verify before every push. Details of each job's traps (check-styles trick, Prettier pinned at 2.4.1, jest transform whitelist): zeus-validation-and-qa.

What PR CI does NOT do: no mobile build, no dependency scan — build-android.yml and dependency-scan.yml are workflow_dispatch-only (manually triggered); telegram.yml is a push/release notifier, not a check. This is exactly why Rule 4 (manual two-platform testing) exists.

CI runs on ubuntu-latest, Node 24.x, yarn install --frozen-lockfile.

6. Dependency policy

• Discuss before adding any new library (CONTRIBUTING.md "Discuss new dependencies"): there may be an existing in-repo solution or a preferred alternative, and every dependency is supply-chain surface in a funds-handling app.
• Zeus vendors some packages under zeus_modules/ (some via file: refs, some imported by relative path and deliberately NOT in package.json). Never yarn add something that lives there. Mechanics: zeus-build-and-env.
• If a PR modifies dependencies: tick the PR-template third-party section, confirm package.json + yarn.lock are consistent, and verify install on both iOS and Android.

7. Locales

• Only locales/en.json may be edited in-repo. The other 33 locale files (34 total in locales/ as of 2026-07-06) are managed through Transifex (https://explore.transifex.com/ZeusLN/zeus/) and must never be modified directly — such PRs get rejected.
• All user-facing strings must go through the localization system; no hardcoded UI text.
• Want to translate? Request a language role on Transifex, not a PR.

8. Docs house rules

• In-repo docs inventory: README.md (project overview, feature list, integration guides), CONTRIBUTING.md (contribution process — source of truth for everything in Sections 2–4 here), CODE_REVIEW.md (review process and vocabulary), docs/Bounties.md (bounty program; reportedly partially stale — check open bounties against the issue tracker before relying on it), docs/RemoteConnections.md (node-connection guides), docs/ReproducibleBuilds.md (Android-only reproducible builds).
• External user docs of record: https://docs.zeusln.app/ — README links there for all user-facing feature documentation. User-behavior changes may need updates there (out-of-repo), plus README/onboarding per the PR template's "Other" section.
• License: AGPLv3 (see LICENSE). All contributions must be AGPLv3-compatible; submitting a PR is agreement to that (CONTRIBUTING.md).
• Signing: all releases and all maintainer commits since 2021-10-20 are PGP-signed with key AAC48DE8AB8DEE84 (full fingerprint 96C225207F2137E278C31CF7AAC48DE8AB8DEE84, Zeus LN zeusln@tutanota.com); public key in PGP.txt (README.md "Release + Commit Verification" section). Contributors are not required to sign.
• Writing style for docs changes: match existing docs; docs: commit prefix; don't bundle doc fixes into code PRs.

Pre-PR checklist (condensed)

1. Classified the change (Section 2)? Storage-touching → maintainer sign-off FIRST. Funds-touching → minimal diff, discussed first.
2. yarn verify green locally.
3. Manually tested on iOS AND Android (Rule 4); backends exercised and recorded.
4. New strings in locales/en.json only; no other locale files touched.
5. Commits: CONTRIBUTING.md component-prefix style (conventional-commit-ish prefixes are tolerated in practice), atomic, no AI co-author lines, rebased on master.
6. PR template fully filled in — not deleted; screenshots for UI changes (mandatory for first-timers).
7. If a dependency changed: was it discussed first?

Provenance and maintenance

Facts verified 2026-07-06 against master c5fd094fb (v13.1.3-alpha). Maintainer-stated rules (Section 1, no-AI-co-author) confirmed verbally 2026-07-06 — they appear in no repo document; everything else was verified by reading the cited files or running the commands below.

Re-verify volatile facts: