> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kynesys.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# L2PS Quick Start

> Complete guide to set up and test L2PS (Layer 2 Privacy Subnets) with ZK proofs.

# L2PS Quick Start Guide

This guide walks you through setting up L2PS from scratch on your Demos node.

## Prerequisites

* Running Demos node
* Node.js 18+
* Docker (for PostgreSQL)

## 1. Create L2PS Network

### Create Configuration Directory

```bash theme={null}
mkdir -p data/l2ps/testnet_l2ps_001
```

### Generate Encryption Keys

```bash theme={null}
# Generate AES-256 key (32 bytes = 64 hex characters)
openssl rand -hex 32 > data/l2ps/testnet_l2ps_001/private_key.txt

# Generate IV (12 bytes = 24 hex characters — AES-GCM standard)
openssl rand -hex 12 > data/l2ps/testnet_l2ps_001/iv.txt
```

### Create Config File

Create `data/l2ps/testnet_l2ps_001/config.json`:

```json theme={null}
{
  "uid": "testnet_l2ps_001",
  "enabled": true,
  "config": {
    "created_at_block": 0,
    "known_rpcs": ["http://127.0.0.1:53550"]
  },
  "keys": {
    "private_key_path": "data/l2ps/testnet_l2ps_001/private_key.txt",
    "iv_path": "data/l2ps/testnet_l2ps_001/iv.txt"
  }
}
```

## 2. ZK Proof Setup (Optional)

ZK proofs provide cryptographic verification of L2PS batch validity.

<Info>
  Without ZK keys, the system still works but batches are submitted without proofs (graceful degradation).
</Info>

### Install Circom

```bash theme={null}
curl -Ls https://scrypt.io/scripts/setup-circom.sh | sh
```

### Generate ZK Keys

```bash theme={null}
npm run l2ps:zk:setup
```

This generates:

* `keys/batch_5/` - For 1-5 tx batches (\~37K constraints)
* `keys/batch_10/` - For 6-10 tx batches (\~74K constraints)

## 3. Start Node

```bash theme={null}
./run
```

Look for these logs:

```
[L2PS] Loaded network: testnet_l2ps_001
[L2PS Batch Aggregator] Started
```

## 4. Test with POC App

The POC app provides a visual interface to test L2PS transactions.

<Info>
  The L2PS POC app is available as a [separate repository](https://github.com/kynesyslabs/l2ps-poc). Clone it to test your L2PS setup.
</Info>

### Install and Run

```bash theme={null}
# Clone the POC app (separate repository)
git clone https://github.com/kynesyslabs/l2ps-poc.git
cd l2ps-poc
npm install
npm run dev
# Open http://localhost:5173
```

### Configure Keys

Create `.env` file in the POC app directory:

```bash theme={null}
VITE_NODE_URL="http://127.0.0.1:53550"
VITE_L2PS_UID="testnet_l2ps_001"
VITE_L2PS_AES_KEY="<contents of private_key.txt>"
VITE_L2PS_IV="<contents of iv.txt>"
```

<Warning>
  **Critical**: Client keys MUST exactly match node keys. Copy the key values from your node's L2PS configuration:

  ```bash theme={null}
  # From your node directory, copy key contents
  cat data/l2ps/testnet_l2ps_001/private_key.txt
  cat data/l2ps/testnet_l2ps_001/iv.txt
  ```

  Paste these values into your POC app's `.env` file.
</Warning>

## 5. Send Test Transactions

### Via POC App

1. Generate or enter a mnemonic
2. Connect wallet
3. Toggle to **L2PS (Private)** mode
4. Enter recipient and amount
5. Click **Send L2PS Transaction**

### Via CLI

```bash theme={null}
# Quick test (5 transactions)
npx tsx scripts/send-l2-batch.ts --uid testnet_l2ps_001

# Load test (50 transactions)
npx tsx scripts/l2ps-load-test.ts --uid testnet_l2ps_001 --count 50
```

## 6. Verify Results

Wait for batch aggregation, then check:

### Check Proofs

```bash theme={null}
docker exec -it postgres_5332 psql -U demosuser -d demos -c \
  "SELECT id, l2ps_uid, transaction_count, status FROM l2ps_proofs ORDER BY id DESC LIMIT 10;"
```

### Check Mempool Status

```bash theme={null}
docker exec -it postgres_5332 psql -U demosuser -d demos -c \
  "SELECT status, COUNT(*) FROM l2ps_mempool GROUP BY status;"
```

### Expected Results

For 50 transactions:

| Metric                | Expected                |
| --------------------- | ----------------------- |
| Proofs in DB          | \~5 (1 per batch of 10) |
| L1 batch transactions | \~5                     |
| Mempool status        | confirmed               |
| Total fees burned     | 50 DEM                  |

## Environment Configuration

| Variable                       | Description                | Default     |
| ------------------------------ | -------------------------- | ----------- |
| `L2PS_AGGREGATION_INTERVAL_MS` | Batch check interval       | 10000 (10s) |
| `L2PS_MIN_BATCH_SIZE`          | Min transactions to batch  | 1           |
| `L2PS_MAX_BATCH_SIZE`          | Max transactions per batch | 10          |
| `L2PS_CLEANUP_AGE_MS`          | Cleanup confirmed after    | 300000 (5m) |

## Troubleshooting

<AccordionGroup>
  <Accordion title="L2PS config not found">
    Check `data/l2ps/<uid>/config.json` exists and JSON is valid.
  </Accordion>

  <Accordion title="Missing L2PS key material">
    Ensure `private_key.txt` and `iv.txt` exist with valid hex values (64 and 24 chars respectively).
  </Accordion>

  <Accordion title="Client keys don't match node">
    POC `.env` keys must exactly match node key files. Use the auto-copy command above.
  </Accordion>

  <Accordion title="Insufficient balance">
    Remember: L2PS requires `amount + 1 DEM` fee. Fund wallet first.
  </Accordion>

  <Accordion title="ZK Prover not available">
    Run `npm run l2ps:zk:setup`. System works without ZK (graceful degradation).
  </Accordion>
</AccordionGroup>

## Complete Setup Checklist

```bash theme={null}
# 1. Create L2PS network
mkdir -p data/l2ps/testnet_l2ps_001
openssl rand -hex 32 > data/l2ps/testnet_l2ps_001/private_key.txt
openssl rand -hex 12 > data/l2ps/testnet_l2ps_001/iv.txt

# 2. Create config.json (see section 1)

# 3. Optional: Setup ZK proofs
npm run l2ps:zk:setup

# 4. Start node
./run

# 5. Setup POC app (separate repository)
git clone https://github.com/kynesyslabs/l2ps-poc.git
cd l2ps-poc && npm install

# 6. Configure POC .env with your node's L2PS keys
# Copy key values from: data/l2ps/testnet_l2ps_001/private_key.txt and iv.txt

# 7. Run POC
npm run dev
```

## Next Steps

<CardGroup cols={2}>
  <Card title="L2PS Architecture" icon="sitemap" href="./overview">
    Understand the complete L2PS architecture
  </Card>

  <Card title="L2PS SDK" icon="code" href="../../sdk/websdk/l2ps-sdk/overview">
    Integrate L2PS into your application
  </Card>
</CardGroup>