README.md 3.92 KB
Newer Older
zeroleak's avatar
zeroleak committed
1 2 3
[![Build Status](https://travis-ci.org/Samourai-Wallet/whirlpool-server.svg?branch=develop)](https://travis-ci.org/Samourai-Wallet/whirlpool-server)
[![](https://jitpack.io/v/Samourai-Wallet/whirlpool-server.svg)](https://jitpack.io/#Samourai-Wallet/whirlpool-server)

TDevD's avatar
TDevD committed
4
# whirlpool-server
zeroleak's avatar
zeroleak committed
5 6 7

Server for [Whirlpool](https://github.com/Samourai-Wallet/Whirlpool) by Samourai-Wallet.

zeroleak's avatar
zeroleak committed
8 9
## Installation
See [README-install.md](README-install.md)
zeroleak's avatar
zeroleak committed
10 11 12

## Configuration
### RPC client
zeroleak's avatar
zeroleak committed
13
```
14
server.rpc-client.protocol = http
zeroleak's avatar
zeroleak committed
15
server.rpc-client.host = CONFIGURE-ME
16
server.rpc-client.port = CONFIGURE-ME
zeroleak's avatar
zeroleak committed
17 18 19
server.rpc-client.user = CONFIGURE-ME
server.rpc-client.password = CONFIGURE-ME
```
zeroleak's avatar
zeroleak committed
20 21
The bitcoin node should be running on the same network (main or test).<br/>
The node will be used to verify UTXO and broadcast tx.
zeroleak's avatar
zeroleak committed
22

zeroleak's avatar
zeroleak committed
23
### Pool: UTXO amounts
zeroleak's avatar
zeroleak committed
24
```
zeroleak's avatar
zeroleak committed
25 26 27 28
server.pools[x].denomination: amount in satoshis
server.pools[x].miner-fee-min: minimum miner-fee accepted for mustMix
server.pools[x].miner-fee-max: maximum miner-fee accepted for mustMix
server.pools[x].miner-fee-cap: "soft cap" miner-fee recommended for a new mustMix (should be <= miner-fee-max)
zeroleak's avatar
zeroleak committed
29
```
30 31 32
UTXO should be founded with:<br/>
for mustMix: (*server.mix.denomination* + *server.mix.miner-fee-min*) to (*server.mix.denomination* + *server.mix.miner-fee-max*)<br/>
for liquidities: (*server.mix.denomination*) to (*server.mix.denomination* + *server.mix.miner-fee-max*)
zeroleak's avatar
zeroleak committed
33

zeroleak's avatar
zeroleak committed
34 35 36 37

### Pool: TX0 fees
```
server.pools[x].fee-value: server fee (in satoshis) for each tx0
38
server.pools[x].fee-accept: alternate fee values accepted (key=fee in sats, value=maxTx0Time)
zeroleak's avatar
zeroleak committed
39 40
```
Standard fee configuration is through *fee-value*.
41
*fee-accept* is useful when changing *fee-value*, to still accept unspent tx0s <= maxTx0Time with previous fee-value.
zeroleak's avatar
zeroleak committed
42 43


44 45 46 47 48 49
### UTXO confirmations
```
server.register-input.min-confirmations-must-mix: minimum confirmations for mustMix inputs
server.register-input.min-confirmations-liquidity: minimum confirmations for liquidity inputs
```

50 51 52 53 54
### UTXO rules
```
server.register-input.max-inputs-same-hash: max inputs with same hash (same origin tx) allowed to register to a mix
```

zeroleak's avatar
zeroleak committed
55 56 57 58 59 60 61 62 63 64
### SCodes
```
server.samourai-fees.feePayloadByScode[foo] = 12345
server.samourai-fees.feePayloadByScode[bar] = 23456
```
Scodes are special codes usable to enable special rules for tx0.
Each scode is mapped in configuration to a short value (-32,768 to 32,767) which will be embedded into tx0's OP_RETURN as WhirlpoolFeeData.feePayload.
Multiple scode can be mapped to same short value.
Forbidden short value is '0', which is mapped to WhirlpoolFeeData.feePayload=NULL.

zeroleak's avatar
zeroleak committed
65
### Pool: Mix limits
zeroleak's avatar
zeroleak committed
66
```
zeroleak's avatar
zeroleak committed
67 68 69 70
server.pools[x].anonymity-set-target = 10
server.pools[x].anonymity-set-min = 6
server.pools[x].anonymity-set-max = 20
server.pools[x].anonymity-set-adjust-timeout = 120
zeroleak's avatar
zeroleak committed
71

zeroleak's avatar
zeroleak committed
72 73
server.pools[x].must-mix-min = 1
server.pools[x].liquidity-timeout = 60
zeroleak's avatar
zeroleak committed
74
```
zeroleak's avatar
zeroleak committed
75 76
Mix will start when *anonymity-set-target* (mustMix + liquidities) are registered.<br/>
If this target is not met after *anonymity-set-adjust-timeout*, it will be gradually decreased to *anonymity-set-min*.<br/>
zeroleak's avatar
zeroleak committed
77

zeroleak's avatar
zeroleak committed
78
At the beginning of the mix, only mustMix can register. Meanwhile, liquidities connecting are placed on a waiting pool.<br/>
zeroleak's avatar
zeroleak committed
79
After *liquidity-timeout* or when current *anonymity-set-target* is reached, liquidities are added as soon as *must-mix-min* is reached, up to *anonymity-set-max* inputs for the mix.
80

81 82 83 84 85 86 87
### Exports
Each mix success/fail is appended to a CSV file:
```
server.export.mixs.directory
server.export.mixs.filename
```

88 89 90
### Testing
```
server.rpc-client.mock-tx-broadcast = false
zeroleak's avatar
zeroleak committed
91
server.test-mode = false
92
```
93
For testing purpose, *server.rpc-client.mock-tx-broadcast* can be enabled to mock txs instead of broadcasting it.
zeroleak's avatar
zeroleak committed
94
When enabled, *server.test-mode* allows client to bypass tx0 checks.
95

zeroleak's avatar
zeroleak committed
96 97 98 99
## 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)