wownero-lws/README.md

# wownero-lws

> This is a fork of [monero-lws](https://github.com/vtnerd/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](#introduction)
  - [About this project](#about-this-project)
  - [Changes from monero-lws](#changes-from-monero-lws)
  - [License](#license)
  - [Compiling from source](#compiling-from-source)
  - [Running wownero-lws](#running-wownero-lws)
  - [Docker](#docker)
  - [Deployment](#deployment)
  - [Syncing with upstream monero-lws](#syncing-with-upstream-monero-lws)
  - [Contributing](#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](https://github.com/vtnerd/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](LICENSE).


## Compiling from source

### Dependencies

Install the [dependencies required by Wownero](https://codeberg.org/wownero/wownero#dependencies).
These are inherited transitively by wownero-lws.

**Ubuntu/Debian:**
```bash
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.

```bash
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)

```bash
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:

```bash
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:

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

### Starting the daemon

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

```bash
./wownero-lws-daemon --version
```

### Adding accounts

Use `wownero-lws-admin` to manage wallet accounts:

```bash
# 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](https://github.com/vtnerd/monero-lws#rest-api) for full API details.


## Docker

### Building the image

```bash
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`:

```yaml
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:
```

```bash
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

```nginx
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:
```bash
./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)

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

### Updating from upstream

```bash
# 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](https://github.com/vtnerd) for creating and maintaining monero-lws
- The Monero Project for the core cryptographic libraries
- The Wownero community for testing and feedback