Add comments and TypeError to document why we don't have ToCBOR instance

Author: palas

cardano-api/src/Cardano/Api/Tx/Internal/Output.hs

@@ -104,6 +104,7 @@ import Data.Typeable (Typeable)
 import Data.Word
 import GHC.Exts (IsList (..))
 import GHC.Stack
+import GHC.TypeLits as TL
 import Lens.Micro hiding (ix)
 
 -- ----------------------------------------------------------------------------
@@ -134,6 +135,21 @@ instance (Typeable ctx, IsShelleyBasedEra era) => FromCBOR (TxOut ctx era) where
     shelleyBasedEraConstraints (shelleyBasedEra @era) $
       pure (fromShelleyTxOut shelleyBasedEra) <*> L.fromEraCBOR @(ShelleyLedgerEra era)
 
+-- | We do not provide a 'ToCBOR' instance for 'TxOut' because they may
+-- contain supplemental datums and the CBOR representation does not support this.
+instance
+  ( TypeError
+      ( TL.Text "Cannot serialise 'TxOut' to CBOR."
+          :$$: TL.Text
+                 "Serialisation for 'TxOut' type is not implemented because they may contain supplemental datums and the CBOR representation does not support this."
+      )
+  , Typeable ctx
+  , IsShelleyBasedEra era
+  )
+  => ToCBOR (TxOut ctx era)
+  where
+  toCBOR = error "This shouldn't happen"
+
 deriving instance Eq (TxOut ctx era)
 
 deriving instance Show (TxOut ctx era)

cardano-api/test/cardano-api-test/Test/Cardano/Api/CBOR.hs

@@ -110,6 +110,13 @@ prop_roundtrip_tx_CBOR = H.property $ do
   x <- H.forAll $ genTx era
   shelleyBasedEraConstraints era $ H.trippingCbor (proxyToAsType Proxy) x
 
+-- | The CBOR representation fo TxOut does not allow for storing
+-- suplemental datums, so we cannot provide a serialization mechanism
+-- that is lossless and for which the roundtrip property would hold.
+-- Therefore, we only provide deserialisation functionality and we
+-- include serialization only for testing purposes. Additionally,
+-- we convert hash any supplemental datum generated before testing
+-- because, otherwise, the property would not hold.
 prop_roundtrip_tx_out_CBOR :: Property
 prop_roundtrip_tx_out_CBOR = H.property $ do
   AnyShelleyBasedEra era <- H.noteShowM . H.forAll $ Gen.element [minBound .. maxBound]