Refined memory/cpu cost models for ValueData and UnValueData

[Unisay]

Context

• What: Replace constant memory costs with linear models for ValueData and UnValueData builtins
• Why: Existing constant memory costs (1 unit) don't reflect actual memory behavior, leading to inaccurate costing
• Approach: Empirical measurement using new memory-analysis tooling to derive accurate linear coefficients

Problem Statement

The current cost models for ValueData and UnValueData use constant memory costs of 1 unit, regardless of input size. This is inaccurate because:

• ValueData: Serializes a Value to Data, memory should scale with serialized size
• UnValueData: Deserializes Data to Value, memory should scale with node count in the Data structure

Inaccurate memory models can lead to budget misestimation in smart contracts.

Solution Approach

This PR implements a comprehensive solution in 6 logical commits:

1. Infrastructure: Add memory-analysis executable with plotting and regression utilities
2. Core Implementation: Introduce DataNodeCount newtype for node-based memory tracking
3. Type System Integration: Wire DataNodeCount into the DefaultUni type system
4. Builtin Application: Apply specialized wrappers (ValueTotalSize, DataNodeCount) to builtins
5. Benchmark Alignment: Update benchmarks to use the new memory wrappers
6. Cost Model Update: Replace constant costs with empirically-derived linear models

Memory Measurement Strategy

• ValueData: Use ValueTotalSize wrapper (already exists) - measures total serialized size
• UnValueData: Use new DataNodeCount wrapper - performs lazy node traversal of Data structure

This approach separates concerns:

• Memory measurement logic lives in ExMemoryUsage.hs (slope applied per node/byte)
• Cost coefficients live in JSON cost models (intercept + slope multiplier)

Design Decisions

Why node count for UnValueData?

• UnValueData converts Data → Value by traversing the Data tree structure
• Memory cost scales with tree complexity measured as node count
• Node count reflects the structural traversal work performed
• Lazy traversal (via CostRose) ensures accurate accounting

Why separate wrappers?

• Type safety: each wrapper represents a specific memory measurement strategy
• Flexibility: can tune coefficients independently via JSON
• Clarity: explicit in builtin signatures what memory model is used

Changes

Memory Analysis Tooling

New executable: plutus-benchmark:memory-analysis

• PlutusBenchmark.MemoryAnalysis: Main analysis framework
• PlutusBenchmark.MemoryAnalysis.Experiments: Memory behavior experiments
• PlutusBenchmark.MemoryAnalysis.Generators: Test data generators
• PlutusBenchmark.Plotting: Chart generation utilities
• PlutusBenchmark.RegressionInteger: Regression with asymmetric loss

This tooling enabled empirical measurement of memory behavior to derive the coefficients used in the cost models.

Core Memory Tracking

plutus-core/src/PlutusCore/Evaluation/Machine/ExMemoryUsage.hs

• Added DataNodeCount newtype wrapping Data
• Implemented ExMemoryUsage instance using countNodesRoseScaled
• Helper function performs lazy node traversal with slope-per-node accounting
• Language extensions: AllowAmbiguousTypes, BlockArguments, InstanceSigs, KindSignatures, ScopedTypeVariables

plutus-core/src/PlutusCore/Default/Universe.hs

• Added KnownTypeAst instance for DataNodeCount
• Added MakeKnownIn and ReadKnownIn instances for marshalling
• Minor refactoring: use void instead of (() <$) for clarity

Builtin Updates

plutus-core/src/PlutusCore/Default/Builtins.hs

• ValueData: Changed signature from Value -> Data to ValueTotalSize -> Data
• UnValueData: Changed signature from Data -> BuiltinResult Value to DataNodeCount -> BuiltinResult Value
• Both changes enable accurate memory accounting via specialized wrappers

Benchmark Alignment

plutus-core/cost-model/budgeting-bench/Benchmarks/Values.hs

• Updated valueDataBenchmark to use createOneTermBuiltinBenchWithWrapper with ValueTotalSize
• Updated unValueDataBenchmark to use createOneTermBuiltinBenchWithWrapper with DataNodeCount
• Ensures benchmarks measure the same memory behavior as production builtins

Cost Model Data

plutus-core/cost-model/data/builtinCostModel{A,B,C}.json

Updated memory models (all three variants updated identically):

"valueData": {
  "memory": {
    "arguments": {
      "intercept": 6,
      "slope": 38
    },
    "type": "linear_in_x"
  }
}

Memory = 38 × size + 6 (was constant 1)

"unValueData": {
  "cpu": {
    "arguments": {
      "intercept": 1000,
      "slope": 290658
    },
    "type": "linear_in_x"
  },
  "memory": {
    "arguments": {
      "intercept": 0,
      "slope": 8
    },
    "type": "linear_in_x"
  }
}

Memory = 8 × nodes + 0 (was constant 1)
CPU = 290658 × nodes + 1000 (updated from 43200 × arg + 1000)

plutus-core/cost-model/data/benching-conway.csv

Regenerated benchmark data (404 lines changed) with new memory measurement approach.

Impact

Budget Changes

Scripts using ValueData or UnValueData will see different memory budget consumption:

• Small values: Similar or slightly higher memory cost
• Large values: Significantly more accurate memory cost (linear scaling)
• CPU costs: UnValueData CPU costs updated to reflect node-based measurement

Conformance Tests

Expect budget differences in conformance tests that use these builtins. The new costs are more accurate than the previous constant models.

4. Memory Analysis

The memory-analysis executable can reproduce the experiments:

cabal run plutus-benchmark:memory-analysis

This generates plots and regression analysis in plutus-benchmark/memory-analysis/data/.

5. Conformance Tests

cabal test plutus-conformance

Expect budget differences but correct behavior.

Notes for Reviewers

Commit Structure

The PR is organized as 6 atomic commits following dependency order:

1. Infrastructure (analysis tools)
2. Core implementation (DataNodeCount)
3. Type system integration
4. Builtin application
5. Benchmark alignment
6. Cost model data

Each commit is buildable and represents a logical unit of change.

The updated CPU models for ValueData and UnValueData could be previewed here.

[ana-pantilie]

I don't think we should implement our own linear regression algorithm when R is the domain standard for this.

[kwxm]

Neither do I!

[zliu41]

Obviously, ValueData can not be constant time!

[kwxm]

See the Slack discussion about this. We'll need to do something like using nf instead of whnf for the CPU costing for valueData, the problem being that the implementaion of valueData begins with Map . ... and whnf won't cause the stuff in ... (which does all the hard work) to be evaluated.

[kwxm]

Can you open a new PR that just updates the costs and doesn't include the memory cost inference stuff in PlutusBenchmark? I think that determining the memory costs empirically instead of just waving our hands and coming up with a rough estimate is a promising idea, but it's quite a big change and it's kind of orthogonal to what we're trying to achieve at the moment. As long as we have a measure of the memory cost it doesn't matter too much where it came from (although I do have some small reservations: see the comments). Keep the memory usage inference code somewhere though! We can come back and think about this more carefully after the pressure to get everything ready for the HF has relaxed.

However, the main thing that needs to be changed is the CPU costing for valueData: the current constant cost is definitely wrong, but that should be fixable.

[kwxm]

This will need to have an intercept and slope since the CPU cost of valueData should be linear (and similarly in the other ParamName files).

[kwxm]

I don't think you need all this. It should be enough to count the nodes (so the same thing, but replacing s with 1), and then runOneArgumentModel will do the scaling for you.

[kwxm]

No, hold on. The only time this is called is with s=1 anyway, so why the extra generality?

[kwxm]

Is this comment correct? The ExMemoryUsage instance doesn't mention the intercept.

[kwxm]

I was a bit worried about what would happen here when we extend Data to have a Value field and valueData and unValueData use that. However I think that'll be OK. For instance we won't need to care about the number of nodes in the input to unValueData any more, but we can deal with that by updating the CPU and memory costing functions to have zero slope, effectively making them constant (although now I'm wondering if we'll still have to traverse the entire CostRose).

[kwxm]

See the Slack discussion about this. We'll need to do something like using nf instead of whnf for the CPU costing for valueData, the problem being that the implementaion of valueData begins with Map . ... and whnf won't cause the stuff in ... (which does all the hard work) to be evaluated.

[kwxm]

Strictly we don't need this because ValueTotalSize gives the same result as the defaullt memory usage instance, but I think we should keep the wrapper because it makes the size measure explicit. So this change is good!

[kwxm]

Note that @ana-pantilie 's PR changes this to ValueMaxDepth, which is less cumbersome and a lot clearer.

[kwxm]

I'm a little dubious about this approach because (if I understand correctly) it measures the total size occupied by the result, which, because the result may share some data with the input, may be considerably larger than the amount of new heap space that has to be allocated. For example, in the case of valueData and unValueData there's no need to make new copies of the keys and quantities: if you call valueData v then (I think) the resulting data object will contain pointers to the keys and quantities in the input value v, not new copies of them (and v itself will I think only contain pointers to the actual keys and quantities). Keys take up 4 words in the worst case and quantities take up 2 words, and we probably need to subtract those numbers from the memory usage reported by measureGraphWords to get the true amount of new heap space allocated.

Maybe this isn't really a problem: the numbers returned by the analysis should definitely be upper bounds for the "true" memory usage, so the bounds will be safe. Also, the existing memory costs are generallly pretty crude anyway, so a litlle bit of extra inaccuracy may be tolerable.

I think this issue would be more of a problem for things like tailList, where there really is a lot of sharing: if you have a list with 1000 elements then tailList will just return a pointer to the tail, not a new list with 999 elements. Similarly, bytestrings are implemented as C arrays in the heap together with a pointer to the start of thebytestring and an integer containing the length: sliceByteString doesn't copy any of the bytes in the bytestring, it just returns a small object containing the same array but with the pointer and the length updated. I have a vague memory that we didn't understand this at first and so overestimated the memory usage of sliceByteString. You'll see that the memory usage function is a linear function with slope zero, and I think that's because it originally had a nonzero slope but then we changed it when we realised what was going on.

These examples suggest that it'd be difficult to automatically infer the memory allocated by a builtin because you have to look at the implementation (which may change!) to see how much sharing there is in the inputs.

However, it's quite possible that I've misunderstood what's going on here, so let me know if that's the case.

[kwxm]

I'll add that the PR description is very lengthy, but it doesn't explain exactly how the memory inference works out the total memory allocation. A crucial point is that it uses GHC.DataSize.recursiveSize, but you have to dig into the code to discover that. Mentioning it in the description would have been helpful.