mirror of
https://github.com/zkemail/zk-email-verify.git
synced 2026-01-09 21:48:14 -05:00
Updated docs to be concise
This commit is contained in:
Metachaser24
@@ -1,4 +1,4 @@
|
||||
# @zk-email/circuits Package Overview
|
||||
# @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).
|
||||
@@ -12,7 +12,6 @@ yarn add @zk-email/circuits
|
||||
|
||||
<br />
|
||||
|
||||
|
||||
## EmailVerifier Circuit
|
||||
|
||||
[`EmailVerifier`](./email-verifier.circom "Email Verifier Circuit") is the primary circuit exported from `@zk-email/circuits` which is used for proving the signature of the input email is valid.
|
||||
@@ -47,11 +46,11 @@ include "@zk-email/circuits/email-verifier.circom";
|
||||
<br/>
|
||||
|
||||
## **Libraries**
|
||||
The package also exports circuits for some popular cryptographic protocols.
|
||||
This section contains a template library located in the `@zk-email/circuits/lib` directory. These templates are important for building your main circuit (EmailVerifier).
|
||||
|
||||
They are used in `EmailVerifier` circuit for signature verification, but can also be used independently in other ZK projects (even when not using ZK Email).
|
||||
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.
|
||||
|
||||
### `@zk-email/circuits/lib/rsa.circom`
|
||||
### `lib/rsa.circom`
|
||||
|
||||
<details>
|
||||
<summary>
|
||||
@@ -70,7 +69,7 @@ RSAVerifier65537: Verifies RSA signatures with exponent 65537.
|
||||
</details>
|
||||
|
||||
|
||||
### `@zk-email/circuits/lib/sha.circom`
|
||||
### `lib/sha.circom`
|
||||
|
||||
<details>
|
||||
<summary>
|
||||
@@ -107,139 +106,63 @@ Sha256BytesPartial: Computes the SHA256 hash of input bytes with a precomputed s
|
||||
</details>
|
||||
|
||||
|
||||
<details>
|
||||
<summary>
|
||||
Sha256General: A modified version of the SHA256 circuit that allows specified length messages up to a max to all work via array indexing on the SHA256 compression circuit.
|
||||
</summary>
|
||||
|
||||
- **[Source](lib/sha.circom#L82-L202)**
|
||||
- **Parameters**
|
||||
- `maxBitLength`: Maximum length of the input bits.
|
||||
- **Inputs**:
|
||||
- `paddedIn[maxBitLength]`: Message to hash padded as per the SHA256 specification.
|
||||
- `paddedInLength`: Length of the message in bits including padding.
|
||||
- **Output**:
|
||||
- `out[256]`: The 256-bit hash of the input message.
|
||||
|
||||
</details>
|
||||
|
||||
### `lib/base64.circom`
|
||||
|
||||
<details>
|
||||
<summary>
|
||||
Sha256Partial: Calculates the SHA256 hash of a message with a precomputed state.
|
||||
Base64Decode: Decodes a base64 encoded string into binary data.
|
||||
</summary>
|
||||
|
||||
- **[Source](lib/sha.circom#L211-L299)**
|
||||
- **Parameters**
|
||||
- `maxBitLength`: Maximum length of the input bits.
|
||||
- **[Source](lib/base64.circom#L11-L61)**
|
||||
- **Inputs**:
|
||||
- `paddedIn[maxBitLength]`: Message to hash padded as per the SHA256 specification.
|
||||
- `paddedInLength`: Length of the message in bits including padding.
|
||||
- `preHash[256]`: The precomputed state of the hash.
|
||||
- **Output**:
|
||||
- `out[256]`: The 256-bit hash of the input message.
|
||||
|
||||
</details>
|
||||
|
||||
|
||||
---
|
||||
|
||||
|
||||
|
||||
### base64.circom
|
||||
This component decodes base64 encoded data within arithmetic circuits, focusing on the conversion of base64 encoded strings into binary data.
|
||||
|
||||
**[`Base64Decode`](https://github.com/zkemail/zk-email-verify/blob/v4/packages/circuits/lib/base64.circom#L11-L61)**: Decodes a base64 encoded string into binary data.
|
||||
- **Inputs**:
|
||||
- `in`: The base64 encoded string to decode.
|
||||
- `N`: The expected length of the output binary data.
|
||||
- `in`: The base64 encoded string to decode.
|
||||
- `N`: The expected length of the output binary data.
|
||||
- **Outputs**:
|
||||
- `out`: The decoded binary data.
|
||||
- `out`: The decoded binary data.
|
||||
|
||||
- **Usage**:
|
||||
- To decode base64 encoded data, include the `Base64Decode` template in your circuit and provide the encoded string as input. The template will output the decoded binary data.
|
||||
</details>
|
||||
|
||||
## 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.
|
||||
|
||||
### `utils/array.circom`
|
||||
|
||||
## **Utilities**
|
||||
These utility templates in circom are used to support the creation of zk proofs, extending beyond the confines of our predefined code.
|
||||
|
||||
### array.circom
|
||||
|
||||
**[` ItemAtIndex`](https://github.com/zkemail/zk-email-verify/blob/v4/packages/circuits/utils/array.circom#L15-L46 "ItemAtIndex")**: This template selects an item at a given index from the input array. It is based on the QuinSelector from MACI.
|
||||
|
||||
- **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.
|
||||
- **Usage**:
|
||||
- To select an item from an array at a specific index, use the `ItemAtIndex` template by specifying the array and the index.
|
||||
|
||||
**[`CalculateTotal`](https://github.com/zkemail/zk-email-verify/blob/v4/packages/circuits/utils/array.circom#L54-L67 "CalculateTotal")**: This template calculates the sum of an array.
|
||||
|
||||
- **Inputs**:
|
||||
- `nums`: The input array.
|
||||
- **Output**:
|
||||
- `sum`: The sum of the input array.
|
||||
- **Usage**:
|
||||
- To calculate the total sum of an array, include the `CalculateTotal` template in your circuit and provide the array as input.
|
||||
|
||||
**[`SelectSubArray`](https://github.com/zkemail/zk-email-verify/blob/v4/packages/circuits/utils/array.circom#L80-L104)**: Extracts a segment from an array using a starting index (`startIndex`) and segment length (`length`), zeroing elements outside this range.
|
||||
|
||||
- **Parameters**:
|
||||
- `maxArrayLen`: The upper limit on the byte count within the input array.
|
||||
- `maxSubArrayLen`: The maximum count of integers allowed within the resultant sub-array.
|
||||
- **Inputs**:
|
||||
- `in`: The byte array from which a segment is to be extracted.
|
||||
- `startIndex`: The array index at which the desired segment begins.
|
||||
- `length`: The extent of the segment, defined by the number of elements it encompasses.
|
||||
- **Output**:
|
||||
- `out`: A `maxSubArrayLen`-sized array, populated starting from `startIndex` for the defined `length`, with subsequent elements reset to zero.
|
||||
- **Usage**:
|
||||
- To isolate a segment from an array, the `SelectSubArray` template should be employed, specifying the original array, the commencement index, and the segment length.
|
||||
|
||||
**[`VarShiftLeft`](https://github.com/zkemail/zk-email-verify/blob/v4/packages/circuits/utils/array.circom#L116-L146)**:This template shifts an input array by `shift` indices to the left. The output array length can be reduced by setting `maxOutArrayLen`.
|
||||
|
||||
- **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.
|
||||
- **Usage**:
|
||||
- To shift an array to the left by a specific number of indices, include the `VarShiftLeft` template in your circuit and specify the array and shift amount.
|
||||
|
||||
**[`AssertZeroPadding`](https://github.com/zkemail/zk-email-verify/blob/v4/packages/circuits/utils/array.circom#L154-L172)**: This template asserts that the input array is zero-padded from the given `startIndex`.
|
||||
<details>
|
||||
<summary>
|
||||
AssertZeroPadding: Asserts that the input array is zero-padded from the given `startIndex`.
|
||||
</summary>
|
||||
|
||||
- **[Source](utils/array.circom#L154-L172)**
|
||||
- **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.
|
||||
- **Usage**:
|
||||
- To ensure an array is zero-padded from a specific index, use the `AssertZeroPadding` template by specifying the array and start index.
|
||||
</details>
|
||||
|
||||
|
||||
### `utils/bytes.circom`
|
||||
|
||||
### bytes.circom
|
||||
<details>
|
||||
<summary>
|
||||
PackBytes: Packs an array of bytes to numbers that fit in the field.
|
||||
</summary>
|
||||
|
||||
These templates are for converting byte arrays into integer arrays, considering specified packing sizes, and for packing byte arrays to numbers that fit in a field.
|
||||
|
||||
**[`PackBytes`](https://github.com/zkemail/zk-email-verify/blob/v4/packages/circuits/utils/bytes.circom#L28-L60 "PackBytes")**: Packs an array of bytes to numbers that fit in the field.
|
||||
- **[Source](utils/bytes.circom#L28-L60)**
|
||||
- **Inputs**:
|
||||
- `in`: The input byte array.
|
||||
- `maxBytes`: The maximum number of bytes in the input array.
|
||||
- **Outputs**:
|
||||
- `out`: The output integer array after packing.
|
||||
- **Usage**:
|
||||
- To pack byte data to integers, include the `PackBytes` template in your circuit and provide the byte array as input. The template will output the packed integer array.
|
||||
|
||||
**[`PackByteSubArray`](https://github.com/zkemail/zk-email-verify/blob/v4/packages/circuits/utils/bytes.circom#L72-L93 "PackByteSubArray")**: Selects a sub-array from the input array and packs it to numbers that fit in the field.
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary>
|
||||
PackByteSubArray: Selects a sub-array from the input array and packs it to numbers that fit in the field.
|
||||
</summary>
|
||||
|
||||
- **[Source](utils/bytes.circom#L72-L93)**
|
||||
- **Inputs**:
|
||||
- `in`: The input byte array.
|
||||
- `startIndex`: The start index of the sub-array.
|
||||
@@ -248,58 +171,78 @@ These templates are for converting byte arrays into integer arrays, considering
|
||||
- `maxSubArrayLen`: The maximum number of elements in the sub-array.
|
||||
- **Outputs**:
|
||||
- `out`: The output integer array after packing the sub-array.
|
||||
- **Usage**:
|
||||
- To pack a specific sub-array of byte data to integers, use the `PackByteSubArray` template by specifying the inputs, including the start index and length of the sub-array.
|
||||
</details>
|
||||
|
||||
**[`DigitBytesToInt`](https://github.com/zkemail/zk-email-verify/blob/v4/packages/circuits/utils/bytes.circom#L102-L117 "DigitBytesToInt")**: Converts a byte array representing digits to an integer.
|
||||
<details>
|
||||
<summary>
|
||||
DigitBytesToInt: Converts a byte array representing digits to an integer.
|
||||
</summary>
|
||||
|
||||
- **[Source](utils/bytes.circom#L102-L117)**
|
||||
- **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.
|
||||
- **Usage**:
|
||||
- To convert a byte array of digit characters into an integer, include the `DigitBytesToInt` template in your circuit and provide the byte array as input. The template will output the corresponding integer.
|
||||
</details>
|
||||
|
||||
### constants.circom
|
||||
|
||||
This file defines a set of constants used across various circom circuits for standardizing sizes and lengths of different data types.
|
||||
### `utils/constants.circom`
|
||||
|
||||
- **[Constants](./utils/constants.circom)**:
|
||||
<details>
|
||||
<summary>
|
||||
Constants: Defines a set of constants used across various circom circuits for standardizing sizes and lengths of different data types.
|
||||
</summary>
|
||||
|
||||
- **[Source](utils/constants.circom)**
|
||||
- **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.
|
||||
|
||||
### functions.circom
|
||||
|
||||
This file contains utility functions that are used across various circom circuits for performing common mathematical and logical operations.
|
||||
|
||||
- **[`log2Ceil`](https://github.com/zkemail/zk-email-verify/blob/v4/packages/circuits/utils/functions.circom#L2-L10 "log2Ceil")**: Calculates the ceiling of the base 2 logarithm of a given number.
|
||||
- **Inputs**:
|
||||
- `a`: The input number for which the base 2 logarithm ceiling is to be calculated.
|
||||
- **Outputs**:
|
||||
- Returns the smallest integer greater than or equal to the base 2 logarithm of the input number.
|
||||
- **Usage**:
|
||||
- To calculate the ceiling of the base 2 logarithm of a number, include the `log2Ceil` function in your circuit and provide the number as input. The function will return the calculated value.
|
||||
</details>
|
||||
|
||||
|
||||
### hash.circom
|
||||
### `utils/functions.circom`
|
||||
|
||||
**[`PoseidonLarge`](https://github.com/zkemail/zk-email-verify/blob/v4/packages/circuits/utils/hash.circom#L13-L37 "PoseidonLarge")**: Circuit to calculate Poseidon hash of inputs more than 16.
|
||||
<details>
|
||||
<summary>
|
||||
log2Ceil: Calculates the ceiling of the base 2 logarithm of a given number.
|
||||
</summary>
|
||||
|
||||
- **[Source](utils/functions.circom#L2-L10)**
|
||||
- **Inputs**:
|
||||
- `a`: The input number for which the base 2 logarithm ceiling is to be calculated.
|
||||
- **Outputs**:
|
||||
- Returns the smallest integer greater than or equal to the base 2 logarithm of the input number.
|
||||
</details>
|
||||
|
||||
|
||||
### `utils/hash.circom`
|
||||
|
||||
<details>
|
||||
<summary>
|
||||
PoseidonLarge: Circuit to calculate Poseidon hash of inputs more than 16.
|
||||
</summary>
|
||||
|
||||
- **[Source](utils/hash.circom#L13-L37)**
|
||||
- **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.
|
||||
- **Usage**:
|
||||
- To calculate a Poseidon hash for large inputs, include the `PoseidonLarge` template in your circuit and provide the necessary inputs. The template will output the Poseidon hash of the input.
|
||||
</details>
|
||||
|
||||
|
||||
### regex.circom
|
||||
### `utils/regex.circom`
|
||||
|
||||
This file contains templates for performing operations related to regular expressions on byte arrays. These templates allow for selecting and packing parts of byte arrays that match specific patterns defined by regular expressions.
|
||||
<details>
|
||||
<summary>
|
||||
SelectRegexReveal: Selects the reveal part of a byte array that matches a regular expression.
|
||||
</summary>
|
||||
|
||||
**[`SelectRegexReveal`](https://github.com/zkemail/zk-email-verify/blob/v4/packages/circuits/utils/regex.circom#L15-L50 "SelectRegexReveal")**: Selects the reveal part of a byte array that matches a regular expression.
|
||||
- **[Source](utils/regex.circom#L15-L50)**
|
||||
- **Inputs**:
|
||||
- `in`: The input byte array.
|
||||
- `startIndex`: The index of the start of the reveal part in the input array.
|
||||
@@ -307,10 +250,14 @@ This file contains templates for performing operations related to regular expres
|
||||
- `maxRevealLen`: The maximum length of the reveal part.
|
||||
- **Outputs**:
|
||||
- `out`: The revealed data array that matches the regular expression.
|
||||
- **Usage**:
|
||||
- To extract a specific part of a byte array that matches a regular expression, use the `SelectRegexReveal` template by specifying the inputs, including the start index of the reveal part.
|
||||
</details>
|
||||
|
||||
**[`PackRegexReveal`](https://github.com/zkemail/zk-email-verify/blob/v4/packages/circuits/utils/regex.circom#L60-L77 "PackRegexReveal")**: Packs the reveal data from a regex match into an integer array.
|
||||
<details>
|
||||
<summary>
|
||||
PackRegexReveal: Packs the reveal data from a regex match into an integer array.
|
||||
</summary>
|
||||
|
||||
- **[Source](utils/regex.circom#L60-L77)**
|
||||
- **Inputs**:
|
||||
- `in`: The input byte array.
|
||||
- `startIndex`: The index of the start of the reveal part in the input array.
|
||||
@@ -318,7 +265,27 @@ This file contains templates for performing operations related to regular expres
|
||||
- `maxRevealLen`: The maximum length of the reveal part.
|
||||
- **Outputs**:
|
||||
- `out`: The packed integer array after processing the reveal data.
|
||||
- **Usage**:
|
||||
- To pack the reveal data from a regular expression match into integers, use the `PackRegexReveal` template by specifying the inputs, including the start index of the reveal part.
|
||||
</details>
|
||||
|
||||
## 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`
|
||||
|
||||
<details>
|
||||
|
||||
<summary>
|
||||
EmailNullifier: Calculates the email nullifier using Poseidon hash.
|
||||
</summary>
|
||||
|
||||
- **[Source](helpers/email-nullifier.circom#L1-L18)**
|
||||
- **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.
|
||||
</details>
|
||||
|
||||
|
||||
|
||||
Reference in New Issue
Block a user