raylsnetwork · ncervaens · Sep 18, 2025 · Sep 11, 2025 · Sep 11, 2025 · Sep 12, 2025
diff --git a/.gitignore b/.gitignore
@@ -22,11 +22,12 @@ node_modules
 # cli
 dist
 
-# artifacts
-packages/circom/artifacts
-packages/foundry/inputs
+# coverage
+packages/foundry/coverage
+lcov.info
 
 # Build artifacts
+packages/foundry/inputs
 packages/foundry/out/
 packages/foundry/broadcast/
 packages/foundry/cache/
@@ -42,4 +43,4 @@ packages/circom/artifacts/
 packages/circom/scripts/*.wtns
 packages/circom/scripts/proof.json
 packages/circom/scripts/public.json
-packages/circom/scripts/input.json
+packages/circom/scripts/input.json
diff --git a/README.md b/README.md
@@ -14,13 +14,23 @@
   <img src="https://img.shields.io/badge/TypeScript-Ready-blue" alt="TypeScript">
 </p>
 
-🧪 **Rayls Hook** is a privacy-preserving investor suitability assessment system built on Uniswap v4 hooks. It allows users to prove their investment suitability without revealing their specific questionnaire responses using Zero-Knowledge Proofs.
+**Rayls Hook** introduces two complementary ZK-SNARK enabled features built on Uniswap v4 hooks:
 
-⚙️ Built using **Scaffold-ETH 2** as the foundation, with **NextJS**, **RainbowKit**, **Foundry**, **Wagmi**, **Circom**, **SnarkJS**, and **TypeScript**.
+1. [🛡️ Suitability Verifier](./docs/suitability.md) (click for more info) – A privacy-preserving investor suitability assessment system. It allows users to prove their investment suitability without revealing their specific questionnaire responses using Zero-Knowledge Proofs.
+
+2. [🔐 Private Swaps](./docs/privateSwaps.md) (click for more info) – Private swaps that allow users to conceal their swap parameters until an execution timestamp is reached. Hidden swap values are committed on-chain via a unique commitment ID, then at execution time they are revealed and validated using zkSNARK proofs. Swap details are also encrypted using the Auditor’s public key and the generated ciphertext is stored on-chain, enabling independent verification at any time. The commitment Id is the result of running the cryptographic function keccak256 against the auditor ciphertext and the poseidon hash generated by the zk snark proof.
+
+## 📌 Key Notes
+
+- More details about circom and zkSNARK implementation [here](./packages/circom/README.md)
+- There's no partner integration but although Private swap commitments and encrypted payloads are currently fully stored on-chain, they could be stored in EigenDA with only lightweight references on-chain to reduce gas costs and improve scalability without compromising verifiability.
+- Only the beforeSwap hook is used, but the logic can be extended to beforeAddLiquidity as well.
+- The two features — Suitability Verifier and Private Swap Commitments — are independent, though private swap execution could optionally require passing the suitability check.
+- The frontend provides an example of a Suitability questionaire, but there's currently no FE->BE integration.
 
 ## 🎯 Project Overview
 
-Rayls Hook implements a comprehensive investor suitability assessment system that:
+🛡️ Suitability Verifier Logic
 
 - ✅ **Private Questionnaire**: Users answer 5 suitability questions without revealing their responses
 - 🔐 **Zero-Knowledge Proofs**: Prove investment suitability using Circom circuits
@@ -29,6 +39,14 @@ Rayls Hook implements a comprehensive investor suitability assessment system tha
 - 🛡️ **Privacy-First**: Never reveal private questionnaire data
 - ⚡ **On-Chain Verification**: Smart contract verification of ZK proofs
 
+🔐 Private Swap Logic
+
+- ✅ Encrypted Commitments: Users (or backend services) create encrypted swap commitments
+- ⏳ Deferred Execution: Commitments become executable only after a timestamp
+- 🔏 ZK Proof of Intent: Execution requires a zkSNARK proof proving knowledge of commitment id
+- 📡 Auditor Access: Commitments include encrypted values for auditors to decrypt
+- 🪝 Uniswap v4 Integration: Hook contract executes swaps using permit + safe transfer logic
+
 ## 🏗️ Architecture
 
 ### System Components
@@ -44,25 +62,31 @@ Rayls Hook implements a comprehensive investor suitability assessment system tha
 └─────────────────┘    └──────────────────┘    └─────────────────┘
 ```
 
+- Suitability Verifier Logic lives in circuits + verifier contracts
+
+- Private Swap Logic lives in the hook contracts + zk circuits + auditor encrypt/decrypt scripts.
+
 ### Technology Stack
 
-| Layer | Technology | Purpose |
-|-------|------------|---------|
-| **ZK Layer** | Circom + SnarkJS | Zero-knowledge proof generation |
-| **Smart Contracts** | Solidity + Foundry | On-chain verification |
-| **Frontend** | NextJS + Scaffold-ETH 2 | User interface |
-| **Integration** | Uniswap v4 Hooks | DEX integration |
-| **Development** | TypeScript + Wagmi | Type-safe development |
+| Layer               | Technology              | Purpose                         |
+| ------------------- | ----------------------- | ------------------------------- |
+| **ZK Layer**        | Circom + SnarkJS        | Zero-knowledge proof generation |
+| **Smart Contracts** | Solidity + Foundry      | On-chain verification           |
+| **Frontend**        | NextJS + Scaffold-ETH 2 | User interface                  |
+| **Integration**     | Uniswap v4 Hooks        | DEX integration                 |
+| **Development**     | TypeScript + Wagmi      | Type-safe development           |
 
 ### Circuit Architecture
 
 #### Suitability Assessment Circuit
+
 - **Private Inputs**: 5 questionnaire responses (0-3 scale)
 - **Public Inputs**: Risk threshold and calculated profile
 - **Output**: Suitability verification (0 or 1)
 
 #### Private Swap Intent Circuit
-- **Private Inputs**: Amount, direction, sender, timestamp
+
+- **Private Inputs**: amountIn, zeroForOne, sender, timestamp
 - **Public Outputs**: Commitment hash and verification data
 - **Purpose**: Prove swap intent without revealing sensitive details
 
@@ -75,6 +99,13 @@ Before you begin, you need to install the following tools:
 - [Git](https://git-scm.com/downloads)
 - [Circom](https://docs.circom.io/getting-started/installation/) (for ZK circuits)
 - [SnarkJS](https://github.com/iden3/snarkjs) (for ZK proofs)
+- [Foundry](https://getfoundry.sh/introduction/installation/)
+
+To better run circom you might need to add this to your PATH:
+
+```bash
+export PATH=$PATH:$HOME/.cargo/bin
+```
 
 ## 🚀 Quick Start
 
@@ -85,7 +116,7 @@ To get started with Rayls Hook, follow these steps:
 ```bash
 # Clone the repository
 git clone https://github.com/raylsnetwork/uniswap-incubator.git
-cd rayls-hook
+cd uniswap-incubator
 
 # Install all dependencies
 yarn install
@@ -95,27 +126,24 @@ yarn install
 
 ```bash
 # Start local Ethereum network (Scaffold-ETH 2)
-yarn chain
+yarn workspace @se-2/foundry chain
 ```
 
 This command starts a local Ethereum network using Foundry. The network runs on your local machine and can be used for testing and development.
 
 ### 3. Setup Zero-Knowledge Circuits
 
 ```bash
-# Setup ZK circuits and generate proofs
-yarn setup
-
 # Or setup specific circuits
-yarn setup-suitability      # Suitability assessment circuit
-yarn setup-private-swap     # Private swap intent circuit
+yarn workspace rayls-hook-circom setup-suitability      # Suitability assessment circuit
+yarn workspace rayls-hook-circom setup-private-swap     # Private swap intent circuit
 ```
 
 ### 4. Deploy Smart Contracts
 
 ```bash
 # Deploy contracts to local network
-yarn deploy
+yarn workspace @se-2/foundry deploy
 ```
 
 This command deploys the Rayls Hook smart contracts to the local network, including the ZK verifiers and Uniswap v4 hooks.
@@ -124,27 +152,41 @@ This command deploys the Rayls Hook smart contracts to the local network, includ
 
 ```bash
 # Start the NextJS frontend
-yarn start
+yarn workspace @se-2/nextjs start
 ```
 
 Visit your app on: `http://localhost:3000`. You can interact with the suitability assessment and test the ZK proof verification.
 
+### 6. Running tests
+
+```bash
+yarn workspace @se-2/foundry test
+```
+
+### 7. Check coverage
+
+(We focused on RaylsHook contract for full coverage)
+
+```bash
+yarn workspace @se-2/foundry coverage
+```
+
 ## 🛠️ Development
 
 ### Available Commands
 
-| Command | Description |
-|---------|-------------|
-| `yarn chain` | Start local blockchain |
-| `yarn deploy` | Deploy smart contracts |
-| `yarn start` | Start frontend |
-| `yarn setup` | Setup ZK circuits (default: Suitability) |
-| `yarn prove` | Generate new ZK proof |
-| `yarn setup-suitability` | Setup Suitability circuit |
-| `yarn prove-suitability` | Generate Suitability proof |
-| `yarn setup-private-swap` | Setup PrivateSwapIntent circuit |
-| `yarn prove-private-swap` | Generate PrivateSwapIntent proof |
-| `yarn test` | Run tests |
+| Command                   | Description                              |
+| ------------------------- | ---------------------------------------- |
+| `yarn chain`              | Start local blockchain                   |
+| `yarn deploy`             | Deploy smart contracts                   |
+| `yarn start`              | Start frontend                           |
+| `yarn setup`              | Setup ZK circuits (default: Suitability) |
+| `yarn prove`              | Generate new ZK proof                    |
+| `yarn setup-suitability`  | Setup Suitability circuit                |
+| `yarn prove-suitability`  | Generate Suitability proof               |
+| `yarn setup-private-swap` | Setup PrivateSwapIntent circuit          |
+| `yarn prove-private-swap` | Generate PrivateSwapIntent proof         |
+| `yarn test`               | Run tests                                |
 
 ### Project Structure
 
@@ -181,26 +223,34 @@ yarn prove-private-swap
 ## 📋 Roadmap
 
 ### Phase 1: Core Infrastructure ✅
+
 - [x] ZK circuits implementation (Suitability + PrivateSwapIntent)
 - [x] Smart contract verifiers
 - [x] Basic Uniswap v4 hook integration
 - [x] ZK proof generation and verification pipeline
+- [x] Auditor encryption feature
+- [x] Multiple tests
 
 ### Phase 2: Frontend Development 🚧
-- [ ] Complete questionnaire UI implementation
+
+- [ ] Complete UI + BE implementation
 - [ ] ZK proof generation interface
 - [ ] Real-time proof verification
 - [ ] User dashboard and profile management
 - [ ] Integration with wallet providers
 
 ### Phase 3: Advanced Features 📋
+
 - [ ] Multi-circuit support and management
+- [ ] Private Swap multi-auditors support and management
+- [ ] Private Swap multi-executors support and management
 - [ ] Advanced risk assessment algorithms
 - [ ] Compliance and regulatory features
 - [ ] Integration with external KYC providers
 - [ ] Mobile-responsive design
 
 ### Phase 4: Production Ready 🎯
+
 - [ ] Security audits and testing
 - [ ] Performance optimization
 - [ ] Documentation and tutorials
@@ -247,4 +297,4 @@ This project is licensed under the MIT License - see the [LICENSE](LICENSE) file
 
 ---
 
-**Note**: This project is part of the Uniswap Hook Incubator 6 program. For production use, consider security audits and additional compliance requirements.
+**Note**: This project is part of the Uniswap Hook Incubator 6 program. For production use, consider security audits and additional compliance requirements.
diff --git a/docs/RaylsHook_private_swaps_block_diagram.svg b/docs/RaylsHook_private_swaps_block_diagram.svg
diff --git a/docs/RaylsHook_private_swaps_diagram.svg b/docs/RaylsHook_private_swaps_diagram.svg
diff --git a/docs/RaylsHook_suitability_diagram.png b/docs/RaylsHook_suitability_diagram.png
diff --git a/docs/SuitabilityQuestionaire.png b/docs/SuitabilityQuestionaire.png
diff --git a/docs/privateSwaps.md b/docs/privateSwaps.md
@@ -0,0 +1,92 @@
+## 📄 `docs/privateSwaps.md`
+
+🔐 Private Swap Commitments
+
+This Uniswap v4 hook extension introduces private swaps that allow users to conceal their swap parameters until an execution timestamp is reached. Hidden swap values are committed on-chain via a unique commitment ID, then at execution time they are revealed and validated using zkSNARK proofs. Swap details are also encrypted using the Auditor’s public key and the generated ciphertext is stored on-chain, enabling independent verification at any time. The commitment Id is the result of running the cryptographic function keccak256 against the auditor ciphertext and the poseidon hash generated by the zk snark proof.
+
+Key use cases include:
+
+- MEV protection – hiding swap intent reduces frontrunning risk.
+
+- Price impact mitigation for large swaps – users executing large trades can split them into multiple commitments to minimize token price impact in the pool.
+
+- Compliance & oversight – DAOs and regulated protocols can prove onchain to an auditor the agreed swap schedules according to the defined tokenomics.
+
+<p align="left"  style="margin-left:12em;">
+  <img src="./RaylsHook_private_swaps_block_diagram.svg" alt="Private Swap Block Diagram" width="700"/>
+</p>
+
+## 🔄 Flow
+
+<p align="left">
+  <img src="./RaylsHook_private_swaps_diagram.svg" alt="Private Swap Diagram" width="1000"/>
+</p>
+
+### 1. Create Commitment
+
+- **User** through a UI:
+
+  - Creates a swap commitment by defining amountIn, direction, timestamp.
+  - Signs and sends along an ERC20 permit
+
+- **Rayls Middleware**
+
+  - Encrypts swap params using Auditor's pub key (file encrypt.js).
+  - Creates and holds zkSNARK proofs of knowledge of swap params for commitment `id`..
+  - Generates commitment id using Auditor's encryption + Poseidon hash from zk proof.
+  - Calls `storeCommitment(id, ciphertext, permit)` with:
+    - `id`: unique hash of the commitment.
+    - `ciphertext`: encrypted swap details (amount, direction, timestamp).
+    - `permit`: ERC20 permit signature.
+    - Contract records commitment and emits `CommitmentStored`.
+
+### 2. Execute Commitment
+
+- **Rayls Middleware**
+
+  - Monitors for commitments with expired timestamps.
+  - Triggers commitment execution when timestamp is reached
+  - When time is reached, calls `executeCommitment(id, zkProof)`.
+
+- **Rayls Hook**
+
+  - Verifies:
+    - zkSNARK proof validity.
+    - Commitment matches proof.
+    - Permit authorizes token pull.
+  - Contract executes swap via Uniswap v4 `PoolManager`.
+  - Settles balances on callback
+  - Emits `CommitmentExecuted`.
+
+### 3. Cancel Commitment
+
+- **User**
+  - Triggers a commitment cancellation through a UI, before execution
+- **Rayls Middleware**
+  - Calls `cancelCommitment(id, zkProof)`.
+- **Rayls Hook**
+  - Marks commitment as canceled, clears heavy storage.
+  - Emits `CommitmentCanceled`.
+
+### 4. Auditor Flow
+
+- **Auditor** can always:
+
+  - Read `ciphertext` onchain.
+  - Decrypt using it's own private key (file decrypt.js).
+  - Verify swap parameters offchain for compliance.
+  - Validates if permit matches the encrypted values
+
+---
+
+## Key notes
+
+- We use circom for zkSNARK and ECIES encryption for the auditor (using nodejs scripts). Encryption in circom is too expensive.
+- We could enforce the auditor to approve a commitement cancelation.
+- When calling executeCommitment, Rayls Middleware would use private bundlers for additional MEV protection.
+
+## Future Extensions and Use Cases
+
+- Decentralized Executors: Anyone could register as an executor and earn a percentage of swap fees for executing commitments, creating an open marketplace of executors.
+- Auditor-Gated Cancellation: Cancellation requests could require auditor approval, preventing users from revoking commitments that already passed compliance checks.
+- Multi-Auditor Support: Commitments could be associated with multiple auditors, allowing collaborative oversight or redundancy in regulatory validation.