Merge pull request #37 from Poly-pay/gitbook-sync

Update documentation and update API URL for ZK verification service

Author: gianalarcon

docs/.gitbook/assets/approve_phase.png

@@ -4,13 +4,13 @@ This page provides a detailed explanation of the [Noir](https://noir-lang.org) c
 
 ## Overview
 
-The circuit file is located at `packages/nextjs/public/circuit/src/main.nr`. It proves four things in a single proof: transaction hash commitment is correct, ECDSA signature is valid, prover is a member of authorized signers, and nullifier prevents double-signing.
+The circuit file is located at `packages/nextjs/public/circuit/src/main.nr`. It proves four things in a single proof: transaction hash commitment is correct, ECDSA signature is valid, prover knows the secret for their commitment, and nullifier prevents double-signing.
 
 ## Circuit Structure
 
-### Constants and Imports
+### Imports
 
-The circuit uses `keccak256` for Ethereum-compatible message hashing, `poseidon` as a ZK-friendly hash function for commitments and nullifiers, and sets `DEPTH = 4` meaning the Merkle tree supports 2^4 = 16 signers maximum.
+The circuit uses `keccak256` for Ethereum-compatible message hashing and `poseidon` as a ZK-friendly hash function for commitments and nullifiers.
 
 ## Main Function Inputs
 
@@ -24,8 +24,6 @@ These inputs are hidden from everyone - only the prover knows them:
 | pub_key_x | [u8; 32] | Public key X coordinate |
 | pub_key_y | [u8; 32] | Public key Y coordinate |
 | secret | Field | Signer's secret |
-| leaf_index | Field | Position in Merkle tree |
-| merkle_path | [Field; DEPTH] | Sibling hashes for proof |
 | tx_hash_bytes | [u8; 32] | Transaction hash to sign |
 
 ### Public Inputs
@@ -35,7 +33,7 @@ These inputs are visible on-chain and used for verification:
 | Input | Type | Description |
 |-------|------|-------------|
 | tx_hash_commitment | Field | Poseidon hash of tx_hash |
-| merkle_root | Field | Root of authorized signers tree |
+| commitment | Field | hash(secret, secret) - checked against signers list |
 | nullifier | Field | Unique identifier to prevent double-signing |
 
 ## Step-by-Step Explanation
@@ -52,11 +50,11 @@ The circuit reconstructs Ethereum's `personal_sign` prefix `"\x19Ethereum Signed
 
 **Why prefix?** Ethereum wallets always add this prefix when signing. We must match the exact message that was signed.
 
-### Step 3: Verify Merkle Membership
+### Step 3: Verify Commitment Ownership
 
-The circuit computes commitment from secret using `commitment = hash(secret, secret)`, uses `leaf_index` and `merkle_path` to compute [Merkle](https://en.wikipedia.org/wiki/Merkle_tree) root, then compares with public `merkle_root`.
+The circuit computes commitment from secret using `commitment = hash(secret, secret)`, then compares with public `commitment`.
 
-**Privacy:** The circuit proves "I know a secret whose commitment is in the tree" without revealing which leaf.
+**How authorization works:** The circuit proves "I know the secret for this commitment". Then the smart contract checks "Is this commitment in the signers list?" This two-step verification ensures only authorized signers can sign transactions.
 
 ### Step 4: Verify Nullifier
 
@@ -66,10 +64,6 @@ The circuit computes nullifier using `nullifier = hash(secret, tx_hash)` and com
 
 ## Helper Functions
 
-### compute_merkle_root
-
-This function converts `leaf_index` to bits (little-endian), then for each level, the bit determines left/right position: bit = 0 means current is left child, bit = 1 means current is right child. It hashes with sibling from `merkle_path` and repeats until reaching root.
-
 ### bytes_to_field
 
 Converts 32-byte array to single Field element by treating bytes as big-endian number.
@@ -83,7 +77,7 @@ Wrapper for [Poseidon](https://www.poseidon-hash.info) hash with 2 inputs.
 | Attack | Prevention |
 |--------|------------|
 | Fake signature | ECDSA verification in circuit |
-| Non-member signing | Merkle membership proof |
+| Non-member signing | Commitment checked against signers list on-chain |
 | Double signing | Nullifier stored on-chain |
 | Transaction tampering | tx_hash_commitment verification |
 | Replay attack | Nonce included in tx_hash |
@@ -92,7 +86,6 @@ Wrapper for [Poseidon](https://www.poseidon-hash.info) hash with 2 inputs.
 
 Navigate to noir package with `cd packages/nextjs/public/circuit/src`, compile circuit with `nargo compile`, run tests with `nargo test`.
 
-
 ## Learn More
 
 - [Noir Language Documentation](https://noir-lang.org/docs)

docs/.gitbook/assets/exec_phase.png

@@ -5,30 +5,32 @@
 | Aspect          | Traditional Multisig             | PolyPay                   |
 | --------------- | -------------------------------- | ------------------------- |
 | Signer Identity | Public addresses stored on-chain | Hidden behind commitments |
-| Who Signed      | Visible to everyone              | Only the signer knows     |
+| Who Signed      | Visible to everyone              | Commitment visible, EOA hidden |
 
 ### Commitment-Based Identity
 
 Instead of storing addresses, PolyPay stores **commitments** (hash(secret, secret)):
 
 * The **secret** is derived from signing a message with your wallet
-* The **commitment** is stored on-chain (in a Merkle tree)
+* The **commitment** is stored on-chain in a signers list
 * Only you know the secret that matches your commitment
 
 ### How It Works
 
 1. **Setup**: Each signer generates a secret and computes their commitment
-2. **Registration**: Commitments are added to the smart contract's Merkle tree
-3. **Signing**: To approve a transaction, signers prove they know a secret that matches one of the commitments - without revealing which one
+2. **Registration**: Commitments are added to the smart contract's signers list
+3. **Signing**: To approve a transaction, signers prove they know the secret for their commitment using ZK proofs
+4. **Verification**: The smart contract checks if the commitment exists in the signers list
 
-### Anonymity Set
+### Privacy Model
 
-All signers share the same anonymity set. When you sign a transaction:
+When you sign a transaction:
 
-* The contract knows "one of the N signers approved"
-* Nobody knows "which specific signer approved"
+* The ZK proof verifies you know the secret for your commitment
+* The contract checks your commitment is in the authorized signers list
+* Your Ethereum address (EOA) is never revealed on-chain
 
-This is achieved through ZK proofs and Merkle tree membership proofs.
+This means observers can see which commitment signed, but cannot link it back to your wallet address.
 
 ### Relayer Privacy
 
@@ -43,4 +45,4 @@ PolyPay's backend uses a dedicated relayer wallet to deploy wallets and execute
 | Deploy wallet       | Creator address exposed  | Only relayer visible |
 | Execute transaction | Executor address exposed | Only relayer visible |
 
-This creates **complete anonymity**: no signer address ever appears on-chain.
+This creates **complete EOA anonymity**: no signer's Ethereum address ever appears on-chain.

docs/.gitbook/assets/setup_phase.png

@@ -15,8 +15,8 @@ In a traditional multisig wallet:
 - Signer addresses are public on blockchain
 
 In PolyPay:
-- You prove "I am an authorized signer" without revealing WHICH signer you are
-- Only the proof is public, your identity stays private
+- You prove "I know the secret for an authorized commitment" without revealing your EOA address
+- Your Ethereum address stays private, only the commitment is visible
 
 ## The Four Proofs
 
@@ -44,18 +44,22 @@ When you sign a transaction in PolyPay, the ZK circuit proves four things simult
 
 ### Proof 3: "I am authorized"
 
-**Problem:** How to prove you're in the signers list without revealing which one?
+**Problem:** How to prove you're in the signers list?
 
 **Solution:**
 - Each signer has a secret "commitment" stored as: `commitment = hash(secret, secret)`
-- All commitments form a [Merkle Tree](https://en.wikipedia.org/wiki/Merkle_tree)
-- You prove your commitment exists in the tree WITHOUT revealing which leaf
+- The circuit proves you know the secret for a given commitment
+- The smart contract checks if that commitment exists in the signers list
 
-**Analogy:** Imagine a club membership list. You prove "my name is on the list" without pointing to which line.
+**Analogy:** Imagine a club membership list. You prove "I know the password for one of these memberships" and the club verifies that membership is on the list.
 
-**How Merkle Proof works:**
+**How it works:**
 
-You have a tree structure where your commitment is one of the leaves (A, B, C, or D). To prove membership, you provide sibling hashes along the path from your leaf to the root. The circuit computes the root from your path and checks it matches the public root.
+The circuit verifies: `hash(secret, secret) == commitment`
+
+Then the smart contract checks: `commitment in signers list?`
+
+This two-step verification ensures only authorized signers can sign transactions while keeping their Ethereum addresses private.
 
 ### Proof 4: "I haven't signed before"
 
@@ -72,11 +76,11 @@ You have a tree structure where your commitment is one of the leaves (A, B, C, o
 
 1. **User Signs:** User signs tx_hash with their Ethereum wallet → Produces signature, pub_key_x, pub_key_y
 
-2. **Frontend Generates Proof:** [Noir](https://noir-lang.org) circuit receives private inputs (signature, pub_key, secret, merkle_path, tx_hash) and public inputs (tx_hash_commitment, merkle_root, nullifier) → Outputs ZK Proof
+2. **Frontend Generates Proof:** [Noir](https://noir-lang.org) circuit receives private inputs (signature, pub_key, secret, tx_hash) and public inputs (tx_hash_commitment, commitment, nullifier) → Outputs ZK Proof
 
 3. **Backend Verifies via zkVerify:** Proof submitted to [zkVerify](https://docs.zkverify.io) for verification → Returns aggregation_id, attestation
 
-4. **Smart Contract Executes:** When threshold signatures reached, contract verifies all proofs on-chain, checks nullifiers not used, checks merkle_root matches current signers, then executes transaction
+4. **Smart Contract Executes:** When threshold signatures reached, contract verifies all proofs on-chain, checks nullifiers not used, checks each commitment is in current signers list, then executes transaction
 
 ## Circuit Inputs Reference
 
@@ -88,16 +92,14 @@ You have a tree structure where your commitment is one of the leaves (A, B, C, o
 | pub_key_x | [u8; 32] | Public key X coordinate |
 | pub_key_y | [u8; 32] | Public key Y coordinate |
 | secret | Field | Signer's secret (from signing "polypay-identity") |
-| leaf_index | Field | Position in Merkle tree |
-| merkle_path | [Field; 4] | Sibling hashes for proof |
 | tx_hash_bytes | [u8; 32] | Transaction hash to sign |
 
 ### Public Inputs (Visible on-chain)
 
 | Input | Type | Description |
 |-------|------|-------------|
 | tx_hash_commitment | Field | Poseidon hash of tx_hash |
-| merkle_root | Field | Root of authorized signers tree |
+| commitment | Field | hash(secret, secret) - checked against signers list |
 | nullifier | Field | Prevents double-signing |
 
 ## More Detail

docs/developer-documentation/circuit-code-walkthrough.md

@@ -9,18 +9,15 @@ import axios from 'axios';
 import * as fs from 'fs';
 import * as path from 'path';
 import {
-  SubmitProofDto,
   ZkVerifySubmitResponse,
   ZkVerifyJobStatusResponse,
-  ProposeTxAndSubmitProofDto,
-  SignTxDto,
 } from './dto';
 import { PrismaService } from '@/database/prisma.service';
 
 @Injectable()
 export class ZkVerifyService {
   private readonly logger = new Logger(ZkVerifyService.name);
-  private readonly apiUrl = 'https://relayer-api-testnet.horizenlabs.io/api/v1';
+  private readonly apiUrl = 'https://api-testnet.kurier.xyz/api/v1';
   private readonly apiKey: string;
   private readonly vkeyPath: string;