Merge PR cosmos#4827: ADR 007 / 008: Specialization Groups Abstractio…

…n / CERT Group

* draft ADR 7

* working

* new CERT ADR seperated

* working

* ...

* complete ADR 007

* CERT Group ADR

* dCERT

* @fede membership admittance discussion

* @fedekunze comments

* @AdityaSripal CERT usefulness

* @AdityaSripal @jleni circuit breaker discussion

* proposal ids discussion

* Update docs/architecture/adr-008-dCERT-group.md

Co-Authored-By: Aditya <[email protected]>

* @AdityaSripal comments

* Apply suggestions from @alexanderbez

Co-Authored-By: Alexander Bezobchuk <[email protected]>

* Update docs/architecture/adr-007-specialization-groups.md

* Update docs/architecture/adr-008-dCERT-group.md

* Update docs/architecture/adr-008-dCERT-group.md

* Update docs/architecture/adr-008-dCERT-group.md

* Update docs/architecture/adr-008-dCERT-group.md

* Update docs/architecture/adr-008-dCERT-group.md

Co-Authored-By: Marko <[email protected]>

* @alexanderbez comments

* blockchain agnostic per @cwgoes comment

* Apply suggestions from code review

Co-Authored-By: Alexander Bezobchuk <[email protected]>

* @alexanderbez second pass comments

* stablization period, and delegating dCERT stake discussion

docs/architecture/adr-007-specialization-groups.md

@@ -0,0 +1,179 @@
+# ADR 007: Specialization Groups
+
+## Changelog
+
+- 2019 Jul 31: Initial Draft
+
+## Context
+
+This idea was first conceived of in order to fulfill the use case of the
+creation of a decentralized Computer Emergency Response Team (dCERT), whose
+members would be elected by a governing community and would fulfill the role of
+coordinating the community under emergency situations. This thinking
+can be further abstracted into the conception of "blockchain specialization
+groups". 
+
+The creation of these groups are the beginning of specialization capabilities
+within a wider blockchain community which could be used to enable a certain
+level of delegated responsibilities. Examples of specialization which could be
+beneficial to a blockchain community include: code auditing, emergency response,
+code development etc. This type of community organization paves the way for
+individual stakeholders to delegate votes by issue type, if in the future
+governance proposals include a field for issue type. 
+
+
+## Decision
+
+A specialization group can be broadly broken down into the following functions
+(herein containing examples):
+
+ - Membership Admittance
+ - Membership Acceptance
+ - Membership Revocation
+   - (probably) Without Penalty 
+     - member steps down (self-Revocation)
+     - replaced by new member from governance
+   - (probably) With Penalty 
+     - due to breach of soft-agreement (determined through governance)
+     - due to breach of hard-agreement (determined by code) 
+ - Execution of Duties
+   - Special transactions which only execute for members of a specialization
+     group (for example, dCERT members voting to turn off transaction routes in
+     an emergency scenario) 
+ - Compensation
+   - Group compensation (further distribution decided by the specialization group) 
+   - Individual compensation for all constituents of a group from the
+     greater community
+
+Membership admittance to a specialization group could take place over a wide
+variety of mechanisms. The most obvious example is through a general vote among
+the entire community, however in certain systems a community may want to allow
+the members already in a specialization group to internally elect new members,
+or maybe the community may assign a permission to a particular specialization
+group to appoint members to other 3rd party groups. The sky is really the limit
+as to how membership admittance can be structured. We attempt to capture
+some of these possiblities in a common interface dubbed the `Electionator`. For
+its initial implementation as a part of this ADR we recommend that the general
+election abstraction (`Electionator`) is provided as well as a basic
+implementation of that abstraction which allows for a continuous election of
+members of a specialization group. 
+
+``` golang
+// The Electionator abstraction covers the concept space for 
+// a wide variety of election kinds.  
+type Electionator interface {
+
+    // is the election object accepting votes.
+    Active() bool 
+
+    // functionality to execute for when a vote is cast in this election, here
+    // the vote field is anticipated to be marshalled into a vote type used 
+    // by an election. 
+    // 
+    // NOTE There are no explicit ids here. Just votes which pertain specifically
+    // to one electionator. Anyone can create and send a vote to the electionator item
+    // which will presumably attempt to marshal those bytes into a particular struct
+    // and apply the vote information in some arbitrary way. There can be multiple
+    // Electionators within the Cosmos-Hub for multiple specialization groups, votes
+    // would need to be routed to the Electionator upstream of here.
+    Vote(addr sdk.AccAddress, vote []byte) 
+
+    // here lies all functionality to authenticate and execute changes for
+    // when a member accepts being elected
+    AcceptElection(sdk.AccAddress) 
+
+    // Register a revoker object
+    RegisterRevoker(Revoker)
+
+    // No more revokers may be registered after this function is called
+    SealRevokers()
+
+    // register hooks to call when an election actions occur
+    RegisterHooks(ElectionatorHooks) 
+
+    // query for the current winner(s) of this election based on arbitrary
+    // election ruleset
+    QueryElected() []sdk.AccAddress 
+
+    // query metadata for an address in the election this 
+    // could include for example position that an address
+    // is being elected for within a group   
+    // 
+    // this metadata may be directly related to 
+    // voting information and/or privileges enabled
+    // to members within a group. 
+    QueryMetadata(sdk.AccAddress) []byte
+}
+
+// ElectionatorHooks, once registered with an Electionator, 
+// trigger execution of relevant interface functions when 
+// Electionator events occur. 
+type ElectionatorHooks interface {
+    AfterVoteCast(addr sdk.AccAddress, vote []byte)
+    AfterMemberAccepted(addr sdk.AccAddress)
+    AfterMemberRevoked(addr sdk.AccAddress, cause []byte)
+}
+
+// Revoker defines the function required for a membership revocation rule-set
+// used by a specialization group. This could be used to create self revoking,
+// and evidence based revoking, etc. Revokers types may be created and
+// reused for different election types. 
+// 
+// When revoking the "cause" bytes may be arbitrarily marshalled into evidence,
+// memos, etc.
+type Revoker interface {
+    RevokeName() string      // identifier for this revoker type 
+    RevokeMember(addr sdk.AccAddress, cause []byte) error
+}
+```
+
+Certain level of commonality likely exists between the existing code within
+`x/governance` and required functionality of elections. This common
+functionality should be abstracted during implementation. Similarly for each 
+vote implementation client CLI/REST functionality should be abstracted
+to be reused for multiple elections. 
+
+The specialization group abstraction firstly extends the `Electionator`
+but also further defines traits of the group. 
+
+``` golang
+type SpecializationGroup interface {
+    Electionator 
+    GetName() string
+    GetDescription() string 
+
+    // general soft contract the group is expected
+    // to fulfill with the greater community
+    GetContract() string
+
+    // messages which can be executed by the members of the group
+    Handler(ctx sdk.Context, msg sdk.Msg) sdk.Result
+
+    // logic to be executed at endblock, this may for instance
+    // include payment of a stipend to the group members
+    // for participation in the security group.   
+    EndBlocker(ctx sdk.Context)
+}
+```
+
+## Status
+
+> Proposed
+
+## Consequences
+
+### Positive
+
+ - increases specialization capabilities of a blockchain
+ - improve abstractions in `x/gov/` such that they can be used with specialization groups
+
+### Negative
+
+ - could be used to increase centralization within a community
+
+### Neutral
+
+## References
+
+ - (dCERT ADR)[./adr-008-dCERT-group.md]
+

docs/architecture/adr-008-dCERT-group.md

@@ -0,0 +1,167 @@
+# ADR 008: Decentralized Computer Emergency Response Team (dCERT) Group
+
+## Changelog
+
+- 2019 Jul 31: Initial Draft
+
+## Context
+
+In order to reduce the number of parties involved with handling sensitive
+information in an emergency scenario, we propose the creation of a
+specialization group named The Decentralized Computer Emergency Response Team
+(dCERT).  Initially this group's role is intended to serve as coordinators
+between various actors within a blockchain community such as validators,
+bug-hunters, and developers.  During a time of crisis, the dCERT group would
+aggregate and relay input from a variety of stakeholders to the developers who
+are actively devising a patch to the software, this way sensitive information
+does not need to be publicly disclosed while some input from the community can
+still be gained. 
+
+Additionally, a special privilege is proposed for the dCERT group: the capacity
+to "circuit-break" (aka. temporarily disable)  a particular message path. Note
+that this privilege should be enabled/disabled globally with a governance
+parameter such that this privilege could start disabled and later be enabled
+through a parameter change proposal, once a dCERT group has been established. 
+
+In the future it is foreseeable that the community may wish to expand the roles
+of dCERT with further responsibilities such as the capacity to "pre-approve" a
+security update on behalf of the community prior to a full community
+wide vote whereby the sensitive information would be revealed prior to a
+vulnerability being patched on the live network.  
+
+## Decision
+
+The dCERT group is proposed to include an implementation of a `SpecializationGroup`
+as defined in [ADR 007](./adr-007-specialization-groups.md). This will include the 
+implementation of: 
+ - continuous voting
+ - slashing due to breach of soft contract
+ - revoking a member due to breach of soft contract
+ - emergency disband of the entire dCERT group (ex. for colluding maliciously) 
+ - compensation stipend from the community pool or other means decided by
+   governance
+
+This system necessitates the following new parameters: 
+ - blockly stipend allowance per dCERT member 
+ - maximum number of dCERT members 
+ - required staked slashable tokens for each dCERT member 
+ - quorum for suspending a particular member 
+ - proposal wager for disbanding the dCERT group 
+ - stabilization period for dCERT member transition
+ - circuit break dCERT privileges enabled 
+
+These parameters are expected to be implemented through the param keeper such 
+that governance may change them at any given point. 
+
+### Continuous Voting Electionator
+
+An `Electionator` object is to be implemented as continuous voting and with the
+following specifications:
+ - All delegation addresses may submit votes at any point which updates their 
+   preferred representation on the dCERT group. 
+ - Preferred representation may be arbitrarily split between addresses (ex. 50%
+   to John, 25% to Sally, 25% to Carol) 
+ - In order for a new member to be added to the dCERT group they must 
+   send a transaction accepting their admission at which point the validity of
+   their admission is to be confirmed. 
+   - A sequence number is assigned when a member is added to dCERT group. 
+     If a member leaves the dCERT group and then enters back, a new sequence number
+     is assigned.  
+ - Addresses which control the greatest amount of preferred-representation are
+   eligible to join the dCERT group (up the _maximum number of dCERT members_). 
+   If the dCERT group is already full and new member is admitted, the existing
+   dCERT member with the lowest amount of votes is kicked from the dCERT group.
+   - In the split situation where the dCERT group is full but a vying candidate 
+     has the same amount of vote as an existing dCERT member, the existing 
+     member should maintain its position. 
+   - In the split situation where somebody must be kicked out but the two
+     addresses with the smallest number of votes have the same number of votes,
+     the address with the smallest sequence number maintains its position.  
+ - A stabilization period can be optionally included to reduce the
+   "flip-flopping" of the dCERT membership tail members. If a stabilization
+   period is provided which is greater than 0, when members are kicked due to
+   insufficient support, a queue entry is created which documents which member is
+   to replace which other member. While this entry is in the queue, no new entries
+   to kick that same dCERT member can be made. When the entry matures at the
+   duration of the  stabilization period, the new member is instantiated, and old
+   member kicked.
+
+### Staking/Slashing
+
+All members of the dCERT group must stake tokens _specifically_ to maintain
+eligibility as a dCERT member. These tokens can be staked directly by the vying
+dCERT member or out of the good will of a 3rd party (who shall gain no on-chain
+benefits for doing so). This staking mechanism should use the existing global
+unbonding time of tokens staked for network validator security. A dCERT member
+can _only be_ a member if it has the required tokens staked under this
+mechanism. If those tokens are unbonded then the dCERT member must be
+automatically kicked from the group.  
+
+Slashing of a particular dCERT member due to soft-contract breach should be
+performed by governance on a per member basis based on the magnitude of the
+breach.  The process flow is anticipated to be that a dCERT member is suspended
+by the dCERT group prior to being slashed by governance.  
+
+Membership suspension by the dCERT group takes place through a voting procedure
+by the dCERT group members. After this suspension has taken place, a governance
+proposal to slash the dCERT member must be submitted, if the proposal is not
+approved by the time the rescinding member has completed unbonding their
+tokens, then the tokens are no longer staked and unable to be slashed. 
+
+Additionally in the case of an emergency situation of a colluding and malicious
+dCERT group, the community needs the capability to disband the entire dCERT
+group and likely fully slash them. This could be achieved though a special new
+proposal type (implemented as a general governance proposal) which would halt
+the functionality of the dCERT group until the proposal was concluded. This
+special proposal type would likely need to also have a fairly large wager which
+could be slashed if the proposal creator was malicious. The reason a large
+wager should be required is because as soon as the proposal is made, the
+capability of the dCERT group to halt message routes is put on temporarily
+suspended, meaning that a malicious actor who created such a proposal could
+then potentially exploit a bug during this period of time, with no dCERT group
+capable of shutting down the exploitable message routes. 
+
+### dCERT membership transactions
+
+Active dCERT members 
+ - change of the description of the dCERT group
+ - circuit break a message route
+ - vote to suspend a dCERT member. 
+
+Here circuit-breaking refers to the capability to disable a groups of messages,
+This could for instance mean: "disable all staking-delegation messages", or
+"disable all distribution messages". This could be accomplished by verifying
+that the message route has not been "circuit-broken" at CheckTx time (in
+`baseapp/baseapp.go`). 
+
+"unbreaking" a circuit is anticipated only to occur during a hard fork upgrade
+meaning that no capability to unbreak a message route on a live chain is
+required. 
+
+Note also, that if there was a problem with governance voting (for instance a
+capability to vote many times) then governance would be broken and should be
+halted with this mechanism, it would be then up to the validator set to
+coordinate and hard-fork upgrade to a patched version of the software where
+governance is re-enabled (and fixed). If the dCERT group abuses this privilege
+they should all be severely slashed.
+
+## Status
+
+> Proposed
+
+## Consequences
+
+### Positive
+
+ - Potential to reduces the number of parties to coordinate with during an emergency 
+ - Reduction in possibility of disclosing sensitive information to malicious parties
+
+### Negative
+
+ - Centralization risks
+
+### Neutral
+
+## References
+
+  (Specialization Groups ADR)[./adr-007-specialization-groups.md]