Merge #2121 #2126

2121: Completing API support for Allegra and Mary eras r=dcoutts a=dcoutts

Following on from #2111 with what is hopefully the last remaining API
changes needed to support all the Shelley-based eras.

All the representations and functions should now work for all
appropriate eras.

2126: Updated help text for query ledger/protocol-state r=intricate a=kevinhammond

Clarified that these commands are not intended for general use, and pointed to the underlying data structures for more information about content

Co-authored-by: Duncan Coutts <duncan@well-typed.com>
Co-authored-by: Luke Nadur <19835357+intricate@users.noreply.github.com>
Co-authored-by: Kevin Hammond <12563287+kevinhammond@users.noreply.github.com>

cardano-api/src/Cardano/API.hs

@@ -114,24 +114,48 @@ module Cardano.API (
 
     -- * Building transactions
     -- | Constructing and inspecting transactions
+
+    -- ** Transaction bodies
     TxBody,
+    makeTransactionBody,
+    TxBodyContent(..),
+
+    -- ** Transaction Ids
     TxId,
     getTxId,
+
+    -- ** Transaction inputs
     TxIn(TxIn),
     TxIx(TxIx),
+
+    -- ** Transaction outputs
     TxOut(TxOut),
     TxOutValue(..),
-    AdaOnlyInEra(..),
-    MultiAssetInEra(..),
-    TTL,
-    TxFee,
-    MintValue(..),
-    makeByronTransaction,
-    makeShelleyTransaction,
-    SlotNo,
-    TxExtraContent,
-    txExtraContentEmpty,
-    Certificate,
+
+    -- ** Other transaction body types
+    TxFee(..),
+    TxValidityLowerBound(..),
+    TxValidityUpperBound(..),
+    SlotNo(..),
+    TxMetadataInEra(..),
+    TxAuxScripts(..),
+    TxWithdrawals(..),
+    TxCertificates(..),
+    TxUpdateProposal(..),
+    TxMintValue(..),
+
+    -- ** Era-dependent transaction body features
+    OnlyAdaSupportedInEra(..),
+    MultiAssetSupportedInEra(..),
+    TxFeesExplicitInEra (..),
+    ValidityUpperBoundSupportedInEra(..),
+    ValidityNoUpperBoundSupportedInEra(..),
+    ValidityLowerBoundSupportedInEra(..),
+    TxMetadataSupportedInEra(..),
+    AuxScriptsSupportedInEra(..),
+    WithdrawalsSupportedInEra(..),
+    CertificatesSupportedInEra(..),
+    UpdateProposalSupportedInEra(..),
 
     -- * Signing transactions
     -- | Creating transaction witnesses one by one, or all in one go.
@@ -176,15 +200,18 @@ module Cardano.API (
     TxMetadataJsonError (..),
     TxMetadataJsonSchemaError (..),
 
-    -- * Registering stake address and delegating
+    -- * Certificates
+    Certificate,
+
+    -- ** Registering stake address and delegating
     -- | Certificates that are embedded in transactions for registering and
     -- unregistering stake address, and for setting the stake pool delegation
     -- choice for a stake address.
     makeStakeAddressRegistrationCertificate,
     makeStakeAddressDeregistrationCertificate,
     makeStakeAddressDelegationCertificate,
 
-    -- * Registering stake pools
+    -- ** Registering stake pools
     -- | Certificates that are embedded in transactions for registering and
     -- retiring stake pools. This includes updating the stake pool parameters.
     makeStakePoolRegistrationCertificate,
@@ -193,7 +220,7 @@ module Cardano.API (
     StakePoolRelay,
     StakePoolMetadataReference,
 
-    -- ** Stake pool off-chain metadata
+    -- * Stake pool off-chain metadata
     StakePoolMetadata,
     validateAndHashStakePoolMetadata,
     StakePoolMetadataValidationError,

cardano-api/src/Cardano/Api/Eras.hs

@@ -193,7 +193,7 @@ deriving instance Show (ShelleyBasedEra era)
 -- of Shelley-based eras, but also non-uniform by making case distinctions on
 -- the 'ShelleyBasedEra' constructors.
 --
-class HasTypeProxy era => IsShelleyBasedEra era where
+class IsCardanoEra era => IsShelleyBasedEra era where
    shelleyBasedEra :: ShelleyBasedEra era
 
 instance IsShelleyBasedEra ShelleyEra where

cardano-api/src/Cardano/Api/Fees.hs

@@ -1,4 +1,6 @@
+{-# LANGUAGE EmptyCase #-}
 {-# LANGUAGE GADTs #-}
+{-# LANGUAGE ScopedTypeVariables #-}
 
 -- | Fee calculation
 --
@@ -34,17 +36,25 @@ import           Cardano.Api.Value
 -- This function is simple, but if you are doing input selection then you
 -- probably want to consider estimateTransactionFee.
 --
-transactionFee :: Natural -- ^ The fixed tx fee
+transactionFee :: forall era.
+                  IsShelleyBasedEra era
+               => Natural -- ^ The fixed tx fee
                -> Natural -- ^ The tx fee per byte
-               -> Tx ShelleyEra
+               -> Tx era
                -> Lovelace
-transactionFee txFeeFixed txFeePerByte (ShelleyTx tx) =
+transactionFee txFeeFixed txFeePerByte (ShelleyTx _ tx) =
     Lovelace (a * x + b)
   where
     a = toInteger txFeePerByte
     x = Shelley.txsize tx
     b = toInteger txFeeFixed
 
+--TODO: This can be made to work for Byron txs too. Do that: fill in this case
+-- and remove the IsShelleyBasedEra constraint.
+transactionFee _ _ (ByronTx _) =
+    case shelleyBasedEra :: ShelleyBasedEra era of {}
+
+
 --TODO: in the Byron case the per-byte is non-integral, would need different
 -- parameters. e.g. a new data type for fee params, Byron vs Shelley
 
@@ -56,17 +66,19 @@ transactionFee txFeeFixed txFeePerByte (ShelleyTx tx) =
 -- contain all the things not subject to coin selection (such as script inputs,
 -- metadata, withdrawals, certs etc)
 --
-estimateTransactionFee :: NetworkId
+estimateTransactionFee :: forall era.
+                          IsShelleyBasedEra era
+                       => NetworkId
                        -> Natural -- ^ The fixed tx fee
                        -> Natural -- ^ The tx fee per byte
-                       -> Tx ShelleyEra
+                       -> Tx era
                        -> Int -- ^ The number of extra UTxO transaction inputs
                        -> Int -- ^ The number of extra transaction outputs
                        -> Int -- ^ The number of extra Shelley key witnesses
                        -> Int -- ^ The number of extra Byron key witnesses
                        -> Lovelace
-estimateTransactionFee nw txFeeFixed txFeePerByte (ShelleyTx tx) =
-    let Lovelace baseFee = transactionFee txFeeFixed txFeePerByte (ShelleyTx tx)
+estimateTransactionFee nw txFeeFixed txFeePerByte (ShelleyTx era tx) =
+    let Lovelace baseFee = transactionFee txFeeFixed txFeePerByte (ShelleyTx era tx)
      in \nInputs nOutputs nShelleyKeyWitnesses nByronKeyWitnesses ->
 
         --TODO: this is fragile. Move something like this to the ledger and
@@ -110,3 +122,8 @@ estimateTransactionFee nw txFeeFixed txFeePerByte (ShelleyTx tx) =
                       Byron.aaNetworkMagic     = toByronNetworkMagic nw
                     }
 
+--TODO: This can be made to work for Byron txs too. Do that: fill in this case
+-- and remove the IsShelleyBasedEra constraint.
+estimateTransactionFee _ _ _ (ByronTx _) =
+    case shelleyBasedEra :: ShelleyBasedEra era of {}
+

cardano-api/src/Cardano/Api/Script.hs

@@ -29,6 +29,7 @@ module Cardano.Api.Script (
   , ScriptFeatureInEra(..)
   , SignatureFeature
   , TimeLocksFeature
+  , HasScriptFeatures
 
     -- * Deprecated aliases
   , MultiSigScript