# Consensys Dilligence Mach 34 Audit Scope

1. Grant Proposal: https://github.com/orgs/noir-lang/discussions/5814
2. Halfway report: https://hackmd.io/sPwcJ2obTFajkCaZ_0I52A
3. Docs Writeup: https://hackmd.io/@IQZ-5dJ4QGGu4K6oX71X7w/BkFZfgCgye

## Code Scope
Consensys Dilligence has expressed that capcity is limited and first priority should be given to ZKEmail.nr

### ZKEmail.nr
1. Commit: [2f81196ac04cd11a921816b52b432bb8c5eb3150](https://github.com/zkemail/zkemail.nr/tree/2f81196ac04cd11a921816b52b432bb8c5eb3150)
2. Loc: 1599

| path0/ | path1/ | Language | LoC (noir) |
|:-----------------------------|:---------------------------------------|:-----------|-------------:|
| js/src | index.ts | ts | 229 |
| | utils.ts | ts | 147 |
| lib/src | partial_hash.nr | noir | 407 |
| | tests/mod.nr | noir | 404 |
| | remove_soft_line_breaks.nr | noir | 208 |
| | headers/email_address.nr | noir | 64 |
| | dkim.nr | noir | 60 |
| | headers/body_hash.nr | noir | 59 |
| | masking.nr | noir | 21 |
| | | | 1599 |

### Z-Imburse
1. Commit: [5f7200342a29b974beb118cf70398b9c8c59a610](https://github.com/Mach-34/z-imburse/tree/5f7200342a29b974beb118cf70398b9c8c59a610)
2. LoC: 1490

| path0/ | path1/ | Language | LoC (noir) |
|:-----------------------------|:------------------------------------|:-----------|-------------:|
| contracts/z_imburse_escrow/ | src/main.nr | noir | 425 |
| | src/types/entitlement_note.nr | noir | 359 |
| | src/verifiers.nr | noir | 75 |
| | src/library_methods/linode.nr | noir | 75 |
| | src/library_methods/entitlements.nr | noir | 58 |
| contracts/z_imburse_registry | src/test/escrow.nr | noir | 498 |
| | | | 1490 |

## Project Focus

### ZKEmail
Be a faithful and (as much as possible) feature complete port of ZKEmail to the Noir langue

1. Noir Features
1. Prove headers signed by 1024-bit and 2048-bit RSA DKIM keys
2. Prove access to header fields, specifically email addresses
3. Prove contents of body by constrained access to body hash from header and matching computation of body hash to signed body hash
4. Provably mask the header or body
5. Remove soft line breaks from QP-encoded body
2. JS Input Gen library for driving Noir contracts
3. Example implementations to help get started

### Z-Imburse
Privacy-preserving proactive reimbursement for certain email-based receipts

1. ZImburseRegistry.nr: the central repository for DKIM keys and entrypoint for finding escrows. Has centralized elements that are handwaved away in V1
1. Permissioned “superuser”/ admin (in V1, this would be decentralized or oracle-ized) can add DKIM keys to the registry
2. Admins can register escrows, allowing them to look up all escrows they manage. Since contracts can’t (yet) deploy other contracts, this registration step is required to check the authenticity of the escrow to ensure escrows are not griefing claimants
3. Admins can add claimants. This allows them to look up the claimants in an escrow and allows the claimants to look up all the escrows they are a part of
2. ZImburseEscrow.nr: Contract instances deployed by organization managers to provide organization members a way to pay themselves out for incurred expenses without a bureaucratic overview process
1. Admin can create spot/ recurring entitlements for claimants (recipients) that permit the claimant to self-authorize a reimbursement given certain parameters dictated in the entitlement
2. Admin can view all the active entitlements that create obligations for the escrow
3. Admin can “revoke” an entitlement from a claimant, preventing them from using the note to reimburse themselves
4. Claimants can reimburse with spot entitlements, meaning that they can verify an email to claim the reimbursement once before the entitlement is consumes.
5. Claimants can reimburse with recurring entitlements, meaning that they can present multiple emails of the same type (but not the same exact email) to claim reimbursements over an indefinite period (until revoked).
6. Claimants can view all the active entitlements they have available to claim

## Terminology

### ZKEmail.nr
* **Partial Hash**: A sha256 hash where the hashing starts natively (in JS) but is completed in constrained circuits. Deveopers will partial hash up to the point they need to access something from the preimage in-circuit
* **Interstitial Hash**: A sha256 hash where the hashing starts somewhere else (JS, other circuit) and computes some but not all of the rest of the hash. This would be used if hashing is split between recursive provers.

### Z-Imburse
* **Entitlement**: A note (aztec storage unit) given by an escrow admin to a claimant that allows them to withdraw funds from the escrow under certain terms
* **Spot Entitlement**: An entitlement that can only be claimed once before it is consumed
* **Recurring Entitlement**: An entitlement that can be claimed multiple times (once per some period). In V1, there is no programmability around the span of time. Monthly entitlement notes are achieved by using receipts that should only show up once a month, and then stripping the timestamp of days/ seconds.
* **Entitlement Receipt**: A copy of an entitlement note stored by the escrow admin. This allows them to view active obligations and revoke them. Receipts cannot be used to claim reimbursements.
* **Escrow Admin**: The administrator of the escrow contract that entitles claimants to reimburse themselves (and revokes those rights)
* **Claimant**: The user who is given entitlements and can present emails to reimburse themselves using entitlements
* **Participant**: Synonymous with claimant, sorry for non-standard usage of single word
* **Registry**: The ZImburseRegistry contract that stores DKIM keys, confirms authenticity of Escrow contracts, allows admins to look up their managed escrows and participants, and allows users to look up escrows they may have reimbursements for
* **Escrow**: The ZImburseEscrow contract that holds payment (usdc) tokens, gives the admin an interface to permit claimants to reimburse themselves, and gives claimants an interface to verify email receipts to reimburse themselves according to the admin’s policy (entitlements)
* **Verifier ID**: A hardcoded ID assigned to a certain receipt type. Ex: Linode → 2

## Setup & Testing

### Z-Imburse

#### Dependencies
The following `emails.zip` is an archive encrypted with the password `eWpgoj8jKaTuXqxPpFzgYtGeVywwFqPE` .

[emails.zip](https://prod-files-secure.s3.us-west-2.amazonaws.com/31f59e43-13d8-4140-a4be-8ad0077cd532/2f715196-2e56-45c6-8eca-89bd87cae4ef/emails.zip)

We considered faking DKIM signatures but were advised to just suck it up and post the raw emails to ensure the authenticity of test data. We are not yet ready to post these emails but will likely end up doing so. In the meantime, take the following measures:
1. unzip the archive to get `linode_sep.eml`, `linode_oct.eml`, and `united.eml`
2. run `mkdir <root_dir>/tests/test-data`
3. move the three `.eml` files into the created directory

Technically you don't need to do this if you don’t run the JS tests, however.

- Node v20.x (I haven’t tested with others, might work might not. This is built with Node v0.20.x)
- Aztec CLI tools (you MUST set version since there is a bug where `aztec-up 0.57.0` is broken)

# install the aztec cli
bash -i <(curl -s https://install.aztec.network)

# pull container images for the proper versions
export VERSION=0.57.0

#### Scripts
* `yarn`: Installs the nodejs (obviously) but the postinstall will build contract artifacts for testing in TXE and Typescript
* `yarn compile:contracts` Compiles only the noir contract artifacts. See next entry.
* `yarn compile:contracts true` This should be run by yarn so ignore unless you change the codebase. Compiles noir contract artifacts and creates Typescript bindings.
* `yarn txe` Runs the TXE testing environment. The TXE has been known to cause memory overflows (being addressed in the future by Aztec). If you encounter this you should comment out most of the tests and re-run parts of it in blocks. This will not require recompilation. Apologies for the inconvenience, we are similarly inconvenienced
* `yarn sandbox` Runs an Aztec Node (with a PXE) along with 3 other PXE’s that connect to the aztec node. used for JS testing. Run in a separate terminal.
* `yarn test test/contracts` Runs JS integration testing through the PXE. Requires that the sandbox command has been run first.

### ZKEmail.nr

#### Dependencies
- bb v0.57.0
- nargo v0.35.0
#### Scripts

* `nargo test --silence-warnings` Runs unit tests for noir codebase. run in `<root_dir>/lib`
* `./compile.sh` Compiles circuit artifacts if running js tests. run in `<root_dir>/scripts`
* `yarn test tests/circuits.test.ts` Runs witness simulation without proving. Ensures integrity of execution without the cost of waiting for proving. run in `<root_dir>/js`
* `yarn test tests/proving.test.ts` Runs full proof generation in UltraHonk and UltraPlonk for all examples. End-to-end proof generation demonstration, unnecessary for any testing most likely since we do not have EVM integrations. run in `<root_dir>/js`