Skip to main content

​
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 (16 bytes = 32 hex characters)
openssl rand -hex 16 > 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-app.git
cd l2ps-poc-app
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

  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

# 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:
MetricExpected
Proofs in DB~5 (1 per batch of 10)
L1 batch transactions~5
Mempool statusconfirmed
Total fees burned50 DEM

​
Environment Configuration

VariableDescriptionDefault
L2PS_AGGREGATION_INTERVAL_MSBatch check interval10000 (10s)
L2PS_MIN_BATCH_SIZEMin transactions to batch1
L2PS_MAX_BATCH_SIZEMax transactions per batch10
L2PS_CLEANUP_AGE_MSCleanup confirmed after300000 (5m)

​
Troubleshooting

Check data/l2ps/<uid>/config.json exists and JSON is valid.
Ensure private_key.txt and iv.txt exist with valid hex values (64 and 32 chars respectively).
POC .env keys must exactly match node key files. Use the auto-copy command above.
Remember: L2PS requires amount + 1 DEM fee. Fund wallet first.
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 16 > 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-app.git
cd l2ps-poc-app && 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

L2PS Architecture

Understand the complete L2PS architecture

L2PS SDK

Integrate L2PS into your application