Builds/wownero-lws
1
0
Fork 0
forked from such-gitea/wownero-lws
Code Pull Requests Actions Activity

Port monero-lws to wownero-lws

Browse Source 
Adapts monero-lws for Wownero cryptocurrency:

- Rename all monero-lws-* binaries to wownero-lws-*
- Update submodule to point to official Wownero repo
- Use Wownero default ports (RPC: 34568, ZMQ: 34569)
- Update data directory to ~/.wownero/light_wallet_server
- Adapt next_difficulty() calls for Wownero API signature

Key technical changes for Wownero compatibility:

- BulletproofPlus (RCTTypeBulletproofPlus, type 8) commitment verification:
  Wownero stores BP+ commitments in 'divided by 8' form. Must call
  rct::scalarmult8() on outPk commitment before comparing with computed
  commitment (mask*G + amount*H). This is essential for amount decryption.

- Pass rct_type to decode_amount() for proper commitment handling

- Handle Wownero's ZMQ JSON format for ecdhTuple (32-byte mask/amount fields)

No fork of Wownero is required - uses official codeberg.org/wownero/wownero.
This commit is contained in:
jwinterm
2026-01-04 13:12:56 -05:00
parent f2b3534002
commit 3427c60315
35 changed files with 789 additions and 395 deletions
Download Patch File Download Diff File Expand all files Collapse all files

443
README.md
View File

@@ -1,44 +1,74 @@
# monero-lws
# wownero-lws
> This project is **NOT** a part of the official monero "core" code, but will
> hopefully be merged into that project as a new repository seperate from the
> [`monero-project/monero`](https://github.com/monero-project/monero)
> repository.
> 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)
- [Compiling Monero-lws from source](#compiling-monero-lws-from-source)
- [Deployment](#deployment)
- [Syncing with upstream monero-lws](#syncing-with-upstream-monero-lws)
- [Contributing](#contributing)
## Introduction
Monero is a private, secure, untraceable, decentralised digital currency. You are your bank, you control your funds, and nobody can trace your transfers unless you allow them to do so.
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:** Monero uses a cryptographically sound system to allow you to send and receive funds without your transactions being easily revealed on the blockchain (the ledger of transactions that everyone has). This ensures that your purchases, receipts, and all transfers remain absolutely private by default.
**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. Wallet files are encrypted with a passphrase to ensure they are useless if stolen.
**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, a special property of a certain type of cryptography, Monero is able to ensure 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.
**Decentralization:** The utility of monero depends on its decentralised peer-to-peer consensus network - anyone should be able to run the monero software, validate the integrity of the blockchain, and participate in all aspects of the monero network using consumer-grade commodity hardware. Decentralization of the monero network is maintained by software development that minimizes the costs of running the monero software and inhibits the proliferation of specialized, non-commodity hardware.
**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 [Monero light-wallet REST API](https://github.com/monero-project/meta/blob/master/api/lightwallet_rest.md)
(i.e. MyMonero compatible). Clients can submit their Monero viewkey via the REST
API, and the server will scan for incoming Monero blockchain transactions.
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.
Differences from [OpenMonero](https://github.com/moneroexamples/openmonero):
- LMDB instead of MySQL
**Features:**
- LMDB database (no MySQL required)
- View keys stored in database - scanning occurs continuously in background
- Uses ZeroMQ interface to `monerod` with chain subscription ("push") support
- Uses amd64 ASM acceleration from Monero project, if available
- 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
@@ -46,127 +76,302 @@ Differences from [OpenMonero](https://github.com/moneroexamples/openmonero):
See [LICENSE](LICENSE).
## Docker
Data is stored at `/home/monero-lws/.bitmonero/light_wallet_server` by default,
and be modified by `--db-path` at runtime.
### Latest Stable Release
Docker image for latest stable release can be fetched via:
* `docker pull ghcr.io/vtnerd/monero-lws`
* `docker pull vtnerd/monero-lws`
Users of this tag should never expect a DB migration issue, provided they never
"downgrade" to a prior major version.
### Supported Releases
Docker images for `0` and `0.3` are provided. The major number refers to
backwards incompatible DB changes, and the minor revision refers to new features
that could cause instability. Stability minded users can use these tags while
they are still listed as officially supported here in the README or on the
Docker overview page.
* `docker pull ghcr.io/vtnerd/monero-lws:0`
* `docker pull vtnerd/monero-lws:0`
* `docker pull ghcr.io/vtnerd/monero-lws:0.3`
* `docker pull vtnerd/monero-lws:0.3`
### Alpha Release
Docker image for the `master` (alpha) branch can be fetched via:
* `docker pull ghcr.io/vtnerd/monero-lws:master`
* `docker pull vtnerd/monero-lws:master`
This branch differs from the `develop` branch in that users should NOT expect
incompatible DB changes; if users never "roll-back" their copy of `master` then
the DB should also be in a valid state for use. However, the `master` version
is considered alpha software so things could break, resulting in complications
if the DB was not saved prior to upgrading.
We need alpha testers, so consider using this where possible!
> The `develop` branch should only be used for development purposes - breaking
> DB changes are expected (but probably rare). No docker image is provided for
> this branch - see compilation section below.
## Compiling Monero-lws from source
## Compiling from source
### Dependencies
The first step, when buiding from source, is installing the [dependencies of the
monero project](https://github.com/monero-project/monero?tab=readme-ov-file#dependencies).
`monero-lws` depends on the monero project for building, so the dependencies of
that project become the dependencies of this project transitively. Only the
"non-vendored" dependencies need to be installed. There are no additional
dependencies that need installing.
Install the [dependencies required by Wownero](https://codeberg.org/wownero/wownero#dependencies).
These are inherited transitively by wownero-lws.
### Beginner Build
**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
```
The easiest method for building is to use git submodules to pull in the correct
Monero project dependency:
### Quick Build (Recommended)
This builds using the official Wownero source as a submodule. No custom fork is needed.
```bash
git clone https://github.com/vtnerd/monero-lws.git
mkdir monero-lws/build && cd monero-lws/build
git submodule update --init --recursive
cmake -DCMAKE_BUILD_TYPE=Release ../
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)
```
* On macOS replace `-j$(nproc)` with `-j8` or the number of cores on your
system.
* Each branch (`master`, and `develop`) should have the correct submodule for
building that particular branch.
* The `submodule` step is being run inside of the `monero-lws` directory, such
that all of vendored dependencies are automatically fetched.
* The instructions above will compile the `master` (beta) release of
`monero-lws`
* The resulting executables can be found in `monero-lws/build/src`
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
### Advanced Build (Separate Wownero tree)
The monero source and build directories can be manually specified, which cuts
the build time in half and potentially re-uses the same source tree for multiple
builds. The process for advanced building is:
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`.
```bash
git clone https://github.com/monero-project/monero.git
git clone https://github.com/vtnerd/monero-lws.git
mkdir monero-lws/build
mkdir monero/build && cd monero/build
git submodule update --init --recursive
cmake -DCMAKE_BUILD_TYPE=Release ../
make -j$(nproc) daemon multisig lmdb_lib
cd ../../monero-lws/build
cmake -DCMAKE_BUILD_TYPE=Relase -DMONERO_SOURCE_DIR=../../monero -DMONERO_BUILD_DIR=../../monero/build ../
# 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)
```
The `master`/`develop` branches of lws should compile against the `master`
branch of monero. The release branches specify which monero branch to compile
against - `release-v0.3_0.18` indicates that monero `0.18` should be used as
the source directory. The [beginner build process](#beginner-build) handles all
of this with git submodules.
* On macOS replace `-j$(nproc)` with `-j8` or the numebr of cores on your
system.
* Notice that the `submodule` step is only being run in the `monero` project;
`monero-lws` intentionally does not initialize submodules in the advanced
mode of building.
* The instructions above will compile the `master` (beta) release of
`monero-lws`.
* The resulting executables can be found in `build/src`
## Running wownero-lws
## Running monero-lws-daemon
### Prerequisites
The build places the binary in `src/` sub-directory within the build directory
from which cmake was invoked (repository root by default). To run in
foreground:
You need a running `wownerod` with ZMQ enabled:
```bash
./src/monero-lws-daemon
wownerod --zmq-pub tcp://127.0.0.1:34569
```
To list all available options, run `./src/monero-lws-daemon --help`.
### 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