Safe Haskell | Safe-Inferred |
---|---|
Language | GHC2021 |
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
- buildTransaction :: NetworkId -> SocketPath -> AddressInEra -> UTxO -> [TxIn] -> [TxOut CtxTx] -> IO (Either (TxBodyErrorAutoBalance Era) TxBody)
- submitTransaction :: NetworkId -> SocketPath -> Tx -> IO ()
- data SubmitTransactionException
- = SubmitEraMismatch EraMismatch
- | SubmitTxValidationError TxValidationErrorInCardanoMode
- awaitTransaction :: NetworkId -> SocketPath -> Tx -> IO UTxO
- data QueryPoint
- 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)
- queryProtocolParameters' :: IsShelleyBasedEra era => NetworkId -> SocketPath -> QueryPoint -> IO (PParams (ShelleyLedgerEra era))
- 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 #
QueryAcquireException AcquiringFailure | |
QueryEraMismatchException EraMismatch | |
QueryProtocolParamsConversionException ProtocolParametersConversionError | |
QueryProtocolParamsEraNotSupported AnyCardanoEra | |
QueryProtocolParamsEncodingFailureOnEra AnyCardanoEra Text | |
QueryEraNotInCardanoModeFailure AnyCardanoEra | |
QueryNotShelleyBasedEraException AnyCardanoEra |
Instances
Exception QueryException Source # | |
Defined in Hydra.Chain.CardanoClient | |
Show QueryException Source # | |
Defined in Hydra.Chain.CardanoClient | |
Eq QueryException Source # | |
Defined in Hydra.Chain.CardanoClient (==) :: QueryException -> QueryException -> Bool Source # (/=) :: QueryException -> QueryException -> Bool Source # |
CardanoClient handle
data CardanoClient Source #
Handle interface for abstract querying of a cardano node.
CardanoClient | |
|
mkCardanoClient :: NetworkId -> SocketPath -> CardanoClient Source #
Construct a CardanoClient
handle.
Tx Construction / Submission
:: 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) TxBody) |
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
.
:: 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
.
SubmitEraMismatch EraMismatch | |
SubmitTxValidationError TxValidationErrorInCardanoMode |
Instances
:: 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.
Local state query
data QueryPoint Source #
Describes whether to query at the tip or at a specific point.
Instances
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 #
:: 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.
queryProtocolParameters' Source #
:: IsShelleyBasedEra era | |
=> NetworkId | Current network discriminant |
-> SocketPath | Filepath to the cardano-node's domain socket |
-> QueryPoint | |
-> IO (PParams (ShelleyLedgerEra era)) |
Query the protocol parameters at given point. NOTE: If the era is not matching this fails with an era mismatch.
Throws at least QueryException
if query fails.
queryGenesisParameters Source #
:: 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 #
:: 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 #
:: 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.
:: 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 #
:: 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 #