Skip to content
This repository was archived by the owner on Sep 11, 2024. It is now read-only.

How to Run

Nicolas Dorier edited this page Sep 18, 2017 · 53 revisions

1. Bitcoin Core

NTumbleBit depends on Bitcoin Core and it works with pruned mode, too. Download Bitcoin Core 0.13.2 (a newer version may work as well) and configure it to work on testnet.

Then create/edit your bitcoin.conf:

# Run on the test network instead of the real bitcoin network.
testnet=1

# server=1 tells Bitcoin-Qt and bitcoind to accept JSON-RPC commands
server=1

# RPC user and password may be used if you aren't using the newer 'cookie' authentication
rpcuser=bitcoinuser
rpcpassword=bitcoinuser

# Optional: pruning can reduce the disk usage from currently around 120GB (or 8GB testnet) to around 2 GB.
prune=2000

Finally, execute bitcoind or bitcoin-qt, allow it catch up with the network and send like 10+ testnet coins to it.

2. .NET Core

NTumbleBit is built upon .NET Core.

You will need to install it on your system following these instructions.

3. Clone & Restore

git clone https://github.com/NTumbleBit/NTumbleBit/
cd NTumbleBit/
dotnet restore

Optional: UnitTest

cd NTumbleBit.Tests/
dotnet test

Your results should be something like this:

=== TEST EXECUTION SUMMARY ===
   NTumbleBit.Tests  Total: 12, Errors: 0, Failed: 0, Skipped: 0, Time: 15.637s
SUMMARY: Total: 1 targets, Passed: 1, Failed: 0.

4. Configure & Run

Notes before you start

  • Your wallet is as secure as your configuration files, so apply appropriate permissions.
  • We'll are working on the testnet from here on.

The Server

First run the server and it will generate the configuration files for you:

cd NTumbleBit.ClassicTumbler.Server.CLI
dotnet run -testnet

The server's configuration file can be found in the user's home directory at .ntumblebitserver/TestNet/server.config. (%appdata%\NTumbleBitServer\TestNet\server.config on Windows)

Sample configuration file:

rpc.url=http://localhost:18332/  # assumes Bitcoin Core is on localhost  
rpc.user=bitcoinuser         # use the credentials from your bitcoin.conf
rpc.password=bitcoinuser     # use the credentials from your bitcoin.conf

Run the server agian: dotnet run -testnet, and keep it running.

The Client

Run the client, just like you did with the server to generate your configuration files:

cd NTumbleBit.ClassicTumbler.Client.CLI
dotnet run -testnet

It will prompt you the location of the client.config file (normally ~/.ntumblebit/TestNet/client.config).

# Bitcoin Core
rpc.url=http://localhost:18332/      # assumes Bitcoin Core is on localhost
rpc.user=bitcoinuser                 # use the credentials from your bitcoin.conf
rpc.password=bitcoinuser             # use the credentials from your bitcoin.conf
# Tumbler Server 
tumbler.server=http://localhost:37123 # assumes Tumbler Server is on localhost
# Wallet
outputwallet.extpubkey=              # obtain from wallet (refer to Copay example)
outputwallet.keypath=                # obtain from wallet  (refer to Copay example)

The outputwallet.extpubkey and outputwallet.keypath define the wallet where you will mix out your bitcoins from your Bitcoin Core. Probably every major Bitcoin wallet provides a way to acquire their extpubkey and keypath. Note that you cannot use extpubkey from Bitcoin Core because it is hashed, but you can do it in another way, see details below.

You can use Copay or HiddenWallet as your output wallet to get the extpubkey.
While for testing TumbleBit it does not matter which wallet you choose to be your output wallet, to protect your privacy you should choose HiddenWallet, since it's a full block downloading SPV wallet, what basically means third parties are not able to link together all your Bitcoin addresses through network analysis.
Of course you could use a full node, like Bitcoin Core or other full block downloading SPV wallets. At the time of writing there are no other this type of wallets released, but HiddenWallet. There are some being worked on: Stratis - Breeze Wallet and Jonas Schnelli's SPV mode extension to Bitcoin Core.

HiddenWallet CoPay
1. Follow the setup instructions for HiddenWallet. 1. Download and install Copay.
2. Create a testnet wallet and acquire the extpubkey: HiddenWallet Testnet Setup for NTumbleBit OutputWallet 2. Create a testnet wallet and acquire the extpubkey: Copay Testnet Setup for NTumbleBit OutputWallet
3. Use the extpubkey in your client.config file: 3. Use the extpubkey in your client.config file:

For HiddenWallet leave the outputwallet.keypath empty:

outputwallet.extpubkey=tpubDCxfJRsapaxp5cDRBkt6x4RxHu9d3cZnzSVfcxib2nGTY1vALSZ6n7CxNZnw8n4AXcxmKA548fDTr2kCRL9wHKG3PbTdihG4RZL5pSAAGJ5
outputwallet.keypath=

CoPay:

outputwallet.extpubkey=tpubDCv6h3AqFXzjQpLnubExzkdyHsngEicFHDsHaGgTMtiSbBXcqN3XuzGPW6hv85R7F8DuQcnJGSXV9knSoG54auiDfzSRsVFvb9QtDBwnukp
outputwallet.keypath=0

By running NTumbleBit.CLI, after each cycle, your output wallet will receive some coins.
It can take a while depending how long a cycle is. (With the current default settings on testnet, it will take 24 blocks to get your first coins in the output wallet, followed by one coin every 2 blocks.)

Bitcoin Core wallet over RPC

If you want to use another Bitcoin Core as output wallet, you need to configure additional RPC settings in your client.config:

outputwallet.rpc.url=...        # Bitcoin Core instance running on a secure host
# Then one method of authentication, either user/password or cookie file:
outputwallet.rpc.user=...
outputwallet.rpc.password=...
outputwallet.rpc.cookiefile=...

Note that RPC calls to and from Bitcoin Core are not encrypted. You can separately encrypt the link between Client and Bitcoin Core Wallet by using OpenVPN or creating an SSH tunnel.

Running The Client

Now run the client again:

cd NTumbleBit.ClassicTumbler.Client.CLI
dotnet run -testnet

The client connects to your running bitcoin core and send funds from it (through the TumblerServer) into your output wallet, that you defined in the client.config file.

By pressing Enter you can stop the NTumbleBit.CLI process and running it again with dotnet run -testnet -onlymonitor command it will tell the CLI not to start Tumbling more coins, but finish those that are in process.

Advanced features

By default, NTumbleBit server and client auto configure on the local TOR instance. However, it is possible to setup Alice and Bob to use SOCKS or HTTP proxy if you have an existing infrastructure. This is for advanced users, use manually configured proxies only if you know what you are doing.

Configuring a SOCKS proxy

You can hide Bob or Alice by using TOR's SOCKS proxy. If you are using the TOR bundle (the browser), change the port to 9150 instead of 9050.

alice.proxy.type=socks
alice.proxy.server=127.0.0.1:9050

5. Command line interface

The server (NTumbleBit.TumblerServer) and the Client (NTumbleBit.CLI) have access to a command line interface when started which allow you to monitor where your money is flowing.

After starting those executable, you can run commands at any time. To get more information:

>>> help

Examples

>>> status 1128572
Phases:
Registration-ClientChannelEstablishment-TumblerChannelEstablishment-PaymentPhase-TumblerCashoutPhase-ClientCashoutPhase

Records:
========
TumblerEscrow
        Transaction ca5ad1d2149dd89af7792e9da7640c1c909df5d6b6a1d7ceb74b70e7bea3b348
        ScriptPubKey 2MwFuFoBSLD2c2QkgN1QDn2gffKM48VhrJw

TumblerCashout
        Transaction a7111cd317c38412fd06b2c01104faaefdfa194ab1e9b031810416fadd0eb22c
        ScriptPubKey myJtrRuJjkM1yzC8YCES25757MyiX8psDJ

ClientEscrow
        Transaction 558909c66bf856b0ca8ebf51ae46fba2e04ae036c291d04495af2e88f1483d61
        ScriptPubKey 2NFTFWB6zPwixXemVe3SdsoaBAzPpEP9dTW

ClientRedeem
        Transaction 42def38ca5ed03f628a41b0c801fe402046cef28139447922c1ff7a0db2f0902
        ScriptPubKey mnoQBRBNNqrdsprvhkFRCX7g3EFiTg6GTY

ClientOfferRedeem
        Transaction a9d40b8f768d7ac9e7d3ae36f3c8336c053c5d9cde0fed07dffcdb6f0ac983b5
        Transaction a4b401cb0112f28c5165e8d23dfced8c01ced63d087fb2375eadfe2d75f327d7
        ScriptPubKey mntPu2fWHT9v2uNuhugAz5YQvpJCN88BKz

========
>>> status a7111cd317c38412fd06b2c01104faaefdfa194ab1e9b031810416fadd0eb22c
Cycle 1128572
Type TumblerCashout
4593 Confirmations
Timelock Height : 37
Hex 010000000148b3a3bee7704bb7ced7a1b6d6f59d901c0c64a79d2e79f79ad89d14d2d15aca00000000fd0a0100483045022100e373205276240ff9f279e313f1307d9c0d120dc4eba02b9352c777b30a5fc19b022000d4c6ba6581f18f1247d230c911fb5d877cec6909a09d376832bbd34c156095014730440220210976c2fecf7a510c6c55519c5defd43298ad512977e4072263d41ad324d32402206b7058dbf563d6ff97e06765be5b60cc033777f6b4bb4aa915c0cc36fbeeed20014c767453876352210232d9633a9e9c1e3a136b8363ce991d22e114dbe8aa3577b903bacd9da94b2f3d2102b2c4805751f0810c663d19b6082c3faba377f22b5aaf3989f206fb3313cac4dd52ae6703903811b175210341c911e29a73458827f55cafb0b293f591e34a8d7bf612545e3c6b299577a536ac68ffffffff0140def505000000001976a914c32a6645ea0fba2116479683a77d9c7e6ff88aef88ac25000000

WARNING

Do NOT lose connection during the process or you may lose money in case of malicious server. You can see if money is still being tumbled by checking Bitcoin Core's watch only addresses.
Once the process is over, there should be no money on watch only addresses.

If you want to stop mixing, type the following command, and wait that your bitcoin core input wallet have no "Watch Only" funds in transit.

>>> stop mixer

Clone this wiki locally