Bitcoin API questions

Developers
1

I would like to open a thread for specific Bitcoin API questions. If there already is one then please let me know and I move over there. I looked but couldn’t find one as the other threads were more about roadmap and timeline.

The documentation I am looking at is Interface spec and code examples.

EDIT: One should look at the Wiki entry as well.

My first question is about the response obtained from bitcoin_get_utxos which looks like this:

type get_utxos_response = record {
  utxos: vec utxo;
  tip_block_hash: block_hash;
  tip_height: nat32;
  next_page: opt blob;
};

What does tip refer to here? Is that the highest height of any block seen by the Bitcoin canister? Or the highest stable one? Or is one of those heights minus the min_contributions that was passed as an argument in filter?

Is it accurate to say that the set of utxos that is returned is complete up to tip_height and that at tip_height+1 there could be an additional utxo that is not yet returned?

2

Hi @timo!

I believe tip refers to the hash/height of the chain tip that was used to compute the UTXOs, which would be the latest block it has seen minus the min confirmations. So all UTXOs up to and including that block are returned, and later ones are not (because they don’t satisfy the min confirmations).

If you’re interested, you can find the code here bitcoin-canister/canister/src/api/get_utxos.rs at master · dfinity/bitcoin-canister · GitHub.

2 Likes
3

Yes, this is correct. Note that things are slightly more complicated if there are forks as documented on the wiki page.

Further note that the returned tip does not change when using the pagination feature for large UTXO sets, that is, responses for different pages still contain the same tip block hash and tip height.

4

Why is it more complicated? The wiki entry does not describe how the returned utxos are assembled in case there is a fork present. So I suppose it is straight-forward: it takes the utxos as per the chain to the tip and ignores the utxos that are created or spent only on the fork. Is that not the case?

5

The wiki does specify how confirmations are counted, right?
The confirmation counts are then used to filter the list of UTXOs.

it takes the utxos as per the chain to the tip and ignores the utxos that are created or spent only on the fork. Is that not the case?

As mentioned above, it is a bit more complicated than that, mainly to deal with the (small) risk of long, competing forks.
In a nutshell, the number of confirmation is tied to the stability count of the block that contains the transaction.
For a detailed explanation, please read the paragraph about forks (“In order to reduce the risk of inconsistencies due to forks…”).

If anything is not clear, please let me know!

6

Yes, it does. Ok, it’s clear now and works as I suspected (that confirmations on the fork blocks are 0).