samourai-wallet / boltzmann

A python script computing the entropy of Bitcoin transactions and the linkability of their inputs and outputs.

Boltzmann

This repository is now maintained at https://code.samourai.io/oxt/boltzmann

A python script computing the entropy of Bitcoin transactions and the linkability of their inputs and outputs.

For a description of the metrics :

• Bitcoin Transactions & Privacy (part 1) : https://gist.github.com/LaurentMT/e758767ca4038ac40aaf

• Bitcoin Transactions & Privacy (part 2) : https://gist.github.com/LaurentMT/d361bca6dc52868573a2

• Bitcoin Transactions & Privacy (part 3) : https://gist.github.com/LaurentMT/e8644d5bc903f02613c6

Boltzmann is also available for Java: https://github.com/Samourai-Wallet/efficiency-score

Python versions

Python 3.3.3

Dependencies

• sortedcontainers
• numpy
• python-bitcoinrpc
• mpmath
• sympy
• chainside-btcpy (>=0.5.1)

Installation

Manual installation

Gets the library from Github : https://github.com/Samourai-Wallet/boltzmann/archive/master.zip
Unzips the archive in a temp directory
python setup.py install

Usage

python ludwig.py [--rpc] [--duration=600] [--maxnbtxos=12] [--cjmaxfeeratio=0] [--options=PRECHECK,LINKABILITY,MERGE_FEES,MERGE_INPUTS,MERGE_OUTPUTS] [--txids=8e56317360a548e8ef28ec475878ef70d1371bee3526c017ac22ad61ae5740b8,812bee538bd24d03af7876a77c989b2c236c063a5803c720769fc55222d36b47,...]

[-t OR --txids] = List of txids to be processed.

[-p OR --rpc] = Use bitcoind's RPC interface as source of blockchain data

[-T OR --testnet] = Use testnet3 as source of blockchain data

[-s OR --smartbit] = Use Smartbit as source of blockchain data

[-d OR --duration] = Maximum number of seconds allocated to the processing of a single transaction. Default value is 600 seconds.

[-x OR --maxnbtxos] = Maximum number of inputs or ouputs. Transactions with more than maxnbtxos inputs or outputs are not processed. Default value is 12.

[-r OR --cjmaxfeeratio] = Max intrafees paid by the taker of a coinjoined transaction. Expressed as a percentage of the coinjoined amount.

[-o OR --options] = Options to be applied during processing. Default value is PRECHECK, LINKABILITY, MERGE_INPUTS. Available options are :

• PRECHECK = Checks if deterministic links exist without processing the entropy of the transaction. Similar to Coinjoin Sudoku by K.Atlas.

• LINKABILITY = Computes the entropy of the transaction and the txos linkability matrix.

• MERGE_INPUTS = Merges inputs "controlled" by a same address. Speeds up computations.

• MERGE_OUTPUTS = Merges outputs "controlled" by a same address. Speeds up computations but this option is not recommended.

• MERGE_FEES = Processes fees as an additional output paid by a single participant. May speed up computations.

Troubleshooting

This project requires python 3. If your default python points to python 2, substitute python3 for all instructions in this README.

MERGE_OUTPUTS option is still a work in progress. Results are not always reliable.

MERGE_FEES should only be used if it is known with certainty that all mining fees were paid by a single partificant to the transaction. Not recommended to use, especillay in the case of Stonewall/Stonewallx2 transactions.

If your request is returning no response and you only see "DEBUG: Using remote blockchain.info API" make sure you are typing the commands correctly.

Data Sources

You can use the remote Blockchain.info API for blockchain data (default), bitcoind's local RPC interface using the --rpc command line option, or write your own wrapper.

In order to use bitcoind's RPC interface, you must set these environment variables:

• BOLTZMANN_RPC_USERNAME
• BOLTZMANN_RPC_PASSWORD
• BOLTZMANN_RPC_HOST
• BOLTZMANN_RPC_PORT

Ex. $ export BOLTZMANN_RPC_USERNAME=myusername

You will also need to enable full indexing for bitcoind. This consumes more storage space. See this sample excerpt of a bitcoin.cfg file:

# You must set rpcuser and rpcpassword to secure the JSON-RPC api
rpcuser=myusername
rpcpassword=mysecretpassword_REPLACE_ME
rpcport=8332

#Maintain a full transaction index, used by the getrawtransaction rpc call (default: 0)
txindex=1

Contributors

@LaurentMT @kristovatlas @SamouraiDev

Uses Chainside's btcpy library and Sipa's bech32 reference code for deriving bech32 addresses from public keys (btcpy) and redeem scripts/witness programs (Sipa).

Contributing

Many improvements are needed:

• smarter heuristics to manage intra fees paid/received by participants to coinjoin markets (e.g. joinmarket, ...)
• optimization of the algorithm (parallelization, memorization, ...)
• ...

Help us to make Boltzmann better !

1. Fork it
2. Create your feature branch (git checkout -b my-new-feature)
3. Commit your changes (git commit -am 'Add some feature')
4. Push to the branch (git push origin my-new-feature)
5. Create new Pull Request

Tip: Don't forget to run python setup.py clean && python setup.py build && python setup.py install after modifying source files.

boltzmann's Issues

Project current status

Hello,

This looks like very interesting work. From what I gather from the gists, the aim is to make transaction privacy analysis open source and available to the general public. I'm interested in contributing and therefore have the following questions:

1. Is this project still active? (Most files were last changed ~2 years ago.)
2. Are there other similar projects which have gained similar or more traction?
3. Is this sort of analysis still relevant given the current state of bitcoin? (The bitcointalk thread linked from the thread is from 4 years ago.)
4. Are there any established-ish companies selling this sort of analysis?

Thank you for your attention.

Pb with bc.i api when using https

TODO: remove btcpy source files once pip repo is updated to v0.4.

Meet in the middle

Have you thought about using it to reduce the complexity from 2^N to 2^N/2?

https://www.geeksforgeeks.org/subsets-sum-b/

bitcoind rpc wrapper?

If you're interested, I'll volunteer to make a PR adding a bitcoind rpc wrapper.

TypeError: 'float' object cannot be interpreted as an integer

$ python3 ludwig.py --txids=8e56317360a548e8ef28ec475878ef70d1371bee3526c017ac22ad61ae5740b8


--- 8e56317360a548e8ef28ec475878ef70d1371bee3526c017ac22ad61ae5740b8 -------------------------------------
Traceback (most recent call last):
  File "ludwig.py", line 142, in <module>
    main(txids, options, max_duration, max_txos, max_cj_intrafees_ratio)  
  File "ludwig.py", line 86, in main
    (mat_lnk, nb_cmbn, inputs, outputs, fees, intrafees) = process_tx(tx, options, max_duration, max_txos, max_cj_intrafees_ratio)
  File "/usr/local/lib/python3.6/site-packages/boltzmann-0.0.1-py3.6.egg/boltzmann/utils/tx_processor.py", line 71, in process_tx
    (mat_lnk, nb_cmbn, txo_ins, txo_outs) = linker.process(linked_ins+linked_outs, options, intrafees)
  File "/usr/local/lib/python3.6/site-packages/boltzmann-0.0.1-py3.6.egg/boltzmann/linker/txos_linker.py", line 134, in process
    self._prepare_data()
  File "/usr/local/lib/python3.6/site-packages/boltzmann-0.0.1-py3.6.egg/boltzmann/linker/txos_linker.py", line 189, in _prepare_data
    self._all_in_agg_val = self._prepare_txos(self.inputs)
  File "/usr/local/lib/python3.6/site-packages/boltzmann-0.0.1-py3.6.egg/boltzmann/linker/txos_linker.py", line 226, in _prepare_txos
    all_agg[j, :] = np.tile(tmp, 2**(expnt-1) / two_exp_j)
  File "/usr/local/lib/python3.6/site-packages/numpy-1.12.0-py3.6-macosx-10.11-x86_64.egg/numpy/lib/shape_base.py", line 881, in tile
    return c.reshape(shape_out)
TypeError: 'float' object cannot be interpreted as an integer

Any suggestions?

Utxos without an associated address are not properly managed by the wrappers

E.g : raw multisigs, segwit, etc

May be solved by using the raw scriptpubkey when an address isn't returned by the api.