Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add governance docs #9

Open
wants to merge 7 commits into
base: main
Choose a base branch
from
Open
Show file tree
Hide file tree
Changes from 1 commit
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
18 changes: 13 additions & 5 deletions docs/OpenBrush/smart-contracts/PSP22/Extensions/votes.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,18 +6,26 @@ This feature provides a way to use your token as a voting power. You can use it
To cast a vote in [Governor](../../governance/governor.md) contract you need to have some amount of tokens and delegate them to be used for voting.
The more tokens you have, the more voting power you have. The extension implements the [Votes](https://github.com/Brushfam/openbrush-contracts/tree/main/contracts/src/governance/utils/votes) trait which provides the ability to delegate tokens from one account to another for voting,
check the number of votes for a proposal, and check the number of votes delegated by a user.
It's a required tool to create a [Governor](../../governance/governor.md) contract.
It's a required tool to create a [Governor](../../governance/governor.md) contract.
Also, you can check the [documentation](https://docs.openzeppelin.com/contracts/4.x/api/token/erc20#ERC20Votes) in OpenZeppelin Contracts for more information about the voting mechanism.

This page describes how to create your own [PSP22Votes](/) contract.
## Step 1: Default implementation
## Step 1: Import default implementation

First, you should implement basic version of [PSP22](../psp22.md).

With [default `Cargo.toml`](../../overview.md/#the-default-toml-of-your-project-with-openbrush),
you need to enable `PSP22Votes` feature, embed modules data structures and implement them via `#[openbrush::implementation]` macro
as described in [that section](../../overview.md/#reuse-implementation-of-traits-from-openbrush).

you need to enable `governance` feature. Also, you need to use implementation macro
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It needs governance and psp22

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
you need to enable `governance` feature. Also, you need to use implementation macro
you need to enable `governance` feature. Also, you need to use the implementation macro

for PSP22Votes and Nonces:
```rust
#[openbrush::implementation(..., PSP22Votes, Nonces, ...)]
#[openbrush::contract]
pub mod your_contract {
...
}
```

You can check [that section](../../overview.md/#reuse-implementation-of-traits-from-openbrush) to understand how it works.

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
You can check [that section](../../overview.md/#reuse-implementation-of-traits-from-openbrush) to understand how it works.
You can check [this section](../../overview.md/#reuse-implementation-of-traits-from-openbrush) to understand how it works.



## Step 2: Set up your Storage
Expand Down
17 changes: 12 additions & 5 deletions docs/OpenBrush/smart-contracts/governance/Extensions/counting.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,16 +5,23 @@ title: GovernorCounting
This extension gives Governor contract the ability to manage and count votes of the contract.
You can see if a user has voted for a proposal, and get the number of votes for a proposal.
Also, this extension provides the ability to count your votes when you cast them, to realize when the quorum is reached, and to realize when the voting is succeeded.

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
Also, this extension provides the ability to count your votes when you cast them, to realize when the quorum is reached, and to realize when the voting is succeeded.
Also, this extension allows you to count your votes when you cast them, to see when the quorum is reached, and when the voting succeeds.

You can check the [documentation](https://docs.openzeppelin.com/contracts/4.x/api/governance#GovernorCountingSimple) in OpenZeppelin Contracts for more information about the counting mechanism.

This page describes how to connect GovernorCounting to Governor contract.
This page describes how to connect [GovernorCounting](/) to [Governor](../governor.md) contract.

## Step 1: Import default implementation

With [default `Cargo.toml`](../../overview.md/#the-default-toml-of-your-project-with-openbrush),
you need to enable `governance` feature, embed modules data structures and implement them via `#[openbrush::implementation]` macro
as described in [that section](../../overview.md/#reuse-implementation-of-traits-from-openbrush).

The main trait is `Governor`.
you need to enable `governance` feature. Also, you need to use implementation macro
for GovernorCounting:
```rust
#[openbrush::implementation(..., GovernorCounting, ...)]
#[openbrush::contract]
pub mod your_contract {
...
}
```
You can check [that section](../../overview.md/#reuse-implementation-of-traits-from-openbrush) to understand how it works.

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
You can check [that section](../../overview.md/#reuse-implementation-of-traits-from-openbrush) to understand how it works.
You can check [this section](../../overview.md/#reuse-implementation-of-traits-from-openbrush) to understand how it works.


## Step 2: Add GovernorCounting field in your Storage
GovernorCounting field in your Storage should be named `governor_counting` and have type `governor_counting::Data`.
Expand Down
18 changes: 12 additions & 6 deletions docs/OpenBrush/smart-contracts/governance/Extensions/quorum.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,16 +8,23 @@ Quorum is calculated as `quorum_numerator * total_votes / quorum_denominator`.
Of course, the value of total votes is not constant, it changes with every vote.
So, the quorum calculates in specific moments of time. It is possible because all votes are stored in [checkpoints]() structure,
that is updated every time when a vote is created or changed.
Also, you can check the [documentation](https://docs.openzeppelin.com/contracts/4.x/api/governance#GovernorQuorumFraction) in OpenZeppelin Contracts for more information about the quorum calculation mechanism.

This page describes how to connect GovernorQuorum to Governor contract.
This page describes how to connect [GovernorQuorum](/) to [Governor](../governor.md) contract.

## Step 1: Import default implementation

With [default `Cargo.toml`](../../overview.md/#the-default-toml-of-your-project-with-openbrush),
you need to enable `governance` feature, embed modules data structures and implement them via `#[openbrush::implementation]` macro
as described in [that section](../../overview.md/#reuse-implementation-of-traits-from-openbrush).

The main trait is `Governor`.
you need to enable `governance` feature. Also, you need to use implementation macro
for GovernorQuorum:
```rust
#[openbrush::implementation(..., GovernorQuorum, ...)]
#[openbrush::contract]
pub mod your_contract {
...
}
```
You can check [that section](../../overview.md/#reuse-implementation-of-traits-from-openbrush) to understand how it works.

## Step 2: Include GovernorQuorum initialization in constructor

Expand Down Expand Up @@ -53,7 +60,6 @@ pub struct Contract {
...
}
```

That's it! Now you can use [GovernorQuorum](/) extension in your [Governor](../governor.md) contract.

You can check an example of the usage of [Governance](https://github.com/Brushfam/openbrush-contracts/tree/main/examples/governance/governor).
18 changes: 12 additions & 6 deletions docs/OpenBrush/smart-contracts/governance/Extensions/settings.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,17 +5,23 @@ title: GovernorSettings
This extension gives Governor contract the ability to set and get settings of the contract.
With this extension, you can set and get voting delay(The time between proposing and vote starting),
voting period, proposal threshold(The amount of votes that need to propose a proposal).

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
voting period, proposal threshold(The amount of votes that need to propose a proposal).
voting period, proposal threshold(The amount of votes required to propose a proposal).

Also, you can check the [documentation](https://docs.openzeppelin.com/contracts/4.x/api/governance#GovernorSettings) in OpenZeppelin Contracts for more information about the settings mechanism.

This page describes how to connect GovernorSettings to Governor contract.
This page describes how to connect [GovernorSettings](/) to [Governor](../governor.md) contract.

## Step 1: Import default implementation

With [default `Cargo.toml`](../../overview.md/#the-default-toml-of-your-project-with-openbrush),
you need to enable `governance` feature, embed modules data structures and implement them via `#[openbrush::implementation]` macro
as described in [that section](../../overview.md/#reuse-implementation-of-traits-from-openbrush).

The main trait is `Governor`.

you need to enable `governance` feature. Also, you need to use implementation macro
for GovernorSettings:
```rust
#[openbrush::implementation(..., GovernorSettings, ...)]
#[openbrush::contract]
pub mod your_contract {
...
}
```
You can check [that section](../../overview.md/#reuse-implementation-of-traits-from-openbrush) to understand how it works.

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
You can check [that section](../../overview.md/#reuse-implementation-of-traits-from-openbrush) to understand how it works.
You can check [this section](../../overview.md/#reuse-implementation-of-traits-from-openbrush) to understand how it works.

## Step 2: Include GovernorSettings initialization in constructor

We need to initialize [GovernorSettings](/) extension in the constructor of [Governor](../governor.md) contract.
Expand Down
15 changes: 13 additions & 2 deletions docs/OpenBrush/smart-contracts/governance/Extensions/votes.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,14 +4,25 @@ title: GovernorVotes
---
This extension gives Governor contract the ability to communicate with [PSP22Votes](../../PSP22/Extensions/votes.md) token.
The main purpose of this extension is to provide a way to check how much voting power a voter has.
Also, it provides the ability to delegate tokens from one account to another for voting.
You can check the [documentation](https://docs.openzeppelin.com/contracts/4.x/api/governance#GovernorVotes) in OpenZeppelin Contracts for more information about the voting mechanism.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm not actually sure that it's the best idea to point directly to OpenZeppelin, maybe there is some other link?


This page describes how to connect [Governor](../governor.md) with [PSP22Votes](../../PSP22/Extensions/votes.md) token using [GovernorVotes](/) extension.

## Step 1: Import default implementation

With [default `Cargo.toml`](../../overview.md/#the-default-toml-of-your-project-with-openbrush),
you need to enable `governance` feature, embed modules data structures and implement them via `#[openbrush::implementation]` macro
as described in [that section](../../overview.md/#reuse-implementation-of-traits-from-openbrush).
you need to enable `governance` feature. Also, you need to use implementation macro
for GovernorVotes:
```rust
#[openbrush::implementation(..., GovernorVotes, ...)]
#[openbrush::contract]
pub mod your_contract {
...
}
```

You can check [that section](../../overview.md/#reuse-implementation-of-traits-from-openbrush) to understand how it works.

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
You can check [that section](../../overview.md/#reuse-implementation-of-traits-from-openbrush) to understand how it works.
You can check [this section](../../overview.md/#reuse-implementation-of-traits-from-openbrush) to understand how it works.


The main trait is `Governor`.

Expand Down
18 changes: 13 additions & 5 deletions docs/OpenBrush/smart-contracts/governance/governor.md
Original file line number Diff line number Diff line change
Expand Up @@ -5,15 +5,23 @@ title: Governance
This feature provides a governance mechanism. It allows token holders to vote on proposals and change the token's parameters.
Everybody who has enough votes can create a proposal to call a method of some contract with some arguments. Then token holders can vote for, against the proposal, or abstain.

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If they abstain, they basically do not vote so we don't need to mention it here)

Suggested change
Everybody who has enough votes can create a proposal to call a method of some contract with some arguments. Then token holders can vote for, against the proposal, or abstain.
Everybody who has enough votes can create a proposal to call a method of some contract with some arguments. Then token holders can vote for or against the proposal.

When the voting period ends, the proposal can be executed if the proposal status is `Succeeded` and the quorum is reached or declined otherwise.

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This sounds like the quorum could be declined, we can remove that part of the sentence and simply say it can be executed if (condition)

Suggested change
When the voting period ends, the proposal can be executed if the proposal status is `Succeeded` and the quorum is reached or declined otherwise.
When the voting period ends, the proposal can be executed if the proposal status is `Succeeded` and the quorum is reached.

This example shows how you can use the implementation of [Governance](https://github.com/Brushfam/openbrush-contracts/tree/main/contracts/src/governance) token.
This example shows how you can use the implementation of [Governance](https://github.com/Brushfam/openbrush-contracts/tree/main/contracts/src/governance) token.
Also you can check the [documentation](https://docs.openzeppelin.com/contracts/4.x/api/governance) in OpenZeppelin Contracts
for more information about the governance mechanism.

## Step 1: Import default implementation

With [default `Cargo.toml`](../overview.md/#the-default-toml-of-your-project-with-openbrush),
you need to enable `governance` feature, embed modules data structures and implement them via `#[openbrush::implementation]` macro
as described in [that section](../overview.md/#reuse-implementation-of-traits-from-openbrush).

The main trait is `Governor`.
you need to enable `governance` feature. Also, you need to use implementation macro
for Governor and all required extensions:
```rust
#[openbrush::implementation(Governor, GovernorVotes, GovernorSettings, GovernorCounting, GovernorQuorum)]
#[openbrush::contract]
pub mod your_contract {
...
}
```
You can check [that section](../overview.md/#reuse-implementation-of-traits-from-openbrush) to understand how it works.

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
You can check [that section](../overview.md/#reuse-implementation-of-traits-from-openbrush) to understand how it works.
You can check [this section](../overview.md/#reuse-implementation-of-traits-from-openbrush) to understand how it works.


## Step 2: Define constructor

Expand Down