garbage collect zero-value UTXOs #1832

darioAnongba · 2025-10-01T15:04:36Z

Garbage collect the residue orphaned UTXOs when creating transactions. Orphaned UTXOs occur when creating tombstones or full burns.
Currently, these UTXOs accumulate in the DB and are never cleaned. This PR introduces a garbage collection mechanism to collect these UTXOs and use them as inputs of transactions initiated by tapd:

Transfers
Burns

The PR adds a new swept flag to the managed_utxo table because UTXOs are not removed from the table when spent. This flag is also returned by the ListUtxos RPC endpoint.

The mechanism preserves the liveness and safety properties, ensuring that zero-value UTXOs can never accumulate in the DB. Adding garbage collection to Mint transactions is not necessary to ensure these properties.

Fixes #514

Note to reviewers

UTXO meaning unspent, keeping the spent outputs in a table called manage_utxos seems like a contradiction, same logic applies for the need of a swept flag in that table. We should either rename the table or store spent utxos somewhere else?

coveralls · 2025-10-01T15:30:55Z

Pull Request Test Coverage Report for Build 19575345571

Details

293 of 382 (76.7%) changed or added relevant lines in 16 files are covered.
388 unchanged lines in 29 files lost coverage.
Overall coverage increased (+6.7%) to 56.271%

Changes Missing Coverage	Covered Lines	Changed/Added Lines	%
asset/asset.go	3	5	60.0%
itest/assertions.go	0	3	0.0%
itest/test_harness.go	1	5	20.0%
rpcserver.go	10	15	66.67%
tapfreighter/chain_porter.go	40	45	88.89%
tapfreighter/coin_select.go	23	29	79.31%
tapfreighter/wallet.go	59	80	73.75%
tapdb/assets_store.go	106	149	71.14%

Files with Coverage Reduction	New Missed Lines	%
fn/context_guard.go	1	91.94%
fn/func.go	2	58.82%
tapdb/assets_common.go	2	77.97%
tapdb/migrations.go	2	76.19%
tapdb/sqlc/transfers.sql.go	2	82.65%
tapdb/universe_federation.go	2	88.55%
itest/assertions.go	3	87.33%
itest/multisig.go	3	97.94%
proof/courier.go	3	79.57%
tapdb/sqlc/db_custom.go	3	70.83%

Totals
Change from base Build 19360481010:	6.7%
Covered Lines:	64244
Relevant Lines:	114169

💛 - Coveralls

GeorgeTsagk

last nits, 99% there

itest/burn_test.go

itest/integration_test.go

tapfreighter/wallet.go

rpcserver.go

itest/test_list_on_test.go

itest/zero_value_anchor_test.go

GeorgeTsagk

LGTM

docs/release-notes/release-notes-0.8.0.md

tapdb/assets_store.go

lightninglabs-deploy · 2025-11-18T10:48:17Z

@ffranr: review reminder

ffranr

I think we should double check our logic around coin release but otherwise just nits.

ffranr · 2025-11-17T15:23:57Z

tapdb/assets_store.go

+				LeaseExpiry: sql.NullTime{
+					Time:  finalLeaseExpiry.UTC(),
+					Valid: true,
+				},


Could be a helper like sqlInt16

no such thing as a sqlTime. I could add one but then I'll have to change everywhere sql.NullTime is used.

tapdb/assets_store.go

tapfreighter/chain_porter.go

tapfreighter/coin_select.go

tapfreighter/wallet.go

ffranr · 2025-11-18T18:26:58Z

itest/zero_value_anchor_test.go

+	// Send full amount of the new asset. This should sweep Alice's
+	// first tombstone and create a new one.
+	bobAddr2, err := secondTapd.NewAddr(ctxb, &taprpc.NewAddrRequest{
+		AssetId:      genInfo2.AssetId,
+		Amt:          assetAmount,
+		AssetVersion: rpcAssets2[0].Version,
+	})
+	require.NoError(t.t, err)
+
+	sendResp2, _ := sendAssetsToAddr(t, t.tapd, bobAddr2)
+
+	ConfirmAndAssertOutboundTransfer(
+		t.t, t.lndHarness.Miner().Client, t.tapd, sendResp2,
+		genInfo2.AssetId,
+		[]uint64{0, assetAmount}, 1, 2,
+	)
+	AssertNonInteractiveRecvComplete(t.t, secondTapd, 2)


Maybe we can inspect this transaction to ensure that the additional zero-value tombstone input is present.

itest/zero_value_anchor_test.go

ffranr · 2025-11-18T18:37:40Z

itest/assertions.go

-	require.NoError(t, err)
-
-	transferResp, err := sender.ListTransfers(
-		ctxb, &taprpc.ListTransfersRequest{},
-	)
-	require.NoError(t, err)
-
-	transferRespJSON, err := formatProtoJSON(transferResp)
-	require.NoError(t, err)
-	t.Logf("Got response from list transfers: %v", transferRespJSON)


Why remove these lines? That doesn't seem to fix under the commit subject. Same further above also.

Do you mean that I shouldn't remove these logs in this PR or that I should move them to a separate commit?

Why remove these lines?

They're only there to dump the entirety of the responses into the console, which serves no purpose (we should use require to validate assertions).
I've been particularly annoyed by these logs so I try to remove them when I can. Happy to revert or create a dedicated PR.

itest/test_list_on_test.go

This includes the addition of a "swept" field in the "managed_utxos" table with the corresponding migration and the "MarkManagedUTXOAsSwept" function.

…ng family and index

darioAnongba self-assigned this Oct 1, 2025

levmi added this to Taproot-Assets Project Board Oct 2, 2025

github-project-automation bot moved this to 🆕 New in Taproot-Assets Project Board Oct 2, 2025

levmi moved this from 🆕 New to 🏗 In progress in Taproot-Assets Project Board Oct 2, 2025

darioAnongba force-pushed the feat/zero-value-utxo-selection branch from f3a3bff to f55b6c5 Compare October 3, 2025 16:21

darioAnongba changed the base branch from main to 0-8-0-staging October 6, 2025 09:43

darioAnongba force-pushed the feat/zero-value-utxo-selection branch 3 times, most recently from 3bd769d to 6fe11a5 Compare October 6, 2025 15:03

darioAnongba changed the base branch from 0-8-0-staging to main October 6, 2025 15:03

darioAnongba force-pushed the feat/zero-value-utxo-selection branch 10 times, most recently from a8f3ce4 to afbfebf Compare October 9, 2025 13:04

darioAnongba marked this pull request as ready for review October 9, 2025 13:09

darioAnongba force-pushed the feat/zero-value-utxo-selection branch 4 times, most recently from bf3e3ee to d812a8e Compare October 9, 2025 16:04

darioAnongba requested review from Roasbeef and ffranr October 9, 2025 16:25

darioAnongba force-pushed the feat/zero-value-utxo-selection branch from d812a8e to 0ceaf76 Compare October 9, 2025 16:32

darioAnongba moved this from 🏗 In progress to 👀 In review in Taproot-Assets Project Board Oct 9, 2025

darioAnongba force-pushed the feat/zero-value-utxo-selection branch 4 times, most recently from ef93717 to d9383ba Compare October 28, 2025 18:58

GeorgeTsagk reviewed Oct 30, 2025

View reviewed changes

ffranr added this to the v0.8 milestone Oct 30, 2025

darioAnongba force-pushed the feat/zero-value-utxo-selection branch from d9383ba to 773c448 Compare October 30, 2025 13:26

darioAnongba requested a review from GeorgeTsagk October 30, 2025 13:50

GeorgeTsagk approved these changes Oct 30, 2025

View reviewed changes

docs/release-notes/release-notes-0.8.0.md Show resolved Hide resolved

darioAnongba force-pushed the feat/zero-value-utxo-selection branch from 773c448 to 4fb0135 Compare October 30, 2025 15:58

ffranr reviewed Nov 10, 2025

View reviewed changes

tapdb/assets_store.go Show resolved Hide resolved

darioAnongba force-pushed the feat/zero-value-utxo-selection branch 4 times, most recently from 1cf422a to 66faf3f Compare November 10, 2025 21:00

darioAnongba requested a review from ffranr November 10, 2025 21:31

darioAnongba force-pushed the 0-8-0-staging branch from 2b3ac4f to 035a840 Compare November 14, 2025 09:38

darioAnongba force-pushed the feat/zero-value-utxo-selection branch from 66faf3f to 61a19e9 Compare November 14, 2025 09:51

ffranr reviewed Nov 18, 2025

View reviewed changes

darioAnongba added 5 commits November 21, 2025 16:22

tapdb: add support for zero-value utxo sweeping

dc33d1d

This includes the addition of a "swept" field in the "managed_utxos" table with the corresponding migration and the "MarkManagedUTXOAsSwept" function.

tapfreighter: add call to FetchOrphanUTXOs to retrieve zero-value inputs

54f5d2f

tapsend: include BIP32 key derivation to allocation to preserve signi…

95c36fb

…ng family and index

taprpc+rpc: Apply garbage collection in AnchorVirtualPsbts

ede8d8e

itest: add test for zero-value utxo garbage collection

28193cd

darioAnongba force-pushed the feat/zero-value-utxo-selection branch from 61a19e9 to b45eb88 Compare November 21, 2025 15:26

darioAnongba added 2 commits November 21, 2025 16:31

tapcfg: configure sweeping with wallet flag

198faba

docs: add release notes

a686922

darioAnongba force-pushed the feat/zero-value-utxo-selection branch from b45eb88 to a686922 Compare November 21, 2025 15:31

garbage collect zero-value UTXOs #1832

Are you sure you want to change the base?

garbage collect zero-value UTXOs #1832

Conversation

darioAnongba commented Oct 1, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

coveralls commented Oct 1, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Pull Request Test Coverage Report for Build 19575345571

Details

💛 - Coveralls

Uh oh!

GeorgeTsagk left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

GeorgeTsagk left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

lightninglabs-deploy commented Nov 18, 2025

Uh oh!

ffranr left a comment

Choose a reason for hiding this comment

Uh oh!

ffranr Nov 17, 2025

Choose a reason for hiding this comment

Uh oh!

darioAnongba Nov 21, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

ffranr Nov 18, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

ffranr Nov 18, 2025

Choose a reason for hiding this comment

Uh oh!

darioAnongba Nov 21, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

darioAnongba commented Oct 1, 2025 •

edited

Loading

coveralls commented Oct 1, 2025 •

edited

Loading