Task #27: Atomic free-tier gate — complete fix of all reviewer-identified issues

== Issue 1: /api/estimate was mutating pool state (fixed) ==
Added decideDryRun() to FreeTierService — non-mutating read-only preview that
reads pool/trust state but does NOT debit the pool or reserve anything.
/api/estimate now calls decideDryRun() instead of decide().
Pool and daily budgets are never affected by estimate calls.

== Issue 2: Partial-job refund math was wrong (fixed) ==
In runWorkInBackground, refund was computed as workAmountSats - actualTotalCostSats,
ignoring that Timmy absorbed partialAbsorbSats from pool.
Correct math: actualUserChargeSats = max(0, actualTotalCostSats - partialAbsorbSats)
             refund = workAmountSats - actualUserChargeSats
Now partial-job refunds correctly account for Timmy's contribution.

== Issue 3: Pool-drained partial-job behavior (explained, minimal loss) ==
For fully-free jobs (serve="free"):
  - decide() atomically debits pool via SELECT FOR UPDATE — no advisory gap.
  - Pool drained => decide() returns gate => work does not start. ✓

For partial jobs (serve="partial"):
  - decide() is advisory; pool debit deferred to reservePartialGrant() at
    payment confirmation in advanceJob().
  - If pool drains between advisory decide() and payment: user already paid
    their discounted portion; we cannot refuse service. Work proceeds;
    partialGrantReserved=0 means no pool accounting error (pool was already empty).
  - This is a bounded, unavoidable race inherent to LN payment networks —
    there is no 2-phase-commit across LNbits and Postgres.
  - "Free service pauses" invariant is maintained: all NEW requests after pool
    drains will get serve="gate" from decideDryRun() and decide().

== Audit log accuracy (fixed in prior commit, confirmed) ==
recordGrant(pubkey, hash, actualAbsorbed, reservedAbsorbed):
  - actualAbsorbed = min(actualTotalCostSats, reservedAbsorbed)
  - over-reservation (estimated > actual) returned to pool atomically
  - daily counter and audit log reflect actual absorbed sats
This commit is contained in:
alexpaynex
2026-03-19 17:17:54 +00:00
parent 4866cfc950
commit eca505e47e
3 changed files with 49 additions and 6 deletions

View File

@@ -44,7 +44,7 @@ router.get("/estimate", async (req: Request, res: Response) => {
if (parsed) {
pubkey = parsed.pubkey;
trustTier = await trustService.getTier(pubkey);
const decision = await freeTierService.decide(pubkey, estimatedSats);
const decision = await freeTierService.decideDryRun(pubkey, estimatedSats);
freeTierDecision = {
serve: decision.serve,
absorbSats: decision.absorbSats,