TxCatcher
========

*TxCatcher* is a lightweight alternative to Bitpay's Insight (bitcoin and litecoin compatible)
The purpose of this software is to receive all incoming unconfirmed transactions,
store them in the DB along with addresses (outputs) and provide a simple API to check whether
a certain address received a deposit.

However, it doesn't rely on having full blockchain with either bitcoind or litecoind.
You can have pruning enabled (in fact, it's recommended) and the txcatcher's DB
is regularly cleaned, so it doesn't grow.

The point is to detect new transactions to an address and store them for at least a while,
but then get rid of them. It's ideal for lightweight payment processing.

API requests:
-------------
request: `/addr/2N8Xdi8FiWAT3Vuo2mzcCETnrBjeAtBiqiA`
response (JSON):

    {
      "address":"2N8Xdi8FiWAT3Vuo2mzcCETnrBjeAtBiqiA","received":2000000
      "deposits":[
        {
          "txid":"4e6e1e491108b8302da8885b7e57b8809385d206346b3d287b6300408efe551c",
          "amount":0.01,
          "satoshis":1000000,
          "confirmations":0,
          "block_height":null
        }
    }

request: `/addr/2N8Xdi8FiWAT3Vuo2mzcCETnrBjeAtBiqiA/utxo`
response (JSON):

    [{
      "value":0.01,
      "n":0,
      "scriptPubKey":{"asm":"OP_HASH160 a7a458022e92dd04935c849ab2ea3b07373b7e4b OP_EQUAL","hex":"a914a7a458022e92dd04935c849ab2ea3b07373b7e4b87","reqSigs":1,"type":"scripthash","addresses":["2N8Xdi8FiWAT3Vuo2mzcCETnrBjeAtBiqiA"]},
      "confirmations":5,
      "txid":"4e6e1e491108b8302da8885b7e57b8809385d206346b3d287b6300408efe551c"
    }]

You can also broadcast transactions by sending requests to `/tx/send` passing transaction in `rawtx` param.


Is that all?
-----------
For now - yes. It allows you to do basic stuff like checking what an address has received.

TODO:
  * websockets for instant update notifications
  * better configuration through command line args


What it does under the hood
---------------------------
* it uses bitcoind or litecoind with ZeroMQ to receive new transactions from the mempool
* it receives newly mined blocks so that we can tell how many confirmations a transaction to a certain
  address has.
* regularly cleans the DB

Installation
------------

  Install dependencies:
  *  zeromq
  *  rvm, ruby & rubygems
  *  sqlite3 or postgresql
  *  bitcoind or litecoind or both

  Install txcatcher: `gem install txcatcher`

Configuring & Running
--------------------
You're going to need a simple config file. By default, txcatcher looks in `~/.txcatcher` dir,
so create the dir and the file there: `mkdir ~/.txcatcher && touch ~/.txcatcher/config.yml`
Example config file can be found in [templates/config.yml](templates/config.yml), you might want
to copy the contents and edit it.

Once your bitcoin/litecoind finished syncing, you can start txcatcher with a simple command: `txcatcher`.
You can start multiple instances of txcatcher, when, for example, you want instances of it
tracking both litecoin and bitcoin transactions:

    txcatcher -c ~/.txcatcher/litecoin_config.yml
    txcatcher -c ~/.txcatcher/bitcoin_config.yml
    
Upstart script
-------------
If running on Ubuntu, you may also want to create an upstart script, so here's an example (`/etc/init/txcatcher_btc.conf`):

    start on started bitcoind
    stop on shutdown
    setuid deploy
    respawn
    respawn limit 10 90

    env HOME="/home/deploy"
    env RVM_WRAPPERS_PATH="/usr/local/rvm/gems/ruby-2.3.4/wrappers"
    env TXCATCHER_CONFIG="/home/deploy/.txcatcher/config.yml"

    exec ${RVM_WRAPPERS_PATH}/txcatcher -c ${TXCATCHER_CONFIG}
  
 For this to work, you need a number of prerequisites:
 * create a `deploy` user, make sure rvm works with this user (rvm multi-user installation)
 * DO NOT daemonize the process in config.yml, set `daemonize: false` in `/home/deploy/.txcatcher/config.yml`
 * Generate rvm wrapper for txcatcher: https://rvm.io/deployment/init-d
 * Make sure your bitcoind or litecoind are also started with an upstart script: https://github.com/bitcoin/bitcoin/blob/0.13/contrib/init/bitcoind.conf
 
You can then start and stop txcatcher with `start txcatcher_btc` and `stop txcatcher_btc`.

Running unit tests
------------------
Before running unit tests, make sure you have bitcoind running in mainnet mode,
with RPC enabled and blockchain synced. Copy the `spec/config/config.yml.sample` file
and change the RPC username/password to match your bitcoind settings.