mirror of
https://github.com/vtnerd/monero-lws.git
synced 2024-09-28 19:41:03 +00:00
initial documentation
This commit is contained in:
Lee Clagett
parent
e99374170f
commit
21a9c9a8da
3 changed files with 278 additions and 0 deletions
30
LICENSE
Normal file
30
LICENSE
Normal file
|
|
@ -0,0 +1,30 @@
|
||||||
|
Copyright (c) 2018-2020, The Monero Project
|
||||||
|
|
||||||
|
All rights reserved.
|
||||||
|
|
||||||
|
Redistribution and use in source and binary forms, with or without
|
||||||
|
modification, are permitted provided that the following conditions are met:
|
||||||
|
|
||||||
|
1. Redistributions of source code must retain the above copyright notice, this
|
||||||
|
list of conditions and the following disclaimer.
|
||||||
|
|
||||||
|
2. Redistributions in binary form must reproduce the above copyright notice,
|
||||||
|
this list of conditions and the following disclaimer in the documentation
|
||||||
|
and/or other materials provided with the distribution.
|
||||||
|
|
||||||
|
3. Neither the name of the copyright holder nor the names of its contributors
|
||||||
|
may be used to endorse or promote products derived from this software without
|
||||||
|
specific prior written permission.
|
||||||
|
|
||||||
|
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
|
||||||
|
ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
|
||||||
|
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
|
||||||
|
DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
|
||||||
|
FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
|
||||||
|
DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
|
||||||
|
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
|
||||||
|
CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
|
||||||
|
OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
|
||||||
|
OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
|
||||||
|
|
||||||
|
|
||||||
141
README.md
Normal file
141
README.md
Normal file
|
|
@ -0,0 +1,141 @@
|
||||||
|
# monero-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.
|
||||||
|
|
||||||
|
## Table of Contents
|
||||||
|
|
||||||
|
- [Introduction](#introduction)
|
||||||
|
- [About this project](#about-this-project)
|
||||||
|
- [License](#license)
|
||||||
|
- [Compiling Monero-lws from source](#compiling-monero-lws-from-source)
|
||||||
|
- [Dependencies](#dependencies)
|
||||||
|
|
||||||
|
|
||||||
|
## 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.
|
||||||
|
|
||||||
|
**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.
|
||||||
|
|
||||||
|
**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.
|
||||||
|
|
||||||
|
**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.
|
||||||
|
|
||||||
|
|
||||||
|
## 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.
|
||||||
|
|
||||||
|
Differences from [OpenMonero](https://github.com/moneroexamples/openmonero):
|
||||||
|
- LMDB instead of MySQL
|
||||||
|
- View keys stored in database - scanning occurs continuously in background
|
||||||
|
- Uses ZeroMQ interface to `monerod` ("push" support coming soon)
|
||||||
|
- Uses amd64 ASM acceleration from Monero project, if available
|
||||||
|
|
||||||
|
|
||||||
|
## License
|
||||||
|
|
||||||
|
See [LICENSE](LICENSE).
|
||||||
|
|
||||||
|
|
||||||
|
## Compiling Monero-lws from source
|
||||||
|
|
||||||
|
### Dependencies
|
||||||
|
|
||||||
|
The following table summarizes the tools and libraries required to build. A
|
||||||
|
few of the libraries are also included in this repository (marked as
|
||||||
|
"Vendored"). By default, the build uses the library installed on the system,
|
||||||
|
and ignores the vendored sources. However, if no library is found installed on
|
||||||
|
the system, then the vendored source will be built and used. The vendored
|
||||||
|
sources are also used for statically-linked builds because distribution
|
||||||
|
packages often include only shared library binaries (`.so`) but not static
|
||||||
|
library archives (`.a`).
|
||||||
|
|
||||||
|
| Dep | Min. version | Vendored | Debian/Ubuntu pkg | Arch pkg | Void pkg | Fedora pkg | Optional | Purpose |
|
||||||
|
| ------------ | ------------- | -------- | -------------------- | ------------ | ------------------ | ------------------- | -------- | --------------- |
|
||||||
|
| GCC | 4.7.3 | NO | `build-essential` | `base-devel` | `base-devel` | `gcc` | NO | |
|
||||||
|
| CMake | 3.1 | NO | `cmake` | `cmake` | `cmake` | `cmake` | NO | |
|
||||||
|
| Boost | 1.58 | NO | `libboost-all-dev` | `boost` | `boost-devel` | `boost-devel` | NO | C++ libraries |
|
||||||
|
| monero | 0.15 | NO | | | | | NO | Monero libraries|
|
||||||
|
| OpenSSL | basically any | NO | `libssl-dev` | `openssl` | `libressl-devel` | `openssl-devel` | NO | sha256 sum |
|
||||||
|
| libzmq | 3.0.0 | NO | `libzmq3-dev` | `zeromq` | `zeromq-devel` | `zeromq-devel` | NO | ZeroMQ library |
|
||||||
|
| Doxygen | any | NO | `doxygen` | `doxygen` | `doxygen` | `doxygen` | YES | Documentation |
|
||||||
|
| Graphviz | any | NO | `graphviz` | `graphviz` | `graphviz` | `graphviz` | YES | Documentation |
|
||||||
|
|
||||||
|
Install all dependencies (except `monero-project/monero`) at once on Debian/Ubuntu:
|
||||||
|
|
||||||
|
``` sudo apt update && sudo apt install build-essential cmake libboost-all-dev libssl-dev libzmq3-dev doxygen graphviz```
|
||||||
|
|
||||||
|
FreeBSD 12.1 one-liner required to build dependencies:
|
||||||
|
```pkg install git gmake cmake pkgconf boost-libs libzmq4```
|
||||||
|
|
||||||
|
### Cloning the repository
|
||||||
|
|
||||||
|
Clone recursively to pull-in needed submodule(s):
|
||||||
|
|
||||||
|
`$ git clone --recursive https://github.com/vtnerd/monero-lws.git`
|
||||||
|
|
||||||
|
If you already have a repo cloned, initialize and update:
|
||||||
|
|
||||||
|
`$ cd monero-lws && git submodule init && git submodule update`
|
||||||
|
|
||||||
|
### Build instructions
|
||||||
|
|
||||||
|
Monero uses the CMake build system and a top-level [Makefile](Makefile) that
|
||||||
|
invokes cmake commands as needed.
|
||||||
|
|
||||||
|
#### On Linux and macOS
|
||||||
|
|
||||||
|
* Install the dependencies. The [`monero`](https://github.com/monero-project/monero)
|
||||||
|
dependency should be cloned and built according to the `README.md` of that
|
||||||
|
project.
|
||||||
|
* Change to the root of the source code directory, change to the most recent develop branch, and build:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
cd monero-lws
|
||||||
|
git checkout develop
|
||||||
|
mkdir build && cd build
|
||||||
|
cmake -DMONERO_SOURCE_DIR=~/monero -DMONERO_BUILD_DIR=~/monero/build ..
|
||||||
|
make
|
||||||
|
```
|
||||||
|
|
||||||
|
*Optional*: If your machine has several cores and enough memory, enable
|
||||||
|
parallel build by running `make -j<number of threads>` instead of `make`. For
|
||||||
|
this to be worthwhile, the machine should have one core and about 2GB of RAM
|
||||||
|
available per thread.
|
||||||
|
|
||||||
|
*Note*: The instructions above will compile the development release of the
|
||||||
|
Monero-lws software.
|
||||||
|
|
||||||
|
* The resulting executables can be found in `build/src`
|
||||||
|
|
||||||
|
* Add `PATH="$PATH:$HOME/monero-lws/build/src"` to `.profile`
|
||||||
|
|
||||||
|
* Run Monero-lws with `monero-lws-daemon`
|
||||||
|
|
||||||
|
Dependencies need to be built with -fPIC. Static libraries usually aren't, so you may have to build them yourself with -fPIC. Refer to their documentation for how to build them.
|
||||||
|
|
||||||
|
* **Optional**: build documentation in `doc/html` (omit `HAVE_DOT=YES` if `graphviz` is not installed):
|
||||||
|
|
||||||
|
```bash
|
||||||
|
HAVE_DOT=YES doxygen Doxyfile
|
||||||
|
```
|
||||||
|
|
||||||
|
## Running monero-lws-daemon
|
||||||
|
|
||||||
|
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:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
./src/monero-lws-daemon
|
||||||
|
```
|
||||||
|
|
||||||
|
To list all available options, run `./src/monero-lws-daemon --help`.
|
||||||
107
docs/administration.md
Normal file
107
docs/administration.md
Normal file
|
|
@ -0,0 +1,107 @@
|
||||||
|
# Using monero-lws-admin
|
||||||
|
|
||||||
|
The `monero-lws-admin` executable is used to administer the database used by
|
||||||
|
`monero-lws-daemon`. Any number of `monero-lws-admin` instances can run
|
||||||
|
concurrently with a single `monero-lws-daemon` instance on the same database.
|
||||||
|
Administration is necessary to authorize new accounts and rescan requests
|
||||||
|
submitted from the REST API. The admin executable can also be used to list
|
||||||
|
the contents of the LMDB file for debugging purposes.
|
||||||
|
|
||||||
|
# Basics
|
||||||
|
|
||||||
|
The `monero-lws-admin` utility is structured around command-line arguments with
|
||||||
|
JSON responses printed to `stdout`. Each administration command takes arguments
|
||||||
|
by position - the design makes it potentially compatible with a JSON or MsgPack
|
||||||
|
array (as used in JSON-RPC, etc). Every available administration command and
|
||||||
|
required+optional arguments are listed when the `--help` flag is given to the
|
||||||
|
executable.
|
||||||
|
|
||||||
|
The [`jq`](https://stedolan.github.io/jq/) utility is recommended if using
|
||||||
|
`monero-lws-admin` in a shell environment. The `jq` program can be used for
|
||||||
|
indenting the output to make it more readable, and can be used to
|
||||||
|
search+filter the JSON output from the command.
|
||||||
|
|
||||||
|
# Examples
|
||||||
|
|
||||||
|
**List every active Monero address on a newline:**
|
||||||
|
```bash
|
||||||
|
monero-lws-admin list_accounts | jq -r '.active | .[] | .address'
|
||||||
|
```
|
||||||
|
|
||||||
|
**Auto-accept every pending account creation request:**
|
||||||
|
```bash
|
||||||
|
monero-lws-admin accept_requests create $(monero-lws-admin list_requests | jq -j '.create? | .[]? | .address?+" "')
|
||||||
|
```
|
||||||
|
|
||||||
|
# Debugging
|
||||||
|
|
||||||
|
`monero-lws-admin` has a debug mode that dumps everything stored in the
|
||||||
|
database, except the blockchain hashes are always truncated and viewkeys are
|
||||||
|
omitted by default (a command-line flag can enable viewkey output). Most of
|
||||||
|
the array outputs are sorted to accelerate `jq` filtering and search queries.
|
||||||
|
|
||||||
|
## Indexes
|
||||||
|
|
||||||
|
- **blocks_by_id** - array of objects sorted by block height.
|
||||||
|
- **accounts_by_status,id** - A single object where account status names are
|
||||||
|
keys. Each value is an array of objects sorted by account id.
|
||||||
|
- **accounts_by_address** - A single object where account addresses are keys.
|
||||||
|
Each value is an object containing the status and account id for the account
|
||||||
|
for lookup in `accounts_by_status,id`. The majority of account lookups should
|
||||||
|
be done by this id (an integer).
|
||||||
|
- **accounts_by_height,id** - An array of objects sorted by block height. These
|
||||||
|
objects contain another array of objects sorted by account id.
|
||||||
|
- **outputs_by_account_id,block_id,tx_hash,output_id** - An object where keys
|
||||||
|
are account ids. Each value is an array of objects sorted by block height,
|
||||||
|
transaction hash, then by output number.
|
||||||
|
- **spends_by_account_id,block_id,tx_hash,image** - An object where keys are
|
||||||
|
account ids. Each value is an array of objects sorted by block height,
|
||||||
|
transaction hash, then by key image.
|
||||||
|
- **requests_by_type,address** - An object where keys are request type, and
|
||||||
|
each value is an array of objects sorted by address.
|
||||||
|
|
||||||
|
## Examples
|
||||||
|
|
||||||
|
**List every key-image associated with every account:**
|
||||||
|
```bash
|
||||||
|
monenero-lws-admin debug_database | jq '."spends_by_account_id,block_id,tx_hash,output_id" | map_values([.[] | .image])'
|
||||||
|
```
|
||||||
|
will output something like:
|
||||||
|
```json
|
||||||
|
{"1":["image1", "image2",...],"2":["image1","image2"...],...}
|
||||||
|
```
|
||||||
|
|
||||||
|
**List every account that received XMR in a given transaction hash:**
|
||||||
|
```bash
|
||||||
|
monenero-lws-admin debug_database | jq '."outputs_by_account_id,block_id,tx_hash,output_id" | map_values(select([.[] | .tx_hash == "hash"] | any)) | keys'
|
||||||
|
```
|
||||||
|
will output somethng like:
|
||||||
|
```json
|
||||||
|
{"1",...}
|
||||||
|
```
|
||||||
|
|
||||||
|
**Add total received XMR for every account**:
|
||||||
|
```bash
|
||||||
|
monenero-lws-admin debug_database | jq '."outputs_by_account_id,block_id,tx_hash,output_id" | map_values([.[] | .amount] | add)'
|
||||||
|
```
|
||||||
|
will output something like:
|
||||||
|
```json
|
||||||
|
{"1":6346,"2":45646}
|
||||||
|
```
|
||||||
|
|
||||||
|
# Extending Administration in monero-lws
|
||||||
|
|
||||||
|
## JSON via `stdin`
|
||||||
|
|
||||||
|
Some commands take sensitive information such as private view keys, and
|
||||||
|
therefore reading arguments from `stdin` via JSON array would also be useful for
|
||||||
|
those situations. This should be a relatively straightforward adaptation given
|
||||||
|
the design of the positional arguments.
|
||||||
|
|
||||||
|
## Administration via ZeroMQ
|
||||||
|
|
||||||
|
The LMDB database does account lookups by view-public only, so that CurveZMQ
|
||||||
|
(which uses curve25519) can be used to authenticate an administration account
|
||||||
|
without additional protocol overhead. The parameters to administration commands
|
||||||
|
can be sent via JSON or MsgPack array since the functions already use positional
|
||||||
|
arguments.
|
||||||
Loading…
Reference in a new issue