Get STX blocks by BTC block

[He1DAr]

Hello team,
We are currently working on a new feature in the explorer to display a list of STX blocks associated with a specific BTC block. For this, we need a new endpoint that accepts either the BTC block hash or height and returns a paginated list of STX blocks.
Suggested interface:
GET /blocks/by_burn_block_hash/{burn_block_hash}?limit={limit}&offset={offset}
Response:

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

[zone117x]

This is doable. One issue is that we already have the endpoints:

• /extended/v1/block/by_burn_block_hash/{burn_block_hash} and
• /extended/v1/block/by_burn_block_height/{burn_block_height}

These return a single stacks block. With Nakamoto, these should return an array of stacks blocks, but that would be a breaking change. I wonder if we should just create new endpoints with the same name but bump the version to /extended/v2/....

@rafaelcr any thoughts?

[He1DAr]

That makes sense. I was suggesting /blocks e.g. /blocks/by_burn_block_hash/{burn_block_hash}?limit={limit}&offset={offset}

[zone117x]

I don't think we should change the endpoint naming convention (block to blocks) just to avoid a naming collision. I'm leaning towards one of the following:

• new path component e.g. /v1/block/by_burn_block_hash/many/{hash}
• new path name e.g. /v1/block/many_by_burn_block_hash/{hash}
• version bump e.g. /v2/block/by_burn_block_hash/{hash}

@rafaelcr what do you think?

[rafaelcr]

Moving to /extended/v2 makes perfect sense, because the /extended/v1/block endpoint just doesn't make sense anymore after Nakamoto. I think we should:

1. Create a new generic blocks endpoint /extended/v2/blocks which returns a paginated list of Stacks blocks. For a more REST-ful approach, we would add a GET filter like burn_block_height or burn_block_hash to get the paginated list for 1 Bitcoin block (and other filters too). This would also be backwards compatible because it would only return an array of length 1 for pre-Nakamoto Bitcoin blocks.
2. Keep the old /extended/v1/block endpoint with the current functionality, but have it return a HTTP 400 error on blocks post-Nakamoto

What do you think?

[zone117x]

@rafaelcr I like that approach. A new endpoint that uses filter query params makes sense.

For post-Nakamoto behavior, I think we should only return HTTP 400 for the endpoints that actually break / don't make sense. That will limit the amount of breaking changes to the couple /extended/v1/block/by_burn_block* endpoints. We can mark the others as deprecated though so we are more prepared to remove them later on.

[zone117x]

Note: this new endpoint should also allow returning blocks from the latest tenure (as requested in #1755), this could be done by allowing the key latest in the burn_block filter.

[blockstack-devops]

🎉 This issue has been resolved in version 7.4.0-nakamoto.4 🎉

The release is available on:

• npm package (@nakamoto dist-tag)
• npm package (@nakamoto dist-tag)
• GitHub release

Your semantic-release bot 📦🚀