Add text envelope serialisation for AnyPlutusScript

[Jimbo4350]

Changelog

- description: |
    Add serialiseAnyPlutusScriptToTextEnvelope and
    deserialiseAnyPlutusScriptFromTextEnvelope for AnyPlutusScript,
    following the existing ScriptInAnyLang pattern using FromSomeType
    and deserialiseFromTextEnvelopeAnyOf.
# uncomment types applicable to the change:
  type:
   - feature        # introduces a new feature
  # - breaking       # the API has changed in a breaking way
  # - compatible     # the API has changed but is non-breaking
  # - optimisation   # measurable performance improvements
  # - refactoring    # QoL changes
  # - bugfix         # fixes a defect
  # - test           # fixes/modifies tests
  # - maintenance    # not directly related to the code
  # - release        # related to a new release preparation
  # - documentation  # change in code docs, haddocks...
# uncomment at least one main project this PR is associated with
  projects:
   - cardano-api
  # - cardano-api-gen
  # - cardano-rpc
  # - cardano-wasm

Context

AnyPlutusScript existentially quantifies the Plutus language, so it cannot have a HasTextEnvelope instance directly (since textEnvelopeType :: AsType a -> TextEnvelopeType has no value to pattern match on to recover the existential lang). Instead, this adds standalone serialisation/deserialisation functions following the same pattern used by ScriptInAnyLang (textEnvelopeToScript in Cardano.Api.Plutus.Internal.Script).

Relates to: IntersectMBO/cardano-cli#1240

How to trust this PR

• The serialisation function delegates to the existing HasTextEnvelope (PlutusScriptInEra lang era) instance, preserving correct per-language envelope types (PlutusScriptV1, PlutusScriptV2, etc.)
• The deserialisation function uses deserialiseFromTextEnvelopeAnyOf with FromSomeType entries for all four Plutus language versions
• Both functions are re-exported from Cardano.Api.Experimental.Plutus and Cardano.Api.Experimental

Checklist

• Commit sequence broadly makes sense and commits have useful messages
• New tests are added if needed and existing tests are updated
• Self-reviewed the diff

[Copilot]

Pull request overview

Adds text envelope serialisation/deserialisation helpers for AnyPlutusScript, enabling round-tripping via TextEnvelope despite the existential Plutus language parameter.

Changes:

• Introduce serialiseAnyPlutusScriptToTextEnvelope delegating to existing HasTextEnvelope (PlutusScriptInEra lang era) instances.
• Introduce deserialiseAnyPlutusScriptFromTextEnvelope using deserialiseFromTextEnvelopeAnyOf with FromSomeType over supported Plutus versions.
• Re-export the new helpers from Cardano.Api.Experimental.Plutus and Cardano.Api.Experimental.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 2 comments.

File	Description
cardano-api/src/Cardano/Api/Experimental/Plutus/Internal/Script.hs	Implements text envelope serialise/deserialise helpers for AnyPlutusScript.
cardano-api/src/Cardano/Api/Experimental/Plutus.hs	Re-exports the new API from the experimental Plutus module.
cardano-api/src/Cardano/Api/Experimental.hs	Re-exports the new API from the top-level experimental module.

[Copilot]

These functions are part of the exported API (re-exported from Cardano.Api.Experimental.*) but currently have no Haddock explaining expected envelope types, version handling, or common failure modes (e.g., wrong TextEnvelopeType). Adding concise Haddock (including that deserialisation supports the enumerated Plutus versions and that the envelope type is determined by the underlying PlutusScriptInEra instance) will make the new API safer and easier to use.

[Copilot]

The supported Plutus versions are hard-coded here; when a new Plutus language version is introduced, this list must be updated or deserialisation will silently not support the new envelope type. Consider centralising this list (e.g., a single top-level allAnyPlutusScriptTextEnvelopeTypes value reused anywhere similar logic exists) and/or adding an explicit comment that this must be kept in sync with the set of supported Plutus language versions.

Suggested change

	deserialiseAnyPlutusScriptFromTextEnvelope
	:: forall era
	. L.Era era
	=> TextEnvelope
	-> Either TextEnvelopeError (AnyPlutusScript era)
	deserialiseAnyPlutusScriptFromTextEnvelope =
	deserialiseFromTextEnvelopeAnyOf textEnvTypes
	where
	textEnvTypes :: [FromSomeType HasTextEnvelope (AnyPlutusScript era)]
	textEnvTypes =
	[ FromSomeType (asType @(PlutusScriptInEra L.PlutusV1 era)) AnyPlutusScript
	, FromSomeType (asType @(PlutusScriptInEra L.PlutusV2 era)) AnyPlutusScript
	, FromSomeType (asType @(PlutusScriptInEra L.PlutusV3 era)) AnyPlutusScript
	, FromSomeType (asType @(PlutusScriptInEra L.PlutusV4 era)) AnyPlutusScript
	]
	-- | List of all supported Plutus script text envelope types for 'AnyPlutusScript'.
	-- NOTE: This must be kept in sync with the set of supported 'Plutus.PlutusLanguage'
	-- / 'L.PlutusLanguage' versions in this module.
	allAnyPlutusScriptTextEnvelopeTypes
	:: forall era. L.Era era
	=> [FromSomeType HasTextEnvelope (AnyPlutusScript era)]
	allAnyPlutusScriptTextEnvelopeTypes =
	[ FromSomeType (asType @(PlutusScriptInEra L.PlutusV1 era)) AnyPlutusScript
	, FromSomeType (asType @(PlutusScriptInEra L.PlutusV2 era)) AnyPlutusScript
	, FromSomeType (asType @(PlutusScriptInEra L.PlutusV3 era)) AnyPlutusScript
	, FromSomeType (asType @(PlutusScriptInEra L.PlutusV4 era)) AnyPlutusScript
	]
	deserialiseAnyPlutusScriptFromTextEnvelope
	:: forall era
	. L.Era era
	=> TextEnvelope
	-> Either TextEnvelopeError (AnyPlutusScript era)
	deserialiseAnyPlutusScriptFromTextEnvelope =
	deserialiseFromTextEnvelopeAnyOf allAnyPlutusScriptTextEnvelopeTypes

[palas]

Looks good 👍 . There are two things that bother me, but I cannot think of any easy way of solving them:

• The fact that we are not using the HasTextEnvelope instance
• What copilot pointed out, that we won't get compiler errors when adding a new version of Plutus

Well and, yes, maybe it would also be good to add a roundtrip test and haddock