@zk-email/circuits

The circuits package exports the circom circuits needed for building on ZK Email.

All circuits in this package are libraries that can be imported to your circom project (i.e this package does not contain a main circuit).

Installation

yarn add @zk-email/circuits

EmailVerifier Circuit

EmailVerifier is the primary circuit exported from @zk-email/circuits which is used for proving the signature of the input email is valid.

Usage:

Import to your circuit file like below.

include "@zk-email/circuits/email-verifier.circom";

• Parameters:

  • maxHeadersLength: Maximum length for the email header.
  • maxBodyLength: Maximum length for the email body.
  • n: Number of bits per chunk the RSA key is split into. Recommended to be 121.
  • k: Number of chunks the RSA key is split into. Recommended to be 17.
  • ignoreBodyHashCheck: Set 1 to skip body hash check in case data to prove/extract is only in the headers.
  • enableHeaderMasking: Set 1 to turn on header masking.
  • enableBodyMasking: Set 1 to turn on body masking.
  • removeSoftLineBreaks: Set 1 to remove soft line breaks (=\r\n) from the email body.

  Note: We use these values for n and k because their product (n * k) needs to be more than 2048 (RSA constraint) and n has to be less than half of 255 to fit in a circom signal.

• Input Signals:

  • emailHeader[maxHeadersLength]: Email headers that are signed (ones in DKIM-Signature header) as ASCII int[], padded as per SHA-256 block size.
  • emailHeaderLength: Length of the email header including the SHA-256 padding.
  • pubkey[k]: RSA public key split into k chunks of n bits each.
  • signature[k]: RSA signature split into k chunks of n bits each.
  • emailBody[maxBodyLength]: Email body after the precomputed SHA as ASCII int[], padded as per SHA-256 block size.
  • emailBodyLength: Length of the email body including the SHA-256 padding.
  • bodyHashIndex: Index of the body hash bh in the emailHeader.
  • precomputedSHA[32]: Precomputed SHA-256 hash of the email body till the bodyHashIndex.
  • headerMask[maxHeadersLength]: Mask to be applied on the emailHeader.
  • bodyMask[maxBodyLength]: Mask to be applied on the emailBody.
  • decodedEmailBody[maxBodyLength]: Decoded email body after removing soft line breaks.

  Output Signal

  • pubkeyHash: Poseidon hash of the pubkey - Poseidon(n/2)(n/2 chunks of pubkey with k*2 bits per chunk).
  • maskedHeader[maxHeadersLength]: Masked email header.
  • maskedBody[maxBodyLength]: Masked email body.

Libraries

This section contains a template library located in the @zk-email/circuits/lib directory. These templates are important for building your main circuit (EmailVerifier).

These templates are used in the EmailVerifier circuit, and can also be used in a wide range of ZK projects, even those not directly related to ZK Email.

lib/rsa.circom

• Source
• Parameters
  • n: Number of bits per chunk the modulus is split into. Recommended to be 121.
  • k: Number of chunks the modulus is split into. Recommended to be 17.
• Inputs:
  • message[k]: The message that was signed.
  • signature[k]: The signature to verify.
  • modulus[k]: The modulus of the RSA key (pubkey).

lib/sha.circom

• Source
• Parameters
  • maxByteLength: Maximum length of the input bytes.
• Inputs:
  • paddedIn[maxByteLength]: Message to hash padded as per the SHA256 specification.
  • paddedInLength: Length of the message in bytes including padding.
• Output:
  • out[256]: The 256-bit hash of the input message.

• Source
• Parameters
  • maxByteLength: Maximum length of the input bytes.
• Inputs:
  • paddedIn[maxByteLength]: Message to hash padded as per the SHA256 specification.
  • paddedInLength: Length of the message in bytes including padding.
  • preHash[32]: The precomputed state of the hash.
• Output:
  • out[256]: The 256-bit hash of the input message.

lib/base64.circom

• Source
• Inputs:
  • in: The base64 encoded string to decode.
  • N: The expected length of the output binary data.
• Outputs:
  • out: The decoded binary data.

Utils

This section provides an overview of utility circom templates available in the @zk-email/circuits/utils directory. These templates assist in the construction of ZK circuits for various applications beyond the core ZK Email functionalities.

Important: When using these templates outside of zk-email, please ensure you read the assumptions on the input signals that are documented above each template source code. You would need to constrain the inputs accordingly before you pass them to these utility circuits.

utils/array.circom

• Source
• Parameters:
  • maxArrayLen: The maximum number of elements in the input array.
• Inputs:
  • in: The input array.
  • startIndex: The index from which the array should be zero-padded.

• Source
• Parameters:
  • maxArrayLen: The number of elements in the array.
• Inputs:
  • in: The input array.
  • index: The index of the element to select.
• Output:
  • out: The selected element.

• Source
• Parameters:
  • n: The number of elements in the array.
• Inputs:
  • nums: The input array.
• Output:
  • sum: The sum of the input array.

• Source
• Parameters:
  • maxArrayLen: The maximum number of bytes in the input array.
  • maxSubArrayLen: The maximum number of integers in the output array.
• Inputs:
  • in: The input byte array.
  • startIndex: The start index of the subarray.
  • length: The length of the subarray.
• Output:
  • out: Array of maxSubArrayLen size, items starting from startIndex, and items after length set to zero.

• Source
• Parameters:
  • maxArrayLen: The maximum length of the input array.
  • maxOutArrayLen: The maximum length of the output array.
• Inputs:
  • in: The input array.
  • shift: The number of indices to shift the array to the left.
• Output:
  • out: Shifted subarray.

utils/bytes.circom

• Source
• Inputs:
  • in: The input byte array.
  • maxBytes: The maximum number of bytes in the input array.
• Outputs:
  • out: The output integer array after packing.

• Source
• Inputs:
  • in: The input byte array.
  • startIndex: The start index of the sub-array.
  • length: The length of the sub-array.
  • maxArrayLen: The maximum number of elements in the input array.
  • maxSubArrayLen: The maximum number of elements in the sub-array.
• Outputs:
  • out: The output integer array after packing the sub-array.

• Source
• Inputs:
  • in: The input byte array - big-endian digit string of out.
  • n: The number of bytes in the input array.
• Outputs:
  • out: The output integer after conversion.

• Source
• Inputs:
  • in: An input signal, expected to be 0 or 1.
• Outputs:
  • None. This template will throw an assertion error if the input is not binary.

• Source
• Parameters:
  • maxLength: The maximum length of the input and mask arrays.
• Inputs:
  • in: An array of signals representing the body to be masked.
  • mask: An array of signals representing the binary mask.
• Outputs:
  • out: An array of signals representing the masked input.

utils/constants.circom

• Source
• Constants:
  • EMAIL_ADDR_MAX_BYTES(): Returns the maximum byte size for an email, defined as 256.
  • DOMAIN_MAX_BYTES(): Returns the maximum byte size for a domain, defined as 255.
  • MAX_BYTES_IN_FIELD(): Returns the maximum number of bytes that can fit in a field, defined as 31.

utils/functions.circom

• Source
• Inputs:
  • a: The input number for which the ceil(log2()) needs to be calculated.
• Outputs:
  • Returns ceil(log2()) of the input number.

utils/hash.circom

• Source
• Inputs:
  • in[chunkSize]: The input array of chunkSize elements.
  • bytesPerChunk: Number of bits in each chunk.
  • chunkSize: Number of chunks in input.
• Outputs:
  • out: Poseidon hash of input where consecutive elements are merged.

utils/regex.circom

• Source
• Inputs:
  • in: The input byte array.
  • startIndex: The index of the start of the reveal part in the input array.
  • maxArrayLen: The maximum length of the input array.
  • maxRevealLen: The maximum length of the reveal part.
• Outputs:
  • out: The revealed data array that matches the regular expression.

• Source
• Inputs:
  • in: The input byte array.
  • startIndex: The index of the start of the reveal part in the input array.
  • maxArrayLen: The maximum length of the input array.
  • maxRevealLen: The maximum length of the reveal part.
• Outputs:
  • out: The packed integer array after processing the reveal data.

Helpers

This section contains helper circom templates in @zk-email/circuits/helpers that you can use to build on top of ZK Email.

helpers/email-nullifier.circom

• Source
• Parameters:
  • bitPerChunk: The number of bits per chunk the signature is split into.
  • chunkSize: The number of chunks the signature is split into.
• Inputs:
  • signature[chunkSize]: The signature of the email.
• Output:
  • out: The email nullifier.

helpers/remove-soft-line-breaks.circom

• Source
• Parameters:
  • maxLength: The maximum length of the input strings.
• Inputs:
  • encoded[maxLength]: An array of ASCII values representing the input string with potential soft line breaks.
  • decoded[maxLength]: An array of ASCII values representing the expected output after removing soft line breaks.
• Outputs:
  • isValid: A signal that is 1 if the decoded input correctly represents the encoded input with soft line breaks removed, 0 otherwise.