plan to add `state` to accounts for expiring and soft deleting by gudnuf · Pull Request #960 · MakePrisms/agicash

gudnuf · 2026-03-26T08:16:38Z

Summary

Design spec for adding active → expired → deleted lifecycle to wallet.accounts. For review/discussion before implementation.

Auto-expiry: pg_cron flips active → expired hourly when expires_at passes
Soft delete: Client-initiated RPC, hidden via restrictive RLS policy
One-way transitions: Enforced by DB trigger (no reactivation)
Partial unique index: Scoped to state = 'active' so expired/deleted accounts don't block new ones at the same mint

What this enables

Expired offer accounts stop showing as active without app-code changes to every query
Users can delete old offer accounts
New offers at the same mint work even after prior account expired

Open questions

Delete UI placement (hook is specced, UX is separate)
Expired balance recovery (proofs may still be swappable, separate feature)

No code changes — spec only.

Two bugs with v2 keysets: getDecodedToken fails without keyset IDs for resolution, and re-encoded tokens have truncated IDs that can't be looked up. Fix uses dependency-injected keyset resolver with cache-first strategy, plus raw token string passthrough in paste/scan.

- extractCashuTokenString validates via getTokenMetadata (not just regex) - extractCashuToken uses try/catch like cashu.me for v2 detection - Preserves immediate validation UX in paste/scan handlers

4 tasks: token functions + tests, resolver factory, paste/scan handlers, route clientLoaders. Includes v2-specific tests with round-trip verification.

Design doc for adding active/expired/deleted lifecycle to wallet.accounts. Covers DB migration (enum, transition trigger, partial unique index, RLS, pg_cron auto-expiry), app-layer changes, and data flow diagrams. For review/discussion before implementation.

vercel · 2026-03-26T08:16:41Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
agicash	Ready	Preview, Comment	Apr 7, 2026 2:48am

supabase · 2026-03-26T08:16:45Z

This pull request has been ignored for the connected project hrebgkfhjpkbxpztqqke because there are no changes detected in supabase directory. You can change this behaviour in Project Integrations Settings ↗︎.

Preview Branches by Supabase.
Learn more about Supabase Branching ↗︎.

No longer needed — account state lifecycle replaces this approach.

Client-side expiry in upsert_user_with_accounts transitions stale accounts before returning them. pg_cron remains as background cleanup for offline users.

Each DB function's WHERE clause only matches valid source states. soft_delete_account gains AND state != 'deleted' guard.

gudnuf · 2026-03-26T08:39:38Z

+  if not found then
+    raise exception
+      using
+        hint = 'NOT_FOUND',


if not found because account is already deleted should this return a different error message that its already deleted?

hm I wonder if we should just make it idempotent and do nothing if already deleted

gudnuf · 2026-03-26T08:41:45Z

+
+This runs inside the existing transaction, before the `accounts_with_proofs` CTE that fetches accounts. The client receives already-expired accounts with `state = 'expired'` — no second round-trip needed.
+
+### pg_cron job for auto-expiry


I was thinking we should keep this around for when the user doesn't open the app for a long time, but do you think its needed

i actually think this is needed and not sure about one in upsert_user_with_accounts. see my comments above

gudnuf · 2026-03-26T08:42:50Z

+### `gift-cards.tsx` -- Simplify filter
+
+```typescript
+function useActiveOffers() {


this is from code I haven't committed yet btw

jbojcic1 · 2026-04-02T14:02:50Z

+
+**Decision: App layer.**
+
+Expired accounts remain visible in `getAll()` -- the RLS policy does not hide them. The existing `useActiveOffers()` filter in `gift-cards.tsx` is simplified from the `expiresAt > now()` check to `account.state === 'active'`.


depending on how we move state to expired there might be some time between expiresAt passing and state being change. we need to have that in mind and see if that poses any problems for us

jbojcic1 · 2026-04-02T14:03:51Z

+
+**Decision: Two layers — eager on user assertion, pg_cron as background cleanup.**
+
+**Eager (on login):** `upsert_user_with_accounts` expires stale accounts before returning them. When a user opens the app, any account with `state = 'active'` and `expires_at <= now()` is transitioned to `expired` within the same transaction. The client gets correct state on first load — no stale-then-update flicker.


not sure if this adds any value since the account can expires after first load

removed in favor of a 1 minute cron job plus client side error handling for expired accounts that have not yet transitioned to expired

jbojcic1 · 2026-04-02T14:08:51Z

+
+**Eager (on login):** `upsert_user_with_accounts` expires stale accounts before returning them. When a user opens the app, any account with `state = 'active'` and `expires_at <= now()` is transitioned to `expired` within the same transaction. The client gets correct state on first load — no stale-then-update flicker.
+
+**Background (pg_cron, hourly):** A cron job catches accounts for users who haven't opened the app. This keeps the DB consistent for realtime broadcasts and prevents stale `active` accounts from accumulating. pg_cron is already installed and used for 8 daily cleanup jobs — no new infrastructure.


probably better to run every minute or see if there is some way to schedule some work to be done for the exact time

claude says there's no way to schedule an exact time so we just went for 1 minute

jbojcic1 · 2026-04-02T14:11:09Z

+as restrictive
+for select
+to authenticated
+using (state != 'deleted'::wallet.account_state);


i think this also requires index on state column to be efficient

jbojcic1 · 2026-04-02T14:14:34Z

+  if not found then
+    raise exception
+      using
+        hint = 'NOT_FOUND',


hm I wonder if we should just make it idempotent and do nothing if already deleted

jbojcic1 · 2026-04-02T14:15:14Z

+
+This runs inside the existing transaction, before the `accounts_with_proofs` CTE that fetches accounts. The client receives already-expired accounts with `state = 'expired'` — no second round-trip needed.
+
+### pg_cron job for auto-expiry


i actually think this is needed and not sure about one in upsert_user_with_accounts. see my comments above

jbojcic1 · 2026-04-02T14:16:21Z

+```typescript
+function useActiveOffers() {
+  const { data: offerAccounts } = useAccounts({ purpose: 'offer' });
+  return offerAccounts.filter((account) => account.state === 'active');


we should use useQuery select for filtering like this. see other examples where we are already using it

- Drop eager expiry from upsert_user_with_accounts, use 1-minute pg_cron only - Mark deleted state as pending decision with Option A/B - Rename soft_delete_account to delete_account - Update enforce_accounts_limit to count only active accounts - Add idx_accounts_state index - Note useQuery select pattern for filtering - Add graceful error handling for expired keysets - Note PR #959 (offer mints) is merged Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

…only Decision: expired is the terminal state for v1. Removes the deleted enum value, RLS restrictive policy, delete_account DB function, useDeleteAccount hook, cache removal logic, and all PENDING DECISION sections. Simplifies transitions to active -> expired only. Delete functionality deferred to future PRs. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Move expired account filtering from client-side select to AccountRepository.getAll() with .eq('state', 'active'). RLS is not viable because security invoker DB functions need expired accounts for in-flight operations. get(id) remains unfiltered for the same reason. Simplify useActiveOffers() and update implementation phases. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

gudnuf · 2026-04-07T00:19:54Z

+
+No eager expiry in `upsert_user_with_accounts` — the 1-minute cron granularity is sufficient for the UX. At most, a user sees a stale active account for up to 60 seconds before the next cron run corrects it.
+
+**Graceful error handling:** If the client somehow triggers an operation on an expired account (race condition between cron expiring the account and user initiating an action), catch the mint rejection and show the user "this offer has expired". Trigger a cache invalidation to pull fresh account state from the server.


@orveth Let's look into exactly when this error would occur and what the error code would be, if any, from the mint (nuts define these error codes). I want to know exactly how we will handle these errors and when they will occur.

Researched this. The error is KEYSET_INACTIVE (code 12002), already defined in error-codes.ts. It surfaces in 3 code paths:

Melt — attempting to spend from an expired offer

Send-swap — swapping tokens out of an expired keyset

Receive-swap — swapping tokens into a keyset that expired between claim and swap

Handling approach: catch MintOperationError with code 12002, check account.purpose === 'offer', and throw a DomainError("This offer has expired"). All documented in the updated spec under the error handling section.

gudnuf · 2026-04-07T00:21:29Z

+
+### `gift-cards.tsx` -- Simplify filter
+
+`useActiveOffers()` no longer needs to filter by `state === 'active'` since `getAll()` already excludes expired accounts at the query level. It becomes a simple query for `purpose: 'offer'` accounts:


@orveth Let's just change this to useOfferCards or something that matches how the gift cards call its own hooks for a regular gift-card accounts. We don't need to call them active anymore.

Done — renamed to useOfferCards throughout the spec in the latest push. Matches the gift-card hook naming convention.

gudnuf · 2026-04-07T00:22:37Z

+Client triggers operation on account just before cron expires it
+  -> Mint rejects operation (keyset expired)
+  -> Catch mint rejection, show "this offer has expired"
+  -> Trigger cache invalidation to pull fresh state


@orveth Is it really worth invalidating the cache Here, because we should get the real time update when it's actually invalidated, right?

Agreed — the realtime ACCOUNT_UPDATED event handles this. Removed the explicit cache invalidation in the latest push; the spec now relies on the existing subscription.

gudnuf · 2026-04-07T00:24:50Z

+
+**Why not RLS?** All DB functions (`get_account_with_proofs`, `create_cashu_send_quote`, etc.) are `security invoker`, so they execute with the calling user's RLS context. A restrictive RLS policy hiding expired accounts would break any in-flight quote or swap operation whose account expires mid-transaction. The DB functions need to see expired accounts to complete already-started operations.
+
+**Why not a `useQuery` `select` filter?** Since `getAll()` excludes expired accounts at the query level, there is no need for a client-side `select` filter -- the data simply never arrives at the client.


@orveth This line is redundant, I think. It's now obvious Because of the way that the query worksWe don't need to mention anything about this. Let's remove it.

Removed in the latest push. That paragraph was leftover context that the query structure already communicates.

…ve redundant section - Add detailed graceful error handling for KEYSET_INACTIVE (12002) race window - Scope error handling to offer accounts only via account.purpose check - Rename useActiveOffers → useOfferCards throughout - Remove redundant "Why not useQuery select" paragraph - Replace explicit cache invalidation with realtime event handling - Add 12002 catch task to Phase 3 Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

gudnuf · 2026-04-13T16:14:46Z

we merged #984 so we don't need this

gudnuf added 4 commits March 20, 2026 10:18

Update v2 keyset spec: validate with getTokenMetadata, try/catch decode

374d786

- extractCashuTokenString validates via getTokenMetadata (not just regex) - extractCashuToken uses try/catch like cashu.me for v2 detection - Preserves immediate validation UX in paste/scan handlers

Add implementation plan for cashu v2 keyset support

79e870f

4 tasks: token functions + tests, resolver factory, paste/scan handlers, route clientLoaders. Includes v2-specific tests with round-trip verification.

vercel bot deployed to Preview March 26, 2026 08:17 View deployment

gudnuf added 2 commits March 26, 2026 01:25

Remove v2 keyset plans and specs

237f021

No longer needed — account state lifecycle replaces this approach.

Add eager expiry on user assertion

f2a5fbf

Client-side expiry in upsert_user_with_accounts transitions stale accounts before returning them. pg_cron remains as background cleanup for offline users.

vercel bot deployed to Preview March 26, 2026 08:27 View deployment

Drop state transition trigger, enforce by construction

7ab30e4

Each DB function's WHERE clause only matches valid source states. soft_delete_account gains AND state != 'deleted' guard.

vercel bot deployed to Preview March 26, 2026 08:35 View deployment

gudnuf commented Mar 26, 2026

View reviewed changes

gudnuf requested a review from jbojcic1 March 26, 2026 18:45

orveth assigned ditto-agent and gudnuf and unassigned ditto-agent and gudnuf Mar 27, 2026

orveth requested review from ditto-agent and removed request for jbojcic1 March 28, 2026 09:20

gudnuf changed the title ~~Account state lifecycle spec~~ plan to add state to accounts for expiring and soft deleting Mar 28, 2026

orveth added the plan Plan or spec document label Mar 28, 2026

jbojcic1 reviewed Apr 2, 2026

View reviewed changes

orveth and others added 2 commits April 6, 2026 13:53

vercel bot deployed to Preview April 6, 2026 22:06 View deployment

vercel bot deployed to Preview April 6, 2026 22:31 View deployment

gudnuf commented Apr 7, 2026

View reviewed changes

vercel bot deployed to Preview April 7, 2026 02:48 View deployment

orveth mentioned this pull request Apr 7, 2026

Add account state lifecycle (active → expired) #984

Merged

gudnuf closed this Apr 13, 2026

gudnuf deleted the docs/account-state-lifecycle branch April 13, 2026 16:14


		This runs inside the existing transaction, before the `accounts_with_proofs` CTE that fetches accounts. The client receives already-expired accounts with `state = 'expired'` — no second round-trip needed.

		### pg_cron job for auto-expiry


		Decision: App layer.

		Expired accounts remain visible in `getAll()` -- the RLS policy does not hide them. The existing `useActiveOffers()` filter in `gift-cards.tsx` is simplified from the `expiresAt > now()` check to `account.state === 'active'`.


		Decision: Two layers — eager on user assertion, pg_cron as background cleanup.

		Eager (on login): `upsert_user_with_accounts` expires stale accounts before returning them. When a user opens the app, any account with `state = 'active'` and `expires_at <= now()` is transitioned to `expired` within the same transaction. The client gets correct state on first load — no stale-then-update flicker.


		Eager (on login): `upsert_user_with_accounts` expires stale accounts before returning them. When a user opens the app, any account with `state = 'active'` and `expires_at <= now()` is transitioned to `expired` within the same transaction. The client gets correct state on first load — no stale-then-update flicker.

		Background (pg_cron, hourly): A cron job catches accounts for users who haven't opened the app. This keeps the DB consistent for realtime broadcasts and prevents stale `active` accounts from accumulating. pg_cron is already installed and used for 8 daily cleanup jobs — no new infrastructure.


		No eager expiry in `upsert_user_with_accounts` — the 1-minute cron granularity is sufficient for the UX. At most, a user sees a stale active account for up to 60 seconds before the next cron run corrects it.

		Graceful error handling: If the client somehow triggers an operation on an expired account (race condition between cron expiring the account and user initiating an action), catch the mint rejection and show the user "this offer has expired". Trigger a cache invalidation to pull fresh account state from the server.


		### `gift-cards.tsx` -- Simplify filter

		`useActiveOffers()` no longer needs to filter by `state === 'active'` since `getAll()` already excludes expired accounts at the query level. It becomes a simple query for `purpose: 'offer'` accounts:


		Why not RLS? All DB functions (`get_account_with_proofs`, `create_cashu_send_quote`, etc.) are `security invoker`, so they execute with the calling user's RLS context. A restrictive RLS policy hiding expired accounts would break any in-flight quote or swap operation whose account expires mid-transaction. The DB functions need to see expired accounts to complete already-started operations.

		Why not a `useQuery` `select` filter? Since `getAll()` excludes expired accounts at the query level, there is no need for a client-side `select` filter -- the data simply never arrives at the client.

Conversation

gudnuf commented Mar 26, 2026

Summary

What this enables

Open questions

Uh oh!

vercel bot commented Mar 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

supabase bot commented Mar 26, 2026

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

gudnuf commented Apr 13, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

vercel bot commented Mar 26, 2026 •

edited

Loading