Added npm package READMEs

docs/zkEmailDocs/Package Overviews/README.md

@@ -19,6 +19,21 @@ Key considerations:
 - It processes DKIM headers and employs Regex for pattern matching in emails.
 - By default, inputs are kept private unless stated otherwise, while outputs are always made public.
 
+
+## zk-email/contracts
+
+The @zk-email/contracts package contains the main contract of the SDK, `DKIMRegistry.sol`. This Solidity contract serves as a registry for storing the hash of the DomainKeys Identified Mail (DKIM) public key for each domain.
+
+Key considerations:
+- The `DKIMRegistry.sol` contract maintains a record of the DKIM key hashes for public domains. The hash is calculated by taking the Poseidon hash of the DKIM key split into 9 chunks of 242 bits each.
+
+- The contract provides functions for registering, revoking, and validating DKIM public key hashes.
+
+- It emits events upon successful registration (`DKIMPublicKeyHashRegistered`) and revocation (`DKIMPublicKeyHashRevoked`) of DKIM public key hashes.
+
+
+- The `DKIMRegistry` contract is used in conjunction with the `EmailVerifier` circuit to verify emails. The `EmailVerifier` circuit checks the DKIM signature of an email against the DKIM public key hash stored in the `DKIMRegistry` contract for the email's domain.
+
 ## **Circuit Helpers**
 The `circuits` directory includes a `helpers` folder, which houses a variety of Circom helper templates. These templates are instrumental in constructing your primary circuit file.
 
@@ -37,7 +52,7 @@ It includes two templates:
 To use these templates in your Circom program, you need to import the base64.circom file. Here's how you can do it:
 
 ```bash
-include "path/to/base64.circom";
+include "path/to/base64.circom"
 ```
 
 Replace "path/to/base64.circom" with the actual path to the base64.circom file.
@@ -145,7 +160,7 @@ Outputs:
 To use these templates in your Circom program, you need to import the extract.circom file. Here's how you can do it:
 
 ```bash
-include "path/to/extract.circom";
+include "path/to/extract.circom"
 ```
 
 Replace "path/to/extract.circom" with the actual path to the extract.circom file.

packages/circuits/README.md

@@ -0,0 +1,84 @@
+## Overview
+The `circuits` package is a collection of helper templates located in the `helpers` folder. These templates are essential for building your primary circuit file.
+
+Additionally, the package includes an `email-verifier.circom` file. This file is a standard template designed for email verification, and it can be tailored to meet specific application requirements.
+
+## Circuit Helpers Overview
+The `circuits` package includes 10 helper templates that are instrumental in constructing the `email-verifier.circom` file. Here's a brief overview of each:
+
+### base64.circom
+
+This template decodes base64 encoded data within arithmetic circuits. It comprises two templates: `Base64Lookup` (converts a base64 character into its 6-bit binary representation) and `Base64Decode` (decodes a base64 encoded string into binary data).
+
+### extract.circom
+
+This file provides a set of utilities for manipulating signal arrays within arithmetic circuits.
+
+ It includes several templates for packing and shifting signals, such as `PackBytes`, `VarShiftLeft`, `VarShiftMaskedStr`, `ClearSubarrayAfterEndIndex`, `ShiftAndPack`, and `ShiftAndPackMaskedStr`.
+
+### rsa.circom
+
+This template implements the RSA (Rivest–Shamir–Adleman) algorithm, a cornerstone of public key cryptography. It includes templates for key generation, encryption, and decryption.
+
+### sha.circom
+This template implements the SHA (Secure Hash Algorithm) family of cryptographic hash functions, which take an input and return a fixed-size string of bytes, typically a message digest.
+
+### bigint.circom
+
+This template provides functionality for performing arithmetic operations on big integers, such as addition and subtraction modulo 2^n.
+
+### bigint_func.circom
+
+This template offers utility functions for handling big integers within arithmetic circuits, performing various mathematical operations on large numbers represented across multiple registers.
+
+### sha256general.circom
+
+This template implements the SHA-256 cryptographic hash function, taking an input signal array representing the message to be hashed and producing an output signal array representing the message digest.
+
+### sha256partial.circom
+
+This template provides a partial implementation of the SHA-256 cryptographic hash function, useful when the initial part of the message to be hashed is known in advance.
+
+### fp.circom
+
+This template provides functionality for performing arithmetic operations in finite fields, fundamental for many cryptographic protocols.
+
+### utils.circom
+
+This template includes a collection of utility functions used across multiple circuits, such as bit manipulation functions, comparison functions, or conversion functions.
+
+## Overview of email-verifier.circom
+
+The `email-verifier.circom` file is a comprehensive template designed for email verification. It is engineered to process DKIM headers and utilizes Regex for pattern matching within emails.
+
+It imports the `base64.circom`, `rsa.circom`, `sha.circom`, and `extract.circom` files.
+
+### Parameters
+
+The `EmailVerifier` template accepts several parameters:
+
+- `max_header_bytes` and `max_body_bytes`: Define the maximum size of the email header and body, respectively. These values should be multiples of 64.
+- `n` and `k`: Represent the big integer parameters for RSA. The number is divided into `k` chunks, each of size `n` bits.
+- `ignore_body_hash_check`: A flag that, when set, allows the body hash check to be skipped. This is useful for projects that do not require verification of the body contents.
+
+### Input Signals
+
+The template also accepts several input signals:
+
+- `in_padded`: Represents the prehashed email data, which includes up to 512 + 64 bytes of padding pre SHA256, and is padded with 0s at the end after the length.
+- `pubkey`: The RSA public key, verified with a smart contract + DNSSEC proof. It's divided into `k` parts, each of `n` bits.
+- `signature`: The RSA signature, divided into `k` parts, each of `n` bits.
+- `in_len_padded_bytes`: The length of the input email data including the padding, which will inform the SHA256 block length.
+
+### Operations
+
+The template performs several operations:
+
+- Calculates the SHA256 hash of the header, which is the "base message" that is RSA signed.
+- Verifies the RSA signature.
+- If `ignore_body_hash_check` is not set to 1, it extracts the body hash from the header and verifies that the hash of the body matches the hash in the header.
+- Calculates the Poseidon hash of the DKIM public key and produces it as an output. This can be used to verify the public key is correct in a contract without requiring the actual key.
+
+
+
+For a more in-depth understanding, please visit our zk Email Verify repository at https://github.com/zkemail/zk-email-verify.

packages/contracts/README.md

@@ -0,0 +1,29 @@
+## DKIMRegistry.sol
+
+The `DKIMRegistry.sol` is a Solidity contract that serves as a registry for storing the hash of the DomainKeys Identified Mail (DKIM) public key for each domain. This contract is part of the `@zk-email/contracts` package.
+
+### Overview
+
+The `DKIMRegistry` contract maintains a record of the DKIM key hashes for public domains. The hash is calculated by taking the Poseidon hash of the DKIM key split into 9 chunks of 242 bits each.
+
+The contract provides methods to set and revoke DKIM public key hashes, and to check if a DKIM public key hash is valid. The contract also emits events when a DKIM public key hash is registered or revoked.
+
+### Key Features
+
+* **DKIM Public Key Hash Registration:** The `setDKIMPublicKeyHash` function allows the contract owner to register a new DKIM public key hash for a domain. The function emits a `DKIMPublicKeyHashRegistered` event upon successful registration.
+
+* **DKIM Public Key Hash Revocation:** The `revokeDKIMPublicKeyHash` function allows the contract owner to revoke a DKIM public key hash. The function emits a `DKIMPublicKeyHashRevoked` event upon successful revocation.
+
+* **DKIM Public Key Hash Validation:** The `isDKIMPublicKeyHashValid` function checks if a DKIM public key hash is valid for a given domain. It returns false if the hash has been revoked or if it does not exist for the domain.
+
+* **Batch DKIM Public Key Hash Registration:** The `setDKIMPublicKeyHashes` function allows the contract owner to register multiple DKIM public key hashes for a domain at once.
+
+### Security
+
+The contract extends the `Ownable` contract from the OpenZeppelin contracts library, which provides basic access control mechanisms. Only the contract owner can register or revoke DKIM public key hashes.
+
+### Usage
+
+The `DKIMRegistry` contract is used in conjunction with the `EmailVerifier` circuit to verify emails. The `EmailVerifier` circuit checks the DKIM signature of an email against the DKIM public key hash stored in the `DKIMRegistry` contract for the email's domain.
+
+For a more in-depth understanding, please visit our zk Email Verify repository at https://github.com/zkemail/zk-email-verify.

packages/helpers/README.md

@@ -0,0 +1,24 @@
+## Overview
+The `helpers` package is a comprehensive SDK, written in TypeScript, that provides utility functions to facilitate various tasks within the application. Here's a brief overview of each module:
+
+**binaryFormat.ts**: This module offers utility functions for converting between different binary formats, including string-to-byte, byte-to-string conversions, and packing bytes into N bytes.
+
+**constants.ts**: This module defines various constants used throughout the application, including the Circom field modulus, maximum header and body padded bytes, and constants for RSA group signature verification.
+
+**fast-sha256.ts**: This module provides a high-performance implementation of the SHA-256 hash function, used for hashing data in performance-critical sections of the application.
+
+**input-helpers.ts**: This module offers utility functions for handling user input, including inserting a character before a newline in a Uint8Array, converting a raw email to a buffer, and finding an index in a Uint8Array.
+
+**merkle.ts**: This module provides utility functions for working with Merkle trees, including building a Merkle tree and getting a Merkle proof.
+
+**poseidonHash.ts**: This module provides an implementation of the Poseidon hash function, used for hashing data in parts of the application that require a cryptographic hash function.
+
+**rsa.ts**: This module offers utility functions for working with RSA encryption, including a function for verifying RSA signatures.
+
+**shaHash.ts**: This module provides an implementation of the SHA hash function, including functions for hashing data, partially hashing data, and padding data for SHA-256.
+
+**sshFormat.ts**: This module offers utility functions for working with SSH formatted data, including unpacking SSH bytes, getting a raw signature from an SSH signature, and converting an SSH signature to a public key.
+
+**dkim/index.ts**: This module provides utility functions for working with DKIM signatures, including functions for verifying DKIM signatures, and types related to DKIM verification results and options.
+
+For a more in-depth understanding, please visit our zk Email Verify repository at https://github.com/zkemail/zk-email-verify.