cardano-api-1.36.0: The cardano api
Safe HaskellSafe-Inferred
LanguageHaskell2010

Cardano.Api.IPC

Description

Node IPC protocols

Synopsis

Node interaction

Operations that involve talking to a local Cardano node.

connectToLocalNodeLocalNodeConnectInfo mode → LocalNodeClientProtocolsInMode mode → IO () Source #

Establish a connection to a local node and execute the given set of protocol handlers.

connectToLocalNodeWithVersionLocalNodeConnectInfo mode → (NodeToClientVersionLocalNodeClientProtocolsInMode mode) → IO () Source #

Establish a connection to a local node and execute the given set of protocol handlers parameterized on the negotiated node-to-client protocol version.

data LocalNodeClientParams where Source #

This type defines the boundary between the mode-parametrised style used in this API and the block-parametrised style used by the underlying network and consensus libraries.

This interface itself is in the block-parametrised style, with the block type itself being an hidden/existential type.

It bundles together all the necessary class instances, the consensus protocol client identifier, and the set of client side mini-protocol handlers for the node-to-client protocol.

Constructors

LocalNodeClientParamsSingleBlock ∷ (ProtocolClient block, LedgerSupportsProtocol (ShelleyBlock (TPraos StandardCrypto) (ShelleyEra StandardCrypto))) ⇒ ProtocolClientInfoArgs block → (NodeToClientVersion → LocalNodeClientProtocolsForBlock block) → LocalNodeClientParams 
LocalNodeClientParamsCardano ∷ (ProtocolClient block, CardanoHardForkConstraints (ConsensusCryptoForBlock block)) ⇒ ProtocolClientInfoArgs block → (NodeToClientVersion → LocalNodeClientProtocolsForBlock block) → LocalNodeClientParams 

mkLocalNodeClientParams ∷ ∀ mode block. ConsensusBlockForMode mode ~ block ⇒ ConsensusModeParams mode → (NodeToClientVersionLocalNodeClientProtocolsInMode mode) → LocalNodeClientParams Source #

Convert from the mode-parametrised style to the block-parametrised style.

data LocalNodeClientProtocols block point tip slot tx txid txerr query m Source #

The protocols we can use with a local node. Use in conjunction with connectToLocalNode.

These protocols use the types from the rest of this API. The conversion to/from the types used by the underlying wire formats is handled by connectToLocalNode.

Modes

TODO move to Cardano.Api

data ByronMode Source #

The Byron-only consensus mode consists of only the Byron era.

This was used on the mainnet before the deployment of the multi-era CardanoMode. It is now of little practical use, though it illustrates how a single-era consensus mode works. It may be sensible to remove this at some stage.

Instances

Instances details
FromJSON (EraInMode ByronEra ByronMode) Source # 
Instance details

Defined in Cardano.Api.Modes

Methods

parseJSON ∷ Value → Parser (EraInMode ByronEra ByronMode) #

parseJSONList ∷ Value → Parser [EraInMode ByronEra ByronMode] #

data ShelleyMode Source #

The Shelley-only consensus mode consists of only the Shelley era.

This was used for the early Shelley testnets prior to the use of the multi-era CardanoMode. It is useful for setting up Shelley test networks (e.g. for benchmarking) without having to go through the complication of the hard fork from Byron to Shelley eras. It also shows how a single-era consensus mode works. It may be replaced by other single-era modes in future.

Instances

Instances details
FromJSON (EraInMode ShelleyEra ShelleyMode) Source # 
Instance details

Defined in Cardano.Api.Modes

Methods

parseJSON ∷ Value → Parser (EraInMode ShelleyEra ShelleyMode) #

parseJSONList ∷ Value → Parser [EraInMode ShelleyEra ShelleyMode] #

data CardanoMode Source #

The Cardano consensus mode consists of all the eras currently in use on the Cardano mainnet. This is currently: the ByronEra; ShelleyEra, AllegraEra and MaryEra, in that order.

This mode will be extended with new eras as the Cardano mainnet develops.

Instances

Instances details
FromJSON (EraInMode AllegraEra CardanoMode) Source # 
Instance details

Defined in Cardano.Api.Modes

Methods

parseJSON ∷ Value → Parser (EraInMode AllegraEra CardanoMode) #

parseJSONList ∷ Value → Parser [EraInMode AllegraEra CardanoMode] #

FromJSON (EraInMode AlonzoEra CardanoMode) Source # 
Instance details

Defined in Cardano.Api.Modes

Methods

parseJSON ∷ Value → Parser (EraInMode AlonzoEra CardanoMode) #

parseJSONList ∷ Value → Parser [EraInMode AlonzoEra CardanoMode] #

FromJSON (EraInMode BabbageEra CardanoMode) Source # 
Instance details

Defined in Cardano.Api.Modes

Methods

parseJSON ∷ Value → Parser (EraInMode BabbageEra CardanoMode) #

parseJSONList ∷ Value → Parser [EraInMode BabbageEra CardanoMode] #

FromJSON (EraInMode ByronEra CardanoMode) Source # 
Instance details

Defined in Cardano.Api.Modes

Methods

parseJSON ∷ Value → Parser (EraInMode ByronEra CardanoMode) #

parseJSONList ∷ Value → Parser [EraInMode ByronEra CardanoMode] #

FromJSON (EraInMode ConwayEra CardanoMode) Source # 
Instance details

Defined in Cardano.Api.Modes

Methods

parseJSON ∷ Value → Parser (EraInMode ConwayEra CardanoMode) #

parseJSONList ∷ Value → Parser [EraInMode ConwayEra CardanoMode] #

FromJSON (EraInMode MaryEra CardanoMode) Source # 
Instance details

Defined in Cardano.Api.Modes

Methods

parseJSON ∷ Value → Parser (EraInMode MaryEra CardanoMode) #

parseJSONList ∷ Value → Parser [EraInMode MaryEra CardanoMode] #

FromJSON (EraInMode ShelleyEra CardanoMode) Source # 
Instance details

Defined in Cardano.Api.Modes

Methods

parseJSON ∷ Value → Parser (EraInMode ShelleyEra CardanoMode) #

parseJSONList ∷ Value → Parser [EraInMode ShelleyEra CardanoMode] #

data ConsensusModeParams mode where Source #

The consensus-mode-specific parameters needed to connect to a local node that is using each consensus mode.

It is in fact only the Byron era that requires extra parameters, but this is of course inherited by the CardanoMode that uses the Byron era. The reason this parameter is needed stems from unfortunate design decisions from the legacy Byron era. The slots per epoch are needed to be able to decode epoch boundary blocks from the Byron era.

It is possible in future that we may be able to eliminate this parameter by discovering it from the node during the initial handshake.

Instances

Instances details
Show (ConsensusModeParams mode) Source # 
Instance details

Defined in Cardano.Api.Modes

newtype EpochSlots #

Constructors

EpochSlots 

Fields

Instances

Instances details
Data EpochSlots 
Instance details

Defined in Cardano.Chain.Slotting.EpochSlots

Methods

gfoldl ∷ (∀ d b. Data d ⇒ c (d → b) → d → c b) → (∀ g. g → c g) → EpochSlots → c EpochSlots Source #

gunfold ∷ (∀ b r. Data b ⇒ c (b → r) → c r) → (∀ r. r → c r) → Constr → c EpochSlots Source #

toConstrEpochSlotsConstr Source #

dataTypeOfEpochSlotsDataType Source #

dataCast1Typeable t ⇒ (∀ d. Data d ⇒ c (t d)) → Maybe (c EpochSlots) Source #

dataCast2Typeable t ⇒ (∀ d e. (Data d, Data e) ⇒ c (t d e)) → Maybe (c EpochSlots) Source #

gmapT ∷ (∀ b. Data b ⇒ b → b) → EpochSlotsEpochSlots Source #

gmapQl ∷ (r → r' → r) → r → (∀ d. Data d ⇒ d → r') → EpochSlots → r Source #

gmapQr ∷ ∀ r r'. (r' → r → r) → r → (∀ d. Data d ⇒ d → r') → EpochSlots → r Source #

gmapQ ∷ (∀ d. Data d ⇒ d → u) → EpochSlots → [u] Source #

gmapQiInt → (∀ d. Data d ⇒ d → u) → EpochSlots → u Source #

gmapMMonad m ⇒ (∀ d. Data d ⇒ d → m d) → EpochSlots → m EpochSlots Source #

gmapMpMonadPlus m ⇒ (∀ d. Data d ⇒ d → m d) → EpochSlots → m EpochSlots Source #

gmapMoMonadPlus m ⇒ (∀ d. Data d ⇒ d → m d) → EpochSlots → m EpochSlots Source #

Generic EpochSlots 
Instance details

Defined in Cardano.Chain.Slotting.EpochSlots

Associated Types

type Rep EpochSlotsTypeType Source #

Read EpochSlots 
Instance details

Defined in Cardano.Chain.Slotting.EpochSlots

Show EpochSlots 
Instance details

Defined in Cardano.Chain.Slotting.EpochSlots

FromCBOR EpochSlots 
Instance details

Defined in Cardano.Chain.Slotting.EpochSlots

Methods

fromCBOR ∷ Decoder s EpochSlots #

labelProxy EpochSlotsText #

ToCBOR EpochSlots 
Instance details

Defined in Cardano.Chain.Slotting.EpochSlots

Methods

toCBOREpochSlots → Encoding #

encodedSizeExpr ∷ (∀ t. ToCBOR t ⇒ Proxy t → Size) → Proxy EpochSlots → Size #

encodedListSizeExpr ∷ (∀ t. ToCBOR t ⇒ Proxy t → Size) → Proxy [EpochSlots] → Size #

Buildable EpochSlots 
Instance details

Defined in Cardano.Chain.Slotting.EpochSlots

Methods

buildEpochSlotsBuilder

Eq EpochSlots 
Instance details

Defined in Cardano.Chain.Slotting.EpochSlots

Ord EpochSlots 
Instance details

Defined in Cardano.Chain.Slotting.EpochSlots

NoThunks EpochSlots 
Instance details

Defined in Cardano.Chain.Slotting.EpochSlots

Methods

noThunks ∷ Context → EpochSlotsIO (Maybe ThunkInfo)

wNoThunks ∷ Context → EpochSlotsIO (Maybe ThunkInfo)

showTypeOfProxy EpochSlotsString

type Rep EpochSlots 
Instance details

Defined in Cardano.Chain.Slotting.EpochSlots

type Rep EpochSlots = D1 ('MetaData "EpochSlots" "Cardano.Chain.Slotting.EpochSlots" "cardano-ledger-byron-0.1.1.2-647fc26e974ce1211a0dc8aec4a08ca2c23d24a3124f962fa998d10443808e0c" 'True) (C1 ('MetaCons "EpochSlots" 'PrefixI 'True) (S1 ('MetaSel ('Just "unEpochSlots") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 Word64)))

Chain sync protocol

newtype ChainSyncClient header point tip (m ∷ TypeType) a #

Constructors

ChainSyncClient 

Fields

newtype ChainSyncClientPipelined header point tip (m ∷ TypeTYPE LiftedRep) a #

Constructors

ChainSyncClientPipelined 

Fields

data BlockInMode mode where Source #

A Block in one of the eras supported by a given protocol mode.

For multi-era modes such as the CardanoMode this type is a sum of the different block types for all the eras. It is used in the ChainSync protocol.

Constructors

BlockInModeIsCardanoEra era ⇒ Block era → EraInMode era mode → BlockInMode mode 

Instances

Instances details
Show (BlockInMode mode) Source # 
Instance details

Defined in Cardano.Api.Block

Methods

showsPrecIntBlockInMode mode → ShowS Source #

showBlockInMode mode → String Source #

showList ∷ [BlockInMode mode] → ShowS Source #

Local tx submission

newtype LocalTxSubmissionClient tx reject (m ∷ TypeType) a #

Constructors

LocalTxSubmissionClient 

Fields

data TxInMode mode where Source #

A Tx in one of the eras supported by a given protocol mode.

For multi-era modes such as the CardanoMode this type is a sum of the different transaction types for all the eras. It is used in the LocalTxSubmission protocol.

Constructors

TxInModeTx era → EraInMode era mode → TxInMode mode

Everything we consider a normal transaction.

TxInByronSpecial ∷ GenTx ByronBlock → EraInMode ByronEra mode → TxInMode mode

Byron has various things we can post to the chain which are not actually transactions. This covers: update proposals, votes and delegation certs.

Instances

Instances details
Show (TxInMode mode) Source # 
Instance details

Defined in Cardano.Api.InMode

Methods

showsPrecIntTxInMode mode → ShowS Source #

showTxInMode mode → String Source #

showList ∷ [TxInMode mode] → ShowS Source #

data TxValidationErrorInMode mode where Source #

A TxValidationError in one of the eras supported by a given protocol mode.

This is used in the LocalStateQuery protocol.

Instances

Instances details
Show (TxValidationErrorInMode mode) Source # 
Instance details

Defined in Cardano.Api.InMode

data TxValidationError era Source #

The transaction validations errors that can occur from trying to submit a transaction to a local node. The errors are specific to an era.

Instances

Instances details
Show (TxValidationError era) Source # 
Instance details

Defined in Cardano.Api.InMode

data SubmitResult reason #

Constructors

SubmitSuccess 
SubmitFail reason 

Instances

Instances details
Functor SubmitResult 
Instance details

Defined in Ouroboros.Network.Protocol.LocalTxSubmission.Type

Methods

fmap ∷ (a → b) → SubmitResult a → SubmitResult b Source #

(<$) ∷ a → SubmitResult b → SubmitResult a Source #

Eq reason ⇒ Eq (SubmitResult reason) 
Instance details

Defined in Ouroboros.Network.Protocol.LocalTxSubmission.Type

Methods

(==)SubmitResult reason → SubmitResult reason → Bool Source #

(/=)SubmitResult reason → SubmitResult reason → Bool Source #

Local state query

newtype LocalStateQueryClient block point (query ∷ TypeType) (m ∷ TypeType) a #

Constructors

LocalStateQueryClient 

Fields

data AcquiringFailure Source #

Establish a connection to a node and execute a single query using the local state query protocol.

data QueryInMode mode result where Source #

Instances

Instances details
Show (QueryInMode mode result) Source # 
Instance details

Defined in Cardano.Api.Query

Methods

showsPrecIntQueryInMode mode result → ShowS Source #

showQueryInMode mode result → String Source #

showList ∷ [QueryInMode mode result] → ShowS Source #

NodeToClientVersionOf (QueryInMode mode result) Source # 
Instance details

Defined in Cardano.Api.Query

data QueryInEra era result where Source #

Constructors

QueryByronUpdateStateQueryInEra ByronEra ByronUpdateState 
QueryInShelleyBasedEraShelleyBasedEra era → QueryInShelleyBasedEra era result → QueryInEra era result 

Instances

Instances details
Show (QueryInEra era result) Source # 
Instance details

Defined in Cardano.Api.Query

Methods

showsPrecIntQueryInEra era result → ShowS Source #

showQueryInEra era result → String Source #

showList ∷ [QueryInEra era result] → ShowS Source #

NodeToClientVersionOf (QueryInEra era result) Source # 
Instance details

Defined in Cardano.Api.Query

data QueryInShelleyBasedEra era result where Source #

Instances

Instances details
Show (QueryInShelleyBasedEra era result) Source # 
Instance details

Defined in Cardano.Api.Query

NodeToClientVersionOf (QueryInShelleyBasedEra era result) Source # 
Instance details

Defined in Cardano.Api.Query

queryNodeLocalState ∷ ∀ mode result. LocalNodeConnectInfo mode → Maybe ChainPointQueryInMode mode result → IO (Either AcquiringFailure result) Source #

Local tx monitoring

newtype LocalTxMonitorClient txid tx slot (m ∷ TypeType) a #

Constructors

LocalTxMonitorClient 

Fields

data LocalTxMonitoringQuery mode Source #

Constructors

LocalTxMonitoringQueryTx (TxIdInMode mode)

Query if a particular tx exists in the mempool. Note that, the absence of a transaction does not imply anything about how the transaction was processed: it may have been dropped, or inserted in a block.

LocalTxMonitoringSendNextTx

The mempool is modeled as an ordered list of transactions and thus, can be traversed linearly. LocalTxMonitoringSendNextTx requests the next transaction from the current list. This must be a transaction that was not previously sent to the client for this particular snapshot.

LocalTxMonitoringMempoolInformation

Ask the server about the current mempool's capacity and sizes. This is fixed in a given snapshot.

data LocalTxMonitoringResult mode Source #

Constructors

LocalTxMonitoringTxExists TxId SlotNo

Slot number at which the mempool snapshot was taken

LocalTxMonitoringTxDoesNotExist TxId SlotNo

Slot number at which the mempool snapshot was taken

LocalTxMonitoringNextTx (Maybe (TxInMode mode)) SlotNo

Slot number at which the mempool snapshot was taken

LocalTxMonitoringMempoolSizeAndCapacity MempoolSizeAndCapacity SlotNo

Slot number at which the mempool snapshot was taken

Instances

Instances details
ToJSON (LocalTxMonitoringResult mode) Source # 
Instance details

Defined in Cardano.Api.IPC

Methods

toJSONLocalTxMonitoringResult mode → Value #

toEncodingLocalTxMonitoringResult mode → Encoding #

toJSONList ∷ [LocalTxMonitoringResult mode] → Value #

toEncodingList ∷ [LocalTxMonitoringResult mode] → Encoding #

data MempoolSizeAndCapacity #

Instances

Instances details
Generic MempoolSizeAndCapacity 
Instance details

Defined in Ouroboros.Network.Protocol.LocalTxMonitor.Type

Associated Types

type Rep MempoolSizeAndCapacityTypeType Source #

Show MempoolSizeAndCapacity 
Instance details

Defined in Ouroboros.Network.Protocol.LocalTxMonitor.Type

Eq MempoolSizeAndCapacity 
Instance details

Defined in Ouroboros.Network.Protocol.LocalTxMonitor.Type

type Rep MempoolSizeAndCapacity 
Instance details

Defined in Ouroboros.Network.Protocol.LocalTxMonitor.Type

type Rep MempoolSizeAndCapacity = D1 ('MetaData "MempoolSizeAndCapacity" "Ouroboros.Network.Protocol.LocalTxMonitor.Type" "ouroboros-network-protocols-0.3.0.0-a5c03edf74359322ebf0740b15593c6d62479c8337729a353281cef37af6b746" 'False) (C1 ('MetaCons "MempoolSizeAndCapacity" 'PrefixI 'True) (S1 ('MetaSel ('Just "capacityInBytes") 'NoSourceUnpackedness 'SourceStrict 'DecidedUnpack) (Rec0 Word32) :*: (S1 ('MetaSel ('Just "sizeInBytes") 'NoSourceUnpackedness 'SourceStrict 'DecidedUnpack) (Rec0 Word32) :*: S1 ('MetaSel ('Just "numberOfTxs") 'NoSourceUnpackedness 'SourceStrict 'DecidedUnpack) (Rec0 Word32))))

data EraHistory mode where Source #

Constructors

EraHistoryConsensusBlockForMode mode ~ HardForkBlock xs ⇒ ConsensusMode mode → Interpreter xs → EraHistory mode 

getProgressSlotNoEraHistory mode → Either PastHorizonException (RelativeTime, SlotLength) Source #

Common queries

Helpers

data ConsensusMode mode where Source #

This GADT provides a value-level representation of all the consensus modes. This enables pattern matching on the era to allow them to be treated in a non-uniform way.

Instances

Instances details
Show (ConsensusMode mode) Source # 
Instance details

Defined in Cardano.Api.Modes

data NodeToClientVersion #

Instances

Instances details
Bounded NodeToClientVersion 
Instance details

Defined in Ouroboros.Network.NodeToClient.Version

Enum NodeToClientVersion 
Instance details

Defined in Ouroboros.Network.NodeToClient.Version

Show NodeToClientVersion 
Instance details

Defined in Ouroboros.Network.NodeToClient.Version

Eq NodeToClientVersion 
Instance details

Defined in Ouroboros.Network.NodeToClient.Version

Ord NodeToClientVersion 
Instance details

Defined in Ouroboros.Network.NodeToClient.Version

MonadReader NodeToClientVersion (LocalStateQueryExpr block point query r m) Source # 
Instance details

Defined in Cardano.Api.IPC.Monad

Methods

askLocalStateQueryExpr block point query r m NodeToClientVersion Source #

local ∷ (NodeToClientVersionNodeToClientVersion) → LocalStateQueryExpr block point query r m a → LocalStateQueryExpr block point query r m a Source #

reader ∷ (NodeToClientVersion → a) → LocalStateQueryExpr block point query r m a Source #