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

Co-authored-by: Mateusz Galazyn <[email protected]>

Author: palas

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

@@ -129,6 +129,10 @@ instance (Typeable ctx, IsShelleyBasedEra era) => HTP.HasTypeProxy (TxOut ctx er
   proxyToAsType :: HTP.Proxy (TxOut ctx era) -> AsType (TxOut ctx era)
   proxyToAsType _ = AsTxOut (HTP.asType @era)
 
+-- | We do not provide a 'ToCBOR' instance for 'TxOut' because 'TxOut's can contain
+-- supplemental datums and the ledger's 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 (Typeable ctx, IsShelleyBasedEra era) => FromCBOR (TxOut ctx era) where
   fromCBOR :: Ledger.Decoder s (TxOut ctx era)
   fromCBOR =

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

@@ -111,6 +111,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]