Copyright	© 2020 IOHK
License	Apache-2.0
Safe Haskell	None
Language	Haskell2010

Ouroboros.Network.Client.Wallet

Contents

ChainSyncFollowTip
ChainSyncWithBlocks
LocalTxSubmission
LocalStateQuery
Helpers

Description

Ouroboros mini-protocols clients for implementing cardano-wallet. These clients implement the logic and lift away concerns related to concrete data-type representation so that the code can be re-used / shared between Byron and Shelley.

Synopsis

chainSyncFollowTip :: forall m block era. Monad m => (block -> era) -> ( Maybe era -> Tip block -> m ()) -> ChainSyncClient block ( Point block) ( Tip block) m Void
chainSyncWithBlocks :: forall m block. ( Monad m, MonadSTM m, MonadThrow m, HasHeader block) => Tracer m ( ChainSyncLog block ( Point block)) -> PipeliningStrategy block -> ChainFollower m ( Point block) ( Tip block) ( NonEmpty block) -> ChainSyncClientPipelined block ( Point block) ( Tip block) m Void
data PipeliningStrategy block = PipeliningStrategy {
- getPipeliningSize :: block -> Natural
- pipeliningStrategyName :: Text
}
thousandPipeliningStrategy :: PipeliningStrategy block
tunedForMainnetPipeliningStrategy :: HasHeader block => PipeliningStrategy block
data LocalTxSubmissionCmd tx err (m :: Type -> Type ) = CmdSubmitTx tx ( SubmitResult err -> m ())
localTxSubmission :: forall m tx err. ( MonadThrow m, MonadSTM m) => TQueue m ( LocalTxSubmissionCmd tx err m) -> LocalTxSubmissionClient tx err m ()
data LSQ block (m :: Type -> Type ) a where
- LSQPure :: a -> LSQ block m a
- LSQBind :: LSQ block m a -> (a -> LSQ block m b) -> LSQ block m b
- LSQry :: BlockQuery block res -> LSQ block m res
data LocalStateQueryCmd block m = forall a. SomeLSQ ( LSQ block m a) (a -> m ())
localStateQuery :: forall m block. ( MonadIO m, MonadSTM m) => TQueue m ( LocalStateQueryCmd block m) -> LocalStateQueryClient block ( Point block) ( Query block) m Void
send :: MonadSTM m => TQueue m (cmd m) -> ((a -> m ()) -> cmd m) -> m a

ChainSyncFollowTip

chainSyncFollowTip Source #

Arguments

:: forall m block era. Monad m
=> (block -> era)
-> ( Maybe era -> Tip block -> m ())	Callback for when the tip changes.
-> ChainSyncClient block ( Point block) ( Tip block) m Void

Client for the 'Chain Sync' mini-protocol, which provides notifications when the node tip changes.

This is used in the same way as chainSyncWithBlocks , except that only one of these clients is necessary, rather than one client per wallet.

ChainSyncWithBlocks

chainSyncWithBlocks :: forall m block. ( Monad m, MonadSTM m, MonadThrow m, HasHeader block) => Tracer m ( ChainSyncLog block ( Point block)) -> PipeliningStrategy block -> ChainFollower m ( Point block) ( Tip block) ( NonEmpty block) -> ChainSyncClientPipelined block ( Point block) ( Tip block) m Void Source #

Client for the 'Chain Sync' mini-protocol.

Once started, the client simply runs ad-infinitum but one may interact with it via a TQueue of commands / messages used to move inside the state-machine.

In a typical usage, chainSyncWithBlocks would be executed in a forked thread and given a TQueue over which the parent thread as control.

>>> forkIO $ void $ chainSyncWithBlocks tr queue channel
()
>>> writeTQueue queue ...

Agency ------------------------------------------------------------------------- Client has agency* | Idle Server has agency* | Intersect, Next

A peer has agency if it is expected to send the next message.
-----------* | Intersect |◀══════════════════════════════╗
-----------* FindIntersect ║ │ ║ │ *---------* *------* │ Intersect.{Found,NotFound} | |═════════════▶| Done | └───────────────────────────────╼| | MsgDone *------* | Idle | ╔═══════════════════════════════════| | ║ RequestNext | |⇦ START ║ *---------* ▼ ╿
------* Roll.{Backward,Forward} │ | Next |────────────────────────────────────┘
------*

data PipeliningStrategy block Source #

How to drive pipelining size from the block height

Constructors

PipeliningStrategy
Fields getPipeliningSize :: block -> Natural pipeliningStrategyName :: Text

Instances

Instances details

Show ( PipeliningStrategy block) Source #
Instance details Defined in Ouroboros.Network.Client.Wallet Methods showsPrec :: Int -> PipeliningStrategy block -> ShowS Source # show :: PipeliningStrategy block -> String Source # showList :: [ PipeliningStrategy block] -> ShowS Source #

thousandPipeliningStrategy :: PipeliningStrategy block Source #

tunedForMainnetPipeliningStrategy :: HasHeader block => PipeliningStrategy block Source #

LocalTxSubmission

data LocalTxSubmissionCmd tx err (m :: Type -> Type ) Source #

Type of commands that are stored in a queue for localTxSubmission.

Constructors

CmdSubmitTx tx ( SubmitResult err -> m ())

localTxSubmission Source #

Arguments

:: forall m tx err. ( MonadThrow m, MonadSTM m)
=> TQueue m ( LocalTxSubmissionCmd tx err m)	We use a `TQueue` as a communication channel to drive queries from outside of the network client to the client itself. Requests are pushed to the queue which are then transformed into messages to keep the state-machine moving.
-> LocalTxSubmissionClient tx err m ()

Client for the 'Local Tx Submission' mini-protocol.

Agency ------------------------------------------------------------------------- Client has agency* | Idle Server has agency* | Busy * A peer has agency if it is expected to send the next message.

-----------* | Busy |◀══════════════════════════════╗
-----------* SubmitTx ║ │ │ ║ │ │ *---------* *------* │ │ AcceptTx | |═════════════▶| Done | │ └────────────────────────────╼| | MsgDone *------* │ RejectTx | Idle | └──────────────────────────────────╼| | | |⇦ START
---------*

LocalStateQuery

data LSQ block (m :: Type -> Type ) a where Source #

Monad for composing local state queries for the node tip .

Warning : Partial functions inside the LSQ monad may cause the entire wallet to crash when interpreted by localStateQuery .

Constructors

LSQPure :: a -> LSQ block m a
LSQBind :: LSQ block m a -> (a -> LSQ block m b) -> LSQ block m b
LSQry :: BlockQuery block res -> LSQ block m res	A local state query.

Instances

Instances details

Monad ( LSQ block m) Source #
Instance details Defined in Ouroboros.Network.Client.Wallet Methods (>>=) :: LSQ block m a -> (a -> LSQ block m b) -> LSQ block m b Source # (>>) :: LSQ block m a -> LSQ block m b -> LSQ block m b Source # return :: a -> LSQ block m a Source #
Functor ( LSQ block m) Source #
Instance details Defined in Ouroboros.Network.Client.Wallet Methods fmap :: (a -> b) -> LSQ block m a -> LSQ block m b Source # (<$) :: a -> LSQ block m b -> LSQ block m a Source #
Applicative ( LSQ block m) Source #
Instance details Defined in Ouroboros.Network.Client.Wallet Methods pure :: a -> LSQ block m a Source # (<>) :: LSQ block m (a -> b) -> LSQ block m a -> LSQ block m b Source # liftA2 :: (a -> b -> c) -> LSQ block m a -> LSQ block m b -> LSQ block m c Source # (>) :: LSQ block m a -> LSQ block m b -> LSQ block m b Source # (<*) :: LSQ block m a -> LSQ block m b -> LSQ block m a Source #

data LocalStateQueryCmd block m Source #

Type of commands that are stored in a queue for local state queries.

Constructors

forall a. SomeLSQ ( LSQ block m a) (a -> m ())

localStateQuery Source #

Arguments

:: forall m block. ( MonadIO m, MonadSTM m)
=> TQueue m ( LocalStateQueryCmd block m)	We use a `TQueue` as a communication channel to drive queries from outside of the network client to the client itself. Requests are pushed to the queue which are then transformed into messages to keep the state-machine moving.
-> LocalStateQueryClient block ( Point block) ( Query block) m Void

Client for the 'Local State Query' mini-protocol.

Agency ------------------------------------------------------------------------- Client has agency* | Idle, Acquired Server has agency* | Acquiring, Querying * A peer has agency if it is expected to send the next message.

┌───────────────┐ Done ┌──────────┐ ┌──────▶│ Idle ├─────────────▶│ Done │ │ └───┬───────────┘ └──────────┘ │ │ ▲ │ Acquire │ │ │ │ │ Failure │ ▼ │ │ ┌───────────┴───┐ │ │ Acquiring │ │ └───┬───────────┘ Release│ │ ▲ │ │ │ │ Acquired │ │ ReAcquire │ │ │ │ ▼ │ │ ┌───────────┴───┐ Query ┌──────────┐ └───────┤ Acquired ├────────────▶│ Querying │ │ │◀────────────┤ │ └───────────────┘ Result └──────────┘

Helpers

send :: MonadSTM m => TQueue m (cmd m) -> ((a -> m ()) -> cmd m) -> m a Source #

Helper function to send commands to the node via a TQueue and receive results.

One of the main purposes of this functions is to handle an existentially quantified type. In typical use, the cmd m involves existential quantification over the type a , so that the TQueue has elements with a monomorphic type. However, the type signature of send allows us to retrieve this particular type a for later use again.