Hallo again,
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?
Best regards,
Jon