This repository has been archived by the owner on Nov 27, 2024. It is now read-only.
docs: Token Voting Module documentation #91
Closed
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Co-authored-by: hello-shreyas <[email protected]>
Co-authored-by: hello-shreyas <[email protected]>
Co-authored-by: hello-shreyas <[email protected]>
Co-authored-by: hello-shreyas <[email protected]>
Co-authored-by: hello-shreyas <[email protected]>
AustinGreen
reviewed
Jan 3, 2024
AustinGreen
reviewed
Jan 3, 2024
Co-authored-by: hello-shreyas <[email protected]>
Co-authored-by: hello-shreyas <[email protected]>
Co-authored-by: hello-shreyas <[email protected]>
Co-authored-by: hello-shreyas <[email protected]>
Co-authored-by: Austin Green <[email protected]>
Co-authored-by: Austin Green <[email protected]>
AustinGreen
reviewed
Jan 3, 2024
AustinGreen
reviewed
Jan 3, 2024
AustinGreen
reviewed
Jan 8, 2024
AustinGreen
reviewed
Jan 8, 2024
AustinGreen
reviewed
Jan 8, 2024
AustinGreen
reviewed
Jan 8, 2024
AustinGreen
reviewed
Jan 8, 2024
AustinGreen
reviewed
Jan 8, 2024
|
Coverage after merging theo/docs into main will be
Coverage Report
|
|||||||||||||||||||||||||||||||||||||
AustinGreen
reviewed
Jan 9, 2024
| @@ -0,0 +1,9 @@ | |||
| # Llama Token Voting | |||
|
|
|||
| Llama Token Voting is extensions to Llama instances. They allow token holders to create actions and collectively cast approvals or disapprovals. The `LlamaTokenGovernor` contract follows established token voting framework best practices and is designed to integrate directly with instances. | |||
There was a problem hiding this comment.
Looks like there is a grammatical error at the start of the sentence here "Llama Token Voting is"
AustinGreen
reviewed
Jan 9, 2024
|
|
||
| Llama Token Voting is extensions to Llama instances. They allow token holders to create actions and collectively cast approvals or disapprovals. The `LlamaTokenGovernor` contract follows established token voting framework best practices and is designed to integrate directly with instances. | ||
|
|
||
| Llama Token Voting consists of two components: |
There was a problem hiding this comment.
Any reason why we're capitalizing Llama Token Voting here?
AustinGreen
reviewed
Jan 9, 2024
|
|
||
| `LlamaTokenGovernor` is the contract that enables token holders to create actions and cast votes/vetoes. | ||
|
|
||
| Llama Token Voting works by issuing a Llama policy to the `LlamaTokenGovernor` contract, which can hold roles and permissions that enable the contract to cast approvals/disapprovals and create actions. The Governor contract exposes this policyholder functionality via public functions to token holders. |
There was a problem hiding this comment.
I think it would be more grammatically correct to say the token voting module.
I think it makes sense to capitalize Llama since it's a proper noun and contract names like LlamaTokenGovernor, but I don't see why Governor should be capitalized here
AustinGreen
reviewed
Jan 9, 2024
| - The casting period | ||
| - The submission period | ||
|
|
||
| Llama Token Voting process begins with a delay period. This period is calculated by multiplying the `delayPeriodPct` by the action's approval or disapproval period. The purpose of the delay period is to provide token holders a window to delegate their tokens before voting balances are crystallized for the duration of the vote. |
There was a problem hiding this comment.
"Llama Token Voting process" is a grammatical error as well.
AustinGreen
reviewed
Jan 9, 2024
|
|
||
| Llama Token Voting process begins with a delay period. This period is calculated by multiplying the `delayPeriodPct` by the action's approval or disapproval period. The purpose of the delay period is to provide token holders a window to delegate their tokens before voting balances are crystallized for the duration of the vote. | ||
|
|
||
| The casting period is when token holders vote/veto a pending action. It is calculated as the product of the `votingPeriodPct` and the action's approval or disapproval period. It automatically begins at the end of the delay period. |
There was a problem hiding this comment.
I think it's worth adding a sentence that explains that voting occurs doing the approval period and vetoing occurs during the disapproval period.
AustinGreen
reviewed
Jan 9, 2024
|
|
||
| The casting period is when token holders vote/veto a pending action. It is calculated as the product of the `votingPeriodPct` and the action's approval or disapproval period. It automatically begins at the end of the delay period. | ||
|
|
||
| Finally, the submission period is when the result is submitted to the instance's `LlamaCore` contract if consensus is reached. It is calculated by subtract the `delayPeriodPct` and `votingPeriodPct` from `ONE_HUNDRED_IN_BPS`. It automatically begins at the end of the casting period. |
There was a problem hiding this comment.
Did you mean subtracting instead of subtract here?
There was a problem hiding this comment.
I think it's easier to just say the submission period is equal to 100% minus the delay and voting period. I wouldn't expect a reader to know what ONE_HUNDRED_IN_BPS is without looking at the code.
AustinGreen
reviewed
Jan 9, 2024
Comment on lines
+42
to
+48
| - Role: This parameter specifies the role of the token holder in the governance process. It is used to determine the permission ID of the `LlamaTokenGovernor`. | ||
| - ActionInfo: This struct contains all the necessary information about the action on which the vote is being cast, including the action ID, creator, strategy, target, value, and data. | ||
| - Support: Indicates the token holder's stance on the action. The values can be: | ||
| - 0 for Against | ||
| - 1 for For | ||
| - 2 for Abstain | ||
| - Reason: A human-readable string providing the rationale behind the token holder's vote. |
There was a problem hiding this comment.
We should bold these terms like we do in the llama docs
AustinGreen
reviewed
Jan 9, 2024
|
|
||
| The function returns the weight of the cast, representing the influence of the token holder's vote based on their token balance. | ||
|
|
||
| ### Casting Vetoes |
There was a problem hiding this comment.
I think the key point to communicate here is that castVote and castVeto are the same but votes occur during the approval period and vetoes occur during the disapproval period
AustinGreen
reviewed
Jan 9, 2024
|
|
||
| Note that if the Governor itself does not have the permission to create the action on the instance's `LlamaCore`, `createAction` will fail. | ||
|
|
||
| The action creation process is the same as the core Llama system, but instead of creating actions based on the user's policy and permissions the Governor's validation check is based on if they hold enough tokens. |
There was a problem hiding this comment.
I would say something like if they hold more tokens than the creation threshold instead of hold enough tokens
AustinGreen
reviewed
Jan 9, 2024
|
|
||
| The action creation process is the same as the core Llama system, but instead of creating actions based on the user's policy and permissions the Governor's validation check is based on if they hold enough tokens. | ||
|
|
||
| If unfamiliar with the canonical Llama action creation process, our the main [Llama docs](https://github.com/llamaxyz/llama/tree/main/docs) will help. |
There was a problem hiding this comment.
Looks like a typo/grammar mistake here with "our"
AustinGreen
reviewed
Jan 9, 2024
AustinGreen
reviewed
Jan 9, 2024
AustinGreen
reviewed
Jan 9, 2024
Sign up for free
to subscribe to this conversation on GitHub.
Already have an account?
Sign in.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Motivation:
We need docs for token voting, and this is an initial push.
Modifications:
Result:
initial documentation