From e1d68b7db91adae99eff063dc17ec4e7f737e14c Mon Sep 17 00:00:00 2001
From: "Ya-wen, Jeng" <vivi432@yahoo.com.tw>
Date: Fri, 3 Oct 2025 10:57:51 +0800
Subject: [PATCH 1/2] docs: enhance README with detailed installation and usage
 instructions for Semaphore Rust package

---
 README.md | 108 +++++++++++++++++++++++++++++++++++++++++++++++++++---
 1 file changed, 103 insertions(+), 5 deletions(-)

diff --git a/README.md b/README.md
index efeb2c2..fa71a19 100644
--- a/README.md
+++ b/README.md
@@ -67,7 +67,105 @@
 
 All tasks related to the Semaphore Rust implementation are public. You can track their progress, statuses, and additional details in the [Semaphore Rust view](https://github.com/orgs/semaphore-protocol/projects/10/views/29).
 
-## 🛠 Install
+## Semaphore Rust Package
+
+### 🛠 Install
+
+Add this to your `Cargo.toml`:
+
+```toml
+[dependencies]
+semaphore-rs = "0.1"
+```
+
+### Semaphore Identity
+
+-   Generate a semaphore identity from a string
+    ```rust
+    use semaphore_rs::identity::Identity;
+    let identity = Identity::new("secret".as_bytes());
+    ```
+-   Get the identity commitment
+    ```rust
+    identity.commitment()
+    ```
+-   Get the identity private key
+    ```rust
+    identity.private_key()
+    ```
+
+### Semaphore Group
+
+-   Generate a group member from an identity
+
+    ```rust
+    use semaphore_rs::utils::to_element;
+    let member = to_element(*identity.commitment())
+    ```
+
+-   Generate a semaphore group from members
+    ```rust
+    use semaphore_rs::group::{Element, Group};
+    const MEMBER1: Element = [1; 32];
+    const MEMBER2: Element = [2; 32];
+    let group = Group::new(&[
+        MEMBER1,
+        MEMBER2,
+        to_element(*identity.commitment())
+    ]).unwrap();
+    ```
+-   Get the group root
+    ```rust
+    let root = group.root();
+    ```
+
+### Semaphore Proof
+
+-   Generate a semaphore proof
+
+    ```rust
+    use semaphore_rs::proof::GroupOrMerkleProof;
+    use semaphore_rs::proof::Proof;
+
+    let message = "message";
+    let scope = "scope";
+    let tree_depth = 20;
+    let proof = Proof::generate_proof(
+        identity,
+        GroupOrMerkleProof::Group(group),
+        message.to_string(),
+        scope.to_string(),
+        tree_depth as u16,
+    )
+    .unwrap();
+    ```
+
+-   Verify a semaphore proof
+    ```rust
+    let valid = Proof::verify_proof(proof);
+    ```
+
+### Serde
+
+-   Please enable the feature in the `Cargo.toml`
+
+    ```toml
+    semaphore-rs = { version = "0.1", features = ["serde"] }
+    ```
+
+-   Serialize a semaphore proof
+    ```rust
+    let proof_json = proof.export().unwrap();
+    ```
+-   Deserialize a semaphore proof
+    ```rust
+    use semaphore_rs::proof::SemaphoreProof;
+    let proof_imported = SemaphoreProof::import(&proof_json).unwrap();
+    ```
+
+## Development
+
+### 🛠 Install
 
 Clone this repository:
 
@@ -75,9 +173,9 @@ Clone this repository:
 git clone https://github.com/semaphore-protocol/semaphore-rs
 ```
 
-## 📜 Usage
+### 📜 Usage
 
-### Code quality and formatting
+#### Code quality and formatting
 
 Run [Rustfmt](https://github.com/rust-lang/rustfmt) to automatically format the code
 
@@ -91,13 +189,13 @@ Run [rust-clippy](https://github.com/rust-lang/rust-clippy) to catch common mist
 cargo clippy
 ```
 
-### Testing
+#### Testing
 
 ```bash
 cargo test
 ```
 
-### Update `witness_graph` with [`circom-witnesscalc`](https://github.com/iden3/circom-witnesscalc)
+#### Update `witness_graph` with [`circom-witnesscalc`](https://github.com/iden3/circom-witnesscalc)
 
 ```bash
 ./script build_witness_graph.sh

From f91ff0e71b99eaf5ddac78e56fb10d2681c06e0e Mon Sep 17 00:00:00 2001
From: "Ya-wen, Jeng" <vivi432@yahoo.com.tw>
Date: Fri, 3 Oct 2025 11:00:34 +0800
Subject: [PATCH 2/2] docs: update README to improve section headings and
 organization for Semaphore usage

---
 README.md | 10 ++++++----
 1 file changed, 6 insertions(+), 4 deletions(-)

diff --git a/README.md b/README.md
index fa71a19..ec14fa0 100644
--- a/README.md
+++ b/README.md
@@ -78,7 +78,9 @@ Add this to your `Cargo.toml`:
 semaphore-rs = "0.1"
 ```
 
-### Semaphore Identity
+### 📜 Usage
+
+#### Semaphore Identity
 
 -   Generate a semaphore identity from a string
     ```rust
@@ -94,7 +96,7 @@ semaphore-rs = "0.1"
     identity.private_key()
     ```
 
-### Semaphore Group
+#### Semaphore Group
 
 -   Generate a group member from an identity
 
@@ -119,7 +121,7 @@ semaphore-rs = "0.1"
     let root = group.root();
     ```
 
-### Semaphore Proof
+#### Semaphore Proof
 
 -   Generate a semaphore proof
 
@@ -145,7 +147,7 @@ semaphore-rs = "0.1"
     let valid = Proof::verify_proof(proof);
     ```
 
-### Serde
+#### Serde
 
 -   Please enable the feature in the `Cargo.toml`