feat(payments): pre-warm the send path with prepareSend [AMB-3038]

[bufo24]

Closes AMB-3038

Problem

Transactions.send() did the full credential derivation on every call: two GraphQL round-trips (GetWalletSendContext, GetWalletNodePermissions) plus two Argon2id passes (m=64 MiB, t=3, p=4) to decrypt the admin macaroon. That is seconds of latency on each payment, all of it redundant after the first send from the same wallet.

What changed

send() is split into a prepare step (wallet context → node permissions → Argon2id → nip44 decrypt) and the payment itself (CreateSendTransaction + node REST call). The prepare step is cached per wallet, so it runs once instead of per send.

New public API on Transactions:

Method	Purpose
prepareSend(params)	Runs the prepare step ahead of time and caches the macaroon
isSendReady(walletId)	Whether a prepared macaroon is resident — false while still deriving
forgetSend(walletId)	Drops it, releasing the decrypted macaroon

PaymentsConfig gains an optional send: readonly PrepareSendParams[] to pre-warm wallets from the constructor. Pre-warming runs sequentially — Argon2id is CPU-bound, so concurrency would only delay readiness — and swallows per-wallet failures. A missing serviceApiKey, by contrast, throws from the constructor rather than silently pre-warming nothing.

The one rule the cache runs on

Only prepareSend writes the cache, and only a send that omits password reads it. A send carrying a password derives afresh — exactly as it does in the published version.

That is a deliberate constraint, not an oversight. An earlier revision of this PR keyed the cache on credentials so a password-bearing send could hit it too. Doing that obliges the cache to answer "are these the same credentials?", and that single question generated passwordFingerprint, a Credentials/PendingSlot/ReadySlot trio, an isReusable wildcard-and-provenance chain, an overrodeTeamId flag, a #ready/#pending split, a pending-attempt array — and three successive rounds of bugs:

1. a wrong password evicting an already-prepared wallet,
2. a concurrent bad-credential attempt displacing a good in-flight one and discarding its result,
3. an omitted teamId being answered from a slot derived with an explicit override.

Making the cache credential-blind removes all of it. The three bugs are now impossible by construction rather than fixed: a failing send never touches the map, a wallet has one identity instead of a set to match against, and there is no provenance to track. Net −117 lines, and the README's five cache-behaviour bullets collapse to one — which also closes a contract leak where callers had to model the SDK's internal credential matching to predict whether a send would be fast.

The cost is narrow and explicit: a caller who passes password on every send() gets no speedup. Omit it to use the prepared macaroon.

Security posture

• Master key is discarded. Only the macaroon is retained; masterKey and masterPasswordHash stay locals of the derivation frame. Verified by tracing closure capture — the cached value and the retained promise reach neither the plaintext password nor the master key. A prepared wallet holds admin access to one node, not the key to every wallet in the team.
• A failing send harms nothing. It never reads or writes the cache, so a typo'd password fails that one call and leaves the prepared wallet working.
• forgetSend wins races. A preparation resolving after it is discarded rather than resurrecting the macaroon.
• Blocking is documented. Argon2id is synchronous; prepareSend is async because of the API calls, not because key derivation yields. Prepare at startup, not per request.

Also in here

• Re-derived onto current main, so the cached path picks up fee_limit_sat (fix: send a fixed fee limit on Transactions.send [AMB-2979] #37) and the already-COMPLETED short-circuit (fix: return already-completed send without re-paying on the node [AMB-2985] #39). Both sit on the single shared path after the cache lookup, so a cache hit cannot bypass them; pinned by a test.
• Test-collection fix, unrelated to this feature. tsx --test src/**/*.test.ts was unquoted, and under sh ** collapses to one directory level — so packages/payments/src/client.test.ts had never run. core escaped it only because it has no subdirectory tests, leaving the pattern unexpanded for tsx to glob itself. Quoting it hands the pattern to tsx in both packages: payments goes 44 → 51 tests. Happy to split this out if you'd rather it landed separately.

Release impact

New public API on a published package (npm is at 1.0.3) — release-please will cut a minor. Deliberately not marked breaking: prepareSend does not exist on main, and send({walletId, password}) behaves as the published version already does.

Test plan

• pnpm run build / typecheck / format:check — pass
• pnpm run test — 62/62 (11 core, 51 payments)
• pnpm run typecheck:examples / test:examples — pass (dual ESM/CJS build)
• A prepared password-less send issues only CreateSendTransaction
• A send passing a password always re-derives and leaves the prepared wallet intact
• isSendReady() is false while deriving, true once resolved, false after forgetSend()
• Sandbox wallets prepare, and still send unprepared, without a password
• Prepared sends still carry fee_limit_sat
• send pre-warm without serviceApiKey throws ConfigError from the constructor
• Manual check against a live wallet before merge

Known follow-up

forgetSend cannot cancel an in-flight Argon2id pass — the derivation runs to completion and its result is discarded. Fixing it means threading an AbortSignal through PrepareSendParams, a public API change beyond this PR.

Docs updated in AGENTS.md, packages/payments/README.md, and docs/INTEGRATION.md.

🤖 Generated with Claude Code