| Safe Haskell | None |
|---|---|
| Language | Haskell2010 |
Cardano.Api.Tx
Contents
- Creating transactions using the old API
- Creating a
TxBodyContent - Balancing a transaction
- Creating a
ShelleyWitnessSigningKey - Creating a transaction using the old API
- Inspecting transactions
- Appendix: Getting Shelley-based era witness from the new API
- Transaction body
- Byron only
- Transaction Ids
- Transaction inputs
- Transaction outputs
- Other transaction body types
- Inspecting
ScriptWitnesses - Conversion to inline data
- Internal conversion functions & types
- Misc helpers
- Data family instances
- Creating a
- Convenience construction functions
- Fees calculation
- Example 1: Simple fee calculation and manual balancing
- Example 2: Automated balancing without chain information (no UTXO, no ledger state)
- Example 3: Fully automated balancing with chain information (requires UTXO and ledger state data)
- Transaction fees
- Script execution units
- Transaction balance
- Automated transaction building
- Minimum UTxO calculation
- Internal helpers
- Signing a transaction
- TxMetadata
Synopsis
- data TxBody era where
- ShelleyTxBody :: forall era. ShelleyBasedEra era -> TxBody (ShelleyLedgerEra era) -> [Script (ShelleyLedgerEra era)] -> TxBodyScriptData era -> Maybe (TxAuxData (ShelleyLedgerEra era)) -> TxScriptValidity era -> TxBody era
- pattern TxBody :: TxBodyContent ViewTx era -> TxBody era
- createTransactionBody :: HasCallStack => ShelleyBasedEra era -> TxBodyContent BuildTx era -> Either TxBodyError (TxBody era)
- createAndValidateTransactionBody :: ShelleyBasedEra era -> TxBodyContent BuildTx era -> Either TxBodyError (TxBody era)
- data TxBodyContent build era = TxBodyContent {
- txIns :: TxIns build era
- txInsCollateral :: TxInsCollateral era
- txInsReference :: TxInsReference build era
- txOuts :: [TxOut CtxTx era]
- txTotalCollateral :: TxTotalCollateral era
- txReturnCollateral :: TxReturnCollateral CtxTx era
- txFee :: TxFee era
- txValidityLowerBound :: TxValidityLowerBound era
- txValidityUpperBound :: TxValidityUpperBound era
- txMetadata :: TxMetadataInEra era
- txAuxScripts :: TxAuxScripts era
- txExtraKeyWits :: TxExtraKeyWitnesses era
- txProtocolParams :: BuildTxWith build (Maybe (LedgerProtocolParameters era))
- txWithdrawals :: TxWithdrawals build era
- txCertificates :: TxCertificates build era
- txUpdateProposal :: TxUpdateProposal era
- txMintValue :: TxMintValue build era
- txScriptValidity :: TxScriptValidity era
- txProposalProcedures :: Maybe (Featured ConwayEraOnwards era (TxProposalProcedures build era))
- txVotingProcedures :: Maybe (Featured ConwayEraOnwards era (TxVotingProcedures build era))
- txCurrentTreasuryValue :: Maybe (Featured ConwayEraOnwards era (Maybe Coin))
- txTreasuryDonation :: Maybe (Featured ConwayEraOnwards era Coin)
- makeByronTransactionBody :: TxIns BuildTx ByronEra -> [TxOut CtxTx ByronEra] -> Either TxBodyError (Annotated Tx ByteString)
- defaultTxBodyContent :: ShelleyBasedEra era -> TxBodyContent BuildTx era
- defaultTxFee :: ShelleyBasedEra era -> TxFee era
- defaultTxValidityUpperBound :: ShelleyBasedEra era -> TxValidityUpperBound era
- setTxIns :: TxIns build era -> TxBodyContent build era -> TxBodyContent build era
- modTxIns :: (TxIns build era -> TxIns build era) -> TxBodyContent build era -> TxBodyContent build era
- addTxIn :: (TxIn, BuildTxWith build (Witness WitCtxTxIn era)) -> TxBodyContent build era -> TxBodyContent build era
- addTxIns :: TxIns build era -> TxBodyContent build era -> TxBodyContent build era
- setTxInsCollateral :: TxInsCollateral era -> TxBodyContent build era -> TxBodyContent build era
- modTxInsCollateral :: (TxInsCollateral era -> TxInsCollateral era) -> TxBodyContent build era -> TxBodyContent build era
- addTxInsCollateral :: IsAlonzoBasedEra era => [TxIn] -> TxBodyContent build era -> TxBodyContent build era
- addTxInCollateral :: IsAlonzoBasedEra era => TxIn -> TxBodyContent build era -> TxBodyContent build era
- setTxInsReference :: TxInsReference build era -> TxBodyContent build era -> TxBodyContent build era
- modTxInsReference :: (TxInsReference build era -> TxInsReference build era) -> TxBodyContent build era -> TxBodyContent build era
- addTxInsReference :: (Applicative (BuildTxWith build), IsBabbageBasedEra era) => [TxIn] -> Set HashableScriptData -> TxBodyContent build era -> TxBodyContent build era
- addTxInReference :: (Applicative (BuildTxWith build), IsBabbageBasedEra era) => TxIn -> Maybe HashableScriptData -> TxBodyContent build era -> TxBodyContent build era
- setTxOuts :: [TxOut CtxTx era] -> TxBodyContent build era -> TxBodyContent build era
- modTxOuts :: ([TxOut CtxTx era] -> [TxOut CtxTx era]) -> TxBodyContent build era -> TxBodyContent build era
- addTxOut :: TxOut CtxTx era -> TxBodyContent build era -> TxBodyContent build era
- addTxOuts :: [TxOut CtxTx era] -> TxBodyContent build era -> TxBodyContent build era
- setTxTotalCollateral :: TxTotalCollateral era -> TxBodyContent build era -> TxBodyContent build era
- modTxTotalCollateral :: (TxTotalCollateral era -> TxTotalCollateral era) -> TxBodyContent build era -> TxBodyContent build era
- setTxReturnCollateral :: TxReturnCollateral CtxTx era -> TxBodyContent build era -> TxBodyContent build era
- modTxReturnCollateral :: (TxReturnCollateral CtxTx era -> TxReturnCollateral CtxTx era) -> TxBodyContent build era -> TxBodyContent build era
- setTxFee :: TxFee era -> TxBodyContent build era -> TxBodyContent build era
- modTxFee :: (TxFee era -> TxFee era) -> TxBodyContent build era -> TxBodyContent build era
- setTxValidityLowerBound :: TxValidityLowerBound era -> TxBodyContent build era -> TxBodyContent build era
- modTxValidityLowerBound :: (TxValidityLowerBound era -> TxValidityLowerBound era) -> TxBodyContent build era -> TxBodyContent build era
- setTxValidityUpperBound :: TxValidityUpperBound era -> TxBodyContent build era -> TxBodyContent build era
- modTxValidityUpperBound :: (TxValidityUpperBound era -> TxValidityUpperBound era) -> TxBodyContent build era -> TxBodyContent build era
- setTxMetadata :: TxMetadataInEra era -> TxBodyContent build era -> TxBodyContent build era
- modTxMetadata :: (TxMetadataInEra era -> TxMetadataInEra era) -> TxBodyContent build era -> TxBodyContent build era
- setTxAuxScripts :: TxAuxScripts era -> TxBodyContent build era -> TxBodyContent build era
- modTxAuxScripts :: (TxAuxScripts era -> TxAuxScripts era) -> TxBodyContent build era -> TxBodyContent build era
- setTxExtraKeyWits :: TxExtraKeyWitnesses era -> TxBodyContent build era -> TxBodyContent build era
- modTxExtraKeyWits :: (TxExtraKeyWitnesses era -> TxExtraKeyWitnesses era) -> TxBodyContent build era -> TxBodyContent build era
- addTxExtraKeyWits :: IsAlonzoBasedEra era => [Hash PaymentKey] -> TxBodyContent build era -> TxBodyContent build era
- setTxProtocolParams :: BuildTxWith build (Maybe (LedgerProtocolParameters era)) -> TxBodyContent build era -> TxBodyContent build era
- setTxWithdrawals :: TxWithdrawals build era -> TxBodyContent build era -> TxBodyContent build era
- modTxWithdrawals :: (TxWithdrawals build era -> TxWithdrawals build era) -> TxBodyContent build era -> TxBodyContent build era
- setTxCertificates :: TxCertificates build era -> TxBodyContent build era -> TxBodyContent build era
- modTxCertificates :: (TxCertificates build era -> TxCertificates build era) -> TxBodyContent build era -> TxBodyContent build era
- setTxUpdateProposal :: TxUpdateProposal era -> TxBodyContent build era -> TxBodyContent build era
- modTxUpdateProposal :: (TxUpdateProposal era -> TxUpdateProposal era) -> TxBodyContent build era -> TxBodyContent build era
- setTxProposalProcedures :: Maybe (Featured ConwayEraOnwards era (TxProposalProcedures build era)) -> TxBodyContent build era -> TxBodyContent build era
- setTxVotingProcedures :: Maybe (Featured ConwayEraOnwards era (TxVotingProcedures build era)) -> TxBodyContent build era -> TxBodyContent build era
- setTxMintValue :: TxMintValue build era -> TxBodyContent build era -> TxBodyContent build era
- modTxMintValue :: (TxMintValue build era -> TxMintValue build era) -> TxBodyContent build era -> TxBodyContent build era
- addTxMintValue :: IsMaryBasedEra era => Map PolicyId (PolicyAssets, BuildTxWith build (ScriptWitness WitCtxMint era)) -> TxBodyContent build era -> TxBodyContent build era
- subtractTxMintValue :: IsMaryBasedEra era => Map PolicyId (PolicyAssets, BuildTxWith build (ScriptWitness WitCtxMint era)) -> TxBodyContent build era -> TxBodyContent build era
- setTxScriptValidity :: TxScriptValidity era -> TxBodyContent build era -> TxBodyContent build era
- modTxScriptValidity :: (TxScriptValidity era -> TxScriptValidity era) -> TxBodyContent build era -> TxBodyContent build era
- setTxCurrentTreasuryValue :: Maybe (Featured ConwayEraOnwards era (Maybe Coin)) -> TxBodyContent build era -> TxBodyContent build era
- setTxTreasuryDonation :: Maybe (Featured ConwayEraOnwards era Coin) -> TxBodyContent build era -> TxBodyContent build era
- data TxBodyError
- = TxBodyPlutusScriptDecodeError DecoderError
- | TxBodyEmptyTxIns
- | TxBodyEmptyTxInsCollateral
- | TxBodyEmptyTxOuts
- | TxBodyOutputError !TxOutputError
- | TxBodyMetadataError ![(Word64, TxMetadataRangeError)]
- | TxBodyInIxOverflow !TxIn
- | TxBodyMissingProtocolParams
- | TxBodyProtocolParamsConversionError !ProtocolParametersConversionError
- data TxOutputError
- data TxBodyScriptData era where
- TxBodyNoScriptData :: forall era. TxBodyScriptData era
- TxBodyScriptData :: forall era. AlonzoEraOnwardsConstraints era => AlonzoEraOnwards era -> TxDats (ShelleyLedgerEra era) -> Redeemers (ShelleyLedgerEra era) -> TxBodyScriptData era
- selectTxDatums :: TxBodyScriptData era -> Map DataHash (Data (ShelleyLedgerEra era))
- data TxScriptValidity era where
- TxScriptValidityNone :: forall era. TxScriptValidity era
- TxScriptValidity :: forall era. AlonzoEraOnwards era -> ScriptValidity -> TxScriptValidity era
- data ScriptValidity
- scriptValidityToIsValid :: ScriptValidity -> IsValid
- isValidToScriptValidity :: IsValid -> ScriptValidity
- txScriptValidityToIsValid :: TxScriptValidity era -> IsValid
- txScriptValidityToScriptValidity :: TxScriptValidity era -> ScriptValidity
- newtype UTxO era = UTxO {}
- newtype TxId = TxId (Hash HASH EraIndependentTxBody)
- parseTxId :: Parser TxId
- getTxId :: TxBody era -> TxId
- getTxIdByron :: ATxAux ByteString -> TxId
- getTxIdShelley :: EraTxBody (ShelleyLedgerEra era) => ShelleyBasedEra era -> TxBody (ShelleyLedgerEra era) -> TxId
- data TxIn = TxIn TxId TxIx
- parseTxIn :: Parser TxIn
- type TxIns build era = [(TxIn, BuildTxWith build (Witness WitCtxTxIn era))]
- indexTxIns :: TxIns BuildTx era -> [(ScriptWitnessIndex, TxIn, Witness WitCtxTxIn era)]
- newtype TxIx = TxIx Word
- parseTxIx :: Parser TxIx
- genesisUTxOPseudoTxIn :: NetworkId -> Hash GenesisUTxOKey -> TxIn
- getReferenceInputsSizeForTxIds :: ShelleyLedgerEra era ~ ledgerera => BabbageEraOnwards era -> UTxO ledgerera -> Set TxIn -> Int
- data CtxTx
- data CtxUTxO
- data TxOut ctx era = TxOut (AddressInEra era) (TxOutValue era) (TxOutDatum ctx era) (ReferenceScript era)
- data TxOutValue era where
- TxOutValueByron :: Coin -> TxOutValue ByronEra
- TxOutValueShelleyBased :: forall era. (Eq (Value (ShelleyLedgerEra era)), Show (Value (ShelleyLedgerEra era))) => ShelleyBasedEra era -> Value (ShelleyLedgerEra era) -> TxOutValue era
- data TxOutDatum ctx era where
- TxOutDatumNone :: forall ctx era. TxOutDatum ctx era
- TxOutDatumHash :: forall era ctx. AlonzoEraOnwards era -> Hash ScriptData -> TxOutDatum ctx era
- TxOutSupplementalDatum :: forall era. AlonzoEraOnwards era -> HashableScriptData -> TxOutDatum CtxTx era
- TxOutDatumInline :: forall era ctx. BabbageEraOnwards era -> HashableScriptData -> TxOutDatum ctx era
- toCtxUTxOTxOut :: TxOut CtxTx era -> TxOut CtxUTxO era
- fromCtxUTxOTxOut :: TxOut CtxUTxO era -> TxOut CtxTx era
- lovelaceToTxOutValue :: ShelleyBasedEra era -> Coin -> TxOutValue era
- prettyRenderTxOut :: TxOutInAnyEra -> Text
- txOutValueToLovelace :: TxOutValue era -> Coin
- txOutValueToValue :: TxOutValue era -> Value
- data TxOutInAnyEra where
- TxOutInAnyEra :: forall era. CardanoEra era -> TxOut CtxTx era -> TxOutInAnyEra
- txOutInAnyEra :: CardanoEra era -> TxOut CtxTx era -> TxOutInAnyEra
- data TxInsCollateral era where
- TxInsCollateralNone :: forall era. TxInsCollateral era
- TxInsCollateral :: forall era. AlonzoEraOnwards era -> [TxIn] -> TxInsCollateral era
- data TxInsReference build era where
- TxInsReferenceNone :: forall build era. TxInsReference build era
- TxInsReference :: forall era build. BabbageEraOnwards era -> [TxIn] -> TxInsReferenceDatums build -> TxInsReference build era
- type TxInsReferenceDatums build = BuildTxWith build (Set HashableScriptData)
- getReferenceInputDatumMap :: TxInsReferenceDatums build -> Map (Hash ScriptData) HashableScriptData
- data TxReturnCollateral ctx era where
- TxReturnCollateralNone :: forall ctx era. TxReturnCollateral ctx era
- TxReturnCollateral :: forall era ctx. BabbageEraOnwards era -> TxOut ctx era -> TxReturnCollateral ctx era
- data TxTotalCollateral era where
- TxTotalCollateralNone :: forall era. TxTotalCollateral era
- TxTotalCollateral :: forall era. BabbageEraOnwards era -> Coin -> TxTotalCollateral era
- data TxFee era where
- TxFeeExplicit :: forall era. ShelleyBasedEra era -> Coin -> TxFee era
- data TxValidityLowerBound era where
- TxValidityNoLowerBound :: forall era. TxValidityLowerBound era
- TxValidityLowerBound :: forall era. AllegraEraOnwards era -> SlotNo -> TxValidityLowerBound era
- data TxValidityUpperBound era where
- TxValidityUpperBound :: forall era. ShelleyBasedEra era -> Maybe SlotNo -> TxValidityUpperBound era
- data TxMetadataInEra era where
- TxMetadataNone :: forall era. TxMetadataInEra era
- TxMetadataInEra :: forall era. ShelleyBasedEra era -> TxMetadata -> TxMetadataInEra era
- data TxAuxScripts era where
- TxAuxScriptsNone :: forall era. TxAuxScripts era
- TxAuxScripts :: forall era. AllegraEraOnwards era -> [ScriptInEra era] -> TxAuxScripts era
- data TxExtraKeyWitnesses era where
- TxExtraKeyWitnessesNone :: forall era. TxExtraKeyWitnesses era
- TxExtraKeyWitnesses :: forall era. AlonzoEraOnwards era -> [Hash PaymentKey] -> TxExtraKeyWitnesses era
- data TxWithdrawals build era where
- TxWithdrawalsNone :: forall build era. TxWithdrawals build era
- TxWithdrawals :: forall era build. ShelleyBasedEra era -> [(StakeAddress, Coin, BuildTxWith build (Witness WitCtxStake era))] -> TxWithdrawals build era
- indexTxWithdrawals :: TxWithdrawals BuildTx era -> [(ScriptWitnessIndex, StakeAddress, Coin, Witness WitCtxStake era)]
- data TxCertificates build era where
- TxCertificatesNone :: forall build era. TxCertificates build era
- TxCertificates :: forall era build. ShelleyBasedEra era -> OMap (Certificate (ShelleyLedgerEra era)) (BuildTxWith build (Maybe (StakeCredential, Witness WitCtxStake era))) -> TxCertificates build era
- mkTxCertificates :: forall era build. Applicative (BuildTxWith build) => ShelleyBasedEra era -> [(Certificate (ShelleyLedgerEra era), Maybe (ScriptWitness WitCtxStake era))] -> TxCertificates build era
- indexTxCertificates :: TxCertificates BuildTx era -> [(ScriptWitnessIndex, Certificate (ShelleyLedgerEra era), StakeCredential, Witness WitCtxStake era)]
- data TxUpdateProposal era where
- TxUpdateProposalNone :: forall era. TxUpdateProposal era
- TxUpdateProposal :: forall era. ShelleyToBabbageEra era -> UpdateProposal -> TxUpdateProposal era
- data TxMintValue build era where
- TxMintNone :: forall build era. TxMintValue build era
- TxMintValue :: forall era build. MaryEraOnwards era -> Map PolicyId (PolicyAssets, BuildTxWith build (ScriptWitness WitCtxMint era)) -> TxMintValue build era
- mkTxMintValue :: MaryEraOnwards era -> [(PolicyId, PolicyAssets, BuildTxWith build (ScriptWitness WitCtxMint era))] -> TxMintValue build era
- txMintValueToValue :: TxMintValue build era -> Value
- indexTxMintValue :: TxMintValue build era -> [(ScriptWitnessIndex, PolicyId, PolicyAssets, BuildTxWith build (ScriptWitness WitCtxMint era))]
- data TxVotingProcedures build era where
- TxVotingProceduresNone :: forall build era. TxVotingProcedures build era
- TxVotingProcedures :: forall era build. VotingProcedures (ShelleyLedgerEra era) -> BuildTxWith build (Map Voter (ScriptWitness WitCtxStake era)) -> TxVotingProcedures build era
- mkTxVotingProcedures :: Applicative (BuildTxWith build) => [(VotingProcedures era, Maybe (ScriptWitness WitCtxStake era))] -> Either (VotesMergingConflict era) (TxVotingProcedures build era)
- indexTxVotingProcedures :: TxVotingProcedures BuildTx era -> [(ScriptWitnessIndex, Voter, ScriptWitness WitCtxStake era)]
- data TxProposalProcedures build era where
- TxProposalProceduresNone :: forall build era. TxProposalProcedures build era
- TxProposalProcedures :: forall era build. EraPParams (ShelleyLedgerEra era) => OMap (ProposalProcedure (ShelleyLedgerEra era)) (BuildTxWith build (Maybe (ScriptWitness WitCtxStake era))) -> TxProposalProcedures build era
- mkTxProposalProcedures :: forall era build. (Applicative (BuildTxWith build), IsShelleyBasedEra era) => [(ProposalProcedure (ShelleyLedgerEra era), Maybe (ScriptWitness WitCtxStake era))] -> TxProposalProcedures build era
- indexTxProposalProcedures :: TxProposalProcedures BuildTx era -> [(ScriptWitnessIndex, ProposalProcedure (ShelleyLedgerEra era), ScriptWitness WitCtxStake era)]
- indexWitnessedTxProposalProcedures :: TxProposalProcedures BuildTx era -> [(ProposalProcedure (ShelleyLedgerEra era), Maybe (ScriptWitnessIndex, ScriptWitness WitCtxStake era))]
- convProposalProcedures :: TxProposalProcedures build era -> OSet (ProposalProcedure (ShelleyLedgerEra era))
- data BuildTxWith build a where
- ViewTx :: forall a. BuildTxWith ViewTx a
- BuildTxWith :: forall a. a -> BuildTxWith BuildTx a
- data BuildTx
- data ViewTx
- buildTxWithToMaybe :: BuildTxWith build a -> Maybe a
- data AnyScriptWitness era where
- AnyScriptWitness :: forall witctx era. Typeable witctx => ScriptWitness witctx era -> AnyScriptWitness era
- data ScriptWitnessIndex
- renderScriptWitnessIndex :: ScriptWitnessIndex -> String
- collectTxBodyScriptWitnesses :: ShelleyBasedEra era -> TxBodyContent BuildTx era -> [(ScriptWitnessIndex, AnyScriptWitness era)]
- collectTxBodyScriptWitnessRequirements :: IsShelleyBasedEra era => AlonzoEraOnwards era -> TxBodyContent BuildTx era -> Either TxBodyError (TxScriptWitnessRequirements (ShelleyLedgerEra era))
- toScriptIndex :: AlonzoEraOnwards era -> PlutusPurpose AsIx (ShelleyLedgerEra era) -> ScriptWitnessIndex
- scriptDataToInlineDatum :: Era ledgerera => HashableScriptData -> Datum ledgerera
- convCertificates :: ShelleyBasedEra era -> TxCertificates build era -> StrictSeq (TxCert (ShelleyLedgerEra era))
- convCollateralTxIns :: TxInsCollateral era -> Set TxIn
- convExtraKeyWitnesses :: TxExtraKeyWitnesses era -> Set (KeyHash 'Witness)
- convLanguages :: [(ScriptWitnessIndex, AnyScriptWitness era)] -> Set Language
- convMintValue :: TxMintValue build era -> MultiAsset
- convPParamsToScriptIntegrityHash :: AlonzoEraOnwards era -> BuildTxWith BuildTx (Maybe (LedgerProtocolParameters era)) -> Redeemers (ShelleyLedgerEra era) -> TxDats (ShelleyLedgerEra era) -> Set Language -> StrictMaybe ScriptIntegrityHash
- convReferenceInputs :: TxInsReference build era -> Set TxIn
- convReturnCollateral :: ShelleyBasedEra era -> TxReturnCollateral ctx era -> StrictMaybe (TxOut (ShelleyLedgerEra era))
- convScripts :: ShelleyLedgerEra era ~ ledgerera => [(ScriptWitnessIndex, AnyScriptWitness era)] -> [Script ledgerera]
- convScriptData :: ShelleyBasedEra era -> [TxOut CtxTx era] -> [(ScriptWitnessIndex, AnyScriptWitness era)] -> TxBodyScriptData era
- convTotalCollateral :: TxTotalCollateral era -> StrictMaybe Coin
- convTransactionFee :: ShelleyBasedEra era -> TxFee era -> Coin
- convTxIns :: TxIns BuildTx era -> Set TxIn
- convTxOuts :: forall ctx era ledgerera. (HasCallStack, ShelleyLedgerEra era ~ ledgerera) => ShelleyBasedEra era -> [TxOut ctx era] -> StrictSeq (TxOut ledgerera)
- convTxUpdateProposal :: ShelleyBasedEra era -> TxUpdateProposal era -> Either TxBodyError (StrictMaybe (Update (ShelleyLedgerEra era)))
- convValidityLowerBound :: TxValidityLowerBound era -> Maybe SlotNo
- convValidityUpperBound :: ShelleyBasedEra era -> TxValidityUpperBound era -> Maybe SlotNo
- convVotingProcedures :: TxVotingProcedures build era -> VotingProcedures (ShelleyLedgerEra era)
- convWithdrawals :: TxWithdrawals build era -> Withdrawals
- getScriptIntegrityHash :: BuildTxWith BuildTx (Maybe (LedgerProtocolParameters era)) -> Set Language -> TxBodyScriptData era -> StrictMaybe ScriptIntegrityHash
- mkCommonTxBody :: HasCallStack => ShelleyBasedEra era -> TxIns BuildTx era -> [TxOut ctx era] -> TxFee era -> TxWithdrawals build era -> Maybe (TxAuxData (ShelleyLedgerEra era)) -> LedgerTxBody era
- toAuxiliaryData :: ShelleyBasedEra era -> TxMetadataInEra era -> TxAuxScripts era -> Maybe (TxAuxData (ShelleyLedgerEra era))
- toByronTxId :: TxId -> TxId
- toShelleyTxId :: TxId -> TxId
- toShelleyTxIn :: TxIn -> TxIn
- toShelleyTxOut :: (HasCallStack, ShelleyLedgerEra era ~ ledgerera) => ShelleyBasedEra era -> TxOut CtxUTxO era -> TxOut ledgerera
- toShelleyTxOutAny :: forall ctx era ledgerera. (HasCallStack, ShelleyLedgerEra era ~ ledgerera) => ShelleyBasedEra era -> TxOut ctx era -> TxOut ledgerera
- fromShelleyTxId :: TxId -> TxId
- fromShelleyTxIn :: TxIn -> TxIn
- fromShelleyTxOut :: ShelleyBasedEra era -> TxOut (ShelleyLedgerEra era) -> TxOut ctx era
- fromByronTxIn :: TxIn -> TxIn
- fromLedgerTxOuts :: ShelleyBasedEra era -> TxBody (ShelleyLedgerEra era) -> TxBodyScriptData era -> [TxOut CtxTx era]
- renderTxIn :: TxIn -> Text
- calculateExecutionUnitsLovelace :: Prices -> ExecutionUnits -> Maybe Coin
- data family AsType t
- getTxBodyContent :: TxBody era -> TxBodyContent ViewTx era
- validateTxIns :: [(TxIn, BuildTxWith BuildTx (Witness WitCtxTxIn era))] -> Either TxBodyError ()
- guardShelleyTxInsOverflow :: [TxIn] -> Either TxBodyError ()
- validateTxOuts :: ShelleyBasedEra era -> [TxOut CtxTx era] -> Either TxOutputError ()
- validateMetadata :: TxMetadataInEra era -> Either TxBodyError ()
- validateTxInsCollateral :: TxInsCollateral era -> Set Language -> Either TxBodyError ()
- validateProtocolParameters :: BuildTxWith BuildTx (Maybe (LedgerProtocolParameters era)) -> Set Language -> Either TxBodyError ()
- constructBalancedTx :: ShelleyBasedEra era -> TxBodyContent BuildTx era -> AddressInEra era -> Maybe Word -> UTxO era -> LedgerProtocolParameters era -> LedgerEpochInfo -> SystemStart -> Set PoolId -> Map StakeCredential Coin -> Map (Credential 'DRepRole) Coin -> [ShelleyWitnessSigningKey] -> Either (TxBodyErrorAutoBalance era) (Tx era)
- data TxInsExistError
- = TxInsDoNotExist [TxIn]
- | EmptyUTxO
- newtype ScriptLockedTxInsError = ScriptLockedTxIns [TxIn]
- notScriptLockedTxIns :: [TxIn] -> UTxO era -> Either ScriptLockedTxInsError ()
- renderNotScriptLockedTxInsError :: ScriptLockedTxInsError -> Text
- renderTxInsExistError :: TxInsExistError -> Text
- txInsExistInUTxO :: [TxIn] -> UTxO era -> Either TxInsExistError ()
- newtype LedgerTxBody era = LedgerTxBody {
- unTxBody :: TxBody (ShelleyLedgerEra era)
- mkAdaOnlyTxOut :: ShelleyBasedEra era -> Addr -> Coin -> TxOut (ShelleyLedgerEra era)
- mkAdaValue :: ShelleyBasedEra era -> Coin -> Value (ShelleyLedgerEra era)
- strictMaybeL :: forall a f. Functor f => (Maybe a -> f (Maybe a)) -> StrictMaybe a -> f (StrictMaybe a)
- invalidBeforeL :: Lens' ValidityInterval (Maybe SlotNo)
- invalidHereAfterL :: Lens' ValidityInterval (Maybe SlotNo)
- invalidBeforeStrictL :: Lens' ValidityInterval (StrictMaybe SlotNo)
- invalidHereAfterStrictL :: Lens' ValidityInterval (StrictMaybe SlotNo)
- invalidBeforeTxBodyL :: AllegraEraOnwards era -> Lens' (LedgerTxBody era) (Maybe SlotNo)
- invalidHereAfterTxBodyL :: ShelleyBasedEra era -> Lens' (LedgerTxBody era) (Maybe SlotNo)
- ttlAsInvalidHereAfterTxBodyL :: ShelleyEraOnly era -> Lens' (LedgerTxBody era) (Maybe SlotNo)
- updateTxBodyL :: ShelleyToBabbageEra era -> Lens' (LedgerTxBody era) (StrictMaybe (Update (ShelleyLedgerEra era)))
- txBodyL :: forall era f. Functor f => (TxBody (ShelleyLedgerEra era) -> f (TxBody (ShelleyLedgerEra era))) -> LedgerTxBody era -> f (LedgerTxBody era)
- mintTxBodyL :: MaryEraOnwards era -> Lens' (LedgerTxBody era) MultiAsset
- scriptIntegrityHashTxBodyL :: AlonzoEraOnwards era -> Lens' (LedgerTxBody era) (StrictMaybe ScriptIntegrityHash)
- collateralInputsTxBodyL :: AlonzoEraOnwards era -> Lens' (LedgerTxBody era) (Set TxIn)
- reqSignerHashesTxBodyL :: AlonzoEraOnwards era -> Lens' (LedgerTxBody era) (Set (KeyHash 'Witness))
- referenceInputsTxBodyL :: BabbageEraOnwards era -> Lens' (LedgerTxBody era) (Set TxIn)
- collateralReturnTxBodyL :: BabbageEraOnwards era -> Lens' (LedgerTxBody era) (StrictMaybe (TxOut (ShelleyLedgerEra era)))
- totalCollateralTxBodyL :: BabbageEraOnwards era -> Lens' (LedgerTxBody era) (StrictMaybe Coin)
- certsTxBodyL :: ShelleyBasedEra era -> Lens' (LedgerTxBody era) (StrictSeq (TxCert (ShelleyLedgerEra era)))
- votingProceduresTxBodyL :: ConwayEraOnwards era -> Lens' (LedgerTxBody era) (VotingProcedures (ShelleyLedgerEra era))
- proposalProceduresTxBodyL :: ConwayEraOnwards era -> Lens' (LedgerTxBody era) (OSet (ProposalProcedure (ShelleyLedgerEra era)))
- currentTreasuryValueTxBodyL :: ConwayEraOnwards era -> Lens' (LedgerTxBody era) (StrictMaybe Coin)
- treasuryDonationTxBodyL :: ConwayEraOnwards era -> Lens' (LedgerTxBody era) Coin
- adaAssetL :: ShelleyBasedEra era -> Lens' (Value (ShelleyLedgerEra era)) Coin
- multiAssetL :: MaryEraOnwards era -> Lens' MaryValue MultiAsset
- valueTxOutL :: ShelleyBasedEra era -> Lens' (TxOut (ShelleyLedgerEra era)) (Value (ShelleyLedgerEra era))
- valueTxOutAdaAssetL :: ShelleyBasedEra era -> Lens' (TxOut (ShelleyLedgerEra era)) Coin
- evaluateTransactionFee :: ShelleyBasedEra era -> PParams (ShelleyLedgerEra era) -> TxBody era -> Word -> Word -> Int -> Coin
- calculateMinTxFee :: ShelleyBasedEra era -> PParams (ShelleyLedgerEra era) -> UTxO era -> TxBody era -> Word -> Coin
- estimateTransactionKeyWitnessCount :: TxBodyContent BuildTx era -> Word
- evaluateTransactionExecutionUnits :: CardanoEra era -> SystemStart -> LedgerEpochInfo -> LedgerProtocolParameters era -> UTxO era -> TxBody era -> Map ScriptWitnessIndex (Either ScriptExecutionError (EvalTxExecutionUnitsLog, ExecutionUnits))
- evaluateTransactionExecutionUnitsShelley :: ShelleyBasedEra era -> SystemStart -> LedgerEpochInfo -> LedgerProtocolParameters era -> UTxO era -> Tx (ShelleyLedgerEra era) -> Map ScriptWitnessIndex (Either ScriptExecutionError (EvalTxExecutionUnitsLog, ExecutionUnits))
- data ScriptExecutionError
- = ScriptErrorMissingTxIn TxIn
- | ScriptErrorTxInWithoutDatum TxIn
- | ScriptErrorWrongDatum (Hash ScriptData)
- | ScriptErrorEvaluationFailed DebugPlutusFailure
- | ScriptErrorExecutionUnitsOverflow
- | ScriptErrorNotPlutusWitnessedTxIn ScriptWitnessIndex ScriptHash
- | ScriptErrorRedeemerPointsToUnknownScriptHash ScriptWitnessIndex
- | ScriptErrorMissingScript ScriptWitnessIndex ResolvablePointers
- | ScriptErrorMissingCostModel Language
- | (EraPlutusContext (ShelleyLedgerEra era), Show (ContextError (ShelleyLedgerEra era))) => ScriptErrorTranslationError (ContextError (ShelleyLedgerEra era))
- data TransactionValidityError era where
- TransactionValidityIntervalError :: forall era. PastHorizonException -> TransactionValidityError era
- TransactionValidityCostModelError :: forall era. Map AnyPlutusScriptVersion CostModel -> String -> TransactionValidityError era
- evaluateTransactionBalance :: ShelleyBasedEra era -> PParams (ShelleyLedgerEra era) -> Set PoolId -> Map StakeCredential Coin -> Map (Credential 'DRepRole) Coin -> UTxO era -> TxBody era -> TxOutValue era
- estimateBalancedTxBody :: HasCallStack => MaryEraOnwards era -> TxBodyContent BuildTx era -> PParams (ShelleyLedgerEra era) -> Set PoolId -> Map StakeCredential Coin -> Map (Credential 'DRepRole) Coin -> Map ScriptWitnessIndex ExecutionUnits -> Coin -> Int -> Int -> Int -> AddressInEra era -> Value -> Either (TxFeeEstimationError era) (BalancedTxBody era)
- estimateOrCalculateBalancedTxBody :: ShelleyBasedEra era -> FeeEstimationMode era -> PParams (ShelleyLedgerEra era) -> TxBodyContent BuildTx era -> Set PoolId -> Map StakeCredential Coin -> Map (Credential 'DRepRole) Coin -> AddressInEra era -> Either (AutoBalanceError era) (BalancedTxBody era)
- makeTransactionBodyAutoBalance :: HasCallStack => ShelleyBasedEra era -> SystemStart -> LedgerEpochInfo -> LedgerProtocolParameters era -> Set PoolId -> Map StakeCredential Coin -> Map (Credential 'DRepRole) Coin -> UTxO era -> TxBodyContent BuildTx era -> AddressInEra era -> Maybe Word -> Either (TxBodyErrorAutoBalance era) (BalancedTxBody era)
- calcReturnAndTotalCollateral :: AlonzoEraPParams (ShelleyLedgerEra era) => BabbageEraOnwards era -> Coin -> PParams (ShelleyLedgerEra era) -> TxInsCollateral era -> TxReturnCollateral CtxTx era -> TxTotalCollateral era -> AddressInEra era -> Value (ShelleyLedgerEra era) -> (TxReturnCollateral CtxTx era, TxTotalCollateral era)
- data AutoBalanceError era
- data BalancedTxBody era = BalancedTxBody (TxBodyContent BuildTx era) (TxBody era) (TxOut CtxTx era) Coin
- data FeeEstimationMode era
- newtype RequiredShelleyKeyWitnesses = RequiredShelleyKeyWitnesses {}
- newtype RequiredByronKeyWitnesses = RequiredByronKeyWitnesses {}
- newtype TotalReferenceScriptsSize = TotalReferenceScriptsSize {}
- data TxBodyErrorAutoBalance era
- = TxBodyError TxBodyError
- | TxBodyScriptExecutionError [(ScriptWitnessIndex, ScriptExecutionError)]
- | TxBodyScriptBadScriptValidity
- | TxBodyErrorBalanceNegative Coin MultiAsset
- | TxBodyErrorAdaBalanceTooSmall TxOutInAnyEra Coin Coin
- | TxBodyErrorByronEraNotSupported
- | TxBodyErrorMissingParamMinUTxO
- | TxBodyErrorMinUTxONotMet TxOutInAnyEra Coin
- | TxBodyErrorNonAdaAssetsUnbalanced Value
- | TxBodyErrorScriptWitnessIndexMissingFromExecUnitsMap ScriptWitnessIndex (Map ScriptWitnessIndex ExecutionUnits)
- data TxFeeEstimationError era
- = TxFeeEstimationTransactionTranslationError (TransactionValidityError era)
- | TxFeeEstimationScriptExecutionError (TxBodyErrorAutoBalance era)
- | TxFeeEstimationBalanceError (TxBodyErrorAutoBalance era)
- | TxFeeEstimationxBodyError TxBodyError
- | TxFeeEstimationFinalConstructionError TxBodyError
- | TxFeeEstimationOnlyMaryOnwardsSupportedError
- calculateMinimumUTxO :: HasCallStack => ShelleyBasedEra era -> PParams (ShelleyLedgerEra era) -> TxOut CtxTx era -> Coin
- data ResolvablePointers where
- ResolvablePointers :: forall era. (Era (ShelleyLedgerEra era), Show (PlutusPurpose AsIx (ShelleyLedgerEra era)), Show (PlutusPurpose AsItem (ShelleyLedgerEra era)), Show (PlutusScript (ShelleyLedgerEra era))) => ShelleyBasedEra era -> !(Map (PlutusPurpose AsIx (ShelleyLedgerEra era)) (PlutusPurpose AsItem (ShelleyLedgerEra era), Maybe (PlutusScriptBytes, Language), ScriptHash)) -> ResolvablePointers
- substituteExecutionUnits :: Map ScriptWitnessIndex ExecutionUnits -> TxBodyContent BuildTx era -> Either (TxBodyErrorAutoBalance era) (TxBodyContent BuildTx era)
- handleExUnitsErrors :: ScriptValidity -> Map ScriptWitnessIndex ScriptExecutionError -> Map ScriptWitnessIndex ExecutionUnits -> Either (TxBodyErrorAutoBalance era) (Map ScriptWitnessIndex ExecutionUnits)
- data Tx era where
- ShelleyTx :: forall era. ShelleyBasedEra era -> Tx (ShelleyLedgerEra era) -> Tx era
- pattern Tx :: TxBody era -> [KeyWitness era] -> Tx era
- data ATxAux a = ATxAux {
- aTaTx :: !(Annotated Tx a)
- aTaWitness :: !(Annotated TxWitness a)
- aTaAnnotation :: !a
- getTxBody :: Tx era -> TxBody era
- getByronTxBody :: ATxAux ByteString -> Annotated Tx ByteString
- getTxWitnesses :: Tx era -> [KeyWitness era]
- getTxWitnessesByron :: ATxAux ByteString -> [KeyWitness ByronEra]
- data ShelleySigningKey
- toShelleySigningKey :: ShelleyWitnessSigningKey -> ShelleySigningKey
- signByronTransaction :: NetworkId -> Annotated Tx ByteString -> [SigningKey ByronKey] -> ATxAux ByteString
- signShelleyTransaction :: ShelleyBasedEra era -> TxBody era -> [ShelleyWitnessSigningKey] -> Tx era
- makeSignedByronTransaction :: [KeyWitness era] -> Annotated Tx ByteString -> ATxAux ByteString
- makeSignedTransaction :: [KeyWitness era] -> TxBody era -> Tx era
- makeSignedTransaction' :: CardanoEra era -> [KeyWitness era] -> TxBody era -> Tx era
- data KeyWitness era where
- ByronKeyWitness :: TxInWitness -> KeyWitness ByronEra
- ShelleyBootstrapWitness :: forall era. ShelleyBasedEra era -> BootstrapWitness -> KeyWitness era
- ShelleyKeyWitness :: forall era. ShelleyBasedEra era -> WitVKey 'Witness -> KeyWitness era
- makeByronKeyWitness :: IsByronKey key => NetworkId -> Annotated Tx ByteString -> SigningKey key -> KeyWitness ByronEra
- data ShelleyWitnessSigningKey
- = WitnessPaymentKey (SigningKey PaymentKey)
- | WitnessPaymentExtendedKey (SigningKey PaymentExtendedKey)
- | WitnessStakeKey (SigningKey StakeKey)
- | WitnessStakeExtendedKey (SigningKey StakeExtendedKey)
- | WitnessStakePoolKey (SigningKey StakePoolKey)
- | WitnessStakePoolExtendedKey (SigningKey StakePoolExtendedKey)
- | WitnessGenesisKey (SigningKey GenesisKey)
- | WitnessGenesisExtendedKey (SigningKey GenesisExtendedKey)
- | WitnessGenesisDelegateKey (SigningKey GenesisDelegateKey)
- | WitnessGenesisDelegateExtendedKey (SigningKey GenesisDelegateExtendedKey)
- | WitnessGenesisUTxOKey (SigningKey GenesisUTxOKey)
- | WitnessCommitteeColdKey (SigningKey CommitteeColdKey)
- | WitnessCommitteeColdExtendedKey (SigningKey CommitteeColdExtendedKey)
- | WitnessCommitteeHotKey (SigningKey CommitteeHotKey)
- | WitnessCommitteeHotExtendedKey (SigningKey CommitteeHotExtendedKey)
- | WitnessDRepKey (SigningKey DRepKey)
- | WitnessDRepExtendedKey (SigningKey DRepExtendedKey)
- makeShelleyKeyWitness :: ShelleyBasedEra era -> TxBody era -> ShelleyWitnessSigningKey -> KeyWitness era
- makeShelleyKeyWitness' :: ShelleyBasedEra era -> TxBody (ShelleyLedgerEra era) -> ShelleyWitnessSigningKey -> KeyWitness era
- data WitnessNetworkIdOrByronAddress
- makeShelleyBootstrapWitness :: ShelleyBasedEra era -> WitnessNetworkIdOrByronAddress -> TxBody era -> SigningKey ByronKey -> KeyWitness era
- makeShelleyBasedBootstrapWitness :: ShelleyBasedEra era -> WitnessNetworkIdOrByronAddress -> TxBody (ShelleyLedgerEra era) -> SigningKey ByronKey -> KeyWitness era
- makeShelleySignature :: SignableRepresentation tosign => tosign -> ShelleySigningKey -> SignedDSIGN DSIGN tosign
- getShelleyKeyWitnessVerificationKey :: ShelleySigningKey -> VKey 'Witness
- getTxBodyAndWitnesses :: Tx era -> (TxBody era, [KeyWitness era])
- newtype TxMetadata = TxMetadata {}
- class AsTxMetadata a where
- asTxMetadata :: a -> TxMetadata
- data TxMetadataValue
- makeTransactionMetadata :: Map Word64 TxMetadataValue -> TxMetadata
- mergeTransactionMetadata :: (TxMetadataValue -> TxMetadataValue -> TxMetadataValue) -> TxMetadata -> TxMetadata -> TxMetadata
- metaTextChunks :: Text -> TxMetadataValue
- metaBytesChunks :: ByteString -> TxMetadataValue
- validateTxMetadata :: TxMetadata -> Either [(Word64, TxMetadataRangeError)] ()
- data TxMetadataRangeError
- data TxMetadataJsonSchema
- metadataFromJson :: TxMetadataJsonSchema -> Value -> Either TxMetadataJsonError TxMetadata
- metadataToJson :: TxMetadataJsonSchema -> TxMetadata -> Value
- metadataValueFromJsonNoSchema :: Value -> Either TxMetadataJsonSchemaError TxMetadataValue
- metadataValueToJsonNoSchema :: TxMetadataValue -> Value
- data TxMetadataJsonError
- data TxMetadataJsonSchemaError
- = TxMetadataJsonNullNotAllowed
- | TxMetadataJsonBoolNotAllowed
- | TxMetadataJsonNumberNotInteger !Double
- | TxMetadataJsonNotObject !Value
- | TxMetadataJsonBadObject ![(Text, Value)]
- | TxMetadataJsonBadMapPair !Value
- | TxMetadataJsonTypeMismatch !Text !Value
- toShelleyMetadata :: Map Word64 TxMetadataValue -> Map Word64 Metadatum
- fromShelleyMetadata :: Map Word64 Metadatum -> Map Word64 TxMetadataValue
- toShelleyMetadatum :: TxMetadataValue -> Metadatum
- fromShelleyMetadatum :: Metadatum -> TxMetadataValue
- extractWitnessableCertificates :: AlonzoEraOnwards era -> TxCertificates BuildTx era -> [(Witnessable 'CertItem (ShelleyLedgerEra era), BuildTxWith BuildTx (Witness WitCtxStake era))]
- extractWitnessableMints :: AlonzoEraOnwards era -> TxMintValue build era -> [(Witnessable 'MintItem (ShelleyLedgerEra era), BuildTxWith BuildTx (Witness WitCtxMint era))]
- extractWitnessableProposals :: forall era (eon :: Type -> Type). ConwayEraOnwards era -> Maybe (Featured eon era (TxProposalProcedures BuildTx era)) -> [(Witnessable 'ProposalItem (ShelleyLedgerEra era), BuildTxWith BuildTx (Witness WitCtxStake era))]
- extractWitnessableTxIns :: AlonzoEraOnwards era -> TxIns BuildTx era -> [(Witnessable 'TxInItem (ShelleyLedgerEra era), BuildTxWith BuildTx (Witness WitCtxTxIn era))]
- extractWitnessableVotes :: forall era (eon :: Type -> Type). ConwayEraOnwards era -> Maybe (Featured eon era (TxVotingProcedures BuildTx era)) -> [(Witnessable 'VoterItem (ShelleyLedgerEra era), BuildTxWith BuildTx (Witness WitCtxStake era))]
- extractWitnessableWithdrawals :: AlonzoEraOnwards era -> TxWithdrawals BuildTx era -> [(Witnessable 'WithdrawalItem (ShelleyLedgerEra era), BuildTxWith BuildTx (Witness WitCtxStake era))]
- legacyKeyWitnessEncode :: KeyWitness era -> ByteString
- parseAll :: Parser a -> Text -> Maybe a
- pUnsigned :: Parser Integer
- pSigned :: Parser Integer
- pBytes :: Parser ByteString
Creating transactions using the old API
Both the old and new APIs support transaction creation. Transactions can be
converted between formats, as they share the same underlying representation.
cardano-api will be moving towards using the new API and deprecating
the old way to ensure simplicity, closer alignment with the ledger, and
easier maintenance.
In both the new and old APIs, to construct a transaction, you need
to construct a TxBodyContent, and you will need at least a
witness (for example, a ShelleyWitnessSigningKey), to sign the transaction.
This process remains unchanged.
To learn how to create a transaction using the new API, refer to Cardano.Api.Experimental.Tx documentation.
The next examples use the following qualified modules:
import qualified Cardano.Api as Api -- the general `cardano-api` exports (including the old API) import qualified Cardano.Api.Script as Script -- types related to scripts (Plutus and native) import qualified Cardano.Api.Ledger as Ledger -- cardano-ledger re-exports
Creating a TxBodyContent
To create a transaction, you first need to define the contents of its body. This section
will show how to use the API to create a TxBodyContent for a simple transaction.
TxBodyContent datatype provides several fields because transactions can serve multiple
purposes, but the function defaultTxBodyContent (exported from Cardano.Api) already provides
a base TxBodyContent with all fields set to their default values that you can use as a starting point
so as not to have to set all fields manually.
The defaultTxBodyContent takes, as the only parameter, the ShelleyBasedEra witness for the era
you are working with. For example, if you are working with the ConwayEra, use shelleyBasedEra
available in Cardano.Api, as follows:
let sbe :: Api.ShelleyBasedEra Api.ConwayEra = Api.shelleyBasedEra
This is what creating a simple TxBodyContent would look like.
First, choose a transaction output to spend (a UTXO). Specify which UTXO to spend by providing the transaction ID and the index of the output in that transaction that you want to spend.
To specify the transaction ID, you can use the deserialiseFromRawBytesHex function on the
hexadecimal representation of the transaction hash. For example:
let (Right srcTxId) = Api.deserialiseFromRawBytesHex Api.AsTxId "be6efd42a3d7b9a00d09d77a5d41e55ceaf0bd093a8aa8a893ce70d9caafd978"
In real implementations, failure cases should be handled appropriately.
To specify the transaction index, use the TxIx constructor. For example:
let srcTxIx = Api.TxIx 0
Now, combine both to create a TxIn value and pair it with a witness requirement using BuildTxWith :
let txIn = ( Api.TxIn srcTxId srcTxIx
, Api.BuildTxWith (Api.KeyWitness Api.KeyWitnessForSpending)
)
Next, specify the address of the recipient of the transaction. If you have the bech32 representation,
you can use the deserialiseAddress function to get the AddressInEra type. For example:
let (Just destAddress) = Api.deserialiseAddress (Api.AsAddressInEra eraAsType) "addr_test1vzpfxhjyjdlgk5c0xt8xw26avqxs52rtf69993j4tajehpcue4v2v"
Now, you can create a TxOut value. For simplicity, assume the output is a simple payment output
of 10 ada, with no datum or reference script attached to it:
let txOut = Api.TxOut
destAddress
(Api.lovelaceToTxOutValue sbe 10_000_000)
Api.TxOutDatumNone
Script.ReferenceScriptNone
Note to set the transaction fee. For example, set it to 2 ada:
let txFee = Api.TxFeeExplicit sbe 2_000_000
Finally, you can create the TxBodyContent by using the defaultTxBodyContent function and
putting everything together:
let txBodyContent = Api.defaultTxBodyContent sbe
& Api.setTxIns [txIn]
& Api.setTxOuts [txOut]
& Api.setTxFee txFee
The txBodyContent can now be used to create a transaction using the old or the new API.
Balancing a transaction
If you have a UTXO with exactly 12 ada, you could just construct the transaction as in the previous section directly, and it would be a valid transaction, but:
- It is probably wasting ADA
- There may not be exactly one UTXO of 12 ada
- The transaciton may not be this simple.
For these reasons, it is recommended that you balance the transaction before proceeding with signing and submitting.
See how to balance a transaction in the Cardano.Api.Tx.Internal.Fee documentation.
Creating a ShelleyWitnessSigningKey
Signing a transaction requires a witness, for example, a ShelleyWitnessSigningKey.
Learn how to create a ShelleyWitnessSigningKey in the Cardano.Api.Tx.Internal.Sign documentation.
Creating a transaction using the old API
Now that you have a TxBodyContent and a ShelleyWitnessSigningKey, you can easily create a transaction using the old API.
First, create a transaction body using the createTransactionBody function and the ShelleyBasedEra witness
defined earlier.
Create the transaction body using the TransactionBodyContent created earlier:
let (Right txBody) = Api.createTransactionBody sbe txBodyContent
Then, sign the transaction using the signShelleyTransaction function and the witness:
let oldApiSignedTx :: Api.Tx Api.ConwayEra = Api.signShelleyTransaction sbe txBody [witness]
We now have a signed transaction. Learn how to submit it to the node by using the IPC protocol in the Cardano.Api.Network.IPC.Internal.
Inspecting transactions
To deconstruct an old-style TxBody into a TxBodyContent, you can also use the
TxBody pattern. Note that this cannot be used for constructing. For that, use ShelleyTxBody
or createTransactionBody, as in the example.
To extract the TxBody and the KeyWitnesses from an old-style Tx, use
the functions getTxBody and getTxWitnesses respectively, from Cardano.Api.
Appendix: Getting Shelley-based era witness from the new API
If you are using the new API, you can also derive the ShelleyBasedEra of it from ConwayEra
from Cardano.Api.Internal.Experimental using the convert function:
let era = Exp.ConwayEra let sbe = Api.convert era
Transaction body
data TxBody era where Source #
Constructors
| ShelleyTxBody | |
Fields
| |
Bundled Patterns
| pattern TxBody :: TxBodyContent ViewTx era -> TxBody era | Deprecated: Use getTxBodyContent $ getTxBody instead |
Instances
| HasTypeProxy era => HasTypeProxy (TxBody era) Source # | |||||
Defined in Cardano.Api.Tx.Internal.Sign Associated Types
| |||||
| IsShelleyBasedEra era => SerialiseAsCBOR (TxBody era) Source # | |||||
Defined in Cardano.Api.Tx.Internal.Sign Methods serialiseToCBOR :: TxBody era -> ByteString Source # deserialiseFromCBOR :: AsType (TxBody era) -> ByteString -> Either DecoderError (TxBody era) Source # | |||||
| IsShelleyBasedEra era => HasTextEnvelope (TxBody era) Source # | |||||
Defined in Cardano.Api.Tx.Internal.Sign Methods textEnvelopeType :: AsType (TxBody era) -> TextEnvelopeType Source # textEnvelopeDefaultDescr :: TxBody era -> TextEnvelopeDescr Source # | |||||
| Show (TxBody era) Source # | |||||
| Eq (TxBody era) Source # | |||||
| data AsType (TxBody era) Source # | |||||
Defined in Cardano.Api.Tx.Internal.Sign | |||||
createTransactionBody :: HasCallStack => ShelleyBasedEra era -> TxBodyContent BuildTx era -> Either TxBodyError (TxBody era) Source #
createAndValidateTransactionBody :: ShelleyBasedEra era -> TxBodyContent BuildTx era -> Either TxBodyError (TxBody era) Source #
Deprecated: Use createTransactionBody instead
data TxBodyContent build era Source #
Constructors
Instances
| IsShelleyBasedEra era => Show (TxBodyContent build era) Source # | |
Defined in Cardano.Api.Tx.Internal.Body | |
| IsShelleyBasedEra era => Eq (TxBodyContent build era) Source # | |
Defined in Cardano.Api.Tx.Internal.Body Methods (==) :: TxBodyContent build era -> TxBodyContent build era -> Bool Source # (/=) :: TxBodyContent build era -> TxBodyContent build era -> Bool Source # | |
Byron only
makeByronTransactionBody :: TxIns BuildTx ByronEra -> [TxOut CtxTx ByronEra] -> Either TxBodyError (Annotated Tx ByteString) Source #
Transaction body builders
defaultTxBodyContent :: ShelleyBasedEra era -> TxBodyContent BuildTx era Source #
defaultTxFee :: ShelleyBasedEra era -> TxFee era Source #
defaultTxValidityUpperBound :: ShelleyBasedEra era -> TxValidityUpperBound era Source #
setTxIns :: TxIns build era -> TxBodyContent build era -> TxBodyContent build era Source #
modTxIns :: (TxIns build era -> TxIns build era) -> TxBodyContent build era -> TxBodyContent build era Source #
addTxIn :: (TxIn, BuildTxWith build (Witness WitCtxTxIn era)) -> TxBodyContent build era -> TxBodyContent build era Source #
addTxIns :: TxIns build era -> TxBodyContent build era -> TxBodyContent build era Source #
setTxInsCollateral :: TxInsCollateral era -> TxBodyContent build era -> TxBodyContent build era Source #
modTxInsCollateral :: (TxInsCollateral era -> TxInsCollateral era) -> TxBodyContent build era -> TxBodyContent build era Source #
addTxInsCollateral :: IsAlonzoBasedEra era => [TxIn] -> TxBodyContent build era -> TxBodyContent build era Source #
addTxInCollateral :: IsAlonzoBasedEra era => TxIn -> TxBodyContent build era -> TxBodyContent build era Source #
setTxInsReference :: TxInsReference build era -> TxBodyContent build era -> TxBodyContent build era Source #
modTxInsReference :: (TxInsReference build era -> TxInsReference build era) -> TxBodyContent build era -> TxBodyContent build era Source #
addTxInsReference :: (Applicative (BuildTxWith build), IsBabbageBasedEra era) => [TxIn] -> Set HashableScriptData -> TxBodyContent build era -> TxBodyContent build era Source #
addTxInReference :: (Applicative (BuildTxWith build), IsBabbageBasedEra era) => TxIn -> Maybe HashableScriptData -> TxBodyContent build era -> TxBodyContent build era Source #
setTxOuts :: [TxOut CtxTx era] -> TxBodyContent build era -> TxBodyContent build era Source #
modTxOuts :: ([TxOut CtxTx era] -> [TxOut CtxTx era]) -> TxBodyContent build era -> TxBodyContent build era Source #
addTxOut :: TxOut CtxTx era -> TxBodyContent build era -> TxBodyContent build era Source #
addTxOuts :: [TxOut CtxTx era] -> TxBodyContent build era -> TxBodyContent build era Source #
setTxTotalCollateral :: TxTotalCollateral era -> TxBodyContent build era -> TxBodyContent build era Source #
modTxTotalCollateral :: (TxTotalCollateral era -> TxTotalCollateral era) -> TxBodyContent build era -> TxBodyContent build era Source #
setTxReturnCollateral :: TxReturnCollateral CtxTx era -> TxBodyContent build era -> TxBodyContent build era Source #
modTxReturnCollateral :: (TxReturnCollateral CtxTx era -> TxReturnCollateral CtxTx era) -> TxBodyContent build era -> TxBodyContent build era Source #
setTxFee :: TxFee era -> TxBodyContent build era -> TxBodyContent build era Source #
modTxFee :: (TxFee era -> TxFee era) -> TxBodyContent build era -> TxBodyContent build era Source #
setTxValidityLowerBound :: TxValidityLowerBound era -> TxBodyContent build era -> TxBodyContent build era Source #
modTxValidityLowerBound :: (TxValidityLowerBound era -> TxValidityLowerBound era) -> TxBodyContent build era -> TxBodyContent build era Source #
setTxValidityUpperBound :: TxValidityUpperBound era -> TxBodyContent build era -> TxBodyContent build era Source #
modTxValidityUpperBound :: (TxValidityUpperBound era -> TxValidityUpperBound era) -> TxBodyContent build era -> TxBodyContent build era Source #
setTxMetadata :: TxMetadataInEra era -> TxBodyContent build era -> TxBodyContent build era Source #
modTxMetadata :: (TxMetadataInEra era -> TxMetadataInEra era) -> TxBodyContent build era -> TxBodyContent build era Source #
setTxAuxScripts :: TxAuxScripts era -> TxBodyContent build era -> TxBodyContent build era Source #
modTxAuxScripts :: (TxAuxScripts era -> TxAuxScripts era) -> TxBodyContent build era -> TxBodyContent build era Source #
setTxExtraKeyWits :: TxExtraKeyWitnesses era -> TxBodyContent build era -> TxBodyContent build era Source #
modTxExtraKeyWits :: (TxExtraKeyWitnesses era -> TxExtraKeyWitnesses era) -> TxBodyContent build era -> TxBodyContent build era Source #
addTxExtraKeyWits :: IsAlonzoBasedEra era => [Hash PaymentKey] -> TxBodyContent build era -> TxBodyContent build era Source #
setTxProtocolParams :: BuildTxWith build (Maybe (LedgerProtocolParameters era)) -> TxBodyContent build era -> TxBodyContent build era Source #
setTxWithdrawals :: TxWithdrawals build era -> TxBodyContent build era -> TxBodyContent build era Source #
modTxWithdrawals :: (TxWithdrawals build era -> TxWithdrawals build era) -> TxBodyContent build era -> TxBodyContent build era Source #
setTxCertificates :: TxCertificates build era -> TxBodyContent build era -> TxBodyContent build era Source #
modTxCertificates :: (TxCertificates build era -> TxCertificates build era) -> TxBodyContent build era -> TxBodyContent build era Source #
setTxUpdateProposal :: TxUpdateProposal era -> TxBodyContent build era -> TxBodyContent build era Source #
modTxUpdateProposal :: (TxUpdateProposal era -> TxUpdateProposal era) -> TxBodyContent build era -> TxBodyContent build era Source #
setTxProposalProcedures :: Maybe (Featured ConwayEraOnwards era (TxProposalProcedures build era)) -> TxBodyContent build era -> TxBodyContent build era Source #
setTxVotingProcedures :: Maybe (Featured ConwayEraOnwards era (TxVotingProcedures build era)) -> TxBodyContent build era -> TxBodyContent build era Source #
setTxMintValue :: TxMintValue build era -> TxBodyContent build era -> TxBodyContent build era Source #
modTxMintValue :: (TxMintValue build era -> TxMintValue build era) -> TxBodyContent build era -> TxBodyContent build era Source #
addTxMintValue :: IsMaryBasedEra era => Map PolicyId (PolicyAssets, BuildTxWith build (ScriptWitness WitCtxMint era)) -> TxBodyContent build era -> TxBodyContent build era Source #
subtractTxMintValue :: IsMaryBasedEra era => Map PolicyId (PolicyAssets, BuildTxWith build (ScriptWitness WitCtxMint era)) -> TxBodyContent build era -> TxBodyContent build era Source #
Adds the negation of the provided assets and quantities to the txMintValue field of the TxBodyContent.
setTxScriptValidity :: TxScriptValidity era -> TxBodyContent build era -> TxBodyContent build era Source #
modTxScriptValidity :: (TxScriptValidity era -> TxScriptValidity era) -> TxBodyContent build era -> TxBodyContent build era Source #
setTxCurrentTreasuryValue :: Maybe (Featured ConwayEraOnwards era (Maybe Coin)) -> TxBodyContent build era -> TxBodyContent build era Source #
setTxTreasuryDonation :: Maybe (Featured ConwayEraOnwards era Coin) -> TxBodyContent build era -> TxBodyContent build era Source #
data TxBodyError Source #
Constructors
Instances
| Error TxBodyError Source # | |
Defined in Cardano.Api.Tx.Internal.Body Methods prettyError :: TxBodyError -> Doc ann Source # | |
| Show TxBodyError Source # | |
Defined in Cardano.Api.Tx.Internal.Body | |
| Eq TxBodyError Source # | |
Defined in Cardano.Api.Tx.Internal.Body Methods (==) :: TxBodyError -> TxBodyError -> Bool Source # (/=) :: TxBodyError -> TxBodyError -> Bool Source # | |
data TxOutputError Source #
Constructors
| TxOutputNegative !Quantity !TxOutInAnyEra | |
| TxOutputOverflow !Quantity !TxOutInAnyEra |
Instances
| Error TxOutputError Source # | |
Defined in Cardano.Api.Tx.Internal.Output Methods prettyError :: TxOutputError -> Doc ann Source # | |
| Show TxOutputError Source # | |
Defined in Cardano.Api.Tx.Internal.Output | |
| Eq TxOutputError Source # | |
Defined in Cardano.Api.Tx.Internal.Output Methods (==) :: TxOutputError -> TxOutputError -> Bool Source # (/=) :: TxOutputError -> TxOutputError -> Bool Source # | |
data TxBodyScriptData era where Source #
Constructors
| TxBodyNoScriptData :: forall era. TxBodyScriptData era | |
| TxBodyScriptData :: forall era. AlonzoEraOnwardsConstraints era => AlonzoEraOnwards era -> TxDats (ShelleyLedgerEra era) -> Redeemers (ShelleyLedgerEra era) -> TxBodyScriptData era |
Instances
| Show (TxBodyScriptData era) Source # | |
Defined in Cardano.Api.Tx.Internal.Sign | |
| Eq (TxBodyScriptData era) Source # | |
Defined in Cardano.Api.Tx.Internal.Sign Methods (==) :: TxBodyScriptData era -> TxBodyScriptData era -> Bool Source # (/=) :: TxBodyScriptData era -> TxBodyScriptData era -> Bool Source # | |
selectTxDatums :: TxBodyScriptData era -> Map DataHash (Data (ShelleyLedgerEra era)) Source #
data TxScriptValidity era where Source #
A representation of whether the era supports tx script validity.
The Alonzo and subsequent eras support script validity.
Constructors
| TxScriptValidityNone :: forall era. TxScriptValidity era | |
| TxScriptValidity :: forall era. AlonzoEraOnwards era -> ScriptValidity -> TxScriptValidity era | Tx script validity is supported in transactions in the |
Instances
| Show (TxScriptValidity era) Source # | |
Defined in Cardano.Api.Tx.Internal.Sign | |
| Eq (TxScriptValidity era) Source # | |
Defined in Cardano.Api.Tx.Internal.Sign Methods (==) :: TxScriptValidity era -> TxScriptValidity era -> Bool Source # (/=) :: TxScriptValidity era -> TxScriptValidity era -> Bool Source # | |
data ScriptValidity Source #
Indicates whether a script is expected to fail or pass validation.
Constructors
| ScriptInvalid | Script is expected to fail validation. Transactions marked as such can include scripts that fail validation. Such transactions may be submitted to the chain, in which case the collateral will be taken upon on chain script validation failure. |
| ScriptValid | Script is expected to pass validation. Transactions marked as such cannot include scripts that fail validation. |
Instances
| DecCBOR ScriptValidity Source # | |
Defined in Cardano.Api.Tx.Internal.Sign | |
| EncCBOR ScriptValidity Source # | |
Defined in Cardano.Api.Tx.Internal.Sign Methods encCBOR :: ScriptValidity -> Encoding Source # encodedSizeExpr :: (forall t. EncCBOR t => Proxy t -> Size) -> Proxy ScriptValidity -> Size Source # encodedListSizeExpr :: (forall t. EncCBOR t => Proxy t -> Size) -> Proxy [ScriptValidity] -> Size Source # | |
| Show ScriptValidity Source # | |
Defined in Cardano.Api.Tx.Internal.Sign | |
| Eq ScriptValidity Source # | |
Defined in Cardano.Api.Tx.Internal.Sign Methods (==) :: ScriptValidity -> ScriptValidity -> Bool Source # (/=) :: ScriptValidity -> ScriptValidity -> Bool Source # | |
txScriptValidityToIsValid :: TxScriptValidity era -> IsValid Source #
Instances
| IsShelleyBasedEra era => FromJSON (UTxO era) Source # | |
Defined in Cardano.Api.UTxO Methods parseJSON :: Value -> Parser (UTxO era) # parseJSONList :: Value -> Parser [UTxO era] # omittedField :: Maybe (UTxO era) # | |
| IsCardanoEra era => ToJSON (UTxO era) Source # | |
Defined in Cardano.Api.UTxO | |
| Monoid (UTxO era) Source # | |
| Semigroup (UTxO era) Source # | |
| IsList (UTxO era) Source # | |
Defined in Cardano.Api.UTxO | |
| Show (UTxO era) Source # | |
| Eq (UTxO era) Source # | |
| MonoFoldable (UTxO era) Source # | |
Defined in Cardano.Api.UTxO Methods ofoldMap :: Monoid m => (Element (UTxO era) -> m) -> UTxO era -> m ofoldr :: (Element (UTxO era) -> b -> b) -> b -> UTxO era -> b ofoldl' :: (a -> Element (UTxO era) -> a) -> a -> UTxO era -> a otoList :: UTxO era -> [Element (UTxO era)] oall :: (Element (UTxO era) -> Bool) -> UTxO era -> Bool oany :: (Element (UTxO era) -> Bool) -> UTxO era -> Bool olength64 :: UTxO era -> Int64 ocompareLength :: Integral i => UTxO era -> i -> Ordering otraverse_ :: Applicative f => (Element (UTxO era) -> f b) -> UTxO era -> f () ofor_ :: Applicative f => UTxO era -> (Element (UTxO era) -> f b) -> f () omapM_ :: Applicative m => (Element (UTxO era) -> m ()) -> UTxO era -> m () oforM_ :: Applicative m => UTxO era -> (Element (UTxO era) -> m ()) -> m () ofoldlM :: Monad m => (a -> Element (UTxO era) -> m a) -> a -> UTxO era -> m a ofoldMap1Ex :: Semigroup m => (Element (UTxO era) -> m) -> UTxO era -> m ofoldr1Ex :: (Element (UTxO era) -> Element (UTxO era) -> Element (UTxO era)) -> UTxO era -> Element (UTxO era) ofoldl1Ex' :: (Element (UTxO era) -> Element (UTxO era) -> Element (UTxO era)) -> UTxO era -> Element (UTxO era) headEx :: UTxO era -> Element (UTxO era) lastEx :: UTxO era -> Element (UTxO era) unsafeHead :: UTxO era -> Element (UTxO era) unsafeLast :: UTxO era -> Element (UTxO era) maximumByEx :: (Element (UTxO era) -> Element (UTxO era) -> Ordering) -> UTxO era -> Element (UTxO era) minimumByEx :: (Element (UTxO era) -> Element (UTxO era) -> Ordering) -> UTxO era -> Element (UTxO era) | |
| MonoFunctor (UTxO era) Source # | |
| MonoTraversable (UTxO era) Source # | |
Defined in Cardano.Api.UTxO | |
| type Item (UTxO era) Source # | |
| type Element (UTxO era) Source # | |
Defined in Cardano.Api.UTxO | |
Transaction Ids
Constructors
| TxId (Hash HASH EraIndependentTxBody) |
Instances
| FromJSON TxId Source # | |
Defined in Cardano.Api.Tx.Internal.TxIn Methods parseJSON :: Value -> Parser TxId # parseJSONList :: Value -> Parser [TxId] # omittedField :: Maybe TxId # | |
| FromJSONKey TxId Source # | |
Defined in Cardano.Api.Tx.Internal.TxIn | |
| ToJSON TxId Source # | |
Defined in Cardano.Api.Tx.Internal.TxIn | |
| ToJSONKey TxId Source # | |
Defined in Cardano.Api.Tx.Internal.TxIn | |
| HasTypeProxy TxId Source # | |
Defined in Cardano.Api.Tx.Internal.TxIn | |
| SerialiseAsRawBytes TxId Source # | |
Defined in Cardano.Api.Tx.Internal.TxIn Methods serialiseToRawBytes :: TxId -> ByteString Source # deserialiseFromRawBytes :: AsType TxId -> ByteString -> Either SerialiseAsRawBytesError TxId Source # | |
| Show TxId Source # | |
| Eq TxId Source # | |
| Ord TxId Source # | |
Defined in Cardano.Api.Tx.Internal.TxIn | |
| Pretty TxId Source # | |
Defined in Cardano.Api.Tx.Internal.TxIn | |
| data AsType TxId Source # | |
Defined in Cardano.Api.Tx.Internal.TxIn | |
getTxIdByron :: ATxAux ByteString -> TxId Source #
getTxIdShelley :: EraTxBody (ShelleyLedgerEra era) => ShelleyBasedEra era -> TxBody (ShelleyLedgerEra era) -> TxId Source #
Transaction inputs
Instances
| FromJSON TxIn Source # | |
Defined in Cardano.Api.Tx.Internal.TxIn Methods parseJSON :: Value -> Parser TxIn # parseJSONList :: Value -> Parser [TxIn] # omittedField :: Maybe TxIn # | |
| FromJSONKey TxIn Source # | |
Defined in Cardano.Api.Tx.Internal.TxIn | |
| ToJSON TxIn Source # | |
Defined in Cardano.Api.Tx.Internal.TxIn | |
| ToJSONKey TxIn Source # | |
Defined in Cardano.Api.Tx.Internal.TxIn | |
| Show TxIn Source # | |
| Eq TxIn Source # | |
| Ord TxIn Source # | |
Defined in Cardano.Api.Tx.Internal.TxIn | |
| Pretty TxIn Source # | |
Defined in Cardano.Api.Tx.Internal.TxIn | |
type TxIns build era = [(TxIn, BuildTxWith build (Witness WitCtxTxIn era))] Source #
indexTxIns :: TxIns BuildTx era -> [(ScriptWitnessIndex, TxIn, Witness WitCtxTxIn era)] Source #
Index transaction inputs ordered by TxIn
Please note that the result can contain also KeyWitnesses.
See section 4.1 of https://github.com/intersectmbo/cardano-ledger/releases/latest/download/alonzo-ledger.pdf
Instances
| FromJSON TxIx Source # | |
Defined in Cardano.Api.Tx.Internal.TxIn Methods parseJSON :: Value -> Parser TxIx # parseJSONList :: Value -> Parser [TxIx] # omittedField :: Maybe TxIx # | |
| ToJSON TxIx Source # | |
Defined in Cardano.Api.Tx.Internal.TxIn | |
| Enum TxIx Source # | |
| Show TxIx Source # | |
| Eq TxIx Source # | |
| Ord TxIx Source # | |
Defined in Cardano.Api.Tx.Internal.TxIn | |
| Pretty TxIx Source # | |
Defined in Cardano.Api.Tx.Internal.TxIn | |
genesisUTxOPseudoTxIn :: NetworkId -> Hash GenesisUTxOKey -> TxIn Source #
Compute the TxIn of the initial UTxO pseudo-transaction corresponding
to the given address in the genesis initial funds.
The Shelley initial UTxO is constructed from the sgInitialFunds which
is not a full UTxO but just a map from addresses to coin values.
This gets turned into a UTxO by making a pseudo-transaction for each address,
with the 0th output being the coin value. So to spend from the initial UTxO
we need this same TxIn to use as an input to the spending transaction.
getReferenceInputsSizeForTxIds :: ShelleyLedgerEra era ~ ledgerera => BabbageEraOnwards era -> UTxO ledgerera -> Set TxIn -> Int Source #
Calculate the reference inputs size in bytes for provided set of transaction IDs and UTXOs.
Transaction outputs
The context is a transaction body
Instances
| IsShelleyBasedEra era => FromJSON (TxOut CtxTx era) Source # | |
Defined in Cardano.Api.Tx.Internal.Output | |
The context is the UTxO
Instances
| IsShelleyBasedEra era => FromJSON (TxOut CtxUTxO era) Source # | |
Defined in Cardano.Api.Tx.Internal.Output | |
Constructors
| TxOut (AddressInEra era) (TxOutValue era) (TxOutDatum ctx era) (ReferenceScript era) |
Instances
| IsShelleyBasedEra era => FromJSON (TxOut CtxTx era) Source # | |||||
Defined in Cardano.Api.Tx.Internal.Output | |||||
| IsShelleyBasedEra era => FromJSON (TxOut CtxUTxO era) Source # | |||||
Defined in Cardano.Api.Tx.Internal.Output | |||||
| IsCardanoEra era => ToJSON (TxOut ctx era) Source # | |||||
Defined in Cardano.Api.Tx.Internal.Output | |||||
| (Typeable ctx, IsShelleyBasedEra era) => HasTypeProxy (TxOut ctx era) Source # | |||||
Defined in Cardano.Api.Tx.Internal.Output Associated Types
| |||||
| (Typeable ctx, IsShelleyBasedEra era) => FromCBOR (TxOut ctx era) Source # | We do not provide a | ||||
| Show (TxOut ctx era) Source # | |||||
| Eq (TxOut ctx era) Source # | |||||
| data AsType (TxOut ctx era) Source # | |||||
Defined in Cardano.Api.Tx.Internal.Output | |||||
data TxOutValue era where Source #
Constructors
| TxOutValueByron :: Coin -> TxOutValue ByronEra | |
| TxOutValueShelleyBased :: forall era. (Eq (Value (ShelleyLedgerEra era)), Show (Value (ShelleyLedgerEra era))) => ShelleyBasedEra era -> Value (ShelleyLedgerEra era) -> TxOutValue era |
Instances
| IsShelleyBasedEra era => FromJSON (TxOutValue era) Source # | |
Defined in Cardano.Api.Tx.Internal.Output Methods parseJSON :: Value -> Parser (TxOutValue era) # parseJSONList :: Value -> Parser [TxOutValue era] # omittedField :: Maybe (TxOutValue era) # | |
| IsCardanoEra era => ToJSON (TxOutValue era) Source # | |
Defined in Cardano.Api.Tx.Internal.Output Methods toJSON :: TxOutValue era -> Value # toEncoding :: TxOutValue era -> Encoding # toJSONList :: [TxOutValue era] -> Value # toEncodingList :: [TxOutValue era] -> Encoding # omitField :: TxOutValue era -> Bool # | |
| Show (TxOutValue era) Source # | |
Defined in Cardano.Api.Tx.Internal.Output | |
| Eq (TxOutValue era) Source # | |
Defined in Cardano.Api.Tx.Internal.Output Methods (==) :: TxOutValue era -> TxOutValue era -> Bool Source # (/=) :: TxOutValue era -> TxOutValue era -> Bool Source # | |
data TxOutDatum ctx era where Source #
Constructors
| TxOutDatumNone :: forall ctx era. TxOutDatum ctx era | |
| TxOutDatumHash :: forall era ctx. AlonzoEraOnwards era -> Hash ScriptData -> TxOutDatum ctx era | A transaction output that only specifies the hash of the datum, but not the full datum value. |
| TxOutSupplementalDatum :: forall era. AlonzoEraOnwards era -> HashableScriptData -> TxOutDatum CtxTx era | A transaction output that specifies the whole datum value. This can only be used in the context of the transaction body (i.e this is a supplemental datum), and does not occur in the UTxO. The UTxO only contains the datum hash. |
| TxOutDatumInline :: forall era ctx. BabbageEraOnwards era -> HashableScriptData -> TxOutDatum ctx 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. |
Instances
| Show (TxOutDatum ctx era) Source # | |
Defined in Cardano.Api.Tx.Internal.Output | |
| Eq (TxOutDatum ctx era) Source # | |
Defined in Cardano.Api.Tx.Internal.Output Methods (==) :: TxOutDatum ctx era -> TxOutDatum ctx era -> Bool Source # (/=) :: TxOutDatum ctx era -> TxOutDatum ctx era -> Bool Source # | |
lovelaceToTxOutValue :: ShelleyBasedEra era -> Coin -> TxOutValue era Source #
txOutValueToLovelace :: TxOutValue era -> Coin Source #
txOutValueToValue :: TxOutValue era -> Value Source #
data TxOutInAnyEra where Source #
Constructors
| TxOutInAnyEra :: forall era. CardanoEra era -> TxOut CtxTx era -> TxOutInAnyEra |
Instances
| Show TxOutInAnyEra Source # | |
Defined in Cardano.Api.Tx.Internal.Output | |
| Eq TxOutInAnyEra Source # | |
Defined in Cardano.Api.Tx.Internal.Output Methods (==) :: TxOutInAnyEra -> TxOutInAnyEra -> Bool Source # (/=) :: TxOutInAnyEra -> TxOutInAnyEra -> Bool Source # | |
| Pretty TxOutInAnyEra Source # | |
Defined in Cardano.Api.Tx.Internal.Output | |
txOutInAnyEra :: CardanoEra era -> TxOut CtxTx era -> TxOutInAnyEra Source #
Convenience constructor for TxOutInAnyEra
Other transaction body types
data TxInsCollateral era where Source #
Constructors
| TxInsCollateralNone :: forall era. TxInsCollateral era | |
| TxInsCollateral :: forall era. AlonzoEraOnwards era -> [TxIn] -> TxInsCollateral era |
Instances
| Show (TxInsCollateral era) Source # | |
Defined in Cardano.Api.Tx.Internal.Body | |
| Eq (TxInsCollateral era) Source # | |
Defined in Cardano.Api.Tx.Internal.Body Methods (==) :: TxInsCollateral era -> TxInsCollateral era -> Bool Source # (/=) :: TxInsCollateral era -> TxInsCollateral era -> Bool Source # | |
data TxInsReference build era where Source #
Transaction reference inputs. Those are not spent and do not require any witnessing to be included in a valid
transaction. Any output can be a reference input. Reference inputs only affect the information that is passed to
scripts by being included in TxInfo.
The third parameter of the TxInsReference constructor stores actual resolved datums. When any outputs of referenced
TxIns store only datum hash, the only way to use them in the plutus script is to provide a resolved datum here.
Note that inserting a datum with hash not present in the reference inputs will result in an error on transaction
submission.
See also: https://github.com/intersectmbo/cardano-ledger/releases/latest/download/babbage-ledger.pdf, chapter 3.
Constructors
| TxInsReferenceNone :: forall build era. TxInsReference build era | |
| TxInsReference | |
Fields
| |
Instances
| Show (TxInsReference build era) Source # | |
Defined in Cardano.Api.Tx.Internal.Body | |
| Eq (TxInsReference build era) Source # | |
Defined in Cardano.Api.Tx.Internal.Body Methods (==) :: TxInsReference build era -> TxInsReference build era -> Bool Source # (/=) :: TxInsReference build era -> TxInsReference build era -> Bool Source # | |
type TxInsReferenceDatums build = BuildTxWith build (Set HashableScriptData) Source #
The public key inputs' resolved datums, referenced by hash in the transaction reference inputs.
getReferenceInputDatumMap :: TxInsReferenceDatums build -> Map (Hash ScriptData) HashableScriptData Source #
data TxReturnCollateral ctx era where Source #
Constructors
| TxReturnCollateralNone :: forall ctx era. TxReturnCollateral ctx era | |
| TxReturnCollateral :: forall era ctx. BabbageEraOnwards era -> TxOut ctx era -> TxReturnCollateral ctx era |
Instances
| Show (TxReturnCollateral ctx era) Source # | |
Defined in Cardano.Api.Tx.Internal.Body | |
| Eq (TxReturnCollateral ctx era) Source # | |
Defined in Cardano.Api.Tx.Internal.Body Methods (==) :: TxReturnCollateral ctx era -> TxReturnCollateral ctx era -> Bool Source # (/=) :: TxReturnCollateral ctx era -> TxReturnCollateral ctx era -> Bool Source # | |
data TxTotalCollateral era where Source #
Constructors
| TxTotalCollateralNone :: forall era. TxTotalCollateral era | |
| TxTotalCollateral :: forall era. BabbageEraOnwards era -> Coin -> TxTotalCollateral era |
Instances
| Show (TxTotalCollateral era) Source # | |
Defined in Cardano.Api.Tx.Internal.Body | |
| Eq (TxTotalCollateral era) Source # | |
Defined in Cardano.Api.Tx.Internal.Body Methods (==) :: TxTotalCollateral era -> TxTotalCollateral era -> Bool Source # (/=) :: TxTotalCollateral era -> TxTotalCollateral era -> Bool Source # | |
Constructors
| TxFeeExplicit :: forall era. ShelleyBasedEra era -> Coin -> TxFee era |
data TxValidityLowerBound era where Source #
Constructors
| TxValidityNoLowerBound :: forall era. TxValidityLowerBound era | |
| TxValidityLowerBound :: forall era. AllegraEraOnwards era -> SlotNo -> TxValidityLowerBound era |
Instances
| Show (TxValidityLowerBound era) Source # | |
Defined in Cardano.Api.Tx.Internal.Body | |
| Eq (TxValidityLowerBound era) Source # | |
Defined in Cardano.Api.Tx.Internal.Body Methods (==) :: TxValidityLowerBound era -> TxValidityLowerBound era -> Bool Source # (/=) :: TxValidityLowerBound era -> TxValidityLowerBound era -> Bool Source # | |
data TxValidityUpperBound era where Source #
This was formerly known as the TTL.
Constructors
| TxValidityUpperBound :: forall era. ShelleyBasedEra era -> Maybe SlotNo -> TxValidityUpperBound era |
Instances
| Show (TxValidityUpperBound era) Source # | |
Defined in Cardano.Api.Tx.Internal.Body | |
| Eq (TxValidityUpperBound era) Source # | |
Defined in Cardano.Api.Tx.Internal.Body Methods (==) :: TxValidityUpperBound era -> TxValidityUpperBound era -> Bool Source # (/=) :: TxValidityUpperBound era -> TxValidityUpperBound era -> Bool Source # | |
data TxMetadataInEra era where Source #
Constructors
| TxMetadataNone :: forall era. TxMetadataInEra era | |
| TxMetadataInEra :: forall era. ShelleyBasedEra era -> TxMetadata -> TxMetadataInEra era |
Instances
| Show (TxMetadataInEra era) Source # | |
Defined in Cardano.Api.Tx.Internal.Body | |
| Eq (TxMetadataInEra era) Source # | |
Defined in Cardano.Api.Tx.Internal.Body Methods (==) :: TxMetadataInEra era -> TxMetadataInEra era -> Bool Source # (/=) :: TxMetadataInEra era -> TxMetadataInEra era -> Bool Source # | |
data TxAuxScripts era where Source #
Constructors
| TxAuxScriptsNone :: forall era. TxAuxScripts era | |
| TxAuxScripts :: forall era. AllegraEraOnwards era -> [ScriptInEra era] -> TxAuxScripts era |
Instances
| Show (TxAuxScripts era) Source # | |
Defined in Cardano.Api.Tx.Internal.Body | |
| Eq (TxAuxScripts era) Source # | |
Defined in Cardano.Api.Tx.Internal.Body Methods (==) :: TxAuxScripts era -> TxAuxScripts era -> Bool Source # (/=) :: TxAuxScripts era -> TxAuxScripts era -> Bool Source # | |
data TxExtraKeyWitnesses era where Source #
Constructors
| TxExtraKeyWitnessesNone :: forall era. TxExtraKeyWitnesses era | |
| TxExtraKeyWitnesses :: forall era. AlonzoEraOnwards era -> [Hash PaymentKey] -> TxExtraKeyWitnesses era |
Instances
| Show (TxExtraKeyWitnesses era) Source # | |
Defined in Cardano.Api.Tx.Internal.Body | |
| Eq (TxExtraKeyWitnesses era) Source # | |
Defined in Cardano.Api.Tx.Internal.Body Methods (==) :: TxExtraKeyWitnesses era -> TxExtraKeyWitnesses era -> Bool Source # (/=) :: TxExtraKeyWitnesses era -> TxExtraKeyWitnesses era -> Bool Source # | |
data TxWithdrawals build era where Source #
Constructors
| TxWithdrawalsNone :: forall build era. TxWithdrawals build era | |
| TxWithdrawals :: forall era build. ShelleyBasedEra era -> [(StakeAddress, Coin, BuildTxWith build (Witness WitCtxStake era))] -> TxWithdrawals build era |
Instances
| Show (TxWithdrawals build era) Source # | |
Defined in Cardano.Api.Tx.Internal.Body | |
| Eq (TxWithdrawals build era) Source # | |
Defined in Cardano.Api.Tx.Internal.Body Methods (==) :: TxWithdrawals build era -> TxWithdrawals build era -> Bool Source # (/=) :: TxWithdrawals build era -> TxWithdrawals build era -> Bool Source # | |
indexTxWithdrawals :: TxWithdrawals BuildTx era -> [(ScriptWitnessIndex, StakeAddress, Coin, Witness WitCtxStake era)] Source #
Index the withdrawals with witnesses in the order of stake addresses. See section 4.1 of https://github.com/intersectmbo/cardano-ledger/releases/latest/download/alonzo-ledger.pdf
data TxCertificates build era where Source #
Constructors
| TxCertificatesNone :: forall build era. TxCertificates build era | No certificates |
| TxCertificates :: forall era build. ShelleyBasedEra era -> OMap (Certificate (ShelleyLedgerEra era)) (BuildTxWith build (Maybe (StakeCredential, Witness WitCtxStake era))) -> TxCertificates build era | Represents certificates present in transaction. Prefer using |
Instances
| Show (TxCertificates build era) Source # | |
Defined in Cardano.Api.Tx.Internal.Body | |
| Eq (TxCertificates build era) Source # | |
Defined in Cardano.Api.Tx.Internal.Body Methods (==) :: TxCertificates build era -> TxCertificates build era -> Bool Source # (/=) :: TxCertificates build era -> TxCertificates build era -> Bool Source # | |
mkTxCertificates :: forall era build. Applicative (BuildTxWith build) => ShelleyBasedEra era -> [(Certificate (ShelleyLedgerEra era), Maybe (ScriptWitness WitCtxStake era))] -> TxCertificates build era Source #
Create TxCertificates. Note that 'Certificate era' will be deduplicated. Only Certificates with a
stake credential will be in the result.
Note that, when building a transaction in Conway era, a witness is not required for staking credential registration, but this is only the case during the transitional period of Conway era and only for staking credential registration certificates without a deposit. Future eras will require a witness for registration certificates, because the one without a deposit will be removed.
indexTxCertificates :: TxCertificates BuildTx era -> [(ScriptWitnessIndex, Certificate (ShelleyLedgerEra era), StakeCredential, Witness WitCtxStake era)] Source #
Index certificates with witnesses by the order they appear in the list (in the transaction). See section 4.1 of https://github.com/intersectmbo/cardano-ledger/releases/latest/download/alonzo-ledger.pdf
data TxUpdateProposal era where Source #
Constructors
| TxUpdateProposalNone :: forall era. TxUpdateProposal era | |
| TxUpdateProposal :: forall era. ShelleyToBabbageEra era -> UpdateProposal -> TxUpdateProposal era |
Instances
| Show (TxUpdateProposal era) Source # | |
Defined in Cardano.Api.Tx.Internal.Body | |
| Eq (TxUpdateProposal era) Source # | |
Defined in Cardano.Api.Tx.Internal.Body Methods (==) :: TxUpdateProposal era -> TxUpdateProposal era -> Bool Source # (/=) :: TxUpdateProposal era -> TxUpdateProposal era -> Bool Source # | |
data TxMintValue build era where Source #
Constructors
| TxMintNone :: forall build era. TxMintValue build era | |
| TxMintValue :: forall era build. MaryEraOnwards era -> Map PolicyId (PolicyAssets, BuildTxWith build (ScriptWitness WitCtxMint era)) -> TxMintValue build era |
Instances
| Monoid (TxMintValue build era) Source # | |
Defined in Cardano.Api.Tx.Internal.Body Methods mempty :: TxMintValue build era Source # mappend :: TxMintValue build era -> TxMintValue build era -> TxMintValue build era Source # mconcat :: [TxMintValue build era] -> TxMintValue build era Source # | |
| Semigroup (TxMintValue build era) Source # | |
Defined in Cardano.Api.Tx.Internal.Body Methods (<>) :: TxMintValue build era -> TxMintValue build era -> TxMintValue build era Source # sconcat :: NonEmpty (TxMintValue build era) -> TxMintValue build era Source # stimes :: Integral b => b -> TxMintValue build era -> TxMintValue build era Source # | |
| Show (TxMintValue build era) Source # | |
Defined in Cardano.Api.Tx.Internal.Body | |
| Eq (TxMintValue build era) Source # | |
Defined in Cardano.Api.Tx.Internal.Body Methods (==) :: TxMintValue build era -> TxMintValue build era -> Bool Source # (/=) :: TxMintValue build era -> TxMintValue build era -> Bool Source # | |
mkTxMintValue :: MaryEraOnwards era -> [(PolicyId, PolicyAssets, BuildTxWith build (ScriptWitness WitCtxMint era))] -> TxMintValue build era Source #
A helper function for building TxMintValue with present witnesses. Only the first witness
in the argument will be used for each policy id.
txMintValueToValue :: TxMintValue build era -> Value Source #
Convert TxMintValue to a more handy Value.
indexTxMintValue :: TxMintValue build era -> [(ScriptWitnessIndex, PolicyId, PolicyAssets, BuildTxWith build (ScriptWitness WitCtxMint era))] Source #
Index the assets with witnesses in the order of policy ids. See section 4.1 of https://github.com/intersectmbo/cardano-ledger/releases/latest/download/alonzo-ledger.pdf
data TxVotingProcedures build era where Source #
Constructors
| TxVotingProceduresNone :: forall build era. TxVotingProcedures build era | |
| TxVotingProcedures :: forall era build. VotingProcedures (ShelleyLedgerEra era) -> BuildTxWith build (Map Voter (ScriptWitness WitCtxStake era)) -> TxVotingProcedures build era |
Instances
| Show (TxVotingProcedures build era) Source # | |
Defined in Cardano.Api.Tx.Internal.Body | |
| Eq (TxVotingProcedures build era) Source # | |
Defined in Cardano.Api.Tx.Internal.Body Methods (==) :: TxVotingProcedures build era -> TxVotingProcedures build era -> Bool Source # (/=) :: TxVotingProcedures build era -> TxVotingProcedures build era -> Bool Source # | |
mkTxVotingProcedures :: Applicative (BuildTxWith build) => [(VotingProcedures era, Maybe (ScriptWitness WitCtxStake era))] -> Either (VotesMergingConflict era) (TxVotingProcedures build era) Source #
Create voting procedures from map of voting procedures and optional witnesses.
Validates the function argument, to make sure the list of votes is legal.
See mergeVotingProcedures for validation rules.
indexTxVotingProcedures :: TxVotingProcedures BuildTx era -> [(ScriptWitnessIndex, Voter, ScriptWitness WitCtxStake era)] Source #
Index voting procedures by the order of the votes (Ord).
data TxProposalProcedures build era where Source #
Constructors
| TxProposalProceduresNone :: forall build era. TxProposalProcedures build era | No proposals in transaction.. |
| TxProposalProcedures :: forall era build. EraPParams (ShelleyLedgerEra era) => OMap (ProposalProcedure (ShelleyLedgerEra era)) (BuildTxWith build (Maybe (ScriptWitness WitCtxStake era))) -> TxProposalProcedures build era | Represents proposal procedures present in transaction. |
Instances
| Show (TxProposalProcedures build era) Source # | |
Defined in Cardano.Api.Tx.Internal.Body | |
| Eq (TxProposalProcedures build era) Source # | |
Defined in Cardano.Api.Tx.Internal.Body Methods (==) :: TxProposalProcedures build era -> TxProposalProcedures build era -> Bool Source # (/=) :: TxProposalProcedures build era -> TxProposalProcedures build era -> Bool Source # | |
mkTxProposalProcedures :: forall era build. (Applicative (BuildTxWith build), IsShelleyBasedEra era) => [(ProposalProcedure (ShelleyLedgerEra era), Maybe (ScriptWitness WitCtxStake era))] -> TxProposalProcedures build era Source #
A smart constructor for TxProposalProcedures. It makes sure that the value produced is consistent - the
witnessed proposals are also present in the first constructor parameter.
indexTxProposalProcedures :: TxProposalProcedures BuildTx era -> [(ScriptWitnessIndex, ProposalProcedure (ShelleyLedgerEra era), ScriptWitness WitCtxStake era)] Source #
Index proposal procedures by their order (Ord).
| and filter out the ones that do not have a witness.
indexWitnessedTxProposalProcedures :: TxProposalProcedures BuildTx era -> [(ProposalProcedure (ShelleyLedgerEra era), Maybe (ScriptWitnessIndex, ScriptWitness WitCtxStake era))] Source #
Index proposal procedures by their order (Ord).
convProposalProcedures :: TxProposalProcedures build era -> OSet (ProposalProcedure (ShelleyLedgerEra era)) Source #
Returns an OSet of proposals from TxProposalProcedures.
Building vs viewing transactions
data BuildTxWith build a where Source #
Constructors
| ViewTx :: forall a. BuildTxWith ViewTx a | |
| BuildTxWith :: forall a. a -> BuildTxWith BuildTx a |
Instances
Instances
| Applicative (BuildTxWith BuildTx) Source # | |
Defined in Cardano.Api.Tx.Internal.BuildTxWith Methods pure :: a -> BuildTxWith BuildTx a Source # (<*>) :: BuildTxWith BuildTx (a -> b) -> BuildTxWith BuildTx a -> BuildTxWith BuildTx b Source # liftA2 :: (a -> b -> c) -> BuildTxWith BuildTx a -> BuildTxWith BuildTx b -> BuildTxWith BuildTx c Source # (*>) :: BuildTxWith BuildTx a -> BuildTxWith BuildTx b -> BuildTxWith BuildTx b Source # (<*) :: BuildTxWith BuildTx a -> BuildTxWith BuildTx b -> BuildTxWith BuildTx a Source # | |
Instances
| Applicative (BuildTxWith ViewTx) Source # | |
Defined in Cardano.Api.Tx.Internal.BuildTxWith Methods pure :: a -> BuildTxWith ViewTx a Source # (<*>) :: BuildTxWith ViewTx (a -> b) -> BuildTxWith ViewTx a -> BuildTxWith ViewTx b Source # liftA2 :: (a -> b -> c) -> BuildTxWith ViewTx a -> BuildTxWith ViewTx b -> BuildTxWith ViewTx c Source # (*>) :: BuildTxWith ViewTx a -> BuildTxWith ViewTx b -> BuildTxWith ViewTx b Source # (<*) :: BuildTxWith ViewTx a -> BuildTxWith ViewTx b -> BuildTxWith ViewTx a Source # | |
buildTxWithToMaybe :: BuildTxWith build a -> Maybe a Source #
Inspecting ScriptWitnesses
data AnyScriptWitness era where Source #
A ScriptWitness in any WitCtx. This lets us handle heterogeneous
collections of script witnesses from multiple contexts.
Constructors
| AnyScriptWitness :: forall witctx era. Typeable witctx => ScriptWitness witctx era -> AnyScriptWitness era |
Instances
| Show (AnyScriptWitness era) Source # | |
Defined in Cardano.Api.Tx.Internal.Body | |
| Eq (AnyScriptWitness era) Source # | |
Defined in Cardano.Api.Tx.Internal.Body Methods (==) :: AnyScriptWitness era -> AnyScriptWitness era -> Bool Source # (/=) :: AnyScriptWitness era -> AnyScriptWitness era -> Bool Source # | |
data ScriptWitnessIndex Source #
Identify the location of a ScriptWitness within the context of a
TxBody. These are indexes of the objects within the transaction that
need or can use script witnesses: inputs, minted assets, withdrawals and
certificates. These are simple numeric indices, enumerated from zero.
Thus the indices are not stable if the transaction body is modified.
Constructors
| ScriptWitnessIndexTxIn !Word32 | The n'th transaction input, in the order of the |
| ScriptWitnessIndexMint !Word32 | |
| ScriptWitnessIndexCertificate !Word32 | The n'th certificate, in the list order of the certificates. |
| ScriptWitnessIndexWithdrawal !Word32 | The n'th withdrawal, in the order of the |
| ScriptWitnessIndexVoting !Word32 | The n'th vote, in the order of the votes. |
| ScriptWitnessIndexProposing !Word32 | The n'th proposal, in the order of the proposals. |
Instances
collectTxBodyScriptWitnesses :: ShelleyBasedEra era -> TxBodyContent BuildTx era -> [(ScriptWitnessIndex, AnyScriptWitness era)] Source #
collectTxBodyScriptWitnessRequirements :: IsShelleyBasedEra era => AlonzoEraOnwards era -> TxBodyContent BuildTx era -> Either TxBodyError (TxScriptWitnessRequirements (ShelleyLedgerEra era)) Source #
toScriptIndex :: AlonzoEraOnwards era -> PlutusPurpose AsIx (ShelleyLedgerEra era) -> ScriptWitnessIndex Source #
Conversion to inline data
scriptDataToInlineDatum :: Era ledgerera => HashableScriptData -> Datum ledgerera Source #
Conversion of ScriptData to binary data which allows for the storage of data onchain within a transaction output.
Internal conversion functions & types
convCertificates :: ShelleyBasedEra era -> TxCertificates build era -> StrictSeq (TxCert (ShelleyLedgerEra era)) Source #
convCollateralTxIns :: TxInsCollateral era -> Set TxIn Source #
convExtraKeyWitnesses :: TxExtraKeyWitnesses era -> Set (KeyHash 'Witness) Source #
convLanguages :: [(ScriptWitnessIndex, AnyScriptWitness era)] -> Set Language Source #
convMintValue :: TxMintValue build era -> MultiAsset Source #
convPParamsToScriptIntegrityHash :: AlonzoEraOnwards era -> BuildTxWith BuildTx (Maybe (LedgerProtocolParameters era)) -> Redeemers (ShelleyLedgerEra era) -> TxDats (ShelleyLedgerEra era) -> Set Language -> StrictMaybe ScriptIntegrityHash Source #
convReferenceInputs :: TxInsReference build era -> Set TxIn Source #
convReturnCollateral :: ShelleyBasedEra era -> TxReturnCollateral ctx era -> StrictMaybe (TxOut (ShelleyLedgerEra era)) Source #
convScripts :: ShelleyLedgerEra era ~ ledgerera => [(ScriptWitnessIndex, AnyScriptWitness era)] -> [Script ledgerera] Source #
convScriptData :: ShelleyBasedEra era -> [TxOut CtxTx era] -> [(ScriptWitnessIndex, AnyScriptWitness era)] -> TxBodyScriptData era Source #
convTotalCollateral :: TxTotalCollateral era -> StrictMaybe Coin Source #
convTransactionFee :: ShelleyBasedEra era -> TxFee era -> Coin Source #
convTxOuts :: forall ctx era ledgerera. (HasCallStack, ShelleyLedgerEra era ~ ledgerera) => ShelleyBasedEra era -> [TxOut ctx era] -> StrictSeq (TxOut ledgerera) Source #
Arguments
| :: ShelleyBasedEra era | |
| -> TxUpdateProposal era | |
| -> Either TxBodyError (StrictMaybe (Update (ShelleyLedgerEra era))) |
|
Convert transaction update proposal into ledger update proposal
convValidityLowerBound :: TxValidityLowerBound era -> Maybe SlotNo Source #
convValidityUpperBound :: ShelleyBasedEra era -> TxValidityUpperBound era -> Maybe SlotNo Source #
convVotingProcedures :: TxVotingProcedures build era -> VotingProcedures (ShelleyLedgerEra era) Source #
convWithdrawals :: TxWithdrawals build era -> Withdrawals Source #
getScriptIntegrityHash :: BuildTxWith BuildTx (Maybe (LedgerProtocolParameters era)) -> Set Language -> TxBodyScriptData era -> StrictMaybe ScriptIntegrityHash Source #
mkCommonTxBody :: HasCallStack => ShelleyBasedEra era -> TxIns BuildTx era -> [TxOut ctx era] -> TxFee era -> TxWithdrawals build era -> Maybe (TxAuxData (ShelleyLedgerEra era)) -> LedgerTxBody era Source #
A helper function that constructs a TxBody with all of the fields that are common for all eras
toAuxiliaryData :: ShelleyBasedEra era -> TxMetadataInEra era -> TxAuxScripts era -> Maybe (TxAuxData (ShelleyLedgerEra era)) Source #
In the Allegra and Mary eras the auxiliary data consists of the tx metadata and the axiliary scripts. In the Alonzo and later eras the auxiliary data consists of the tx metadata and the axiliary scripts, and the axiliary script data.
toByronTxId :: TxId -> TxId Source #
toShelleyTxId :: TxId -> TxId Source #
toShelleyTxIn :: TxIn -> TxIn Source #
This function may overflow on the transaction index. Call sites must ensure that all uses of this function are appropriately guarded.
toShelleyTxOut :: (HasCallStack, ShelleyLedgerEra era ~ ledgerera) => ShelleyBasedEra era -> TxOut CtxUTxO era -> TxOut ledgerera Source #
toShelleyTxOutAny :: forall ctx era ledgerera. (HasCallStack, ShelleyLedgerEra era ~ ledgerera) => ShelleyBasedEra era -> TxOut ctx era -> TxOut ledgerera Source #
A variant of 'toShelleyTxOutAny that is used only internally to this module
that works with a TxOut in any context (including CtxTx) by ignoring
embedded datums (taking only their hash).
fromShelleyTxId :: TxId -> TxId Source #
fromShelleyTxIn :: TxIn -> TxIn Source #
fromShelleyTxOut :: ShelleyBasedEra era -> TxOut (ShelleyLedgerEra era) -> TxOut ctx era Source #
fromByronTxIn :: TxIn -> TxIn Source #
fromLedgerTxOuts :: ShelleyBasedEra era -> TxBody (ShelleyLedgerEra era) -> TxBodyScriptData era -> [TxOut CtxTx era] Source #
renderTxIn :: TxIn -> Text Source #
Misc helpers
Data family instances
A family of singleton types used in this API to indicate which type to use where it would otherwise be ambiguous or merely unclear.
Values of this type are passed to deserialisation functions for example.
Instances
getTxBodyContent :: TxBody era -> TxBodyContent ViewTx era Source #
validateTxIns :: [(TxIn, BuildTxWith BuildTx (Witness WitCtxTxIn era))] -> Either TxBodyError () Source #
guardShelleyTxInsOverflow :: [TxIn] -> Either TxBodyError () Source #
validateTxOuts :: ShelleyBasedEra era -> [TxOut CtxTx era] -> Either TxOutputError () Source #
validateMetadata :: TxMetadataInEra era -> Either TxBodyError () Source #
validateTxInsCollateral :: TxInsCollateral era -> Set Language -> Either TxBodyError () Source #
validateProtocolParameters :: BuildTxWith BuildTx (Maybe (LedgerProtocolParameters era)) -> Set Language -> Either TxBodyError () Source #
Convenience construction functions
Arguments
| :: ShelleyBasedEra era | |
| -> TxBodyContent BuildTx era | |
| -> AddressInEra era | Change address |
| -> Maybe Word | Override key witnesses |
| -> UTxO era | Just the transaction inputs, not the entire |
| -> LedgerProtocolParameters era | |
| -> LedgerEpochInfo | |
| -> SystemStart | |
| -> Set PoolId | The set of registered stake pools |
| -> Map StakeCredential Coin | |
| -> Map (Credential 'DRepRole) Coin | |
| -> [ShelleyWitnessSigningKey] | |
| -> Either (TxBodyErrorAutoBalance era) (Tx era) |
Construct a balanced transaction. See Cardano.Api.Query.Internal.Convenience.queryStateForBalancedTx for a convenient way of querying the node to get the required arguements for constructBalancedTx.
Misc
data TxInsExistError Source #
Constructors
| TxInsDoNotExist [TxIn] | |
| EmptyUTxO |
newtype ScriptLockedTxInsError Source #
Constructors
| ScriptLockedTxIns [TxIn] |
notScriptLockedTxIns :: [TxIn] -> UTxO era -> Either ScriptLockedTxInsError () Source #
txInsExistInUTxO :: [TxIn] -> UTxO era -> Either TxInsExistError () Source #
Ledger TxBody wrapper with useful lens
newtype LedgerTxBody era Source #
Constructors
| LedgerTxBody | |
Fields
| |
Constructors
mkAdaOnlyTxOut :: ShelleyBasedEra era -> Addr -> Coin -> TxOut (ShelleyLedgerEra era) Source #
mkAdaValue :: ShelleyBasedEra era -> Coin -> Value (ShelleyLedgerEra era) Source #
Lenses
strictMaybeL :: forall a f. Functor f => (Maybe a -> f (Maybe a)) -> StrictMaybe a -> f (StrictMaybe a) Source #
invalidBeforeL :: Lens' ValidityInterval (Maybe SlotNo) Source #
Lens to access the invalidBefore field of a ValidityInterval as a 'Maybe SlotNo'.
invalidHereAfterL :: Lens' ValidityInterval (Maybe SlotNo) Source #
Lens to access the invalidHereAfter field of a ValidityInterval as a 'Maybe SlotNo'.
invalidBeforeStrictL :: Lens' ValidityInterval (StrictMaybe SlotNo) Source #
Lens to access the invalidBefore field of a ValidityInterval as a 'StrictMaybe SlotNo'.
Ideally this should be defined in cardano-ledger
invalidHereAfterStrictL :: Lens' ValidityInterval (StrictMaybe SlotNo) Source #
Lens to access the invalidHereAfter field of a ValidityInterval as a 'StrictMaybe SlotNo'.
Ideally this should be defined in cardano-ledger
invalidBeforeTxBodyL :: AllegraEraOnwards era -> Lens' (LedgerTxBody era) (Maybe SlotNo) Source #
invalidHereAfterTxBodyL :: ShelleyBasedEra era -> Lens' (LedgerTxBody era) (Maybe SlotNo) Source #
Compatibility lens that provides a consistent interface over ttlTxBodyL and
'vldtTxBodyL . invalidHereAfterStrictL' across all shelley based eras.
The ledger uses ttlTxBodyL in Shelley only and from Allegra onwards uses vldtTxBodyL instead.
The former is a SlotNo with no limit represented as maxBound.
The latter is a ValidityInterval which is a pair of SlotNos that represent the lower and upper
bounds.
The upper bound field is similar t ttlTxBodyL except it is a 'StrictMaybe SlotNo' type where
no bounds is represented by SNothing.
invalidHereAfterTxBodyL lens over both with a 'Maybe SlotNo' type representation. Withing the
Shelley era, setting Nothing will set the ttl to maxBound in the underlying ledger type.
ttlAsInvalidHereAfterTxBodyL :: ShelleyEraOnly era -> Lens' (LedgerTxBody era) (Maybe SlotNo) Source #
updateTxBodyL :: ShelleyToBabbageEra era -> Lens' (LedgerTxBody era) (StrictMaybe (Update (ShelleyLedgerEra era))) Source #
txBodyL :: forall era f. Functor f => (TxBody (ShelleyLedgerEra era) -> f (TxBody (ShelleyLedgerEra era))) -> LedgerTxBody era -> f (LedgerTxBody era) Source #
mintTxBodyL :: MaryEraOnwards era -> Lens' (LedgerTxBody era) MultiAsset Source #
scriptIntegrityHashTxBodyL :: AlonzoEraOnwards era -> Lens' (LedgerTxBody era) (StrictMaybe ScriptIntegrityHash) Source #
collateralInputsTxBodyL :: AlonzoEraOnwards era -> Lens' (LedgerTxBody era) (Set TxIn) Source #
reqSignerHashesTxBodyL :: AlonzoEraOnwards era -> Lens' (LedgerTxBody era) (Set (KeyHash 'Witness)) Source #
referenceInputsTxBodyL :: BabbageEraOnwards era -> Lens' (LedgerTxBody era) (Set TxIn) Source #
collateralReturnTxBodyL :: BabbageEraOnwards era -> Lens' (LedgerTxBody era) (StrictMaybe (TxOut (ShelleyLedgerEra era))) Source #
totalCollateralTxBodyL :: BabbageEraOnwards era -> Lens' (LedgerTxBody era) (StrictMaybe Coin) Source #
certsTxBodyL :: ShelleyBasedEra era -> Lens' (LedgerTxBody era) (StrictSeq (TxCert (ShelleyLedgerEra era))) Source #
votingProceduresTxBodyL :: ConwayEraOnwards era -> Lens' (LedgerTxBody era) (VotingProcedures (ShelleyLedgerEra era)) Source #
proposalProceduresTxBodyL :: ConwayEraOnwards era -> Lens' (LedgerTxBody era) (OSet (ProposalProcedure (ShelleyLedgerEra era))) Source #
currentTreasuryValueTxBodyL :: ConwayEraOnwards era -> Lens' (LedgerTxBody era) (StrictMaybe Coin) Source #
treasuryDonationTxBodyL :: ConwayEraOnwards era -> Lens' (LedgerTxBody era) Coin Source #
adaAssetL :: ShelleyBasedEra era -> Lens' (Value (ShelleyLedgerEra era)) Coin Source #
multiAssetL :: MaryEraOnwards era -> Lens' MaryValue MultiAsset Source #
valueTxOutL :: ShelleyBasedEra era -> Lens' (TxOut (ShelleyLedgerEra era)) (Value (ShelleyLedgerEra era)) Source #
valueTxOutAdaAssetL :: ShelleyBasedEra era -> Lens' (TxOut (ShelleyLedgerEra era)) Coin Source #
Fees calculation
The Cardano.Api.Tx.Internal.Body documentation demonstrates how to create a TxBodyContent for a
transaction that takes 12 ada and sends 10 ada to an address, and spends 2 ada for fees. If a
UTXO with exactly 12 ada is available, this would be a valid transaction, because it is balanced, and has
sufficient fees, as 2 ada is more than enough to cover the fees for such a simple transaction on mainnet
at the time of writing.
A simple transaction that spends UTXOs is considered balanced if the value consumed equals the value produced. Simply put, a transaction that spends only lovelace must account for the total lovelace at the inputs, output(s), and transaction fee.
In other words:
inputs = outputs + fee
In this equation, the inputs would include the minted tokens, and the outputs would include the burned tokens.
However, we don't always want to spend all the ada from a UTXO. Balancing a transaction ensures that we send the desired amount, pay only the necessary fees, and calculate any extra currency to be sent back to a change address.
Since changes to the transaction body can affect the required, finding this balance can be challenging. Fortunately, there are functions available to help achieve this.
This module offers several methods for calculating transaction fees or fully balancing a draft transaction. Each method requires varying amounts of information and provides different levels of accuracy and automation.
Next, this module explores three examples of fee calculation methods. Other methods exist but they have similar requirements.
Examples below use the following qualified modules:
import qualified Cardano.Api as Api -- the general `cardano-api` exports
Example 1: Simple fee calculation and manual balancing
This method requires minimal information and some manual work.
It calculates the transaction fees, but we need to balance the transaction manually.
We need to know:
- The Shelley-based era witness for the current era, which can be obtained by using
shelleyBasedEra.
let sbe :: Api.ShelleyBasedEra Api.ConwayEra = Api.shelleyBasedEra
- The protocol parameters for the current era, which can be obtained using the
QueryProtocolParametersquery defined in Cardano.Api.Query.Internal.Type.QueryInMode. Cardano.Api.Network.IPC.Internal documentation illustrates how to make a query using IPC protocol. Let's assume they are stored in theexampleProtocolParamsvariable. - The draft transaction body, which can be created using
createTransactionBodydefined in Cardano.Api.Tx.Internal.Body:
let (Right txBody) = Api.createTransactionBody sbe txBodyContent
- The number of Byron and Shelley key witnesses, which corresponds to the number of keys required
to sign the transaction. We can estimate this by using
estimateTransactionKeyWitnessCount. For a simple transaction with a single UTXO locked by a single modern Shelley key, there would be0Byron witnesses and1Shelley witness. - The size of any reference scripts in bytes (if any). For simple transactions,
this would be
0.
With this in mind, it is possible to estimate the fees required by the transaction by calling
evaluateTransactionFee as follows:
let fees = Api.evaluateTransactionFee sbe exampleProtocolParams txBody 0 1 0
Once we know the required fees, we can balance the transaction by subtracting fees from the total value of the UTXO being spent.
For example, if we have a UTXO with 12 ada, the fees are 0.2 ada, and we want to send 10 ada to an address, the transaction could look like this:
- 1 input of 12 ada (from the UTXO)
- 1 output of 10 ada (to the recipient address)
- 1 output of 1.8 ada (to the change address)
- 0.2 ada in fees (calculated fees, in this case, an overestimation).
We would then have to update the TxBodyContent accordingly and continue building
the transaction as demonstrated in Cardano.Api.Experimental.Tx.
Example 2: Automated balancing without chain information (no UTXO, no ledger state)
This method requires more information, but better automates the process, reducing
the need for estimation. It also works with a TxBodyContent, rather than a
full TxBody.
The following information is required:
- The MaryEraOnwards witness for the current era. In this case, we use the
one for the
Conwayera:
let meo = Api.MaryEraOnwardsConway
- The draft
TxBodyContentfor the transaction we want to balance. See how to create one in Cardano.Api.Tx.Internal.Body. It is assumed to be stored in thetxBodyContentvariable. - The protocol parameters for the current era, which can be obtained using the
QueryProtocolParametersquery defined in Cardano.Api.Query.Internal.Type.QueryInMode. Cardano.Api.Network.IPC.Internal documentation illustrates how to make a query using IPC protocol. Let's assume they are stored in theexampleProtocolParamsvariable. For stake pool and governance actions, we will also need:
- The set of registered stake pools being unregistered in this transaction
- The map of all deposits for stake credentials being unregistered in this transaction
- The map of all deposits for DRep credentials that are unregistered in this transaction
- Plutus script execution units for all script witnesses used in the transaction.
This example assumes we are only spending key-locked UTXOs. Therefore, we can ignore the above
and use mempty.
The following amounts:
- Collateral amount: required only for transactions involving Plutus scripts. Since
this transaction does not include any, the collateral is
0. - Amount of Shelley key witnesses to be added: estimated using
estimateTransactionKeyWitnessCount. For a simple transaction spending a single UTXO locked by a modern Shelley key, there is1Shelley witness. - Amount of Byron key witnesses to be added: assumed to be
0for this transaction. - Size of all reference scripts (in bytes): since no reference scripts are used, this value is
0.
- Collateral amount: required only for transactions involving Plutus scripts. Since
this transaction does not include any, the collateral is
- The address for sending the change. We can deserialize it from its bech32 representation
using the
deserialiseAddressfunction defined in Cardano.Api.Address:
let Just exampleChangeAddress =
Api.deserialiseAddress
(Api.AsAddressInEra eraAsType)
"addr_test1vzpfxhjyjdlgk5c0xt8xw26avqxs52rtf69993j4tajehpcue4v2v"
Alternatively, we can get it from our signing key:
let exampleChangeAddress =
Api.shelleyAddressInEra sbe $
Api.makeShelleyAddress
(Api.Testnet $ Api.NetworkMagic 2) -- The magic for the network we are using
(Api.PaymentCredentialByKey
$ Api.verificationKeyHash
$ Api.getVerificationKey
signingKey)
Api.NoStakeAddress -- Potentially, the stake credential if we want to use one
- Finally, we need the total amount of ada (and other tokens) in the UTXOs being spent. In this example, the transaction spends 12 ada:
let totalUTxOValue = Api.lovelaceToValue 12_000_000
With all this information, a balanced transaction can be obtained by calling estimateBalancedTxBody
as follows:
let (Right (Api.BalancedTxBody
updatedTxBodyContent
updatedTxBody
changeOutput
fees)) =
Api.estimateBalancedTxBody
meo
txBodyContent
exampleProtocolParams
mempty
mempty
mempty
mempty
0
1
0
0
exampleChangeAddress
This will produce a balanced transaction body with calculated fees and a change output, but it still needs to be signed and submitted.
Example 3: Fully automated balancing with chain information (requires UTXO and ledger state data)
The previous example required manually providing various details, which was feasible for a simple transaction. However, for more complex transactions involving scripts or advanced functionalities such as governance actions, a more automated approach is available. This method performs most calculations in exchange for general ledger information.
The following details are required:
- Shelley-based era witness for the current era, retrievable using
shelleyBasedEra.
let sbe :: Api.ShelleyBasedEra Api.ConwayEra = Api.shelleyBasedEra
- Network start time, obtainable using the
QuerySystemStartquery defined in Cardano.Api.Query.Internal.Type.QueryInMode. Cardano.Api.Network.IPC.Internal documentation illustrates how to make a query using IPC protocol. Assume we have it in theexampleSystemStartvariable. - Ledger epoch information, derivable by applying
toLedgerEpochInfoto theEraHistory, which can be retrieved using theQueryEraHistoryquery defined in Cardano.Api.Query.Internal.Type.QueryInMode. Assume this is stored in theexampleLedgerEpochInfovariable. - Protocol parameters for the current era, accessible through the
QueryProtocolParametersquery defined in Cardano.Api.Query.Internal.Type.QueryInMode. Assume this is stored in theexampleProtocolParamsvariable. For stake pool and gov actions, additional data is requried:
- The set of registered stake pools being unregistered in this transaction
- The map of all deposits associated with stake credentials being unregistered in this transaction
- The map of all deposits associated with DRep credentials being unregistered in this transaction.
For this example, no stake pool deregistration or governance actions are considered, so mempty is used
for the corresponding parameters.
- UTXO set being spent -- the full UTXO set can be obtained using the
QueryUTxOquery from Cardano.Api.Query.Internal.Type.QueryInMode. Assume this is stored in theutxoToUsevariable. - Draft transaction body content -- the
TxBodyContentfor the transaction that requires balancing. The process for creating this structure is demonstrated in Cardano.Api.Tx.Internal.Body. - Change address -- the address where any remaining balance should be returned. This can be
deserialized from its Bech32 representation using the
deserialiseAddressfunction from Cardano.Api.Address:
let (Just exampleChangeAddress) =
Api.deserialiseAddress
(Api.AsAddressInEra eraAsType)
"addr_test1vzpfxhjyjdlgk5c0xt8xw26avqxs52rtf69993j4tajehpcue4v2v"
Alternatively, it is possible to get it from the signing key:
let exampleChangeAddress =
Api.shelleyAddressInEra sbe $
Api.makeShelleyAddress
(Api.Testnet $ Api.NetworkMagic 2) -- The magic for the network we are using
(Api.PaymentCredentialByKey
$ Api.verificationKeyHash
$ Api.getVerificationKey
signingKey)
Api.NoStakeAddress -- Potentially, the stake credential if we want to use one
- Finally, the number of key witnesses required for the transaction can be manually specified.
However, if set to
Nothing, the function will automatically estimate the required number.
With all the necessary information available, a balanced transaction can be obtained
by calling makeTransactionBodyAutoBalance as follows:
let Right (Api.BalancedTxBody
updatedTxBodyContent
updatedTxBody
changeOutput
fees) =
Api.makeTransactionBodyAutoBalance
sbe
exampleSystemStart
exampleLedgerEpochInfo
(Api.LedgerProtocolParameters exampleProtocolParams)
mempty
mempty
mempty
utxoToUse
txBodyContent
exampleChangeAddress
Nothing
This will give us a balanced transaction with the fees calculated and the change output included. The transaction can now be signed and submitted.
Transaction fees
evaluateTransactionFee Source #
Arguments
| :: ShelleyBasedEra era | |
| -> PParams (ShelleyLedgerEra era) | |
| -> TxBody era | |
| -> Word | The number of Shelley key witnesses |
| -> Word | The number of Byron key witnesses |
| -> Int | Reference script size in bytes |
| -> Coin |
Transaction fees can be computed for a proposed transaction based on the expected number of key witnesses (i.e. signatures).
When possible, use calculateMinTxFee, as it provides a more accurate
estimate:
Arguments
| :: ShelleyBasedEra era | |
| -> PParams (ShelleyLedgerEra era) | |
| -> UTxO era | |
| -> TxBody era | |
| -> Word | The number of Shelley key witnesses |
| -> Coin |
Estimate the minimum transaction fee by analyzing the transaction structure and determining the required number and type of key witnesses.
It requires access to the relevant portion of the UTXO set to look up any transaction inputs (txins) included in the transaction. However, it cannot reliably determine the number of witnesses required for native scripts.
Therefore, the number of witnesses needed for native scripts must be provided as an additional argument.
estimateTransactionKeyWitnessCount :: TxBodyContent BuildTx era -> Word Source #
Provide and approximate count of the key witnesses (i.e. signatures) required for a transaction.
This estimate is not exact and may overestimate the required number of witnesses. The function makes conservative assumptions, including:
- Treating all inputs as originating from distinct addresses. In reality, multiple inputs may share the same address, requiring only one witness per address.
- Assuming regular and collateral inputs are distinct, even though they may overlap.
TODO: Consider implementing a more precise calculation that leverages the UTXO set to determine which inputs correspond to distinct addresses. Additionally, the estimate can be refined by distinguishing between Shelley and Byron-style witnesses.
Script execution units
evaluateTransactionExecutionUnits :: CardanoEra era -> SystemStart -> LedgerEpochInfo -> LedgerProtocolParameters era -> UTxO era -> TxBody era -> Map ScriptWitnessIndex (Either ScriptExecutionError (EvalTxExecutionUnitsLog, ExecutionUnits)) Source #
Compute the ExecutionUnits required for each script in the transaction.
This process involves executing all scripts and counting the actual execution units consumed.
evaluateTransactionExecutionUnitsShelley :: ShelleyBasedEra era -> SystemStart -> LedgerEpochInfo -> LedgerProtocolParameters era -> UTxO era -> Tx (ShelleyLedgerEra era) -> Map ScriptWitnessIndex (Either ScriptExecutionError (EvalTxExecutionUnitsLog, ExecutionUnits)) Source #
data ScriptExecutionError Source #
This data type represents the possible reasons for a script’s execution
failure, as reported by the evaluateTransactionExecutionUnits function.
The first three errors relate to issues before executing the script, while the last two arise during script execution.
TODO: Consider replacing ScriptWitnessIndex with the ledger’s PlutusPurpose
AsIx ledgerera. This change would require parameterizing the
ScriptExecutionError.
Constructors
| ScriptErrorMissingTxIn TxIn | The script depends on a |
| ScriptErrorTxInWithoutDatum TxIn | The |
| ScriptErrorWrongDatum (Hash ScriptData) | The |
| ScriptErrorEvaluationFailed DebugPlutusFailure | The script evaluation failed. This usually means it evaluated to an
error value. This is not a case of running out of execution units
(which is not possible for |
| ScriptErrorExecutionUnitsOverflow | The execution units overflowed a 64bit word. Congratulations if you encounter this error. With the current style of cost model this would need a script to run for over 7 months, which is somewhat more than the expected maximum of a few milliseconds. |
| ScriptErrorNotPlutusWitnessedTxIn ScriptWitnessIndex ScriptHash | An attempt was made to spend a key witnessed tx input with a script witness. |
| ScriptErrorRedeemerPointsToUnknownScriptHash ScriptWitnessIndex | The redeemer pointer points to a script hash that does not exist in the transaction nor in the UTxO as a reference script" |
| ScriptErrorMissingScript ScriptWitnessIndex ResolvablePointers | A redeemer pointer points to a script that does not exist. |
| ScriptErrorMissingCostModel Language | A cost model was missing for a language which was used. |
| (EraPlutusContext (ShelleyLedgerEra era), Show (ContextError (ShelleyLedgerEra era))) => ScriptErrorTranslationError (ContextError (ShelleyLedgerEra era)) |
Instances
| Error ScriptExecutionError Source # | |
Defined in Cardano.Api.Tx.Internal.Fee Methods prettyError :: ScriptExecutionError -> Doc ann Source # | |
| Show ScriptExecutionError Source # | |
Defined in Cardano.Api.Tx.Internal.Fee | |
data TransactionValidityError era where Source #
Constructors
| TransactionValidityIntervalError :: forall era. PastHorizonException -> TransactionValidityError era | The transaction validity interval is too far into the future. Transactions containing Plutus scripts must have a validity interval that is not excessively far in the future. This ensures that the UTC corresponding to the validity interval expressed in slot numbers, can be reliably determined. Plutus scripts are given the transaction validity interval in UTC to prevent sensitivity to variations in slot lengths. If either end of the validity interval exceeds the "time horizon", the consensus algorithm cannot reliably establish the relationship between slots and time. This error occurs when thevalidity interval exceeds the time horizon. For the Cardano mainnet, the time horizon is set to 36 hours beyond the current time. This effectively restricts the submission and validation of transactions that include Plutus scripts if the end of their validity interval extends more than 36 hours into the future. |
| TransactionValidityCostModelError :: forall era. Map AnyPlutusScriptVersion CostModel -> String -> TransactionValidityError era |
Instances
| Error (TransactionValidityError era) Source # | |
Defined in Cardano.Api.Tx.Internal.Fee Methods prettyError :: TransactionValidityError era -> Doc ann Source # | |
| Show (TransactionValidityError era) Source # | |
Defined in Cardano.Api.Tx.Internal.Fee | |
Transaction balance
evaluateTransactionBalance :: ShelleyBasedEra era -> PParams (ShelleyLedgerEra era) -> Set PoolId -> Map StakeCredential Coin -> Map (Credential 'DRepRole) Coin -> UTxO era -> TxBody era -> TxOutValue era Source #
Compute the total balance of the proposed transaction. Ultimately, a valid transaction must be fully balanced, which means that it has a total value of zero.
Finding the (non-zero) balance of a partially constructed transaction is useful for adjusting a transaction to be fully balanced.
Automated transaction building
estimateBalancedTxBody Source #
Arguments
| :: HasCallStack | |
| => MaryEraOnwards era | |
| -> TxBodyContent BuildTx era | |
| -> PParams (ShelleyLedgerEra era) | |
| -> Set PoolId | The set of registered stake pools, being unregistered in this transaction. |
| -> Map StakeCredential Coin | A map of all deposits for stake credentials that are being unregistered in this transaction. |
| -> Map (Credential 'DRepRole) Coin | A map of all deposits for DRep credentials that are being unregistered in this transaction. |
| -> Map ScriptWitnessIndex ExecutionUnits | Plutus script execution units. |
| -> Coin | Total potential collateral amount. |
| -> Int | The number of key witnesses to be added to the transaction. |
| -> Int | The number of Byron key witnesses to be added to the transaction. |
| -> Int | The size of all reference scripts in bytes. |
| -> AddressInEra era | Change address. |
| -> Value | Total value of UTXOs being spent. |
| -> Either (TxFeeEstimationError era) (BalancedTxBody era) |
Use when you do not have access to the UTxOs you intend to spend
estimateOrCalculateBalancedTxBody :: ShelleyBasedEra era -> FeeEstimationMode era -> PParams (ShelleyLedgerEra era) -> TxBodyContent BuildTx era -> Set PoolId -> Map StakeCredential Coin -> Map (Credential 'DRepRole) Coin -> AddressInEra era -> Either (AutoBalanceError era) (BalancedTxBody era) Source #
makeTransactionBodyAutoBalance Source #
Arguments
| :: HasCallStack | |
| => ShelleyBasedEra era | |
| -> SystemStart | |
| -> LedgerEpochInfo | |
| -> LedgerProtocolParameters era | |
| -> Set PoolId | The set of registered stake pools, being unregistered in this transaction. |
| -> Map StakeCredential Coin | The map of all deposits for stake credentials that are being unregistered in this transaction |
| -> Map (Credential 'DRepRole) Coin | The map of all deposits for DRep credentials that are being unregistered in this transaction |
| -> UTxO era | The transaction inputs (including reference and collateral ones), not the entire |
| -> TxBodyContent BuildTx era | |
| -> AddressInEra era | Change address |
| -> Maybe Word | Override key witnesses |
| -> Either (TxBodyErrorAutoBalance era) (BalancedTxBody era) |
This is similar to makeTransactionBody but with greater automation to
calculate suitable values for several things.
In particular:
- It calculates the correct script
ExecutionUnits(ignoring the provided values, which can thus be zero). - It calculates the transaction fees based on the script
ExecutionUnits, the currentProtocolParameters, and an estimate of the number of key witnesses (i.e. signatures). There is an override for the number of key witnesses. - It accepts a change address, calculates the balance of the transaction and puts the excess change into the change output.
- It also checks that the balance is positive and the change is above the minimum threshold.
To do this, it requires more information than makeTransactionBody, all of
which can be queried from a local node.
calcReturnAndTotalCollateral Source #
Arguments
| :: AlonzoEraPParams (ShelleyLedgerEra era) | |
| => BabbageEraOnwards era | |
| -> Coin | Fee |
| -> PParams (ShelleyLedgerEra era) | |
| -> TxInsCollateral era | From the initial TxBodyContent |
| -> TxReturnCollateral CtxTx era | From the initial TxBodyContent |
| -> TxTotalCollateral era | From the initial TxBodyContent |
| -> AddressInEra era | Change address |
| -> Value (ShelleyLedgerEra era) | Total available collateral (can include non-ada) |
| -> (TxReturnCollateral CtxTx era, TxTotalCollateral era) |
data AutoBalanceError era Source #
Constructors
| AutoBalanceEstimationError (TxFeeEstimationError era) | |
| AutoBalanceCalculationError (TxBodyErrorAutoBalance era) |
Instances
| Error (AutoBalanceError era) Source # | |
Defined in Cardano.Api.Tx.Internal.Fee Methods prettyError :: AutoBalanceError era -> Doc ann Source # | |
| Show (AutoBalanceError era) Source # | |
Defined in Cardano.Api.Tx.Internal.Fee | |
data BalancedTxBody era Source #
Constructors
| BalancedTxBody | |
Instances
| IsShelleyBasedEra era => Show (BalancedTxBody era) Source # | |
Defined in Cardano.Api.Tx.Internal.Fee | |
data FeeEstimationMode era Source #
Constructors
| CalculateWithSpendableUTxO | Accurate fee calculation. |
Fields
| |
| EstimateWithoutSpendableUTxO | Less accurate fee estimation. |
Fields
| |
newtype RequiredShelleyKeyWitnesses Source #
Constructors
| RequiredShelleyKeyWitnesses | |
Fields | |
Instances
newtype RequiredByronKeyWitnesses Source #
Constructors
| RequiredByronKeyWitnesses | |
Fields | |
Instances
newtype TotalReferenceScriptsSize Source #
Constructors
| TotalReferenceScriptsSize | |
Fields | |
Instances
data TxBodyErrorAutoBalance era Source #
The possible errors that can arise from makeTransactionBodyAutoBalance.
Constructors
| TxBodyError TxBodyError | The same errors that can arise from |
| TxBodyScriptExecutionError [(ScriptWitnessIndex, ScriptExecutionError)] | One or more scripts failed to execute correctly. |
| TxBodyScriptBadScriptValidity | One or more scripts were expected to fail validation, but none did. |
| TxBodyErrorBalanceNegative Coin MultiAsset | There is not enough ada and non-ada to cover both the outputs and the fees. The transaction should be changed to provide more input assets, or otherwise adjusted to need less (e.g. outputs, script etc). |
| TxBodyErrorAdaBalanceTooSmall | There is enough ada to cover both the outputs and the fees, but the resulting change is too small: it is under the minimum value for new UTXO entries. The transaction should be changed to provide more input ada. |
Fields
| |
| TxBodyErrorByronEraNotSupported |
|
| TxBodyErrorMissingParamMinUTxO | The |
| TxBodyErrorMinUTxONotMet | The minimum spendable UTxO threshold has not been met. |
Fields
| |
| TxBodyErrorNonAdaAssetsUnbalanced Value | |
| TxBodyErrorScriptWitnessIndexMissingFromExecUnitsMap ScriptWitnessIndex (Map ScriptWitnessIndex ExecutionUnits) | |
Instances
| Error (TxBodyErrorAutoBalance era) Source # | |
Defined in Cardano.Api.Tx.Internal.Fee Methods prettyError :: TxBodyErrorAutoBalance era -> Doc ann Source # | |
| Show (TxBodyErrorAutoBalance era) Source # | |
Defined in Cardano.Api.Tx.Internal.Fee | |
data TxFeeEstimationError era Source #
Constructors
Instances
| Error (TxFeeEstimationError era) Source # | |
Defined in Cardano.Api.Tx.Internal.Fee Methods prettyError :: TxFeeEstimationError era -> Doc ann Source # | |
| Show (TxFeeEstimationError era) Source # | |
Defined in Cardano.Api.Tx.Internal.Fee | |
Minimum UTxO calculation
calculateMinimumUTxO :: HasCallStack => ShelleyBasedEra era -> PParams (ShelleyLedgerEra era) -> TxOut CtxTx era -> Coin Source #
Internal helpers
data ResolvablePointers where Source #
Constructors
| ResolvablePointers :: forall era. (Era (ShelleyLedgerEra era), Show (PlutusPurpose AsIx (ShelleyLedgerEra era)), Show (PlutusPurpose AsItem (ShelleyLedgerEra era)), Show (PlutusScript (ShelleyLedgerEra era))) => ShelleyBasedEra era -> !(Map (PlutusPurpose AsIx (ShelleyLedgerEra era)) (PlutusPurpose AsItem (ShelleyLedgerEra era), Maybe (PlutusScriptBytes, Language), ScriptHash)) -> ResolvablePointers |
Instances
| Show ResolvablePointers Source # | |
Defined in Cardano.Api.Tx.Internal.Fee | |
substituteExecutionUnits :: Map ScriptWitnessIndex ExecutionUnits -> TxBodyContent BuildTx era -> Either (TxBodyErrorAutoBalance era) (TxBodyContent BuildTx era) Source #
Arguments
| :: ScriptValidity | Mark script as expected to pass or fail validation |
| -> Map ScriptWitnessIndex ScriptExecutionError | |
| -> Map ScriptWitnessIndex ExecutionUnits | |
| -> Either (TxBodyErrorAutoBalance era) (Map ScriptWitnessIndex ExecutionUnits) |
Signing a transaction
Example: Creating a ShelleyWitnessSigningKey
Signing a transaction requires a witness, for example, a ShelleyWitnessSigningKey.
This example uses the following qualified module:
import qualified Cardano.Api as Api -- the general `cardano-api` exports (including the old API)
There are several ways of signing a transaction and representing a signing key. If the
bech32 representation of the signing key is available, it is possible to use the
deserialiseFromBech32 function as follows:
let (Right signingKey) = Api.deserialiseFromBech32 (Api.AsSigningKey Api.AsPaymentKey) "addr_sk1648253w4tf6fv5fk28dc7crsjsaw7d9ymhztd4favg3cwkhz7x8sl5u3ms"
Then, simply wrap the signing key in a ShelleyWitnessSigningKey value:
let witness = Api.WitnessPaymentKey signingKey
This could also be done using an extended key, such as AsPaymentExtendedKey and WitnessPaymentExtendedKey.
Signing transactions
Creating transaction witnesses one by one, or all in one go.
Constructors
| ShelleyTx :: forall era. ShelleyBasedEra era -> Tx (ShelleyLedgerEra era) -> Tx era |
Bundled Patterns
| pattern Tx :: TxBody era -> [KeyWitness era] -> Tx era | This pattern will be deprecated in the future. We advise against introducing new usage of it. |
Instances
Constructors
| ATxAux | |
Fields
| |
Instances
| FromCBOR TxAux | |||||
| ToCBOR TxAux | |||||
| DecCBOR TxAux | |||||
| EncCBOR TxAux | |||||
| Buildable TxAux | |||||
Defined in Cardano.Chain.UTxO.TxAux | |||||
| Functor ATxAux | |||||
| ToJSON a => ToJSON (ATxAux a) | |||||
Defined in Cardano.Chain.UTxO.TxAux | |||||
| FromCBOR (ATxAux ByteSpan) | |||||
| Decoded (ATxAux ByteString) | |||||
Defined in Cardano.Chain.UTxO.TxAux Associated Types
Methods | |||||
| DecCBOR (ATxAux ByteSpan) | |||||
| NFData a => NFData (ATxAux a) | |||||
Defined in Cardano.Chain.UTxO.TxAux | |||||
| Generic (ATxAux a) | |||||
Defined in Cardano.Chain.UTxO.TxAux Associated Types
| |||||
| Show a => Show (ATxAux a) | |||||
| Eq a => Eq (ATxAux a) | |||||
| type BaseType (ATxAux ByteString) | |||||
Defined in Cardano.Chain.UTxO.TxAux | |||||
| type Rep (ATxAux a) | |||||
Defined in Cardano.Chain.UTxO.TxAux type Rep (ATxAux a) = D1 ('MetaData "ATxAux" "Cardano.Chain.UTxO.TxAux" "cardano-ledger-byron-1.2.0.0-3ee22d24db91dd8e62083ee9328601ef2301a2da431b66c1587c0258b1803b2c" 'False) (C1 ('MetaCons "ATxAux" 'PrefixI 'True) (S1 ('MetaSel ('Just "aTaTx") 'NoSourceUnpackedness 'SourceStrict 'DecidedStrict) (Rec0 (Annotated Tx a)) :*: (S1 ('MetaSel ('Just "aTaWitness") 'NoSourceUnpackedness 'SourceStrict 'DecidedStrict) (Rec0 (Annotated TxWitness a)) :*: S1 ('MetaSel ('Just "aTaAnnotation") 'NoSourceUnpackedness 'SourceStrict 'DecidedStrict) (Rec0 a)))) | |||||
getTxWitnesses :: Tx era -> [KeyWitness era] Source #
Signing in one go
data ShelleySigningKey Source #
We support making key witnesses with both normal and extended signing keys.
Constructors
| ShelleyNormalSigningKey (SignKeyDSIGN DSIGN) | A normal ed25519 signing key |
| ShelleyExtendedSigningKey XPrv | An extended ed25519 signing key |
signByronTransaction :: NetworkId -> Annotated Tx ByteString -> [SigningKey ByronKey] -> ATxAux ByteString Source #
signShelleyTransaction :: ShelleyBasedEra era -> TxBody era -> [ShelleyWitnessSigningKey] -> Tx era Source #
Incremental signing and separate witnesses
makeSignedByronTransaction :: [KeyWitness era] -> Annotated Tx ByteString -> ATxAux ByteString Source #
makeSignedTransaction :: [KeyWitness era] -> TxBody era -> Tx era Source #
makeSignedTransaction' :: CardanoEra era -> [KeyWitness era] -> TxBody era -> Tx era Source #
data KeyWitness era where Source #
Constructors
| ByronKeyWitness :: TxInWitness -> KeyWitness ByronEra | |
| ShelleyBootstrapWitness :: forall era. ShelleyBasedEra era -> BootstrapWitness -> KeyWitness era | |
| ShelleyKeyWitness :: forall era. ShelleyBasedEra era -> WitVKey 'Witness -> KeyWitness era |
Instances
| HasTypeProxy era => HasTypeProxy (KeyWitness era) Source # | |||||
Defined in Cardano.Api.Tx.Internal.Sign Associated Types
Methods proxyToAsType :: Proxy (KeyWitness era) -> AsType (KeyWitness era) Source # | |||||
| IsCardanoEra era => SerialiseAsCBOR (KeyWitness era) Source # | |||||
Defined in Cardano.Api.Tx.Internal.Sign Methods serialiseToCBOR :: KeyWitness era -> ByteString Source # deserialiseFromCBOR :: AsType (KeyWitness era) -> ByteString -> Either DecoderError (KeyWitness era) Source # | |||||
| IsCardanoEra era => HasTextEnvelope (KeyWitness era) Source # | |||||
Defined in Cardano.Api.Tx.Internal.Sign Methods textEnvelopeType :: AsType (KeyWitness era) -> TextEnvelopeType Source # textEnvelopeDefaultDescr :: KeyWitness era -> TextEnvelopeDescr Source # | |||||
| Show (KeyWitness era) Source # | |||||
Defined in Cardano.Api.Tx.Internal.Sign | |||||
| Eq (KeyWitness era) Source # | |||||
Defined in Cardano.Api.Tx.Internal.Sign Methods (==) :: KeyWitness era -> KeyWitness era -> Bool Source # (/=) :: KeyWitness era -> KeyWitness era -> Bool Source # | |||||
| data AsType (KeyWitness era) Source # | |||||
Defined in Cardano.Api.Tx.Internal.Sign | |||||
makeByronKeyWitness :: IsByronKey key => NetworkId -> Annotated Tx ByteString -> SigningKey key -> KeyWitness ByronEra Source #
data ShelleyWitnessSigningKey Source #
Constructors
| WitnessPaymentKey (SigningKey PaymentKey) | |
| WitnessPaymentExtendedKey (SigningKey PaymentExtendedKey) | |
| WitnessStakeKey (SigningKey StakeKey) | |
| WitnessStakeExtendedKey (SigningKey StakeExtendedKey) | |
| WitnessStakePoolKey (SigningKey StakePoolKey) | |
| WitnessStakePoolExtendedKey (SigningKey StakePoolExtendedKey) | |
| WitnessGenesisKey (SigningKey GenesisKey) | |
| WitnessGenesisExtendedKey (SigningKey GenesisExtendedKey) | |
| WitnessGenesisDelegateKey (SigningKey GenesisDelegateKey) | |
| WitnessGenesisDelegateExtendedKey (SigningKey GenesisDelegateExtendedKey) | |
| WitnessGenesisUTxOKey (SigningKey GenesisUTxOKey) | |
| WitnessCommitteeColdKey (SigningKey CommitteeColdKey) | |
| WitnessCommitteeColdExtendedKey (SigningKey CommitteeColdExtendedKey) | |
| WitnessCommitteeHotKey (SigningKey CommitteeHotKey) | |
| WitnessCommitteeHotExtendedKey (SigningKey CommitteeHotExtendedKey) | |
| WitnessDRepKey (SigningKey DRepKey) | |
| WitnessDRepExtendedKey (SigningKey DRepExtendedKey) |
makeShelleyKeyWitness :: ShelleyBasedEra era -> TxBody era -> ShelleyWitnessSigningKey -> KeyWitness era Source #
makeShelleyKeyWitness' :: ShelleyBasedEra era -> TxBody (ShelleyLedgerEra era) -> ShelleyWitnessSigningKey -> KeyWitness era Source #
data WitnessNetworkIdOrByronAddress Source #
Either a network ID or a Byron address to be used in constructing a Shelley bootstrap witness.
Constructors
| WitnessNetworkId !NetworkId | Network ID. If this value is used in the construction of a Shelley bootstrap witness,
the result will not consist of a derivation path. If that is required,
specify a |
| WitnessByronAddress !(Address ByronAddr) | Byron address. If this value is used in the construction of a Shelley bootstrap witness, both the network ID and derivation path will be extracted from the address and used in the construction of the witness. |
makeShelleyBootstrapWitness :: ShelleyBasedEra era -> WitnessNetworkIdOrByronAddress -> TxBody era -> SigningKey ByronKey -> KeyWitness era Source #
makeShelleyBasedBootstrapWitness :: ShelleyBasedEra era -> WitnessNetworkIdOrByronAddress -> TxBody (ShelleyLedgerEra era) -> SigningKey ByronKey -> KeyWitness era Source #
makeShelleySignature :: SignableRepresentation tosign => tosign -> ShelleySigningKey -> SignedDSIGN DSIGN tosign Source #
getTxBodyAndWitnesses :: Tx era -> (TxBody era, [KeyWitness era]) Source #
TxMetadata
newtype TxMetadata Source #
Constructors
| TxMetadata | |
Fields | |
Instances
| HasTypeProxy TxMetadata Source # | |||||
Defined in Cardano.Api.Tx.Internal.TxMetadata Associated Types
Methods proxyToAsType :: Proxy TxMetadata -> AsType TxMetadata Source # | |||||
| SerialiseAsCBOR TxMetadata Source # | |||||
Defined in Cardano.Api.Tx.Internal.TxMetadata Methods serialiseToCBOR :: TxMetadata -> ByteString Source # deserialiseFromCBOR :: AsType TxMetadata -> ByteString -> Either DecoderError TxMetadata Source # | |||||
| Monoid TxMetadata Source # | |||||
Defined in Cardano.Api.Tx.Internal.TxMetadata Methods mempty :: TxMetadata Source # mappend :: TxMetadata -> TxMetadata -> TxMetadata Source # mconcat :: [TxMetadata] -> TxMetadata Source # | |||||
| Semigroup TxMetadata Source # | Merge metadata maps. When there are clashing entries the left hand side takes precedence. | ||||
Defined in Cardano.Api.Tx.Internal.TxMetadata Methods (<>) :: TxMetadata -> TxMetadata -> TxMetadata Source # sconcat :: NonEmpty TxMetadata -> TxMetadata Source # stimes :: Integral b => b -> TxMetadata -> TxMetadata Source # | |||||
| Show TxMetadata Source # | |||||
Defined in Cardano.Api.Tx.Internal.TxMetadata | |||||
| Eq TxMetadata Source # | |||||
Defined in Cardano.Api.Tx.Internal.TxMetadata Methods (==) :: TxMetadata -> TxMetadata -> Bool Source # (/=) :: TxMetadata -> TxMetadata -> Bool Source # | |||||
| data AsType TxMetadata Source # | |||||
Defined in Cardano.Api.Tx.Internal.TxMetadata | |||||
Constructing metadata
class AsTxMetadata a where Source #
Methods
asTxMetadata :: a -> TxMetadata Source #
Instances
| AsTxMetadata GovernancePoll Source # | |
Defined in Cardano.Api.Governance.Internal.Poll Methods | |
| AsTxMetadata GovernancePollAnswer Source # | |
Defined in Cardano.Api.Governance.Internal.Poll Methods | |
data TxMetadataValue Source #
Constructors
| TxMetaMap [(TxMetadataValue, TxMetadataValue)] | |
| TxMetaList [TxMetadataValue] | |
| TxMetaNumber Integer | |
| TxMetaBytes ByteString | |
| TxMetaText Text |
Instances
| Show TxMetadataValue Source # | |
Defined in Cardano.Api.Tx.Internal.TxMetadata | |
| Eq TxMetadataValue Source # | |
Defined in Cardano.Api.Tx.Internal.TxMetadata Methods (==) :: TxMetadataValue -> TxMetadataValue -> Bool Source # (/=) :: TxMetadataValue -> TxMetadataValue -> Bool Source # | |
| Ord TxMetadataValue Source # | |
Defined in Cardano.Api.Tx.Internal.TxMetadata Methods compare :: TxMetadataValue -> TxMetadataValue -> Ordering Source # (<) :: TxMetadataValue -> TxMetadataValue -> Bool Source # (<=) :: TxMetadataValue -> TxMetadataValue -> Bool Source # (>) :: TxMetadataValue -> TxMetadataValue -> Bool Source # (>=) :: TxMetadataValue -> TxMetadataValue -> Bool Source # max :: TxMetadataValue -> TxMetadataValue -> TxMetadataValue Source # min :: TxMetadataValue -> TxMetadataValue -> TxMetadataValue Source # | |
mergeTransactionMetadata :: (TxMetadataValue -> TxMetadataValue -> TxMetadataValue) -> TxMetadata -> TxMetadata -> TxMetadata Source #
metaTextChunks :: Text -> TxMetadataValue Source #
Create a TxMetadataValue from a Text as a list of chunks of an
acceptable size.
metaBytesChunks :: ByteString -> TxMetadataValue Source #
Create a TxMetadataValue from a ByteString as a list of chunks of an
accaptable size.
Validating metadata
validateTxMetadata :: TxMetadata -> Either [(Word64, TxMetadataRangeError)] () Source #
Validate transaction metadata. This is for use with existing constructed metadata values, e.g. constructed manually or decoded from CBOR directly.
data TxMetadataRangeError Source #
An error in transaction metadata due to an out-of-range value.
Constructors
| TxMetadataNumberOutOfRange !Integer | The number is outside the maximum range of |
| TxMetadataTextTooLong !Int | The length of a text string metadatum value exceeds the maximum of 64 bytes as UTF8. |
| TxMetadataBytesTooLong !Int | The length of a byte string metadatum value exceeds the maximum of 64 bytes. |
Instances
| Error TxMetadataRangeError Source # | |
Defined in Cardano.Api.Tx.Internal.TxMetadata Methods prettyError :: TxMetadataRangeError -> Doc ann Source # | |
| Data TxMetadataRangeError Source # | |
Defined in Cardano.Api.Tx.Internal.TxMetadata Methods gfoldl :: (forall d b. Data d => c (d -> b) -> d -> c b) -> (forall g. g -> c g) -> TxMetadataRangeError -> c TxMetadataRangeError Source # gunfold :: (forall b r. Data b => c (b -> r) -> c r) -> (forall r. r -> c r) -> Constr -> c TxMetadataRangeError Source # toConstr :: TxMetadataRangeError -> Constr Source # dataTypeOf :: TxMetadataRangeError -> DataType Source # dataCast1 :: Typeable t => (forall d. Data d => c (t d)) -> Maybe (c TxMetadataRangeError) Source # dataCast2 :: Typeable t => (forall d e. (Data d, Data e) => c (t d e)) -> Maybe (c TxMetadataRangeError) Source # gmapT :: (forall b. Data b => b -> b) -> TxMetadataRangeError -> TxMetadataRangeError Source # gmapQl :: (r -> r' -> r) -> r -> (forall d. Data d => d -> r') -> TxMetadataRangeError -> r Source # gmapQr :: forall r r'. (r' -> r -> r) -> r -> (forall d. Data d => d -> r') -> TxMetadataRangeError -> r Source # gmapQ :: (forall d. Data d => d -> u) -> TxMetadataRangeError -> [u] Source # gmapQi :: Int -> (forall d. Data d => d -> u) -> TxMetadataRangeError -> u Source # gmapM :: Monad m => (forall d. Data d => d -> m d) -> TxMetadataRangeError -> m TxMetadataRangeError Source # gmapMp :: MonadPlus m => (forall d. Data d => d -> m d) -> TxMetadataRangeError -> m TxMetadataRangeError Source # gmapMo :: MonadPlus m => (forall d. Data d => d -> m d) -> TxMetadataRangeError -> m TxMetadataRangeError Source # | |
| Show TxMetadataRangeError Source # | |
Defined in Cardano.Api.Tx.Internal.TxMetadata | |
| Eq TxMetadataRangeError Source # | |
Defined in Cardano.Api.Tx.Internal.TxMetadata Methods (==) :: TxMetadataRangeError -> TxMetadataRangeError -> Bool Source # (/=) :: TxMetadataRangeError -> TxMetadataRangeError -> Bool Source # | |
Conversion to/from JSON
data TxMetadataJsonSchema Source #
Tx metadata is similar to JSON but not exactly the same. It has some deliberate limitations such as no support for floating point numbers or special forms for null or boolean values. It also has limitations on the length of strings. On the other hand, unlike JSON, it distinguishes between byte strings and text strings. It also supports any value as map keys rather than just string.
We provide two different mappings between tx metadata and JSON, useful for different purposes:
- A mapping that allows almost any JSON value to be converted into tx metadata. This does not require a specific JSON schema for the input. It does not expose the full representation capability of tx metadata.
- A mapping that exposes the full representation capability of tx metadata, but relies on a specific JSON schema for the input JSON.
In the "no schema" mapping, the idea is that (almost) any JSON can be turned into tx metadata and then converted back, without loss. That is, we can round-trip the JSON.
The subset of JSON supported is all JSON except: * No null or bool values * No floating point, only integers in the range of a 64bit signed integer * A limitation on string lengths
The approach for this mapping is to use whichever representation as tx metadata is most compact. In particular:
- JSON lists and maps represented as CBOR lists and maps
- JSON strings represented as CBOR strings
- JSON hex strings with "0x" prefix represented as CBOR byte strings
- JSON integer numbers represented as CBOR signed or unsigned numbers
- JSON maps with string keys that parse as numbers or hex byte strings, represented as CBOR map keys that are actually numbers or byte strings.
The string length limit depends on whether the hex string representation is used or not. For text strings the limit is 64 bytes for the UTF8 representation of the text string. For byte strings the limit is 64 bytes for the raw byte form (ie not the input hex, but after hex decoding).
In the "detailed schema" mapping, the idea is that we expose the full representation capability of the tx metadata in the form of a JSON schema. This means the full representation is available and can be controlled precisely. It also means any tx metadata can be converted into the JSON and back without loss. That is we can round-trip the tx metadata via the JSON and also round-trip schema-compliant JSON via tx metadata.
Constructors
| TxMetadataJsonNoSchema | Use the "no schema" mapping between JSON and tx metadata as described above. |
| TxMetadataJsonDetailedSchema | Use the "detailed schema" mapping between JSON and tx metadata as described above. |
Instances
| Show TxMetadataJsonSchema Source # | |
Defined in Cardano.Api.Tx.Internal.TxMetadata | |
| Eq TxMetadataJsonSchema Source # | |
Defined in Cardano.Api.Tx.Internal.TxMetadata Methods (==) :: TxMetadataJsonSchema -> TxMetadataJsonSchema -> Bool Source # (/=) :: TxMetadataJsonSchema -> TxMetadataJsonSchema -> Bool Source # | |
metadataFromJson :: TxMetadataJsonSchema -> Value -> Either TxMetadataJsonError TxMetadata Source #
Convert a value from JSON into tx metadata, using the given choice of mapping between JSON and tx metadata.
This may fail with a conversion error if the JSON is outside the supported
subset for the chosen mapping. See TxMetadataJsonSchema for the details.
metadataToJson :: TxMetadataJsonSchema -> TxMetadata -> Value Source #
Convert a tx metadata value into JSON , using the given choice of mapping between JSON and tx metadata.
This conversion is total but is not necessarily invertible.
See TxMetadataJsonSchema for the details.
metadataValueToJsonNoSchema :: TxMetadataValue -> Value Source #
data TxMetadataJsonError Source #
Constructors
| TxMetadataJsonToplevelNotMap | |
| TxMetadataJsonToplevelBadKey !Text | |
| TxMetadataJsonSchemaError !Word64 !Value !TxMetadataJsonSchemaError | |
| TxMetadataRangeError !Word64 !Value !TxMetadataRangeError |
Instances
| Error TxMetadataJsonError Source # | |
Defined in Cardano.Api.Tx.Internal.TxMetadata Methods prettyError :: TxMetadataJsonError -> Doc ann Source # | |
| Data TxMetadataJsonError Source # | |
Defined in Cardano.Api.Tx.Internal.TxMetadata Methods gfoldl :: (forall d b. Data d => c (d -> b) -> d -> c b) -> (forall g. g -> c g) -> TxMetadataJsonError -> c TxMetadataJsonError Source # gunfold :: (forall b r. Data b => c (b -> r) -> c r) -> (forall r. r -> c r) -> Constr -> c TxMetadataJsonError Source # toConstr :: TxMetadataJsonError -> Constr Source # dataTypeOf :: TxMetadataJsonError -> DataType Source # dataCast1 :: Typeable t => (forall d. Data d => c (t d)) -> Maybe (c TxMetadataJsonError) Source # dataCast2 :: Typeable t => (forall d e. (Data d, Data e) => c (t d e)) -> Maybe (c TxMetadataJsonError) Source # gmapT :: (forall b. Data b => b -> b) -> TxMetadataJsonError -> TxMetadataJsonError Source # gmapQl :: (r -> r' -> r) -> r -> (forall d. Data d => d -> r') -> TxMetadataJsonError -> r Source # gmapQr :: forall r r'. (r' -> r -> r) -> r -> (forall d. Data d => d -> r') -> TxMetadataJsonError -> r Source # gmapQ :: (forall d. Data d => d -> u) -> TxMetadataJsonError -> [u] Source # gmapQi :: Int -> (forall d. Data d => d -> u) -> TxMetadataJsonError -> u Source # gmapM :: Monad m => (forall d. Data d => d -> m d) -> TxMetadataJsonError -> m TxMetadataJsonError Source # gmapMp :: MonadPlus m => (forall d. Data d => d -> m d) -> TxMetadataJsonError -> m TxMetadataJsonError Source # gmapMo :: MonadPlus m => (forall d. Data d => d -> m d) -> TxMetadataJsonError -> m TxMetadataJsonError Source # | |
| Show TxMetadataJsonError Source # | |
Defined in Cardano.Api.Tx.Internal.TxMetadata | |
| Eq TxMetadataJsonError Source # | |
Defined in Cardano.Api.Tx.Internal.TxMetadata Methods (==) :: TxMetadataJsonError -> TxMetadataJsonError -> Bool Source # (/=) :: TxMetadataJsonError -> TxMetadataJsonError -> Bool Source # | |
data TxMetadataJsonSchemaError Source #
Constructors
| TxMetadataJsonNullNotAllowed | |
| TxMetadataJsonBoolNotAllowed | |
| TxMetadataJsonNumberNotInteger !Double | |
| TxMetadataJsonNotObject !Value | |
| TxMetadataJsonBadObject ![(Text, Value)] | |
| TxMetadataJsonBadMapPair !Value | |
| TxMetadataJsonTypeMismatch !Text !Value |
Instances
| Error TxMetadataJsonSchemaError Source # | |
Defined in Cardano.Api.Tx.Internal.TxMetadata Methods prettyError :: TxMetadataJsonSchemaError -> Doc ann Source # | |
| Data TxMetadataJsonSchemaError Source # | |
Defined in Cardano.Api.Tx.Internal.TxMetadata Methods gfoldl :: (forall d b. Data d => c (d -> b) -> d -> c b) -> (forall g. g -> c g) -> TxMetadataJsonSchemaError -> c TxMetadataJsonSchemaError Source # gunfold :: (forall b r. Data b => c (b -> r) -> c r) -> (forall r. r -> c r) -> Constr -> c TxMetadataJsonSchemaError Source # toConstr :: TxMetadataJsonSchemaError -> Constr Source # dataTypeOf :: TxMetadataJsonSchemaError -> DataType Source # dataCast1 :: Typeable t => (forall d. Data d => c (t d)) -> Maybe (c TxMetadataJsonSchemaError) Source # dataCast2 :: Typeable t => (forall d e. (Data d, Data e) => c (t d e)) -> Maybe (c TxMetadataJsonSchemaError) Source # gmapT :: (forall b. Data b => b -> b) -> TxMetadataJsonSchemaError -> TxMetadataJsonSchemaError Source # gmapQl :: (r -> r' -> r) -> r -> (forall d. Data d => d -> r') -> TxMetadataJsonSchemaError -> r Source # gmapQr :: forall r r'. (r' -> r -> r) -> r -> (forall d. Data d => d -> r') -> TxMetadataJsonSchemaError -> r Source # gmapQ :: (forall d. Data d => d -> u) -> TxMetadataJsonSchemaError -> [u] Source # gmapQi :: Int -> (forall d. Data d => d -> u) -> TxMetadataJsonSchemaError -> u Source # gmapM :: Monad m => (forall d. Data d => d -> m d) -> TxMetadataJsonSchemaError -> m TxMetadataJsonSchemaError Source # gmapMp :: MonadPlus m => (forall d. Data d => d -> m d) -> TxMetadataJsonSchemaError -> m TxMetadataJsonSchemaError Source # gmapMo :: MonadPlus m => (forall d. Data d => d -> m d) -> TxMetadataJsonSchemaError -> m TxMetadataJsonSchemaError Source # | |
| Show TxMetadataJsonSchemaError Source # | |
Defined in Cardano.Api.Tx.Internal.TxMetadata | |
| Eq TxMetadataJsonSchemaError Source # | |
Defined in Cardano.Api.Tx.Internal.TxMetadata Methods (==) :: TxMetadataJsonSchemaError -> TxMetadataJsonSchemaError -> Bool Source # (/=) :: TxMetadataJsonSchemaError -> TxMetadataJsonSchemaError -> Bool Source # | |
Internal conversion functions
extractWitnessableCertificates :: AlonzoEraOnwards era -> TxCertificates BuildTx era -> [(Witnessable 'CertItem (ShelleyLedgerEra era), BuildTxWith BuildTx (Witness WitCtxStake era))] Source #
extractWitnessableMints :: AlonzoEraOnwards era -> TxMintValue build era -> [(Witnessable 'MintItem (ShelleyLedgerEra era), BuildTxWith BuildTx (Witness WitCtxMint era))] Source #
extractWitnessableProposals :: forall era (eon :: Type -> Type). ConwayEraOnwards era -> Maybe (Featured eon era (TxProposalProcedures BuildTx era)) -> [(Witnessable 'ProposalItem (ShelleyLedgerEra era), BuildTxWith BuildTx (Witness WitCtxStake era))] Source #
extractWitnessableTxIns :: AlonzoEraOnwards era -> TxIns BuildTx era -> [(Witnessable 'TxInItem (ShelleyLedgerEra era), BuildTxWith BuildTx (Witness WitCtxTxIn era))] Source #
extractWitnessableVotes :: forall era (eon :: Type -> Type). ConwayEraOnwards era -> Maybe (Featured eon era (TxVotingProcedures BuildTx era)) -> [(Witnessable 'VoterItem (ShelleyLedgerEra era), BuildTxWith BuildTx (Witness WitCtxStake era))] Source #
extractWitnessableWithdrawals :: AlonzoEraOnwards era -> TxWithdrawals BuildTx era -> [(Witnessable 'WithdrawalItem (ShelleyLedgerEra era), BuildTxWith BuildTx (Witness WitCtxStake era))] Source #
legacyKeyWitnessEncode :: KeyWitness era -> ByteString Source #
We no longer use the non-compliant CDDL legacy encoding.
Instead of depending on a tag to differentiate which key witness
we are dealing with, we opted to use Validation data type. This
provides a convenient way to try multiple decoders until one succeeds.
Shared parsing utils
pBytes :: Parser ByteString Source #