Skip to content

Commit 48220cd

Browse files
committed
update readme
1 parent 632da16 commit 48220cd

1 file changed

Lines changed: 24 additions & 99 deletions

File tree

pallets/governance/README.md

Lines changed: 24 additions & 99 deletions
Original file line numberDiff line numberDiff line change
@@ -37,11 +37,6 @@ The governance system consists of three main actors working together:
3737
- Can eject its own key from the allowed proposers list (i.e., if it is lost or compromised)
3838
- Can propose an update to the allowed proposers list via proposal flow
3939

40-
**Open Questions:**
41-
42-
- Q1: Who can add/remove proposer accounts? Only governance or should Triumvirate have emergency powers?
43-
- Q2: Who validates that proposal code matches stated intent before Triumvirate votes? Share runtime WASM hash like Polkadot fellowship does?
44-
4540
#### Triumvirate
4641

4742
- **Composition**: 3 distinct accounts (must always maintain 3 members)
@@ -52,28 +47,18 @@ The governance system consists of three main actors working together:
5247
- **Permissions**:
5348
- Can vote on proposals submitted by allowed proposers
5449

55-
**Open Questions:**
56-
57-
- Q3: How to allow a triumvirate member to resign?
58-
5950
#### Economic and Building Collectives
6051

6152
- **Economic Collective**: Top 16 validators by total stake (including delegated stake) (configurable)
6253
- **Building Collective**: Top 16 subnet owners by moving average price (with minimum age of 6 months) (configurable)
54+
- **Total Collective Size**: 32 members (16 Economic + 16 Building)
6355
- **Recalculation**: Membership refreshed every 6 months (configurable)
6456
- **Permissions**:
6557
- Can vote aye/nay on proposals submitted by allowed proposers and approved by Triumvirate
66-
- More than 2/3 of aye vote for any collective fast tracks the proposal (next block execution) (threshold configurable)
67-
- More than 1/2 of nay vote for any collective cancels the proposal (threshold configurable)
68-
- Nays votes accumulate and delay the proposal execution exponentially until cancellation (see Delay Period section)
69-
- Can replace a Triumvirate member every 6 months via single atomic vote (remove current holder + install replacement candidate, with rotating seat selection)
70-
- Can mark himself as eligible for nomination to the Triumvirate
71-
- Can accept a nomination to the Triumvirate
72-
73-
**Open Questions:**
74-
75-
- Q4: How to handle the nomination process?
76-
- Q5: How to incentivize the collective members to vote?
58+
- Votes are aggregated across both collectives (total of 32 possible votes)
59+
- More than configured threshold of aye votes (based on total collective size of 32) fast tracks the proposal (next block execution) (threshold configurable)
60+
- More than configured threshold of nay votes (based on total collective size of 32) cancels the proposal (threshold configurable)
61+
- Delay is calculated using net score (nays - ayes) and applies exponential delay until cancellation (see Delay Period section)
7762

7863
### Governance Process Flow
7964

@@ -102,91 +87,31 @@ The governance system consists of three main actors working together:
10287

10388
When a proposal has been approved by the Triumvirate, it is scheduled in 1 hour (configurable) and enters the "Delay Period" where the Economic and Building Collectives can vote to delay, cancel or fast-track the proposal.
10489

105-
1. Both collectives can vote aye/nay on the proposal
106-
2. Delay is an exponential function of the number of nays votes, set to 2^n (configurable).
90+
1. Both collectives can vote aye/nay on the proposal, with votes aggregated across all 32 collective members
91+
2. Delay is calculated using **net score** (nays - ayes) and applies an exponential function based on a configurable delay factor.
10792

10893
- Initial delay is 1 hour (configurable).
109-
- After 1 nays vote, the delay is 2^1 \* 1 hour = 2 hours.
110-
- After 2 nays votes, the delay is 2^2 \* 1 hour = 4 hours.
111-
- After 3 nays votes, the delay is 2^3 \* 1 hour = 8 hours.
112-
- After 4 nays votes, the delay is 2^4 \* 1 hour = 16 hours.
113-
- After 5 nays votes, the delay is 2^5 \* 1 hour = 32 hours.
114-
- After 6 nays votes, the delay is 2^6 \* 1 hour = 64 hours.
115-
- After 7 nays votes, the delay is 2^7 \* 1 hour = 128 hours.
116-
- After 8 nays votes, the delay is 2^8 \* 1 hour = 256 hours.
117-
- After 9 nays votes, proposal is cancelled (given we have a collective size of 16, hence more than 1/2 of the collective votes nay).
94+
- Net score = (number of nays) - (number of ayes)
95+
- If net score > 0: additional delay = initial_delay × (delay_factor ^ net_score)
96+
- If net score ≤ 0: no additional delay (proposal can be fast-tracked if net score becomes negative)
97+
- **Example with delay_factor = 2**:
98+
- Net score of 1 (e.g., 1 nay, 0 ayes): delay = 1 hour × 2^1 = 2 hours
99+
- Net score of 2 (e.g., 2 nays, 0 ayes): delay = 1 hour × 2^2 = 4 hours
100+
- Net score of 3 (e.g., 3 nays, 0 ayes): delay = 1 hour × 2^3 = 8 hours
101+
- Net score of 4 (e.g., 4 nays, 0 ayes): delay = 1 hour × 2^4 = 16 hours
102+
- Net score of 5 (e.g., 5 nays, 0 ayes): delay = 1 hour × 2^5 = 32 hours
103+
- Net score of 16 (e.g., 16 nays, 0 ayes): delay = 1 hour × 2^16 = 65,536 hours
104+
- Net score of 17 (e.g., 17 nays, 0 ayes): proposal is cancelled (threshold configurable, typically ≥ 17 nays out of 32 total members)
118105

119106
3. If the delay period expires without cancellation: Proposal executes automatically
120107

121-
- The delay is calculated based on the collective with the most nays votes (i.e., if Economic has 3 nays and Building has 1 nay, the delay is based on 3 nays = 8 hours).
122-
- More than 2/3 of aye vote for any collective fast tracks the proposal (next block execution) (threshold configurable)
123-
- More than 1/2 of nay vote for any collective cancels the proposal (threshold configurable)
124-
- Collective members can change their vote during the delay period. If changing a nay vote to aye reduces the delay below the time already elapsed, the proposal executes immediately.
125-
- **Example**: A proposal has 3 nays votes, creating a 8 hours delay. After 5 hours have elapsed, a collective member changes their nay vote to aye, reducing the delay to 4 hours. Since 5 hours have already passed (more than the new 4 hours delay), the proposal executes immediately.
126-
127-
**Open Questions:**
128-
129-
- Q6: Should the voting be across both collectives or each collective votes independently? What if a collective decide to go rogue and fast track proposals that the other collective is against or vice versa?
108+
- The delay is calculated based on the **net score** across both collectives (total of 32 members), not per collective
109+
- More than configured threshold of aye votes (based on total collective size of 32) fast tracks the proposal (next block execution) (threshold configurable)
110+
- More than configured threshold of nay votes (based on total collective size of 32) cancels the proposal (threshold configurable, typically ≥ 17 nays)
111+
- Collective members can change their vote during the delay period. If changing a nay vote to aye (or vice versa) changes the net score such that the delay is reduced below the time already elapsed, the proposal executes immediately.
112+
- **Example**: A proposal has net score of 3 (3 nays, 0 ayes), creating an 8 hour delay. After 5 hours have elapsed, a collective member changes their nay vote to aye, reducing the net score to 2 (2 nays, 1 aye) and the delay to 4 hours. Since 5 hours have already passed (more than the new 4 hours delay), the proposal executes immediately.
130113

131114
#### Execution
132115

133116
- Proposals executed automatically after the delay period if not cancelled or when fast-tracked by the collectives.
134-
- If executing fails, the proposal is not retried and is cleaned up from storage.
135-
136-
### Triumvirate Replacement Mechanism
137-
138-
Each collective can replace one Triumvirate member every 6 months through a **single atomic vote**: the collective votes to replace the current seat holder with a randomly selected new candidate from the eligible candidates. If the vote succeeds, the replacement happens immediately. The Triumvirate always maintains exactly 3 active members.
139-
140-
#### Timing
141-
142-
- Each collective can initiate replacement vote every 6 months (configurable)
143-
- Economic and Building collectives have independent cycles (seat are rotated independently)
144-
145-
**Open Questions:**
146-
147-
- Q7: How to have an emergency replacement vote?
148-
- Q8: Can a replaced member be voted back in immediately, or should there be a cooldown period?
149-
150-
#### Rotating Seat Selection
151-
152-
- Triumvirate seats are numbered: Seat 0, Seat 1, Seat 2
153-
- Each collective maintains an independent rotation index that determines which seat they target:
154-
- Economic Power automatically targets the next seat in rotation:
155-
- If last removal was Seat 0, next automatically targets Seat 1
156-
- If last removal was Seat 1, next automatically targets Seat 2
157-
- If last removal was Seat 2, next automatically targets Seat 0
158-
- Building Power has independent automatic rotation
159-
- Rotation ensures no single seat is disproportionately targeted
160-
- Collective members cannot choose which seat to target: it's determined automatically
161-
162-
#### Replacement Process (Single Atomic Vote)
163-
164-
The replacement happens in a single vote where the collective votes **both** to remove the current seat holder **and** to install a specific replacement candidate. This is an atomic operation: either both happen or neither happens.
165-
166-
**Process:**
167-
168-
1. **Eligibility Phase**: Collective members can mark themselves as eligible for nomination to the Triumvirate.
169-
2. **Voting Phase**: Collective members can vote aye/nay during the voting period to replace the current seat holder.
170-
- Threshold of more than 1/2 of the collective size (configurable)
171-
- **If vote succeeds**: Current seat holder immediately removed, replacement candidate immediately installed
172-
- **If vote fails**: No change, current member remains.
173-
3. **Selection Phase**: The replacement candidate is selected randomly from the eligible candidates.
174-
4. **Validation Phase**: The replacement candidate validates their nomination on-chain to avoid nominating inactive members.
175-
5. **Transition**: Atomic swap ensures Triumvirate always has exactly 3 members with no vacancy period
176-
177-
### Implementation Phases
178-
179-
#### Phase 1: Coexistence (Duration: TBD)
180-
181-
1. Remove dead code: triumvirate collective and senate pallets and related code
182-
2. Implement the governance as a new pallet
183-
3. Deploy new governance pallet to runtime
184-
4. Configure initial Triumvirate members and allowed proposers.
185-
5. Run new governance system in parallel with existing sudo multisig
186-
6. Emergency procedures documented and tested
187-
7. Community review and feedback period
188-
189-
#### Phase 2: Full Migration
190-
191-
1. Disable sudo pallet via governance vote (new runtime)
192-
2. New governance system becomes sole authority
117+
- If executing fails, the proposal is not retried and is cleaned up from storage.

0 commit comments

Comments
 (0)