This is a fork of monero-lws adapted for the Wownero cryptocurrency. We aim to stay compatible with upstream changes to ease merging of security and feature updates.

Introduction
About this project
Changes from monero-lws
License
Compiling from source
Running wownero-lws
Docker
Deployment
Syncing with upstream monero-lws
Contributing

Introduction

Wownero is a privacy-focused, CPU-mineable cryptocurrency and a "fun" fork of Monero. It uses the RandomWOW proof-of-work algorithm and shares Monero's commitment to privacy and decentralization.

Privacy: Wownero uses a cryptographically sound system to allow you to send and receive funds without your transactions being easily revealed on the blockchain. This ensures that your purchases, receipts, and all transfers remain absolutely private by default.

Security: Using the power of a distributed peer-to-peer consensus network, every transaction on the network is cryptographically secured. Individual wallets have a 25 word mnemonic seed that is only displayed once, and can be written down to backup the wallet.

Untraceability: By taking advantage of ring signatures, Wownero ensures that transactions are not only untraceable, but have an optional measure of ambiguity that ensures that transactions cannot easily be tied back to an individual user or computer.

About this project

This is an implementation of the light-wallet REST API for Wownero, adapted from monero-lws. Clients can submit their Wownero viewkey via the REST API, and the server will scan for incoming Wownero blockchain transactions.

Features:

LMDB database (no MySQL required)
View keys stored in database - scanning occurs continuously in background
Uses ZeroMQ interface to wownerod with chain subscription ("push") support
Supports webhook notifications, including "0-conf" notification
Compatible with MyMonero-style light wallet clients

Changes from monero-lws

This fork includes the following modifications to support Wownero:

Component	Change
Submodule	`external/monero` points to `codeberg.org/wownero/wownero`
Build system	All CMake targets renamed from `monero-lws-` to `wownero-lws-`
Libraries	Links against Wownero libraries (includes RandomWOW PoW)
Difficulty	Updated `next_difficulty()` calls for Wownero's API signature
Default ports	RPC: 34568, ZMQ: 34569 (Wownero defaults)
Data directory	Uses `~/.wownero/light_wallet_server`
RingCT decryption	BulletproofPlus commitments require `scalarmult8()` (see below)

Wownero BulletproofPlus Commitment Format

Wownero stores BulletproofPlus (RCTTypeBulletproofPlus, type 8) output commitments in a "divided by 8" form for efficiency. When verifying decrypted amounts, the commitment from outPk must be multiplied by 8 using rct::scalarmult8() before comparing with the computed commitment mask*G + amount*H.

This differs from standard Monero and is the key change required for amount decryption to work on Wownero's post-HF18 transactions.

The directory structure is kept identical to upstream to simplify rebasing.

License

See LICENSE.

Compiling from source

Dependencies

Install the dependencies required by Wownero. These are inherited transitively by wownero-lws.

Ubuntu/Debian:

sudo apt update && sudo apt install -y \
  build-essential cmake git pkg-config \
  libboost-all-dev libssl-dev libzmq3-dev \
  libunbound-dev libsodium-dev libpgm-dev \
  libhidapi-dev libusb-1.0-0-dev libprotobuf-dev \
  protobuf-compiler libudev-dev

Quick Build (Recommended)

This builds using the official Wownero source as a submodule. No custom fork is needed.

git clone --recursive https://codeberg.org/wownero/wownero-lws.git
cd wownero-lws
mkdir build && cd build
cmake -DCMAKE_BUILD_TYPE=Release ..
make -j$(nproc)

The binaries will be in build/src/:

wownero-lws-daemon - Main server daemon
wownero-lws-admin - Administration tool
wownero-lws-client - Client utility

Advanced Build (Separate Wownero tree)

If you already have a Wownero source tree built (e.g. you compiled wownerod yourself), you should link against it to ensure binary compatibility.

Important: Use WOWNERO_SOURCE_DIR, not Monero_DIR.

# Assuming wownero is built at ~/wownero/build
git clone https://codeberg.org/wownero/wownero-lws.git
cd wownero-lws
mkdir build && cd build
cmake -DCMAKE_BUILD_TYPE=Release \
  -DWOWNERO_SOURCE_DIR=~/wownero \
  -DWOWNERO_BUILD_DIR=~/wownero/build ..
make -j$(nproc)

Running wownero-lws

Prerequisites

You need a running wownerod with ZMQ enabled:

wownerod --zmq-pub tcp://127.0.0.1:34569

Starting the daemon

./wownero-lws-daemon \
  --daemon=tcp://127.0.0.1:34568 \
  --sub=tcp://127.0.0.1:34569 \
  --log-level=1

Command-line options

Option	Description	Default
`--daemon`	wownerod RPC address	`tcp://127.0.0.1:34568`
`--sub`	wownerod ZMQ pub address	`tcp://127.0.0.1:34569`
`--db-path`	LMDB database path	`~/.wownero/light_wallet_server`
`--rest-server`	REST API bind address	`https://0.0.0.0:8443`
`--rest-ssl-key`	SSL private key file	(required for HTTPS)
`--rest-ssl-cert`	SSL certificate file	(required for HTTPS)
`--log-level`	Log verbosity (0-4)	`0`
`--help`	Show all options

Verify installation

./wownero-lws-daemon --version

Adding accounts

Use wownero-lws-admin to manage wallet accounts:

# Add a new account
./wownero-lws-admin add_account <primary_address> <view_key>

# List all accounts
./wownero-lws-admin list_accounts

# Check account status
./wownero-lws-admin account_status <primary_address>

# Accept a pending account request
./wownero-lws-admin accept_requests create <primary_address>

# Rescan account from specific height
./wownero-lws-admin rescan <height> <primary_address>

REST API

The REST API is compatible with MyMonero-style light wallet clients.

Endpoint	Method	Description
`/login`	POST	Authenticate with address + view key
`/get_address_info`	POST	Get account balance and status
`/get_address_txs`	POST	Get transaction history
`/get_unspent_outs`	POST	Get spendable outputs
`/get_random_outs`	POST	Get decoy outputs for ring signatures
`/submit_raw_tx`	POST	Broadcast a signed transaction
`/import_request`	POST	Request account import from genesis

See the monero-lws documentation for full API details.

Docker

Building the image

git clone https://codeberg.org/wownero/wownero-lws.git
cd wownero-lws
docker build -t wownero-lws .

Running with Docker Compose

Create docker-compose.yml:

version: '3.8'
services:
  wownerod:
    image: wownero/wownerod:latest
    command: >
      --non-interactive
      --zmq-pub tcp://0.0.0.0:34569
      --rpc-bind-ip 0.0.0.0
      --confirm-external-bind
    volumes:
      - wownerod-data:/home/wownero/.wownero
    ports:
      - "34567:34567"  # P2P
      - "34568:34568"  # RPC

  wownero-lws:
    image: wownero-lws:latest
    command: >
      --daemon=tcp://wownerod:34568
      --sub=tcp://wownerod:34569
      --log-level=1
    volumes:
      - wownero-lws-data:/home/wownero-lws/.wownero
    ports:
      - "8443:8443"
    depends_on:
      - wownerod

volumes:
  wownerod-data:
  wownero-lws-data:

docker-compose up -d

Deployment

Production Checklist

TLS Certificate: Use Let's Encrypt or similar for the REST API
Firewall: Only expose port 8443 (REST API) publicly
Reverse Proxy: Consider nginx/caddy in front for rate limiting
Backups: Regularly backup ~/.wownero/light_wallet_server/
Monitoring: Monitor disk space (LMDB can grow large)

Example nginx config

server {
    listen 443 ssl http2;
    server_name lws.example.com;

    ssl_certificate /etc/letsencrypt/live/lws.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/lws.example.com/privkey.pem;

    location / {
        proxy_pass http://127.0.0.1:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

Then run wownero-lws with HTTP internally:

./wownero-lws-daemon --rest-server http://127.0.0.1:8080 ...

Syncing with upstream monero-lws

This project is designed to be rebased on upstream vtnerd/monero-lws updates.

Setup (one-time)

cd wownero-lws
git remote add upstream https://github.com/vtnerd/monero-lws.git
git fetch upstream

Updating from upstream

# Fetch latest upstream changes
git fetch upstream

# Rebase our changes on top of upstream master
git checkout main
git rebase upstream/master

# Resolve any conflicts, then:
git rebase --continue

# Force push to update the fork
git push --force-with-lease origin main

Common conflict areas

When rebasing, conflicts typically occur in:

CMakeLists.txt - variable names (MONERO vs WOWNERO)
src/scanner.cpp - API differences (e.g., next_difficulty signature)
Dockerfile - paths and image names

The goal is to keep Wownero-specific changes minimal and isolated.

Troubleshooting

"Unable to sync blockchain - wrong --network ?"

If you see this error immediately upon starting wownero-lws-daemon, it usually indicates a mismatch between the Wownero source code used to build LWS and the wownerod daemon you are connecting to.

Solution:

Ensure you are building wownero-lws against the exact same version of the Wownero source code that your daemon uses.
Use the Advanced Build instructions to point CMake to your local Wownero source tree using -DWOWNERO_SOURCE_DIR=/path/to/wownero.
Do not use -DMonero_DIR, as this variable is ignored by wownero-lws.
After rebuilding, you must delete your LWS database (default: ~/.wownero/light_wallet_server) and let it resync from scratch.

"Blockchain reorg detected" loop

If the scanner gets stuck in a loop detecting reorgs at a specific block height:

Check if your wownerod is fully synced and on the correct chain.
This can also be caused by the build mismatch described above (LWS calculating different block hashes than the daemon). Follow the rebuild steps above.

Contributing

Fork the repository on Codeberg
Create a feature branch: git checkout -b my-feature
Commit your changes: git commit -am 'Add feature'
Push to the branch: git push origin my-feature
Submit a Pull Request

Please ensure your changes don't break the ability to rebase on upstream.

Acknowledgments

vtnerd for creating and maintaining monero-lws
The Monero Project for the core cryptographic libraries
The Wownero community for testing and feedback

README.md

wownero-lws

Table of Contents