# 🦀 zkip

> Zero-knowledge proof library for proving IP location privacy.

## Changelog

### 0.1.0

* Initial release
* ZK Proof Core implementation
* CLI with `--ip`, `--exclude`, `--refresh` flags
* EVM-compatible proofs (Groth16/PLONK)


## Privacy Model

| Party              | Sees IP?                | Stores IP? |
| :----------------- | :---------------------- | :--------- |
| User               | ✅ (their own)           | N/A        |
| Your Server        | ✅ (transient in memory) | ❌ No       |
| SP1 Prover Network | ✅ (during computation)  | ❌ No       |

**Note**: The SP1 Prover Network is a compute service, not a blockchain. Inputs are processed in memory and discarded after proof generation.


## What is zkip?

**zkip** is a zero-knowledge proof library for proving a user's IP address is **not** from a specified set of countries without revealing the actual IP address. Built with [SP1](https://github.com/succinctlabs/sp1) zkVM.

### Motivation

Many businesses and developers end up storing IP addresses for various reasons:

* Regulatory compliance (tax laws, content licensing, gambling restrictions)
* Proving user location to auditors
* Fraud prevention and geo-restrictions
* Analytics and service customization

But storing IP addresses creates privacy concerns and GDPR obligations. **What if you could prove location without storing the IP?**

(For example: In France, digital service providers must charge VAT on all sales unless they can prove the customer's location. This typically requires storing IP addresses, which is a privacy concern.)

**zkip's solution**: Generate a zero-knowledge proof that verifies "this IP is not from countries X, Y, Z" without revealing or storing the actual IP address. You get verifiable location proofs while keeping user data private.


## Installation

### Requirements

* [Rust](https://rustup.rs/)
* [SP1](https://docs.succinct.xyz/docs/sp1/getting-started/install)

### Clone the Repository

```sh
git clone https://github.com/nahiiko/zkip.git
cd zkip
```


## Quick Start

### 1. Build the Program

```sh
cd program && cargo prove build
```

Or let it build automatically when running the script.

### 2. Execute (No Proof)

Test the logic without generating a proof:

```sh
cargo run --release -- --execute --ip 8.8.8.8 --exclude FR,US
```

This runs the ZK circuit locally and outputs the result without generating a cryptographic proof.

### 3. Generate a Proof (Local)

```sh
cargo run --release -- --prove --ip 8.8.8.8 --exclude FR
```

Local proving is slow (minutes to hours depending on hardware). For production, use the network.

### 4. Use the Prover Network

The [Succinct Prover Network](https://docs.succinct.xyz/docs/sp1/prover-network/quickstart) provides fast, distributed proof generation.

**Setup:**

1. Generate a key pair: `cast wallet new` (or export from Metamask)
2. Get [PROVE tokens](https://docs.succinct.xyz/docs/sp1/prover-network/quickstart) on Ethereum Mainnet
3. Deposit PROVE at [Succinct Explorer](https://explorer.succinct.xyz/)
4. Configure environment:

```sh
cp .env.example .env
```

```env
SP1_PROVER=network
NETWORK_PRIVATE_KEY=0x...  # Your requester account private key
```

5. Run:

```sh
cargo run --release -- --prove --ip 8.8.8.8 --exclude FR
```


## On-Chain Verification

Coming soon...


## REST API

Coming soon...


## Flow

```
┌──────────────┐                    ┌──────────────┐                    ┌──────────────┐
│              │                    │              │                    │              │
│     User     │                    │  Your API    │                    │ SP1 Prover   │
│ (0x123...)   │                    │   (zkip)     │                    │              │
│              │                    │              │                    │              │
└──────┬───────┘                    └──────┬───────┘                    └──────┬───────┘
       │                                   │                                   │
       │  POST /prove                      │                                   │
       │  {excluded: ["FR", "DE"],         │                                   │
       │   wallet: "0x123..."}             │                                   │
       ├──────────────────────────────────▶│                                   │
       │                                   │                                   │
       │                                   │  Extract IP from TCP connection   │
       │                                   │  Load IP-to-country range table   │
       │                                   │                                   │
       │                                   │  Private: IP + range table        │
       │                                   │  Public: excluded countries       │
       │                                   ├──────────────────────────────────▶│
       │                                   │                                   │
       │                                   │                                   │  ZK Circuit:
       │                                   │                                   │  1. Lookup IP
       │                                   │                                   │  2. Check country
       │                                   │                                   │  3. Output result
       │                                   │                                   │
       │                                   │  proof + is_excluded              │
       │                                   │◀──────────────────────────────────┤
       │                                   │                                   │
       │  Discard IP from memory           │                                   │
       │                                   │                                   │
       │  {proof, is_excluded, timestamp}  │                                   │
       │◀──────────────────────────────────┤                                   │
       │                                   │                                   │
       │  Store proof for audit            │                                   │
       │  (No IP ever stored)              │                                   │
       │                                   │                                   │
```

**Flow Steps:**

1. **User Request**: Client sends excluded countries list and wallet address
2. **IP Extraction**: Server extracts IP from TCP connection (transient, in memory only)
3. **Proof Generation**: SP1 Prover runs ZK circuit with:
   * **Private inputs**: User's IP address + full country range table
   * **Public inputs**: List of excluded countries
4. **Circuit Execution**: Proves IP is NOT in any excluded country
5. **Response**: Server returns proof and result, then discards IP from memory
6. **Audit Trail**: User stores proof for compliance (without revealing IP)


## Architecture Overview

```
┌─────────────────────────────────────────────────────────────────────────────┐
│                              ARCHITECTURE                                    │
└─────────────────────────────────────────────────────────────────────────────┘

┌──────────────┐     POST /prove            ┌──────────────────┐
│              │   {excluded: ["FR","DE"]}  │                  │
│    User      │ ─────────────────────────▶ │    Your API      │
│  (Browser)   │                            │     (zkip)       │
│              │                            │                  │
│  IP: hidden  │                            │ Extracts IP from │
│              │                            │ TCP connection   │
│              │                            └────────┬─────────┘
│              │                                     │
│              │                                     │ IP + country ranges
│              │                                     │ (private inputs)
│              │                                     ▼
│              │                            ┌──────────────────┐
│              │                            │                  │
│              │   {                        │   SP1 Prover     │
│              │     is_excluded: true,     │   (local or      │
│              │     proof: "0xabc...",     │    network)      │
│              │     timestamp: "..."       │                  │
│              │   }                        │ Runs ZK circuit: │
│              │                            │ IP ∉ excluded?   │
│              │ ◀──────────────────────────┤                  │
│              └────────────────────────────┴──────────────────┘
```


## API Reference

### Future Design

```
POST /prove

Request:
{
  "excluded_countries": ["FR", "DE", "IT"],  // Countries to prove absence from
  "user_id": "0x123..."                      // Optional: wallet or identifier
}

Response:
{
  "is_excluded": true,                       // IP not in any excluded country
  "proof": "0xabc...",                       // ZK proof
  "timestamp": "2025-12-18T12:00:00Z"
}
```