wownero-lws

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.

Table of Contents

• 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 can link against it. However, the standard Wownero build uses OBJECT libraries, which are not compatible with wownero-lws's linking requirements.

You have two options:

Option A: Use the LWS-compatible Wownero fork (easiest)

git clone https://codeberg.org/jw_wow/wownero.git
cd wownero
git checkout lws-compat-fix
git submodule update --init --recursive
mkdir -p build && cd build
cmake -DCMAKE_BUILD_TYPE=Release ..
make -j$(nproc)

This fork adds 3 commits that force static library generation (liblmdb_lib.a, etc.) which wownero-lws requires.

Then build wownero-lws:

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/Linux/master/release ..
make -j$(nproc)

Option B: Use the submodule method (no fork needed)

The Quick Build method above uses Wownero as a submodule and builds it internally with the correct settings. This is the recommended approach if you don't need to link against a specific wownerod binary.

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

1. TLS Certificate: Use Let's Encrypt or similar for the REST API
2. Firewall: Only expose port 8443 (REST API) publicly
3. Reverse Proxy: Consider nginx/caddy in front for rate limiting
4. Backups: Regularly backup ~/.wownero/light_wallet_server/
5. 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:

1. Ensure you are building wownero-lws against the exact same version of the Wownero source code that your daemon uses.
2. Use the Advanced Build instructions to point CMake to your local Wownero source tree using -DWOWNERO_SOURCE_DIR=/path/to/wownero.
3. Do not use -DMonero_DIR, as this variable is ignored by wownero-lws.
4. 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:

1. Check if your wownerod is fully synced and on the correct chain.
2. 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

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

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

Links

• Wownero: https://wownero.org
• Wownero Codeberg: https://codeberg.org/wownero
• Upstream monero-lws: https://github.com/vtnerd/monero-lws
• Wownero Discord: https://discord.gg/ykZyAzJhDK
• Wownero Reddit: https://reddit.com/r/wownero

Acknowledgments

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