cardano-ledger-conway-1.14.0.0: Cardano ledger with an updated on-chain governance system.
Safe HaskellSafe-Inferred
LanguageHaskell2010

Cardano.Ledger.Conway.Governance.Proposals

Description

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 (Proposals) and another at the epoch boundary (PrevGovActionIds, DRepPulser). 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.

Below is a typical timeline of the processing of these states.

  1. Epoch n: Proposals and votes are continuously collected from incoming transactions into Proposals
  2. Epoch n boundary: The DRepPulser contains all proposals and votes from epoch (n - 1). Its calculation is completed, ratified and enacted or expired. Ratification and enactment do not affect Proposals directly. They only update the PrevGovActionIds directly and return the sequence of enacted action-ids and the set of expired action-ids that inform us of the changes pending on Proposals.
  3. 1. We take this sequence of enacted action-ids and set of expired action-ids and apply them to the Proposals 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 the Proposals 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 the Proposals tree.
  4. 2. The resultant Proposals 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 (DRepPulser), before entering the new epoch to collect more proposals and votes in Proposals. Here we trust that the pulser accounts correctly for newly collected votes on proposals from previous epochs that haven't been ratified yet.
  5. Epoch (n + 1): New proposals and votes are collected from incoming transactions into Proposals.
  6. Epoch (n + 1) boundary: The DRepPulser now contains all unratified proposals and votes from epoch n. Its calculation is completed, ratified and enacted or expired. This updates PrevGovActionIds and gives us a new sequence of enacted action-ids and set of expired actions-ids to apply to the Proposals, which have been collecting even newer proposals and votes to be a superset of our set of pulsed proposals and votes. And so on...
Synopsis

Intended interface to be used for all implementation

data Proposals era Source #

Self-contained representation of all 4 proposals trees. This forest is made up of only action-ids for nodes - full GovActionStates 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 (PGraph). We also need to always know the roots of the 4 trees, and those we store in the PRoot

NOTE: At the end of an epoch boundary, we expect pRoots to be the same as the PrevGovActionIds from the EnactState

Instances

Instances details
EraPParams era ⇒ ToJSON (Proposals era) Source # 
Instance details

Defined in Cardano.Ledger.Conway.Governance.Proposals

Generic (Proposals era) Source # 
Instance details

Defined in Cardano.Ledger.Conway.Governance.Proposals

Associated Types

type Rep (Proposals era) ∷ TypeType Source #

Methods

fromProposals era → Rep (Proposals era) x Source #

toRep (Proposals era) x → Proposals era Source #

EraPParams era ⇒ Show (Proposals era) Source # 
Instance details

Defined in Cardano.Ledger.Conway.Governance.Proposals

Methods

showsPrecIntProposals era → ShowS Source #

showProposals era → String Source #

showList ∷ [Proposals era] → ShowS Source #

EraPParams era ⇒ DecCBOR (Proposals era) Source # 
Instance details

Defined in Cardano.Ledger.Conway.Governance.Proposals

Methods

decCBORDecoder s (Proposals era) Source #

dropCBORProxy (Proposals era) → Decoder s () Source #

labelProxy (Proposals era) → Text Source #

EraPParams era ⇒ DecShareCBOR (Proposals era) Source # 
Instance details

Defined in Cardano.Ledger.Conway.Governance.Proposals

Associated Types

type Share (Proposals era) Source #

EraPParams era ⇒ EncCBOR (Proposals era) Source # 
Instance details

Defined in Cardano.Ledger.Conway.Governance.Proposals

Methods

encCBORProposals era → Encoding Source #

encodedSizeExpr ∷ (∀ t. EncCBOR t ⇒ Proxy t → Size) → Proxy (Proposals era) → Size Source #

encodedListSizeExpr ∷ (∀ t. EncCBOR t ⇒ Proxy t → Size) → Proxy [Proposals era] → Size Source #

Default (Proposals era) Source # 
Instance details

Defined in Cardano.Ledger.Conway.Governance.Proposals

Methods

defProposals era Source #

EraPParams era ⇒ NFData (Proposals era) Source # 
Instance details

Defined in Cardano.Ledger.Conway.Governance.Proposals

Methods

rnfProposals era → () Source #

EraPParams era ⇒ Eq (Proposals era) Source # 
Instance details

Defined in Cardano.Ledger.Conway.Governance.Proposals

Methods

(==)Proposals era → Proposals era → Bool Source #

(/=)Proposals era → Proposals era → Bool Source #

EraPParams era ⇒ NoThunks (Proposals era) Source # 
Instance details

Defined in Cardano.Ledger.Conway.Governance.Proposals

type Rep (Proposals era) Source # 
Instance details

Defined in Cardano.Ledger.Conway.Governance.Proposals

type Rep (Proposals era) = D1 ('MetaData "Proposals" "Cardano.Ledger.Conway.Governance.Proposals" "cardano-ledger-conway-1.14.0.0-inplace" 'False) (C1 ('MetaCons "Proposals" 'PrefixI 'True) (S1 ('MetaSel ('Just "pProps") 'NoSourceUnpackedness 'SourceStrict 'DecidedStrict) (Rec0 (OMap (GovActionId (EraCrypto era)) (GovActionState era))) :*: (S1 ('MetaSel ('Just "pRoots") 'NoSourceUnpackedness 'SourceStrict 'DecidedStrict) (Rec0 (GovRelation PRoot era)) :*: S1 ('MetaSel ('Just "pGraph") 'NoSourceUnpackedness 'SourceStrict 'DecidedStrict) (Rec0 (GovRelation PGraph era)))))
type Share (Proposals era) Source # 
Instance details

Defined in Cardano.Ledger.Conway.Governance.Proposals

type Share (Proposals era) = ()

proposalsIdsProposals era → StrictSeq (GovActionId (EraCrypto era)) Source #

Get the sequence of GovActionIds

proposalsAddAction ∷ ∀ era. (EraPParams era, HasCallStack) ⇒ GovActionState era → Proposals era → Maybe (Proposals era) Source #

Add a single GovActionState to the Proposals forest. The tree to which it is added is picked according to its GovActionPurpose. Returns 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 EPOCH rule. Apply the result of extractDRepPulsingState to the Proposals 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 step

proposalsAddVoteVoter (EraCrypto era) → VoteGovActionId (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

proposalsActionsMapProposals era → Map (GovActionId (EraCrypto era)) (GovActionState era) Source #

Get the unordered map of GovActionIds and GovActionStates

To be used only for testing

proposalsRemoveWithDescendantsEraPParams 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 Proposals forest. Cannot be used for removing enacted GovActionIds (i.e. roots)

data TreeMaybe a Source #

Wraper type, which serves as a composition of Tree . StrictMaybe

Also its Show instance will print a nice tree structure.

Constructors

TreeMaybe 

Fields

Instances

Instances details
Show (TreeMaybe (GovPurposeId p era)) Source # 
Instance details

Defined in Cardano.Ledger.Conway.Governance.Proposals

Eq a ⇒ Eq (TreeMaybe a) Source # 
Instance details

Defined in Cardano.Ledger.Conway.Governance.Proposals

Methods

(==)TreeMaybe a → TreeMaybe a → Bool Source #

(/=)TreeMaybe a → TreeMaybe a → Bool Source #

mkProposals ∷ (EraPParams era, MonadFail m) ⇒ GovRelation StrictMaybe era → OMap (GovActionId (EraCrypto era)) (GovActionState era) → m (Proposals era) Source #

Reconstruct the Proposals forest from an OMap of GovActionStates and the 4 roots (PrevGovActionIds)

unsafeMkProposalsHasCallStackGovRelation StrictMaybe era → OMap (GovActionId (EraCrypto era)) (GovActionState era) → Proposals era Source #

Reconstruct the Proposals forest from an OMap of GovActionStates and the 4 roots (PrevGovActionIds). This function can fail and may return a malformed Proposals if not given correct inputs.

WARNING: Should only be used for testing!

data PRoot a Source #

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

Constructors

PRoot 

Fields

Instances

Instances details
Generic (PRoot a) Source # 
Instance details

Defined in Cardano.Ledger.Conway.Governance.Proposals

Associated Types

type Rep (PRoot a) ∷ TypeType Source #

Methods

fromPRoot a → Rep (PRoot a) x Source #

toRep (PRoot a) x → PRoot a Source #

Show a ⇒ Show (PRoot a) Source # 
Instance details

Defined in Cardano.Ledger.Conway.Governance.Proposals

Methods

showsPrecIntPRoot a → ShowS Source #

showPRoot a → String Source #

showList ∷ [PRoot a] → ShowS Source #

Default (PRoot a) Source # 
Instance details

Defined in Cardano.Ledger.Conway.Governance.Proposals

Methods

defPRoot a Source #

NFData a ⇒ NFData (PRoot a) Source # 
Instance details

Defined in Cardano.Ledger.Conway.Governance.Proposals

Methods

rnfPRoot a → () Source #

Eq a ⇒ Eq (PRoot a) Source # 
Instance details

Defined in Cardano.Ledger.Conway.Governance.Proposals

Methods

(==)PRoot a → PRoot a → Bool Source #

(/=)PRoot a → PRoot a → Bool Source #

Ord a ⇒ Ord (PRoot a) Source # 
Instance details

Defined in Cardano.Ledger.Conway.Governance.Proposals

Methods

comparePRoot a → PRoot a → Ordering Source #

(<)PRoot a → PRoot a → Bool Source #

(<=)PRoot a → PRoot a → Bool Source #

(>)PRoot a → PRoot a → Bool Source #

(>=)PRoot a → PRoot a → Bool Source #

maxPRoot a → PRoot a → PRoot a Source #

minPRoot a → PRoot a → PRoot a Source #

NoThunks a ⇒ NoThunks (PRoot a) Source # 
Instance details

Defined in Cardano.Ledger.Conway.Governance.Proposals

type Rep (PRoot a) Source # 
Instance details

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))))

data PEdges a Source #

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.

Constructors

PEdges 

Fields

Instances

Instances details
Generic (PEdges a) Source # 
Instance details

Defined in Cardano.Ledger.Conway.Governance.Proposals

Associated Types

type Rep (PEdges a) ∷ TypeType Source #

Methods

fromPEdges a → Rep (PEdges a) x Source #

toRep (PEdges a) x → PEdges a Source #

Show a ⇒ Show (PEdges a) Source # 
Instance details

Defined in Cardano.Ledger.Conway.Governance.Proposals

Methods

showsPrecIntPEdges a → ShowS Source #

showPEdges a → String Source #

showList ∷ [PEdges a] → ShowS Source #

Default (PEdges a) Source # 
Instance details

Defined in Cardano.Ledger.Conway.Governance.Proposals

Methods

defPEdges a Source #

NFData a ⇒ NFData (PEdges a) Source # 
Instance details

Defined in Cardano.Ledger.Conway.Governance.Proposals

Methods

rnfPEdges a → () Source #

Eq a ⇒ Eq (PEdges a) Source # 
Instance details

Defined in Cardano.Ledger.Conway.Governance.Proposals

Methods

(==)PEdges a → PEdges a → Bool Source #

(/=)PEdges a → PEdges a → Bool Source #

Ord a ⇒ Ord (PEdges a) Source # 
Instance details

Defined in Cardano.Ledger.Conway.Governance.Proposals

Methods

comparePEdges a → PEdges a → Ordering Source #

(<)PEdges a → PEdges a → Bool Source #

(<=)PEdges a → PEdges a → Bool Source #

(>)PEdges a → PEdges a → Bool Source #

(>=)PEdges a → PEdges a → Bool Source #

maxPEdges a → PEdges a → PEdges a Source #

minPEdges a → PEdges a → PEdges a Source #

NoThunks a ⇒ NoThunks (PEdges a) Source # 
Instance details

Defined in Cardano.Ledger.Conway.Governance.Proposals

type Rep (PEdges a) Source # 
Instance details

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))))

newtype PGraph a Source #

A single proposal-tree. This map represents all the action-ids that form a tree.

Constructors

PGraph 

Fields

Instances

Instances details
Generic (PGraph a) Source # 
Instance details

Defined in Cardano.Ledger.Conway.Governance.Proposals

Associated Types

type Rep (PGraph a) ∷ TypeType Source #

Methods

fromPGraph a → Rep (PGraph a) x Source #

toRep (PGraph a) x → PGraph a Source #

Show a ⇒ Show (PGraph a) Source # 
Instance details

Defined in Cardano.Ledger.Conway.Governance.Proposals

Methods

showsPrecIntPGraph a → ShowS Source #

showPGraph a → String Source #

showList ∷ [PGraph a] → ShowS Source #

Default (PGraph a) Source # 
Instance details

Defined in Cardano.Ledger.Conway.Governance.Proposals

Methods

defPGraph a Source #

NFData a ⇒ NFData (PGraph a) Source # 
Instance details

Defined in Cardano.Ledger.Conway.Governance.Proposals

Methods

rnfPGraph a → () Source #

Eq a ⇒ Eq (PGraph a) Source # 
Instance details

Defined in Cardano.Ledger.Conway.Governance.Proposals

Methods

(==)PGraph a → PGraph a → Bool Source #

(/=)PGraph a → PGraph a → Bool Source #

Ord a ⇒ Ord (PGraph a) Source # 
Instance details

Defined in Cardano.Ledger.Conway.Governance.Proposals

Methods

comparePGraph a → PGraph a → Ordering Source #

(<)PGraph a → PGraph a → Bool Source #

(<=)PGraph a → PGraph a → Bool Source #

(>)PGraph a → PGraph a → Bool Source #

(>=)PGraph a → PGraph a → Bool Source #

maxPGraph a → PGraph a → PGraph a Source #

minPGraph a → PGraph a → PGraph a Source #

NoThunks a ⇒ NoThunks (PGraph a) Source # 
Instance details

Defined in Cardano.Ledger.Conway.Governance.Proposals

type Rep (PGraph a) Source # 
Instance details

Defined in Cardano.Ledger.Conway.Governance.Proposals

type Rep (PGraph a) = D1 ('MetaData "PGraph" "Cardano.Ledger.Conway.Governance.Proposals" "cardano-ledger-conway-1.14.0.0-inplace" 'True) (C1 ('MetaCons "PGraph" 'PrefixI 'True) (S1 ('MetaSel ('Just "unPGraph") 'NoSourceUnpackedness 'NoSourceStrictness 'DecidedLazy) (Rec0 (Map a (PEdges a)))))

proposalsDepositsProposals era → Map (Credential 'Staking (EraCrypto era)) (CompactForm Coin) Source #

Get a mapping from the reward-account staking credentials to deposits of all proposals.