RFC: Master Accounts and Subaccounts

Date: 2026-07-14

Status: Draft

Related: Lazy Account Provisioning — this RFC is a large part of the "step 11" account-lifecycle surface that RFC explicitly deferred (self-serve creation of a second, non-default account); System User and System Trading Accounts — the permission-grant guard on system accounts interacts with the new grant paths; Margin Groups — margin stays per-account here, but a subaccount family is an obvious future margin-group candidate.

The account model today is flat. trading_accounts (db/postgres/1.sql:551-585) has no parent pointer, no grouping table, and no hierarchy of any kind. Each account is optionally owned by one UBO — ubo_user_id, "the user that 'owns' this account for KYC/tax/compliance purposes" (db/postgres/1.sql:577-582) — and operational access is a separate M:N grant table:

with a hierarchy encoded in AccountPermissions::allows (rs/sdk-internal/db/src/entities.rs:3410-3437): Trade ⇒ ReduceOrClose ⇒ Read ⇒ List, SetLimits ⇒ List. All permission grants are admin-only today — PUT /admin/accounts/{id}/permissions/{user_id} (rs/api-gateway/src/admin_trading_account_routes.rs:352) and the admin-cli (rs/admin-cli/src/accounts.rs). There is no customer-facing surface for creating an account or granting anyone access to one.

Money movement is equally flat: there is no account-to-account transfer anywhere in the system. Every money event is a single-account NewTransaction (rs/transaction-engine/src/lib.rs:106-118) whose double-entry counterparty is always an AX system ledger — deposits and withdrawals book against AX_DEPOSITOR_ACCOUNT_ID, funding against AX_FUNDING_ACCOUNT_ID (rs/risk-engine2/src/tigerbeetle_driver.rs:286-331). The customer GUI's "Transfer Funds" panel (gui/packages/app/screens/portfolio/components/Transfer/index.tsx) offers exactly two actions: Deposit and Withdraw.

Institutional customers want the standard exchange subaccount workflow: one legal entity (one UBO, one KYC) running several segregated books — per desk, per strategy, per client — with a designated operator who can:

1. spin up new subaccounts without an admin ticket,
2. delegate trading access on those subaccounts to their own people, and
3. rebalance capital between the master account and its subaccounts,

all without any subaccount going through onboarding, because the beneficial owner — and therefore the compliance standing — is the same. The compliance half of this already works by construction: the order-gateway checks is_onboarded/is_frozen on the account's UBO, not the acting user (rs/order-gateway/src/state.rs:239-274), so an account minted with the same ubo_user_id inherits the owner's KYC status and freeze state automatically. What's missing is the hierarchy, the delegated authority, and the money movement.

1. A master account can sprout subaccounts. A subaccount is an ordinary trading_accounts row — same UBO as its master, its own venue identity, its own balances, margin, limits, and permissions — plus a parent pointer. No new KYC; freezing the UBO freezes the whole family.
2. can_master — delegated family administration. A per-(user, master) grant that lets its holder create subaccounts under that master and manage (grant/revoke/edit) the base permissions on those subaccounts, from a customer-facing UI — no admin involvement per subaccount or per trader.
3. can_subtransfer — delegated treasury, one-sided. A per-(user, master) grant that lets its holder move balance freely between the master and any of its subaccounts — in both directions — without holding any permission row on the subaccounts themselves. Master↔︎sub only; never sub↔︎sub directly.
4. A transfers GUI. Users holding can_subtransfer on a master see a family view — master and subaccount balances — and a transfer form, plus the family's transfer history.
5. Transfers are first-class ledger events. A transfer is one atomic two-leg transaction (debit one account, credit the other), visible in ClickHouse history for both accounts, booked in TigerBeetle, and subject to the same withdrawability constraints as an external withdrawal on the debited leg.

• Cross-margin across the family. Each account continues to margin independently; a subaccount family is deliberately N isolated risk silos (that isolation is much of the point). If a family ever wants shared margin, that is the Margin Groups design's job, and the family tree gives it a natural seed.
• Sub↔︎sub direct transfers. Excluded by design (see §6). Two hops (sub→master, master→sub) compose to the same effect; the invariant we keep is that every transfer leg pairs with the master, which keeps authorization one-sided and the audit trail radial.
• Nested hierarchies. One level only: a master cannot itself be a subaccount, and a subaccount cannot be a master. Schema-enforced.
• A first-class customer-entity table. ubo_user_id remains the owner key; this RFC leans on it but does not replace it. (It arguably delays the need for one: "one entity, many accounts" is the main thing an entity table would buy.)
• Multi-currency transfers. Balances are a single usd_balance (current_balances, db/postgres/1.sql:148-156); transfers move USD.
• An invite flow. Permission grants target existing users by username; inviting someone who has no AX login is out of scope (they sign up first, identity-only, per lazy provisioning).

Why an explicit parent pointer and not "same UBO". The ask phrases a subaccount as "just an additional account with the same UBO," and that is the compliance semantics — but it cannot be the structural definition. A UBO may legitimately own accounts that are not part of the family (a pre-existing standalone account, or two independent masters), and can_master/can_subtransfer need a precise scope: "the subaccounts of this master," not "everything this UBO owns." So the parent pointer defines the family, and same-UBO becomes an invariant of the pointer: sub.ubo_user_id = master.ubo_user_id, enforced at every write path and by a recon check (cross-row, so a CHECK can't reach it — same treatment as the system-account grant guard in system-accounts).

Write-path invariants (endpoint-enforced + recon-checked):

• master_account_id may only reference a row with is_master = TRUE;
• sub.ubo_user_id = master.ubo_user_id, and both non-NULL (a system account can never be a master or a sub — its UBO is the system user, which never gets is_master);
• can_master/can_subtransfer may only be granted on accounts with is_master = TRUE;
• flipping is_master off requires the account to have no subaccounts and no can_master/can_subtransfer grants.

trading_accounts and account_permissions are both already on every relevant logical-replication publication (db/postgres/1.sql:1112-1115), so the new columns flow to api-gateway, order-gateway, and trade-engine replicas with no publication changes; existing consumers ignore columns they don't read.

Two new Action variants join the enum at rs/sdk-internal/db/src/entities.rs:3431-3437:

with allows: Master => can_master, Subtransfer => can_subtransfer (neither implies nor is implied by Trade — treasury and administration are deliberately orthogonal to trading authority).

The genuinely new mechanism is derived authority on subaccounts. Both new grants live on the master row only ("one-sided"), but their holders need visibility into the subaccounts — the manager to render the permissions UI, the treasurer to see the balances they're rebalancing. Rather than fanning out shadow account_permissions rows onto every subaccount (which would need lifecycle management on every subaccount create/revoke, and would blur which rows are direct grants), authorization becomes family-aware: the effective permission of (user, account) is the direct row, unioned — when the account has a master_account_id — with a derivation from the user's row on the master:

Nothing stronger is ever derived: neither grant confers Trade, ReduceOrClose, or SetLimits on a subaccount. A can_master holder who wants to trade a subaccount grants themself can_trade on it — an explicit, audited row — exactly as they would for anyone else.

Concretely: authorize (entities.rs:3454-3464) gains a family-aware variant that takes the accounts replica alongside the permissions replica (api-gateway already holds both, rs/api-gateway/src/utils.rs:185-210); given (user, S, action) where S.master_account_id = M, it checks the direct row and falls back to the derivation from (user, M). The authorize_with_api_key intersection (entities.rs:3488-3503) composes unchanged on top.

Creation reuses the machinery admin create_account (rs/api-gateway/src/admin_trading_account_routes.rs:57-168) already has — mint an id from state.account_id_generator, provision the EP3 participant/account (provision_ep3_trading_account is idempotent and account-keyed), insert the row — with the family shape forced rather than requested:

• ubo_user_id := master.ubo_user_id, master_account_id := master.id, is_master := FALSE;
• maker_fee/taker_fee copied from the master (the family is one customer; admins can diverge a subaccount's fees afterwards);
• zero current_balances row seeded (ON CONFLICT DO NOTHING, per the lazy-provisioning idempotency work);
• an account_permissions.full_access row for the creator (they created it to use it or hand it out; they can trim their own row afterwards). No implicit row for the UBO — the UBO's operational access is a deliberate grant, as everywhere else post-multi-account.

This is materialize_account (lazy-provisioning §2) generalized from "the derived default id" to "a minted id with a parent" — one primitive, two callers.

Edition note. Self-serve creation requires the edition to be able to mint venue identity on demand. The EP3 edition can (two idempotent gRPC RPCs); the Bitnomial/aiex edition cannot — accounts must be pre-provisioned and paired with btnl_* identity by an admin (create_account's edition rules already encode this). On aiex, POST .../subaccounts is disabled and subaccount creation stays an admin action; the rest of this design (flags, transfers, GUI) works identically there once the rows exist.

Deletion stays admin-only (admin-cli accounts delete); customers get close-only at most. A closed-and-flat subaccount is cheap to keep.

Same request/response shapes as the admin endpoints (SetAccountPermissionsRequest, rs/sdk-internal/src/protocol.rs:1589-1594) so the sdk-internal types and the admin GUI's permission editor carry over. Guard rails, all endpoint-enforced:

• Scope: subaccounts only. The target account must have master_account_id pointing at a master on which the caller holds can_master. The master account's own permission rows are not editable from this surface — grants on the master (including can_master and can_subtransfer themselves) remain admin-only. This caps the blast radius: a rogue or compromised manager can reshuffle sub access but cannot mint more managers, cannot grant treasury power, and cannot lock anyone out of the master.
• Only the five base flags. The request type for this surface simply does not carry can_master/can_subtransfer — unrepresentable, nothing to validate (they'd also be meaningless on a sub, and the write-path invariant in §1 rejects them there from any path).
• Grantees must share... nothing. Any existing user may be granted access to a subaccount, same as the admin surface — the delegate-trader who should trade desk-A's book is precisely someone who is not the UBO. Compliance stays keyed on the UBO regardless of who trades.

A transfer is one event, two legs: -amount on the source account, +amount on the destination, sharing an event_id. The plumbing wants this shape already — insert_transactions takes a Vec<NewTransaction> and applies it in one advisory-lock-serialized Postgres transaction (rs/transaction-engine/src/lib.rs:199-220), and NewTransaction targets an arbitrary account_id. What's new:

• TransactionKind::Transfer ("transfer", allows USD). Two rows land in ClickHouse transactions (one per leg, signed amounts, shared event_id); reference_id carries the counterparty account id so each account's history is self-describing without a join.
• Debit-leg constraints = withdrawal constraints. The debited account must pass the same checks an external withdrawal does: OverWithdrawal on balance, the loan covenant (ensure_withdrawal_within_loan_covenant, rs/api-gateway/src/utils.rs:1281), and — critically — the account must remain adequately margined after the debit if it has open positions. Moving equity out of a sub with open risk is economically a withdrawal; whatever free-collateral predicate withdrawals settle on (see open questions — today's check is balance-based, not margin-based) applies identically here. The credit leg needs no check.
• Risk-engine booking. RecordTransaction events (rs/risk-engine2/src/events.rs:17-33) fire for both legs. In TigerBeetle the pair books as one direct customer↔︎customer transfer — TB's primitive is a credit/debit pair, and unlike deposits/withdrawals there is no system-account counterparty: the family's money never leaves the exchange, and exchange-wide net transfer delta is zero. In-memory (rs/risk-engine2/src/state.rs:155-175), each leg adjusts its account's net_transfers_usd with no system-account mirror entry.
• Atomicity across stores. Postgres (both current_balances updates + both CH-bound rows) commits atomically under the existing advisory lock; the CH append and TB booking follow the same eventual path every deposit/withdrawal takes today. No new consistency machinery.

Authorization is entirely master-side: the caller must hold Action::Subtransfer on {master_id}, and {from_account, to_account} must be {master_id, S} in either order where S.master_account_id = master_id. No permission row on S is consulted — that is the "one-sided" semantics. Consequences worth stating:

• A treasurer can drain a subaccount they cannot trade. Intended: treasury and trading are different jobs, and the money only ever moves to/from the master — it cannot leave the family through this endpoint. (Getting money out still requires a real withdrawal, with its own Action::Trade check on whichever account it exits from.)
• Sub↔︎sub is rejected even though two hops achieve it. The invariant bought: every transfer leg has the master as counterparty, so the master's own history is the family's complete rebalancing record, and authorization never needs to reason about sub-to-sub pairs.
• Admin variant (POST /admin/subtransfer, god-mode, any family) for support operations, mirroring the admin deposit/withdraw pair (rs/api-gateway/src/admin_routes.rs:1543,1613).

API keys. api_keys mirrors the permission flags and intersects with live grants (db/postgres/1.sql:25-48, api_key_permissions_allow, entities.rs:3473-3481). Add can_subtransfer to the key flags — automated rebalancing between strategy subaccounts is a first-order programmatic use case. can_master stays session-only in v1; nobody should be minting subaccounts from a bot before the workflow has soaked.

Customer app (gui/packages/app): a Subaccounts section, visible when WhoAmI/MyAccountEntry (rs/sdk-internal/src/protocol.rs:1638-1651, extended with is_master, master_account_id, and the two new flags) shows the user holding either new grant on some master:

• Family view (either grant): master + subaccounts, name and balance per row, sourced from the family-derived Read.
• Transfer panel (can_subtransfer): from/to selectors constrained to valid master↔︎sub pairs (picking a sub in "from" locks "to" to the master, and vice versa), amount, and the family transfer history below. Lives alongside the existing Deposit/Withdraw "Transfer Funds" component rather than inside it — external funding and internal rebalancing are different operations with different permission gates.
• Manage panel (can_master): per-subaccount list of (user, flags) rows with an editor for the five base flags, grant-by-username, revoke; and a "New subaccount" action. Effectively the admin GUI's permission tab scoped to one family — reuse its patterns (gui/apps/admin/src/pages/users/).

Admin GUI: is_master badge and a family tree on the account page; subaccounts grouped under their master in listings; the two new flags in the admin permission editor, with the master-only guard surfaced as a disabled state rather than a 4xx surprise.

• Order-gateway compliance checks — already UBO-keyed (rs/order-gateway/src/state.rs:239-274); subaccounts inherit standing and freeze with zero code change. This is the load-bearing reason "same UBO" is the right ownership shape.
• External funding — deposits/withdrawals per account, unchanged, including per-subaccount blockchain_deposit_addresses.
• Margin, loss limits, LTV monitors — per account, unchanged.
• The system-accounts grant guard — system accounts reject all grants; they can never be masters or subs (§1 invariants).

1. Schema + types — columns, CHECKs, replica plumbing. Inert: nothing reads the new columns yet. Atlas-applied.
2. Transfer primitive — TransactionKind::Transfer end to end (engine → CH → RE/TB), admin-only endpoint first. Soak on demo with recon's zero-sum check watching. Lifecycle tests per CLAUDE.md: transfer racing a withdrawal on the debited account, api-gateway crash between commit and downstream consumption, restart/replay, and the concurrent double-submit (advisory lock + event_id idempotency).
3. Family + delegation — customer endpoints (§3, §4, §6), family-aware authorize, admin GUI surfaces. Grant can_master/can_subtransfer to a pilot customer by hand.
4. Customer GUI — family view, transfer panel, manage panel.
5. No backfill. Existing accounts stay flat (is_master = FALSE, no parent). Admins flip is_master and/or adopt existing accounts under a master (set master_account_id, subject to the §1 invariants) per customer request.

• Withdrawability predicate for the debit leg. Today's withdrawal check is balance-based (OverWithdrawal) plus the loan covenant — is that actually margin-safe for an account with open positions, and if not, do we fix withdrawals and transfers together on a free-collateral predicate from the risk engine? (Transfers should not launch with a weaker check than withdrawals, nor vice versa.)
• Adoption of existing accounts. Admin-set master_account_id on a pre-existing standalone account (same UBO) seems clearly wanted — any reason to disallow? What about detaching a sub (clearing the pointer): require flat balance first?
• Should can_master derive SetLimits on subs? The manager sets up the desk — do they also set its loss limits, or is that a separate explicit grant per sub? Leaning explicit (limits are risk controls; keep the derived set minimal).
• View scope of the derived Read. can_read conventionally includes balances, positions, orders, and history. Does the treasurer (can_subtransfer) need positions/orders, or only balances? Deriving full Read is simpler and probably fine — the master-side grant is already a high-trust role — but confirm with the pilot customer.
• Limits. Max subaccounts per master (EP3 participant namespace is finite — the same pressure that motivated lazy provisioning)? Rate-limit on creation? A soft cap (e.g. 32) with an admin override seems cheap insurance.
• initiated_by_user_id display. Transfer legs stamp the acting treasurer. The sub's delegate-trader sees an outflow initiated by a user who holds no grant on their account — make sure history rendering ("internal transfer to/from master") reads sensibly rather than alarmingly.
• aiex edition. Confirm the Bitnomial pre-provisioned account set can carry the family columns without upsetting accounts_monitor consumers, and decide whether admin-created btnl subaccounts are in v1 scope there.