sattle/src/lnurlcash/AGENTS.md

src/lnurlcash — protocol engine

Framework-free LNURLcash core: no Vue, no Pinia, no Quasar imports. Pinia stores call these modules and apply returned changesets; UI never touches lnurlcash-kit directly.

FUND-CRITICAL INVARIANTS (non-negotiable)

• Rotate on every receive, and immediately after claiming a fresh mint.
• A note's declared amount is a claim; the service's maxWithdrawable is authoritative.
• A melt's "OK" only means the payment is in flight — the verify URL (or the note becoming spendable again) is the real outcome.
• An ambiguous mutation NEVER loses fresh secrets: rescued into tracked notes, probed, or surfaced to the caller unverified.
• Definitive service answers (NoteSpentError / NoteUnknownError / PendingNoteError) always propagate distinctly — never papered over by an unverified fallback.

STRUCTURE

ops.ts / ops/    # flows: carve (exact-amount), mint, pay, receiveBearer,
                 # transfer (inter-mint); ops.ts is the façade
storage/         # encrypted bearers + activity log, settings, backup,
                 # nwcConnections, passkeySlots; storage.ts is the façade
keys.ts          # BIP39, LUD-05 linking key derivation, password wrap
passkeys.ts + passkeyWrap.ts   # WebAuthn PRF wrap (same linking key)
nostrBackup.ts + nostr/        # kind-30078 backup, NIP-44 self-encryption
nwc.ts + nwc/    # NIP-47 wallet service
fees.ts          # mint fee math (gross/net direction!) + cached quotes
trustedMints.ts  # key pinning, rekey staging, backup merge rules
test-utils.ts    # mock mint harness used by *.test.ts

CONVENTIONS

• Style: NO semicolons, 2-space indent, single quotes, {braced} imports without inner spaces — deliberately different from the rest of the app (eslint override); keep the tested core diffable against its lineage.
• Storage: localStorage keys sattle_*; strict shape validation on read, malformed entries dropped; read-modify-write under withStorageLock.
• Network: kit calls only; injectable transport/options so tests never touch the network. No WebSocket at import time (lazy import()).
• Every module header comment explains the WHY, including failure models.

TESTS

npx vitest run — node environment, *.test.ts next to the modules. Adversarial mock mint from lnurlcash-conformance via test-utils.