Get burn blocks

[He1DAr]

Suggested interface:
GET /burn-blocks?limit={limit}&offset={offset}
Response:

{
    limit: number;
    offset: number;
    total: number;
    results: Array<BurnBlock>;
}

[zone117x]

Can you give some details into what you expect the BurnBlock object to contain? We have a very limited view of the bitcoin chain. Pretty much all burnchain related data is already exposed (essentially just burn hashes associated with stacks blocks).

More bitcoin block info (e.g. like what bitcoin explorers show) is out-of-scope for this service.

[He1DAr]

This is what we plan to display for BTC blocks, basically hash, height and timestamp.

[zone117x]

The API only receives this for burn blocks that have an associated stacks block. So if there are "flash blocks" where the a burn block is skipped, we won't have this info. For the burnchain block data we do have, the current /extended/v1/block endpoint will already give you this data.

E.g. https://api.dev.hiro.so/extended/v1/block

{
  "limit": 20,
  "offset": 0,
  "total": 131279,
  "results": [
    {
      "burn_block_time": 1702030405,
      "burn_block_time_iso": "2023-12-08T10:13:25.000Z",
      "burn_block_hash": "0x000000000000000000019ad3831a51e9f85ced2b61f1a723b1b6ca174f9862e3",
      "burn_block_height": 820246,
      ...
    },
    {
      "burn_block_time": 1702029924,
      "burn_block_time_iso": "2023-12-08T10:05:24.000Z",
      "burn_block_hash": "0x00000000000000000002c221d75afa237fe0c46e08944f8285a1bbe1430583cc",
      "burn_block_height": 820245,
      ...

I don't think it makes sense to create a new endpoint that does the same thing but only includes the burn_block data, it will just result in more cache-misses (more load on the API, more rate-limiting on the client).

Can you confirm that this works for you?

[He1DAr]

correct me if I'm wrong, to get the last n burn block hashes, we'd need to use extended/v1/block and keep paginating until we see 3 unique burn block hashes?

[zone117x]

Yeah that's true, you'd potentially have to paginate extra to get the last n burn blocks. That's probably a good enough reason to implement a new endpoint for this.