Skip to content
A python script computing the entropy of Bitcoin transactions and the linkability of their inputs and outputs.
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.


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

For a description of the metrics :

Boltzmann is also available for Java:

Python versions

Python 3.3.3


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


Manual installation

Gets the library from Github :
Unzips the archive in a temp directory
python install


python [--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.


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

Data Sources

You can use the remote 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:


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

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


@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).


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 clean && python build && python install after modifying source files.

You can’t perform that action at this time.