BGC X IBLOOMING WEB3 LOGIN IMPLEMENTATION

Revision D — October 13, 2025 First Version: Web3 Login Implementation Draft Status: Draft for sign-off (clean, single-source) Owners: Prof. NOTA (Product/Architecture), Yuku (Tech Owner), BGC × iBLOOMING Eng/DevOps

Table of Contents

1. Purpose & Scope

2. Key Decisions

We operate on a single, unified credentials database (already in production) for BGC and iBLOOMING. Users can sign up and log in to any app (BGC Web, iBLOOMING Web, iBLOOMING Mobile) with the same username/password and, during rollout, may also authenticate with a Passkey (WebAuthn) as a first-class method.

After login, users complete Wallet Setup by either:

• Create EOA (Embedded/In-App) → auto-provision a Smart Account (AA); or

• Connect existing wallet (SIWE) → auto-provision a Smart Account (AA).

This standardizes on-chain identity to one EOA and one Smart Account (AA) per user per chain, enabling consistent features (rewards, receipts, payments) across the BGC/iB ecosystem with minimal friction and predictable costs.

Bridging Web2 ↔ Web3. If a user does not yet have a BGC/iB account, they must first sign up for a BGC/iB account and then log in (via username/password or Passkey). Only after a successful login is Wallet Setup available: either Create an embedded EOA → auto-provision AA or Connect an existing Web3 wallet → auto-provision AA. Web3-native users who already have a BGC/iB account simply log in and proceed to Wallet Setup.

Analytics & simulations. The unified mapping user_id ⇄ identity_id ⇄ (EOA, AA) enables reliable, on-chain-addressed telemetry for behavioral simulations (Alpha Coin → future iBC/iBTC).

Partner signal. A single, passkey-enabled login and post-login Smart Account bootstrap operating across apps demonstrates concrete momentum while tokenomics is finalized.

In scope: identity model, wallet binding, AA provisioning, SIWE, Passkey support, security, DevOps, and Thirdweb implementation. Out of scope: tokenomics/ledger rules, analytics dashboards, and non-auth product features.

• Single credentials auth for the BGC/iB ecosystem.

• Passkey (WebAuthn) as a first-class login method (rolling out), with username/password fallback.

• Post-login Wallet Setup (Create or Connect), not pre-login.

Constraints

• Unified DB & identity

  • Single credentials store across BGC/iB; no per-app user tables.

  • One on-chain identity per user per chain: exactly 1 EOA + 1 AA.

Non-Goals

• No separate user tables per app within the BGC/iB ecosystem.

• No server-side plaintext key handling for wallets (embedded/MPC only).

5.1 New User (no BGC/iB account yet)

1. Sign up a BGC/iB account (username/password; offer Passkey registration during or after signup).

2. Log in using credentials or Passkey (MFA optional per policy).

3. Wallet Setup (post-login): choose Create or Connect.

5.2 Existing User (no wallet yet)

1. Log in (credentials or Passkey).

2. Wallet Setup (Create or Connect).

3. AA provisioned → Done.

5.3 Existing User (wallet already bound)

1. Log in (credentials or Passkey).

2. Skip Wallet Setup; identity already has EOA/AA.

3. Proceed to app.

users

• user_id (PK), email (unique, nullable), phone (unique, nullable), username (unique), password_hash, mfa_enabled, timestamps.

webauthn_credentials

• credential_id (PK, b64url), user_id (FK→users), public_key, sign_count, transports, backup_eligible, backed_up, timestamps.

identities

• identity_id (PK), user_id (FK→users), timestamps. (Keeps future merge/link options without breaking unification.)

wallets

• wallet_id (PK), identity_id (FK), type (EOA|AA), address, chain_id, salt, timestamps.

auth_providers

• provider_id (PK), user_id (FK), provider_type (credentials|siwe), provider_ref (email/phone hash or EOA), timestamps.

siwe_nonces

• nonce (PK), used (boolean), expires_at (UTC), issued_for_domain, issued_for_uri, timestamps.

audit_logs

• log_id (PK), identity_id, user_id, action (bind|merge|unlink|passkey.register|passkey.login), actor

Constraints

• wallets: UNIQUE(address, chain_id); CHECK (type IN ('EOA','AA')); UNIQUE(identity_id, type, chain_id) ensures one EOA and one AA per chain.

• webauthn_credentials.credential_id unique; sign_count monotonic (reject regressions).

Auth

• POST /auth/credentials/login → { username|email|phone, password } → { session_jwt, user_id }

• POST /auth/passkey/register/options → server generates WebAuthn attestation options

Wallet Setup

• POST /wallet/provision → uses session → Create EOA (if missing) + deploy AA → { identity_id, eoa, aa }

• POST /wallet/connect/siwe → { message, signature } → verify SIWE (domain/uri/chainId + nonce), bind EOA, deploy AA → { identity_id, eoa, aa }

Identity

• GET /identity → session → { identity_id, eoa, aa }

Admin/Audit

• GET /admin/merge/diff?source&target

• POST /admin/merge/execute (dual-control for risky merges)

• GET /admin/audit?identity_id|user_id

• Passkey (WebAuthn)

  • rpId = auth domain; allowed origins explicitly listed.

  • userVerification = required; resident/discoverable credentials enabled.

9.1 Capabilities used

• In-App (Embedded) Wallet — built-in auth via Email OTP or Phone OTP (Starter plan; no Thirdweb Passkey/Social for wallet creation).

• SIWE (Auth) for existing wallets (Connect Wallet).

• Smart Accounts (AA) with deterministic deployment (factory + salt).

9.2 Client (Web)

1. After a successful BGC/iB login (credentials/Passkey handled by our system), open a custom modal with exactly two buttons:

   • Create Wallet (In-App Wallet, built-in)

   • Connect Wallet (External + SIWE)

9.3 Server (Auth + Identity)

• Credentials/Passkey login: issue session/JWT { user_id, roles }. (Passkey ceremonies handled by WebAuthn endpoints in the Auth service.)

• SIWE challenge: generate cryptographic nonce, store (used=false, TTL 3–5 min).

9.4 Environment Variables

• THIRDWEB_CLIENT_ID

• CHAIN_ID

• RPC_URL

9.5 Error Handling & Cost Controls

• Retry with backoff for AA deploy; allow lazy deploy on first tx if applicable.

• Scope gas sponsorship (onboarding only, per-action caps); alerts on budget.

• Clear UX for wrong network / expired nonce / denied signature.

• Domains: auth.bgcxib.com (unified), brand app domains.

• CI/CD: build/lint/typecheck; E2E flows (Create & Connect); smoke tests for JWT issuance, SIWE verify, AA deploy.

• Observability: metrics (login success/error, passkey adoption, SIWE failures, AA deployment success), logs, traces; alerts for gas spend and failure spikes.

1. Inventory current user stores; pick the source of truth (users).

2. Deduplicate historic BGC/iB accounts into unified users; preserve audit mapping.

3. Soft-launch Wallet Setup behind a feature flag (only users without a wallet see it).

• Unit: SIWE message builder/validator; nonce repository; AA address derivation; WebAuthn option/response validators.

• Integration: credentials/Passkey login → /wallet/provision and /wallet/connect/siwe.

• E2E: full flows A (Embedded) & B (SIWE); negative paths (expired/reused nonce, wrong domain/chainId, duplicate EOA).

• Roles: Viewer, Support, Operator, Finance, Admin, SuperAdmin, Auditor.

• Permissions: users.read, wallets.read, wallets.link/unlink, users.merge_safe, users.merge_risky (dual-control), balances.adjust

Acceptance Criteria

• Single credentials login (with Passkey support) works across BGC/iB.

• Wallet Setup (Create/Connect) yields a working AA.

• GET /identity returns consistent EOA/AA across apps.

Launch Checklist

• Domains & SSL ready

• Env vars configured (all envs)

• AA factory & (optional) paymaster configured

• E2E suite green on staging

Notes

• Snippets are illustrative (TypeScript/Next.js style).

• Replace SDK calls with the exact Thirdweb functions used in your repo.

• Always handle errors, network checks, and feature flags in production.

Plan: thirdweb Starter · MAU < 1k · RPC < 1M · Chain: Base mainnet Scope: vendor/platform costs only (no human resources)

• Plan fee: Starter = $5 / month.

• In-App (Embedded) Wallet — MAU pricing: $0.015 / MAU for 0–100k, first 1,000 wallets free → with <1k MAU, effective $0.

• Account Abstraction (AA) — user-ops: first 1,000 included, then $1 per 1,000 (=$0.001/op). With low usage, often $0

Platform subtotal (under stated caps): ≈ $5 / month.

Note (SMS): Thirdweb’s pricing notes international SMS may incur extra fees (country-dependent). If you avoid Phone OTP and use Email OTP for “Create Wallet”, this line item is $0.

If you enable Phone OTP for wallet creation, budget per SMS by destination. For example, Indonesia outbound via Twilio is $0.4414 per SMS segment as of Oct-2025; US starts around $0.0083. (Using Email OTP keeps this at $0.)

SMS monthly estimate = # of SMS OTP × local_rate.

• Reference fee level: recent data shows Base average tx fee ≈ $0.03 per transaction. Use this as a baseline for simple, sponsored actions.

• AA (smart account) deploy: budget ≈ 2× average tx (contract deployment & init overhead) → ≈ $0.06 per new wallet. (Rough planning factor.)

• Paymaster surcharge (if using thirdweb paymaster): +2.5% on sponsored gas.

Real costs vary with network gas, calldata size, and ETH price on the day. You can reduce spend via lazy AA deployment (create AA on first action) and by sponsoring only onboarding operations.

• Thirdweb platform (Starter): ~$5

• In-App Wallet MAU, AA user-ops, RPC: $0 (within free tiers).

• Gas sponsorship (Base): ~$9–$111 depending on onboarding volume & sponsored actions (see table).

Ballpark total:

• Email-only OTP: ≈ $14–$116 / month (Starter $5 + gas).

• With some Phone OTP (ID): add ~$0.44 per SMS used.

• Prefer Email OTP; keep Phone OTP as fallback only.

• Lazy deploy smart accounts; sponsor first action only; set budget caps in paymaster rules.

End of document.

P.S. Read this document freely for information and guidance. Do not redistribute or restate—no quotes, summaries, paraphrases, or derivatives—without prior written permission from . Sharing the link is allowed. So, share the link, not the text. Do not discuss or re-tell the contents in any form—written, spoken, or recorded—without prior written permission.