Add 'Note [Mapping of protocol versions and ledger languages to seman…

…tics variants]'
IntersectMBO · Apr 25, 2024 · 1f1bf5e · 1f1bf5e
1 parent 60bbf02
commit 1f1bf5e
Show file tree

Hide file tree

Showing 5 changed files with 23 additions and 0 deletions.
diff --git a/plutus-core/plutus-core/src/PlutusCore/Evaluation/Machine/ExBudgetingDefaults.hs b/plutus-core/plutus-core/src/PlutusCore/Evaluation/Machine/ExBudgetingDefaults.hs
@@ -86,6 +86,8 @@ defaultCekMachineCosts =
 defaultCekCostModel :: CostModel CekMachineCosts BuiltinCostModel
 defaultCekCostModel = CostModel defaultCekMachineCosts defaultBuiltinCostModel
 
+-- | Return the 'CostModel' corresponding to the given semantics variant. The dependency on the
+-- semantics variant is what makes cost models configurable.
 toCekCostModel :: BuiltinSemanticsVariant DefaultFun -> CostModel CekMachineCosts BuiltinCostModel
 toCekCostModel _ = defaultCekCostModel
 

diff --git a/plutus-ledger-api/src/PlutusLedgerApi/Common/ProtocolVersions.hs b/plutus-ledger-api/src/PlutusLedgerApi/Common/ProtocolVersions.hs
@@ -83,3 +83,21 @@ knownPVs = Set.fromList [ shelleyPV, allegraPV, maryPV, alonzoPV, vasilPV, valen
 -- associate something with the wrong protocol version.
 futurePV :: MajorProtocolVersion
 futurePV = MajorProtocolVersion maxBound
+
+{- Note [Mapping of protocol versions and ledger languages to semantics variants]
+Semantics variants depend on both the protocol version and the ledger language.
+
+Here's a table specifying the mapping in full:
+
+  pv pre-Conway post-Conway
+ll
+1       0           1
+2       0           1
+3       2           2
+
+I.e. for example
+
+- post-Conway 'PlutusV1' corresponds to 'DefaultFunSemanticsVariant1'
+- pre-Conway  'PlutusV2' corresponds to 'DefaultFunSemanticsVariant0'
+- post-Conway 'PlutusV3' corresponds to 'DefaultFunSemanticsVariant2'
+-}
diff --git a/plutus-ledger-api/src/PlutusLedgerApi/V1/EvaluationContext.hs b/plutus-ledger-api/src/PlutusLedgerApi/V1/EvaluationContext.hs
@@ -41,6 +41,7 @@ mkEvaluationContext =
     >=> mkDynEvaluationContext
         PlutusV1
         [DefaultFunSemanticsVariant0, DefaultFunSemanticsVariant1]
+        -- See Note [Mapping of protocol versions and ledger languages to semantics variants].
         (\pv -> if pv < conwayPV
             then DefaultFunSemanticsVariant0
             else DefaultFunSemanticsVariant1)
diff --git a/plutus-ledger-api/src/PlutusLedgerApi/V2/EvaluationContext.hs b/plutus-ledger-api/src/PlutusLedgerApi/V2/EvaluationContext.hs
@@ -41,6 +41,7 @@ mkEvaluationContext =
     >=> mkDynEvaluationContext
         PlutusV2
         [DefaultFunSemanticsVariant0, DefaultFunSemanticsVariant1]
+        -- See Note [Mapping of protocol versions and ledger languages to semantics variants].
         (\pv -> if pv < conwayPV
             then DefaultFunSemanticsVariant0
             else DefaultFunSemanticsVariant1)
diff --git a/plutus-ledger-api/src/PlutusLedgerApi/V3/EvaluationContext.hs b/plutus-ledger-api/src/PlutusLedgerApi/V3/EvaluationContext.hs
@@ -39,4 +39,5 @@ mkEvaluationContext =
     >=> mkDynEvaluationContext
         PlutusV3
         [DefaultFunSemanticsVariant2]
+        -- See Note [Mapping of protocol versions and ledger languages to semantics variants].
         (const DefaultFunSemanticsVariant2)