# web3auth/mpc-core-kit architecture

> Architecture diagram of the GitHub repository web3auth/mpc-core-kit, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-11-04). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/web3auth/mpc-core-kit
- Repository: https://github.com/web3auth/mpc-core-kit

## Overview

##### Project type and purpose
- This is an open-source wrapper SDK (npm package) named “Web3Auth MPC Core Kit.”
- Its purpose is to expose a set of client-side functions that let developers integrate passwordless Web3 authentication (via MPC + OAuth or JWT) into their own front-end apps or wallets.

##### File structure
- **Top-level config**:
- `.eslintrc.js`, `.prettierrc.yaml`, `tsconfig.json`, `webpack.config.js` – linting, formatting, TypeScript compilation, bundling.
- `package.json`, `package-lock.json` – dependencies, build scripts.
- `tests/` – unit tests for core functions (factors, session timing, import recovery, etc.).
- **Core source** (`src/`):
- `mpcCoreKit.ts` – main entry point exporting the `Web3AuthMPCCoreKit` class.
- `constants.ts`, `interfaces.ts`, `helper/`, `utils.ts` – supporting modules (browserStorage, factorSerialization, error handling, security question logic).
- `index.ts` – public API surface.
- **Example/demo** (`demo/redirect-flow-example/`): a standalone React/Vite app illustrating usage of the SDK.

##### README for additional insights
- Confirms the core responsibilities: initialize Web3Auth with chain config, call `loginWithOAuth` or `loginWithJWT`, obtain a provider for blockchain RPC calls.
- Mentions interaction with external Web3Auth Dashboard (client ID) and external blockchain RPC endpoints.

a. Main components
- Client Application (your UI code / demo app)
- Web3Auth MPC Core Kit SDK (library modules)
- Web3Auth MPC Network (Torus nodes / threshold key service)
- OAuth Identity Providers (Google, Twitter, Discord, etc.) and/or JWT IdP
- Blockchain RPC Node (Ethereum, etc.)
- Browser Storage (local/session storage for storing key shares)
b. Relationships and interactions
1. Client App imports and initializes the SDK with a `web3AuthClientId` and `chainConfig`.
2. Client App calls `sdk.init()` → SDK connects to Web3Auth network over HTTPS/WebSocket to fetch its key share.
3. User clicks “Login” → SDK triggers OAuth2 flow or JWT exchange with the external identity provider.
4. OAuth IdP redirects back to the Client App → SDK reconstructs the private key via MPC: combining the server share (Web3Auth nodes) and the client share (in browser storage).
5. SDK exposes a Web3 provider → Client App uses it to send RPC calls to the configured blockchain RPC node.
c. Architectural patterns and principles
- **Facade/Wrapper**: the SDK abstracts away complexity of MPC, OAuth, key management, exposing a simple API.
- **Modular design**: helper modules (serialization, storage, security questions) are decoupled.
- **Client­side‐first**: all cryptographic key operations happen in the browser, with no custodial exposure.
d. Key technologies and libraries
- TypeScript (src/, interfaces, tsconfig)
- Webpack (bundling for distribution)
- Jest/Mocha (tests/*.spec.ts)
- Vite/React (demo app)
- OAuth2 / JWT protocols
- JSON RPC (blockchain interactions)

##### Detail
- Initialization module (`mpcCoreKit.init`)
- OAuth/JWT handlers (`loginWithOAuth`, `loginWithJWT`)
- Storage & serialization helpers
- Provider factory for RPC calls
- Error handling paths (helper/errors.ts) and developer-configurable surfaces (constants.ts, interfaces.ts).

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Client Application
    ClientApp["Client Application<br/>(Demo or Host App)"]:::client

    %% SDK Boundary
    subgraph "MPC Core Kit SDK" 
        direction TB
        API["Public API Surface<br/>index.ts"]:::sdk
        MPC["Web3AuthMPCCoreKit Class & Init<br/>mpcCoreKit.ts"]:::sdk
        OAuth["OAuth & JWT Handlers<br/>loginWithOAuth(), loginWithJWT()"]:::sdk
        ProvFactory["Provider Factory<br/>utils.ts"]:::sdk
        Constants["Constants & Config<br/>constants.ts"]:::sdk
        Interfaces["Type Definitions & Interfaces<br/>interfaces.ts"]:::sdk
        subgraph "Helpers"
            direction TB
            BrowserStorage["Browser Storage Helper<br/>helper/browserStorage.ts"]:::sdk
            FactorSer["Factor Serialization Helper<br/>helper/factorSerialization.ts"]:::sdk
            SecQuestion["Security Question Logic<br/>helper/securityQuestion.ts"]:::sdk
            Errors["Error Handling Module<br/>helper/errors.ts"]:::sdk
            HelperIndex["Helper Module Index<br/>helper/index.ts"]:::sdk
        end
        Utils["Utility Functions<br/>utils.ts"]:::sdk
    end

    %% External Services
    subgraph "External Services"
        direction TB
        Web3AuthNet["Web3Auth MPC Network"]:::external
        OAuthProviders["OAuth / JWT Identity Providers"]:::external
        BlockchainRPC["Blockchain RPC Node"]:::external
    end

    %% Config & Test files
    subgraph "Configs & Tests"
        direction TB
        BuildConfig["Webpack & TS Configs<br/>webpack.config.js, tsconfig.json"]:::config
        LintFmt["Linting & Formatting Configs<br/>.eslintrc.js, .prettierrc.yaml"]:::config
        UnitTests["Unit Tests<br/>tests/"]:::config
    end

    %% Demo App
    DemoApp["Demo Client Application<br/>demo/redirect-flow-example/"]:::client

    %% Flows
    ClientApp -->|"import & init()"| MPC
    MPC -->|"MPC key share exchange"| Web3AuthNet
    ClientApp -->|"loginWithOAuth()/loginWithJWT()"| OAuth
    OAuth -->|"POST /authorize"| OAuthProviders
    OAuthProviders -->|"redirect callback"| OAuth
    OAuth -->|"reconstruct key"| MPC
    MPC -->|"provider factory"| ProvFactory
    ProvFactory -->|"eth_sendTransaction<br/>JSON-RPC"| BlockchainRPC
    ClientApp -->|"uses provider"| BlockchainRPC

    DemoApp -->|"example integration"| ClientApp

    %% Click events
    click API "https://github.com/web3auth/mpc-core-kit/blob/master/src/index.ts"
    click MPC "https://github.com/web3auth/mpc-core-kit/blob/master/src/mpcCoreKit.ts"
    click OAuth "https://github.com/web3auth/mpc-core-kit/blob/master/src/mpcCoreKit.ts"
    click ProvFactory "https://github.com/web3auth/mpc-core-kit/blob/master/src/utils.ts"
    click Constants "https://github.com/web3auth/mpc-core-kit/blob/master/src/constants.ts"
    click Interfaces "https://github.com/web3auth/mpc-core-kit/blob/master/src/interfaces.ts"
    click BrowserStorage "https://github.com/web3auth/mpc-core-kit/blob/master/src/helper/browserStorage.ts"
    click FactorSer "https://github.com/web3auth/mpc-core-kit/blob/master/src/helper/factorSerialization.ts"
    click SecQuestion "https://github.com/web3auth/mpc-core-kit/blob/master/src/helper/securityQuestion.ts"
    click Errors "https://github.com/web3auth/mpc-core-kit/blob/master/src/helper/errors.ts"
    click HelperIndex "https://github.com/web3auth/mpc-core-kit/blob/master/src/helper/index.ts"
    click Utils "https://github.com/web3auth/mpc-core-kit/blob/master/src/utils.ts"
    click UnitTests "https://github.com/web3auth/mpc-core-kit/tree/master/tests/"
    click DemoApp "https://github.com/web3auth/mpc-core-kit/tree/master/demo/redirect-flow-example/"
    click BuildConfig "https://github.com/web3auth/mpc-core-kit/blob/master/webpack.config.js"
    click LintFmt "https://github.com/web3auth/mpc-core-kit/blob/master/.eslintrc.js"

    %% Styles
    classDef client fill:#daf1ff,stroke:#3399ff
    classDef sdk fill:#d0e8ff,stroke:#0066cc
    classDef external fill:#d4ffd0,stroke:#33cc33
    classDef config fill:#ffe0b2,stroke:#cc6600
```
