listsinceblock parameter: target-confirmations

6

listsinceblock help returns:

listsinceblock ( "blockhash" target-confirmations )

Get all transactions in blocks since block [blockhash], or all transactions if omitted

Arguments:
1. "blockhash"   (string, optional) The block hash to list transactions since
2. target-confirmations:    (numeric, optional) The confirmations required, must be 1 or more

I sent a coin to my wallet and a few seconds later I executed listsinceblock 1. My transaction was just broadcasted so it had 0 confirmations, as expected. Note the target-confirmations parameter above which must be greater than 0 no matter what.

So for my test I executed bitcoin-cli listsinceblock 0000000008eb5d53efbb39d2cb9f595e5bd567c295936de5c2282bbb8ef46cf0 1 which returned:

{
    "transactions" : [
        {
            "account" : "",
            "address" : "mzE6DJMHPghYpVg4GCurMbxSSXBfW1KCFH",
            "category" : "receive",
            "amount" : 1.00000000,
            "confirmations" : 0,
            "txid" : "917248d57293a7fd3a88aa3a26026d2e4d6a1d4eef898519b20419f2339c265c",
            "walletconflicts" : [
            ],
            "time" : 1399200157,
            "timereceived" : 1399200157
        }
    ],
    "lastblock" : "0000000004ba22e9f8cea2e843b34f7eeaa2c3b7004ddcf19bfd8af0215fc0cc"
}

Note that the above transaction has 0 confirmations, however listsinceblock is supposed to operate beyond 1 confirmations (which is weird, as I am polling listsinceblock to get new transactions that are always unconfirmed, after Gavin's tip on: How to know there is a new transaction?).

What am I missing here?

Doug Peters

Posted 2014-05-04T11:11:22.800

Reputation: 1 326

Answers

6

As per: https://en.bitcoin.it/wiki/Original_Bitcoin_client/API_calls_list

We have,

[target-confirmations] intentionally does not affect the list of returned transactions, but only affects the returned 'lastblock' value.

What does this mean? It means the lastblock entry in your returned object is the last block you can see on the blockchain (as it the block that currently has exactly 1 confirmation as indicated by the argument you passed in). The lastblock entry is the only field you can affect by changing the target-confirmations argument.

This means that if you want all transactions with at least 1 confirmation, you need to filter this list. This begs the question, why isn't the target-confirmations argument used to do this filtering?

This is because the way the function works currently allows for a use-case in which you can constantly call listsinceblock with the value of lastblock that was returned in your last call. By doing this, your transactions list will contain transactions that reach X or more confirmations on the blockchain in exactly one of those calls, (where X in this case is 1).

Max Steele

Posted 2014-05-04T11:11:22.800

Reputation: 61

As the author of the patch that introduced this command, +1. This is the right answer. (See my comment on GitHub clarifying the rationale.) The point is to allow your application to become aware of transactions below your confirmation target (maybe you display them as unconfirmed to your user) but still notice when they reach that target later.

– cdhowie – 2016-03-08T02:50:25.923

Asked: 2014-05-04T11:11:22.800

Viewed: 1 973 times

Active: 2014-06-26T09:33:43.493