Skip to content

GitLab

Commit cbd398e8 authored by zeroleak's avatar zeroleak
Browse files

update documentation

parent 07729cc1
Hide whitespace changes
Inline Side-by-side
Showing with 164 additions and 153 deletions
README-ADVANCED.md deleted 100644 → 0
View file @ 07729cc1
# whirlpool-client-cli for advanced users
## Advanced usage
#### Debugging
- ```--debug```: debug logs
- ```--debug-client```: more debug logs
- ```--dump-payload```: dump pairing-payload of current wallet and exit
Any problem with a remote CLI? Test it locally:
- Configure CLI manually: ```java -jar whirlpool-client-cli-xxx-run.jar --debug --init```
- Then start it with manual authentication: ```java -jar whirlpool-client-cli-xxx-run.jar --debug --authenticate```
#### Log file
You can configure a log file in whirlpool-cli-config.properties:
```
logging.file = /tmp/whirlpool-cli.log
```
See this doc for advanced log settings (rotation, limits...):
https://docs.spring.io/spring-boot/docs/current/reference/html/spring-boot-features.html#boot-features-logging-file-output
#### Testing loop
You can run CLI in loop mode on testnet to generate liquidity on testnet server:
- run TX0 while possible
- mix while possible
- consolidate wallet when PREMIX is empty and start again
```
--clients=5 --auto-tx0=0.01btc --tx0-max-outputs=15 --mixs-target=100 --scode=
```
Adjust mixing rate with ```cli.mix.clientDelay = 60```
Generate simultaneous liquidity with ```cli.mix.clientsPerPool = 5```
## Whirlpool integration
#### Authenticate on startup
You can authenticate in several ways:
- ```--authenticate```: manually type your passphrase on startup
- ```--listen```: use the GUI or API to authenticate remotely
For security reasons, you should not store your passphrase anywhere. If you really need to automate authentication process, use this at your own risk:
```
export PP="mypassphrase"
echo $PP|java -jar whirlpool-client-cli-x-run.jar --authenticate
```
#### Configuration override
Configuration can be overriden in whirlpool-cli-config.properties (see default configuration in [src/main/resources/application.properties]).
Or with equivalent argument:
```
--cli.tor=true --cli.apiKey=foo...
```
Or with following arguments:
- ```--scode=```: scode to use for tx0
- ```--tx0-max-outputs=```: tx0 outputs limit
- ```--auto-tx0=[poolId]```: run tx0 from deposit utxos automatically
- ```--auto-mix=[true/false]```: mix premix utxos automatically
#### Custom Tor configuration
Tor should be automatically detected, installed or configured. You can customize it for your needs:
```
cli.torConfig.executable = /path/to/bin/tor
```
- Use `auto` to use embedded tor, or detecting a local Tor install when your system is not supported.
- Use `local` to detect a local tor install.
- Use custom path to `tor` binary to use your own tor build.
Custom config can be appended to Torrc with:
```
cli.torConfig.customTorrc = /path/to/torrc
```
Tor can be enabled with:
```
cli.tor = true # global toggle
cli.torConfig.coordinator.enabled = true # enable for whirlpool coordinator
cli.torConfig.backend.enabled = true # enable for wallet backend
```
Tor mode can be customized with:
```
cli.torConfig.coordinator.onion = true # whirlpool server
cli.torConfig.backend.onion = true # wallet backend
```
- `true`: Tor hidden services
- `false`: clearnet over Tor
Tor startup timeout can be customized with:
```
cli.torConfig.fileCreationTimeout = 20 # 20s
```
## Build instructions
Build with maven:
```
cd whirlpool-client-cli
mvn clean install -Dmaven.test.skip=true
```
\ No newline at end of file
README.md
View file @ cbd398e8
......@@ -2,12 +2,12 @@
# whirlpool-client-cli
Command line client for [Whirlpool](https://github.com/Samourai-Wallet/Whirlpool) by Samourai-Wallet.
Command line client for [Whirlpool](https://code.samourai.io/whirlpool/whirlpool) by Samourai-Wallet.
## Getting started
#### Download and verify CLI
- Download whirlpool-client-cli-\[version\]-run.jar from [releases](https://github.com/Samourai-Wallet/whirlpool-client-cli/releases)
- Download whirlpool-client-cli-\[version\]-run.jar from [releases](https://code.samourai.io/whirlpool/whirlpool-client-cli/-/releases)
- Verify sha256 hash of the jar with signed message in whirlpool-client-cli-\[version\]-run.jar.sig
- Verify signature with [@SamouraiDev](https://github.com/SamouraiDev) 's key
......@@ -21,22 +21,15 @@ You can setup whirlpool-client-cli in 2 ways:
java -jar target/whirlpool-client-version-run.jar
```
Optional arguments:
- ```--listen```: enable API for remote commands & GUI. Authentication on startup is optional, but you can authenticate on startup with --authenticate
- ```--mixs-target```: minimum number of mixs to achieve per UTXO
- ```--authenticate```: will ask for your passphrase at startup
- ```--list-pools```: list pools and exit
#### Advanced
See [README-API.md](README-API.md) to manage whirlpool-client-cli remotely with REST API.
See [README-ADVANCED.md](README-ADVANCED.md) for advanced usage, integration and development.
- [doc/USAGE.md](doc/USAGE.md) for CLI usage.
- [doc/API.md](doc/API.md) to manage CLI remotely.
- [doc/CONFIG.md](doc/CONFIG.md) for advanced usage, integration and development.
- [doc/DEV.md](doc/DEV.md) for developers.
## Resources
* [whirlpool](https://github.com/Samourai-Wallet/Whirlpool)
* [whirlpool-protocol](https://github.com/Samourai-Wallet/whirlpool-protocol)
* [whirlpool-client](https://github.com/Samourai-Wallet/whirlpool-client)
* [whirlpool-server](https://github.com/Samourai-Wallet/whirlpool-server)
* [whirlpool](https://code.samourai.io/whirlpool/Whirlpool)
* [whirlpool-protocol](https://code.samourai.io/whirlpool/whirlpool-protocol)
* [whirlpool-client](https://code.samourai.io/whirlpool/whirlpool-client)
* [whirlpool-server](https://code.samourai.io/whirlpool/whirlpool-server)
README-API.md → doc/API.md
View file @ cbd398e8
# whirlpool-client-cli API
## Using REST API
whirlpool-client-cli exposes a REST API over HTTPS when started with --listen.
HTTPS port is defined in `whirlpool-cli-config.properties`:
```
cli.api.port=8899
```
Clear HTTP can be enabled at your own risk:
```
cli.api.http-enable=true
cli.api.http-port=8898
```
#### API KEY
API key is configured in ```whirlpool-cli-config.properties```.
It can be overriden with ```--api-key=```
## Using CLI API
whirlpool-client-cli exposes a REST API when started with --listen (see [CONFIG.md](CONFIG.md) for configuration).
It can be used by whirlpool-gui or any REST client.
#### Required headers
* apiVersion (see [CliApi.java](src/main/java/com/samourai/whirlpool/cli/api/protocol/CliApi.java))
* apiKey
#### HTTPS cert
REST API uses a self-signed certificate for HTTPS. It can be downloaded by opening https://CLI-HOST:8899/ with Firefox, then Advanced -> View certificate -> Download PEM.
* apiKey (configured in ```whirlpool-cli-config.properties```)
You can configure your own cert in `whirlpool-cli-config.properties`:
```
server.ssl.key-store-type=PKCS12 or JKS
server.ssl.key-store=</path/to/keystore>
server.ssl.key-store-password=<passord>
server.ssl.key-alias=<alias in keystore>
```
## Pools
......
doc/CONFIG.md 0 → 100644
View file @ cbd398e8
# whirlpool-client-cli configuration
CLI is configured in `whirlpool-cli-config.properties` or with equivalent argument:
```
--cli.tor=true --cli.apiKey=foo...
```
Default configuration is [src/main/resources/application.properties].
#### Basic
| Setting | Default value | Description |
| ----------- | ----------- | ----------- |
| cli.server | TESTNET | Bitcoin network (TESTNET or MAINNET) |
| cli.apiKey | *generated on --init* | Secret key for using CLI API |
| cli.seed | *generated on --init* | Wallet seed encrypted with passphrase (AES) |
| cli.seedAppendPassphrase | true | Append passphrase as additional seed word |
| cli.tor | false | Enable Tor |
| cli.dojo.enabled | false | Enable Dojo as wallet backend |
| cli.version | *generated* | Technical setting for tracking CLI upgrades |
| cli.scode | - | SCODE for discount Whirlpool fees |
| cli.mix.mixsTarget | - | Mixs limit per UTXO (0 for unlimited) |
| cli.mix.autoMix | true | Automatically (re)mix premix & postmix. When disabled, each utxo must be mixed manually. |
#### Dojo
| Setting | Default value | Description |
| ----------- | ----------- | ----------- |
| cli.dojo.url | - | Dojo url |
| cli.dojo.apiKey | - | Dojo API key |
#### Logs
| Setting | Default value | Description |
| ----------- | ----------- | ----------- |
| logging.file | - | Enable external log (/tmp/whirlpool-cli.log) |
See advanced log settings (rotation, limits...):
https://docs.spring.io/spring-boot/docs/current/reference/html/spring-boot-features.html#boot-features-logging-file-output
#### Tor
Tor should be automatically detected, installed or configured.
You can customize it for your needs:
| Setting | Default value | Description |
| ----------- | ----------- | ----------- |
| cli.torConfig.coordinator.enabled | true | Enable Tor for whirlpool coordinator (when cli.tor=true) |
| cli.torConfig.backend.enabled | true | Enable Tor for wallet backend (when cli.tor=true) |
| cli.torConfig.coordinator.onion | true | Use Tor hidden services (instead of clearnet over Tor) for whirlpool server |
| cli.torConfig.backend.onion | true | Use Tor hidden services (instead of clearnet over Tor) for wallet backend |
| cli.torConfig.executable | auto | `auto` : use embedded tor or detect a local Tor install when your system is not supported. |
| | | `local` : detect a local tor install|
| | | `/path/to/bin/tor` : use your own tor binary|
| cli.torConfig.customTorrc | | `/path/to/torrc` : custom tor configuration to append to Torrc|
| cli.torConfig.fileCreationTimeout | 20 | Tor startup timeout (in seconds)|
#### CLI API
whirlpool-client-cli exposes a REST API over HTTPS when started with --listen (see [API.md](API.md)).
It can be exposed over HTTP at your own risk.
| Setting | Default value | Description |
| ----------- | ----------- | ----------- |
| cli.api.port | 8899 | Port for CLI API over HTTPS (when started with --listen) |
| cli.api.http-enable | false | Enable unsecure CLI API over HTTP (not recommended, use it at your own risk!) |
| cli.api.http-port | 8898 | Port for unsecure CLI API over HTTP (when started with --listen and cli.api.http-enable=true) |
#### CLI API certificate
By default CLI API uses a self-signed certificate for HTTPS, which can be downloaded by opening https://CLI-HOST:8899/ with Firefox, then Advanced -> View certificate -> Download PEM.
You can configure your own cert:
| Setting | Default value | Description |
| ----------- | ----------- | ----------- |
| server.ssl.key-store | classpath:keystore/whirlpool.p12 | Path to your own keystore |
| server.ssl.key-store-type | PKCS12 | Keystore type: PKCS12 or JKS |
| server.ssl.key-store-password | whirlpool | Keystore password |
| server.ssl.key-alias | whirlpool | Alias in keystore |
#### Technical settings
| Setting | Default value | Description |
| ----------- | ----------- | ----------- |
| cli.proxy | - | Custom proxy to connect through. |
| cli.requestTimeout | 30000 | HTTP requests timeout |
| cli.tx0MinConfirmations | 0 | Confirmations required for TX0 |
| cli.mix.clients | 5 | Max simultaneous mixing clients |
| cli.mix.clientsPerPool | 1 | Max simultaneous mixing clients per pool |
| cli.mix.tx0MaxOutputs | 0 | Max premixs to create per TX0 (0 for unlimited) |
| cli.mix.clientDelay | 15 | Connecting delay (seconds) between each mixing client |
| cli.mix.tx0Delay | 30 | Delay (seconds) between each tx0 (when --auto-tx0) |
doc/DEV.md 0 → 100644
View file @ cbd398e8
# whirlpool-client-cli for developers
## Build instructions
Build with maven:
```
cd whirlpool-client-cli
mvn clean install -Dmaven.test.skip=true
```
#### Testing loop
You can run CLI in loop mode on testnet to generate liquidity on testnet server:
- automatically run TX0 while possible
- mix while possible
- consolidate wallet when PREMIX is empty and start again
```
--clients=5 --auto-tx0=0.01btc --tx0-max-outputs=15 --mixs-target=100 --scode=
```
Adjust mixing rate with ```cli.mix.clientDelay = 60```
Generate simultaneous liquidity with ```cli.mix.clientsPerPool = 5```
doc/USAGE.md 0 → 100644
View file @ cbd398e8
# whirlpool-client-cli usage
#### Basic
| Argument | Default value | Description |
| ----------- | ----------- | ----------- |
| --init | - | Initialize CLI (by setting wallet seed and generating API key) |
| --authenticate | - | Enable interactive authentication on startup |
| --listen | - | Enable CLI API for remote commands & GUI (see [API.md](API.md))|
| --list-pools | - | List pools and exit|
| --dump-payload | - | Dump pairing-payload of current wallet and exit |
#### Debugging
| Argument | Default value | Description |
| ----------- | ----------- | ----------- |
| --debug | - | Enable debug logs for CLI |
| --debug-client | - | Enable debug logs for whirlpool-client |
Any problem with a remote CLI? Test it locally:
- Configure CLI manually: ```java -jar whirlpool-client-cli-xxx-run.jar --debug --init```
- Then start it with manual authentication: ```java -jar whirlpool-client-cli-xxx-run.jar --debug --authenticate```
#### Authenticate on startup
You can authenticate in several ways:
For security reasons, you should not store your passphrase anywhere. If you really need to automate authentication process, use this at your own risk:
```
export PP="mypassphrase"
echo $PP|java -jar whirlpool-client-cli-x-run.jar --authenticate
```
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment