1. User Experience

1.1 Goal

A user of on-chain apps can authenticate that the user is a correct holder of the email address in the From field and authorize anything described in the Subject field simply by requesting the user to reply to coming emails.

1.2 System Design

  1. A frontend of an on-chain app using our email auth sends a relayer server a request data, of which the form depends on each application.
  2. The relayer sends an email with a specified subject to a specified user’s email address.
  3. The user replies to that email.
  4. The relayer receives the reply, generates its email proof, constructs an email auth message, and calls an entry function of the on-chain app contract.
  5. The app contract calls the auth function of our email auth contract, which can be deployed for each user/wallet.

2. Basic Concepts

2.1 Account Code and Salt

An accountCode is a random integer in a finite scalar field F_r of BN254 curve. It is a private randomness to derive a CREATE2 salt of the user’s ethereum address from the email address. As long as the accountCode is not published, the user can hide the email address from on-chain data. Specifically, the salt accountSalt is defined as accountSalt=poseidonHash(emailAddr|0..0, accountKey,0). The emailAddr|0..0 is zero-padded to be 256 bytes and decomposed into multiple field values on F_r.

2.2 Invitation Code

An invitation code is a hex string of accountCode along with a prefix, contained in any field of the email header to be inherited by its reply, e.g., Message-id and Subject. By confirming that a user sends an email with the invitation code, contracts can ensure that the accountCode is available to that user. It ensures the user’s liveness even when a malicious relayer or another user generate your accountCode because it prevents them from withholding the accountCode. It suggests that the application contract must check that a new user sends an email containing the invitation code before confirming that user’s account.

2.3 Subject Template

A concept of subject template is an array of strings to define the expected subject format. It can use a fixed string containing no space and the following variable matchers.