Add roundtrip tests and fix SerialiseAsCBOR for PlutusScriptInEra

Fix serialiseToCBOR to extract raw script bytes from PlutusRunnable
instead of using L.serialize' which adds CBOR framing that
deserialiseFromCBOR does not expect.

Add CBOR and TextEnvelope roundtrip tests for PlutusScriptInEra and
AnyPlutusScript. Add haddocks for the text envelope functions.

Author: Jimbo4350

cardano-api/src/Cardano/Api/Experimental/Plutus/Internal/Script.hs

@@ -117,8 +117,11 @@ instance
   )
   => SerialiseAsCBOR (PlutusScriptInEra (lang :: L.Language) era)
   where
+  -- The 'PlutusBinary' stored in the 'PlutusRunnable' already contains
+  -- CBOR-wrapped Flat-encoded UPLC bytes (see 'Cardano.Ledger.Plutus.Language'),
+  -- so we extract them directly rather than re-encoding with 'L.serialize''.
   serialiseToCBOR (PlutusScriptInEra s) =
-    L.serialize' (L.eraProtVerHigh @era) s
+    SBS.fromShort . L.unPlutusBinary . L.plutusBinary $ L.plutusFromRunnable s
 
   deserialiseFromCBOR _ bs = do
     let v = L.eraProtVerHigh @era
@@ -204,12 +207,17 @@ data AnyPlutusScriptLanguage where
     :: L.PlutusLanguage lang
     => L.SLanguage lang -> AnyPlutusScriptLanguage
 
+-- | Serialise an 'AnyPlutusScript' to a 'TextEnvelope'. The text envelope type
+-- is determined by the Plutus language version of the script.
 serialiseAnyPlutusScriptToTextEnvelope
   :: Maybe TextEnvelopeDescr -> AnyPlutusScript era -> TextEnvelope
 serialiseAnyPlutusScriptToTextEnvelope mbDescr (AnyPlutusScript script) =
   obtainLangConstraints (plutusScriptInEraSLanguage script) $
     serialiseToTextEnvelope mbDescr script
 
+-- | Deserialise an 'AnyPlutusScript' from a 'TextEnvelope'. The text envelope type
+-- is matched against all known Plutus language versions derived from
+-- 'Plutus.nonNativeLanguages', so new language versions are picked up automatically.
 deserialiseAnyPlutusScriptFromTextEnvelope
   :: forall era
    . L.Era era

cardano-api/test/cardano-api-test/Test/Cardano/Api/Transaction/Body/Plutus/Scripts.hs

@@ -8,22 +8,26 @@ module Test.Cardano.Api.Transaction.Body.Plutus.Scripts
   )
 where
 
-import Cardano.Api (AlonzoEraOnwards (..))
+import Cardano.Api (AlonzoEraOnwards (..), proxyToAsType)
 import Cardano.Api qualified as Api
 import Cardano.Api.Experimental
 import Cardano.Api.Experimental.AnyScriptWitness
 import Cardano.Api.Experimental.Plutus hiding (AnyPlutusScript (..))
+import Cardano.Api.Experimental.Plutus qualified as Plutus
 import Cardano.Api.Experimental.Tx qualified as Exp
 import Cardano.Api.Ledger qualified as L
+import Cardano.Api.Serialise.Cbor (SerialiseAsCBOR (..))
 
 import Cardano.Ledger.Conway qualified as L
 import Cardano.Ledger.Core qualified as L
+import Cardano.Ledger.Plutus.Language qualified as L
 
 import Prelude
 
 import Data.Function
 import Data.List qualified as List
 import Data.Map.Strict qualified as Map
+import Data.Proxy (Proxy (..))
 
 import Test.Gen.Cardano.Api.Experimental qualified as Exp
 import Test.Gen.Cardano.Api.Typed
@@ -55,6 +59,27 @@ prop_compare_plutus_script_hashes = property $ do
 
   hash === anyScriptHash
 
+prop_roundtrip_plutus_script_in_era_cbor :: Property
+prop_roundtrip_plutus_script_in_era_cbor = property $ do
+  scriptInEra <- forAll genPlutusScriptInEra
+  tripping
+    scriptInEra
+    serialiseToCBOR
+    (deserialiseFromCBOR (proxyToAsType (Proxy @(PlutusScriptInEra L.PlutusV3 (LedgerEra ConwayEra)))))
+
+-- | Serialise an 'AnyPlutusScript' to a 'TextEnvelope' and deserialise it back.
+-- We compare the resulting 'TextEnvelope' values because 'AnyPlutusScript' is
+-- existentially quantified and does not have an 'Eq' instance.
+prop_roundtrip_any_plutus_script_text_envelope :: Property
+prop_roundtrip_any_plutus_script_text_envelope = property $ do
+  scriptInEra <- forAll genPlutusScriptInEra
+  let anyScript = Plutus.AnyPlutusScript scriptInEra
+      envelope = serialiseAnyPlutusScriptToTextEnvelope Nothing anyScript
+  anyScript' <-
+    evalEither $ deserialiseAnyPlutusScriptFromTextEnvelope @(LedgerEra ConwayEra) envelope
+  let envelope' = serialiseAnyPlutusScriptToTextEnvelope Nothing anyScript'
+  envelope === envelope'
+
 -- | This property checks that the redeemer pointer map is constructed correctly.
 -- Previously identical script purposes were being created and overwriting each other
 -- in the redeemer pointer map.
@@ -214,6 +239,12 @@ tests =
   testGroup
     "Test.Cardano.Api.Transaction.Body.Plutus.Scripts"
     [ testProperty "prop_compare_plutus_script_hashes" prop_compare_plutus_script_hashes
+    , testProperty
+        "prop_roundtrip_plutus_script_in_era_cbor"
+        prop_roundtrip_plutus_script_in_era_cbor
+    , testProperty
+        "prop_roundtrip_any_plutus_script_text_envelope"
+        prop_roundtrip_any_plutus_script_text_envelope
     , testProperty
         "prop_extractAllIndexedPlutusScriptWitnesses"
         prop_extractAllIndexedPlutusScriptWitnesses