I have a new proposal. This one is IMHO simpler and more robust. Moreover, it caters for two kinds of clients of the API: 1) those who don't want to bother with block chain reorgs and therefore can just play it safe and request only transactions which have a high number of confirmations (and therefore have an infinitesimal chance of belonging to a block which might be discarded down the road), and 2) those who want absolute control, 100% robustness, and are willing to deal with possible block chain reorgs.
My suggestion is to base the API call not on transactions but on blocks. After all, transactions are grouped into blocks, and saying that a given transaction has N confirmations means that all transactions in that same block also have N confirmations. It therefore makes more sense for the client application to receive transactions in block-based batches.
So, I propose a gettransactionssince
method with the following parameters:
gettransactionssince [account] [blkhash] [blknum] [minconf=6]
If given, the optional parameter account
restricts the result set to transactions pertaining to that account. The also optional parameter blkhash
indicates the block hash of the last block the client knows about. When this parameter is given, the Bitcoin daemon is supposed to return all transactions which have occurred since this block (but not including the transactions in the block itself!). If not given, then all transactions since the beginning should be returned.
Very important: together with a set of transactions, the method gettransactionssince
should also return the block hash and the block number of the last block in the chain with minconf
confirmations (and whose transactions are possibly contained in the result set). This way, the client can in subsequent invocations tell the Bitcoin daemon what it already knows about.
Note the minconf
parameter. I suggest setting its default value to a number so high that the probability of a reorg affecting the returned blocks is practically zero. This way, "dumb" clients can just call gettransactionssince
using a different blkhash
each time, and not worry about any other book-keeping.
As for the blknum
parameter, it can be used for an early breakout of the cycle in the event that there's been a reorg and therefore blkhash
will not be found. If it's not given, then the daemon will have to loop all the way to the beginning before it can detect and report an error situation.
Smarter clients can use blknum
together with a lower minconf
value to ensure a lower latency for confirmations; they should however take care of some extra book-keeping in case there's been in fact a reorg. The algorithm for this is not that
complicated, but it is in any case the sole responsibility of the client to implement it correctly
; the Bitcoin daemon should not have to care.
Anyway, what do you think?