README.md 4.76 KB
Newer Older
zeroleak's avatar
zeroleak committed
1
[![](https://jitpack.io/v/io.samourai.code.whirlpool/whirlpool-server.svg)](https://jitpack.io/#io.samourai.code.whirlpool/whirlpool-server)
zeroleak's avatar
zeroleak committed
2

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

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

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

## Configuration
### RPC client
zeroleak's avatar
zeroleak committed
12
```
13
server.rpc-client.protocol = http
zeroleak's avatar
zeroleak committed
14
server.rpc-client.host = CONFIGURE-ME
15
server.rpc-client.port = CONFIGURE-ME
zeroleak's avatar
zeroleak committed
16 17 18
server.rpc-client.user = CONFIGURE-ME
server.rpc-client.password = CONFIGURE-ME
```
zeroleak's avatar
zeroleak committed
19 20
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
21

zeroleak's avatar
zeroleak committed
22
### Pool: UTXO amounts
zeroleak's avatar
zeroleak committed
23
```
zeroleak's avatar
zeroleak committed
24
server.pools[x].denomination: amount in satoshis
zeroleak's avatar
zeroleak committed
25
server.pools[x].tx0MaxOutputs: max outputs per tx0
zeroleak's avatar
zeroleak committed
26 27 28
server.miner-fees.miner-fee-min: minimum miner-fee accepted for mustMix
server.miner-fees.miner-fee-max: maximum miner-fee accepted for mustMix
server.miner-fees.miner-fee-cap: "soft cap" miner-fee recommended for a new mustMix (should be <= miner-fee-max)
29
server.miner-fees.min-relay-fee: minimum miner-fee to accumulate for mixing
zeroleak's avatar
zeroleak committed
30
```
31 32 33 34 35 36 37 38 39

Optional pool override:
```
server.pools[x].miner-fees.miner-fee-min
server.pools[x].miner-fees.miner-fee-max
server.pools[x].miner-fees.miner-fee-cap
server.pools[x].miner-fees.min-relay-fee
```

40
UTXO should be founded with:<br/>
zeroleak's avatar
zeroleak committed
41
for mustMix: (*server.mix.denomination* + *server.miner-fees.miner-fee-min*) to (*server.mix.denomination* + *server.miner-fees.miner-fee-max*). New TX0 outputs are capped to (*server.mix.denomination* + *server.miner-fees.miner-fee-cap*).<br/>
42
for liquidities: (*server.mix.denomination*) to (*server.mix.denomination* + *server.mix.miner-fee-max*)
zeroleak's avatar
zeroleak committed
43

zeroleak's avatar
zeroleak committed
44 45 46 47

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


54 55 56 57
### 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
58
server.register-input.confirm-interval = 10: inputs are confirmed by batch at this frequency (seconds)
Gigi's avatar
Gigi committed
59
```
60

61 62 63
### UTXO rules
```
server.register-input.max-inputs-same-hash: max inputs with same hash (same origin tx) allowed to register to a mix
64
server.register-input.max-inputs-same-user-hash: max inputs with same user-hash (same mixing client) allowed to register to a mix
65 66
```

zeroleak's avatar
zeroleak committed
67 68
### SCodes
```
69 70 71 72 73 74
server.samourai-fees.scodes[foo].payload = 12345
server.samourai-fees.scodes[foo].fee-value-percent = 50
server.samourai-fees.scodes[foo].expiration = 1569484078 # optional

server.samourai-fees.scodes[bar].payload = 23456
server.samourai-fees.scodes[bar].fee-value-percent = 0
zeroleak's avatar
zeroleak committed
75
```
76 77 78 79 80
SCodes are special codes usable to enable special rules for tx0.
Each SCode is mapped to a short value payload (-32,768 to 32,767) which will be embedded into tx0's OP_RETURN as WhirlpoolFeeData.feePayload.
Payload '0' is forbidden, which is mapped to WhirlpoolFeeData.feePayload=NULL.
SCode overrides standard fee-value with a percent of this value.
SCode can expire for tx0s confirmed after a specified time.
zeroleak's avatar
zeroleak committed
81

zeroleak's avatar
zeroleak committed
82
### Pool: Mix limits
zeroleak's avatar
zeroleak committed
83
```
zeroleak's avatar
zeroleak committed
84
server.pools[x].anonymity-set = 5
zeroleak's avatar
zeroleak committed
85
server.pools[x].must-mix-min = 1
zeroleak's avatar
zeroleak committed
86
server.pools[x].liquidity-min = 1
zeroleak's avatar
zeroleak committed
87
```
zeroleak's avatar
zeroleak committed
88
Mix will start when *anonymity-set* (mustMix + liquidities) are registered.<br/>
zeroleak's avatar
zeroleak committed
89

zeroleak's avatar
zeroleak committed
90
At the beginning of the mix, only mustMix can register up, to *anonymity-set - liquidity-min*. Meanwhile, liquidities are placed on a waiting pool.<br/>
zeroleak's avatar
zeroleak committed
91 92
Liquidities are added as soon as *must-mix-min* are reached, up to *anonymity-set* inputs for the mix.<br/>
MustMixs are selected such as accumulated miner-fees >= *min-relay-fee* and >= *must-mix-min x miner-fee-cap* 
93

94
### Exports
zeroleak's avatar
zeroleak committed
95
Mixs are exported to a CSV file:
96 97 98 99 100
```
server.export.mixs.directory
server.export.mixs.filename
```

zeroleak's avatar
zeroleak committed
101 102 103 104 105 106
Activity is exported to a CSV file:
```
server.export.activity.directory
server.export.activity.filename
```

107 108 109
### Testing
```
server.rpc-client.mock-tx-broadcast = false
zeroleak's avatar
zeroleak committed
110
server.test-mode = false
111
```
112
For testing purpose, *server.rpc-client.mock-tx-broadcast* can be enabled to mock txs instead of broadcasting it.
zeroleak's avatar
zeroleak committed
113
When enabled, *server.test-mode* allows client to bypass tx0 checks.
114

115 116
java -jar -Dspring.profiles.active=test target/whirlpool-server-develop-SNAPSHOT.jar --debug --spring.config.location=classpath:application.properties,/path/to/application-default.properties

zeroleak's avatar
zeroleak committed
117 118 119
## Resources
 * [whirlpool](https://github.com/Samourai-Wallet/Whirlpool)
 * [whirlpool-protocol](https://github.com/Samourai-Wallet/whirlpool-protocol)
Gigi's avatar
Gigi committed
120
 * [whirlpool-client](https://github.com/Samourai-Wallet/whirlpool-client)