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:
- Safety guarantee: if your email domain server does not forge your emails, no one can send assets in your wallet.
- 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.
- 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
- 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 ☆