Bitcoin Plugin

by | Jan 20, 2014 | Payments, Plugins

In this post we will describe our Kill Bill Bitcoin plugin. Our Kill Bill Coinbase plugin has been described in a previous entry and the intent here is to focus on the Bitcoin plugin itself. Its goal is twofold:

  1. It must verify each Kill Bill payment that occurred in BTC so that payments can transition from their PENDING (unconfirmed) state to SUCCESS (confirmed) state; each BTC payment in Kill Bill will have one matching transaction within the Bitcoin blockchain. The verification relies on some heuristics that are configurable, such as the depth of the blocks where the transaction occurred.
  2. It must periodically transfer the BTC to a specific merchant key. Each plugin instance currently has its own instance of a wallet; since we often run Kill Bill as a distributed service– for robustness purpose, or to address needs of scaling horizontally — that means that each node where Kill Bill runs has a different wallet, and the BTC in each wallet need to be transferred to a well known (set of) public merchant keys.


The plugins are all initialized with a well known key  that they have inserted in their wallet. The public key is known to Kill Bill and this is where it sends the money to when a payment is made. The plugin listens to both Kill Bill notifications and it relies on the Simplified Payment Verification (SPV) bitcoinj library to be notified of Bitcoin transactions. The flow of operations can be summarized as follows:

  • Each time it detects a new payment whose payment method points to a BTC plugin and whose status is set to PENDING, it keeps track of that payment in its persistent tables. It keeps a mapping between the Kill Bill payment unique id, and the BTC transaction.
  • When it receives a transaction notification from the bitcoinj library, it checks to see if there is a PENDING payment that matches that BTC transactionId and it verifies if the payment can be considered valid. If it is, it makes an API call to Kill Bill so that the payment status can be updated to SUCCESS.

In addition to that, the plugin periodically empties its wallet using a well known (set of) public key. The interval, amount of money,.. that should be in the wallet are all parameters that can be tuned.

We currently have a prototype of a Kill Bill instance running on EC2, deployed with both the Coinbase and Bitcoin plugins.

Related Articles