> For the complete documentation index, see [llms.txt](https://q3labs.gitbook.io/polypay-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://q3labs.gitbook.io/polypay-docs/zk-authentication.md).

# ZK Authentication

### Traditional vs ZK Authentication

| Aspect       | Traditional Auth                | PolyPay                                 |
| ------------ | ------------------------------- | --------------------------------------- |
| Login method | Password or wallet signature    | ZK proof of secret knowledge            |
| Server knows | Password hash or public address | Only the membership ID (hash of secret) |
| Each login   | Send password/sign message      | Generate fresh ZK proof                 |

### Identity Generation

Your identity is based on a **secret** derived from your wallet:

1. Sign a specific message with your wallet (one-time setup)
2. Derive a **secret** from the signature
3. Compute **membership ID** = `poseidon_hash(secret, secret)`
4. Store the membership ID on-chain as your identifier

### Login Flow

| Step | Action                                                                         |
| ---- | ------------------------------------------------------------------------------ |
| 1    | User generates secret                                                          |
| 2    | Client generates ZK proof: "I know a secret that hashes to this membership ID" |
| 3    | Proof submitted to zkVerify network                                            |
| 4    | Backend verifies attestation from zkVerify                                     |
| 5    | Backend issues JWT tokens (access + refresh)                                   |

### Why ZK?

* **Secret never leaves your device** - only the proof is sent
* **Server cannot impersonate you** - knowing the membership ID is not enough
* **No password database to leak** - server stores nothing sensitive
* **Stateless verification** - proof is self-contained