Safe Haskell	None
Language	Haskell2010

Cardano.Wallet.Network

Contents

Interface
Errors
Chain following
Logging (for testing)

Synopsis

data NetworkLayer m block = NetworkLayer {
- chainSync :: Tracer IO ChainFollowLog -> ChainFollower m ChainPoint BlockHeader ( NonEmpty block) -> m ()
- lightSync :: Maybe ( ChainFollower m ChainPoint BlockHeader (LightBlocks m Block ) -> m ())
- currentNodeTip :: m BlockHeader
- currentNodeEra :: m AnyCardanoEra
- currentProtocolParameters :: m ProtocolParameters
- currentSlottingParameters :: m SlottingParameters
- watchNodeTip :: ( BlockHeader -> m ()) -> m ()
- postTx :: SealedTx -> ExceptT ErrPostTx m ()
- stakeDistribution :: Coin -> m StakePoolsSummary
- getCachedRewardAccountBalance :: RewardAccount -> m Coin
- fetchRewardAccountBalances :: Set RewardAccount -> m ( Map RewardAccount Coin )
- timeInterpreter :: TimeInterpreter ( ExceptT PastHorizonException m)
- syncProgress :: SlotNo -> m SyncProgress
}
newtype ErrPostTx = ErrPostTxValidationError Text
data ChainFollower m point tip blocks = ChainFollower {
- checkpointPolicy :: Integer -> CheckpointPolicy
- readChainPoints :: m [point]
- rollForward :: blocks -> tip -> m ()
- rollBackward :: point -> m point
}
mapChainFollower :: Functor m => (point1 -> point2) -> (point2 -> point1) -> (tip2 -> tip1) -> (blocks2 -> blocks1) -> ChainFollower m point1 tip1 blocks1 -> ChainFollower m point2 tip2 blocks2
data ChainFollowLog
- = MsgChainSync ( ChainSyncLog BlockHeader ChainPoint )
- | MsgFollowStats ( FollowStats Rearview )
- | MsgStartFollowing
data ChainSyncLog block point
- = MsgChainFindIntersect [point]
- | MsgChainRollForward ( NonEmpty block) point
- | MsgChainRollBackward point Int
- | MsgChainTip point
- | MsgLocalTip point
- | MsgTipDistance Natural
mapChainSyncLog :: (b1 -> b2) -> (p1 -> p2) -> ChainSyncLog b1 p1 -> ChainSyncLog b2 p2
withFollowStatsMonitoring :: Tracer IO ChainFollowLog -> ( SlotNo -> IO SyncProgress ) -> ( Tracer IO ( ChainSyncLog BlockHeader ChainPoint ) -> IO ()) -> IO ()
data FollowStats f = FollowStats {
- blocksApplied :: !(f Int )
- rollbacks :: !(f Int )
- localTip :: !(f ChainPoint )
- time :: !(f UTCTime )
- prog :: !(f SyncProgress )
}
data Rearview a = Rearview {
- past :: !a
- current :: !a
}
emptyStats :: UTCTime -> FollowStats Rearview
updateStats :: ChainSyncLog block ChainPoint -> FollowStats Rearview -> FollowStats Rearview

Interface

data NetworkLayer m block Source #

Interface for network capabilities.

Constructors

NetworkLayer

Fields

chainSync :: Tracer IO ChainFollowLog -> ChainFollower m ChainPoint BlockHeader ( NonEmpty block) -> m ()

Connect to the node and run the ChainSync protocol. The callbacks provided in the ChainFollower argument are used to handle intersection finding, the arrival of new blocks, and rollbacks.
lightSync :: Maybe ( ChainFollower m ChainPoint BlockHeader (LightBlocks m Block ) -> m ())

Connect to a data source that offers an efficient query Address -> Transactions .
currentNodeTip :: m BlockHeader

Get the current tip from the chain producer
currentNodeEra :: m AnyCardanoEra

Get the era the node is currently in.
currentProtocolParameters :: m ProtocolParameters

Get the last known protocol parameters. In principle, these can only change once per epoch.
currentSlottingParameters :: m SlottingParameters

Get the last known slotting parameters. In principle, these can only change once per era.
watchNodeTip :: ( BlockHeader -> m ()) -> m ()

Register a callback for when the node tip changes. This function should never finish, unless the callback throws an exception, which will be rethrown by this function.
postTx :: SealedTx -> ExceptT ErrPostTx m ()

Broadcast a transaction to the chain producer
stakeDistribution :: Coin -> m StakePoolsSummary
getCachedRewardAccountBalance :: RewardAccount -> m Coin

Return the cached reward balance of an account.

If there is no cached value, it will return `Coin 0`, and add the account to the internal set of observed account, such that it will be fetched later.
fetchRewardAccountBalances :: Set RewardAccount -> m ( Map RewardAccount Coin )

Fetch the reward account balance of a set of accounts without any caching.
timeInterpreter :: TimeInterpreter ( ExceptT PastHorizonException m)
syncProgress :: SlotNo -> m SyncProgress

Compute the ratio between the provided SlotNo and the slot corresponding to the current wall-clock time.

Unlike using syncProgress after retrieving a timeInterpreter , this function will return NotResponding rather than block in the edge case when the era history has not yet been fetched from the node on startup.

Instances

Instances details

Functor m => Functor ( NetworkLayer m) Source #
Instance details Defined in Cardano.Wallet.Network Methods fmap :: (a -> b) -> NetworkLayer m a -> NetworkLayer m b Source # (<$) :: a -> NetworkLayer m b -> NetworkLayer m a Source #

Errors

newtype ErrPostTx Source #

Error while trying to send a transaction

Constructors

ErrPostTxValidationError Text

Instances

Instances details

Eq ErrPostTx Source #
Instance details Defined in Cardano.Wallet.Network Methods (==) :: ErrPostTx -> ErrPostTx -> Bool Source # (/=) :: ErrPostTx -> ErrPostTx -> Bool Source #
Show ErrPostTx Source #
Instance details Defined in Cardano.Wallet.Network Methods showsPrec :: Int -> ErrPostTx -> ShowS Source # show :: ErrPostTx -> String Source # showList :: [ ErrPostTx ] -> ShowS Source #
Generic ErrPostTx Source #
Instance details Defined in Cardano.Wallet.Network Associated Types type Rep ErrPostTx :: Type -> Type Source # Methods from :: ErrPostTx -> Rep ErrPostTx x Source # to :: Rep ErrPostTx x -> ErrPostTx Source #
ToText ErrPostTx Source #
Instance details Defined in Cardano.Wallet.Network Methods toText :: ErrPostTx -> Text Source #
IsServerError ErrPostTx Source #
Instance details Defined in Cardano.Wallet.Api.Server Methods toServerError :: ErrPostTx -> ServerError Source #
type Rep ErrPostTx Source #
Instance details Defined in Cardano.Wallet.Network type Rep ErrPostTx = D1 (' MetaData "ErrPostTx" "Cardano.Wallet.Network" "cardano-wallet-core-2022.7.1-AGKhlyz9liLKN3QqZD1gj" ' True ) ( C1 (' MetaCons "ErrPostTxValidationError" ' PrefixI ' False ) ( S1 (' MetaSel (' Nothing :: Maybe Symbol ) ' NoSourceUnpackedness ' NoSourceStrictness ' DecidedLazy ) ( Rec0 Text )))

Chain following

data ChainFollower m point tip blocks Source #

A collection of callbacks to use with the chainSync function.

Constructors

ChainFollower

Fields

checkpointPolicy :: Integer -> CheckpointPolicy

The policy for creating and pruning checkpoints that is used by the ChainFollower . The argument of this field is the epochStability .

Exposing this policy here enables any chain synchronizer which does not retrieve full blocks, such as lightSync , to specifically target those block heights at which the ChainFollower intends to create checkpoints.
readChainPoints :: m [point]

Callback for reading the local tip. Used to negotiate the intersection with the node.

A response of [] is interpreted as Origin -- i.e. the chain will be served from genesis.
rollForward :: blocks -> tip -> m ()

Callback for rolling forward.

Implementors _may_ delete old checkpoints while rolling forward.
rollBackward :: point -> m point
Roll back to the requested slot, or further, and return the point actually rolled back to.

Example 1:

If the follower stores checkpoints for all blocks, we can always roll back to the requested point exactly.
```
-- If
knownSlots follower shouldReturn [0,1,2,3]
let requested = SlotNo 2
-- Then
actual <- rollBackward follower requested
knownSlots follower shouldReturn` [0,1,2]
actual shouldBe SlotNo 2
```
Note that the slotNos are unlikely to be consecutive in real life, but this doesn't matter, as ouroboros-network asks us to rollback to points, corresponding to blocks.

Example 2:
```
-- If
knownSlots follower shouldReturn [0,9,10]
let requested = SlotNo 2
-- Then
actual <- rollBackward follower requested
knownSlots follower shouldReturn` [0]
actual shouldBe SlotNo 0
```

mapChainFollower Source #

Arguments

:: Functor m
=> (point1 -> point2)	Covariant
-> (point2 -> point1)	Contravariant
-> (tip2 -> tip1)	Contravariant
-> (blocks2 -> blocks1)	Contravariant
-> ChainFollower m point1 tip1 blocks1
-> ChainFollower m point2 tip2 blocks2

data ChainFollowLog Source #

Higher level log of a chain follower. Includes computed statistics about synchronization progress.

Constructors

MsgChainSync ( ChainSyncLog BlockHeader ChainPoint )
MsgFollowStats ( FollowStats Rearview )
MsgStartFollowing

Instances

Instances details

Eq ChainFollowLog Source #
Instance details Defined in Cardano.Wallet.Network Methods (==) :: ChainFollowLog -> ChainFollowLog -> Bool Source # (/=) :: ChainFollowLog -> ChainFollowLog -> Bool Source #
Show ChainFollowLog Source #
Instance details Defined in Cardano.Wallet.Network Methods showsPrec :: Int -> ChainFollowLog -> ShowS Source # show :: ChainFollowLog -> String Source # showList :: [ ChainFollowLog ] -> ShowS Source #
Generic ChainFollowLog Source #
Instance details Defined in Cardano.Wallet.Network Associated Types type Rep ChainFollowLog :: Type -> Type Source # Methods from :: ChainFollowLog -> Rep ChainFollowLog x Source # to :: Rep ChainFollowLog x -> ChainFollowLog Source #
ToText ChainFollowLog Source #
Instance details Defined in Cardano.Wallet.Network Methods toText :: ChainFollowLog -> Text Source #
HasPrivacyAnnotation ChainFollowLog Source #
Instance details Defined in Cardano.Wallet.Network Methods getPrivacyAnnotation :: ChainFollowLog -> PrivacyAnnotation
HasSeverityAnnotation ChainFollowLog Source #
Instance details Defined in Cardano.Wallet.Network Methods getSeverityAnnotation :: ChainFollowLog -> Severity
type Rep ChainFollowLog Source #
Instance details Defined in Cardano.Wallet.Network type Rep ChainFollowLog = D1 (' MetaData "ChainFollowLog" "Cardano.Wallet.Network" "cardano-wallet-core-2022.7.1-AGKhlyz9liLKN3QqZD1gj" ' False ) ( C1 (' MetaCons "MsgChainSync" ' PrefixI ' False ) ( S1 (' MetaSel (' Nothing :: Maybe Symbol ) ' NoSourceUnpackedness ' NoSourceStrictness ' DecidedLazy ) ( Rec0 ( ChainSyncLog BlockHeader ChainPoint ))) :+: ( C1 (' MetaCons "MsgFollowStats" ' PrefixI ' False ) ( S1 (' MetaSel (' Nothing :: Maybe Symbol ) ' NoSourceUnpackedness ' NoSourceStrictness ' DecidedLazy ) ( Rec0 ( FollowStats Rearview ))) :+: C1 (' MetaCons "MsgStartFollowing" ' PrefixI ' False ) ( U1 :: Type -> Type )))

data ChainSyncLog block point Source #

Low-level logs of the ChainSync mini-protocol

Constructors

MsgChainFindIntersect [point]
MsgChainRollForward ( NonEmpty block) point
MsgChainRollBackward point Int
MsgChainTip point
MsgLocalTip point
MsgTipDistance Natural

Instances

Instances details

( Eq point, Eq block) => Eq ( ChainSyncLog block point) Source #
Instance details Defined in Cardano.Wallet.Network Methods (==) :: ChainSyncLog block point -> ChainSyncLog block point -> Bool Source # (/=) :: ChainSyncLog block point -> ChainSyncLog block point -> Bool Source #
( Show point, Show block) => Show ( ChainSyncLog block point) Source #
Instance details Defined in Cardano.Wallet.Network Methods showsPrec :: Int -> ChainSyncLog block point -> ShowS Source # show :: ChainSyncLog block point -> String Source # showList :: [ ChainSyncLog block point] -> ShowS Source #
Generic ( ChainSyncLog block point) Source #
Instance details Defined in Cardano.Wallet.Network Associated Types type Rep ( ChainSyncLog block point) :: Type -> Type Source # Methods from :: ChainSyncLog block point -> Rep ( ChainSyncLog block point) x Source # to :: Rep ( ChainSyncLog block point) x -> ChainSyncLog block point Source #
ToText ( ChainSyncLog BlockHeader ChainPoint ) Source #
Instance details Defined in Cardano.Wallet.Network Methods toText :: ChainSyncLog BlockHeader ChainPoint -> Text Source #
HasPrivacyAnnotation ( ChainSyncLog block point) Source #
Instance details Defined in Cardano.Wallet.Network Methods getPrivacyAnnotation :: ChainSyncLog block point -> PrivacyAnnotation
HasSeverityAnnotation ( ChainSyncLog block point) Source #
Instance details Defined in Cardano.Wallet.Network Methods getSeverityAnnotation :: ChainSyncLog block point -> Severity
type Rep ( ChainSyncLog block point) Source #
Instance details Defined in Cardano.Wallet.Network type Rep ( ChainSyncLog block point) = D1 (' MetaData "ChainSyncLog" "Cardano.Wallet.Network" "cardano-wallet-core-2022.7.1-AGKhlyz9liLKN3QqZD1gj" ' False ) (( C1 (' MetaCons "MsgChainFindIntersect" ' PrefixI ' False ) ( S1 (' MetaSel (' Nothing :: Maybe Symbol ) ' NoSourceUnpackedness ' NoSourceStrictness ' DecidedLazy ) ( Rec0 [point])) :+: ( C1 (' MetaCons "MsgChainRollForward" ' PrefixI ' False ) ( S1 (' MetaSel (' Nothing :: Maybe Symbol ) ' NoSourceUnpackedness ' NoSourceStrictness ' DecidedLazy ) ( Rec0 ( NonEmpty block)) :: S1 (' MetaSel (' Nothing :: Maybe Symbol ) ' NoSourceUnpackedness ' NoSourceStrictness ' DecidedLazy ) ( Rec0 point)) :+: C1 (' MetaCons "MsgChainRollBackward" ' PrefixI ' False ) ( S1 (' MetaSel (' Nothing :: Maybe Symbol ) ' NoSourceUnpackedness ' NoSourceStrictness ' DecidedLazy ) ( Rec0 point) :: S1 (' MetaSel (' Nothing :: Maybe Symbol ) ' NoSourceUnpackedness ' NoSourceStrictness ' DecidedLazy ) ( Rec0 Int )))) :+: ( C1 (' MetaCons "MsgChainTip" ' PrefixI ' False ) ( S1 (' MetaSel (' Nothing :: Maybe Symbol ) ' NoSourceUnpackedness ' NoSourceStrictness ' DecidedLazy ) ( Rec0 point)) :+: ( C1 (' MetaCons "MsgLocalTip" ' PrefixI ' False ) ( S1 (' MetaSel (' Nothing :: Maybe Symbol ) ' NoSourceUnpackedness ' NoSourceStrictness ' DecidedLazy ) ( Rec0 point)) :+: C1 (' MetaCons "MsgTipDistance" ' PrefixI ' False ) ( S1 (' MetaSel (' Nothing :: Maybe Symbol ) ' NoSourceUnpackedness ' NoSourceStrictness ' DecidedLazy ) ( Rec0 Natural )))))

mapChainSyncLog :: (b1 -> b2) -> (p1 -> p2) -> ChainSyncLog b1 p1 -> ChainSyncLog b2 p2 Source #

withFollowStatsMonitoring :: Tracer IO ChainFollowLog -> ( SlotNo -> IO SyncProgress ) -> ( Tracer IO ( ChainSyncLog BlockHeader ChainPoint ) -> IO ()) -> IO () Source #

Monitors health and statistics by inspecting the messages submitted to a ChainSyncLog tracer.

Statistics are computed in regular time intervals. In order to do that, the monitor runs in separate thread. The results are submitted to the outer ChainFollowLog tracer.

Logging (for testing)

data FollowStats f Source #

Statistics of interest from the follow-function.

The f allows us to use Rearview to keep track of both current and previously logged stats, and perform operations over it in a nice way.

Constructors

FollowStats
Fields blocksApplied :: !(f Int ) rollbacks :: !(f Int ) localTip :: !(f ChainPoint ) time :: !(f UTCTime ) NOTE: Current time is not updated until `flush` is called. prog :: !(f SyncProgress ) NOTE: prog is not updated until `flush` is called.

Instances

Instances details

Eq ( FollowStats Rearview ) Source #
Instance details Defined in Cardano.Wallet.Network Methods (==) :: FollowStats Rearview -> FollowStats Rearview -> Bool Source # (/=) :: FollowStats Rearview -> FollowStats Rearview -> Bool Source #
Show ( FollowStats Rearview ) Source #
Instance details Defined in Cardano.Wallet.Network Methods showsPrec :: Int -> FollowStats Rearview -> ShowS Source # show :: FollowStats Rearview -> String Source # showList :: [ FollowStats Rearview ] -> ShowS Source #
Generic ( FollowStats f) Source #
Instance details Defined in Cardano.Wallet.Network Associated Types type Rep ( FollowStats f) :: Type -> Type Source # Methods from :: FollowStats f -> Rep ( FollowStats f) x Source # to :: Rep ( FollowStats f) x -> FollowStats f Source #
NoThunks ( FollowStats Rearview ) Source #
Instance details Defined in Cardano.Wallet.Network Methods noThunks :: Context -> FollowStats Rearview -> IO ( Maybe ThunkInfo ) Source # wNoThunks :: Context -> FollowStats Rearview -> IO ( Maybe ThunkInfo ) Source # showTypeOf :: Proxy ( FollowStats Rearview ) -> String Source #
ToText ( FollowStats Rearview ) Source #
Instance details Defined in Cardano.Wallet.Network Methods toText :: FollowStats Rearview -> Text Source #
HasSeverityAnnotation ( FollowStats Rearview ) Source #
Instance details Defined in Cardano.Wallet.Network Methods getSeverityAnnotation :: FollowStats Rearview -> Severity
type Rep ( FollowStats f) Source #
Instance details Defined in Cardano.Wallet.Network type Rep ( FollowStats f) = D1 (' MetaData "FollowStats" "Cardano.Wallet.Network" "cardano-wallet-core-2022.7.1-AGKhlyz9liLKN3QqZD1gj" ' False ) ( C1 (' MetaCons "FollowStats" ' PrefixI ' True ) (( S1 (' MetaSel (' Just "blocksApplied") ' NoSourceUnpackedness ' SourceStrict ' DecidedStrict ) ( Rec0 (f Int )) :: S1 (' MetaSel (' Just "rollbacks") ' NoSourceUnpackedness ' SourceStrict ' DecidedStrict ) ( Rec0 (f Int ))) :: ( S1 (' MetaSel (' Just "localTip") ' NoSourceUnpackedness ' SourceStrict ' DecidedStrict ) ( Rec0 (f ChainPoint )) :: ( S1 (' MetaSel (' Just "time") ' NoSourceUnpackedness ' SourceStrict ' DecidedStrict ) ( Rec0 (f UTCTime )) :: S1 (' MetaSel (' Just "prog") ' NoSourceUnpackedness ' SourceStrict ' DecidedStrict ) ( Rec0 (f SyncProgress ))))))

data Rearview a Source #

A Rearview consists of a past value and a present value. Useful for keeping track of past logs.

The idea is to 1. Reconstruct a model of the current state using a Trace 2. Sometimes log the difference between the current state and the most recently logged one.

Constructors

Rearview
Fields past :: !a Most previously logged state current :: !a Not-yet logged state

Instances

Instances details

Functor Rearview Source #
Instance details Defined in Cardano.Wallet.Network Methods fmap :: (a -> b) -> Rearview a -> Rearview b Source # (<$) :: a -> Rearview b -> Rearview a Source #
Eq a => Eq ( Rearview a) Source #
Instance details Defined in Cardano.Wallet.Network Methods (==) :: Rearview a -> Rearview a -> Bool Source # (/=) :: Rearview a -> Rearview a -> Bool Source #
Eq ( FollowStats Rearview ) Source #
Instance details Defined in Cardano.Wallet.Network Methods (==) :: FollowStats Rearview -> FollowStats Rearview -> Bool Source # (/=) :: FollowStats Rearview -> FollowStats Rearview -> Bool Source #
Show a => Show ( Rearview a) Source #
Instance details Defined in Cardano.Wallet.Network Methods showsPrec :: Int -> Rearview a -> ShowS Source # show :: Rearview a -> String Source # showList :: [ Rearview a] -> ShowS Source #
Show ( FollowStats Rearview ) Source #
Instance details Defined in Cardano.Wallet.Network Methods showsPrec :: Int -> FollowStats Rearview -> ShowS Source # show :: FollowStats Rearview -> String Source # showList :: [ FollowStats Rearview ] -> ShowS Source #
Generic ( Rearview a) Source #
Instance details Defined in Cardano.Wallet.Network Associated Types type Rep ( Rearview a) :: Type -> Type Source # Methods from :: Rearview a -> Rep ( Rearview a) x Source # to :: Rep ( Rearview a) x -> Rearview a Source #
NoThunks a => NoThunks ( Rearview a) Source #
Instance details Defined in Cardano.Wallet.Network Methods noThunks :: Context -> Rearview a -> IO ( Maybe ThunkInfo ) Source # wNoThunks :: Context -> Rearview a -> IO ( Maybe ThunkInfo ) Source # showTypeOf :: Proxy ( Rearview a) -> String Source #
NoThunks ( FollowStats Rearview ) Source #
Instance details Defined in Cardano.Wallet.Network Methods noThunks :: Context -> FollowStats Rearview -> IO ( Maybe ThunkInfo ) Source # wNoThunks :: Context -> FollowStats Rearview -> IO ( Maybe ThunkInfo ) Source # showTypeOf :: Proxy ( FollowStats Rearview ) -> String Source #
ToText ( FollowStats Rearview ) Source #
Instance details Defined in Cardano.Wallet.Network Methods toText :: FollowStats Rearview -> Text Source #
HasSeverityAnnotation ( FollowStats Rearview ) Source #
Instance details Defined in Cardano.Wallet.Network Methods getSeverityAnnotation :: FollowStats Rearview -> Severity
type Rep ( Rearview a) Source #
Instance details Defined in Cardano.Wallet.Network type Rep ( Rearview a) = D1 (' MetaData "Rearview" "Cardano.Wallet.Network" "cardano-wallet-core-2022.7.1-AGKhlyz9liLKN3QqZD1gj" ' False ) ( C1 (' MetaCons "Rearview" ' PrefixI ' True ) ( S1 (' MetaSel (' Just "past") ' NoSourceUnpackedness ' SourceStrict ' DecidedStrict ) ( Rec0 a) :*: S1 (' MetaSel (' Just "current") ' NoSourceUnpackedness ' SourceStrict ' DecidedStrict ) ( Rec0 a)))

emptyStats :: UTCTime -> FollowStats Rearview Source #

updateStats :: ChainSyncLog block ChainPoint -> FollowStats Rearview -> FollowStats Rearview Source #

Update the current statistics based on a new log message.