Safe Haskell	Safe-Inferred
Language	GHC2021

Hydra.Chain.CardanoClient

Contents

CardanoClient handle
Tx Construction / Submission
Local state query
Helpers

Description

A basic cardano-node client that can talk to a local cardano-node.

The idea of this module is to provide a Haskell interface on top of cardano-cli's API, using cardano-api types.

Synopsis

data QueryException
- = QueryAcquireException AcquiringFailure
- | QueryEraMismatchException EraMismatch
- | QueryProtocolParamsConversionException ProtocolParametersConversionError
- | QueryProtocolParamsEraNotSupported AnyCardanoEra
- | QueryProtocolParamsEncodingFailureOnEra AnyCardanoEra Text
- | QueryEraNotInCardanoModeFailure AnyCardanoEra
- | QueryNotShelleyBasedEraException AnyCardanoEra
data CardanoClient = CardanoClient {
- queryUTxOByAddress :: [Address ShelleyAddr] -> IO UTxO
- networkId :: NetworkId
}
mkCardanoClient :: NetworkId -> SocketPath -> CardanoClient
buildTransactionWithBody :: PParams LedgerEra -> SystemStart -> EraHistory -> Set PoolId -> AddressInEra -> TxBodyContent BuildTx -> UTxO -> Either (TxBodyErrorAutoBalance Era) Tx
buildTransaction :: NetworkId -> SocketPath -> AddressInEra -> UTxO -> [TxIn] -> [TxOut CtxTx] -> IO (Either (TxBodyErrorAutoBalance Era) Tx)
buildTransactionWithPParams :: PParams LedgerEra -> NetworkId -> SocketPath -> AddressInEra -> UTxO -> [TxIn] -> [TxOut CtxTx] -> IO (Either (TxBodyErrorAutoBalance Era) Tx)
buildTransactionWithPParams' :: PParams LedgerEra -> SystemStart -> EraHistory -> Set PoolId -> AddressInEra -> UTxO -> [TxIn] -> [TxOut CtxTx] -> Either (TxBodyErrorAutoBalance Era) Tx
submitTransaction :: NetworkId -> SocketPath -> Tx -> IO ()
data SubmitTransactionException
- = SubmitEraMismatch EraMismatch
- | SubmitTxValidationError TxValidationErrorInCardanoMode
awaitTransaction :: NetworkId -> SocketPath -> Tx -> IO UTxO
awaitTransactionId :: NetworkId -> SocketPath -> TxId -> IO UTxO
data QueryPoint
- = QueryTip
- | QueryAt ChainPoint
queryTip :: NetworkId -> SocketPath -> IO ChainPoint
queryTipSlotNo :: NetworkId -> SocketPath -> IO SlotNo
querySystemStart :: NetworkId -> SocketPath -> QueryPoint -> IO SystemStart
queryEraHistory :: NetworkId -> SocketPath -> QueryPoint -> IO EraHistory
queryEpochNo :: NetworkId -> SocketPath -> QueryPoint -> IO EpochNo
queryProtocolParameters :: NetworkId -> SocketPath -> QueryPoint -> IO (PParams LedgerEra)
queryGenesisParameters :: NetworkId -> SocketPath -> QueryPoint -> IO (GenesisParameters ShelleyEra)
queryUTxO :: NetworkId -> SocketPath -> QueryPoint -> [Address ShelleyAddr] -> IO UTxO
queryUTxOExpr :: ShelleyBasedEra era -> [Address ShelleyAddr] -> LocalStateQueryExpr b p QueryInMode r IO UTxO
queryUTxOByTxIn :: NetworkId -> SocketPath -> QueryPoint -> [TxIn] -> IO UTxO
assumeShelleyBasedEraOrThrow :: MonadThrow m => CardanoEra era -> m (ShelleyBasedEra era)
queryUTxOWhole :: NetworkId -> SocketPath -> QueryPoint -> IO UTxO
queryUTxOFor :: NetworkId -> SocketPath -> QueryPoint -> VerificationKey PaymentKey -> IO UTxO
queryStakePools :: NetworkId -> SocketPath -> QueryPoint -> IO (Set PoolId)
queryCurrentEraExpr :: LocalStateQueryExpr b p QueryInMode r IO AnyCardanoEra
queryInShelleyBasedEraExpr :: ShelleyBasedEra era -> QueryInShelleyBasedEra era a -> LocalStateQueryExpr b p QueryInMode r IO a
runQuery :: NetworkId -> SocketPath -> QueryPoint -> QueryInMode a -> IO a
runQueryExpr :: NetworkId -> SocketPath -> QueryPoint -> LocalStateQueryExpr BlockInMode ChainPoint QueryInMode () IO a -> IO a
throwOnEraMismatch :: MonadThrow m => Either EraMismatch a -> m a
throwOnUnsupportedNtcVersion :: MonadThrow m => Either UnsupportedNtcVersionError a -> m a
localNodeConnectInfo :: NetworkId -> SocketPath -> LocalNodeConnectInfo
cardanoModeParams :: ConsensusModeParams

Documentation

data QueryException Source #

Constructors

QueryAcquireException AcquiringFailure
QueryEraMismatchException EraMismatch
QueryProtocolParamsConversionException ProtocolParametersConversionError
QueryProtocolParamsEraNotSupported AnyCardanoEra
QueryProtocolParamsEncodingFailureOnEra AnyCardanoEra Text
QueryEraNotInCardanoModeFailure AnyCardanoEra
QueryNotShelleyBasedEraException AnyCardanoEra

Instances

Instances details

Exception QueryException Source #
Instance details Defined in Hydra.Chain.CardanoClient Methods toException :: QueryException -> SomeException Source # fromException :: SomeException -> Maybe QueryException Source # displayException :: QueryException -> String Source #
Show QueryException Source #
Instance details Defined in Hydra.Chain.CardanoClient Methods showsPrec :: Int -> QueryException -> ShowS Source # show :: QueryException -> String Source # showList :: [QueryException] -> ShowS Source #
Eq QueryException Source #
Instance details Defined in Hydra.Chain.CardanoClient Methods (==) :: QueryException -> QueryException -> Bool Source # (/=) :: QueryException -> QueryException -> Bool Source #

CardanoClient handle

data CardanoClient Source #

Handle interface for abstract querying of a cardano node.

Constructors

CardanoClient
Fields queryUTxOByAddress :: [Address ShelleyAddr] -> IO UTxO networkId :: NetworkId

mkCardanoClient :: NetworkId -> SocketPath -> CardanoClient Source #

Construct a CardanoClient handle.

Tx Construction / Submission

buildTransactionWithBody Source #

Arguments

:: PParams LedgerEra	Protocol parameters
-> SystemStart	System start
-> EraHistory	Change address to send
-> Set PoolId
-> AddressInEra
-> TxBodyContent BuildTx	Body
-> UTxO	Unspent transaction outputs to spend.
-> Either (TxBodyErrorAutoBalance Era) Tx

buildTransaction Source #

Arguments

:: NetworkId	Current network identifier
-> SocketPath	Filepath to the cardano-node's domain socket
-> AddressInEra	Change address to send
-> UTxO	Unspent transaction outputs to spend.
-> [TxIn]	Collateral inputs.
-> [TxOut CtxTx]	Outputs to create.
-> IO (Either (TxBodyErrorAutoBalance Era) Tx)

buildTransactionWithPParams Source #

Arguments

:: PParams LedgerEra	Protocol parameters
-> NetworkId	Current network identifier
-> SocketPath	Filepath to the cardano-node's domain socket
-> AddressInEra	Change address to send
-> UTxO	Unspent transaction outputs to spend.
-> [TxIn]	Collateral inputs.
-> [TxOut CtxTx]	Outputs to create.
-> IO (Either (TxBodyErrorAutoBalance Era) Tx)

Construct a simple payment consuming some inputs and producing some outputs (no certificates or withdrawals involved).

On success, the returned transaction is fully balanced. On error, return TxBodyErrorAutoBalance.

buildTransactionWithPParams' Source #

Arguments

:: PParams LedgerEra	Protocol parameters
-> SystemStart
-> EraHistory
-> Set PoolId
-> AddressInEra	Change address to send
-> UTxO	Unspent transaction outputs to spend.
-> [TxIn]	Collateral inputs.
-> [TxOut CtxTx]	Outputs to create.
-> Either (TxBodyErrorAutoBalance Era) Tx

submitTransaction Source #

Arguments

:: NetworkId	Current network discriminant
-> SocketPath	Filepath to the cardano-node's domain socket
-> Tx	A signed transaction.
-> IO ()

Submit a (signed) transaction to the node.

Throws SubmitTransactionException if submission fails.

data SubmitTransactionException Source #

Exceptions that can occur during a transaction submission.

In principle, we can only encounter an EraMismatch at era boundaries, when we try to submit a "next era" transaction as a "current era" transaction, or vice-versa. Similarly, TxValidationError shouldn't occur given that the transaction was safely constructed through buildTransaction.

Constructors

SubmitEraMismatch EraMismatch
SubmitTxValidationError TxValidationErrorInCardanoMode

Instances

Instances details

Exception SubmitTransactionException Source #
Instance details Defined in Hydra.Chain.CardanoClient Methods toException :: SubmitTransactionException -> SomeException Source # fromException :: SomeException -> Maybe SubmitTransactionException Source # displayException :: SubmitTransactionException -> String Source #
Show SubmitTransactionException Source #
Instance details Defined in Hydra.Chain.CardanoClient Methods showsPrec :: Int -> SubmitTransactionException -> ShowS Source # show :: SubmitTransactionException -> String Source # showList :: [SubmitTransactionException] -> ShowS Source #

awaitTransaction Source #

Arguments

:: NetworkId	Current network discriminant
-> SocketPath	Filepath to the cardano-node's domain socket
-> Tx	The transaction to watch / await
-> IO UTxO

Await until the given transaction is visible on-chain. Returns the UTxO set produced by that transaction.

Note that this function loops forever; hence, one probably wants to couple it with a surrounding timeout.

awaitTransactionId Source #

Arguments

:: NetworkId	Current network discriminant
-> SocketPath	Filepath to the cardano-node's domain socket
-> TxId	The transaction ID to watch / await
-> IO UTxO

Await until the given transaction id is visible on-chain. Returns the UTxO set produced by that transaction.

Note that this function loops forever; hence, one probably wants to couple it with a surrounding timeout.

Local state query

data QueryPoint Source #

Describes whether to query at the tip or at a specific point.

Constructors

QueryTip
QueryAt ChainPoint

Instances

Instances details

Generic QueryPoint Source #
Instance details Defined in Hydra.Chain.CardanoClient Associated Types type Rep QueryPoint :: Type -> Type Source # Methods from :: QueryPoint -> Rep QueryPoint x Source # to :: Rep QueryPoint x -> QueryPoint Source #
Show QueryPoint Source #
Instance details Defined in Hydra.Chain.CardanoClient Methods showsPrec :: Int -> QueryPoint -> ShowS Source # show :: QueryPoint -> String Source # showList :: [QueryPoint] -> ShowS Source #
Eq QueryPoint Source #
Instance details Defined in Hydra.Chain.CardanoClient Methods (==) :: QueryPoint -> QueryPoint -> Bool Source # (/=) :: QueryPoint -> QueryPoint -> Bool Source #
type Rep QueryPoint Source #
Instance details Defined in Hydra.Chain.CardanoClient type Rep QueryPoint = D1 ('MetaData "QueryPoint" "Hydra.Chain.CardanoClient" "hydra-node-0.21.0-4ibc00B6CCmF4EmjGjxvGm" 'False) (C1 ('MetaCons "QueryTip" 'PrefixI 'False) (U1 :: Type -> Type) :+: C1 ('MetaCons "QueryAt" 'PrefixI 'False) (S1 ('MetaSel ('Nothing :: Maybe Symbol) 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 ChainPoint)))

queryTip :: NetworkId -> SocketPath -> IO ChainPoint Source #

Query the latest chain point aka "the tip".

queryTipSlotNo :: NetworkId -> SocketPath -> IO SlotNo Source #

Query the latest chain point just for the slot number.

querySystemStart :: NetworkId -> SocketPath -> QueryPoint -> IO SystemStart Source #

Query the system start parameter at given point.

Throws at least QueryException if query fails.

queryEraHistory :: NetworkId -> SocketPath -> QueryPoint -> IO EraHistory Source #

Query the era history at given point.

Throws at least QueryException if query fails.

queryEpochNo :: NetworkId -> SocketPath -> QueryPoint -> IO EpochNo Source #

Query the current epoch number.

Throws at least QueryException if query fails.

queryProtocolParameters Source #

Arguments

:: NetworkId	Current network discriminant
-> SocketPath	Filepath to the cardano-node's domain socket
-> QueryPoint
-> IO (PParams LedgerEra)

Query the protocol parameters at given point and convert them to Babbage era protocol parameters.

Throws at least QueryException if query fails.

queryGenesisParameters Source #

Arguments

:: NetworkId	Current network discriminant
-> SocketPath	Filepath to the cardano-node's domain socket
-> QueryPoint
-> IO (GenesisParameters ShelleyEra)

Query GenesisParameters at a given point.

Throws at least QueryException if query fails.

queryUTxO :: NetworkId -> SocketPath -> QueryPoint -> [Address ShelleyAddr] -> IO UTxO Source #

Query UTxO for all given addresses at given point.

Throws at least QueryException if query fails.

queryUTxOExpr :: ShelleyBasedEra era -> [Address ShelleyAddr] -> LocalStateQueryExpr b p QueryInMode r IO UTxO Source #

queryUTxOByTxIn Source #

Arguments

:: NetworkId	Current network discriminant
-> SocketPath	Filepath to the cardano-node's domain socket
-> QueryPoint
-> [TxIn]
-> IO UTxO

Query UTxO for given tx inputs at given point.

Throws at least QueryException if query fails.

assumeShelleyBasedEraOrThrow :: MonadThrow m => CardanoEra era -> m (ShelleyBasedEra era) Source #

queryUTxOWhole Source #

Arguments

:: NetworkId	Current network discriminant
-> SocketPath	Filepath to the cardano-node's domain socket
-> QueryPoint
-> IO UTxO

Query the whole UTxO from node at given point. Useful for debugging, but should obviously not be used in production code.

Throws at least QueryException if query fails.

queryUTxOFor :: NetworkId -> SocketPath -> QueryPoint -> VerificationKey PaymentKey -> IO UTxO Source #

Query UTxO for the address of given verification key at point.

Throws at least QueryException if query fails.

queryStakePools Source #

Arguments

:: NetworkId	Current network discriminant
-> SocketPath	Filepath to the cardano-node's domain socket
-> QueryPoint
-> IO (Set PoolId)

Query the current set of registered stake pools.

Throws at least QueryException if query fails.

Helpers

queryCurrentEraExpr :: LocalStateQueryExpr b p QueryInMode r IO AnyCardanoEra Source #

Monadic query expression to get current era.

queryInShelleyBasedEraExpr Source #

Arguments

:: ShelleyBasedEra era	The current running era we can use to query the node
-> QueryInShelleyBasedEra era a
-> LocalStateQueryExpr b p QueryInMode r IO a

Monadic query expression for a QueryInShelleyBasedEra.

runQuery :: NetworkId -> SocketPath -> QueryPoint -> QueryInMode a -> IO a Source #

Throws at least QueryException if query fails.

runQueryExpr :: NetworkId -> SocketPath -> QueryPoint -> LocalStateQueryExpr BlockInMode ChainPoint QueryInMode () IO a -> IO a Source #

Throws at least QueryException if query fails.

throwOnEraMismatch :: MonadThrow m => Either EraMismatch a -> m a Source #

throwOnUnsupportedNtcVersion :: MonadThrow m => Either UnsupportedNtcVersionError a -> m a Source #

localNodeConnectInfo :: NetworkId -> SocketPath -> LocalNodeConnectInfo Source #

cardanoModeParams :: ConsensusModeParams Source #