Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

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

A smart contract wallet controlled using email
https://github.com/zkemail/email-wallet

Last synced: 3 months ago
JSON representation

A smart contract wallet controlled using email

Awesome Lists containing this project

README 

        
# Email Wallet



A smart contract wallet controlled using emails.



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.



For documentation on our email wallet extension click [here](https://github.com/zkemail/email-wallet-sdk)



This is first proposed at [ICBC2023](https://speakerdeck.com/sorasuegami/icbc2023-contract-wallet-using-emails)[1].



#### Things you can do:



- ✓ Send ETH to email address and Ethereum addresses.

  - `Send 1 ETH to [email protected]`

  - `Send 2.5 ETH to 0xf39fd6e51aad88f6f4ce6ab8827279cfffb92266`



- ✓ Send ERC20 to email address and Ethereum addresses.

  - `Send 1.5 DAI to [email protected]`

  - `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 [email protected]` (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.

- Sender might be able learn the recipient's wallet address by scanning blockchain for the 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 [email protected]".

- 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](https://saleel.xyz/blog/email-wallet/).







## ☞ Directory structure

This is a mono-repo that contains the circom circuits, smart contracts, the relayer and a prover server.



- `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/frontend` contains the UI to generate emails.



```

/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

├

├── /frontend           # UI to generate emails

├

├── /utils

├──── /src              # Helper functions for email parsing, proving circuits, etc.

├

├── /subgraph          # indexing and querying events generated by circuits.



```







## ☞ Building and Running



- Refer to the [circuit docs](./packages/circuits/README.md) for more details on building and testing circuits.

- Refer to the [contract docs](./packages/contracts/README.md) for more details on building and testing contracts.

- Refer to the [relayer docs](./packages/relayer/README.md) for more details on building and running relayer.



#### To build the docs



In directory `docs/`, run:

```

cargo install mdbook

```



And to serve the website:

```sh

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](https://github.com/zkemail/zk-email-verify) ☆