ZK-Email Wallet Documentation

The ZK-Email Wallet is a unique type of non-custodial cryptocurrency wallet that is managed via email. This document provides an overview of its features and future development plans. You can try our demo at https://emailwallet.org, and view broader docs at emailwallet.org/docs.

For the source code of the contracts, relayers, and other infrastructure, see the main repo here: github.com/zkemail/email-wallet.

Features

The ZK-Email Wallet currently supports the following functions:

• ETH Transfers: Users can transfer ETH from standard ETH addresses to email wallets, from email wallets to standard ETH addresses, and between email wallets.
• ERC20 Transfers
• Native swaps on Uniswap
• Changing your DKIM Registry
• Transporting to another relayer
• Sign for any Safe{Wallet}

Currently, the wallet uniquely provides the following features:

• Send money to people without accounts: Because transfers are authorized by an email address, you can mass send money or assets to people who have never used email wallet before but do have an email address. If the email address does not claim the money in 1 year (or another preset time), it can be returned to the sender. This avoids problems with dead email addresses or transactions the recipient does not want to recieve.
• No user interaction with Ethereum: By delegating control of their account to an account abstraction wallet under their email provider (which they already trust with their bank account recovery and social media password reset control), users can avoid ever having to think about private keys or the complexity of the crypto ecosystem.

How It Works (User Perspective)

For each transaction, you send an email. This email can be formatted for you on https://emailwallet.org, or you can simply email "[email protected]" with a subject like "Send 2 DAI to [email protected]". The relayer will automatically deploy a new wallet for you (if you don't have one) that can only be authorized via emails from you. If you want to test without any Goerli assets, you can start trying to send TEST token like "Send 2 TEST to [email protected]", which will automatically spend from a free 10 token starting balance.

This money is sent to a smart contract wallet authorized to your friend's email address (in this case, [email protected]), meaning only emails from them can spend the money. This transaction occurs in wallets on-chain, and neither the relayer nor us can steal your funds (since we can't generate a fake email from you with the correct cryptographic signatures, only your email provider can). Currently, transfers happen on Goerli -- dm us if you need free Goerli ETH/DAI/USDC to test it out!

If you want to mass-send to a lot of email addresses at once, right now you have to send one email per transaction.

How It Works (Technical Summary)

All sent emails are typically signed using a private key that is managed by your email domain server via the DKIM protocol. This signature is included in the headers of the email.

The DKIM signature serves to authenticate that the email was indeed sent by you, thereby providing a secure means to manage your wallet. Rather than verifying the signature directly on-chain, a zero-knowledge (zk) proof of the signature is generated by a permissionless entity, known as the relayer, and subsequently verified on-chain. The relayer also masks out all of the email addresses to ensure that they are not published publicly on-chain. This authorizes a transaction only if the email is formatted exactly correctly, or else the entire transaction will revert.

Below is an illustration of a standard interaction with the wallet:

1. An email is sent to the Relayer's email address with a subject such as "Send 1 ETH to [email protected]".
2. The Relayer authenticates the DKIM signature and generates a zk proof of the email.
3. The ZK circuit validates the subject's regular expression, the recipient's email address, and the amount to be transferred.
4. Sensitive data, such as the sender's email and the recipient's email in the subject line, is not disclosed on-chain.
5. The Relayer generates an Ethereum transaction that mirrors the intended action specified in the subject.
6. The smart contract verifies the ZK Proof and ensures that the subject line corresponds with the transaction.
7. The smart contract executes the transaction, transferring 1 ETH to the recipient's Email Wallet address.
8. The Relayer awaits confirmation of the transaction, and subsequently sends an email to both you and the recipient detailing the transaction.

Note that email addresses are salted via the message ID of your email, so you can always retrieve your own on-chain address without the relayer's help. Neither the email nor email address are on-chain; they are kept private.

For a more detailed technical breakdown of the cryptographic technology used in emails, read the technical blog post behind zk-email! For a more in-depth technical breakdown of our code, read through our Github repository! For a detailed breakdown of the protocol, read through our presentation slides.

Installation and Running

Copy .env.example to .env and fill in the Alchemy API key, and include your deployed relayer API URL (ours is included as an example).

yarn
yarn dev

We use this command to deploy on Render:

sed -i 's|// output: "export",|output: "export",|' next.config.js && yarn; yarn build; yarn next export; ls -alhk && ls ./out

and set the publish directory to out/.

Future Development

In the next month or two, we intend to prioritize:

• KYC-Free Onboarding and Offboarding: We intend to build a native integration with ZK P2P, which uses the same base email proving technology (prove.email) to on and offramp via Venmo.
• Bulk Sending: We intend to include bulk-sending a list of amounts to a list of email addresses, in one email or transaction.
• 2FA Ability: By adding ERC 1271 signatures, enable the ability to use your email wallet as a 2FA method for any Gnosis Safe.