TumbleBit: An Untrusted Bitcoin-Compatible Anonymous Payment Hub
C++ Python C Makefile Shell



Proof of Concept implementation of TumbleBit as an untrusted classic tumbler as described in: "TumbleBit: An Untrusted Bitcoin-Compatible Anonymous Payment Hub".

Description: TumbleBit is a new anonymous payments protocol that is fully compatible with today’s Bitcoin protocol. TumbleBit allows parties to make payments through an untrusted Tumbler. No-one, not even the Tumbler, can tell which payer paid which payee during a TumbleBit epoch. TumbleBit consists of two interleaved fair-exchange protocols that prevent theft of bitcoins by cheating users or a malicious Tumbler. TumbleBit combines fast cryptographic computations (performed off the blockchain) with standard bitcoin scripting functionalities (on the blockchain) that realize smart contracts. TumbleBit was used to mix 800 input addresses to 800 output addresses on Bitcoin's blockchain.


This code is very early in its development (proof-of-concept phase) and is currently not ready for production.

  • Don't use the default keys if you plan on posting transactions on testnet or mainnet.
  • We have not audited this code for vulnerabilities and we are actively fixing memory corruption vulnerabilities.
  • There are known memory leaks in the networking code of the servers.
  • The servers currently do not handle more than one client at a time.
  • There are known side channel attacks on ECDSA in openssl.

Road Map

Road map for TumbleBit software development. Given the early nature of TumbleBit development the roadmap should be viewed as a rough guide and is likely to be updated and changed as development continues.

Phase 1: Code Safety and Testing

  • Move as much code as possible into python for improved memory safety.
  • Modularize code to allow our core protocol to be used in other settings.
  • Replace openssl-ECDSA with libsecp256k1.

Phase 2: Server Features

  • Payment Hub support.
  • Misbehavior reactive server and client.
  • Session Management and parallelization.
  • TOR integration.
  • Standardized REST Interface.

Phase 3: Usability and Wallets

  • Wallet Prototype.
  • Classic Tumbler Wallet integration.
  • Payment Hub Wallet integration.
  • Wallet to wallet demo.

Phase 4: Operational Concerns

  • Monitoring.
  • Audit and test at-scale deployment.
  • Assess, test and mitigate server compromise risks.
  • Release ops guide.

Phase 5: Alpha Release

  • User guides and documentation.
  • Wallet binaries.


  • LibreSSL Version 2.3.4 or higher
  • Boost
  • ZMQ
  • Bitcoind (Optional: for posting transactions)
  • Python dependencies: pip install -r requirements.txt
    • python-bitcoinlib
    • simplejson
    • pyzmq
    • pycrypto

For ubuntu, you can install the dependencies by running:


Building POC

Default build setting is to have the clients and the servers on the same machine.

If you want to run the servers on different machines, change TUMBLER_SERVER_SOCKET and SIGNER_SERVER_SOCKET in include/constants.h to point to the ip of your machine.

Running Tests for Python code

Our python code only supports python3.

cd TumbleBit/ 
sudo pip install -e .
python3 -m pytest tests/

Should be in the POC_code directory

All resulting binaries will be in the bin directory

  • Clients & Servers:
    • make
  • Servers:
    • make tumbler_server
    • make signer_server
  • Clients:
    • make bob_client
    • make alice_client_test Only runs the puzzle-solver protocol
  • Tests: Tests are located in src/test
    • make test_name


  • Full Tumbler run:
    • ./python/tx_server.py
    • ./bin/tumbler_server
    • ./bin/signer_server
    • ./bin/bob_client
  • Just the Puzzle Solver protocol:

    • ./python/tx_server.py
    • ./bin/signer_server
    • ./bin/alice_client_test