From aa19612dd0491bc6abb2d6d6f419cfe7228c6b79 Mon Sep 17 00:00:00 2001 From: gamarin Date: Mon, 26 Feb 2018 17:28:57 +0100 Subject: [PATCH] Improve store description --- docs/spec/governance/state.md | 25 ++++++++++++--------- docs/spec/governance/transactions.md | 33 +++++++++++++++------------- 2 files changed, 33 insertions(+), 25 deletions(-) diff --git a/docs/spec/governance/state.md b/docs/spec/governance/state.md index 97622645f..b0633ea83 100644 --- a/docs/spec/governance/state.md +++ b/docs/spec/governance/state.md @@ -24,10 +24,6 @@ type Procedure struct { } ``` -**Store**: -* `Procedures`: a mapping `map[int16]Procedure` of procedures indexed by their - `ProcedureNumber` -* `ActiveProcedureNumber`: returns current procedure number ### Proposals @@ -58,8 +54,12 @@ type ValidatorGovInfo struct { } ``` -**Store:** +### Stores +*Stores are KVStores in the multistore. The key to find the store is the first parameter in the list* + +* `Procedures`: a mapping `map[int16]Procedure` of procedures indexed by their + `ProcedureNumber`. First ever procedure is found at index '1'. Index '0' is reserved for parameter `ActiveProcedureNumber` which returns the number of the current procedure. * `Proposals`: A mapping `map[int64]Proposal` of proposals indexed by their `proposalID` * `Deposits`: A mapping `map[[]byte]int64` of deposits indexed by @@ -76,6 +76,10 @@ type ValidatorGovInfo struct { `nil` if proposal has not entered voting period or if `PubKey` was not the governance public key of a validator when proposal entered voting period. +For pseudocode purposes, here are the two function we will use to read or write in stores: + +* `load(StoreKey, Key)`: Retrieve item stored at key `Key` in store found at key `StoreKey` in the multistore +* `store(StoreKey, Key, value)`: Write value `Value` at key `Key` in store found at key `StoreKey` in the multistore ### Proposal Processing Queue @@ -105,8 +109,8 @@ And the pseudocode for the `ProposalProcessingQueue`: else proposalID = ProposalProcessingQueue.Peek() - proposal = load(store, Proposals, proposalID) - initProcedure = load(store, Procedures, proposal.InitProcedureNumber) + proposal = load(Proposals, proposalID) + initProcedure = load(Procedures, proposal.InitProcedureNumber) if (proposal.Category AND proposal.Votes['Yes']/proposal.InitTotalVotingPower >= 2/3) @@ -118,15 +122,16 @@ And the pseudocode for the `ProposalProcessingQueue`: else if (CurrentBlock == proposal.VotingStartBlock + initProcedure.VotingPeriod) - activeProcedure = load(store, Procedures, ActiveProcedureNumber) + activeProcedureNumber = load(Procedures, '0') + activeProcedure = load(Procedures, activeProcedureNumber) for each validator in CurrentBondedValidators - validatorGovInfo = load(store, ValidatorGovInfos, validator.GovPubKey) + validatorGovInfo = load(multistore, ValidatorGovInfos, validator.GovPubKey) if (validatorGovInfo.InitVotingPower != nil) // validator was bonded when vote started - validatorOption = load(store, Options, validator.GovPubKey) + validatorOption = load(Options, validator.GovPubKey) if (validatorOption == nil) // validator did not vote slash validator by activeProcedure.GovernancePenalty diff --git a/docs/spec/governance/transactions.md b/docs/spec/governance/transactions.md index 4c58b0eb6..06e20ffd9 100644 --- a/docs/spec/governance/transactions.md +++ b/docs/spec/governance/transactions.md @@ -13,7 +13,7 @@ type TxGovSubmitProposal struct { Description string // Description of the proposal Type string // Type of proposal. Initial set {PlainTextProposal, SoftwareUpgradeProposal} Category bool // false=regular, true=urgent - InitialDeposit int64 // Initial deposit paid by sender. Must be strictly positive. + InitialDeposit int64 // Initial deposit paid by sender. Must be strictly positive. } ``` @@ -61,7 +61,8 @@ upon receiving txGovSubmitProposal from sender do proposal.SubmitBlock = CurrentBlock store(Deposits, :, txGovSubmitProposal.InitialDeposit) - activeProcedure = load(store, Procedures, ActiveProcedureNumber) + activeProcedureNumber = load(Procedures, '0') + activeProcedure = load(Procedures, activeProcedureNumber) if (txGovSubmitProposal.InitialDeposit < activeProcedure.MinDeposit) then // MinDeposit is not reached @@ -127,7 +128,7 @@ upon receiving txGovDeposit from sender do throw else - proposal = load(store, Proposals, txGovDeposit.ProposalID) + proposal = load(Proposals, txGovDeposit.ProposalID) if (proposal == nil) then // There is no proposal for this proposalID @@ -141,7 +142,8 @@ upon receiving txGovDeposit from sender do throw else - activeProcedure = load(store, Procedures, ActiveProcedureNumber) + activeProcedureNumber = load(Procedures, '0') + activeProcedure = load(Procedures, activeProcedureNumber) if (proposal.Deposit >= activeProcedure.MinDeposit) then // MinDeposit was reached @@ -157,7 +159,7 @@ upon receiving txGovDeposit from sender do // sender can deposit sender.AtomBalance -= txGovDeposit.Deposit - deposit = load(store, Deposits, :) + deposit = load(Deposits, :) if (deposit == nil) // sender has never deposited on this proposal @@ -221,7 +223,7 @@ And the associated pseudocode. throw else - proposal = load(store, Proposals, txGovDeposit.ProposalID) + proposal = load(Proposals, txGovDeposit.ProposalID) if (proposal == nil) then // There is no proposal for this proposalID @@ -229,7 +231,7 @@ And the associated pseudocode. throw else - deposit = load(store, Deposits, :) + deposit = load(Deposits, :) if (deposit == nil) // sender has not deposited on this proposal @@ -246,7 +248,8 @@ And the associated pseudocode. if (proposal.VotingStartBlock <= 0) // Vote never started - activeProcedure = load(store, Procedures, ActiveProcedureNumber) + activeProcedureNumber = load(Procedures, '0') + activeProcedure = load(Procedures, ActiveProcedureNumber) if (CurrentBlock <= proposal.SubmitBlock + activeProcedure.MaxDepositPeriod) // MaxDepositPeriod is not reached @@ -262,7 +265,7 @@ And the associated pseudocode. else // Vote started - initProcedure = load(store, Procedures, proposal.InitProcedureNumber) + initProcedure = load(Procedures, proposal.InitProcedureNumber) if (proposal.Category AND proposal.Votes['Yes']/proposal.InitTotalVotingPower >= 2/3) OR ((CurrentBlock > proposal.VotingStartBlock + initProcedure.VotingPeriod) AND (proposal.Votes['NoWithVeto']/(proposal.Votes['Yes']+proposal.Votes['No']+proposal.Votes['NoWithVeto']) < 1/3) AND (proposal.Votes['Yes']/(proposal.Votes['Yes']+proposal.Votes['No']+proposal.Votes['NoWithVeto']) > 1/2)) then @@ -318,7 +321,7 @@ handled: throw else - proposal = load(store, Proposals, txGovDeposit.ProposalID) + proposal = load(Proposals, txGovDeposit.ProposalID) if (proposal == nil) then // There is no proposal for this proposalID @@ -326,8 +329,8 @@ handled: throw else - initProcedure = load(store, Procedures, proposal.InitProcedureNumber) // get procedure that was active when vote opened - validator = load(store, Validators, txGovVote.ValidatorPubKey) + initProcedure = load(Procedures, proposal.InitProcedureNumber) // get procedure that was active when vote opened + validator = load(Validators, txGovVote.ValidatorPubKey) if !initProcedure.OptionSet.includes(txGovVote.Option) OR (validator == nil) then @@ -339,7 +342,7 @@ handled: throw else - option = load(store, Options, ::) + option = load(Options, ::) if (option != nil) // sender has already voted with the Atoms bonded to ValidatorPubKey @@ -363,7 +366,7 @@ handled: throw else - validatorGovInfo = load(store, ValidatorGovInfos, :) + validatorGovInfo = load(ValidatorGovInfos, :) if (validatorGovInfo == nil) // validator became validator after proposal entered voting period @@ -384,7 +387,7 @@ handled: throw else - validatorOption = load(store, Options, ::::