PROJECT KNOWLEDGE BASE

Generated: 2026-08-20 Commit: 7841a13 Branch: main

OVERVIEW

sattle — end-user PWA wallet for LNURLcash (LUD-25) Lightning bearer notes. Quasar 2 / Vue 3 (script setup + TS) / Pinia / vue-i18n. Capacitor 8 Android wrapper lives in android/; the PWA is the canonical build.

STRUCTURE

src/lnurlcash/    # protocol engine + storage, framework-free (own AGENTS.md)
src/stores/       # Pinia: wallet, mints, activity, nostrBackup, nwc
src/components/   # dialogs (send/, receive/), QrCode, QrScanner, UnlockForm
src/pages/        # IndexPage (main), Settings*, ManageMints, MoveFunds, Nwc,
                  # Backup, Security, Welcome (onboarding)
src/capabilities/ # ONLY place Capacitor plugins are imported
src/boot/         # wallet init, deeplinks
e2e/              # Playwright (own AGENTS.md)

WHERE TO LOOK

Task	Location	Notes
Any fund movement	`src/lnurlcash/ops/`	engine returns changesets, never mutates state
Add a settings page	`src/pages/` + `router/routes.ts` + SettingsPage group	back-button header pattern
Native feature	`src/capabilities/`	never import plugins elsewhere
Change wallet state	stores call ops + `addBearers`/`markSpent`	add fresh notes BEFORE marking spent
Mint fee math	`src/lnurlcash/fees.ts`	gross vs net direction matters

CODE MAP

Module	Role
`lnurlcash/ops.ts`	façade: carve/mint/pay/receiveBearer/transfer
`lnurlcash/storage/`	AES-GCM bearers+activity, backup (merge entry point), settings
`lnurlcash/keys.ts`	BIP39 + LUD-05 linking key; password wrap
`lnurlcash/passkeys.ts`	WebAuthn PRF wrap of the SAME linking key
`lnurlcash/nostrBackup.ts`	kind-30078 NIP-44 backup + restore via applyBackup
`lnurlcash/nwc/`	NIP-47 wallet service (per-connection budget)
`stores/wallet.ts`	state none/locked/unlocked; linking key in memory only while unlocked

CONVENTIONS

Commit style: semantic (feat:, fix:, build:, ci:, test:), English.
Releases: release-please (.github/workflows/release.yml) — never bump versions or write changelog entries by hand; merge the release PR.
Hash router; BlankLayout for /welcome (q-page needs a layout).
Dark theme, #002222 bg, mint #55ffcc primary; sattle-card surfaces.
Quasar Notify plugin is enabled — use it for toasts.
Brand assets: src/assets/sattle-{wallet,text}.png (raster; source SVGs live outside the repo).

ANTI-PATTERNS (THIS PROJECT)

NEVER mutate wallet state inside src/lnurlcash/** — engine is pure.
NEVER auto-apply a mint's advertised new signing key — stage as pending rekey.
NEVER log note URLs / k1 values.
No type suppression (as any, @ts-ignore) anywhere.
No new runtime deps without a recorded reason (nostr-tools is the bar).

COMMANDS

npx quasar dev -m spa      # dev
npx vitest run             # unit (node env, mock mint)
npm run test:e2e           # playwright, system chromium (CHROMIUM_PATH)
npx vue-tsc --noEmit       # typecheck
npx quasar build -m pwa    # production build
npm run cap:sync           # build + cap sync android

NOTES

NixOS: use the flake dev shell (nodejs_22 + chromium for e2e). sass-embedded is aliased to pure-JS sass via npm overrides.
lnurlcash-kit comes from github:TheCryptoDonkey/lnurlcash-kit pinned to a commit — the prepare script (our merged PR#1) builds dist on install.
tsconfig deliberately relaxed (exactOptionalPropertyTypes etc. off) to keep the protocol core untouched; src/lnurlcash has an eslint override.
Gitea remote dropped; origin = GitHub. Gitea mirror = pull-mirror on the Gitea side (no secrets needed).

3.7 KiB Raw Blame History