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

mkdir -p data/l2ps/testnet_l2ps_001

Generate Encryption Keys

# 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:

{
  "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.

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

Install Circom

curl -Ls https://scrypt.io/scripts/setup-circom.sh | sh

Generate ZK Keys

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

./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.

The L2PS POC app is available as a separate repository. Clone it to test your L2PS setup.

Install and Run

# 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:

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>"

Critical: Client keys MUST exactly match node keys. Copy the key values from your node’s L2PS configuration:

# 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.

5. Send Test Transactions

Via POC App

Generate or enter a mnemonic
Connect wallet
Toggle to L2PS (Private) mode
Enter recipient and amount
Click Send L2PS Transaction

Via CLI

# 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

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

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

L2PS config not found

Check data/l2ps/<uid>/config.json exists and JSON is valid.

Missing L2PS key material

Ensure private_key.txt and iv.txt exist with valid hex values (64 and 24 chars respectively).

Client keys don't match node

POC .env keys must exactly match node key files. Use the auto-copy command above.

Insufficient balance

Remember: L2PS requires amount + 1 DEM fee. Fund wallet first.

ZK Prover not available

Run npm run l2ps:zk:setup. System works without ZK (graceful degradation).

Complete Setup Checklist

# 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

​L2PS Quick Start Guide

​Prerequisites

​1. Create L2PS Network

​Create Configuration Directory

​Generate Encryption Keys

​Create Config File

​2. ZK Proof Setup (Optional)

​Install Circom

​Generate ZK Keys

​3. Start Node

​4. Test with POC App

​Install and Run

​Configure Keys

​5. Send Test Transactions

​Via POC App

​Via CLI

​6. Verify Results

​Check Proofs

​Check Mempool Status

​Expected Results

​Environment Configuration

​Troubleshooting

​Complete Setup Checklist

​Next Steps

L2PS Architecture

L2PS SDK

L2PS Quick Start Guide

Prerequisites

1. Create L2PS Network

Create Configuration Directory

Generate Encryption Keys

Create Config File

2. ZK Proof Setup (Optional)

Install Circom

Generate ZK Keys

3. Start Node

4. Test with POC App

Install and Run

Configure Keys

5. Send Test Transactions

Via POC App

Via CLI

6. Verify Results

Check Proofs

Check Mempool Status

Expected Results

Environment Configuration

Troubleshooting

Complete Setup Checklist

Next Steps