universe+tapdb: add new block_height field to universe_leaves use that to implement block height based supply tree queries

[Roasbeef]

In this PR, we add a new method FetchSupplyLeavesByHeight, that can be used to query for the leaves of a supply tree by height. This will be useful for writing the new syncing state machine and the sub-system that serves the supply tree syncer. Such a syncer would start from the initially created pre-commitment, then fetch all the leaves for the future updates, assemble those into the supply tree, then verify that everything matches up.

Prompts used during development (aider+Gemini 2.5-pro-06-5)

Initial draft creation

Based on by working memory of this new feature, I scanned the relevant files, then made mental nodes of what needed to be updated. I then drafted this fairly detailed prompt that guided aider w.r.t which files to update, and the set of high level changes to make.

#### Today we assemble the individual updates (burn, ignore, mint) for a given asset  
#### specifier (group key is what we care about) into distinct trees for each type.  
#### We then further aggregrate each of those roots into a unified supply tree for  
#### the entire asset specifier. This tree commits to a root sum of the supply (you  
#### can subtract out any of the roots from the root sum to derive a snapshot of the  
#### supply such as the amt burnt, etc).  
####   
#### We then also have a system to assemble these updates, then commit then in a  
#### batch, this exists in: tapdb/supply_commit.go and tapdb/supply_tree.go.  
####   
#### For each of the supply sub-trees, we actually re-use the existing  
#### universe_leaves table to point to each of the respective leaves.  
####   
#### In this task, we want to add a block height to this leaf, as this'll allow us  
#### to scan the leaves in order, based on the type, so we can send out the set of  
#### leaves added in a state transition to a party that wants to sync the set of  
#### leaves.  
####   
####   
#### For this, we may need to update the set of queries in:  
#### tapdb/sqlc/queries/universe.sql. Of interest is also the  
#### applySupplyUpdatesInternal helper function, as we'll want to make sure that the  
#### helper functions that it calls properly inserts the height into the ultimately  
#### universe leaf. For the mint and burn types, we can obtain this height from the  
#### issuance proof.  
####   
#### For the ignore type, we'll need to add a block height field to  
#### universe.IgnoreTuple (universe/ignore_records.go).  
####   
#### For the leaves, we'll likely need to add a new migration (38) which adds the  
#### new height field (can be NULL) to the universe_leaves table.  
####   
#### We'll likely also want to add a new BlockHeight() method to the  
#### SupplyUpdateEvent interface.  
####   
#### Next, we'll want a new method on the SupplyTreeStore that given a start+end  
#### height and a specifier, the set of updates whose universe_leaves have a block  
#### height between that param. This may need to update  
#### tapdb/sqlc/queries/supply_tree.sql.  
####   
#### Also see tapdb/querier.go.  
####   
#### Ruminate on my sketch above, then let's create an execution plan remembering  
#### the ultimate goal. From there we'll implement each portion.  

Subsequent iterations

From here I made an edit or two to get things compiling. Then I executed a series of prompts to refine the code, refactor slightly, then add unit tests.

inside multiverse.UpsertProof Leaf, let's use SparseDecode instead along with BlockHeightRecord as we don't need to decode the entire proof just to get the block height

let's use the same sparse decode in BaseUniverseStore.UpsertProofLeaf

let's do the same for SupplyTreeStore.RegisterMintSupply (sparse decode)

can we morph that into a function closure invocation that itself returns lfn.Option[uint32]? so we don't leak that intermediate variable to the higher scope

great! but now we have a bit of duplication, can we make a helper function can call that intead of having the same duplication everywhere? we can put the helper function in tapdb/sqlutils.go

nice! now let's extend the unit tests in tapdb/supply_tree_test.go to cover the new FetchSupplyLeavesByHeight method.

I messed when committing and dropped a commit entirely (lol), so I had aider re-add it:

help me ree-add QuerySupplyLeavesByHeight back to tapdb/sqlc/queries/supply_tree.sql, I deleted it accidentally

[Roasbeef]

Rebased.

[coveralls]

Pull Request Test Coverage Report for Build 16428331342

Warning: This coverage report may be inaccurate.

This pull request's base commit is no longer the HEAD commit of its target branch. This means it includes changes from outside the original pull request, including, potentially, unrelated coverage changes.

• For more information on this, see Tracking coverage changes with pull request builds.
• To avoid this issue with future PRs, see these Recommended CI Configurations.
• For a quick fix, rebase this PR at GitHub. Your next report should be accurate.

Details

• 159 of 215 (73.95%) changed or added relevant lines in 10 files are covered.
• 61 unchanged lines in 15 files lost coverage.
• Overall coverage increased (+0.01%) to 56.472%

---

Changes Missing Coverage	Covered Lines	Changed/Added Lines	%
tapdb/sqlc/universe.sql.go	1	2	50.0%
tapdb/universe.go	18	20	90.0%
tapdb/sqlutils.go	11	14	78.57%
universe/supplycommit/states.go	8	11	72.73%
tapdb/multiverse.go	12	16	75.0%
universe/ignore_records.go	9	13	69.23%
tapdb/sqlc/supply_tree.sql.go	19	27	70.37%
tapdb/supply_tree.go	62	93	66.67%

Files with Coverage Reduction	New Missed Lines	%
fn/context_guard.go	1	88.71%
asset/asset.go	2	79.23%
rfqmsg/records.go	2	70.25%
tapdb/multiverse.go	2	82.48%
tapdb/sqlc/assets.sql.go	2	74.29%
universe_rpc_diff.go	2	76.0%
universe/syncer.go	2	86.63%
tapdb/sqlerrors.go	3	67.86%
tapdb/assets_common.go	4	78.19%
tapdb/mssmt.go	4	90.45%

Totals
Change from base Build 16427162624:	0.01%
Covered Lines:	57863
Relevant Lines:	102463

---

💛 - Coveralls

[lightninglabs-deploy]

@ffranr: review reminder

[guggero]

Looks great! Got a couple of suggestions and the linter isn't fully happy yet. Other than that LGTM 🎉

[guggero]

nit: feels like this would make a good package-level variable with the list of tree types we often iterate over? Would also help a bit with the formatting/readability.

[Roasbeef]

Good idea, added.

[ffranr]

Pretty much there. One question on SQL query re-use.

[ffranr]

We already have a where clause in QueryUniverseSupplyLeaves. Instead of adding a new query here, can't we just extend QueryUniverseSupplyLeaves with an optional block height?

[Roasbeef]

Good eye. These queries differ slightly though: the above is based on always knowing the root_id to pass in (hence the join with universe supply roots). Here we query based on just the namespace, so we can skip the extra join on the root.

[Roasbeef]

This should be ready for a final pass. The unit test failure is being addressed in another PR to improve the set of property based tests.

[guggero]

LGTM 🎉

[ffranr]

LGTM!