tapdb: switch proof cache to size-based limits and add deep size estimation #1870

ffranr · 2025-11-07T16:47:36Z

Issue: #1865

This PR introduces a size-based proof cache and supporting deep-size logic.

Summary

Replace proof-count cache limits with a byte-size limit.
Add human-readable size parsing in configuration.
Introduce deep size estimation (LowerBoundByteSize) and apply it to proof cache entries.
Update proof cache keys for finer-grained eviction.
Improve error handling and logging around cache initialization.

Note

It's pretty trivial to get from here to logging cache size, but we need lightninglabs/neutrino#330 for that.

gemini-code-assist · 2025-11-07T16:47:59Z

Summary of Changes

Hello @ffranr, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request significantly refactors the tapdb proof caching mechanism by transitioning from a simple count-based eviction strategy to a more sophisticated size-based approach. This change aims to provide more efficient and predictable memory usage for the proof cache. It introduces a robust deep size estimation utility for Go objects and updates the configuration to be more user-friendly with human-readable size inputs. Additionally, cache keying and management logic have been refined for better performance and error handling.

Highlights

Size-Based Proof Cache: The proof cache now uses a byte-size limit instead of a count-based limit, allowing for more accurate memory management. The default size is set to 32MB.
Deep Size Estimation: A new utility function, LowerBoundByteSize, has been introduced in the fn package to provide a conservative deep-size estimate of Go objects, including handling pointers and cycles. This is crucial for the new size-based cache.
Human-Readable Configuration: The configuration for the maximum proof cache size now accepts human-readable values like '32MB' or '1GB', improving user experience.
Finer-Grained Cache Eviction: The proof cache keys have been updated to UniverseProofKey, which combines the universe ID and leaf key, enabling more granular eviction of cached proofs.
Improved Error Handling and Logging: Error handling around MultiverseStore initialization has been enhanced, and logging messages for cache operations have been made more descriptive.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	`/gemini review`	Performs a code review for the current pull request in its current state.
Pull Request Summary	`/gemini summary`	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	`/gemini help`	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

gemini-code-assist

Code Review

This pull request introduces a significant improvement by switching the proof cache from count-based to size-based limits, incorporating deep size estimation for more accurate memory management. The changes also include finer-grained eviction strategies for cache entries and enhanced error handling and logging around cache initialization. The new LowerBoundByteSize function, utilizing reflect and unsafe, provides a conservative estimate of an object's memory footprint, which is crucial for the new cache mechanism. Comprehensive unit tests have been added for this new functionality, covering various data types and edge cases like pointer cycles. Configuration options have been updated to support human-readable size values for the cache limit. Overall, the changes align well with the stated objective of improving cache efficiency and control.

tapdb/multiverse_cache.go

coveralls · 2025-11-07T17:12:42Z

Pull Request Test Coverage Report for Build 19709230089

Details

221 of 240 (92.08%) changed or added relevant lines in 6 files are covered.
91 unchanged lines in 19 files lost coverage.
Overall coverage increased (+0.06%) to 56.668%

Changes Missing Coverage	Covered Lines	Changed/Added Lines	%
tapdb/multiverse.go	12	14	85.71%
fn/memory.go	89	93	95.7%
tapdb/multiverse_cache.go	91	104	87.5%

Files with Coverage Reduction	New Missed Lines	%
tapdb/multiverse_cache.go	1	91.85%
mssmt/compacted_tree.go	2	79.03%
tapcfg/server.go	2	79.55%
tapdb/mssmt.go	2	90.45%
tapdb/multiverse.go	2	80.69%
tapdb/sqlc/mssmt.sql.go	2	48.34%
tapdb/sqlc/transfers.sql.go	2	82.65%
tapdb/universe.go	2	81.04%
tapgarden/custodian.go	2	77.57%
itest/multisig.go	3	97.94%

Totals
Change from base Build 19707991000:	0.06%
Covered Lines:	64753
Relevant Lines:	114267

💛 - Coveralls

lightninglabs-deploy · 2025-11-21T18:49:50Z

@darioAnongba: review reminder
@GeorgeTsagk: review reminder
@ffranr, remember to re-request review from reviewers when ready

Introduce `LowerBoundByteSize` for deep-size estimation of various data types, handling primitives, structs, slices, maps, and pointer cycles. Add unit tests to ensure correctness and coverage.

- Replace `ProofKey` with `UniverseProofKey` for clearer cache key distinction, enabling removal of individual proofs by leaf key instead of all proofs for a universe ID. - Refactor proof cache methods: add `RemoveLeafKeyProofs` and enhance `RemoveUniverseProofs` for more granular control. - Implement deep size estimation in the `Size` method to improve memory management accuracy. - Change cache size limit from number of proofs to total memory size of all proofs, as proof sizes can vary due to inclusion of parent proof files.

- Replace `proofs-per-universe` configuration with `max-proof-cache-size`, allowing proof cache limits to be defined by total memory size instead of proof count. - Add logic to parse and handle human-readable size values (e.g., "32MB"). - Update default configuration and related comments. - Adjust `NewMultiverseStore` to use parsed cache size values and improve error handling.

Updates the dependency to expose the Size() method on cache implementations, enabling direct access to cache size.

* Add support for an optional cache size callback to newCacheLogger. * Enable cache size logging in the universe proof cache.

GeorgeTsagk · 2025-11-25T18:36:37Z

universe/interface.go

 }

+// LowerBoundByteSize returns the lower bound on the byte size of the proof.
+func (p *Proof) LowerBoundByteSize() uint64 {


could also add some test coverage for the LowerBoundByteSize function of universe.Proof

universe.Proof.LowerBoundByteSize just delegates to fn.LowerBoundByteSize, and the underlying function already has test coverage.

Maybe I've misunderstood what you mean.

I mean we should create dummy universe.Proof instances and verify that an iteration of fn.LowerBoundByteSize over it actually returns the size of it.

I guess if we're very confident on the fn function coverage this is actually not needed. Would only be a sanity check that it can iterate a proof properly.

tapdb/multiverse_cache.go

GeorgeTsagk · 2025-11-25T18:45:53Z

tapdb/multiverse.go

 		),
 		transferProofDistributor: fn.NewEventDistributor[proof.Blob](),
-	}
+	}, nil


can drop this commit -- seems like no error is ever returned?

The next commit adds an error return code path to NewMultiverseStore.

GeorgeTsagk · 2025-11-25T18:50:35Z

tapdb/multiverse_cache.go

-	return lru.NewCache[ProofKey, *cachedProofs](proofCacheSize)
+//
+// nolint: lll
+func newProofCache(totalCacheBytesSize uint64) *lru.Cache[UniverseProofKey, *cachedProofs] {


I wonder if a direction where proof entries lack the recursive element (i.e size within bounds or fixed) is a better approach to this overall. Even with a fully fledged size aware cache we'll still have overlapping content between various proof files.

The PR seems in good shape so def not worth changing our mind now. Should make sure there's an issue tracking the elimination of the recursive element of the entries.

I think we need both this size aware cache and also proof reference optimisation. This issue tracks most of the proof optimisation work: #503

Also, enhance the release notes template with a section to aid in reporting breaking config changes.

ffranr self-assigned this Nov 7, 2025

ffranr added universe proofs cache labels Nov 7, 2025

gemini-code-assist bot reviewed Nov 7, 2025

View reviewed changes

tapdb/multiverse_cache.go Outdated Show resolved Hide resolved

ffranr force-pushed the wip/limit-proof-cache-size branch from f273430 to e2c0aad Compare November 7, 2025 16:57

ffranr changed the base branch from main to 0-8-0-staging November 7, 2025 16:57

ffranr force-pushed the wip/limit-proof-cache-size branch from e2c0aad to 7e26748 Compare November 7, 2025 16:58

levmi added this to Taproot-Assets Project Board Nov 10, 2025

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

levmi added this to the v0.8 milestone Nov 10, 2025

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

ffranr requested review from GeorgeTsagk and darioAnongba November 11, 2025 19:16

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

ffranr added 10 commits November 24, 2025 14:30

tapdb: improve cache related log messages

1bf2b55

fn: add LowerBoundByteSize function and associated unit tests

f896ac9

Introduce `LowerBoundByteSize` for deep-size estimation of various data types, handling primitives, structs, slices, maps, and pointer cycles. Add unit tests to ensure correctness and coverage.

universe: fix receiver name

84f36c1

universe: add LowerBoundByteSize method to Proof struct

f234869

tapdb: add support for error return from NewMultiverseStore

e08e68a

go.mod: bump neutrino/cache to v1.1.3

f073ca1

Updates the dependency to expose the Size() method on cache implementations, enabling direct access to cache size.

tapdb: extend newCacheLogger with func option for size callback

62052de

* Add support for an optional cache size callback to newCacheLogger. * Enable cache size logging in the universe proof cache.

tapdb: add TestUniverseProofCache unit tests

0b29bb2

ffranr force-pushed the wip/limit-proof-cache-size branch from 362970f to 8619862 Compare November 24, 2025 14:44

ffranr changed the base branch from 0-8-0-staging to main November 24, 2025 14:46

ffranr force-pushed the wip/limit-proof-cache-size branch from 8619862 to 140f544 Compare November 24, 2025 15:07

GeorgeTsagk reviewed Nov 25, 2025

View reviewed changes

ffranr added 2 commits November 26, 2025 15:31

tapdb: add inner proof size cache to type cachedProofs

26a2228

docs: add release notes

edce8ac

Also, enhance the release notes template with a section to aid in reporting breaking config changes.

ffranr force-pushed the wip/limit-proof-cache-size branch from 140f544 to edce8ac Compare November 26, 2025 15:38

ffranr requested review from jtobin and removed request for darioAnongba November 26, 2025 15:51

tapdb: switch proof cache to size-based limits and add deep size estimation #1870

Are you sure you want to change the base?

tapdb: switch proof cache to size-based limits and add deep size estimation #1870

Uh oh!

Conversation

ffranr commented Nov 7, 2025

Note

Uh oh!

gemini-code-assist bot commented Nov 7, 2025

Summary of Changes

Highlights

Footnotes

Uh oh!

gemini-code-assist bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

Uh oh!

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

Uh oh!

Pull Request Test Coverage Report for Build 19709230089

Details

💛 - Coveralls

Uh oh!

lightninglabs-deploy commented Nov 21, 2025

Uh oh!

GeorgeTsagk Nov 25, 2025

Choose a reason for hiding this comment

Uh oh!

ffranr Nov 26, 2025

Choose a reason for hiding this comment

Uh oh!

GeorgeTsagk Nov 26, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

GeorgeTsagk Nov 25, 2025

Choose a reason for hiding this comment

Uh oh!

ffranr Nov 26, 2025

Choose a reason for hiding this comment

Uh oh!

GeorgeTsagk Nov 25, 2025

Choose a reason for hiding this comment

Uh oh!

ffranr Nov 26, 2025

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

coveralls commented Nov 7, 2025 •

edited

Loading