mirror of
https://github.com/pezkuwichain/pezkuwi-subxt.git
synced 2026-04-26 11:07:56 +00:00
Chevdor
a30092ab42
* Add markdown linting - add linter default rules - adapt rules to current code - fix the code for linting to pass - add CI check fix #1243 * Fix markdown for Substrate * Fix tooling install * Fix workflow * Add documentation * Remove trailing spaces * Update .github/.markdownlint.yaml Co-authored-by: Oliver Tale-Yazdi <oliver.tale-yazdi@parity.io> * Fix mangled markdown/lists * Fix captalization issues on known words
229 lines
9.5 KiB
Markdown
229 lines
9.5 KiB
Markdown
# Society Module
|
|
|
|
- [`society::Config`](https://docs.rs/pallet-society/latest/pallet_society/trait.Config.html)
|
|
- [`Call`](https://docs.rs/pallet-society/latest/pallet_society/enum.Call.html)
|
|
|
|
## Overview
|
|
|
|
The Society module is an economic game which incentivizes users to participate
|
|
and maintain a membership society.
|
|
|
|
### User Types
|
|
|
|
At any point, a user in the society can be one of a:
|
|
- Bidder - A user who has submitted intention of joining the society.
|
|
- Candidate - A user who will be voted on to join the society.
|
|
- Suspended Candidate - A user who failed to win a vote.
|
|
- Member - A user who is a member of the society.
|
|
- Suspended Member - A member of the society who has accumulated too many strikes
|
|
or failed their membership challenge.
|
|
|
|
Of the non-suspended members, there is always a:
|
|
- Head - A member who is exempt from suspension.
|
|
- Defender - A member whose membership is under question and voted on again.
|
|
|
|
Of the non-suspended members of the society, a random set of them are chosen as
|
|
"skeptics". The mechanics of skeptics is explained in the
|
|
[member phase](https://docs.rs/pallet-society/latest/pallet_society/#member-phase) below.
|
|
|
|
### Mechanics
|
|
|
|
#### Rewards
|
|
|
|
Members are incentivized to participate in the society through rewards paid
|
|
by the Society treasury. These payments have a maturity period that the user
|
|
must wait before they are able to access the funds.
|
|
|
|
#### Punishments
|
|
|
|
Members can be punished by slashing the reward payouts that have not been
|
|
collected. Additionally, members can accumulate "strikes", and when they
|
|
reach a max strike limit, they become suspended.
|
|
|
|
#### Skeptics
|
|
|
|
During the voting period, a random set of members are selected as "skeptics".
|
|
These skeptics are expected to vote on the current candidates. If they do not vote,
|
|
their skeptic status is treated as a rejection vote, the member is deemed
|
|
"lazy", and are given a strike per missing vote.
|
|
|
|
#### Membership Challenges
|
|
|
|
Every challenge rotation period, an existing member will be randomly selected
|
|
to defend their membership into society. Then, other members can vote whether
|
|
this defender should stay in society. A simple majority wins vote will determine
|
|
the outcome of the user. Ties are treated as a failure of the challenge, but
|
|
assuming no one else votes, the defender always get a free vote on their
|
|
own challenge keeping them in the society. The Head member is exempt from the
|
|
negative outcome of a membership challenge.
|
|
|
|
#### Society Treasury
|
|
|
|
The membership society is independently funded by a treasury managed by this
|
|
module. Some subset of this treasury is placed in a Society Pot, which is used
|
|
to determine the number of accepted bids.
|
|
|
|
#### Rate of Growth
|
|
|
|
The membership society can grow at a rate of 10 accepted candidates per rotation period up
|
|
to the max membership threshold. Once this threshold is met, candidate selections
|
|
are stalled until there is space for new members to join. This can be resolved by
|
|
voting out existing members through the random challenges or by using governance
|
|
to increase the maximum membership count.
|
|
|
|
### User Life Cycle
|
|
|
|
A user can go through the following phases:
|
|
|
|
```rust
|
|
+-------> User <----------+
|
|
| + |
|
|
| | |
|
|
+----------------------------------------------+
|
|
| | | | |
|
|
| | v | |
|
|
| | Bidder <-----------+ |
|
|
| | + | |
|
|
| | | + |
|
|
| | v Suspended |
|
|
| | Candidate +----> Candidate |
|
|
| | + + |
|
|
| | | | |
|
|
| + | | |
|
|
| Suspended +------>| | |
|
|
| Member | | |
|
|
| ^ | | |
|
|
| | v | |
|
|
| +-------+ Member <----------+ |
|
|
| |
|
|
| |
|
|
+------------------Society---------------------+
|
|
```
|
|
|
|
#### Initialization
|
|
|
|
The society is initialized with a single member who is automatically chosen as the Head.
|
|
|
|
#### Bid Phase
|
|
|
|
New users must have a bid to join the society.
|
|
|
|
A user can make a bid by reserving a deposit. Alternatively, an already existing member
|
|
can create a bid on a user's behalf by "vouching" for them.
|
|
|
|
A bid includes reward information that the user would like to receive for joining
|
|
the society. A vouching bid can additionally request some portion of that reward as a tip
|
|
to the voucher for vouching for the prospective candidate.
|
|
|
|
Every rotation period, Bids are ordered by reward amount, and the module
|
|
selects as many bids the Society Pot can support for that period.
|
|
|
|
These selected bids become candidates and move on to the Candidate phase.
|
|
Bids that were not selected stay in the bidder pool until they are selected or
|
|
a user chooses to "unbid".
|
|
|
|
#### Candidate Phase
|
|
|
|
Once a bidder becomes a candidate, members vote whether to approve or reject
|
|
that candidate into society. This voting process also happens during a rotation period.
|
|
|
|
The approval and rejection criteria for candidates are not set on chain,
|
|
and may change for different societies.
|
|
|
|
At the end of the rotation period, we collect the votes for a candidate
|
|
and randomly select a vote as the final outcome.
|
|
|
|
```rust
|
|
[ a-accept, r-reject, s-skeptic ]
|
|
+----------------------------------+
|
|
| |
|
|
| Member |0|1|2|3|4|5|6|7|8|9| |
|
|
| ----------------------------- |
|
|
| Vote |a|a|a|r|s|r|a|a|s|a| |
|
|
| ----------------------------- |
|
|
| Selected | | | |x| | | | | | | |
|
|
| |
|
|
+----------------------------------+
|
|
|
|
Result: Rejected
|
|
```
|
|
|
|
Each member that voted opposite to this randomly selected vote is punished by
|
|
slashing their unclaimed payouts and increasing the number of strikes they have.
|
|
|
|
These slashed funds are given to a random user who voted the same as the
|
|
selected vote as a reward for participating in the vote.
|
|
|
|
If the candidate wins the vote, they receive their bid reward as a future payout.
|
|
If the bid was placed by a voucher, they will receive their portion of the reward,
|
|
before the rest is paid to the winning candidate.
|
|
|
|
One winning candidate is selected as the Head of the members. This is randomly
|
|
chosen, weighted by the number of approvals the winning candidates accumulated.
|
|
|
|
If the candidate loses the vote, they are suspended and it is up to the Suspension
|
|
Judgement origin to determine if the candidate should go through the bidding process
|
|
again, should be accepted into the membership society, or rejected and their deposit
|
|
slashed.
|
|
|
|
#### Member Phase
|
|
|
|
Once a candidate becomes a member, their role is to participate in society.
|
|
|
|
Regular participation involves voting on candidates who want to join the membership
|
|
society, and by voting in the right way, a member will accumulate future payouts.
|
|
When a payout matures, members are able to claim those payouts.
|
|
|
|
Members can also vouch for users to join the society, and request a "tip" from
|
|
the fees the new member would collect by joining the society. This vouching
|
|
process is useful in situations where a user may not have enough balance to
|
|
satisfy the bid deposit. A member can only vouch one user at a time.
|
|
|
|
During rotation periods, a random group of members are selected as "skeptics".
|
|
These skeptics are expected to vote on the current candidates. If they do not vote,
|
|
their skeptic status is treated as a rejection vote, the member is deemed
|
|
"lazy", and are given a strike per missing vote.
|
|
|
|
There is a challenge period in parallel to the rotation period. During a challenge period,
|
|
a random member is selected to defend their membership to the society. Other members
|
|
make a traditional majority-wins vote to determine if the member should stay in the society.
|
|
Ties are treated as a failure of the challenge.
|
|
|
|
If a member accumulates too many strikes or fails their membership challenge,
|
|
they will become suspended. While a member is suspended, they are unable to
|
|
claim matured payouts. It is up to the Suspension Judgement origin to determine
|
|
if the member should re-enter society or be removed from society with all their
|
|
future payouts slashed.
|
|
|
|
## Interface
|
|
|
|
### Dispatchable Functions
|
|
|
|
#### For General Users
|
|
|
|
- `bid` - A user can make a bid to join the membership society by reserving a deposit.
|
|
- `unbid` - A user can withdraw their bid for entry, the deposit is returned.
|
|
|
|
#### For Members
|
|
|
|
- `vouch` - A member can place a bid on behalf of a user to join the membership society.
|
|
- `unvouch` - A member can revoke their vouch for a user.
|
|
- `vote` - A member can vote to approve or reject a candidate's request to join the society.
|
|
- `defender_vote` - A member can vote to approve or reject a defender's continued membership
|
|
to the society.
|
|
- `payout` - A member can claim their first matured payment.
|
|
- `unfound` - Allow the founder to unfound the society when they are the only member.
|
|
|
|
#### For Super Users
|
|
|
|
- `found` - The founder origin can initiate this society. Useful for bootstrapping the Society
|
|
pallet on an already running chain.
|
|
- `judge_suspended_member` - The suspension judgement origin is able to make
|
|
judgement on a suspended member.
|
|
- `judge_suspended_candidate` - The suspension judgement origin is able to
|
|
make judgement on a suspended candidate.
|
|
- `set_max_membership` - The ROOT origin can update the maximum member count for the society.
|
|
The max membership count must be greater than 1.
|
|
|
|
License: Apache-2.0
|