952 governance #999
952 governance #999
Conversation
Deploying documentation with
|
| Latest commit: |
5292aa8
|
| Status: | ✅ Deploy successful! |
| Preview URL: | https://d1eec55c.documentation-7tp.pages.dev |
| Branch Preview URL: | https://952-governance.documentation-7tp.pages.dev |
|
p.s. fodder that I did not managed to get into this 2-day timeboxed effort:
|
main/guides/governance/index.md
Outdated
| @@ -0,0 +1,263 @@ | |||
| # Contract Governance | |||
|
|
|||
| To help build systems with a good balance of decentralization and executive control, the Agoric platform includes, in addition to chain-wide governance included in the Cosmos SDK platform, an `@agoric/governance` package with a flexible archtecture supporting 3 main features: | |||
There was a problem hiding this comment.
Please add something saying the following. It might be in this paragraph, or it might go after the bullet points. Feel free to reword.
The emphasis, throughout the design of the governance library, is on ensuring that clients of a contract have visibility into who can make changes, what changes they can make, and what the current state of the controlled values is.
I would also add a sentence or a few more words after each of the bullet points. The first one is clear enough on its own, but the latter two phrases probably won't mean much to most readers at this point.
- API governance -- give governance the ability to invoke particular methods called out by the contract's authors
- Offer filters -- give governance the ability to disable the use of some offers/invitations to deal with emergencies.
There was a problem hiding this comment.
yes, I meant to elaborate the bullets. thanks for the suggestions.
but
give governance ...
personifies governance in a way that seems awkward. "give the electorate ..." would fit better, but we haven't introduced the term "electorate" yet. hm.
main/guides/governance/index.md
Outdated
| style="border: 2px solid" width="600" /> | ||
|
|
||
| To exercises their `VoteOnParamChange` capability, | ||
| the committee participant makes a _continuing invitation_, |
There was a problem hiding this comment.
Is there an explanation of continuing invitations somewhere to link to? Is it in the queue?
There was a problem hiding this comment.
Is there an explanation of continuing invitations somewhere to link to?
Not really; the markup here is intended to signal introducing / defining the term.
There should be.
Is it in the queue?
#667 about continuing invitations was opened Apr 2022, but it's not scheduled.
#878 about invitation specs is scheduled... sort of. One kind of invitation spec is a continuing invitation, so it's possible #667 will be addressed along with it.
There was a problem hiding this comment.
I can add a glossary entry pointing here for now
There was a problem hiding this comment.
My dislike for novel info in the glossary prompted me to go ahead and write up continuing invitations and the rest of invitation specs, based on...
main/guides/governance/index.md
Outdated
| const offer = { | ||
| id: offerId, | ||
| invitationSpec: { | ||
| source: 'continuing', | ||
| previousOffer: NonNullish(charterAcceptOfferId), | ||
| invitationMakerName: 'VoteOnParamChange', | ||
| }, | ||
| offerArgs, | ||
| proposal: {}, | ||
| }; |
There was a problem hiding this comment.
| const offer = { | |
| id: offerId, | |
| invitationSpec: { | |
| source: 'continuing', | |
| previousOffer: NonNullish(charterAcceptOfferId), | |
| invitationMakerName: 'VoteOnParamChange', | |
| }, | |
| offerArgs, | |
| proposal: {}, | |
| }; | |
| const offer = { | |
| id: offerId, | |
| invitationSpec: { | |
| source: 'continuing', | |
| previousOffer: NonNullish(charterAcceptOfferId), | |
| invitationMakerName: 'VoteOnParamChange', | |
| }, | |
| offerArgs, | |
| proposal: {}, | |
| }; |
main/guides/governance/index.md
Outdated
| const targetFee = IST(50n, 100n); // 50 / 100 = 0.5 IST | ||
| const changes = { Fee: targetFee }; | ||
| ... | ||
| const deadline = 2n; |
There was a problem hiding this comment.
I presume deadline is Timestamp rather than RelativeTime.
| const deadline = 2n; | |
| const deadline = 2n; // outside of tests, this would be unix epoch time seconds |
There was a problem hiding this comment.
yes... also, timer docs are Coming Soon
- add glossary entry for Continuing Invitation Pattern
closes #878, #667, #952, #749
rendered:
outline: