feat(bench): implement comprehensive benchmarking for Value builtins

Add systematic benchmarking framework with worst-case test coverage: LookupCoin with 400 power-of-2 combinations testing BST depth range 2-21, ValueContains with 1000+ cases using multiplied_sizes model for x * y complexity.

Includes R statistical models: linearInZ for LookupCoin, multiplied_sizes for ValueContains to properly account for both container and contained sizes.

Author: Unisay

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

@@ -0,0 +1,345 @@
+{-# LANGUAGE BlockArguments      #-}
+{-# LANGUAGE ImportQualifiedPost #-}
+{-# LANGUAGE LambdaCase          #-}
+{-# LANGUAGE NumericUnderscores  #-}
+{-# LANGUAGE TupleSections       #-}
+{-# LANGUAGE TypeApplications    #-}
+
+module Benchmarks.Values (makeBenchmarks) where
+
+import Prelude
+
+import Common
+import Control.Monad (replicateM)
+import Criterion.Main (Benchmark)
+import Data.Bits (shiftR, (.&.))
+import Data.ByteString (ByteString)
+import Data.ByteString qualified as BS
+import Data.Int (Int64)
+import Data.List (find)
+import Data.Word (Word8)
+import GHC.Stack (HasCallStack)
+import PlutusCore (DefaultFun (LookupCoin, UnValueData, ValueContains, ValueData))
+import PlutusCore.Builtin (BuiltinResult (BuiltinFailure, BuiltinSuccess, BuiltinSuccessWithLogs))
+import PlutusCore.Evaluation.Machine.ExMemoryUsage (ValueLogOuterSizeAddLogMaxInnerSize (..),
+                                                    ValueTotalSize (..))
+import PlutusCore.Value (K, Value)
+import PlutusCore.Value qualified as Value
+import System.Random.Stateful (StatefulGen, StdGen, runStateGen_, uniformRM)
+
+----------------------------------------------------------------------------------------------------
+-- Benchmarks --------------------------------------------------------------------------------------
+
+makeBenchmarks :: StdGen -> [Benchmark]
+makeBenchmarks gen =
+  [ lookupCoinBenchmark gen
+  , valueContainsBenchmark gen
+  , valueDataBenchmark gen
+  , unValueDataBenchmark gen
+  ]
+
+----------------------------------------------------------------------------------------------------
+-- LookupCoin --------------------------------------------------------------------------------------
+
+lookupCoinBenchmark :: StdGen -> Benchmark
+lookupCoinBenchmark gen =
+  createThreeTermBuiltinBenchElementwiseWithWrappers
+    (id, id, ValueLogOuterSizeAddLogMaxInnerSize) -- Wrap Value argument to report sum of log sizes
+    LookupCoin -- the builtin fun
+    [] -- no type arguments needed (monomorphic builtin)
+    (lookupCoinArgs gen) -- the argument combos to generate benchmarks for
+
+lookupCoinArgs :: StdGen -> [(ByteString, ByteString, Value)]
+lookupCoinArgs gen = runStateGen_ gen \(g :: g) -> do
+  {- Exhaustive power-of-2 combinations for BST worst-case benchmarking.
+
+     Tests all combinations of sizes from powers and half-powers of 2.
+     For each integer n ∈ {1..10}, includes both 2^n and 2^(n+0.5) ≈ 2^n * √2.
+
+     This provides:
+     - 400 total test points (20 × 20 grid)
+     - Complete systematic coverage of depth range 2 to 21
+     - Finer granularity between powers of 2
+     - All distribution patterns (balanced, outer-heavy, inner-heavy)
+
+     Size values: 2, 3, 4, 6, 8, 11, 16, 23, 32, 45, 64, 91, 128, 181,
+                  256, 362, 512, 724, 1024, 1448
+
+     Depth coverage:
+     - Minimum depth: log₂(2) + log₂(2) ≈ 2
+     - Maximum depth: log₂(1448) + log₂(1448) ≈ 21
+  -}
+  let
+    -- Generate powers of 2 and their geometric means (half-powers)
+    sizes =
+      [ 2 ^ n -- 2^n
+      | n <- [1 .. 10 :: Int]
+      ]
+        ++ [ round @Double (2 ^ n * sqrt 2) -- 2^(n+0.5)
+           | n <- [1 .. 10 :: Int]
+           ]
+
+  sequence
+    -- Generate worst-case lookups for each size combination
+    [ withWorstCaseSearchKeys (generateConstrainedValueWithMaxPolicy numPolicies tokensPerPolicy g)
+    | numPolicies <- sizes
+    , tokensPerPolicy <- sizes
+    ]
+
+-- | Add worst-case search keys targeting the max-size inner map
+withWorstCaseSearchKeys :: (Monad m) => m (Value, K, K) -> m (ByteString, ByteString, Value)
+withWorstCaseSearchKeys genValueWithKeys = do
+  (value, maxPolicyId, deepestToken) <- genValueWithKeys
+  pure (Value.unK maxPolicyId, Value.unK deepestToken, value)
+
+----------------------------------------------------------------------------------------------------
+-- ValueContains -----------------------------------------------------------------------------------
+
+valueContainsBenchmark :: StdGen -> Benchmark
+valueContainsBenchmark gen =
+  createTwoTermBuiltinBenchElementwiseWithWrappers
+    (ValueLogOuterSizeAddLogMaxInnerSize, ValueTotalSize)
+    -- Container: sum of log sizes, Contained: totalSize
+    ValueContains -- the builtin fun
+    [] -- no type arguments needed (monomorphic builtin)
+    (valueContainsArgs gen) -- the argument combos to generate benchmarks for
+
+valueContainsArgs :: StdGen -> [(Value, Value)]
+valueContainsArgs gen = runStateGen_ gen \g -> do
+  {- ValueContains performs multiple LookupCoin operations (one per entry in contained).
+     Worst case: All lookups succeed at maximum depth with many entries to check.
+
+     Strategy:
+     1. Generate container with worst-case BST structure (uniform, power-of-2 sizes)
+     2. Select entries FROM container (maintain subset relationship for no early exit)
+     3. Include deepest entry to force maximum BST traversal
+     4. Test multiple contained sizes to explore iteration count dimension
+
+     Result: ~1000 systematic worst-case benchmarks vs 100 random cases previously
+  -}
+
+  -- Use power-of-2 grid (without half-powers) for systematic coverage
+  -- ValueContains does multiple lookups, so we don't need as fine-grained
+  -- size variation as LookupCoin
+  let containerSizes = [2 ^ n | n <- [1 .. 10 :: Int]] -- [2, 4, 8, 16, 32, 64, 128, 256, 512, 1024]
+
+  -- Generate test cases for all container size combinations
+  concat
+    <$> sequence
+      [ do
+          -- Generate container with worst-case BST structure:
+          -- - Uniform distribution (all policies have same token count)
+          -- - Worst-case keys (long common prefix, differ in last 4 bytes)
+          -- - Returns metadata about the deepest entry
+          (container, maxPolicyId, deepestToken) <-
+            generateConstrainedValueWithMaxPolicy numPolicies tokensPerPolicy g
+
+          -- Extract all entries from container as a flat list
+          -- This maintains the subset relationship: contained ⊆ container
+          let allEntries = Value.toFlatList container
+              totalEntries = length allEntries
+
+          -- Find the worst-case entry (deepest in both BSTs)
+          -- This entry forces maximum depth lookup:
+          -- - maxPolicyId: first in outer BST (but all equal size, so any works)
+          -- - deepestToken: last token in sorted order (maximum inner BST depth)
+          let worstCaseEntry =
+                find (\(p, t, _) -> p == maxPolicyId && t == deepestToken) allEntries
+
+          -- Generate test cases for different contained sizes (uniform linear distribution)
+          -- Each size tests the same container with different iteration counts
+          -- Use uniform spacing from 1 to min(1000, totalEntries) for better distribution
+          let maxContainedSize = min 1000 totalEntries
+              numSamples = 10
+              containedSizes =
+                if totalEntries < numSamples
+                  then [1 .. totalEntries] -- Test all sizes for small containers
+                  else
+                    let step = maxContainedSize `div` numSamples
+                     in [i * step | i <- [1 .. numSamples], i * step > 0]
+                          ++ [maxContainedSize | maxContainedSize `notElem` [i * step | i <- [1 .. numSamples]]]
+
+          -- Create one test case per contained size
+          pure
+            [ let
+                -- Select entries ensuring worst-case is included
+                -- Place worst-case entry at END so it's checked (not early-exit)
+                selectedEntries =
+                  case worstCaseEntry of
+                    Just worst ->
+                      -- Take (containedSize - 1) entries, then add worst-case
+                      -- This ensures: 1) subset relationship maintained
+                      --               2) worst-case depth is hit
+                      --               3) no early exit (all lookups succeed)
+                      let numOthers = min (containedSize - 1) (totalEntries - 1)
+                          others = take numOthers allEntries
+                       in others ++ [worst]
+                    Nothing ->
+                      -- Fallback if worst-case entry somehow not found
+                      -- (shouldn't happen, but defensive programming)
+                      take containedSize allEntries
+
+                -- Build contained Value from selected entries
+                -- This maintains the Value structure while ensuring subset
+                contained =
+                  unsafeFromBuiltinResult $
+                    Value.fromList
+                      [ (policyId, [(tokenName, quantity)])
+                      | (policyId, tokenName, quantity) <- selectedEntries
+                      ]
+               in
+                (container, contained)
+            | containedSize <- containedSizes
+            ]
+      | numPolicies <- containerSizes
+      , tokensPerPolicy <- containerSizes
+      ]
+
+----------------------------------------------------------------------------------------------------
+-- ValueData ---------------------------------------------------------------------------------------
+
+valueDataBenchmark :: StdGen -> Benchmark
+valueDataBenchmark gen = createOneTermBuiltinBench ValueData [] (generateTestValues gen)
+
+----------------------------------------------------------------------------------------------------
+-- UnValueData -------------------------------------------------------------------------------------
+
+unValueDataBenchmark :: StdGen -> Benchmark
+unValueDataBenchmark gen =
+  createOneTermBuiltinBench UnValueData [] (Value.valueData <$> generateTestValues gen)
+
+----------------------------------------------------------------------------------------------------
+-- Value Generators --------------------------------------------------------------------------------
+
+-- | Generate common test values for benchmarking
+generateTestValues :: StdGen -> [Value]
+generateTestValues gen = runStateGen_ gen \g ->
+  -- Empty value as edge case
+  (Value.empty :)
+    <$>
+    -- Random tests for parameter spread (100 combinations)
+    replicateM 100 (generateValue g)
+
+-- | Generate Value with random budget between 1 and 30,000 bytes
+generateValue :: (StatefulGen g m) => g -> m Value
+generateValue g = do
+  maxEntries <- uniformRM (1, maxValueEntries maxValueInBytes) g
+  generateValueMaxEntries maxEntries g
+ where
+  -- Maximum budget for Value generation (30,000 bytes)
+  maxValueInBytes :: Int
+  maxValueInBytes = 30_000
+
+  -- Calculate maximum possible number of entries with maximal key sizes that fits in the budget
+  maxValueEntries :: Int -> Int
+  maxValueEntries budget =
+    let bytesPerEntry =
+          {- bytes per policy -} Value.maxKeyLen
+            {- bytes per token -} + Value.maxKeyLen
+            {- bytes per quantity (Int64 takes up 8 bytes) -} + 8
+     in budget `div` bytesPerEntry
+
+-- | Generate Value within total size budget
+generateValueMaxEntries :: (StatefulGen g m) => Int -> g -> m Value
+generateValueMaxEntries maxEntries g = do
+  -- Uniform random distribution: cover full range from many policies (few tokens each)
+  -- to few policies (many tokens each)
+  numPolicies <- uniformRM (1, maxEntries) g
+  let tokensPerPolicy = if numPolicies > 0 then maxEntries `div` numPolicies else 0
+
+  generateConstrainedValue numPolicies tokensPerPolicy g
+
+-- | Generate constrained Value with information about max-size policy
+generateConstrainedValueWithMaxPolicy
+  :: (StatefulGen g m)
+  => Int -- Number of policies
+  -> Int -- Number of tokens per policy
+  -> g
+  -> m (Value, K, K) -- Returns (value, maxPolicyId, deepestTokenInMaxPolicy)
+generateConstrainedValueWithMaxPolicy numPolicies tokensPerPolicy g = do
+  policyIds <- replicateM numPolicies (generateKey g)
+  tokenNames <- replicateM tokensPerPolicy (generateKey g)
+
+  let
+    qty :: Value.Quantity
+    qty = case Value.quantity (fromIntegral (maxBound :: Int64)) of
+      Just q -> q
+      Nothing -> error "generateConstrainedValueWithMaxPolicy: Int64 maxBound should be valid Quantity"
+
+    nestedMap :: [(K, [(K, Value.Quantity)])]
+    nestedMap = (,(,qty) <$> tokenNames) <$> policyIds
+
+    value = unsafeFromBuiltinResult $ Value.fromList nestedMap
+
+    -- All policies have the same number of tokens in this uniform distribution,
+    -- so we pick the first policy as the max-size policy for worst-case targeting
+    maxPolicyId = head policyIds
+    -- Pick the last token (deepest in binary search tree) for worst-case inner lookup
+    deepestToken = last tokenNames
+
+  pure (value, maxPolicyId, deepestToken)
+
+-- | Generate constrained Value (legacy interface for other builtins)
+generateConstrainedValue
+  :: (StatefulGen g m)
+  => Int -- Number of policies
+  -> Int -- Number of tokens per policy
+  -> g
+  -> m Value
+generateConstrainedValue numPolicies tokensPerPolicy g = do
+  (value, _, _) <- generateConstrainedValueWithMaxPolicy numPolicies tokensPerPolicy g
+  pure value
+
+----------------------------------------------------------------------------------------------------
+-- Other Generators --------------------------------------------------------------------------------
+
+{-| Generate a worst-case key for benchmarking ByteString comparisons.
+
+ByteString comparison is lexicographic and short-circuits on the first differing byte.
+Random keys typically differ in the first 1-2 bytes, making comparisons artificially cheap.
+
+For accurate worst-case costing, we generate keys with a common prefix (0xFF bytes) that
+differ only in the last bytes. This forces full-length comparisons during Map lookups,
+providing conservative cost estimates for adversarial on-chain scenarios.
+
+We use a random integer to ensure uniqueness while maintaining the worst-case prefix pattern.
+-}
+generateKey :: (StatefulGen g m) => g -> m K
+generateKey g = do
+  -- Generate a random integer for uniqueness
+  n <- uniformRM (0, maxBound :: Int) g
+  case Value.k (mkWorstCaseKey n) of
+    Just key -> pure key
+    Nothing  -> error "Internal error: maxKeyLen key should always be valid"
+
+{-| Helper: Create a worst-case ByteString key from an integer
+The key has maxKeyLen-4 bytes of 0xFF prefix, followed by 4 bytes encoding the integer
+-}
+mkWorstCaseKey :: Int -> ByteString
+mkWorstCaseKey n =
+  let prefixLen = Value.maxKeyLen - 4
+      prefix = BS.replicate prefixLen (0xFF :: Word8)
+      -- Encode the integer in big-endian format (last 4 bytes)
+      b0 = fromIntegral $ (n `shiftR` 24) .&. 0xFF
+      b1 = fromIntegral $ (n `shiftR` 16) .&. 0xFF
+      b2 = fromIntegral $ (n `shiftR` 8) .&. 0xFF
+      b3 = fromIntegral $ n .&. 0xFF
+      suffix = BS.pack [b0, b1, b2, b3]
+   in prefix <> suffix
+
+----------------------------------------------------------------------------------------------------
+-- Helper Functions --------------------------------------------------------------------------------
+
+{-| Extract value from BuiltinResult for benchmark data generation.
+
+This function is intended for use in test and benchmark code where BuiltinResult
+failures indicate bugs in the generator code, not runtime errors.
+
+Errors if BuiltinResult indicates failure (should never happen with valid inputs).
+The call stack will provide context about where the error occurred.
+-}
+unsafeFromBuiltinResult :: (HasCallStack) => BuiltinResult a -> a
+unsafeFromBuiltinResult = \case
+  BuiltinSuccess x -> x
+  BuiltinSuccessWithLogs _ x -> x
+  BuiltinFailure _ err -> error $ "BuiltinResult failed: " <> show err

plutus-core/cost-model/budgeting-bench/Main.hs

@@ -17,6 +17,7 @@ import Benchmarks.Pairs qualified
 import Benchmarks.Strings qualified
 import Benchmarks.Tracing qualified
 import Benchmarks.Unit qualified
+import Benchmarks.Values qualified
 
 import Criterion.Main
 import Criterion.Types as C
@@ -60,6 +61,7 @@ main = do
         <> Benchmarks.Strings.makeBenchmarks     gen
         <> Benchmarks.Tracing.makeBenchmarks     gen
         <> Benchmarks.Unit.makeBenchmarks        gen
+        <> Benchmarks.Values.makeBenchmarks      gen
 
   {- Run the nop benchmarks with a large time limit (30 seconds) in an attempt to
      get accurate results. -}