Introduce Org Structure: Move Wallet Ownership from User to Org

[ygrishajev]

Context

Console’s API is built around a flat single-tenant-per-user model. There is no shared workspace primitive — each user owns their own managed wallet, payment methods, deployment settings, alerts, and API keys. As we look at multi-seat customers (teams, agencies, anyone deploying for a client), this is a hard ceiling: two people cannot share a balance, manage the same set of deployments, or split roles.

The objection raised against introducing orgs has been async wallet interaction — multiple users contending on a single shared wallet’s sequence number. This RFC argues the right unblock isn’t to defer orgs; it’s to shift wallet ownership from user to org and let the org expose either a single wallet (like today, just owned higher up) or a small pool of HD-derived wallets when concurrency matters. The pool option is essentially free given the current key-derivation setup (more on that below).

Self-custody is out of scope here. Per the team direction, Console is moving to managed-only, so this design assumes managed wallets only.

---

Current state (what’s actually in apps/api)

User table — userSetting

apps/api/src/user/model-schemas/user/user.schema.ts

export const Users = pgTable("userSetting", {
  id: uuid("id").primaryKey()...,
  userId: varchar("userId", { length: 255 }).unique(),  // Auth0 sub
  email, emailVerified,
  stripeCustomerId,                                      // billing identity is on the user
  ...
});

export const UsersRelations = relations(Users, ({ one, many }) => ({
  userWallets: one(UserWallets, { fields: [Users.id], references: [UserWallets.userId] }),  // 1:1
  templates: many(Templates)
}));

Wallet — user_wallets (strict 1:1 with user)

apps/api/src/billing/model-schemas/user-wallet/user-wallet.schema.ts

export const UserWallets = pgTable("user_wallets", {
  id: serial("id").primaryKey(),                    // ← also used as HD addressIndex
  userId: uuid("user_id")
    .references(() => Users.id, { onDelete: "cascade" })
    .unique()                                        // ← hard 1:1 constraint
    .notNull(),
  address: varchar("address").unique(),
  deploymentAllowance, feeAllowance,
  isTrialing,
  ...
});

How wallets are created — HD derivation by serial id

apps/api/src/billing/services/wallet-initializer/wallet-initializer.service.ts

async initialize(userId: string) {
  const { id } = await this.userWalletRepository.create({ userId });
  const wallet = await this.walletManager.createWallet({ addressIndex: id });   // ← derivation index = row id
  return await this.userWalletRepository.updateById(id, { address: wallet.address }, { returning: true });
}

Every wallet’s on-chain address is derived from the master mnemonic at HD index = user_wallets.id. There is one master seed; every “new wallet” is just a new row at the next serial id. This is the property that makes a wallet pool trivial — additional wallets cost a row insert, not new key material.

Everything else that hangs off the user

All scoped by user_id:

Table	File
wallet_settings (auto-reload)	billing/model-schemas/wallet-setting/wallet-setting.schema.ts
payment_methods	billing/model-schemas/payment-method/payment-method.schema.ts
deployment_settings (auto top-up, dseq)	deployment/model-schemas/deployment-setting/deployment-setting.schema.ts — unique on (dseq, user_id)
stripe_transactions	billing/model-schemas/stripe-transaction/stripe-transaction.schema.ts
API keys, alerts, notification channels, templates	various

Authz today — CASL rules keyed on user.id

apps/api/src/auth/services/ability/ability.service.ts

REGULAR_USER: [
  { action: ["create", "read", "sign"], subject: "UserWallet",       conditions: { userId: "${user.id}" } },
  { action: "manage",                   subject: "WalletSetting",     conditions: { userId: "${user.id}" } },
  { action: "manage",                   subject: "PaymentMethod",     conditions: { userId: "${user.id}" } },
  { action: "manage",                   subject: "DeploymentSetting", conditions: { userId: "${user.id}" } },
  { action: "manage",                   subject: "ApiKey",            conditions: { userId: "${user.id}" } },
  { action: "manage",                   subject: "Alert",             conditions: { userId: "${user.id}" } },
  { action: "manage",                   subject: "NotificationChannel", conditions: { userId: "${user.id}" } },
  ...
]

This is where the org change has the most surface area: every userId: "${user.id}" becomes orgId: "${user.activeOrgId}" (or a per-action equivalent), and the role grid expands from the current flat REGULAR_USER / REGULAR_PAYING_USER to a small set of org roles.

---

Problem

1. Wallet is glued to the user. The .unique() on user_wallets.user_id makes it a strict 1:1. There is no place to put “the org’s wallet,” and no second user can sign for the same wallet, even if business needs it.
2. Billing identity is on the user. stripeCustomerId lives on userSetting. A team that wants one invoice for ten engineers has nowhere to put a shared Stripe customer.
3. Deployment ownership is per-user. deployment_settings is unique on (dseq, user_id). Two users in the same team cannot manage each other’s deployments.
4. Authz has no notion of “team”. Every CASL rule conditions on userId: "${user.id}". There is no orgId, no role beyond user/paying-user/super-user.
5. The “concurrency” objection assumes 1 wallet must serve N users. With current HD derivation that’s not actually a constraint — see proposal.

---

Proposed model

Introduce a thin org layer. Users join orgs through memberships. Wallet ownership shifts to org. Existing personal accounts become personal orgs (an org with one member, the owner) — no migration trauma.

Entity model

erDiagram
  ORG ||--o{ MEMBERSHIP : "has"
  USER ||--o{ MEMBERSHIP : "joins"
  ORG ||--|{ ORG_WALLET : "owns 1..N"
  ORG ||--o{ DEPLOYMENT_SETTING : "scopes"
  ORG ||--o{ PAYMENT_METHOD : "scopes"
  ORG_WALLET ||--o{ DEPLOYMENT_SETTING : "1..1 active per dseq"

  ORG {
    uuid id
    string name
    string slug
    string stripeCustomerId
    boolean isPersonal
    timestamp createdAt
  }
  MEMBERSHIP {
    uuid id
    uuid orgId
    uuid userId
    string role "owner|admin|deployer|viewer"
    timestamp createdAt
  }
  USER {
    uuid id
    string userId "Auth0 sub"
    string email
  }
  ORG_WALLET {
    serial id "= HD addressIndex"
    uuid orgId
    string address
    numeric deploymentAllowance
    numeric feeAllowance
    boolean isTrialing
  }
  DEPLOYMENT_SETTING {
    uuid id
    uuid orgId
    integer walletId
    string dseq
    boolean autoTopUpEnabled
  }

Loading

Concurrency: single wallet vs pool

The pool is not a separate architecture — it’s just “1 row” vs “N rows” in the same org_wallets table.

• Phase 1, single wallet per org: the user_wallets table is renamed org_wallets, user_id becomes org_id, and the .unique() on the FK stays. Current behavior is preserved 1:1; orgs are introduced; the only contention surface is two users trying to broadcast at once — same as today’s “two tabs” case, which already exists.
• Phase 2 (only if/when needed), wallet pool per org: drop the unique constraint, allow multiple rows per org_id. On deploy, atomically lease a status = free row (SELECT ... FOR UPDATE SKIP LOCKED or equivalent), bind it to the deployment, release on close. Pool grows lazily — when all rows are leased, insert a new one. Address is HD-derived from the new serial id at insert time.

This is the same code path either way. The pool is not a new system; it’s the same table without a uniqueness constraint and with a lease/release step in the deploy service.

Deploy flow (with optional pool lease)

sequenceDiagram
  participant Client
  participant API as Console API
  participant AuthZ as CASL ability
  participant Pool as org_wallets
  participant Chain

  Client->>API: POST /v1/deployments  { orgId, sdl }
  API->>AuthZ: can("create", "Deployment", { orgId })?
  AuthZ-->>API: ✓ (role ∈ owner|admin|deployer)
  API->>Pool: lease(orgId)  -- single row today, FOR UPDATE SKIP LOCKED if pooled
  Pool-->>API: wallet { id, address }
  API->>Chain: signAndBroadcastWithDerivedWallet(wallet.id, msgs)
  Chain-->>API: dseq
  API->>API: insert deployment_setting { orgId, walletId, dseq }
  API-->>Client: { deploymentId, dseq, walletId }

Loading

signAndBroadcastWithDerivedWallet(derivationIndex, ...) already exists in tx-manager.service.ts — the pool design uses the existing signer untouched.

---

What changes

Schema

• New tables: orgs, memberships (org_id, user_id, role).
• user_wallets → org_wallets; user_id → org_id. Drop .unique() only when Phase 2 lands.
• payment_methods.user_id → org_id; move stripeCustomerId from userSetting to orgs.
• deployment_settings.user_id → org_id; add wallet_id FK; unique becomes (dseq, org_id).
• wallet_settings.user_id → org_id. Same for alerts, notification channels, api keys.
• Templates stay user-owned (they’re personal, not workspace artifacts).

Authz

AbilityService rules switch the condition key from userId to orgId, and the role grid expands:

// sketch — for discussion
const ROLES = {
  owner:    [{ action: "manage", subject: "all",                 conditions: { orgId: "${activeOrg.id}" } }],
  admin:    [{ action: "manage", subject: ["OrgWallet","WalletSetting","PaymentMethod","DeploymentSetting","Alert","NotificationChannel","ApiKey","Membership"], conditions: { orgId: "${activeOrg.id}" } }],
  deployer: [{ action: ["create","read","sign"], subject: "OrgWallet",        conditions: { orgId: "${activeOrg.id}" } },
             { action: "manage",                  subject: "DeploymentSetting", conditions: { orgId: "${activeOrg.id}" } }],
  viewer:   [{ action: "read",   subject: ["OrgWallet","DeploymentSetting","Alert"], conditions: { orgId: "${activeOrg.id}" } }]
};

The auth interceptor needs to resolve the active org for the request (header, JWT claim, or path param) and pass activeOrg into getAbilityFor. API keys get scoped to an org at creation time.

Wallet/billing services

• WalletInitializerService.initialize(orgId) instead of initialize(userId). The HD index is still the row’s serial id — no key-management change.
• ManagedSignerService / tx-manager are unchanged. They already take derivationIndex.
• Stripe customer is created on org creation. Trial limits granted per org, not per user.

Migration (managed users only — self-custody is out of scope)

For each existing userSetting row:

1. Create a personal org (isPersonal = true, name = email, slug = userId).
2. Create a membership with role = owner.
3. Reattach user_wallets → org_wallets by org_id; same row, same serial id, same address — no on-chain change, no re-derivation.
4. Reattach payment_methods, deployment_settings, wallet_settings, etc. by org_id.
5. Move stripeCustomerId from userSetting to the personal org.

Existing users see no behavioral change. The org is invisible until they invite someone.

---

Why this is the right shape

• No on-chain migration. Addresses are derived from org_wallets.id (= old user_wallets.id). Existing addresses keep their funds and their escrow accounts.
• No new key infra. The HD-by-serial-id pattern already in wallet-initializer is exactly what a pool needs.
• Single wallet today, pool tomorrow — same table. The pool is a flag-flip + a FOR UPDATE SKIP LOCKED lease, not a separate system.
• Authz is one consistent change. Every CASL rule moves from userId → orgId. Touching one file (ability.service.ts) plus the auth interceptor plus repository accessibleBy calls.
• Backward-compatible. Personal orgs preserve current single-user UX. The org primitive just unlocks multi-seat when needed.

---

Open questions for the sync

1. Active-org resolution. Header (x-org-id) vs JWT claim vs path-prefixed routes (/v1/orgs/:slug/...)? My preference: JWT claim refreshed on org switch; falls back to personal org if absent.
2. API key scoping. One key = one org? Or scoped to user with an orgId parameter per request? My preference: keys are bound to an org at creation.
3. Pool: now or later? I’d land Phase 1 (single wallet, just owned by org) first. Pool is a follow-up that doesn’t need to ship in the same PR.
4. Roles grid. Are owner / admin / deployer / viewer the right four, or do we want to start with three (owner / member / viewer) and split later?
5. Trial limits. Per org, or per user-who-created-the-org? I lean per-org so a user can’t farm trials across new orgs, but that punishes legit second-org creation.