feat: implement clarity Contract cache

[cylewitruk-stacks]

Description

Builds on #7049 (ResidentBytes impl) for calculating resident memory size. Currently in draft status until that PR merges.

Adds a size-weighted read-through TinyUFO cache (written by Cloudflare; uses S3-FIFO eviction + TinyLFU admission) for parsed Clarity Contract instances:

• The cache uses a CACHE_WEIGHT_UNIT of 256, which the resident_bytes() size of a CachedContract is divided by (since TinyUFO's weight system uses u16), allowing for a maximum cacheable entry size of roughly 16MiB each.
• The DEFAULT_CONTRACT_CACHE_SIZE is set to 64MiB (64 * 1024 * 1024), which gives a cache-wide weight limit of 262,144 units. TinyUFO enforces this budget on every insertion, evicting entries by access frequency to stay within the limit.
• The cache tracks the last block hash + epoch and clears itself when it detects a reorg or epoch change to prevent providing stale contracts.
• Read-only/ephemeral Clarity db's are wired up, but will only use the cache if reading at chain tip.

Applicable issues

• Part of https://github.com/stx-labs/core-epics/issues/126

Additional info (benefits, drawbacks, caveats)

NOTE: The cache is implemented as a node-level cache and as such is purely a node optimization; a next iteration which incorporates tx-level caching policy for targeting tenure budgets could implement its own tx-scoped cache on top of the node-level cache with stricter/deterministic policy.

Some benchmark results:

Benchmark	No Cache	Cached	Speedup
direct_call/increment	32.456 µs	8.248 µs	3.9x
contract_call/proxy_increment	55.053 µs	9.462 µs	5.8x
repeated_calls/10x_proxy_increment	799.16 µs	119.73 µs	6.7x
deep_fold/4_deep_x20_fold	2,150.6 µs	255.66 µs	8.4x

Checklist

• Test coverage for new or modified code paths
• Changelog fragment(s) or "no changelog" label added (see changelog.d/README.md)

[Copilot]

Pull request overview

Implements a size-weighted, read-through cache for parsed Clarity Contract instances to reduce repeated contract parsing/loading overhead while keeping cache correctness across reorgs and epoch transitions.

Changes:

• Add ResidentBytes trait (and implementations) to estimate heap+stack footprint for cache weighting.
• Introduce a TinyUFO-backed ContractCache and wire it through Clarity DB/VM call paths (including cost-contract loads).
• Add tests and a Criterion benchmark to validate/measure caching behavior and correctness guards (tip-only, rollback/reorg/epoch invalidation).

Reviewed changes

Copilot reviewed 22 out of 23 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
stackslib/src/clarity_vm/clarity.rs	Plumbs cache through block/tx/read-only connections and adds integration tests for persistence/bypass/invalidation.
stacks-common/src/util/macros.rs	Extends guarded_string! types with heap_capacity() for sizing.
clarity/src/vm/types/signatures.rs	Adds ResidentBytes impl for FunctionSignature.
clarity/src/vm/functions/mod.rs	Switches contract lookup in contract-of to cached contract load.
clarity/src/vm/functions/database.rs	Uses cached contract loads during trait-based dispatch checks.
clarity/src/vm/database/structures.rs	Adds ResidentBytes impls for token/map/var metadata types.
clarity/src/vm/database/mod.rs	Exposes ContractCache/CachedContract and adds module.
clarity/src/vm/database/key_value_wrapper.rs	Adds is_retargeted() and a test helper to bypass caches on historical views.
clarity/src/vm/database/contract_cache.rs	New TinyUFO-backed weighted cache implementation with unit tests.
clarity/src/vm/database/clarity_db.rs	Adds optional cache attachment and cached contract/load-cost accessors with retarget bypass.
clarity/src/vm/costs/mod.rs	Loads cost-contract contexts via cached contract loads.
clarity/src/vm/contracts.rs	Adds ResidentBytes impl for Contract plus tests for sizing consistency.
clarity/src/vm/contexts.rs	Adds ResidentBytes impl for ContractContext; charges load cost before contract load using cached cost-size path.
clarity/src/vm/callables.rs	Adds ResidentBytes impl for DefinedFunction.
clarity/Cargo.toml	Adds TinyUFO dependency and a contract_cache benchmark target.
clarity/benches/contract_cache.rs	Adds Criterion benchmark comparing cached vs uncached contract execution.
clarity-types/src/types/mod.rs	Adds FunctionIdentifier::heap_capacity() for sizing.
clarity-types/src/resident_bytes.rs	New ResidentBytes trait and implementations for many Clarity types and std containers.
clarity-types/src/lib.rs	Exports the new resident_bytes module.
changelog.d/README.md	Tweaks example fenced block language (text).
changelog.d/7049-clarity-type-size-approximation.added	Adds changelog fragment for the ResidentBytes addition.
Cargo.toml	Adds workspace dependency entry for TinyUFO.
Cargo.lock	Locks TinyUFO and its transitive dependencies.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[coveralls]

Coverage Report for CI Build 25800686541

Coverage increased (+0.07%) to 85.786%

Details

• Coverage increased (+0.07%) from the base build.
• Patch coverage: 20 uncovered changes across 5 files (1709 of 1729 lines covered, 98.84%).
• 5424 coverage regressions across 104 files.

Uncovered Changes

File	Changed	Covered	%
clarity-types/src/resident_bytes.rs	655	645	98.47%
clarity/src/vm/costs/mod.rs	19	12	63.16%
clarity/src/vm/contracts.rs	174	173	99.43%
clarity/src/vm/database/clarity_db.rs	271	270	99.63%
stackslib/src/clarity_vm/clarity.rs	276	275	99.64%

Coverage Regressions

5424 previously-covered lines in 104 files lost coverage.

Top 10 Files by Coverage Loss	Lines Losing Coverage	Coverage
stackslib/src/config/mod.rs	358	69.04%
stackslib/src/chainstate/stacks/index/storage.rs	262	80.55%
stackslib/src/chainstate/stacks/miner.rs	231	83.74%
stackslib/src/net/inv/epoch2x.rs	213	79.95%
stackslib/src/chainstate/stacks/db/transactions.rs	203	97.13%
stackslib/src/net/chat.rs	202	92.95%
stackslib/src/chainstate/stacks/db/mod.rs	196	86.23%
stackslib/src/chainstate/stacks/index/trie_sql.rs	190	69.7%
stackslib/src/core/mempool.rs	170	86.87%
stackslib/src/chainstate/stacks/index/node.rs	161	87.28%

---

Coverage Stats

Relevant Lines:	221317
Covered Lines:	189860
Line Coverage:	85.79%
Coverage Strength:	20001262.47 hits per line

---

💛 - Coveralls