We don't belong in your reality, your real life. In your reality, your real life, you can merely meet our avatars in any version. So, stay alert and beware of scams!
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)
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).
Partner signal: live working login across apps shows momentum while tokenomics is being finalized.
Quick win with high user impact.
Necessary base layer for identityβkeyed rewards & future settlements.
Decoupled scope (can be executed by a small pod; minimal crossβteam contention).
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).
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.
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:
Options 1β5 β create EOA (InβApp/Embedded Wallet) if missing β autoβenable Smart Account
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).
Redirect to BGC auth (new tab or modal).
BGC returns JWT β Identity Bridge provisions InβApp EOA if missing; enables AA.
Identity Bridge binds bgc_user_id to identity_id and wallet(s).
Same as A but with iB auth and ib_user_id binding.
Send OTP β verify.
Create/restore InβApp Wallet EOA β enable AA.
Offer to create or link BGC/iB accounts.
Same as C but using phone number.
Passkey/WebAuthn ceremony β InβApp Wallet EOA β enable AA.
Offer to create/link BGC/iB accounts.
User connects MetaMask/OKX/PhantomβEVM/Rainbow/etc.
SIWE challenge β verify.
Enable AA with connected wallet as admin.
Offer to create/link BGC/iB accounts.
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.
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.
Identity Bridge Service: minimal microservice for mapping & merge operations.
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(app,
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
POST /auth/web2/bgc/start β redirect URL
GET /auth/web2/bgc/callback?code=β¦ β returns session JWT
POST /wallet/provision β body: { session_jwt } β creates EOA if missing; prepares AA
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.
PII minimization: store hashed emails/phones where feasible.
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, AA_FACTORY_ADDR, JWT_SECRET
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.
Basic Admin Console (readβonly).
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.
Runbooks: oncall, incident, rollback, key/secrets management.
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.
Unit: OTP, SIWE nonce, DB constraints (unique address per chain).
Integration: /wallet/provision, /account/link, /identity.
E2E: six login paths (new user, existing Web2, existing Web3), identity reuse, link both accounts, forced collision & merge.
Soft launch on staging; internal dogfooding across both apps.
Email/WA campaign: βBind your walletβ (3 clicks).
Progressive feature flag: new signups autoβprovision wallets; after β₯95% existing users are bound, autoβcreate BGC+iB accounts for new identities.
Postβlaunch monitoring; incident playbook; weekly audit of merges.
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.
Gas spikes on mainnet β keep Paymaster off in prod initially; batch AA deployments; preβfund only when needed.
Use the ConnectButton (React Native) or the HTTP API to support Email/Phone/Passkey + WalletConnect.
Keep the same accountAbstraction settings; reuse Identity Bridge endpoints.
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.
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).
EntryPoint: The onβchain contract used by ERCβ4337 to validate and execute UserOperations (the βrouterβ for smart account actions).
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).
Passkey (WebAuthn): Passwordless signβin using device biometrics/secure hardware (Face/Touch ID). In our setup, passkeys can secure an
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).
Replay Attack: An attacker reuses a previously valid message; prevented by unique nonces and expiration windows.
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.
Settlement: Converting points/rights into transferable value (often requires final token design; not in October scope).
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.
Address / Checksum Address: Public identifier of a wallet/contract; checksum casing helps detect typos.
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).
OAuth 2.0 / OIDC:
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.
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).
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.
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
Passkey signβin changelog: https://portal.thirdweb.com/changelog/passkey-sign-in-for-in-app-wallets
This section is the final quality gate before enabling production features. All items must be checked to proceed.
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.
Security review (keys, OTP, SIWE nonces, rate limiting)
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.
Security by design: no plaintext private keys; passkeys/OTP; audit trails for link/merge.
Option 6 β use userβs existing EOA β autoβenable Smart Account (AA).
Identity linking page: allow users to link/merge BGC and iB accounts to the same identity.
Environments: Staging on Base testnet; Production on Base mainnet (toggle via config).
Admin Console: search identity_id, view bindings, approve merges.
Constraints: UNIQUE(address,chain_id)
app_user_idPOST /wallet/connect/siwe β body: { address, signature, nonce } β returns { identity_id }
POST /account/link β body: { identity_id, app, app_user_id } (requires OTP or SIWE per policy)
GET /identity β returns { identity_id, eoa, aa, bgc_user_id?, ib_user_id? }
POST /identity/merge (admin) β body: { from_identity_id, to_identity_id, reason }
Secrets in vault; rotate regularly.
RBAC for Admin Console and merge operations.
Logs include who/when/how for every bind/merge.
BGC_AUTH_URLIB_AUTH_URLCI/CD: build, lint, typeβcheck, smoke test /login β /identity happy paths; e2e on staging before production promote.
Monitoring:
Auth success/error rate per provider.
Duplicate identity attempts.
AA deployment rate & failures.
OTP latency, SIWE errors.
Security: replay protection, authZ on admin routes, rate limits, secret scanning.
Load: peak login bursts; OTP provider throttling behavior.
User confusion β clear copy in UI: βYou will get a selfβcustodial wallet; keep access factors safe.β
Bundler: A service that collects UserOperations from many users and submits them to the EntryPoint in one transaction.
Paymaster: A component that sponsors transaction gas on behalf of users (enables βgaslessβ UX) with rules/limits.
Deterministic Deployment / CREATE2: A method to preβcompute a smart contract address before it is deployed (address determined by salt + bytecode + deployer). Used so a userβs smart account address stays consistent across apps.
Counterfactual Address: A contract address computed before deployment (via CREATE2); it becomes real when deployed.
Chain / Chain ID: A specific blockchain network (e.g., Base mainnet has a numeric chain ID). Apps must explicitly select the chain.
OTP (OneβTime Password): A oneβtime code sent by email/SMS for verifying ownership of a channel during login or linking.
InβApp (Embedded) Wallet: A nonβcustodial wallet generated and secured via SDK (e.g., with passkey/OTP). Users donβt paste private keys; recovery relies on chosen factors (e.g., passkey, email).
WalletConnect / EIPβ6963: Protocols enabling dApp β wallet connections across browsers/devices; EIPβ6963 improves wallet discovery in browsers.
Link (Account Linking): Attaching an app account (BGC/iB) to a single onβchain identity (EOA/Smart Account). Requires proofs (OTP/SIWE).
Merge (Identity Merge): Combining two identities into one (e.g., when duplicate records exist). Requires stronger proofs and admin approval.
PII (Personally Identifiable Information): Data that can identify a person (email, phone, etc.). We minimize and protect it.
RBAC (RoleβBased Access Control): Access permissions based on user roles (e.g., Admin, SecurityOps).
KYC/AML: KnowβYourβCustomer / AntiβMoneyβLaundering checks. Outβofβscope for October beyond basic OTP verification.
Phishing: Trick users to reveal secrets; we never ask users to paste private keys in app UIs.
Audit Trail: An immutable record of critical actions (link/merge), including who/what/when/how, for forensics and accountability.
WORM Storage: WriteβOnceβReadβMany log storage to ensure logs cannot be tampered with postβwrite.
ABI (Application Binary Interface): The interface (function/event signatures) used to call smart contracts.
Event Logs: Onβchain records emitted by contracts (used for indexing and analytics).
Hash: A fixedβlength fingerprint of data (used for integrity, signatures, addresses, logs).
TwelveβFactor Config: A practice of storing configuration in environment variables (not in code), enabling portable deployments.
Feature Flags: Switches to enable/disable features at runtime without redeploying; used for safe launches and rollbacks.
Rollback Plan: A predefined, stepβbyβstep procedure to revert a release safely.
Idempotency: Designing APIs so repeating the same request doesnβt produce duplicate effects (important for wallet provisioning/linking).
Rate Limiting / 429: Limits requests per time window to protect from abuse; HTTP 429 is βToo Many Requests.β
Observability: The trio of metrics, logs, traces used to monitor health and diagnose issues.
CI/CD: Continuous Integration/Continuous Delivery pipelines for automated build/test/deploy.
E2E Tests: Endβtoβend tests simulating real user flows across systems (e.g., six login paths β EOA β AA β link accounts).
Account Abstraction β Get started (autoβsmartβaccount via Connect): https://portal.thirdweb.com/react/v5/account-abstraction/get-started
Smart Wallet (TypeScript API): https://portal.thirdweb.com/references/typescript/v5/smartWallet
Wallets overview + HTTP/TypeScript/React/RN: https://portal.thirdweb.com/wallets
Connect UI overview: https://portal.thirdweb.com/react/v5/connecting-wallets/ui-components
Linking multiple identities to one wallet: https://portal.thirdweb.com/wallets/link-profiles
SIWE (EIPβ4361) spec: https://eips.ethereum.org/EIPS/eip-4361
Account Abstraction (EIPβ4337) spec: https://eips.ethereum.org/EIPS/eip-4337
Ethereum.org β Account Abstraction explainer: https://ethereum.org/roadmap/account-abstraction/
Acceptance: secrets management validated; OTP antiβabuse configured; SIWE uses perβlogin nonce + expiry; rateβlimits in place; admin routes protected with RBAC.
Artifacts: lightweight threat model, security checklist, findings & fixes, signed review note.
Staging signβoff (QA, DevOps)
Acceptance: all six login paths pass on staging/testnet; EOAβAA works; link/merge flows pass; audit logs recorded; E2E suite green; basic load test acceptable.
Artifacts: QA report (pass rates), evidence of AA on testnet, load test summary.
Production feature flags & rollback plan
Acceptance: feature flags exist per capability (Connect UI, provisioning, link/merge); defaults documented; rollback playbook verified in rehearsal; backups/restores tested.
Artifacts: flag registry & defaults, rollback playbook, postβrollback checklist.
Postβlaunch monitoring dashboards
Acceptance: dashboards & alerts live for: login success/error, AA provisioning latency/failure, OTP delivery, SIWE errors, duplicateβidentity attempts; onβcall rota confirmed.
Artifacts: links to Grafana/ELK dashboards, alert thresholds, escalation policy.
[ User ]
β
ββ Web2 Login (BGC/iB) βββββββΊ [ Identity Bridge API ] ββββββ Web3 Login (Email/Phone/Passkey/Connect)
β β
β ββ map identity_id β (EOA, AA)
β ββ link bgc_user_id / ib_user_id
β
ββ BGC Web App ββββββββ calls getIdentity() βββββββββΊ returns { identity_id, EOA, AA, bgc_user_id, ib_user_id }
ββ iB Web/Mobile βββββ calls getIdentity() βββββββββΊ returns { β¦sameβ¦ }
Onβchain:
[ EOA ] β(owner/admin)ββΊ [ Smart Account (ERCβ4337, deterministic) ] ββ(optional)ββΊ Paymaster (gasless)// components/UnifiedLogin.tsx
"use client";
import { ConnectButton } from "thirdweb/react";
import { createThirdwebClient, defineChain } from "thirdweb";
import { inAppWallet, walletConnect, metamaskWallet } from "thirdweb/wallets";
const client = createThirdwebClient({ clientId: process.env.NEXT_PUBLIC_THIRDWEB_CLIENT_ID! });
const base = defineChain(8453); // Base mainnet; use 84532 for Base Sepolia
export default function UnifiedLogin() {
return (
<div className="flex flex-col gap-3 items-center">
{/* Legacy Web2 CTAs */}
<div className="flex gap-2">
<a className="btn" href="/api/auth/bgc/start">Login with BGC</a>
<a className="btn" href="/api/auth/ib/start">Login with iBLOOMING</a>
</div>
{/* Connect UI: Email / Phone / Passkey / External Wallets */}
<ConnectButton
client={client}
wallets={[
inAppWallet({ auth: { options: ["email", "phone", "passkey"] } }),
metamaskWallet(),
walletConnect({ projectId: process.env.NEXT_PUBLIC_WC_PROJECT_ID! }),
]}
accountAbstraction={{ chain: base, sponsorGas: false }}
/>
</div>
);
}POST /auth/web2/bgc/start -> 302 redirect
GET /auth/web2/bgc/callback -> returns session JWT
POST /wallet/provision -> ensures EOA; prepares AA; returns { identity_id, eoa, aa }
POST /wallet/connect/siwe -> verifies SIWE; returns { identity_id }
POST /account/link -> links bgc_user_id/ib_user_id; audit log
GET /identity -> returns identity mapping
POST /identity/merge (admin only) -> merges two identities