# 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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://q3labs.gitbook.io/polypay-docs/zk-authentication.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.