refactor: Improved README.md (#80)

Enhance README.md with detailed project overview and architecture for ERC-7579 modules integrating Semaphore with ERC-4337. Added sections on project delivery, usage, and integration guidance, along with a flowchart illustrating data flow.

Author: jimmychu0807

README.md

@@ -1,43 +1,123 @@
 # Semaphore Modular Smart Account Modules
 
-## Project Artifacts
+**ERC-7579 modules** that plug Semaphore’s anonymous group proofs into **ERC-4337** modular smart accounts—so members can co-author transactions without revealing *which* member approved each action on-chain.
 
-- 🌐 [Project demo website](https://semaphore-msa-modules.jimmychu0807.hk/) (please connect to Base Sepolia)
-- 🎥 [Project demo video](https://www.loom.com/share/0b800171a4f1491f9eedd4f555569e37?sid=0c2d3024-5652-499e-b374-218023da581b)
-- 📜 [Project writeup](https://jimmychu0807.hk/semaphore-msa-modules)
+## Try it
 
-## Overview
+- [Demo website](https://semaphore-msa-modules.jimmychu0807.hk/) (connect on **Base Sepolia**)
+- [Demo video](https://www.loom.com/share/0b800171a4f1491f9eedd4f555569e37?sid=0c2d3024-5652-499e-b374-218023da581b)
+- [Project write-up](https://jimmychu0807.hk/semaphore-msa-modules)
 
-This project mainly consists of [a validator and an executor modules](https://eips.ethereum.org/EIPS/eip-7579#validators) adheres to [**ERC-7579**](https://eips.ethereum.org/EIPS/eip-7579) standard that uses [Semaphore](https://semaphore.pse.dev/) for proof validation. Smart accounts incorporate these modules gain the following benefits:
+## What this repo delivers
 
-- The smart account behaves like an  **anonymous multi-sig wallet** controlled by [Semaphore group members](https://docs.semaphore.pse.dev/guides/groups) of the smart account. Proofs sent by the members are regarded as signatures.
+Two complementary [ERC-7579](https://eips.ethereum.org/EIPS/eip-7579) modules (see [validators and executors](https://eips.ethereum.org/EIPS/eip-7579#validators)) backed by [Semaphore](https://semaphore.pse.dev/):
 
-- The smart account gains Semaphore property guaranteeing a valid proof (seen as signature) must be from a member within the group and have not signed before, while preserving the member privacy and no one could trace who send the proof from the on-chain log.
+| Module | Role |
+|--------|------|
+| **SemaphoreValidator** | Validates `UserOperation` signatures (EdDSA + identity commitment in the account’s Semaphore [group](https://docs.semaphore.pse.dev/guides/groups)). Restricts calls so the account can only drive the paired executor’s API surface. |
+| **SemaphoreExecutor** | Holds per-account state (group, threshold, pending txs, collected proofs). Exposes **`initiateTx` → `signTx` → `executeTx`** so proofs act like threshold “signatures” while preserving member privacy. |
 
-Development of this project is supported by [PSE Acceleration Program](https://github.com/privacy-scaling-explorations/acceleration-program) (see [thread discussion](https://github.com/privacy-scaling-explorations/acceleration-program/issues/72)).
+Together they give a smart account **anonymous threshold control**: only group members can advance state, proofs are unique per signal (no replay as the same “vote”), and calldata does not deanonymize the prover.
 
-Project Code: FY24-1847
+**Project code:** FY24-1847 · Development supported by the [PSE Acceleration Program](https://github.com/privacy-scaling-explorations/acceleration-program) ([discussion](https://github.com/privacy-scaling-explorations/acceleration-program/issues/72)).
 
-Please refer to the project packages READMEs:
-- [packages/contracts](./packages/contracts): Smart contracts of the Semaphore validator and executor module.
-- [packages/lib](./packages/lib): Javascript library for interacting with Semaphore modular smart account modules.
-- [packages/web](./packages/web): Frontend demo to interact with a smart account and semaphore MSA modules.
+## Architecture
 
-## Relevant Information
+High-level data flow from a developer-built client through account abstraction to Semaphore on-chain.
 
-![ERC-4337 Lifecycle](./docs/contracts-assets/4337-lifecycle.svg)
+```mermaid
+sequenceDiagram
 
-*Source: [ERC-4337 website](https://www.erc4337.io/docs/understanding-ERC-4337/architecture)*
+  autonumber
+  actor App as Wallet or demo dApp
+  participant Lib as @semaphore-msa-modules/lib
+  participant ZK as Off-chain ZK prover
+  participant SA as Smart account
+  participant Val as SemaphoreValidator
+  participant Ex as SemaphoreExecutor
+  participant Sem as Semaphore contracts
 
-- [ERC-4337](https://eips.ethereum.org/EIPS/eip-4337):  [overview](https://www.erc4337.io/)
-- [ERC-7579](https://eips.ethereum.org/EIPS/eip-7579): [overview](https://erc7579.com/)
-- [ERC-7780](https://eips.ethereum.org/EIPS/eip-7780)
+  App->>Lib: Install modules, encode calls, build user ops
 
-## Acknowledgement
+  Note over App,Sem: Anonymous threshold flow — each step is usually its own UserOperation
 
-Thanks to the following folks on discussing about this project and helps along: 
+  App->>ZK: Identity + signal, proof for initiateTx
+  ZK-->>App: Proof bytes
+  App->>SA: initiateTx UserOperation (validate + execute)
+  SA->>Val: validateUserOp
+  Val->>Ex: Restrict to paired executor API
+  SA->>Ex: initiateTx
+  Ex->>Sem: Verify proof, nullifier, store pending tx (1st proof)
 
-- [Saleel P](https://github.com/saleel) on initiating this idea with [Semaphore Wallet](https://github.com/saleel/semaphore-wallet), showing me that the idea is feasible.
-- [Cedoor](https://github.com/cedoor) and [Vivian Plasencia](https://github.com/vplasencia) on Semaphore development and their opinions.
-- [John Guilding](https://github.com/JohnGuilding) on the discussion, support, and review of the project.
-- [Rhinestone team](https://rhinestone.wtf/) and [Konrad Kopp](https://github.com/kopy-kat) support on using [ModuleKit](https://docs.rhinestone.wtf/build-modules), [ModuleSDK](https://docs.rhinestone.wtf/build-modules) and their work on ERC-7579 that make this project possible, from which I have learned a lot.
+  Note over App,Sem: signTx UserOperation
+
+  loop Until collected proofs >= M-of-N threshold
+    App->>ZK: Proof for same txHash / signal
+    ZK-->>App: Proof bytes
+    App->>SA: signTx UserOperation (validate + execute)
+    SA->>Val: validateUserOp
+    Val->>Ex: Restrict to paired executor API
+    SA->>Ex: signTx
+    Ex->>Sem: Verify proof, nullifier, increment count
+  end
+
+  Note over App,Sem: executeTx UserOperation
+  App->>SA: executeTx UserOperation (validate + execute)
+  SA->>Val: validateUserOp
+  Val->>Ex: Restrict to paired executor API
+  SA->>Ex: executeTx
+  Ex->>Sem: Final checks, then run the pending external call
+```
+
+**How to read it:** clients use the library (with **Rhinestone Module SDK** and **viem** under the hood) to install modules, encode calls, and assemble user ops; an off-chain prover produces Semaphore proofs; each **`UserOperation`** is validated and executed on the **smart account** (in a full **ERC-4337** stack, **`EntryPoint`** orchestrates this via **`handleOps`**, often through a bundler, with an optional paymaster); the **validator** checks the user-op path and signature; the **executor** runs **`initiateTx`** (first proof, pending tx), then **`signTx`** in a loop until the account’s **M-of-N threshold** is met, then **`executeTx`** when proofs are sufficient (or earlier if `execute` is set so the contract auto-runs `executeTx` once the threshold is reached).
+
+## Who should integrate this?
+
+Pick this stack when you are **not** satisfied with a plain on-chain multisig that reveals approvers, but you still want **account abstraction** (gas sponsorship, batched ops, smart accounts) and **modular** validation per [ERC-7579](https://eips.ethereum.org/EIPS/eip-7579).
+
+| If you are building… | Why integrate |
+|----------------------|----------------|
+| **Modular smart account products** (wallets, DAO tooling, team treasuries) | Add a **privacy-preserving threshold** policy: M-of-N control without exposing which key approved each transaction. |
+| **dApps that already use Semaphore** | Reuse **groups and proofs** as the authorization layer for a **4337** smart account instead of only for app-specific claims. |
+| **Rhinestone / Module SDK workflows** | The published package exposes **`getSemaphoreExecutor`** and **`getSemaphoreValidator`** module descriptors compatible with **`@rhinestone/module-sdk`**, so you can treat these modules like other installable validators and executors. |
+| **Research and education** | End-to-end reference: Foundry tests (FFI + proofs), a **Next.js** demo, and Dockerized **Alto** + paymaster for local experimentation. |
+
+You will touch **Solidity** if you fork or redeploy the modules, **TypeScript** for proofs and user-ops (`viem`, Semaphore protocol packages), and **4337 infrastructure** (bundler RPC, optional paymaster) for production UX.
+
+## Monorepo layout
+
+| Package | Description |
+|---------|-------------|
+| [`packages/contracts`](./packages/contracts) | **Foundry** contracts: `SemaphoreValidator`, `SemaphoreExecutor`, tests, deployment scripts. Includes **Base Sepolia** deployment addresses in its README. |
+| [`packages/lib`](./packages/lib) | **`@semaphore-msa-modules/lib`**: module installation helpers, ABIs, and transaction helpers built on **viem** and **Rhinestone Module SDK**. |
+| [`packages/web`](./packages/web) | **Next.js** demo UI for installing modules, managing identities, and sending demo transactions. |
+| [`docker-containers`](./docker-containers) | **Docker Compose**: forked **Anvil**, **Alto** bundler, mock paymaster—used by `pnpm dev` at the workspace root. |
+
+**Requirements:** Node **≥ 22**, **pnpm** (see root `package.json` for the pinned version).
+
+**Common commands:**
+
+```bash
+pnpm install
+pnpm dev          # Docker stack + package dev servers
+pnpm ci-check     # build, test, lint across packages
+```
+
+## Standards and further reading
+
+![ERC-4337 lifecycle](./docs/contracts-assets/4337-lifecycle.svg)
+
+*Source: [ERC-4337 documentation](https://www.erc4337.io/docs/understanding-ERC-4337/architecture)*
+
+- [ERC-4337](https://eips.ethereum.org/EIPS/eip-4337) — [overview](https://www.erc4337.io/)
+- [ERC-7579](https://eips.ethereum.org/EIPS/eip-7579) — [overview](https://erc7579.com/)
+- [ERC-7780](https://eips.ethereum.org/EIPS/eip-7780) (stateless validator hooks used by the validator module—see contracts README)
+
+## Acknowledgements
+
+Thanks to everyone who shaped and supported this work:
+
+- [Saleel P](https://github.com/saleel) for the original impetus with [Semaphore Wallet](https://github.com/saleel/semaphore-wallet) and showing the approach was viable.
+- [Cedoor](https://github.com/cedoor) and [Vivian Plasencia](https://github.com/vplasencia) for Semaphore guidance.
+- [John Guilding](https://github.com/JohnGuilding) for discussion, support, and review.
+- The [Rhinestone](https://rhinestone.wtf/) team and [Konrad Kopp](https://github.com/kopy-kat) for [ModuleKit](https://docs.rhinestone.wtf/build-modules), [Module SDK](https://docs.rhinestone.wtf/build-modules), and ERC-7579 foundations this repo builds on.