DOCSEARCHbyAlgolia
Submit Docs

Email Wallet

repository·main·Indexed 41 days ago

https://github.com/zkemail/email-wallet

A system for deploying and running email-based zero-knowledge identity services. It includes smart contracts, a relayer service, and a front-end interface, utilizing Circom circuits (version 1.0.0) to verify account creation, initialization, transport, fund claiming, and email verification.

Tokens
25.9K
Snippets
75
Records
114
Agent score
52%

What's inside Email Wallet

  1. Understand the ZK-Email Wallet core functionality

    main

    The ZK-Email Wallet is a non-custodial cryptocurrency wallet managed via email. It uses ZK-Email technology to allow users to perform trustless operations by validating email messages as a source of oracle data.

    The V1 smart contract supports:

    • ETH transfers
    • ERC20 token transfers
    • Extensions for interacting with external contracts (e.g., Uniswap)

  2. Email Wallet Repository Structure

    main

    The project is a monorepo organized as follows:

    • packages/circuits: Circom circuits, tests, scripts for generating zkeys/vkeys, and helper functions for circuit inputs.
    • packages/contracts: Solidity contracts, tests, and deployment scripts.
    • packages/relayer: Relayer code (listens to IMAP, generates proofs via prover server, calls contracts).
    • packages/prover: Prover server code (generates ZK proofs for circuits).
    • packages/utils: Helper functions for email parsing and circuit proving.
    • packages/subgraph: Subgraph for indexing circuit-generated events (used by Relayer for PSI communication).
    • packages/scripts: Scripts for generating data for registry contracts.

  3. Overview of Email Wallet Circom Circuits

    main
    The @email-wallet/circom package provides several main circuits used to verify different stages of the Email Wallet lifecycle, including account creation, initialization, transport, claiming funds, and email verification. Each circuit takes specific private inputs and produces public instances (commitments, hashes, or pointers) that can be verified on-chain.

  4. Overview of Email Wallet contract architecture

    main

    The Email Wallet contract system is modular, splitting core logic into specialized handlers and utility contracts.

    Core Components

    • EmailWalletCore.sol: The central contract implementing handleEmailOp. It delegates specific functionalities to various handlers.
    • Handlers:
      • RelayerHandler.sol: Manages Relayer configuration (registration/updates).
      • AccountHandler.sol: Manages account lifecycle (createAccount, initAccount, transportAccount) and wallet functions.
      • UnclaimsHandler.sol: Manages Unclaimed Funds and Unclaimed States.
      • ExtensionHandler.sol: Manages the installation and publishing of Extensions.
    • Wallet.sol: A user-specific contract. The Core contract is the default owner, allowing it to execute call data on a target on behalf of the user.

    Supporting Infrastructure

    • Interfaces: Defines types (EmailOp), commands, events, and interfaces for Verifiers, Price Oracles, and Extensions.
    • Libraries: SubjectUtils.sol (subject line computation) and DecimalUtils.sol (uint to decimal conversion).
    • Utilities:
      • TokenRegistry.sol: Maps ERC20 token names to addresses across chains.
      • UniswapTWAPOracle.sol: Provides Uniswap TWAP prices in ETH.
      • ECDSAOwnedDKIMRegistry.sol: Allows an ECDSA signer to manage DKIM public keys for a domain.
    • Extensions: Default implementations include NFTExtension.sol (NFT transfers) and UniswapExtension.sol (token swaps).
    • Verifiers: A suite of circuit verifiers (e.g., AccountCreationVerifier, EmailSenderVerifier, ClaimVerifier) used to validate ZK proofs.

  5. How the Relayer infrastructure works

    main

    The Relayer acts as a bridge between email communication and blockchain transactions. It consists of four main components:

    • SMTP Server: The entry point that monitors incoming emails. Emails containing an accountCode in the subject line trigger blockchain transactions.
    • Relayer: The core service. It listens to the SMTP server, communicates with the Prover to verify proofs, and writes validated transactions to the blockchain.
    • Prover: A service that verifies and generates zk proofs of the data extracted from emails.
    • Database (DB): A PostgreSQL database used to store account information and facilitate existence checks.

  6. How the Relayer incentive mechanism works

    main

    The Relayer earns revenue through transaction fees collected from senders. This mechanism is inspired by the bundler fee mechanism in ERC-4337.

    Fee Calculation

    The Relayer sets a FEE_PER_GAS (in wei) in the .env file. This value must be less than the maxFeePerGas (currently 2 gwei) defined in the contract.

    When a transaction is posted on-chain with a ZK proof of email, the contract calculates the fee as follows:

    1. Validation: If validateEmailOp fails, the fee is zero.
    2. Gas Measurement: The contract measures the gas consumed during execution.
    3. Base Gas: 55,000 gas is added for ERC20 token refunds.
    4. Use-case Additions:
      • If a recipient's email is specified: +450,000 gas (for ERC20 transfers).
      • Other use cases: +500,000 gas.
    5. Total Fee: FEE_PER_GAS * (Total Gas calculated in steps 2-4).

    Reliability

    The contract catches execution errors during the transaction process rather than failing the transaction. This ensures the Relayer can collect the fee as long as the initial email validation (Step 1) passes, even if the Relayer cannot perfectly simulate all execution outcomes beforehand.

  7. Core technical components of ZK-Email

    main

    The ZK-Email ecosystem relies on two primary technical primitives to enable private, verifiable email data:

    1. ZK-RSA: Enables RSA signature verification (used for DKIM signatures) within a Zero-Knowledge circuit. This ensures the authenticity of the mail server without revealing the full message content.
    2. ZK-Regex: Enables regex pattern matching within a Zero-Knowledge circuit. This allows the wallet to extract specific pieces of information from email messages that do not follow a strict, standardized format.

  8. How ZK-Email technology works

    main

    ZK-Email provides a trustless bridge from Web2 to Web3 by validating the existence of an email message and verifying statements about its content without relying on third-party oracles like Chainlink.

    It works by verifying the DKIM signature (RSA) of an email message in Zero-Knowledge. This allows the system to confirm the message was processed by a specific mail server while keeping the sensitive data within the message private. To extract specific data from unstructured email formats, the system utilizes ZK-Regex for pattern matching within the ZK proof.

  9. Advanced Wallet Features: DKIM Registries and Relayers

    main

    Users can increase their security and decentralization through two main advanced features:

    Personal DKIM Registry

    Users can create their own DKIM Registry. This allows users to have complete control over their email wallet, ensuring it is exclusively accessible and managed by them, providing an extra layer of security and privacy.

    Self-Hosted Relayers

    To reduce reliance on third-party services, users have the ability to host their own relayer. This enhances the decentralization and security of the wallet by allowing users to manage their own relaying service.

  10. How ZK-Email Wallet works technically

    main

    The ZK-Email Wallet uses zero-knowledge proofs to verify email authenticity without exposing sensitive data on-chain.

    The Technical Lifecycle

    1. Authentication: The email is signed using the DKIM protocol managed by your email domain server. This signature is included in the email headers.
    2. ZK Proof Generation: A permissionless Relayer authenticates the DKIM signature and generates a zk proof. This proof validates that the email subject follows the required regular expression, contains the correct recipient address, and specifies the correct amount.
    3. Privacy Preservation: The relayer masks all email addresses. Sensitive data (sender/recipient emails) is not published on-chain. Email addresses are salted via the email's message ID to allow users to retrieve their own on-chain address.
    4. On-Chain Verification: The relayer submits an Ethereum transaction. The smart contract verifies the ZK Proof to ensure the transaction matches the intent expressed in the email subject line before executing the transfer.

    Security Model

    • Non-Custodial: Neither the relayer nor the project developers can steal funds because they cannot forge the cryptographic DKIM signatures required to authorize transactions.
    • Account Abstraction: Control is delegated to an account abstraction wallet under your email provider's domain.

  11. How Email Wallet works

    main

    Email Wallet is an Ethereum smart contract wallet controlled via human-readable emails. It uses Zero-Knowledge (ZK) proofs to verify DKIM signatures of emails without exposing sensitive data on-chain.

    The Workflow

    1. Email Submission: You send an email to the Relayer's email address with a command in the subject line (e.g., Send 1 ETH to recipient@gmail.com).
    2. Proof Generation: The Relayer verifies the DKIM signature (provided in the email headers) and generates a ZK proof. The ZK circuit extracts the subject, recipient email, timestamp, and other metadata.
    3. On-chain Verification: The Relayer calls the smart contract with the ZK proof and extracted data. The contract validates the proof and ensures the subject matches the extracted data.
    4. Execution: Once validated, the contract executes the transaction (e.g., sending ETH).
    5. Privacy: The ZK proof ensures that the sender's email and the recipient's email in the subject line are not exposed on-chain.

    Supported Commands (Examples)

    • ETH Transfers: Send 1 ETH to friend@domain.com or Send 2.5 ETH to 0xf39fd6e51aad88f6f4ce6ab8827279cfffb92266
    • ERC20 Transfers: Send 1.5 DAI to friend@skiff.com
    • Contract Execution: Execute 0xba7676a8.....
    • Extension Management: Install extension Uniswap or Remove extension Uniswap
    • Extension Usage: Swap 1 ETH to DAI or NFT Send 1337 of Punks to recipient@domain.com
    • Configuration: DKIM registry set to 0x1ababab111...
    • Ownership Transfer: Exit Email Wallet. Set owner to 0x1ababab111...

  12. Populate the Token Registry using populate-token-registry

    main

    The populate-token-registry script fetches tokens from the Uniswap default token list and populates the TokenRegistry contracts on your target chain.

    To use this script, you must configure the following environment variables:

    • CHAIN_ID: The ID of the chain you are targeting.
    • RPC_URL: The RPC URL for the chain.
    • TOKEN_REGISTRY: The contract address of the Token Registry.
    • PRIVATE_KEY: The private key of the wallet used to sign the transactions.
    # Set environment variables
export CHAIN_ID=1
export RPC_URL=https://eth-mainnet.g.alchemy.com/v2/your-api-key
export TOKEN_REGISTRY=0x...
export PRIVATE_KEY=0x...

# Run the script
cargo run populate-token-registry