smirk-backend-core/docs/design/premium-relay.md

Spec — Premium relay access (recurring)

Status: implemented — a design overview of the as-built feature (shipped v0.3.0).

1. Summary

A premium tier: registration and wallet use stay free (PoW-gated); an optional recurring fee (e.g. $5 / quarter) grants posting access to the operator's Nostr relay. This reframes payment from pay-to-register (a one-time gate on wallet creation) to a subscription (a recurring gate on relay writes). Everything else — register, unlock, balances, tip stats, receiving DMs, posting to public relays — remains free.

This is the flagship cookbook recipe (examples/paid-relay/): a complete, working demonstration of operator monetization, built entirely on seams that already exist (PaymentProvider + the relay admission engine).

2. Goals / non-goals

Goals

• Recurring revenue with real utility (relay posting), not a cosmetic badge.
• Compose from existing seams — no new architecture.
• Operator-configurable + advertised via /capabilities; self-hosting bypasses it.
• Rigorous: migration, OpenAPI, capabilities golden, unit + L2 + E2E tests.

Non-goals (v1)

• Read-gating. Reads stay open (or DM-reads via NIP-42 later). Paid relays conventionally gate writes; gating reads needs NIP-42 AUTH + a premium check and is a possible v2.
• Auto-charge subscriptions. Crypto has no card-on-file; premium is a prepaid period — the user re-pays each term or posting lapses. Honest + simple.
• Fiat. Uses the existing crypto PaymentProvider; fiat on-ramp is separate.

3. Model

The free tier includes everything that makes the wallet work — including publishing wallet-functional events to the operator's relay (encrypted DMs that ride with tips, and future P2P atomic-swap coordination). Premium adds using that relay as a general-purpose Nostr relay (notes, reactions, anything).

Capability	Free	Premium
Register / unlock / use wallet (all chains)	✅	✅
Login, view tip/balance stats	✅	✅
Receive DMs (gift-wrap delivery to you)	✅	✅
Publish wallet events to the operator's relay (encrypted DMs, tips, swap coordination)	✅	✅
Publish to public relays (damus, nos.lol…)	✅	✅
Publish general Nostr to the operator's relay (kind-1 notes, reactions, …)	❌	✅ while premium_until > now

The value line: the relay is free for what makes your wallet work; you pay to use it as your everyday Nostr relay. Free users are never cut off from wallet features.

4. Data model

Migration ..._premium.sql:

ALTER TABLE users ADD COLUMN premium_until TIMESTAMPTZ;  -- NULL = never premium
-- No standalone index on premium_until: is_premium_npub keys on the existing UNIQUE
-- index on users.nostr_pubkey and `premium_until > NOW()` is a cheap per-row filter,
-- so an index here would only add write cost to every users UPDATE.

A dedicated premium_invoices table (not a purpose column on payment_invoices), because premium binds on the authenticated user_id (a logged-in purchase) while registration invoices bind on plaintext pubkey_hash — cleaner than a nullable either-or. Columns: invoice_id PK, user_id FK (ON DELETE CASCADE), provider, plan_id, period_days, amount, currency, created_at, consumed_at; a partial WHERE consumed_at IS NULL index for the single-use lookup + a per-user pending cap.

DB fns (infra/db/premium_invoices.rs + users.rs):

• is_premium_npub(nostr_pubkey) -> bool — SELECT EXISTS(... WHERE nostr_pubkey = $1 AND premium_until > NOW()) (npub is public → not peppered).
• activate_premium(invoice_id, user_id, days) -> Option<premium_until> — consume the single-use invoice AND extend premium_until in one transaction (so a mid-flight failure rolls the consume back and the paid invoice stays redeemable). Extends from GREATEST(COALESCE(premium_until, NOW()), NOW()), so early/longer renewals stack.
• count_unconsumed_premium_invoices(user_id) — bounds pending invoices per user.

5. Admission policy change

The pure engine (infra/relay/policy.rs::decide) classifies each event and gates on kind × membership. A new WritePolicy::PremiumPost and an author_premium input:

• Wallet-functional kinds are free for registered users. Define WALLET_KINDS — the events that make the wallet + its peer features work: 1059 (NIP-59 gift-wrap / encrypted DMs, incl. tip + swap-coordination payloads), 10050 (NIP-17 DM relay list), and the tip / atomic-swap coordination kinds as those features define their on-Nostr shape. Extensible constant.
• PremiumPost decision order in the pure engine (first match wins). The max_event_bytes size cap is enforced in the nauthz adapter before the pure engine runs (fail-closed), so it is not a branch here:
  1. author_premium → Permit (any kind — the general-purpose relay).
  2. author_registered && kind ∈ WALLET_KINDS → Permit (free wallet use).
  3. author_registered (non-wallet kind, not premium) → Deny (premium required).
  4. external author → gift-wrap inbox delivery only (kind == 1059 to a registered recipient, PoW-gated), else Deny.
• Existing Open / AuthorAllowlist / InboxOutbox unchanged.

nauthz.rs::event_admit passes the event kind, is_registered_npub(author), and the new is_premium_npub(author) into decide. Fail-closed on error (deny).

Config (config.rs): RELAY_WRITE_POLICY=premium-post; validate() keeps the loopback-admission requirement (non-open policies need the admission service).

6. Payment flow (recurring + tiered, reuses the PaymentProvider seam)

• POST /premium/invoice (JWT auth), body { plan } → mint an invoice for the selected plan's amount via the PaymentProvider, recorded in premium_invoices bound to the caller's user_id with the plan's days. Returns the invoice (pay URL / address).
• POST /premium/activate (JWT auth), body { invoice_id } → the client-driven settle path (pull model, no background poller): verify the invoice is Settled at the processor, then activate_premium (single-use consume + premium_until extend, in one transaction). Never holds funds — status reads only.
• GET /premium/status (JWT auth) → { active, premium_until }.

Tiered plans (a built-in discount feature). PREMIUM_PLANS is a list of { id, days, amount }:

id	days	price	vs. quarterly
quarter	90	$5	—
halfyear	182	$9	~10% off
year	365	$15	~25% off

The invoice endpoint validates plan against the configured list; /capabilities advertises it so the client shows the tiers with the discount visible. extend_premium stacks from max(now, current_expiry), so buying early (or a longer plan) just extends. Single shared PREMIUM_CURRENCY.

Config: PREMIUM_ENABLED (default false), PREMIUM_CURRENCY, PREMIUM_PLANS (id:days:amount entries), reuses PAYMENT_PROVIDER_*. validate(): PREMIUM_ENABLED ⇒ provider configured and RELAY_ENABLED and RELAY_WRITE_POLICY=premium-post and ≥1 valid plan (fail closed otherwise).

6.5 Resource governance — a shared host

When the relay runs on the same host as the wallet backend and the LWS scanners, it must stay within a budget and never starve them. A paid base is naturally bounded (only paying users post general content); set hard limits regardless:

• Size + retention — RELAY_MAX_EVENT_BYTES (64 KB) and RELAY_RETENTION_DAYS (30) cap storage; general (non-DM) content can carry a shorter retention than gift-wraps if needed.
• Connection / subscription / rate limits — cap max connections, subscriptions per connection, and ingest rate in the nostr-rs-relay config so a burst can't monopolize CPU / DB / bandwidth.
• DB isolation — the relay uses its own tables + retention job; the wallet backend's hot auth / LWS paths are untouched.
• Escape hatch — the paid-relay recipe ships a suggested cap set: if relay load approaches the wallet backend's headroom, move the relay to its own host — the seam already supports RELAY_MODE=external.

7. Capabilities + OpenAPI

• /capabilities: features.premium_relay: bool + a premium object { currency, plans: [{ id, days, amount }], relay_url } (present only when enabled), so the client renders the plan tiers with the discount visible. The client greys the general-Nostr-posting affordance unless premium.active; wallet events + DMs stay available free.
• OpenAPI: document POST /premium/invoice, POST /premium/activate, and GET /premium/status; the existing OpenAPI no-drift check must pass. Capabilities golden test updated to include premium_relay + premium.

8. Free ↔ premium enforcement points (defense in depth)

1. Relay admission (authoritative): the gRPC hook denies non-premium general writes to the relay regardless of client behavior (wallet events stay free). This is the real gate.
2. Client UX: reads premium.active from /premium/status and disables the affordance — a courtesy, never the enforcement.

The client is never trusted; a user who bypasses the UI still hits admission-deny.

9. Migration / compatibility

• Additive column; existing users get premium_until = NULL (free). No break.
• v0.2 backend unaffected. PREMIUM_ENABLED=false (default) → zero behavior change: POST /premium/invoice and /premium/activate return 400 (VALIDATION_ERROR, "Premium is not available on this instance."), GET /premium/status returns 200 with { active: false, premium_until: null }, and /capabilities omits the premium object (features.premium_relay: false).
• The relay stays off until an operator opts in (RELAY_ENABLED=true + premium-post) — see the examples/paid-relay/ recipe.

10. Testing (Ps and Qs)

• Unit — policy.rs: PremiumPost permits a premium author (any kind), permits a registered author's wallet kinds, denies a registered author's general post, and delivers an external gift-wrap to a registered recipient (else denies).
• Unit — config fail-closed matrix (relay / policy / plans / creds / 0-conf / days cap) and the PREMIUM_PLANS parser.
• Integration — activate_premium is single-use, stacks from max(now, current), and rejects a cross-user invoice; is_premium_npub respects expiry (npub is public, not peppered); the premium routes are feature-gated off by default.
• Golden — capabilities includes premium_relay + premium when enabled, omits when off.
• No-drift — OpenAPI covers the three premium endpoints.

11. Design decisions & limitations

1. Expiry is a hard cutoff — no grace window; early-renewal stacking (activate_premium extends from max(now, current)) softens it.
2. Writes are gated, reads stay open — read-gating would need NIP-42 AUTH plus a premium check; a possible future addition.
3. Prepaid periods, not auto-charge — crypto has no card-on-file, so a member re-pays each term or posting lapses (honest + simple).
4. No refunds — prepaid access to a service; stated in the recipe README / ToS.

12. Cookbook tie-in

examples/paid-relay/ = PREMIUM_ENABLED=true + RELAY_ENABLED=true + RELAY_WRITE_POLICY=premium-post + open+PoW registration. Its README is the operator playbook: pricing, the NCMEC/DMCA content posture (Terms §6/§9.1), resource expectations, and the "reads open, writes paid" decision. See examples/README.md.