Skip to main content

Email Wallet

Email Wallet is an Ethereum contract wallet that can be controlled by sending emails. The contract validates the authenticity of emails by verifying the ZK Proof of DKIM signature of the email. This ensures email is generated by the user without leaking user's email address on-chain. This idea was first proposed at ICBC2023[1].

Documentation Explanation​

API Documentation: Make calls to the email wallet relayer from a frontend or dapp. This will be the only resource needed for most developers.

Circuit Architecture: In case you want to fork or define your own email parsing logic, you can learn how the in-depth ZK circuits work.

Contract Architecture: To understand each of the smart contracts, the overall architecture, and the compilation pipeline, you can read these docs. If you are just integrating smart contracts into existing deployed contracts, we recommend the Extensions SDK instead.

Relayer Infrastructure: To host your own email wallet relayer, you can follow the guide here to understand the microservices architecture, environment variables, setup, and Docker deployments.

Extensions SDK: Define your own functoinality for email wallet by defining a Solidity function that defines the parsing logic and calls the relevant smart contracts.

Commands that the Email Wallet supports​

  • ✓ Send ETH to email address and Ethereum addresses.
    • Send 1 ETH to friend@domain.com
    • Send 2.5 ETH to 0xf39fd6e51aad88f6f4ce6ab8827279cfffb92266
  • ✓ Send ERC20 to email address and Ethereum addresses.
    • Send 1.5 DAI to friend@skiff.com
    • Send 21.14 DAI to 0xf39fd6e51aad88f6f4ce6ab8827279cfffb92266
  • ✓ Execute any calldata on a target contract
    • Execute 0xba7676a8.....
  • ✓ Install extensions for additional functionalities. Extensions can be developed for any DeFi protocols.
    • Install extension Uniswap
    • Remove extension Uniswap
  • ✓ Use Uniswap extension to swap tokens.
    • Swap 1 ETH to DAI
    • Swap 1 DAI to ETH
  • ✓ Use NFT extension to mint NFTs.
    • NFT Send 1337 of Punks to recipient@domain.com (and more)
  • ✓ Use custom DKIM Registry for complete control.
    • DKIM registry set to 0x1ababab111...
  • ✓ Set email wallet to a new owner. New owner (EOA) can control the wallet by executing any calldata on a target contract.
    • Exit Email Wallet. Set owner to 0x1ababab111...

Features:

  • ✓ No need to install any browser extension or mobile app.
  • ✓ No need to remember any seed phrase or private key.
  • ✓ Operate the wallet by sending human readable emails.
  • ✓ Hide link from an email address to a wallet address.
  • ✓ Pay fee in ERC20 tokens.
  • ✓ Developers can build extensions to add new functionalities.

Security Considerations:

  1. Safety guarantee: if your email domain server does not forge your emails, no one can send assets in your wallet.
  2. Liveness guarantee: if your email domain server does not block your emails and you stores an invitation email that you have received before, you can execute a new transaction on-chain.
  3. Privacy protection against DoS scanning attacks: no adversary can learn an address or existence of the wallet for your email address for free.
    • Note that by sending funds to a user, you may be able learn the wallet address corresponding to a user's email address by scanning the blockchain for that specific amount.

☞ How it works​

Emails you send are (usually) signed using a private key controlled by your email domain server according to a DKIM protocol. This signature is included in the headers section of the email.

Email Wallet verify the DKIM signature of an email to ensure the mail was sent by the user and the contents are not forged. Instead of verifying the signature directly on-chain, a zk proof of signature is created (by a permissionless entity called Relayer) and verified on-chain.

ZK circuit also helps to hide the sender's email address and the recipient's email address on-chain.

Here is how a typical interaction with the wallet looks like:

  • You send an email to your Relayer's email address with a subject like "Send 1 ETH to recipient@gmail.com".
  • The Relayer verifies the DKIM signature and creates a zk proof of email.
  • The ZK circuit extracts the subject, recipient email, timestamp, and other data from the email.
  • Relayer calls the smart contract with the zk proof and the extracted data.
  • Contract computes the subject from the extracted data and matches it with the subject passed by the Relayer.
  • The ZK proof of email is validated on-chain, which also validates the subject.
  • Private data like the sender email, recipient's email in the subject line, is not exposed on-chain.
  • The smart contract executes the transaction and sends 1 ETH to recipient's Email Wallet address.
  • The Relayer wait for the transaction confirmation, and send you and the recipient an email with the transaction details.

This is a simplified flow, but underneath we use many parameters to ensure security and make the Relayer permissionless. You can read a more detailed spec on Saleel's blog.

\

☞ Directory structure​

Email-wallet is a mono-repo that contains the circom circuits, smart contracts, the relayer and a prover server. The frontend code is located in a separate repository at emailwallet.org.

  • packages/circuits contains the circom circuits, tests, scripts to generate zkeys, vkeys, and helper functions to generate circuit inputs.
  • packages/contracts contains the solidity contracts, tests, and scripts to deploy the wallet.
  • packages/relayer contains the relayer code - relayer listens to IMAP server, generate proof using prover server, and call the contract.
  • packages/prover contains the prover server code - prover server receives generates ZK proof for all circuits based on the inputs received from the relayer.
  • packages/utils contains helper functions to help parse emails, and prove circuits.
  • packages/subgraph indexes events generated by circuits- mainly used by the Relayer for PSI communication.
  • packages/scripts contains scripts to generate data for the registry contracts.
/packages
├── /circuits
├──── /src              # Circom circuits.
├──── /build            # Compiled circuits.
├──── /helpers          # Helper functions to generate circuit input.
├──── /scripts          # CLI scripts to generate input, zkeys.
├──── /test             # Circom tests for circuit
├
├── /contracts
├──── /src              # Solidity contracts.
├──── /test             # Solidity tests for contracts.
├──── /script           # Scripts to deploy wallet.
├
├── /relayer
├──── /src              # Relayer code.
├──── /eml_templates    # eml templates.
saved here.
├── /prover             # Prover server code.
├
├── /scripts            # scripts for registry contracts
├
├── /utils
├──── /src              # Helper functions for email parsing, proving circuits, etc.
├
├── /subgraph          # indexing and querying events generated by circuits.


To build the docs

In directory docs/, run:

cargo install mdbook

And to serve the website:

mdbook serve

References​

  1. S. Suegami and K. Shibano, "Contract Wallet Using Emails," 2023 IEEE International Conference on Blockchain and Cryptocurrency (ICBC), Dubai, United Arab Emirates, 2023, pp. 1-2, doi: 10.1109/ICBC56567.2023.10174932.

☆ Built using zk-email ☆