5. Counterparty Documentation, Release 0.1.0
counterpartyd_build is the automated build system for counterpartyd. This is an alternative method from
manual counterpartyd installation and running, which may be especially helpful in the following circumstances:
• You are a Windows user, or a Linux user that isn’t super experienced with the command line interface.
• You want to deploy counterpartyd in a production environment, and have it run automatically on system
startup
• You want to build your own counterpartyd binaries
This build system can can be used for the following tasks at this time:
• Automated setup of counterpartyd to run from source on Windows or Ubuntu Linux
• Automated creation of a Windows binary installer to allow for “point-and-click” installation of
counterpartyd on Windows (as a packaged counterpartyd.exe binary)
Future plans for the build system (pull requests for these features would be greatly appreaciated):
• Add support for Linux distributions beyond Ubuntu Linux
• Add support for Mac OS X automated setup from source
• Add support for creation of installer for Mac OS X
• Add support for creation of .rpm, .deb., etc. binary packages for Linux
Contents 1
7. CHAPTER 1
What is Counterparty?
Counterparty is an protocol that provides decentralized financial instrument on top of the Bitcoin blockchain.
Besides acting as a store of value, decentralized payment network and public ledger, Bitcoin itself allows programs to
embed arbitrary data into transactions. The value of this is immense, as it allows programs to be developed that add
new functionality on top of Bitcoin, while inheriting Bitcoin’s security model, peer to peer processing system, and
decentralized nature in the process.
3
9. CHAPTER 2
Table of Contents
2.1 Getting Started
The two main steps to get counterpartyd up and running are running bitcoind, and running the install script
itself, which will take care of the rest.
2.1.1 Running bitcoind
Warning: Counterparty is currently operating only on the Bitcoin testnet blockchain, because it requires the
use of a feature of the Bitcoin protocol that is not yet enabled in the official client (namely OP_RETURN outputs).
Please run ‘‘bitcoind‘‘ with ‘‘-testnet=1‘‘, when using it with Counterparty, for the time being.
counterpartyd communicates with the Bitcoin reference client (bitcoind). Normally, you’ll run bitcoind
on the same computer as your instance of counterpartyd runs on. However, you can also use a bitcoind sitting
on a different server entirely.
At this time, third-party RPC interfaces such as Blockchain.info’s are not supported.
On Windows
Go to the bitcoind download page and grab the installer for Windows. Install it with the default options.
Once installed, launch the GUI wallet program (Bitcoin-QT) to start the download of the blockchain. Then, type
Windows Key-R and enter cmd.exe to open a Windows command prompt. Type the following:
cd %LOCALAPPDATA%..Roaming.bitcoin
notepad bitcoin.conf
Say Yes to when Notepad asks if you want to create a new file, then paste in the text below:
rpcuser=rpc
rpcpassword=rpcpw1234
server=1
daemon=1
txindex=1
testnet=1
5
10. Counterparty Documentation, Release 0.1.0
You should change the RPC password above to something more secure. Once done, press CTRL-S to save, and close
Notepad.
After this, you must wait for the blockchain to finish downloading. Once this is done, you have two options:
• Close Bitcoin-QT and run bitcoind.exe directly. You can run it on startup by adding to your Startup
program group in Windows, or using something like NSSM.
• You can simply restart Bitcoin-QT (for the configuration changes to take effecnt) and use that. This is fine
for development/test setups, but not normally suitable for production systems. (You can have Bitcoin-QT start
up automatically by clicking on Settings, then Options and checking the box titled “Start Bitcoin on system
startup”.
On Ubuntu Linux
If not already installed (or running on a different machine), do the following to install it (on Ubuntu, other distros will
have similar instructions):
sudo apt-get install python-software-properties
sudo add-apt-repository ppa:bitcoin/bitcoin
sudo apt-get update
sudo apt-get install bitcoind
mkdir -p ~/.bitcoin/
echo -e "rpcuser=rpcnrpcpassword=rpcpw1234nserver=1ndaemon=1" > ~/.bitcoin/bitcoin.conf
Please then edit the ~/.bitcoin/bitcoin.conf file and set the file to the contents specified above (.
Next, start bitcoind:
bitcoind
The bitcoin server should now be started. The blockchain will begin to download automatically. You must let it finish
downloading entirely before going to the next step. You can check the status of this by running:
bitcoind getinfo|grep blocks
When done, the block count returned by this command will match the value given from this page.
For automatic startup of bitcoind on system boot, this page provides some good tips.
2.1.2 Installing counterpartyd
On Windows
• Download the counterpartyd installer for 64-bit Windows or 32-bit Windows
• Run the installer and navigate through the setup wizard
• The installer will verify all dependencies are on your system, as well as installing counterpartyd.exe (i.e.
which has been created as a self-contained program with all the necessary Python dependencies compiled in)
• The installer will gather data on your bitcoind installation, and create a basic counterpartyd configuration
file from that
• The installer will also have counterpartyd run as a service on startup (called “Counterparty”) automatically
You can start and stop the Counterparty service via the Services icon in the Administrative Tools Control Panel.
6 Chapter 2. Table of Contents
11. Counterparty Documentation, Release 0.1.0
On Linux
There is no pre-made installer for Linux at this time, as the source install is rather straightforward.
Just follow the instructions for Linux in Building & Running from Source.
2.1.3 Config and Logging
Finding the Data Directory
counterpartyd stores its configuration, logging, and state data in a place known as the counterpartyd data
directory.
Under Linux, the data directory is normally located in ~/.config/counterparty (when counterparty is
installed normally, via the setup.py installer).
Under Windows, the data directory is normally located at %APPDATA%Counterpartycounterpartyd. Ex-amples
of this are:
• C:Users<your username>AppDataRoamingCounterpartycounterpartyd (Win-dows
7/8/Server)
• C:Documents and Settings<your username>Application
DataCounterpartycounterparyd (Windows XP)
Editing the Config
counterpartyd can read its configuration data from a file. The build system uses this method to allow for auto-mated
startup of counterpartyd.
If using the Windows installer, a configuration file will be automatically created for you from data gathered via the
installation wizard.
If not using the Windows installer, the setup.py script will create a basic counterpartyd.conf file for you
that contains options that tell counterpartyd where and how to connect to your bitcoind process. Here’s an
example of the default file created:
[Default]
rpc-connect=localhost
rpc-port=18832
rpc-user=rpc
rpc-password=rpcpw1234
After running the setup.py script to create this file, you’ll probably need to edit it and tweak the settings to match
your exact bitcoind configuration (e.g. especially rpc-password).
Viewing the Logs
By default, counterpartyd logs data to a file named counterpartyd.log, located within the
counterpartyd data directory.
Under Linux, you can monitor these logs via a command like tail -f
~/.config/counterparty/counterparty.log.
Under Windows, you can use a tool like Notepad++ to view the log file, which will detect changes to the file and
update if necessary.
2.1. Getting Started 7
12. Counterparty Documentation, Release 0.1.0
2.1.4 Next Steps
Once counterpartyd is installed and running, you can start exploring the API via the API documentation off of
the main counterpartyd repository.
2.2 Building & Running from Source
This section provides information about how to install and run counterpartyd from source, using this
counterpartyd build system (as an alternative to setting it up manually). This method is suitable for Linux
users, as well as Windows users that want to develop/enhance counterpartyd (or just don’t want to use the binary
installer).
2.2.1 On Windows
Prerequisites
Note: If you are on a computer with a 64-bit version of Windows, it’s normally best to get the 64-bit version of
everything below. The only exception would be if you want to create a 32-bit installer for Counterpartyd. In that case,
go with the 32-bit versions of all of the dependencies below.
Minimally required to build Counterpartyd from source is the following:
• Python 3.3.x – grab the 32-bit version or 64-bit version. Install to the default C:Python33 location
• Python Win32 extensions – grab the 32-bit version or 64-bit version
• Git for Windows. Download here and install. Use the default installer options
If you want to be able to build the Counterpartyd installer, also download the following:
• Grab NSIS from here – Please choose the default options during installation, and install to the default path
• Download the NSIS SimpleService plugin from here and save the .dll file contained in that zip to your NSIS
plugins directory (e.g. C:Program Files (X86)NSISplugins)
• cx_freeze – grab the 32-bit version or 64-bit version as appropriate
Installing
Type <Windows Key>-R to open the run dialog, and enter “cmd.exe” to launch a command window.
In the command window, type the following commands:
cd C:
git clone https://github.com/PhantomPhreak/Counterparty.git
cd Counterparty
C:Python33python.exe setup.py
The above steps will check out Counterparty to C:Counterparty, and run the Counterparty setup.py script,
which will create a virtual environment with the required dependencies.
If you chose to start counterpartyd at startup automatically, the setup script will also create a shortcut to
counterpartyd in your Startup group.
Upon the successful completion of this script, you can now run counterpartyd using the steps below.
8 Chapter 2. Table of Contents
13. Counterparty Documentation, Release 0.1.0
Running from Source
After installing, open a command window and run counterpartyd in the foreground via:
cd C:Counterparty
run.py
Or, if you have multiple versions of python on your computer and want to make sure you use the right one:
cd C:Counterparty
C:Python33python.exe run.py
In another command window, you can then run any of counterparty’s other functions, like:
run.py --help
run.py send <options....>
run.py order <options....>
To run the counterparty testsuite:
cd C:Counterparty
run.py tests
Building your own Installer
Complete the instructions under Running from Source above. Then, execute the following commands to build from
source:
cd C:Counterparty
C:Python33python.exe setup.py -b
If successful, you will be provided the location of the resulting installer for Counterparty.
2.2.2 On Linux
Prerequisites
Currently, Ubuntu Linux (Server or Desktop) 12.04 LTS, 12.10, 13.04 or 13.10 are required.
Support for other distributions is a future task.
Installing
As the user you want to run ‘‘counterpartyd‘‘ as, launch a terminal window, and type the following:
sudo apt-get -y update
sudo apt-get -y install git-core
git clone https://github.com/PhantomPhreak/Counterparty.git ~/Counterparty
sudo ~/Counterparty/setup.py
The setup.py script will install necessary dependencies, create the python environment for counterpartyd,
create a dedicated counterpartyd system user (which will run it, by default), and install an upstart script that will
automatically start counterpartyd on startup.
2.2. Building & Running from Source 9
14. Counterparty Documentation, Release 0.1.0
Creating a default config
Follow the instructions listed under the Config and Logging section in Getting Started.
Running from Source
After installing and creating the necessary basic config, run counterpartyd in the foreground to make sure every-thing
works fine:
counterpartyd
(The above assumes /usr/local/bin is in your PATH, which is where the counterpartyd symlink (which
just points to the run.py script) is placed. If not, run /usr/local/bin/counterpartyd instead.
Once you’re sure it launches and runs fine, press CTRL-C to exit it, and then run counterpartyd as a background
process via:
sudo service counterpartyd start
You can then run any of counterparty’s other functions, like:
counterpartyd --help
counterpartyd send <options....>
counterpartyd order <options....>
To run the counterparty testsuite:
counterpartyd tests
2.2.3 Mac OS X
Mac OS support will be forthcoming.
10 Chapter 2. Table of Contents
