Architecture

Overview

The Payment ID system with OAuth integration provides a seamless way for users to register and manage human-readable identifiers across blockchain networks using only their email. The architecture leverages ZK Email OAuth for authentication and ephemeral key management, eliminating the need for users to manage private keys or interact directly with the blockchain.

Key Components

Component	Description
ZK Email OAuth SDK	Provides email-based authentication and ephemeral key generation for seamless user onboarding.
Registration Controller	Manages the registration process for Payment IDs and initializes resolver records.
PID Contract	ERC-721 token contract representing ownership of Payment IDs as transferable NFTs.
PID Registry	Core registry maintaining relationships between token IDs, owners, and resolvers.
Public Resolver	Resolves Payment IDs to blockchain addresses across different networks.
Email Wallet Core	Underlying infrastructure handling email verification and transaction execution.
Wallet	Singleton wallet for email users

Login Flow

1. Email Sign-In: User provides their email address to sign in or sign up through the dApp.

2. OAuth Request: The OauthClient sends a request to the relayer to initiate the email-based authentication.

3. One-Time Email Reply: User receives an email and authenticates by simply replying to it.

4. Ephemeral Key Generation: The OAuth SDK generates an ephemeral ECDSA key for the browser session.

5. Key Activation: The ephemeral key is activated on-chain once the email proof is verified.

Registration Flow

1. Payment ID Registration: User selects a Payment ID to register (e.g., alice@binance).

2. Transaction Construction: The dApp constructs a transaction to the Registration Controller.

3. OAuth Execution: The transaction is executed via the ephemeral key using oauthExecuteTx.

4. PID Minting: The Registration Controller mints a new PID token to the user's Email Wallet address.

5. Record Setup: The PID Registry and Resolver are updated with the appropriate records.

Workflow

Contract Functions

Registration Controller

Function	Description
register	Registers a new Payment ID, minting a token and setting up resolver records.
available	Checks if a Payment ID is available for registration.

PID Contract

Function	Description
register	Mints a new token representing the Payment ID.
transferFrom	Transfers ownership of a Payment ID, updating registry records.

PID Registry

Function	Description
setRecord	Sets both owner and resolver for a token ID.
setOwner	Updates ownership information for a token ID.
setResolver	Updates resolver information for a token ID.

Public Resolver

Function	Description
setAddr	Sets address records for different chains and source types.
addr	Retrieves address records for specific chains and source types.

Security Considerations

Consideration	Description
Email Privacy	User email addresses remain private through ZK proofs, never exposed on-chain.
Key Management	Ephemeral keys are generated per session, reducing risks of permanent key compromise.
Transaction Limitations	Ephemeral keys can be configured with expiration times and token allowances.
Session Integrity	The OAuth system ensures that only authenticated users can perform operations.