From 11db5cf02bc8c6e90684aec5fac3433e1f5e76b4 Mon Sep 17 00:00:00 2001 From: John Ky Date: Tue, 21 May 2024 00:32:12 +1000 Subject: [PATCH] Document GADT constructor arguments --- cardano-api/internal/Cardano/Api/Address.hs | 77 ++++---- cardano-api/internal/Cardano/Api/Block.hs | 19 +- .../internal/Cardano/Api/Certificate.hs | 85 +++++++-- cardano-api/internal/Cardano/Api/Error.hs | 6 +- cardano-api/internal/Cardano/Api/Fees.hs | 14 +- cardano-api/internal/Cardano/Api/IPC.hs | 4 + cardano-api/internal/Cardano/Api/InMode.hs | 9 + cardano-api/internal/Cardano/Api/Modes.hs | 1 + .../Cardano/Api/ProtocolParameters.hs | 24 +++ cardano-api/internal/Cardano/Api/Query.hs | 23 ++- cardano-api/internal/Cardano/Api/Script.hs | 104 +++++++---- .../Cardano/Api/SerialiseLedgerCddl.hs | 8 +- cardano-api/internal/Cardano/Api/Tx/Body.hs | 164 +++++++++++++----- cardano-api/internal/Cardano/Api/Tx/Sign.hs | 115 ++++++------ 14 files changed, 455 insertions(+), 198 deletions(-) diff --git a/cardano-api/internal/Cardano/Api/Address.hs b/cardano-api/internal/Cardano/Api/Address.hs index 6d0ac9493a..3c01a8a57a 100644 --- a/cardano-api/internal/Cardano/Api/Address.hs +++ b/cardano-api/internal/Cardano/Api/Address.hs @@ -175,25 +175,29 @@ instance HasTypeProxy ShelleyAddr where -- with the era in which it is supported. -- data Address addrtype where - - -- | Byron addresses were the only supported address type in the original - -- Byron era. - -- - ByronAddress - :: Byron.Address - -> Address ByronAddr - - -- | Shelley addresses allow delegation. Shelley addresses were introduced - -- in Shelley era and are thus supported from the Shelley era onwards - -- - ShelleyAddress - :: Shelley.Network - -> Shelley.PaymentCredential StandardCrypto - -> Shelley.StakeReference StandardCrypto - -> Address ShelleyAddr - -- Note that the two ledger credential types here are parametrised by - -- the era, but in fact this is a phantom type parameter and they are - -- the same for all eras. See 'toShelleyAddr' below. + -- | Byron addresses were the only supported address type in the original + -- Byron era. + -- + ByronAddress + :: Byron.Address + -- ^ The Byron address + -> Address ByronAddr + + -- | Shelley addresses allow delegation. Shelley addresses were introduced + -- in Shelley era and are thus supported from the Shelley era onwards + -- + -- Note that the two ledger credential types here are parameterrised by + -- the era, but in fact this is a phantom type parameter and they are + -- the same for all eras. See 'toShelleyAddr' below. + -- + ShelleyAddress + :: Shelley.Network + -- ^ The shelley network + -> Shelley.PaymentCredential StandardCrypto + -- ^ Payment credentials + -> Shelley.StakeReference StandardCrypto + -- ^ Stake reference + -> Address ShelleyAddr deriving instance Eq (Address addrtype) deriving instance Ord (Address addrtype) @@ -363,9 +367,12 @@ fromShelleyAddrToAny (Shelley.Addr nw pc scr) = -- supported in the 'ShelleyEra' and later eras. -- data AddressInEra era where - AddressInEra :: AddressTypeInEra addrtype era - -> Address addrtype - -> AddressInEra era + AddressInEra + :: AddressTypeInEra addrtype era + -- ^ Witness that the address type is supported in the era + -> Address addrtype + -- ^ The address + -> AddressInEra era instance NFData (AddressInEra era) where rnf (AddressInEra t a) = deepseq (deepseq t a) () @@ -428,10 +435,15 @@ deriving instance Show (AddressInEra era) data AddressTypeInEra addrtype era where - ByronAddressInAnyEra :: AddressTypeInEra ByronAddr era + -- | Byron addresses are supported in all eras. + ByronAddressInAnyEra + :: AddressTypeInEra ByronAddr era - ShelleyAddressInEra :: ShelleyBasedEra era - -> AddressTypeInEra ShelleyAddr era + -- | Shelley addresses are supported in the Shelley era and later eras. + ShelleyAddressInEra + :: ShelleyBasedEra era + -- ^ Witness that the era is shelley era onwards + -> AddressTypeInEra ShelleyAddr era deriving instance Show (AddressTypeInEra addrtype era) @@ -523,15 +535,17 @@ makeShelleyAddressInEra sbe nw pc scr = -- data StakeAddress where - StakeAddress - :: Shelley.Network - -> Shelley.StakeCredential StandardCrypto - -> StakeAddress + StakeAddress + :: Shelley.Network + -- ^ The shelley network + -> Shelley.StakeCredential StandardCrypto + -- ^ The stake credential + -> StakeAddress deriving (Eq, Ord, Show) data PaymentCredential - = PaymentCredentialByKey (Hash PaymentKey) - | PaymentCredentialByScript ScriptHash + = PaymentCredentialByKey (Hash PaymentKey) + | PaymentCredentialByScript ScriptHash deriving (Eq, Ord, Show) data StakeCredential @@ -679,6 +693,7 @@ fromShelleyAddrIsSbe sbe = \case fromShelleyAddr :: ShelleyBasedEra era + -- ^ Witness that the era is shelley era onwards -> Shelley.Addr StandardCrypto -> AddressInEra era fromShelleyAddr _ (Shelley.AddrBootstrap (Shelley.BootstrapAddress addr)) = diff --git a/cardano-api/internal/Cardano/Api/Block.hs b/cardano-api/internal/Cardano/Api/Block.hs index 90182c16f0..54e09c05ee 100644 --- a/cardano-api/internal/Cardano/Api/Block.hs +++ b/cardano-api/internal/Cardano/Api/Block.hs @@ -94,12 +94,17 @@ import Data.Text (Text) -- data Block era where - ByronBlock :: Consensus.ByronBlock - -> Block ByronEra - - ShelleyBlock :: ShelleyBasedEra era - -> Consensus.ShelleyBlock (ConsensusProtocol era) (ShelleyLedgerEra era) - -> Block era + ByronBlock + :: Consensus.ByronBlock + -- ^ The underlying Byron block type + -> Block ByronEra + + ShelleyBlock + :: ShelleyBasedEra era + -- ^ Shelley based era witness + -> Consensus.ShelleyBlock (ConsensusProtocol era) (ShelleyLedgerEra era) + -- ^ The underlying Shelley block type + -> Block era -- | A block consists of a header and a body containing transactions. -- @@ -186,7 +191,9 @@ getShelleyBlockTxs era (Ledger.Block _header txs) = data BlockInMode where BlockInMode :: CardanoEra era + -- ^ The era of the block -> Block era + -- ^ The block itself -> BlockInMode deriving instance Show BlockInMode diff --git a/cardano-api/internal/Cardano/Api/Certificate.hs b/cardano-api/internal/Cardano/Api/Certificate.hs index ea8d4be064..56e708aa6d 100644 --- a/cardano-api/internal/Cardano/Api/Certificate.hs +++ b/cardano-api/internal/Cardano/Api/Certificate.hs @@ -114,25 +114,29 @@ import Network.Socket (PortNumber) -- data Certificate era where - -- Pre-Conway - -- 1. Stake registration - -- 2. Stake unregistration - -- 3. Stake delegation - -- 4. Pool retirement - -- 5. Pool registration - -- 6. Genesis delegation - -- 7. MIR certificates - ShelleyRelatedCertificate - :: ShelleyToBabbageEra era - -> Ledger.ShelleyTxCert (ShelleyLedgerEra era) - -> Certificate era - - -- Conway onwards - -- TODO: Add comments about the new types of certificates - ConwayCertificate - :: ConwayEraOnwards era - -> Ledger.ConwayTxCert (ShelleyLedgerEra era) - -> Certificate era + -- Pre-Conway + -- 1. Stake registration + -- 2. Stake unregistration + -- 3. Stake delegation + -- 4. Pool retirement + -- 5. Pool registration + -- 6. Genesis delegation + -- 7. MIR certificates + ShelleyRelatedCertificate + :: ShelleyToBabbageEra era + -- ^ Shelley to babbage era witness + -> Ledger.ShelleyTxCert (ShelleyLedgerEra era) + -- ^ Shelley ledger transaction certificate + -> Certificate era + + -- Conway onwards + -- TODO: Add comments about the new types of certificates + ConwayCertificate + :: ConwayEraOnwards era + -- ^ Conway era onwards witness + -> Ledger.ConwayTxCert (ShelleyLedgerEra era) + -- ^ Conway ledger transaction certificate + -> Certificate era deriving anyclass SerialiseAsCBOR @@ -250,13 +254,18 @@ data DRepMetadataReference = data StakeAddressRequirements era where StakeAddrRegistrationConway :: ConwayEraOnwards era + -- ^ Witness that the era is conway onwards -> L.Coin + -- ^ Deposit -> StakeCredential + -- ^ Stake credential -> StakeAddressRequirements era StakeAddrRegistrationPreConway :: ShelleyToBabbageEra era + -- ^ Witness that the era is shelley to babbage -> StakeCredential + -- ^ Stake credential -> StakeAddressRequirements era makeStakeAddressRegistrationCertificate :: StakeAddressRequirements era -> Certificate era @@ -286,14 +295,20 @@ makeStakeAddressUnregistrationCertificate req = data StakeDelegationRequirements era where StakeDelegationRequirementsConwayOnwards :: ConwayEraOnwards era + -- ^ Witness that the era is conway onwards -> StakeCredential + -- ^ Stake credential -> Ledger.Delegatee (EraCrypto (ShelleyLedgerEra era)) + -- ^ Delegatee -> StakeDelegationRequirements era StakeDelegationRequirementsPreConway :: ShelleyToBabbageEra era + -- ^ Witness that the era is shelley to babbage -> StakeCredential + -- ^ Stake credential -> PoolId + -- ^ Pool id -> StakeDelegationRequirements era makeStakeAddressDelegationCertificate :: StakeDelegationRequirements era -> Certificate era @@ -311,12 +326,16 @@ makeStakeAddressDelegationCertificate = \case data StakePoolRegistrationRequirements era where StakePoolRegistrationRequirementsConwayOnwards :: ConwayEraOnwards era + -- ^ Witness that the era is conway onwards -> Ledger.PoolParams (EraCrypto (ShelleyLedgerEra era)) + -- ^ Pool parameters -> StakePoolRegistrationRequirements era StakePoolRegistrationRequirementsPreConway :: ShelleyToBabbageEra era + -- ^ Witness that the era is shelley to babbage -> Ledger.PoolParams (EraCrypto (ShelleyLedgerEra era)) + -- ^ Pool parameters -> StakePoolRegistrationRequirements era makeStakePoolRegistrationCertificate :: () @@ -335,14 +354,20 @@ makeStakePoolRegistrationCertificate = \case data StakePoolRetirementRequirements era where StakePoolRetirementRequirementsConwayOnwards :: ConwayEraOnwards era + -- ^ Witness that the era is conway onwards -> PoolId + -- ^ Pool id -> Ledger.EpochNo + -- ^ Retirement epoch number -> StakePoolRetirementRequirements era StakePoolRetirementRequirementsPreConway :: ShelleyToBabbageEra era + -- ^ Witness that the era is shelley to babbage -> PoolId + -- ^ Pool id -> Ledger.EpochNo + -- ^ Retirement epoch number -> StakePoolRetirementRequirements era makeStakePoolRetirementCertificate :: () @@ -362,9 +387,13 @@ makeStakePoolRetirementCertificate req = data GenesisKeyDelegationRequirements ere where GenesisKeyDelegationRequirements :: ShelleyToBabbageEra era + -- ^ Witness that the era is shelley to babbage -> Hash GenesisKey + -- ^ Genesis key hash -> Hash GenesisDelegateKey + -- ^ Genesis delegate key hash -> Hash VrfKey + -- ^ VRF key hash -> GenesisKeyDelegationRequirements era makeGenesisKeyDelegationCertificate :: GenesisKeyDelegationRequirements era -> Certificate era @@ -377,8 +406,11 @@ makeGenesisKeyDelegationCertificate (GenesisKeyDelegationRequirements atMostEra data MirCertificateRequirements era where MirCertificateRequirements :: ShelleyToBabbageEra era + -- ^ Witness that the era is shelley to babbage -> Ledger.MIRPot + -- ^ MIR pot -> Ledger.MIRTarget (EraCrypto (ShelleyLedgerEra era)) + -- ^ MIR target -> MirCertificateRequirements era makeMIRCertificate :: () @@ -391,8 +423,11 @@ makeMIRCertificate (MirCertificateRequirements atMostEra mirPot mirTarget) = data DRepRegistrationRequirements era where DRepRegistrationRequirements :: ConwayEraOnwards era + -- ^ Witness that the era is conway onwards -> (Ledger.Credential Ledger.DRepRole (EraCrypto (ShelleyLedgerEra era))) + -- ^ DRep credential -> L.Coin + -- ^ Deposit -> DRepRegistrationRequirements era @@ -408,8 +443,11 @@ makeDrepRegistrationCertificate (DRepRegistrationRequirements conwayOnwards vcre data CommitteeHotKeyAuthorizationRequirements era where CommitteeHotKeyAuthorizationRequirements :: ConwayEraOnwards era + -- ^ Witness that the era is conway onwards -> Ledger.Credential Ledger.ColdCommitteeRole (EraCrypto (ShelleyLedgerEra era)) + -- ^ Cold key credential -> Ledger.Credential Ledger.HotCommitteeRole (EraCrypto (ShelleyLedgerEra era)) + -- ^ Hot key credential -> CommitteeHotKeyAuthorizationRequirements era makeCommitteeHotKeyAuthorizationCertificate :: () @@ -423,8 +461,11 @@ makeCommitteeHotKeyAuthorizationCertificate (CommitteeHotKeyAuthorizationRequire data CommitteeColdkeyResignationRequirements era where CommitteeColdkeyResignationRequirements :: ConwayEraOnwards era + -- ^ Witness that the era is conway onwards -> Ledger.Credential Ledger.ColdCommitteeRole (EraCrypto (ShelleyLedgerEra era)) + -- ^ Cold key credential -> Maybe (Ledger.Anchor (EraCrypto (ShelleyLedgerEra era))) + -- ^ Anchor -> CommitteeColdkeyResignationRequirements era makeCommitteeColdkeyResignationCertificate :: () @@ -440,8 +481,11 @@ makeCommitteeColdkeyResignationCertificate (CommitteeColdkeyResignationRequireme data DRepUnregistrationRequirements era where DRepUnregistrationRequirements :: ConwayEraOnwards era + -- ^ Witness that the era is conway onwards -> (Ledger.Credential Ledger.DRepRole (EraCrypto (ShelleyLedgerEra era))) + -- ^ DRep credential -> L.Coin + -- ^ Deposit -> DRepUnregistrationRequirements era makeDrepUnregistrationCertificate :: () @@ -466,7 +510,9 @@ makeStakeAddressAndDRepDelegationCertificate w cred delegatee deposit = data DRepUpdateRequirements era where DRepUpdateRequirements :: ConwayEraOnwards era + -- ^ Witness that the era is conway onwards -> Ledger.Credential Ledger.DRepRole (EraCrypto (ShelleyLedgerEra era)) + -- ^ DRep credential -> DRepUpdateRequirements era makeDrepUpdateCertificate @@ -484,6 +530,7 @@ makeDrepUpdateCertificate (DRepUpdateRequirements conwayOnwards vcred) mAnchor = getTxCertWitness :: ShelleyBasedEra era + -- ^ Witness that the era is shelley era onwards -> Ledger.TxCert (ShelleyLedgerEra era) -> Maybe StakeCredential getTxCertWitness sbe ledgerCert = shelleyBasedEraConstraints sbe $ diff --git a/cardano-api/internal/Cardano/Api/Error.hs b/cardano-api/internal/Cardano/Api/Error.hs index 69bc22c5a5..d7e6b02079 100644 --- a/cardano-api/internal/Cardano/Api/Error.hs +++ b/cardano-api/internal/Cardano/Api/Error.hs @@ -38,7 +38,11 @@ throwErrorAsException :: Error e => e -> IO a throwErrorAsException e = throwIO (ErrorAsException e) data ErrorAsException where - ErrorAsException :: Error e => e -> ErrorAsException + ErrorAsException + :: Error e + => e + -- ^ The error + -> ErrorAsException instance Error ErrorAsException where prettyError (ErrorAsException e) = diff --git a/cardano-api/internal/Cardano/Api/Fees.hs b/cardano-api/internal/Cardano/Api/Fees.hs index 820692c8cb..f35d56e705 100644 --- a/cardano-api/internal/Cardano/Api/Fees.hs +++ b/cardano-api/internal/Cardano/Api/Fees.hs @@ -419,6 +419,7 @@ data ResolvablePointers where , Show (Alonzo.PlutusScript (ShelleyLedgerEra era)) ) => ShelleyBasedEra era + -- ^ Witness that the era is from shelley onwards -> !(Map (L.PlutusPurpose L.AsIx (ShelleyLedgerEra era)) ( L.PlutusPurpose L.AsItem (ShelleyLedgerEra era) @@ -426,6 +427,7 @@ data ResolvablePointers where , Ledger.ScriptHash Ledger.StandardCrypto ) ) + -- ^ A mapping of pointers that are possible to resolve -> ResolvablePointers deriving instance Show ResolvablePointers @@ -561,15 +563,23 @@ data TransactionValidityError era where -- check or submit transactions that use Plutus scripts that have the end -- of their validity interval more than 36 hours into the future. TransactionValidityIntervalError - :: Consensus.PastHorizonException -> TransactionValidityError era + :: Consensus.PastHorizonException + -- ^ The exception that was thrown by the consensus layer + -> TransactionValidityError era TransactionValidityTranslationError :: Plutus.EraPlutusContext (ShelleyLedgerEra era) + -- ^ The era plutus context that was used to translate the transaction context => Plutus.ContextError (ShelleyLedgerEra era) + -- ^ The error that occurred while translating the transaction context -> TransactionValidityError era TransactionValidityCostModelError - :: (Map AnyPlutusScriptVersion CostModel) -> String -> TransactionValidityError era + :: Map AnyPlutusScriptVersion CostModel + -- ^ The cost models that were used to calculate the execution units + -> String + -- ^ The error that occurred while converting from the cardano-api cost + -> TransactionValidityError era deriving instance Show (TransactionValidityError era) diff --git a/cardano-api/internal/Cardano/Api/IPC.hs b/cardano-api/internal/Cardano/Api/IPC.hs index 537f8f8e71..62e2b11356 100644 --- a/cardano-api/internal/Cardano/Api/IPC.hs +++ b/cardano-api/internal/Cardano/Api/IPC.hs @@ -342,13 +342,17 @@ data LocalNodeClientParams where ) => ProtocolClientInfoArgs block + -- ^ The protocol client info -> (NodeToClientVersion -> LocalNodeClientProtocolsForBlock block) + -- ^ The client side mini-protocol handler -> LocalNodeClientParams LocalNodeClientParamsCardano :: (ProtocolClient block, CardanoHardForkConstraints (ConsensusCryptoForBlock block)) => ProtocolClientInfoArgs block + -- ^ The protocol client info -> (NodeToClientVersion -> LocalNodeClientProtocolsForBlock block) + -- ^ The client side mini-protocol handler -> LocalNodeClientParams data LocalNodeClientProtocolsForBlock block = diff --git a/cardano-api/internal/Cardano/Api/InMode.hs b/cardano-api/internal/Cardano/Api/InMode.hs index d5bc0cf28b..8f388b8344 100644 --- a/cardano-api/internal/Cardano/Api/InMode.hs +++ b/cardano-api/internal/Cardano/Api/InMode.hs @@ -67,7 +67,9 @@ data TxInMode where -- TxInMode :: ShelleyBasedEra era + -- ^ Witness that the era is shelley era onwards -> Tx era + -- ^ The transaction itself -> TxInMode -- | Legacy Byron transactions and things we can @@ -159,7 +161,9 @@ toConsensusGenTx (TxInMode ShelleyBasedEraConway (ShelleyTx _ tx)) = data TxIdInMode where TxIdInMode :: CardanoEra era + -- ^ The cardano era -> TxId + -- ^ The transaction id -> TxIdInMode toConsensusTxId :: () @@ -218,11 +222,14 @@ toConsensusTxId (TxIdInMode ConwayEra txid) = data TxValidationError era where ByronTxValidationError :: Consensus.ApplyTxErr Consensus.ByronBlock + -- ^ The error from trying to submit a Byron transaction -> TxValidationError era ShelleyTxValidationError :: ShelleyBasedEra era + -- ^ Witness that the era is shelley era onwards -> Consensus.ApplyTxErr (Consensus.ShelleyBlock (ConsensusProtocol era) (ShelleyLedgerEra era)) + -- ^ The error from trying to submit a Shelley transaction -> TxValidationError era deriving instance Generic (TxValidationError era) @@ -273,10 +280,12 @@ appTxErrToJson w e = shelleyBasedEraConstraints w $ toJSON e data TxValidationErrorInCardanoMode where TxValidationErrorInCardanoMode :: () => TxValidationError era + -- ^ The transaction validation error -> TxValidationErrorInCardanoMode TxValidationEraMismatch :: () => EraMismatch + -- ^ The error from trying to submit a transaction to the wrong era -> TxValidationErrorInCardanoMode deriving instance Show TxValidationErrorInCardanoMode diff --git a/cardano-api/internal/Cardano/Api/Modes.hs b/cardano-api/internal/Cardano/Api/Modes.hs index 2cb6ca0b38..1ad3054c4b 100644 --- a/cardano-api/internal/Cardano/Api/Modes.hs +++ b/cardano-api/internal/Cardano/Api/Modes.hs @@ -64,6 +64,7 @@ import Data.SOP.Strict (NS (S, Z)) data ConsensusModeParams where CardanoModeParams :: Byron.EpochSlots + -- ^ The number of slots in an epoch. -> ConsensusModeParams deriving instance Show ConsensusModeParams diff --git a/cardano-api/internal/Cardano/Api/ProtocolParameters.hs b/cardano-api/internal/Cardano/Api/ProtocolParameters.hs index 767e08a613..810752168c 100644 --- a/cardano-api/internal/Cardano/Api/ProtocolParameters.hs +++ b/cardano-api/internal/Cardano/Api/ProtocolParameters.hs @@ -202,44 +202,68 @@ createPParams sbe ebPParamsUpdate = data EraBasedProtocolParametersUpdate era where ShelleyEraBasedProtocolParametersUpdate :: CommonProtocolParametersUpdate + -- ^ Common protocol parameters -> DeprecatedAfterMaryPParams ShelleyEra + -- ^ Protocol parameters that have been deprecated after Mary -> DeprecatedAfterBabbagePParams ShelleyEra + -- ^ Protocol parameters that have been deprecated after Babbage -> ShelleyToAlonzoPParams ShelleyEra + -- ^ Protocol parameters that have been deprecated after Alonzo -> EraBasedProtocolParametersUpdate ShelleyEra AllegraEraBasedProtocolParametersUpdate :: CommonProtocolParametersUpdate + -- ^ Common protocol parameters -> DeprecatedAfterMaryPParams AllegraEra + -- ^ Protocol parameters that have been deprecated after Mary -> ShelleyToAlonzoPParams AllegraEra + -- ^ Protocol parameters that have been deprecated after Alonzo -> DeprecatedAfterBabbagePParams ShelleyEra + -- ^ Protocol parameters that have been deprecated after Babbage -> EraBasedProtocolParametersUpdate AllegraEra MaryEraBasedProtocolParametersUpdate :: CommonProtocolParametersUpdate + -- ^ Common protocol parameters -> DeprecatedAfterMaryPParams MaryEra + -- ^ Protocol parameters that have been deprecated after Mary -> ShelleyToAlonzoPParams MaryEra + -- ^ Protocol parameters that have been deprecated after Alonzo -> DeprecatedAfterBabbagePParams ShelleyEra + -- ^ Protocol parameters that have been deprecated after Babbage -> EraBasedProtocolParametersUpdate MaryEra AlonzoEraBasedProtocolParametersUpdate :: CommonProtocolParametersUpdate + -- ^ Common protocol parameters -> ShelleyToAlonzoPParams AlonzoEra + -- ^ Protocol parameters that have been deprecated after Alonzo -> AlonzoOnwardsPParams AlonzoEra + -- ^ Protocol parameters that have been introduced in Alonzo -> DeprecatedAfterBabbagePParams ShelleyEra + -- ^ Protocol parameters that have been deprecated after Babbage -> EraBasedProtocolParametersUpdate AlonzoEra BabbageEraBasedProtocolParametersUpdate :: CommonProtocolParametersUpdate + -- ^ Common protocol parameters -> AlonzoOnwardsPParams BabbageEra + -- ^ Protocol parameters that have been introduced in Babbage -> DeprecatedAfterBabbagePParams ShelleyEra + -- ^ Protocol parameters that have been deprecated after Babbage -> IntroducedInBabbagePParams BabbageEra + -- ^ Protocol parameters that have been introduced in Babbage -> EraBasedProtocolParametersUpdate BabbageEra ConwayEraBasedProtocolParametersUpdate :: CommonProtocolParametersUpdate + -- ^ Common protocol parameters -> AlonzoOnwardsPParams ConwayEra + -- ^ Protocol parameters that have been introduced in Conway -> IntroducedInBabbagePParams ConwayEra + -- ^ Protocol parameters that have been introduced in Babbage -> IntroducedInConwayPParams (ShelleyLedgerEra ConwayEra) + -- ^ Protocol parameters that have been introduced in Conway -> EraBasedProtocolParametersUpdate ConwayEra deriving instance Show (EraBasedProtocolParametersUpdate era) diff --git a/cardano-api/internal/Cardano/Api/Query.hs b/cardano-api/internal/Cardano/Api/Query.hs index 4fa03c05e0..8c53e4e734 100644 --- a/cardano-api/internal/Cardano/Api/Query.hs +++ b/cardano-api/internal/Cardano/Api/Query.hs @@ -157,6 +157,7 @@ data QueryInMode result where QueryInEra :: QueryInEra era result + -- ^ Query in a specific era -> QueryInMode (Either EraMismatch result) QueryEraHistory @@ -184,6 +185,7 @@ data EraHistory where EraHistory :: Consensus.CardanoBlock L.StandardCrypto ~ Consensus.HardForkBlock xs => History.Interpreter xs + -- ^ The history interpreter for the hard fork combinator -> EraHistory getProgress :: () @@ -225,11 +227,15 @@ slotToEpoch slotNo (EraHistory interpreter) = case Qry.interpretQuery interprete deriving instance Show (QueryInMode result) data QueryInEra era result where - QueryByronUpdateState :: QueryInEra ByronEra ByronUpdateState + QueryByronUpdateState + :: QueryInEra ByronEra ByronUpdateState - QueryInShelleyBasedEra :: ShelleyBasedEra era - -> QueryInShelleyBasedEra era result - -> QueryInEra era result + QueryInShelleyBasedEra + :: ShelleyBasedEra era + -- ^ The witness that the era is shelley era onwards + -> QueryInShelleyBasedEra era result + -- ^ The query in the shelley-based era + -> QueryInEra era result instance NodeToClientVersionOf (QueryInEra era result) where nodeToClientVersionOf QueryByronUpdateState = NodeToClientV_9 @@ -257,11 +263,14 @@ data QueryInShelleyBasedEra era result where QueryUTxO :: QueryUTxOFilter + -- ^ Filter the UTxO by this filter -> QueryInShelleyBasedEra era (UTxO era) QueryStakeAddresses :: Set StakeCredential + -- ^ Stake addresses to query -> NetworkId + -- ^ Network ID -> QueryInShelleyBasedEra era (Map StakeAddress L.Coin, Map StakeAddress PoolId) QueryStakePools @@ -269,6 +278,7 @@ data QueryInShelleyBasedEra era result where QueryStakePoolParameters :: Set PoolId + -- ^ Stake pools to query -> QueryInShelleyBasedEra era (Map PoolId StakePoolParameters) -- TODO: add support for RewardProvenance @@ -286,18 +296,22 @@ data QueryInShelleyBasedEra era result where QueryPoolState :: Maybe (Set PoolId) + -- ^ Stake pools to query -> QueryInShelleyBasedEra era (SerialisedPoolState era) QueryPoolDistribution :: Maybe (Set PoolId) + -- ^ Stake pools to query -> QueryInShelleyBasedEra era (SerialisedPoolDistribution era) QueryStakeSnapshot :: Maybe (Set PoolId) + -- ^ Stake pools to query -> QueryInShelleyBasedEra era (SerialisedStakeSnapshots era) QueryStakeDelegDeposits :: Set StakeCredential + -- ^ Stake addresses to query -> QueryInShelleyBasedEra era (Map StakeCredential L.Coin) QueryConstitution @@ -308,6 +322,7 @@ data QueryInShelleyBasedEra era result where QueryDRepState :: Set (Shelley.Credential Shelley.DRepRole StandardCrypto) + -- ^ DRep IDs to query -> QueryInShelleyBasedEra era (Map (Shelley.Credential Shelley.DRepRole StandardCrypto) (L.DRepState StandardCrypto)) QueryDRepStakeDistr diff --git a/cardano-api/internal/Cardano/Api/Script.hs b/cardano-api/internal/Cardano/Api/Script.hs index f79439484e..75f6969b2e 100644 --- a/cardano-api/internal/Cardano/Api/Script.hs +++ b/cardano-api/internal/Cardano/Api/Script.hs @@ -222,9 +222,12 @@ instance HasTypeProxy PlutusScriptV3 where -- data ScriptLanguage lang where - SimpleScriptLanguage :: ScriptLanguage SimpleScript' + SimpleScriptLanguage :: ScriptLanguage SimpleScript' - PlutusScriptLanguage :: PlutusScriptVersion lang -> ScriptLanguage lang + PlutusScriptLanguage + :: PlutusScriptVersion lang + -- ^ The version of the Plutus language + -> ScriptLanguage lang deriving instance (Eq (ScriptLanguage lang)) deriving instance (Show (ScriptLanguage lang)) @@ -254,7 +257,10 @@ instance TestEquality PlutusScriptVersion where data AnyScriptLanguage where - AnyScriptLanguage :: ScriptLanguage lang -> AnyScriptLanguage + AnyScriptLanguage + :: ScriptLanguage lang + -- ^ The script language + -> AnyScriptLanguage deriving instance (Show AnyScriptLanguage) @@ -282,8 +288,10 @@ instance Bounded AnyScriptLanguage where data AnyPlutusScriptVersion where - AnyPlutusScriptVersion :: PlutusScriptVersion lang - -> AnyPlutusScriptVersion + AnyPlutusScriptVersion + :: PlutusScriptVersion lang + -- ^ The version of the Plutus language + -> AnyPlutusScriptVersion deriving instance (Show AnyPlutusScriptVersion) @@ -403,12 +411,17 @@ instance IsPlutusScriptLanguage PlutusScriptV3 where -- data Script lang where - SimpleScript :: !SimpleScript - -> Script SimpleScript' + SimpleScript + :: !SimpleScript + -- ^ A script in the simple script language + -> Script SimpleScript' - PlutusScript :: !(PlutusScriptVersion lang) - -> !(PlutusScript lang) - -> Script lang + PlutusScript + :: !(PlutusScriptVersion lang) + -- ^ The version of the Plutus language + -> !(PlutusScript lang) + -- ^ A script in the Plutus language + -> Script lang deriving instance (Eq (Script lang)) deriving instance (Show (Script lang)) @@ -469,9 +482,12 @@ instance IsScriptLanguage lang => HasTextEnvelope (Script lang) where -- Use 'toScriptInEra' to convert to a script in the context of an era. -- data ScriptInAnyLang where - ScriptInAnyLang :: ScriptLanguage lang - -> Script lang - -> ScriptInAnyLang + ScriptInAnyLang + :: ScriptLanguage lang + -- ^ The language of the script + -> Script lang + -- ^ The script itself + -> ScriptInAnyLang deriving instance Show ScriptInAnyLang @@ -528,9 +544,12 @@ instance HasTypeProxy ScriptInAnyLang where -- data ScriptInEra era where - ScriptInEra :: ScriptLanguageInEra lang era - -> Script lang - -> ScriptInEra era + ScriptInEra + :: ScriptLanguageInEra lang era + -- ^ Witness that the script language is supported in this era + -> Script lang + -- ^ The script itself + -> ScriptInEra era deriving instance Show (ScriptInEra era) @@ -740,17 +759,20 @@ data SimpleScriptOrReferenceInput lang -- data ScriptWitness witctx era where - SimpleScriptWitness :: ScriptLanguageInEra SimpleScript' era - -> SimpleScriptOrReferenceInput SimpleScript' - -> ScriptWitness witctx era - - PlutusScriptWitness :: ScriptLanguageInEra lang era - -> PlutusScriptVersion lang - -> PlutusScriptOrReferenceInput lang - -> ScriptDatum witctx - -> ScriptRedeemer - -> ExecutionUnits - -> ScriptWitness witctx era + SimpleScriptWitness + :: ScriptLanguageInEra SimpleScript' era + -- ^ Witness that the script language is supported in this era + -> SimpleScriptOrReferenceInput SimpleScript' + -- ^ The script itself + -> ScriptWitness witctx era + + PlutusScriptWitness :: ScriptLanguageInEra lang era + -> PlutusScriptVersion lang + -> PlutusScriptOrReferenceInput lang + -> ScriptDatum witctx + -> ScriptRedeemer + -> ExecutionUnits + -> ScriptWitness witctx era deriving instance Show (ScriptWitness witctx era) @@ -826,12 +848,17 @@ scriptWitnessScript (PlutusScriptWitness _ _ (PReferenceScript _ _) _ _ _) = data Witness witctx era where - KeyWitness :: KeyWitnessInCtx witctx - -> Witness witctx era + KeyWitness + :: KeyWitnessInCtx witctx + -- ^ The kind of key witness + -> Witness witctx era - ScriptWitness :: ScriptWitnessInCtx witctx - -> ScriptWitness witctx era - -> Witness witctx era + ScriptWitness + :: ScriptWitnessInCtx witctx + -- ^ The kind of script witness + -> ScriptWitness witctx era + -- ^ The script witness itself + -> Witness witctx era deriving instance Eq (Witness witctx era) deriving instance Show (Witness witctx era) @@ -1387,11 +1414,14 @@ parsePaymentKeyHash = -- has to be added to the transaction, they can now be referenced via a transaction output. data ReferenceScript era where - ReferenceScript :: BabbageEraOnwards era - -> ScriptInAnyLang - -> ReferenceScript era - - ReferenceScriptNone :: ReferenceScript era + ReferenceScript + :: BabbageEraOnwards era + -- ^ Witness that the era is babbage era onwards + -> ScriptInAnyLang + -- ^ The script itself + -> ReferenceScript era + + ReferenceScriptNone :: ReferenceScript era deriving instance Eq (ReferenceScript era) deriving instance Show (ReferenceScript era) diff --git a/cardano-api/internal/Cardano/Api/SerialiseLedgerCddl.hs b/cardano-api/internal/Cardano/Api/SerialiseLedgerCddl.hs index 7bb799d6f0..e07e32c3bf 100644 --- a/cardano-api/internal/Cardano/Api/SerialiseLedgerCddl.hs +++ b/cardano-api/internal/Cardano/Api/SerialiseLedgerCddl.hs @@ -278,13 +278,17 @@ textEnvelopeCddlJSONKeyOrder = keyOrder ["type", "description", "cborHex"] -- having to provide the era. data FromSomeTypeCDDL c b where FromCDDLTx - :: Text -- ^ CDDL type that we want + :: Text + -- ^ CDDL type that we want -> (InAnyShelleyBasedEra Tx -> b) + -- ^ Function to convert the tx to the desired type -> FromSomeTypeCDDL TextEnvelopeCddl b FromCDDLWitness - :: Text -- ^ CDDL type that we want + :: Text + -- ^ CDDL type that we want -> (InAnyShelleyBasedEra KeyWitness -> b) + -- ^ Function to convert the witness to the desired type -> FromSomeTypeCDDL TextEnvelopeCddl b deserialiseFromTextEnvelopeCddlAnyOf diff --git a/cardano-api/internal/Cardano/Api/Tx/Body.hs b/cardano-api/internal/Cardano/Api/Tx/Body.hs index b395f25f0f..dc9aef8c41 100644 --- a/cardano-api/internal/Cardano/Api/Tx/Body.hs +++ b/cardano-api/internal/Cardano/Api/Tx/Body.hs @@ -280,9 +280,12 @@ deriving instance Eq (TxOut ctx era) deriving instance Show (TxOut ctx era) data TxOutInAnyEra where - TxOutInAnyEra :: CardanoEra era - -> TxOut CtxTx era - -> TxOutInAnyEra + TxOutInAnyEra + :: CardanoEra era + -- ^ The cardano era + -> TxOut CtxTx era + -- ^ The transaction output + -> TxOutInAnyEra deriving instance Show TxOutInAnyEra @@ -798,12 +801,15 @@ deriving instance Eq (TxInsCollateral era) deriving instance Show (TxInsCollateral era) data TxInsReference build era where + -- ^ No transaction inputs + TxInsReferenceNone :: TxInsReference build era - TxInsReferenceNone :: TxInsReference build era - - TxInsReference :: BabbageEraOnwards era - -> [TxIn] - -> TxInsReference build era + TxInsReference + :: BabbageEraOnwards era + -- ^ Witness that the era is babbage era onwards + -> [TxIn] + -- ^ Transaction inputs + -> TxInsReference build era deriving instance Eq (TxInsReference build era) deriving instance Show (TxInsReference build era) @@ -816,6 +822,7 @@ data TxOutValue era where TxOutValueByron :: L.Coin + -- ^ The value in lovelace -> TxOutValue era TxOutValueShelleyBased @@ -823,7 +830,9 @@ data TxOutValue era where , Show (Ledger.Value (ShelleyLedgerEra era)) ) => ShelleyBasedEra era + -- ^ Witness that the era is shelley era onwards -> L.Value (ShelleyLedgerEra era) + -- ^ The value in the era -> TxOutValue era deriving instance Eq (TxOutValue era) @@ -914,26 +923,30 @@ prettyRenderTxOut (TxOutInAnyEra _ (TxOut (AddressInEra _ addr) txOutVal _ _)) = <> renderValue (txOutValueToValue txOutVal) data TxReturnCollateral ctx era where - + -- ^ No return collateral TxReturnCollateralNone :: TxReturnCollateral ctx era TxReturnCollateral :: BabbageEraOnwards era + -- ^ Witness that the era is babbage era onwards -> TxOut ctx era + -- ^ The return collateral -> TxReturnCollateral ctx era deriving instance Eq (TxReturnCollateral ctx era) deriving instance Show (TxReturnCollateral ctx era) data TxTotalCollateral era where - + -- ^ No total collateral TxTotalCollateralNone :: TxTotalCollateral era TxTotalCollateral :: BabbageEraOnwards era + -- ^ Witness that the era is babbage era onwards -> L.Coin + -- ^ The total collateral -> TxTotalCollateral era deriving instance Eq (TxTotalCollateral era) @@ -945,31 +958,43 @@ deriving instance Show (TxTotalCollateral era) data TxOutDatum ctx era where - TxOutDatumNone :: TxOutDatum ctx era - - -- | A transaction output that only specifies the hash of the datum, but - -- not the full datum value. - -- - TxOutDatumHash :: AlonzoEraOnwards era - -> Hash ScriptData - -> TxOutDatum ctx era - - -- | A transaction output that specifies the whole datum value. This can - -- only be used in the context of the transaction body, and does not occur - -- in the UTxO. The UTxO only contains the datum hash. - -- - TxOutDatumInTx' :: AlonzoEraOnwards era - -> Hash ScriptData - -> HashableScriptData - -> TxOutDatum CtxTx era - - -- | A transaction output that specifies the whole datum instead of the - -- datum hash. Note that the datum map will not be updated with this datum, - -- it only exists at the transaction output. - -- - TxOutDatumInline :: BabbageEraOnwards era - -> HashableScriptData - -> TxOutDatum ctx era + -- | No transaction output datum + TxOutDatumNone + :: TxOutDatum ctx era + + -- | A transaction output that only specifies the hash of the datum, but + -- not the full datum value. + -- + TxOutDatumHash + :: AlonzoEraOnwards era + -- ^ Witness that the era is alonzo era onwards + -> Hash ScriptData + -- ^ The hash of the datum + -> TxOutDatum ctx era + + -- | A transaction output that specifies the whole datum value. This can + -- only be used in the context of the transaction body, and does not occur + -- in the UTxO. The UTxO only contains the datum hash. + -- + TxOutDatumInTx' + :: AlonzoEraOnwards era + -- ^ Witness that the era is alonzo era onwards + -> Hash ScriptData + -- ^ The hash of the datum + -> HashableScriptData + -- ^ The datum value + -> TxOutDatum CtxTx era + + -- | A transaction output that specifies the whole datum instead of the + -- datum hash. Note that the datum map will not be updated with this datum, + -- it only exists at the transaction output. + -- + TxOutDatumInline + :: BabbageEraOnwards era + -- ^ Witness that the era is babbage era onwards + -> HashableScriptData + -- ^ The datum value + -> TxOutDatum ctx era deriving instance Eq (TxOutDatum ctx era) deriving instance Show (TxOutDatum ctx era) @@ -996,7 +1021,12 @@ parseHash asType = do -- data TxFee era where - TxFeeExplicit :: ShelleyBasedEra era -> L.Coin -> TxFee era + TxFeeExplicit + :: ShelleyBasedEra era + -- ^ Witness that the era is shelley era onwards + -> L.Coin + -- ^ The explicit fee + -> TxFee era deriving instance Eq (TxFee era) deriving instance Show (TxFee era) @@ -1013,7 +1043,9 @@ defaultTxFee w = TxFeeExplicit w mempty data TxValidityUpperBound era where TxValidityUpperBound :: ShelleyBasedEra era + -- ^ Witness that the era is shelley era onwards -> Maybe SlotNo + -- ^ The upper bound of the validity range -> TxValidityUpperBound era deriving instance Eq (TxValidityUpperBound era) @@ -1031,7 +1063,9 @@ data TxValidityLowerBound era where TxValidityLowerBound :: AllegraEraOnwards era + -- ^ Witness that the era is allegra era onwards -> SlotNo + -- ^ The lower bound of the validity range -> TxValidityLowerBound era deriving instance Eq (TxValidityLowerBound era) @@ -1048,7 +1082,9 @@ data TxMetadataInEra era where TxMetadataInEra :: ShelleyBasedEra era + -- ^ Witness that the era is shelley era onwards -> TxMetadata + -- ^ The transaction metadata -> TxMetadataInEra era deriving instance Eq (TxMetadataInEra era) @@ -1065,7 +1101,9 @@ data TxAuxScripts era where TxAuxScripts :: AllegraEraOnwards era + -- ^ Witness that the era is allegra era onwards -> [ScriptInEra era] + -- ^ The auxiliary scripts -> TxAuxScripts era deriving instance Eq (TxAuxScripts era) @@ -1082,7 +1120,9 @@ data TxExtraKeyWitnesses era where TxExtraKeyWitnesses :: AlonzoEraOnwards era + -- ^ Witness that the era is alonzo era onwards -> [Hash PaymentKey] + -- ^ The required signatures -> TxExtraKeyWitnesses era deriving instance Eq (TxExtraKeyWitnesses era) @@ -1099,7 +1139,9 @@ data TxWithdrawals build era where TxWithdrawals :: ShelleyBasedEra era + -- ^ Witness that the era is shelley era onwards -> [(StakeAddress, L.Coin, BuildTxWith build (Witness WitCtxStake era))] + -- ^ The withdrawals -> TxWithdrawals build era deriving instance Eq (TxWithdrawals build era) @@ -1116,8 +1158,11 @@ data TxCertificates build era where TxCertificates :: ShelleyBasedEra era + -- ^ Witness that the era is shelley era onwards -> [Certificate era] + -- ^ The certificates -> BuildTxWith build (Map StakeCredential (Witness WitCtxStake era)) + -- ^ The witnesses for the certificates -> TxCertificates build era deriving instance Eq (TxCertificates build era) @@ -1128,8 +1173,15 @@ deriving instance Show (TxCertificates build era) -- data TxUpdateProposal era where - TxUpdateProposalNone :: TxUpdateProposal era - TxUpdateProposal :: ShelleyToBabbageEra era -> UpdateProposal -> TxUpdateProposal era + TxUpdateProposalNone + :: TxUpdateProposal era + + TxUpdateProposal + :: ShelleyToBabbageEra era + -- ^ Witness that the era is shelley to babbage + -> UpdateProposal + -- ^ The update proposal + -> TxUpdateProposal era deriving instance Eq (TxUpdateProposal era) deriving instance Show (TxUpdateProposal era) @@ -1140,13 +1192,18 @@ deriving instance Show (TxUpdateProposal era) data TxMintValue build era where - TxMintNone :: TxMintValue build era + -- ^ No minting + TxMintNone + :: TxMintValue build era - TxMintValue :: MaryEraOnwards era - -> Value - -> BuildTxWith build - (Map PolicyId (ScriptWitness WitCtxMint era)) - -> TxMintValue build era + TxMintValue + :: MaryEraOnwards era + -- ^ Witness that the era is mary era onwards + -> Value + -- ^ The minted value + -> BuildTxWith build (Map PolicyId (ScriptWitness WitCtxMint era)) + -- ^ The witnesses for the minting policies + -> TxMintValue build era deriving instance Eq (TxMintValue build era) deriving instance Show (TxMintValue build era) @@ -1156,10 +1213,15 @@ deriving instance Show (TxMintValue build era) -- data TxVotingProcedures build era where - TxVotingProceduresNone :: TxVotingProcedures build era + -- ^ No voting procedures + TxVotingProceduresNone + :: TxVotingProcedures build era + TxVotingProcedures :: L.VotingProcedures (ShelleyLedgerEra era) + -- ^ The voting procedures -> BuildTxWith build (Map (Ledger.Voter (Ledger.EraCrypto (ShelleyLedgerEra era))) (ScriptWitness WitCtxStake era)) + -- ^ The witnesses for the voting procedures -> TxVotingProcedures build era @@ -1172,11 +1234,16 @@ deriving instance Show (TxVotingProcedures build era) -- data TxProposalProcedures build era where - TxProposalProceduresNone :: TxProposalProcedures build era + -- | No proposal procedures + TxProposalProceduresNone + :: TxProposalProcedures build era + TxProposalProcedures :: Ledger.EraPParams (ShelleyLedgerEra era) => OSet (L.ProposalProcedure (ShelleyLedgerEra era)) + -- ^ The proposal procedures -> BuildTxWith build (Map (L.ProposalProcedure (ShelleyLedgerEra era)) (ScriptWitness WitCtxStake era)) + -- ^ The witnesses for the proposal procedures -> TxProposalProcedures build era @@ -2734,7 +2801,10 @@ toShelleyTxOutAny _ = \case -- collections of script witnesses from multiple contexts. -- data AnyScriptWitness era where - AnyScriptWitness :: ScriptWitness witctx era -> AnyScriptWitness era + AnyScriptWitness + :: ScriptWitness witctx era + -- The script witness itself + -> AnyScriptWitness era deriving instance Show (AnyScriptWitness era) diff --git a/cardano-api/internal/Cardano/Api/Tx/Sign.hs b/cardano-api/internal/Cardano/Api/Tx/Sign.hs index 882f4fd2b8..644bb11f26 100644 --- a/cardano-api/internal/Cardano/Api/Tx/Sign.hs +++ b/cardano-api/internal/Cardano/Api/Tx/Sign.hs @@ -120,7 +120,9 @@ import Lens.Micro data Tx era where ShelleyTx :: ShelleyBasedEra era + -- ^ Witness that the era is shelley era onwards -> L.Tx (ShelleyLedgerEra era) + -- ^ The transaction itself -> Tx era @@ -288,36 +290,38 @@ instance IsShelleyBasedEra era => HasTextEnvelope (Tx era) where -- TODO: We can use Ledger.Tx era here however we would need to rename TxBody -- as technically it is not strictly a transaction body. data TxBody era where - ShelleyTxBody - :: ShelleyBasedEra era - -> Ledger.TxBody (ShelleyLedgerEra era) - - -- We include the scripts along with the tx body, rather than the - -- witnesses set, since they need to be known when building the body. - -> [Ledger.Script (ShelleyLedgerEra era)] - - -- The info for each use of each script: the script input data, both - -- the UTxO input data (called the "datum") and the supplied input - -- data (called the "redeemer") and the execution units. - -> TxBodyScriptData era - - -- The 'L.TxAuxData' consists of one or several things, - -- depending on era: - -- + transaction metadata (in Shelley and later) - -- + auxiliary scripts (in Allegra and later) - -- Note that there is no auxiliary script data as such, because the - -- extra script data has to be passed to scripts and hence is needed - -- for validation. It is thus part of the witness data, not the - -- auxiliary data. - -> Maybe (L.TxAuxData (ShelleyLedgerEra era)) - - -> TxScriptValidity era -- ^ Mark script as expected to pass or fail validation - - -> TxBody era - -- The 'ShelleyBasedEra' GADT tells us what era we are in. - -- The 'ShelleyLedgerEra' type family maps that to the era type from the - -- ledger lib. The 'Ledger.TxBody' type family maps that to a specific - -- tx body type, which is different for each Shelley-based era. + ShelleyTxBody + :: ShelleyBasedEra era + -- ^ Witness that the era is shelley era onwards + + -> Ledger.TxBody (ShelleyLedgerEra era) + -- ^ The 'ShelleyLedgerEra' type family maps that to the era type from the + -- ledger lib. The 'Ledger.TxBody' type family maps that to a specific + -- tx body type, which is different for each Shelley-based era. + + -> [Ledger.Script (ShelleyLedgerEra era)] + -- ^ We include the scripts along with the tx body, rather than the + -- witnesses set, since they need to be known when building the body. + + -> TxBodyScriptData era + -- ^ The info for each use of each script: the script input data, both + -- the UTxO input data (called the "datum") and the supplied input + -- data (called the "redeemer") and the execution units. + + -> Maybe (L.TxAuxData (ShelleyLedgerEra era)) + -- ^ The 'L.TxAuxData' consists of one or several things, + -- depending on era: + -- + transaction metadata (in Shelley and later) + -- + auxiliary scripts (in Allegra and later) + -- Note that there is no auxiliary script data as such, because the + -- extra script data has to be passed to scripts and hence is needed + -- for validation. It is thus part of the witness data, not the + -- auxiliary data. + + -> TxScriptValidity era + -- ^ Mark script as expected to pass or fail validation + + -> TxBody era -- The GADT in the ShelleyTxBody case requires a custom instance @@ -467,13 +471,18 @@ instance IsShelleyBasedEra era => HasTextEnvelope (TxBody era) where ShelleyBasedEraConway -> "TxBodyConway" data TxBodyScriptData era where - TxBodyNoScriptData :: TxBodyScriptData era - TxBodyScriptData - :: AlonzoEraOnwardsConstraints era - => AlonzoEraOnwards era - -> Alonzo.TxDats (ShelleyLedgerEra era) - -> Alonzo.Redeemers (ShelleyLedgerEra era) - -> TxBodyScriptData era + -- ^ No script data + TxBodyNoScriptData :: TxBodyScriptData era + + TxBodyScriptData + :: AlonzoEraOnwardsConstraints era + => AlonzoEraOnwards era + -- ^ Witness that the era is alonzo era onwards + -> Alonzo.TxDats (ShelleyLedgerEra era) + -- ^ The data inputs for the scripts + -> Alonzo.Redeemers (ShelleyLedgerEra era) + -- ^ The redeemers for the scripts + -> TxBodyScriptData era deriving instance Eq (TxBodyScriptData era) deriving instance L.EraCrypto (ShelleyLedgerEra era) ~ StandardCrypto => Show (TxBodyScriptData era) @@ -510,13 +519,16 @@ isValidToScriptValidity (L.IsValid True) = ScriptValid -- The Alonzo and subsequent eras support script validity. -- data TxScriptValidity era where + -- | No tx script validity TxScriptValidityNone :: TxScriptValidity era - -- | Tx script validity is supported in transactions in the 'Alonzo' era onwards. + -- | Tx script validity TxScriptValidity :: AlonzoEraOnwards era + -- ^ Witness that the era is alonzo era onwards -> ScriptValidity + -- ^ The script validity -> TxScriptValidity era deriving instance Eq (TxScriptValidity era) @@ -533,19 +545,24 @@ txScriptValidityToIsValid = scriptValidityToIsValid . txScriptValidityToScriptVa data KeyWitness era where - ByronKeyWitness - :: Byron.TxInWitness - -> KeyWitness ByronEra + ByronKeyWitness + :: Byron.TxInWitness + -- ^ The witness for a Byron transaction + -> KeyWitness ByronEra - ShelleyBootstrapWitness - :: ShelleyBasedEra era - -> Shelley.BootstrapWitness StandardCrypto - -> KeyWitness era + ShelleyBootstrapWitness + :: ShelleyBasedEra era + -- ^ Witness that the era is shelley era onwards + -> Shelley.BootstrapWitness StandardCrypto + -- ^ The bootstrap witness for a Shelley transaction + -> KeyWitness era - ShelleyKeyWitness - :: ShelleyBasedEra era - -> L.WitVKey Shelley.Witness StandardCrypto - -> KeyWitness era + ShelleyKeyWitness + :: ShelleyBasedEra era + -- ^ Witness that the era is shelley era onwards + -> L.WitVKey Shelley.Witness StandardCrypto + -- ^ The witness for a Shelley transaction + -> KeyWitness era -- The GADT in the Shelley cases requires a custom instance