# 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.

<figure><img src="https://2637588294-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F9JGIkcXbzugdcagoi7aL%2Fuploads%2FQ5MnSH9YCJyYxkSwhrep%2Fimage.png?alt=media&#x26;token=a9468a07-09f8-4101-ba36-2c9ea47df78d" alt=""><figcaption><p>Workflow</p></figcaption></figure>

### 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.        |