Submit to StumbleUpon Share

Hello and welcome back to my blog!

This article talks about the technical implementation details of building a watch only wallet on top of bitcoind - it's aimed at bitcoin / altcoin business owners/developers rather than individuals.


Watch only

Watch only wallets do not contain the private keys for the addresses they're watching, which makes them extremely secure. An attacker who gained access to your watch-only wallet would not be able to withdraw any coins. You cannot spend coins from a watch only wallet directly, but you can get the balance of an address, or export a transaction to be signed externally. This makes them fall into the category of cold storage.

The reference bitcoin client, bitcoind currently does not support watch only wallets, which is a great shame. However, it does expose a nice JSON RPC API which we can use to help us.


Before we get started it is necessary to explore the sacrifices we make going down this route:

Assisted manual block-chain parsing

It will be necessary to look at every transaction, block by block which means we will need to deal with block orphans and general bookkeeping for tracking which block we're up to.

Custom bookkeeping of transaction outputs

The bitcoind wallet doesn't track transaction outputs for addresses it doesn't have the private keys for. This means we will need to track them ourselves, checking and updating them whenever a new block arrives.

No wallet accounts

Again, there are no private keys in this wallet, so the accounts feature of bitcoind isn't useable.

Parsing the block-chain

The general idea here is that we want to be able to move from one block to the next, examining the transactions contained within. If we have the hash of the block we'd like to start from, we can get going - if we just want to start from the current block, we can do:

getblockhash( getblockcount() )

Using the getblock() RPC function we can then pull down a JSON encoded block from bitcoind, which looks like this:

    "hash" : "000000004cabf003eeba1c75e6842a5a098dbb98ebf0c4482936806190cdfd46",
    "confirmations" : 1,
    "size" : 5164,
    "height" : 205401,
    "version" : 2,
    "merkleroot" : "ebcc75ac9cff8719568ea20e09d39ec0060fdb5cf013b6ce1cd082f779f0de09",
    "tx" : [
    "time" : 1395151737,
    "nonce" : 80102656,
    "bits" : "1d00ffff",
    "difficulty" : 1.00000000,
    "previousblockhash" : "00000000d67d50da2cc50da6b977543d7ea52364d75eeb4f7cf2ef4048c30090"

This is a block from testnet, hence the low difficulty

This gives us a list of transaction hashes, which is perfect to feed into the RPC call, getrawtransaction(). We can also get a similar list of TXIDs from the mempool, using getrawmempool() which enables us to see 0 confirmation transactions, which is very helpful for instant feedback purposes when displaying a list of deposits a customer has made, for example.

Both getblock() and getrawmempool() return all transactions, even those which the wallet doesn't have private keys for. This is the key to this process.

So, now we have a way to get all TXIDs we must build a function which takes a list of transaction hashes and processes them, filtering out the ones we are interested in watching.

Processing and filtering transactions

We need to call getrawtransaction() with the list of TXIDs we're interested in taking a look at. Calling it in batch mode is a good idea, since that will save on RPC overhead. In addition, we'd like the results in JSON, so we set verbose to 1 in the optional parameter.

Here is an example of the result of getrawtransaction()

    "hex" : "0100000001a0ddd030fcec3491a66faeb933618a3d3f35bdb564b439baf67e676f0e861344000000006b48304502205c8b1a8ed30cf6f9ed634879b6f98b257fde2764bb1274316524cf5223bf8456022100dd23eb57b5f1cdbeb77921543e23c30962f475162ff330fdc91a44175d871fc801210280d610df7855e1b9645193643c478268d189307372861d0d9c4560d1f63e22bfffffffff02848ed923000000001976a91416ac385ac5dca1580bce6cfc68d08771c23cd64f88ace041d88e030000001976a914febfbe6f1e323ba68e79205555814f7b6f6fda5888ac00000000",
    "txid" : "f6977b1ace8248745752eb2e4e6a407d61741d75b6a8354c0f5cd486d4037630",
    "version" : 1,
    "locktime" : 0,
    "vin" : [
            "txid" : "4413860e6f677ef6ba39b464b5bd353f3d8a6133b9ae6fa69134ecfc30d0dda0",
            "vout" : 0,
            "scriptSig" : {
                "asm" : "304502205c8b1a8ed30cf6f9ed634879b6f98b257fde2764bb1274316524cf5223bf8456022100dd23eb57b5f1cdbeb77921543e23c30962f475162ff330fdc91a44175d871fc801 0280d610df7855e1b9645193643c478268d189307372861d0d9c4560d1f63e22bf",
                "hex" : "48304502205c8b1a8ed30cf6f9ed634879b6f98b257fde2764bb1274316524cf5223bf8456022100dd23eb57b5f1cdbeb77921543e23c30962f475162ff330fdc91a44175d871fc801210280d610df7855e1b9645193643c478268d189307372861d0d9c4560d1f63e22bf"
            "sequence" : 4294967295
    "vout" : [
            "value" : 6.01460356,
            "n" : 0,
            "scriptPubKey" : {
                "asm" : "OP_DUP OP_HASH160 16ac385ac5dca1580bce6cfc68d08771c23cd64f OP_EQUALVERIFY OP_CHECKSIG",
                "hex" : "76a91416ac385ac5dca1580bce6cfc68d08771c23cd64f88ac",
                "reqSigs" : 1,
                "type" : "pubkeyhash",
                "addresses" : [
            "value" : 152.81439200,
            "n" : 1,
            "scriptPubKey" : {
                "asm" : "OP_DUP OP_HASH160 febfbe6f1e323ba68e79205555814f7b6f6fda58 OP_EQUALVERIFY OP_CHECKSIG",
                "hex" : "76a914febfbe6f1e323ba68e79205555814f7b6f6fda5888ac",
                "reqSigs" : 1,
                "type" : "pubkeyhash",
                "addresses" : [
    "blockhash" : "000000004cabf003eeba1c75e6842a5a098dbb98ebf0c4482936806190cdfd46",
    "confirmations" : 2,
    "time" : 1395151737,
    "blocktime" : 1395151737

We're going to go through this step by step, looking at what the relevant parts of this mean and how it can help us identify deposits and withdrawals from the addresses we are interested in watching.


In order to watch for deposits, we will need a list of addresses we're interested in watching.

Deposits to an address always show up in the vout array inside the JSON result. There can be any number of vout structures, so we must loop over each one.

Each vout contains a value field (the amount of bitcoins), an n field (the index inside the transaction) and a scriptPubKey field, which contains the deposit address for this transaction. Together, the TXID of the transaction and the n field of the vout form a unique unspent output, which can be thought of like a deposit.

Inside the scriptPubKey field there is an array of addresses, which is almost always of length 1. It's an array because of a special and seldom used transaction type, 'multisig' but you don't need to worry about this since you're likely to control the addresses to be watched and their types. Filter out outputs of this type by checking the type field field of scriptPubKey. The full list of possible types is:

  • nonstandard
  • pubkey
  • pubkeyhash
  • scripthash
  • multisig

Taken from

Most likely, you'll only be interested in pubkeyhash (a regular bitcoin address) and scripthash (a multi-signature address).

The pseudocode for the loop over all the vouts inside a transaction looks like this:

foreach (Vout vout in t.VOut)
	if (vout.ScriptPubKey.Addresses != null)
		if (vout.ScriptPubKey.Addresses.Count == 1)
			string address = vout.ScriptPubKey.Addresses[0];
			bool deposit = addressesToWatch.ContainsKey(address);
			if (deposit)
				// found a deposit!
				unspent[ BuildKey(t.TxId, vout.n) ] = vout;

addressesToWatch is a set of all the bitcoin addresses you're interested in watching

Once you have found a deposit, you'll want to store it indexed by TXID and vout index (the n field inside the vout). You'll also want to take a look at the number of confirmations on the transaction before you consider this output for getting an address balance.


In order to process withdrawals, we must look at the vin array inside the transaction and cross reference with our stored set of outputs (TXID and index). The vin structure contains a txid and vout field, so this is actually trivial. Whenever we see a TXID and vout that we have a record for being referenced inside the vin of a transaction, we must mark this as spent which excludes it from balance calculations.

foreach (Vin vin in t.VIn)
	if (vin.CoinBase == null)
		unspent.RemoveKey( BuildKey(t.TxId, vin.Vout) );

Address balance

It is then a trivial matter to calculate the balance of an address, just a loop over all unspent outputs which have the address you are interested in.

decimal addressBalance = unspent.Where( u=>u.Address == balanceAddress && u.Confirmations == requiredConfirms ).Sum( u=>u.Amount );

balanceAddress is the address you'd like to get the balance of and requiredConfirms is the required number of confirmations

Orphaned blocks

When manually parsing the blockchain in real time, it's quite common to get stuck on an orphaned block. This can happen when two miners submit a solved block at the same time. One block is discarded and becomes an orphan, but if your parser happens to call getblock() at the 'wrong' time, you can end up processing the wrong block.

The symptoms of this happening are:

  • The number of confirmations on your current block are 0
  • The nextblockhash field is null
  • getblockcount() returns a higher number than the height field inside your current block

Once you have detected this case, the way to become unstuck from the orphan is to step backwards until you find a block with non 0 confirmations, and then step forward again.

That's it

You now have all the tools you need to implement a watch only wallet on top of bitcoind!

I hope this helps some developers. Until next time, have fun!

Cheers, Paul.

Submit to StumbleUpon Share