# ZKEmail.nr/ Z-Imburse Halfway Progress Report
NRG#1 Proposal: https://github.com/orgs/noir-lang/discussions/5814

Mach 34 is excited to deliver the half-way report on our work integrating ZKEmail into the Aztec Ecosystem! Our deliverables are split into two categories:
* The [ZKEmail.nr](https://github.com/zkemail/zkemail.nr) SDK for all Aztec/Noir devs to implement to easily prove any type of email in Noir
* The Z-Imburse proactive reimbursement application

We've mostly completed the ZKEmail.nr library already - and we look forward to delivering the Z-Imburse application by DevCon 7. Below is a recap of our progress so far:

## Zkemail.nr
Mach 34 has had the privilege to work with the ZKEmail team to build the official SDK and circuit libraries in the Aztec/ Noir ecosystem. We've worked diligently to mirror the tools and experience given by ZKEmail circom while leveraging the benefits of Noir.

While the [ZKEmail.nr](https://github.com/zkemail/zkemail.nr) library is still in active development, we are proud to share that it is now available in public Early Access! We've proven about a dozen different types of emails so far, and invite you to try the SDK for yourself. Issues and PRs are welcome in the github repository if a specific email is giving you trouble ([ZKEmail.nr GitHub](https://github.com/zkemail/zkemail.nr))

### Official Library Features
[ZKEmail.nr](https://github.com/zkemail/zkemail.nr) has officially been adopted by ZKEmail as the official Noir implementation of ZKEmail! We've taken the [zk-email-verify](https://github.com/zkemail/zk-email-verify) JS input generators and set up a fully featured JS library for generating ZKEmail.nr inputs.

The library can be imported using `yarn add @mach-34/zkemail-nr` for NodeJS and browser environments. It is capable of parsing in emails and extracting all the information you need to verify the DKIM signature over the header and body. It aims at supporting all features provided by ZKEmail Circom. The latest list and status of TODOs is available on GitHub [here](https://github.com/zkemail/zkemail.nr?tab=readme-ov-file#todo).

### Testing
ZKEmail.nr has a set of [basic test cases](https://github.com/zkemail/zkemail.nr/blob/main/js/tests/circuits.test.ts) demonstrating the use of the NPM package `@mach-34/zkemail-nr` (likely eventually moved into the ZKEmail NPM org). These tests drive a set of [example circuits](https://github.com/zkemail/zkemail.nr/tree/main/examples) that currently demonstrate the use of ZKEmail to prove:
* 1024-bit DKIM keys
* 2048-bit DKIM keys
* Partially hashed bodies
We demonstrate proving and verifying ZKEmail.nr circuits both with the Plonk and Honk backends in this test, and largely believe these unit tests are sufficient to get anyone started using the [ZKEmail.nr](https://github.com/zkemail/zkemail.nr/tree/main/js/tests) library.
Find more about the tests here: https://github.com/zkemail/zkemail.nr/tree/main/js/tests

### Contracts
We don't have anything in the official ZKEmail.nr repository- this is something we will certainly add in the near future, but is not an *immediate* priority. We've nonetheless successfully successfully verified various ZKEmail.nr Plonk proofs in the (Base Sepolia) EVM.

Additionally, we've integrated Linode and AWS hosting receipts into Aztec smart contracts. We'll talk more about this process in the Z-Imburse section.

### On Pattern Matching
We have been unenthused with [noir_string_search](https://github.com/noir-lang/noir_string_search) after attempting to use it. We don't yet have access to Regex, and in the interim have defaulted to specifying maximum lengths, expected lengths, and indexes to manually perform pattern matching. We aren't comfortable with the hygiene or security of this practice yet, and will be finalizing our implementation of non-regex searching.

For context, [ZK-Regex](https://github.com/olehmisar/zk-regex) in noir is not yet complete. We intend on integrating regex into ZKEmail.nr as soon as it is available for our use.

### ZKEMail.nr Remaining Work
The only missing requirement is pattern matching, which we describe above.

We do intend on cleaning up the code, perhaps implementing Noir's new metaprogramming to facilitate conditional use of parts of the circuit from a single import rather than having multiple imports for various components of the ZKEmail stack.

Additionally, the upstream [ZK-Email-Verify](https://github.com/zkemail/zk-email-verify/) SDK which parses emails is not capable of handling archived DKIM keys - this presents an issue for use of older emails. ZKEmail actually has a [registry](https://archive.prove.email) of countless older DKIM keys, with a mechanism to reverse engineer keys from emails if you can't find the selector already. We will PR this functionality into ZK-Email-Verify then support it in the ZKEmail.nr JS SDK as well.

We potentially will include EVM and Aztec demo integrations by the delivery date. We are not committing to this, however, and may elect to do this outside of the scope of NRG#1 (but we will definitely do it!). Z-Imburse acts as a defacto demonstration of the Aztec integration anyways.

## Z-Imburse
[Z-Imburse](https://github.com/Mach-34/z-imburse) is a proactive reimbursement tool for crypto-native organizations. We're starting out with cloud hosting costs and travel receipts - two types of reimbursement transactions that DAOs, foundations, and companies in the cryptospace often engage in. The flow is as follows:

1. The organization sets up a Z-Imburse contract instance and funds the escrow with USDC
2. The organization creates an entitlement type - for instance, up to $100/ month that can be claimed from the escrow using an AWS Receipt sent via email
3. The organization gives this entitlement to a recipient address
4. The recipient address can upload their email into the Z-Imburse web app, prove authenticity, and export the amount they paid to AWS that month
5. The Z-Imburse contract constrains the timeframe and allows the recipient to withdraw USDC, up to the max value set by the escrow manager

We've got the absolute minimal PoC of this flow built out so far, and look forward to shipping the MVP in the coming month.

### Email Verifiers
We started with cloud hosting receipts, for which our chosen AWS and Linode were quite small. These verifiers are fairly simple - they check the DKIM signing key is valid for the verifier type and export a date and value of the receipt.

We had to temporarily abandon AWS as the DKIM selectors we had access to were out of date - but as described in the [ZKEmail.nr Remaining Work](#ZKEMailnr-Remaining-Work) section, we can resolve this once we set up the use of archived keys.

Right now, we have a different entrypoint for each verifier. However, we are exploring a conditional selector from a single entrypoint that takes in some of the reusable inputs (mostly the dkim signature) and uses capsules from the PXE to handle the dynamic lengths of email headers and bodies that may be present.

### Testing
We'd originally planned to do most testing in the TXE - however, with the JS input parser for emails, we found it was easier to drive inputs from the PXE. We've set up basic [unit testing](https://github.com/Mach-34/z-imburse/blob/main/tests/escrow.test.ts) to drive the process of creating a Z-Imburse contract, escrowing funds, setting up entitlements, and claiming reimbursements. This testing is pretty barebones at the moment, and while it reflects the base case, we will deliver a complete testing harness by delivery.

### UI
We've created a [skeleton UI](https://github.com/mach-34/zimburse-ui) that encompasses the full UX requirements of the Z-Imburse application, both from escrow managers and grant recipients.

The UI is fully representative of the final UX we will ship for this MVP, but expect it to be far prettier! Additionally, we've made some compromises on UX that would be addressed in a later version - for instance, an escrow manager must create a reimbursement template and select from this set when setting an entitlement for a user where it would be more ergonomic to do this on the fly.

### Remaining Work

#### Making Entitlements Recurring
We were not quite able to get the recurring entitlement flow working in time for the half-way deadline. We have written a (unoptimized) [Date parser](https://github.com/Mach-34/z-imburse/blob/main/contracts/zimburse/src/date_parser.nr), we just need to set up the logic to nullify a note by the month value rather than relying on nullification of the note itself!

#### Adding Flight/ Rideshare Receipts
Z-Imburse additionally should support travel receipts. These are quite a bit more complex than hosting receipts, for numerous reasons:
- Hosting receipts often (not always) are quite simple, but travel receipts have a lot of styling. From our inboxes, just about every travel receipt has a large body with the important sensitive information towards the beginning. This means we need ["Post-Partial Hashing"](#Post-partial-Hashing) to have a reasonably achievable UX
- Escrow managers need to set *exact* matching destinations. Without regex, we can't easily normalize street names (i.e. "Street vs street vs st. vs St."). We may use a conditional check, or we may defer this improvement to the inclusion of ZK-Regex.
- Oftentimes, these emails may be one-way or two-way travel. We may or may not elect to choose to support only one-way travel.
- It is possible to re-issue travel receipts via email upon request to a platform. While this generally is not an issue for spot entitlements, it means that emails could potentially be reused by multiple parties without proper framing of the email nullifier to include the right information (date, location, value, etc).
#### Post-partial Hashing
As mentioned in the ZKEmail.nr section, we've already shipped "partial hashing". However, many emails place the important text at the top, and have relatively static HTML/CSS at the bottom. Large email bodies with the important information, like most of the travel receipts, therefore pose a challenging problem for verification.

Fortunately, the information at the end that we want to skip hashing on the client is not sensitive. While it may leak *what* we are verifying, we can safely enlist a remote prover to finish hashing the email body without revealing the start of the email.

We're still in the process of determining the optimal integration for this, but this is a critical component of delivering a wide range of emails

#### Devnet Integration?
If possible, we'd like to deploy Z-Imburse to the actual Aztec Devnet. This will provide a full simulation of the user experience of privacy preserving reimbursements (or even just the use of ZKEmail on aztec at all)! This one is really up to the appetite of the Aztec team to support.