BGC X IBLOOMING WEB3 LOGIN DRAFT

Authors: Prof. NOTA (proposal), Yuku (technical owner), BGC & iBLOOMING engineering/DevOps Audience: BGC & iBLOOMING founders, engineers, QA, DevOps, PMs Status: Draft for implementation sign‑off Last updated: 2025‑09‑29 (Asia/Jakarta)

1) Executive Summary

We propose to ship Web3 Login first (October) while the team finalizes the Whitepaper & Tokenomics. This delivers a visible, low‑risk foundation for the ecosystem:

• Unified identity across BGC Web, iBLOOMING Web, and iBLOOMING Mobile via one EOA (Externally Owned Account) and one Smart Account (Account Abstraction/AA) per user per chain.

• Bridges Web2 ↔ Web3: users can start with email/phone/passkey or existing BGC/iB credentials and seamlessly obtain a self‑custodial wallet; Web3‑native users can connect existing wallets.

• Faster analytics: reliable, on‑chain‑addressed telemetry for behavior simulations (Alpha Coin → later iBC/iBTC).

Why ship this first?

1. Quick win with high user impact.

2. Necessary base layer for identity‑keyed rewards & future settlements.

3. Decoupled scope (can be executed by a small pod; minimal cross‑team contention).

Non‑goals (October)

• Launch of production token contracts, DEX/CEX listings, or final economic parameters.

• Complex KYC/AML flows (beyond optional email/phone verification).

• Multi‑chain rollout (focus on a single chain first; propose Base testnet → mainnet).

2) Architecture Principles

• Single EOA per user (master identity).

• One Smart Account (AA) per user per chain, deterministic (CREATE2) from the EOA + salt so the AA address stays the same across BGC & iBLOOMING.

• Identity Bridge Service maps: identity_id ⇄ EOA ⇄ AA ⇄ bgc_user_id ⇄ ib_user_id.

3) Scope (October)

In‑scope

• A single Login entry with six options: (1) Login with BGC (2) Login with iBLOOMING (3) Login with Email (OTP) (4) Login with Phone (OTP) (5) Login with Passkey (biometric) (6) Login with Web3 Wallet (Connect Wallet)

• Automatic wallet provisioning & upgrade:

Out‑of‑scope (defer to later sprints)

• Gas sponsorship in production (can pilot on staging).

• OAuth socials (Google/Apple/etc.) unless trivial to include.

• Mobile deep‑linking polish (basic flows supported; advanced UX later).

4) System Overview

5) User Login Flows (Six Options)

A) Login with BGC (legacy account)

1. Redirect to BGC auth (new tab or modal).

2. BGC returns JWT → Identity Bridge provisions In‑App EOA if missing; enables AA.

3. Identity Bridge binds bgc_user_id to identity_id and wallet(s).

B) Login with iBLOOMING (legacy account)

Same as A but with iB auth and ib_user_id binding.

C) Login with Email (OTP)

1. Send OTP → verify.

2. Create/restore In‑App Wallet EOA → enable AA.

3. Offer to create or link BGC/iB accounts.

D) Login with Phone (OTP)

Same as C but using phone number.

E) Login with Passkey (biometric)

1. Passkey/WebAuthn ceremony → In‑App Wallet EOA → enable AA.

2. Offer to create/link BGC/iB accounts.

F) Login with Web3 Wallet (Connect Wallet)

1. User connects MetaMask/OKX/Phantom‑EVM/Rainbow/etc.

2. SIWE challenge → verify.

3. Enable AA with connected wallet as admin.

Zero‑Redundancy Policy:

• If a login flow reveals an EOA already mapped to another identity, we reuse the existing identity_id (no duplicates).

• Link/merge requires dual proof (OTP+SIWE) and writes an audit log.

6) Components

• Connect UI (Web): prebuilt modal shows Email/Phone/Passkey + 3rd‑party wallets. Two custom CTAs for “Login with BGC/iB”.

• In‑App Wallet (Embedded/MPC): creates EOAs for Email/Phone/Passkey; passkey‑first UX where available.

• Account Abstraction (Smart Wallet): auto “upgrade” any connected EOA to an AA account; optional gas sponsorship via Paymaster.

7) Data Model (minimal viable)

identities

• identity_id (UUID, PK), created_at

wallets

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

accounts

• account_id (PK), identity_id (FK), app (BGC | IB), app_user_id, created_at

• Constraints: UNIQUE(

auth_providers

• provider_id (PK), identity_id (FK), provider_type (email | phone | passkey | siwe | bgc | ib), provider_ref (email/phone hash or wallet addr), created_at

audit_logs

• log_id (PK), identity_id, action (bind | merge | unlink), actor, metadata, created_at

8) Identity Bridge — API Contracts (HTTP/JSON)

• POST /auth/web2/bgc/start → redirect URL

• GET /auth/web2/bgc/callback?code=… → returns session JWT

• POST /wallet/provision → body: { session_jwt }

9) Security & Privacy

• No plaintext private keys stored server‑side; In‑App Wallet uses secure enclaves/MPC and user factors (email/phone/passkey).

• SIWE + per‑login nonce to prevent replay.

• Rate limiting for OTP and link/merge endpoints.

10) Environments & DevOps

• Chains: Staging → Base testnet; Production → Base mainnet.

• Third‑party infra: Bundler/Paymaster (staging only at first).

• Config (12‑factor): THIRDWEB_CLIENT_ID, WC_PROJECT_ID, CHAIN_ID

11) Implementation Plan — October 2025 (target)

Week 1 (Oct 1–7)

• Kickoff & sign‑off scope; create repos and envs.

• Web apps: add unified Login button + Connect UI (Email/Phone/Passkey/Wallet).

• Identity Bridge skeleton (DB schemas; /identity read‑only).

Week 2 (Oct 8–14)

• Web2 logins: BGC/iB redirects & callbacks; session JWT.

• Wallet provisioning for Web2 flows (EOA) + enable AA on staging chain.

• SIWE flow for external wallets.

Week 3 (Oct 15–21)

• Link/merge flows (dual proof policy, audit logs).

• Mobile (iB): implement ConnectButton RN or HTTP API (Email/Phone/Passkey + WalletConnect).

• QA: unit + e2e (happy paths + failure cases).

Week 4 (Oct 22–31)

• Staging bake‑off (gasless trial via Paymaster).

• Hardening: rate limiting, retries, telemetry dashboards.

• Production launch window with feature flags; rollback plan.

Deliverables

• Web: unified Login + AA.

• Mobile: at least Email/Phone/WalletConnect + AA.

• Identity Bridge: mapping APIs + Admin Console.

Acceptance Criteria

• A user can log in via any of the six options and end with one identity having one EOA and one AA on the target chain.

• The same identity is recognized across BGC and iB apps.

• Admins can safely link/merge with full auditability.

12) Testing Plan

• Unit: OTP, SIWE nonce, DB constraints (unique address per chain).

• Integration: /wallet/provision, /account/link, /identity.

13) Migration & Rollout

1. Soft launch on staging; internal dogfooding across both apps.

2. Email/WA campaign: “Bind your wallet” (3 clicks).

3. Progressive feature flag: new signups auto‑provision wallets; after ≥95% existing users are bound, auto‑create BGC+iB accounts for new identities.

14) Risks & Mitigations

• Duplicate identities due to race conditions → enforce DB uniqueness + retry/merge workflow.

• OTP deliverability → fallback channel (email↔SMS), resend with backoff.

• Mobile deep‑link quirks → use universal links + WalletConnect v2; provide QR fallback.

15) Minimal Code Samples

15.1 Next.js (Web)

15.2 Identity Bridge (pseudo‑routes)

15.3 React Native (Mobile iB)

• Use the ConnectButton (React Native) or the HTTP API to support Email/Phone/Passkey + WalletConnect.

• Keep the same accountAbstraction settings; reuse Identity Bridge endpoints.

16) Glossary

A founder‑friendly glossary of terms and acronyms used in this plan. Short, plain‑English definitions come first; technical notes follow in parentheses when helpful.

Core Identity & Wallets

• EOA (Externally Owned Account): A standard crypto wallet controlled by a private key (e.g., MetaMask address). (EVM concept.)

• Smart Account / Smart Wallet: A programmable wallet implemented as a smart contract. In our plan it’s created from the user’s EOA and follows ERC‑4337 rules.

• Account Abstraction (AA): A model (EIP‑4337) that makes smart accounts act like normal wallets but with extra powers (gas sponsorship, batching, policies).

Authentication & Linking

• Web2 Login: Traditional login via existing BGC/iB accounts, email+OTP, phone+OTP, or passkey.

• Web3 Login: Authentication using a crypto wallet (EOA) and SIWE.

• SIWE (Sign‑In With Ethereum / EIP‑4361): A standard where users sign a human‑readable message with their wallet to prove control of an address (no transaction required).

Security & Compliance

• No Plaintext Private Keys: Private keys are never stored or transmitted as raw text. In‑App wallets use secure enclaves/MPC/OS keystores.

• MFA (Multi‑Factor Authentication): Requiring >1 proof (e.g., passkey + OTP) for sensitive operations.

• Nonce: A unique value used once to prevent replay (exists in SIWE and in on‑chain transactions; context differs).

Tokens & Economics (context only)

• Tokenomics: The economic design of a token (supply, emissions, rewards). Final parameters are out‑of‑scope for October.

• DEX/CEX: Decentralized/Centralized Exchanges where tokens can be traded. Listings are out‑of‑scope for October.

• Airdrop / Faucet: Token distribution mechanisms; faucets usually provide small testnet funds for testing.

Blockchain & EVM Basics

• EVM (Ethereum Virtual Machine): The execution environment for smart contracts used by Ethereum and many L2s (including Base).

• Base: An Ethereum Layer‑2 (OP Stack) we target for staging (testnet) and production (mainnet).

• Gas / Gas Price / Gwei: Computational fee paid to execute transactions. Gas sponsorship = someone else pays.

App & Service Architecture

• Identity Bridge Service: A small service (our component) that maps identity_id ⇄ EOA ⇄ AA ⇄ bgc_user_id ⇄ ib_user_id, exposes /identity, /account/link, /identity/merge, etc.

• JWT (JSON Web Token): A signed token for session/auth between services (header.payload.signature).

Mobile & Deep Linking

• Deep Link / Universal Link (iOS) / App Link (Android): Mechanisms to open an app to a specific screen from a URL.

• Wallet Deep Linking: Opening a wallet app from a dApp and returning the user after approval.

• QR Fallback: Displaying a QR code users can scan with their wallet if deep linking fails.

Data & Analytics (light)

• Telemetry: Operational data (success/error rates, latency) used for monitoring.

• Behavior Analytics: Measuring user actions tied to on‑chain identity (for simulations like Alpha Coin → later iBC/iBTC).

• Anomaly Detection: Automated alerts for suspicious patterns (e.g., unusual merges or link spikes).

Governance & Process

• Sign‑off: Formal approval gate before production release (scope, security, QA, monitoring, rollback ready).

• Runbook / Playbook: Step‑by‑step guides for operations (incident response, rollback, key rotation).

• Change Log: Human‑readable list of changes per release for transparency.

17) References & Further Reading

• thirdweb React SDK v5 — Connect UI & components: https://portal.thirdweb.com/react/v5

• ConnectButton docs (supports email/phone/passkey & external wallets): https://portal.thirdweb.com/react/v5/components/ConnectButton

• In‑App Wallets (Email/Phone/Passkey, socials, custom auth): https://portal.thirdweb.com/react/v5/in-app-wallet/get-started

18) Sign‑off Checklist

This section is the final quality gate before enabling production features. All items must be checked to proceed.

1. Scope & timeline approved (Founders, PM)

   • Acceptance: October scope is frozen (six login options, EOA→AA, Identity Bridge basics) with a clear calendar and signed‑off responsibilities.

   • Artifacts: finalized scope doc, sprint plan, locked epics/tickets.

Green‑light rule: proceed to production only when all five items are checked ✅. Owner mapping: (1) Founders/PM, (2) Security/Eng, (3) QA/DevOps, (4) DevOps/Eng Mgmt, (5) SRE/DevOps.

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.