zkLogin Framework (Based on 4337 Contract Wallet)

zkLogin Workflow

Components

OAuth Provider

Entities implementing OpenID Connect and OAuth 2.0 protocols, such as Google, Apple, and Meta, have a key feature: the ability to issue signed JWTs (JSON Web Tokens) containing a set of claims to verify the identity of end users.

Frontend

The frontend application supporting zkLogin guides users through the OAuth login process, passes circuit inputs to the zkLogin Service, and receives a proof. Since there is no need to securely store or export key pairs, no additional clients or plugins are required. The frontend can be seamlessly integrated into any Dapp, reducing the complexity for users when interacting with the Dapp.

zkLogin Service

A zero-knowledge proof is generated to verify the validity of the JWT without revealing its content. We currently use zk-SNARKs to generate the proof, as they are better suited for handling smaller proof sizes.

• Bundler

Bundler is an intermediary responsible for bundling and submitting transactions. It collects operation requests from users’ wallets (such as $UserOperations$ in EIP-4337), combines multiple user operations, and sends them as a transaction bundle to the blockchain for processing. When submitting these operations, the Bundler calculates and pays the necessary gas fees and ensures the validity of these operations.

• Entrypoint Contract

Entrypoint contract is the core smart contract implementing the EIP-4337 standard, responsible for handling operations related to user accounts. It receives user operation requests submitted by the Bundler, verifies and executes these operations. The Entrypoint contract also manages account verification logic, gas payment logic, and calls functions from the user’s wallet.

• Wallet Contract

Wallet contract is a smart contract on the blockchain that provides account functionalities for users, often replacing traditional EOAs (Externally Owned Accounts). It allows users to manage their digital assets and interaction logic through smart contracts in a flexible manner.

• Verification Contract

Verification contract is responsible for verifying proofs related to user operations, such as zero-knowledge proofs generated by zk-SNARKs. In the zkLogin scenario, the Verification contract receives proofs generated by the zkLogin Service and verifies their validity to ensure the correctness of the user’s operations and identity information.

Workflow

1. User’s First Login (Initial Registration)

Frontend Operations:

• The frontend generates a secp256k1 public-private key pair $(priv_{k1}，pub_{k1})$ for the user and calculates the EOA address $addr1$.

• The frontend computes $nonce1 = H(addr1, exp1)$，and sends $nonce1$ to the OAuth server.

• After the user logs in via OAuth, the front end obtains the user’s JWT, which contains the fields $iss$, $aud$, $sub$, and $nonce$. The frontend parses these fields and calculates the $salt$ required for creating the Wallet contract: $salt = H(iss, aud, sub)$.

• The frontend then sends a request to the zkLogin Service with the input data to generate the corresponding proof.

zkLogin Service Operation:

• The ZEROBASE backend receives the input sent by the frontend and passes it into the $prove$ function.

• It generates the corresponding proof and returns the proof (including $publicSignals$) to the frontend

Frontend Operations:

• The frontend takes the proof (with $pubsignals$ containing $addr2$, $iss$, $aud$, $sub$) obtained from ZEROBASE, combines it with business parameters, and uses the private key $priv_{k1}$ to create an encrypted signature. The signed data is then structured into a $UserOperation$ and sent to the Bundler.

Bundler Operations:

• The Bundler verifies the validity of the $UserOperation$ and then sends the operation to the EntryPoint contract.

EntryPoint Contract:

• The EntryPoint contract receives the $UserOperation$ passed by the Bundler and calculates $salt = H(iss, aud, sub)$ from $UserOperation.proof.pubsignal$. It then checks in the mapping table to see if a field with the $key$ as $salt$ exists. If it does not exist, the contract creates a Wallet contract for the user using the $salt$ as a parameter and stores the corresponding $salt$ value in the mapping table $(key: salt, value: Wallet contract address)$.

• The EntryPoint contract then forwards the $UserOperation.proof$ and $UserOperation.calldata$ to the Wallet contract.

Wallet Contract:

• The EntryPoint contract calls the verification contract and passes in $UserOperation.proof$.

Verification Contract:

• The verification contract verifies the zkProof to ensure that the information provided by the user matches the expected values.

Wallet Contract:

• After successfully validating $UserOperation.proof$, the $owner$ is updated to $addr1$, and the remaining business logic is executed.

2. User Logs Out and Logs In Again

Frontend Operations:

• When the user logs in again, the frontend generates a new secp256k1 public-private key pair $(priv_{k2}, pub_{k2})$ and logs in via OAuth to obtain a new JWT, which contains a new $nonce2 = H(addr2, exp2)$ field.

• The frontend parses the JWT, extracts the circuit input, and sends the input to the ZEROBASE Backend.

zkLogin Service (ZEROBASE) Operations:

• The zkLogin Service backend receives the input sent by the frontend and passes it into the $prove$ function.

• It generates the corresponding proof and returns the proof (including $publicSignals$) to the frontend.

Frontend Operations:

• The frontend takes the proof (with $pubsignals$ containing $addr2$, $iss$, $aud$, $sub$) obtained from the zkLogin Service, combines it with business parameters, and signs it using $priv_{k2}$. This signed data is then structured into a $UserOperation$ and sent to the Bundler.

Bundler Operation:

• The Bundler sends the $UserOperation$ to the EntryPoint contract.

EntryPoint Contract:

• The EntryPoint contract verifies the signature, ensuring that the signer is $addr2$ from the $publicSignals$, but without needing to ensure that the Wallet contract owner is $addr2$. It then calculates $salt = H(iss, aud, sub)$ from $UserOperation.proof.pubsignal$. The contract checks if an entry with the $key$ as $salt$ exists in the mapping table. If it exists, the EntryPoint forwards $UserOperation.proof$ and $UserOperation.calldata$ to the corresponding Wallet contract.

Wallet Contract:

• The EntryPoint contract calls the verification contract, passing in the $UserOperation.proof$.

Verification Contract:

• The verification contract verifies the zkProof to ensure that the information provided by the user matches the expected values.

Wallet Contract:

• After successfully validating the $UserOperation.proof$, the $owner$ is updated to $addr2$, and the remaining business logic is executed.

3. Normal Operation (User Has Not Logged Out)

Frontend Operations:

• After the user successfully logs in, they can proceed with regular transactions and operations.

• The frontend computes the user’s $salt = H(iss, sub, aud)$, combines it with business parameters, and signs the operation using the current private key $priv_k$. It then constructs a $UserOperation$ and sends it to the Bundler.

Bundler Operation:

• The Bundler sends the user’s $UserOperation$ to the EntryPoint contract.

EntryPoint Contract:

• The EntryPoint contract retrieves the corresponding Wallet contract address based on $UserOperation.salt$, verifies the signature to ensure that the Wallet contract’s owner is equal to $addr$, and then executes the user’s $UserOperation$ through the Wallet contract.

The standard proof of zkLogin circuit generation takes 200ms on TEE devices. 75TPS/Prover Node, supporting large-scale adoption.

1/4 196ms

2/4 199ms

3/4 209ms

4/4 210ms

Use Case

zkLogin - StarkNet

zkLogin utilizes Zero-Knowledge Proofs (ZKPs) to enable users to authenticate blockchain transactions on StarkNet using existing credentials from OpenID Connect-enabled platforms (e.g., Google, Facebook) without disclosing sensitive information or relying on additional trusted parties.

zkLogin - TOMO Wallet

ZEROBASE is collaborating with TOMO Wallet and World Liberty Financial, a project associated with Trump, to deliver a more streamlined and privacy-focused login experience. By utilizing ZEROBASE 's ZKLogin technology, sensitive user details such as OpenID, avatar, and email are securely processed and converted into a zero-knowledge proof. This proof is then returned to TOMO for verification, ensuring that user data is authenticated without being exposed. Once validated, TOMO can securely complete the login process. This partnership, in collaboration with World Liberty Financial, enhances security and privacy, offering TOMO users a more efficient and trusted way to manage their accounts.

About ZEROBASE

ZEROBASE is a real-time ZK prover network designed for speed, decentralization, and regulatory compliance. It generates ZK proofs within hundreds of milliseconds and ensures decentralized, fast consensus through its HUB ring-wake mechanism, enabling large-scale commercial use. We offer free circuit development services and commercial licenses, including zkLogin, zkDarkPool, and zkVote systems, which require ZEROBASE provers for optimal performance. We also undertake general commercial circuit development.

ZEROBASE’s standard circuit integration takes one week, while custom circuit development takes only 2-3 weeks. Agile development and fast iteration are achieved through proof conversion using Circom and Gnark, with an optional decryptable circuit framework for compliance. With a core team of three years and partnerships with top institutions, ZEROBASE delivers high-quality circuit development and proof generation services.

Utilize your intelligence and my circuit development skills to establish cryptographic applications on Ethereum together.Share your insights.

We offer free circuit generation for public goods. Please feel free to email me directly at: [email protected]