Safe Haskell | Safe-Inferred |
---|---|
Language | Haskell2010 |
This module isolates all the types and functionality around Governance Proposals.
It is important to note that there are two sets of state that we
maintain around proposals and their enactment. One is processed
with transactions (
) and another at the epoch boundary
(Proposals
, PrevGovActionIds
). These two sets work together:
the incoming proposals and votes are collected continuously in the
state that lives with transaction processing, and at each epoch
boundary a snapshot of this state is taken to perform pulsing
computations on - after it has been adjusted (the proposals are
enacted or expired) based on the result of the previous pulsing
computaiion.DRepPulser
Below is a typical timeline of the processing of these states.
- Epoch n: Proposals and votes are continuously collected from
incoming transactions into
Proposals
- Epoch n boundary: The
contains all proposals and votes from epoch (n - 1). Its calculation is completed, ratified and enacted or expired. Ratification and enactment do not affectDRepPulser
directly. They only update theProposals
directly and return the sequence of enacted action-ids and the set of expired action-ids that inform us of the changes pending onPrevGovActionIds
.Proposals
- 1. We take this sequence of enacted action-ids and set of expired
action-ids and apply them to the
in the ledger state that now includes all the newly collected proposals and votes from epoch n and epoch (n - 1), as this is a superset of the pulsed set of proposals and votes. We do not expect this operation to fail, since all invariants are expected to hold and only an implementation bug could cause this operation to fail. After applying this operation we expect theProposals
to be in a state, where (i) all expired actions and their descendants have been pruned, and (ii) the sequence of enacted action-ids have been promoted to be the root of the respective tree and their competing or sibling action-ids and their descendants have been pruned from theProposals
tree.Proposals
- 2. The resultant
forest has all the latest proposals and votes collected and with enactments and expirations applied to existing ones, so we take a new snapshot to perform pulsing computations on and start the new pulser (Proposals
), before entering the new epoch to collect more proposals and votes inDRepPulser
. Here we trust that the pulser accounts correctly for newly collected votes on proposals from previous epochs that haven't been ratified yet.Proposals
- Epoch (n + 1): New proposals and votes are collected from incoming
transactions into
.Proposals
- Epoch (n + 1) boundary: The
now contains all unratified proposals and votes from epoch n. Its calculation is completed, ratified and enacted or expired. This updatesDRepPulser
and gives us a new sequence of enacted action-ids and set of expired actions-ids to apply to thePrevGovActionIds
, which have been collecting even newer proposals and votes to be a superset of our set of pulsed proposals and votes. And so on...Proposals
Synopsis
- data Proposals era
- proposalsIds ∷ Proposals era → StrictSeq (GovActionId (EraCrypto era))
- proposalsActions ∷ Proposals era → StrictSeq (GovActionState era)
- proposalsSize ∷ Proposals era → Int
- proposalsAddAction ∷ ∀ era. (EraPParams era, HasCallStack) ⇒ GovActionState era → Proposals era → Maybe (Proposals era)
- proposalsApplyEnactment ∷ ∀ era. EraPParams era ⇒ Seq (GovActionState era) → Set (GovActionId (EraCrypto era)) → Proposals era → (Proposals era, Map (GovActionId (EraCrypto era)) (GovActionState era), Map (GovActionId (EraCrypto era)) (GovActionState era))
- proposalsAddVote ∷ Voter (EraCrypto era) → Vote → GovActionId (EraCrypto era) → Proposals era → Proposals era
- proposalsLookupId ∷ GovActionId (EraCrypto era) → Proposals era → Maybe (GovActionState era)
- proposalsActionsMap ∷ Proposals era → Map (GovActionId (EraCrypto era)) (GovActionState era)
- toPrevGovActionIds ∷ GovRelation PRoot era → GovRelation StrictMaybe era
- fromPrevGovActionIds ∷ GovRelation StrictMaybe era → GovRelation PRoot era
- proposalsRemoveWithDescendants ∷ EraPParams era ⇒ Set (GovActionId (EraCrypto era)) → Proposals era → (Proposals era, Map (GovActionId (EraCrypto era)) (GovActionState era))
- data TreeMaybe a = TreeMaybe {
- unTreeMaybe ∷ Tree (StrictMaybe a)
- toGovRelationTree ∷ (Era era, HasCallStack) ⇒ Proposals era → GovRelation TreeMaybe era
- toGovRelationTreeEither ∷ Era era ⇒ Proposals era → Either String (GovRelation TreeMaybe era)
- pPropsL ∷ Lens' (Proposals era) (OMap (GovActionId (EraCrypto era)) (GovActionState era))
- pRootsL ∷ Lens' (Proposals era) (GovRelation PRoot era)
- pGraphL ∷ Lens' (Proposals era) (GovRelation PGraph era)
- mkProposals ∷ (EraPParams era, MonadFail m) ⇒ GovRelation StrictMaybe era → OMap (GovActionId (EraCrypto era)) (GovActionState era) → m (Proposals era)
- unsafeMkProposals ∷ HasCallStack ⇒ GovRelation StrictMaybe era → OMap (GovActionId (EraCrypto era)) (GovActionState era) → Proposals era
- data PRoot a = PRoot {
- prRoot ∷ !(StrictMaybe a)
- prChildren ∷ !(Set a)
- prRootL ∷ Lens' (PRoot a) (StrictMaybe a)
- prChildrenL ∷ Lens' (PRoot a) (Set a)
- data PEdges a = PEdges {
- peParent ∷ !(StrictMaybe a)
- peChildren ∷ !(Set a)
- peChildrenL ∷ Lens' (PEdges a) (Set a)
- newtype PGraph a = PGraph {}
- pGraphNodesL ∷ Lens' (PGraph a) (Map a (PEdges a))
- proposalsDeposits ∷ Proposals era → Map (Credential 'Staking (EraCrypto era)) (CompactForm Coin)
Intended interface to be used for all implementation
Self-contained representation of all 4 proposals trees. This forest
is made up of only action-ids for nodes - full GovActionState
s are
stored only once in the OMap
. All functions in this module prefixed
with the string proposals-
operate on this data-type keeping it
consistent.
NOTE: The correct way to think about this data-structure is similar
to 4 of the following, one for each GovActionPurpose
data Tree a = Node (StrictMaybe a) [Tree a]
but because this does not allow us to look-up a node's edges in
predictable time, we use a map from nodes to their edges (parent and
children) to capture the graph (
). We also need to always
know the roots of the 4 trees, and those we store in the PGraph
PRoot
NOTE: At the end of an epoch boundary, we expect
to be the same
as the pRoots
from the PrevGovActionIds
EnactState
Instances
proposalsIds ∷ Proposals era → StrictSeq (GovActionId (EraCrypto era)) Source #
Get the sequence of GovActionId
s
proposalsActions ∷ Proposals era → StrictSeq (GovActionState era) Source #
Get the sequence of GovActionState
s
proposalsSize ∷ Proposals era → Int Source #
proposalsAddAction ∷ ∀ era. (EraPParams era, HasCallStack) ⇒ GovActionState era → Proposals era → Maybe (Proposals era) Source #
Add a single
to the GovActionState
forest.
The tree to which it is added is picked according to its
Proposals
. Returns GovActionPurpose
Nothing
when the operation cannot
succeed.
proposalsApplyEnactment ∷ ∀ era. EraPParams era ⇒ Seq (GovActionState era) → Set (GovActionId (EraCrypto era)) → Proposals era → (Proposals era, Map (GovActionId (EraCrypto era)) (GovActionState era), Map (GovActionId (EraCrypto era)) (GovActionState era)) Source #
For use in the
rule. Apply the result of
EPOCH
to the extractDRepPulsingState
forest, so that:
i. all the expired action-ids and their descendants are removed,
and
ii. the sequence of enacted action-ids is promoted to the root,
removing competing/sibling action-ids and their descendants at each
stepProposals
proposalsAddVote ∷ Voter (EraCrypto era) → Vote → GovActionId (EraCrypto era) → Proposals era → Proposals era Source #
Add a vote to an existing GovActionState
. This is a no-op if the
provided GovActionId
does not already exist
proposalsLookupId ∷ GovActionId (EraCrypto era) → Proposals era → Maybe (GovActionState era) Source #
proposalsActionsMap ∷ Proposals era → Map (GovActionId (EraCrypto era)) (GovActionState era) Source #
Get the unordered map of GovActionId
s and GovActionState
s
toPrevGovActionIds ∷ GovRelation PRoot era → GovRelation StrictMaybe era Source #
fromPrevGovActionIds ∷ GovRelation StrictMaybe era → GovRelation PRoot era Source #
To be used only for testing
proposalsRemoveWithDescendants ∷ EraPParams era ⇒ Set (GovActionId (EraCrypto era)) → Proposals era → (Proposals era, Map (GovActionId (EraCrypto era)) (GovActionState era)) Source #
Remove the set of given action-ids with their descendants from the
forest. Cannot be used for removing enacted GovActionIds (i.e. roots)Proposals
Wraper type, which serves as a composition of Tree
. StrictMaybe
Also its Show instance will print a nice tree structure.
TreeMaybe | |
|
toGovRelationTree ∷ (Era era, HasCallStack) ⇒ Proposals era → GovRelation TreeMaybe era Source #
Partial version of toGovRelationTreeEither
toGovRelationTreeEither ∷ Era era ⇒ Proposals era → Either String (GovRelation TreeMaybe era) Source #
pPropsL ∷ Lens' (Proposals era) (OMap (GovActionId (EraCrypto era)) (GovActionState era)) Source #
mkProposals ∷ (EraPParams era, MonadFail m) ⇒ GovRelation StrictMaybe era → OMap (GovActionId (EraCrypto era)) (GovActionState era) → m (Proposals era) Source #
Reconstruct the
forest from an Proposals
of
OMap
s and the 4 roots (GovActionState
)PrevGovActionIds
unsafeMkProposals ∷ HasCallStack ⇒ GovRelation StrictMaybe era → OMap (GovActionId (EraCrypto era)) (GovActionState era) → Proposals era Source #
Reconstruct the
forest from an Proposals
of
OMap
s and the 4 roots (GovActionState
).
This function can fail and may return a malformed PrevGovActionIds
Proposals
if not given correct inputs.
WARNING: Should only be used for testing!
The root of a single Proposals
tree. prRoot
is always expected
to be equal to the respective PrevGovActionId
at the end of every
epoch boundary
PRoot | |
|
Instances
Generic (PRoot a) Source # | |
Show a ⇒ Show (PRoot a) Source # | |
Default (PRoot a) Source # | |
Defined in Cardano.Ledger.Conway.Governance.Proposals | |
NFData a ⇒ NFData (PRoot a) Source # | |
Defined in Cardano.Ledger.Conway.Governance.Proposals | |
Eq a ⇒ Eq (PRoot a) Source # | |
Ord a ⇒ Ord (PRoot a) Source # | |
Defined in Cardano.Ledger.Conway.Governance.Proposals | |
NoThunks a ⇒ NoThunks (PRoot a) Source # | |
type Rep (PRoot a) Source # | |
Defined in Cardano.Ledger.Conway.Governance.Proposals type Rep (PRoot a) = D1 ('MetaData "PRoot" "Cardano.Ledger.Conway.Governance.Proposals" "cardano-ledger-conway-1.14.0.0-inplace" 'False) (C1 ('MetaCons "PRoot" 'PrefixI 'True) (S1 ('MetaSel ('Just "prRoot") 'NoSourceUnpackedness 'SourceStrict 'DecidedStrict) (Rec0 (StrictMaybe a)) :*: S1 ('MetaSel ('Just "prChildren") 'NoSourceUnpackedness 'SourceStrict 'DecidedStrict) (Rec0 (Set a)))) |
A non-root edges in a Proposals
tree. peParent
is expected to be
a SNothing
only at the begining when no governance actions has been
enacted yet.
PEdges | |
|
Instances
Generic (PEdges a) Source # | |
Show a ⇒ Show (PEdges a) Source # | |
Default (PEdges a) Source # | |
Defined in Cardano.Ledger.Conway.Governance.Proposals | |
NFData a ⇒ NFData (PEdges a) Source # | |
Defined in Cardano.Ledger.Conway.Governance.Proposals | |
Eq a ⇒ Eq (PEdges a) Source # | |
Ord a ⇒ Ord (PEdges a) Source # | |
Defined in Cardano.Ledger.Conway.Governance.Proposals | |
NoThunks a ⇒ NoThunks (PEdges a) Source # | |
type Rep (PEdges a) Source # | |
Defined in Cardano.Ledger.Conway.Governance.Proposals type Rep (PEdges a) = D1 ('MetaData "PEdges" "Cardano.Ledger.Conway.Governance.Proposals" "cardano-ledger-conway-1.14.0.0-inplace" 'False) (C1 ('MetaCons "PEdges" 'PrefixI 'True) (S1 ('MetaSel ('Just "peParent") 'NoSourceUnpackedness 'SourceStrict 'DecidedStrict) (Rec0 (StrictMaybe a)) :*: S1 ('MetaSel ('Just "peChildren") 'NoSourceUnpackedness 'SourceStrict 'DecidedStrict) (Rec0 (Set a)))) |
A single proposal-tree. This map represents all the action-ids that form a tree.
Instances
Generic (PGraph a) Source # | |
Show a ⇒ Show (PGraph a) Source # | |
Default (PGraph a) Source # | |
Defined in Cardano.Ledger.Conway.Governance.Proposals | |
NFData a ⇒ NFData (PGraph a) Source # | |
Defined in Cardano.Ledger.Conway.Governance.Proposals | |
Eq a ⇒ Eq (PGraph a) Source # | |
Ord a ⇒ Ord (PGraph a) Source # | |
Defined in Cardano.Ledger.Conway.Governance.Proposals | |
NoThunks a ⇒ NoThunks (PGraph a) Source # | |
type Rep (PGraph a) Source # | |
Defined in Cardano.Ledger.Conway.Governance.Proposals |
proposalsDeposits ∷ Proposals era → Map (Credential 'Staking (EraCrypto era)) (CompactForm Coin) Source #
Get a mapping from the reward-account staking credentials to deposits of all proposals.