Society Module

• society::Config
• Call

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 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:

          +------->  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.

 [ 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

Release

Polkadot SDK stable2409