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,23 @@ 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 'TxOut's can
+-- contain supplemental datums and the CBOR representation does not support this.
+-- For this reason, if we were to serialise a 'TxOut' with a supplemental datum,
+-- we would lose information and the roundtrip property would not hold.
+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,15 @@ prop_roundtrip_tx_CBOR = H.property $ do
   x <- H.forAll $ genTx era
   shelleyBasedEraConstraints era $ H.trippingCbor (proxyToAsType Proxy) x
 
+-- | The CBOR representation for 'TxOut' does not store supplemental datums.
+-- This means we cannot provide a lossless serialisation instance for which
+-- a roundtrip property would hold.
+--
+-- Therefore, we only provide a deserialisation instance. The serialisation
+-- implementation is included for testing purposes only.
+--
+-- For the roundtrip test, we hash any supplemental datum before serialisation
+-- to ensure the property holds.
 prop_roundtrip_tx_out_CBOR :: Property
 prop_roundtrip_tx_out_CBOR = H.property $ do
   AnyShelleyBasedEra era <- H.noteShowM . H.forAll $ Gen.element [minBound .. maxBound]