RFC: Lazy Account Provisioning

Date: 2026-06-23

Status: Draft

Related: Multi-Accounts (A-3402, step 11) — migration complete; the plan and service-audit docs have been retired (see A-3402 / git history).

Today, POST /signup provisions a complete trading account eagerly and atomically, before the user has been KYC'd and before they have shown any intent to trade. The provision_user function (rs/api-gateway/src/auth.rs:267-383) performs, in one Postgres transaction plus a side ClickHouse/EP3 effect, the following ordered sequence:

1. (EP3 enabled) Mint a default account_id from the generator, then call provision_ep3_trading_account (rs/ep3/src/ep3_user_manager.rs:176-184), which fires two real EP3 gRPC RPCs — CreateAccount and CreateParticipant (ep3_user_manager.rs:115-167). The user_id is then read back out of the minted EP3 username via Ep3Username::from_full_path(...).user_id_v2() (auth.rs:301-304).
2. INSERT INTO users (auth.rs:345).
3. Seed a zero current_balances row in Postgres via initialize_balances → pg_insert_balance (auth.rs:353-359, rs/transaction-engine/src/lib.rs:56).
4. INSERT INTO user_risk_profiles (auth.rs:360).
5. INSERT INTO trading_accounts with ubo_user_id = user_id (auth.rs:363-375).
6. INSERT INTO account_permissions — the UBO's full_access grant (auth.rs:376-378).

The cost of this eagerness is borne by EP3. Every signup mints an EP3 participant, whether or not the user ever funds, trades, or even passes KYC. If we open signups to non-traders who just want to view market data or window-shop the product, we will flood EP3 with permanently-inactive participants — a finite, externally-managed namespace — and carry the operational and reconciliation weight of accounts that will never see a fill.

The Multi-Accounts work (A-3402) has done the heavy lifting that makes this tractable. It cleanly separated identity (user_id) from ownership (account_id) and membership (account_permissions) (Multi-Accounts A-3402 §2a), inverted the gateway guard to a real authorize(user, account, action) ACL (step 6), and made the EP3 seam account-keyed rather than user-keyed (step 10e). The one piece the plan explicitly deferred is account lifecycle — "who creates accounts beyond onboarding, and is there a public-SDK creation message?" is an open question, slated for step 11 (CreateAccount/ListAccounts/...). This RFC is the design for that lifecycle: stop creating the account at signup, and materialize it lazily at a well-defined trigger.

The eager flow exists for one reason: under the old 1:1 user == account world, "a user" and "their account" were the same object, so there was no seam at which to split them. After A-3402 that seam exists everywhere — every money path already keys on account_id and authorizes against account_permissions. A user with no trading_accounts row and no account_permissions rows is now a perfectly coherent state: it is simply a user whose readable-account set is empty. Most read surfaces already degrade correctly to that state (see § Graceful degradation). What is left is to (a) make signup create only identity, (b) introduce an idempotent materialization step, and (c) fix the handful of read paths that still assume the default account row exists.

• Signup creates identity only. A freshly-signed-up user has a users row (and onboarding/KYC scaffolding) but no trading_accounts row, no account_permissions rows, no current_balances row, and — critically — no EP3 participant.
• Window-shopping works without an account. A user with no account can log in, call WhoAmI, browse instruments, and stream market data. None of these surfaces 500 or 403 on a missing default account.
• EP3 participants are minted only for accounts that will actually trade. The CreateAccount/CreateParticipant RPCs move to the materialization trigger, gated behind KYC.
• Materialization is idempotent and concurrency-safe. The trigger can fire more than once (deposit + onboarding callback racing) and the derived default account_id is stable, so re-running converges to one account.
• No backfill, no migration of existing users. Already-provisioned users keep every row they have; only new signups take the lazy path. The change is feature-flagged so we can roll forward and back per environment.

• Self-serve / multi-account creation (a user creating a second, non-default account). That is the broader step-11 public-SDK surface (CreateAccount message). This RFC only changes when the default account is materialized; it reuses the same materialization primitive step 11 will expose, but does not design the multi-account UX.
• Changing the default-account derivation. account_id = user_id.as_default_account_id() (id shares the user's ULID bit pattern) stays exactly as it is (Multi-Accounts A-3402 §2c.1). Lazy provisioning defers creating the row; it does not change what id the row gets. This is what makes materialization a safe upsert on a stable key.
• On-chain deposit detection. The off-chain watcher that maps an incoming blockchain deposit to an account_id is out of repo and unchanged; this RFC only addresses what AX-side state must exist when a deposit is credited.
• Joint / cross-account margin. Unchanged; each account margins independently (Multi-Accounts A-3402 §3.1).

Split the seven-step eager sequence above into two phases along the identity/ownership line the plan already drew:

The single structural blocker to deferring EP3 is that the user_id is currently produced by EP3 provisioning (auth.rs:289-304): we mint an account_id, hand it to EP3, and parse the user_id back out of the returned participant string. If EP3 provisioning moves to a later trigger, signup has no user_id.

The fix is clean and is in fact a simplification: mint the user_id from the generator directly at signup (exactly what the EP3-disabled branch already does, auth.rs:306). The EP3 username was never genuinely supplied by EP3 — it is a pure deterministic function of the account id (generate_ep3_username(account_id), ep3_user_manager.rs:62-65), and account_id = user_id.as_default_account_id() is itself derived. So at signup we can compute the eventual ep3_username/ep3_account strings without talking to EP3 at all; the RPCs that actually register those strings on the venue are what we defer. (Whether we persist the computed strings on the users row at signup or compute them at materialization is a minor implementation choice; computing at materialization keeps the users row honest about what exists on EP3.)

Introduce one idempotent function — call it materialize_account(state, user_id) -> Result<AccountId> — that performs the ownership-phase writes and only those writes:

Idempotency is the crux, because the trigger is not exactly-once:

• EP3 is already idempotent — provision_ep3_trading_account early-returns via find_ep3_user_by_account_id (ep3_user_manager.rs:89-93,180-182). The first race-loser that finds the participant already present is a no-op.
• Postgres writes become ON CONFLICT DO NOTHING on their primary keys (trading_accounts.id, account_permissions (user_id, account_id), current_balances.account_id). Because the default account_id is derived, not generated, two concurrent materializations target the same key and collapse cleanly.
• Concurrency between two simultaneous triggers (e.g. a deposit and an onboarding-complete callback) is contained by a Postgres advisory lock keyed on the account id for the duration of the transaction, so we never half-create.

materialize_account is the same primitive step 11's public CreateAccount message will call; this RFC just wires it to the default account's lifecycle first.

The user framed two options: at first deposit (latest) or at the earliest, once onboarding/KYC is complete. These are not really competing — KYC is a precondition for funding, so they compose into a single pipeline:

Recommendation: trigger on the first funding action, with KYC as a hard precondition. Rationale:

• It maximally protects EP3: a participant is minted only when a real, KYC'd user takes a concrete step to put money in. A user who KYCs but never funds (a real population) still costs EP3 zero.
• "First deposit" in practice means "the user requests a deposit address or initiates a deposit," which is the earliest unambiguous funding signal and is itself the natural materialization point: deposit addresses are FK'd to trading_accounts (db/postgres/1.sql:314-324), so we cannot hand out a deposit address without an account row anyway. Materializing on deposit-address request is therefore forced by the schema and is clean.
• KYC-complete-as-trigger (materialize the instant is_onboarded flips) is the weaker choice on its own: it re-introduces the very EP3 clutter we are trying to avoid for the cohort that KYCs out of curiosity but never funds. We keep KYC as the gate (you cannot fund un-KYC'd) but not the trigger.

The deposit edge is special and must materialize-then-authorize, not the usual authorize-then-act. A bare deposit into one's own default account currently 403s under the post-A-3402 ACL because there is no account_permissions row yet (authorize returns Forbidden on a missing row, rs/sdk-internal/db/src/entities.rs:2779-2789). For the UBO depositing into their own default account the authorization is implicit (they are the beneficial owner by derivation: account_id.as_default → user_id). So the deposit-bootstrap path resolves the default account, calls materialize_account(user_id) if absent, then proceeds through the normal deposit machinery (process_deposit_or_withdrawal, rs/api-gateway/src/utils.rs:908-976), which already auto-creates the balance row on first transaction (rs/transaction-engine/src/lib.rs:325-340). Deposits into a non-default account a user does not own remain governed by the normal ACL.

The KYC gate (is_onboarded) is the precondition for the funding trigger, and making it fire automatically on KYC approval is in scope for this RFC — see the next section.

Today there is no automatic transition from "onboarding application complete" to is_onboarded = true. An admin flips the flag by hand via PUT /admin/user/status on api-gateway (rs/api-gateway/src/admin_routes.rs:337-411 → DbUser::update_status, rs/sdk-internal/db/src/entities.rs:161-198), and the onboarding-gateway's application_completed write (admin_update_application, rs/onboarding-gateway/src/admin_onboarding_routes.rs:1035-1087 → DbOnboardingApplication::update, entities.rs:1365-1399) notifies nothing downstream. The two services share one Postgres but onboarding-gateway never writes the users table — api-gateway owns those writes and maintains the users_replica (rs/api-gateway/src/state.rs:32). We must respect that ownership boundary: onboarding-gateway should not reach across and UPDATE users directly, or the api-gateway replica and any write-side invariants are bypassed.

Design: a service-authed internal callback. The plumbing already exists — ServiceAuthToken (bearer, constant-time compare, rs/sdk-internal/web/src/service_auth.rs:8-43) is loaded by both services but not yet used between them. Wire it up:

1. Add an internal, service-authed endpoint on api-gateway — POST /internal/onboarding/complete { user_id } (or fold the same guard onto the existing update_user_status path with a service-token auth layer). It sets is_onboarded = true through the normal DbUser::update_status write, so the replica and all existing invariants stay intact. It is idempotent (setting an already-true flag is a no-op) and does not materialize the account — materialization stays bound to the funding trigger (§3).
2. onboarding-gateway calls it when an application crosses into the "approved" terminal state. "Approved" is not a single boolean today: it is the conjunction of questionnaire_completed, documents_completed, application_completed/status='complete' (db/postgres/1.sql:166-168) and the separate risk_assessments.status = 'complete' (db/postgres/1.sql:231-236, entities.rs:1777-1808), which are updated independently and not synchronized today. Part of this work is to define the single predicate is_kyc_approved(application, risk_assessment) and fire the callback exactly when it first becomes true (in admin_update_application and in the risk-assessment update path, since either can be the last to flip).

Delivery reliability. A bare in-handler HTTP call drops the signal if api-gateway is briefly down at the moment of approval, leaving a KYC-approved user stuck un-onboarded. Two acceptable shapes, in increasing robustness:

• Synchronous call with a reconciliation backstop (recommended first cut): onboarding-gateway calls the endpoint inline; separately, a periodic reconciler (a recon-engine check, or a small task) finds applications that are is_kyc_approved but whose users.is_onboarded is still false and re-fires. This is cheap, and the backstop also retro-onboards the existing manually-managed population on first run.
• Transactional outbox: onboarding-gateway writes an outbox row in the same tx as the approval and a worker drains it to the api-gateway endpoint with retries. More moving parts; defer unless the reconciler proves insufficient.

Because the flag is idempotent and the funding trigger is what actually mints the EP3 participant, at-least-once delivery is entirely safe here — a double-fired callback is a no-op.

Interaction with the Clerk migration. If user authentication moves to Clerk (see the companion Clerk authN migration RFC), is_onboarded remains an AX-owned authZ/state attribute on the AX users row, not a Clerk concern — Clerk owns credentials and MFA, AX owns "is this user cleared to trade." This callback is unaffected by that migration.

A user with no account must traverse every non-trading surface without error. The audit of read paths found that most already degrade correctly because A-3402 made them key on the (possibly empty) readable-account set rather than assuming the default account:

The only hard breakage is the risk-snapshot endpoint. The fix is to make get_risk_snapshot_from_redis return a synthetic zero/empty snapshot (or a clean 404 Not Provisioned) when the account has no Redis key, rather than mapping the absent key to INTERNAL_SERVER_ERROR. A zero snapshot is the correct answer for an account with no balances and no positions, and it keeps the GUI's risk panel rendering "$0 / no positions" for an unfunded account instead of erroring. We should sweep for any sibling reads that .ok_or(... 500) on a default-account Redis/CH key with the same pattern.

• users and user_risk_profiles — identity/compliance, created at signup.
• The onboarding application (onboarding_applications and its questionnaire/document/risk-assessment children) — these are per user and exist precisely to drive KYC, which happens before materialization. They are identity-grained and correct to create eagerly (Multi-Accounts service audit: onboarding-gateway, A-3402).

1. Land materialize_account as a no-op-equivalent refactor: have eager provision_user call it, so the new primitive is exercised on the existing path with zero behavior change. Verify idempotency with a test that calls it twice.
2. Fix the risk-snapshot degradation (and any sibling 500s) independently — it is correct on its own merits and unblocks window-shopping.
3. Feature-flag the signup split (lazy_account_provisioning, per environment). Off = today's eager flow; on = identity-only signup + deposit/KYC trigger. Roll out sandbox → demo → prod.
4. No backfill. Existing users are fully provisioned and untouched. Only signups after the flag flips take the lazy path.
5. Lifecycle tests per CLAUDE.md's connection/lifecycle directive: signup → window-shop (marketdata + WhoAmI + balances + risk-snapshot all 200/empty) → KYC → first deposit → materialize → trade; plus the race (concurrent deposit and a second deposit, or deposit + admin provisioning) converging to a single account; plus restart/replay (materialize, crash mid-trigger, re-fire).

• Deposit-address request vs. funds-landing as the precise trigger. Schema forces materialization at deposit-address request (FK to trading_accounts). Is requesting an address the intended "first funding action," or do we want an even earlier explicit "activate account" button? Leaning: address request is the natural, schema-forced point.
• SignupResponse.account_id. Keep returning the derived (not-yet-real) account id, or omit it until materialization? Returning it preserves the current response shape but advertises an id with no row behind it.
• is_kyc_approved predicate. KYC approval is today an unsynchronized conjunction of three onboarding-application flags plus a separate risk_assessments.status. The exact predicate (and which writes can be the last to flip it, hence must fire the callback) needs to be pinned down with compliance — §4 assumes "all four complete" but that should be confirmed.
• Callback delivery shape. Synchronous-call-plus-reconciler (recommended) vs. transactional outbox — decide based on how tolerant we are of a brief onboarding-approval-to-tradeable lag.
• recon-engine / invariant checks. Confirm the continuous-recon suite treats "user with no account" as valid (it keys on rows that exist, so orphans are unlikely) and does not flag unfunded identities as missing-balance violations.
• GUI. The account selector (plan §3.7) should render a clear "no trading account yet — complete KYC and fund to start trading" empty state rather than an error, for the window-shopper cohort.