SCP-2772: Teach evaluateScriptRestricting to return the used budget

This enables the ledger to compute budgets while still setting an
overall limit, to guard against scripts that run for a very long time,
or loop.

I decided to roll this into `evaluateScriptRestricting` rather than
giving `evaluteScriptCounting` a bound, since having the bound-less
version of `evaluateScriptCounting` is still handy for casual usage.
Possibly it's actually just a trap and we should delete it, though.

Author: michaelpj

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

@@ -137,6 +137,7 @@ possible to adjust them at runtime.
 
 module PlutusCore.Evaluation.Machine.ExBudget
     ( ExBudget(..)
+    , minusExBudget
     , ExBudgetBuiltin(..)
     , ExRestrictingBudget(..)
     , LowerIntialCharacter
@@ -178,6 +179,10 @@ data ExBudget = ExBudget { exBudgetCPU :: ExCPU, exBudgetMemory :: ExMemory }
     deriving (FromJSON, ToJSON) via CustomJSON '[FieldLabelModifier LowerIntialCharacter] ExBudget
     -- LowerIntialCharacter won't actually do anything here, but let's have it in case we change the field names.
 
+-- | Subract one 'ExBudget' from another. Does not guarantee that the result is positive.
+minusExBudget :: ExBudget -> ExBudget -> ExBudget
+minusExBudget (ExBudget c1 m1) (ExBudget c2 m2) = ExBudget (c1-c2) (m1-m2)
+
 -- These functions are performance critical, so we can't use GenericSemigroupMonoid, and we insist that they be inlined.
 instance Semigroup ExBudget where
     {-# INLINE (<>) #-}

plutus-ledger-api/src/Plutus/V1/Ledger/Api.hs

@@ -220,24 +220,25 @@ mkTermToEvaluate bs args = do
     pure t
 
 -- | Evaluates a script, with a cost model and a budget that restricts how many
--- resources it can use according to the cost model.  There's a default cost
--- model in  'UPLC.defaultBuiltinCostModel' and a budget called 'enormousBudget' in
--- 'UntypedPlutusCore.Evaluation.Machine.Cek.ExBudgetMode' which should be large
--- enough to evaluate any sensible program.
+-- resources it can use according to the cost model. Also returns the budget that
+-- was actually used.
+--
+-- Can be used to calculate budgets for scripts, but even in this case you must give
+-- a limit to guard against scripts that run for a long time or loop.
 evaluateScriptRestricting
     :: VerboseMode     -- ^ Whether to produce log output
     -> CostModelParams -- ^ The cost model to use
     -> ExBudget        -- ^ The resource budget which must not be exceeded during evaluation
     -> SerializedScript          -- ^ The script to evaluate
     -> [PLC.Data]          -- ^ The arguments to the script
-    -> (LogOutput, Either EvaluationError ())
+    -> (LogOutput, Either EvaluationError ExBudget)
 evaluateScriptRestricting verbose cmdata budget p args = swap $ runWriter @LogOutput $ runExceptT $ do
     appliedTerm <- mkTermToEvaluate p args
     model <- case applyCostModelParams PLC.defaultCekCostModel cmdata of
         Just model -> pure model
         Nothing    -> throwError CostModelParameterMismatch
 
-    let (res, _, logs) =
+    let (res, UPLC.RestrictingSt (PLC.ExRestrictingBudget final), logs) =
             UPLC.runCek
                 (toMachineParameters model)
                 (UPLC.restricting $ PLC.ExRestrictingBudget budget)
@@ -246,9 +247,12 @@ evaluateScriptRestricting verbose cmdata budget p args = swap $ runWriter @LogOu
 
     tell logs
     liftEither $ first CekError $ void res
+    pure (budget `PLC.minusExBudget` final)
 
 -- | Evaluates a script, returning the minimum budget that the script would need
--- to evaluate successfully.
+-- to evaluate successfully. This will take as long as the script takes, if you need to
+-- limit the execution time of the script also, you can use 'evaluateScriptRestricting', which
+-- also returns the used budget.
 evaluateScriptCounting
     :: VerboseMode     -- ^ Whether to produce log output
     -> CostModelParams -- ^ The cost model to use