feat: linear quorums

.env.localnet.template

@@ -19,8 +19,8 @@ TEST_XGOV_DAEMON=AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAY5HFKQ
 # XGOV_CFG_MAX_REQUESTED_AMOUNT=25_000_000_000,100_000_000_000,200_000_000_000  # 25K (S), 100K (M), 250K (L) ALGO in microALGO
 # XGOV_CFG_DISCUSSION_DURATION=1_814_400,1_814_400,1_814_400,2_419_200  # 3 (S), 3 (M), 3 (L), 4 (XL) weeks in seconds
 # XGOV_CFG_VOTING_DURATION=604_800,604_800,1_209_600,2_419_200  # 1 (S), 1 (M), 2 (L), 4 (XL) weeks in seconds
-# XGOV_CFG_QUORUM=3_000,5_000,7_000  # 30 (S), 50 (M), 70 (L) % in bps
-# XGOV_CFG_WEIGHTED_QUORUM=5_000,6_000,7_000  # 50 (S), 60 (M), 70 (L) % in bps
+# XGOV_CFG_QUORUM=3_000,0,7_000  # 30 (S), 0 (M), 70 (L) % in bps
+# XGOV_CFG_WEIGHTED_QUORUM=5_000,0,7_000  # 50 (S), 0 (M), 70 (L) % in bps
 ## Lenient
 XGOV_CFG_XGOV_FEE=1_000_000  # 1 ALGO in microALGO
 XGOV_CFG_PROPOSER_FEE=1_000_000  # 1 ALGO in microALGO
@@ -31,5 +31,5 @@ XGOV_CFG_MIN_REQUESTED_AMOUNT=1_000_000  # 1 ALGO in microALGO
 XGOV_CFG_MAX_REQUESTED_AMOUNT=10_000_000,20_000_000,30_000_000  # 10 (S), 20 (M), 30 (L) ALGO in microALGO
 XGOV_CFG_DISCUSSION_DURATION=60,60,60,60  # 1 (S), 1 (M), 1 (L), 1 (XL) minutes in seconds
 XGOV_CFG_VOTING_DURATION=3_600,3_600,3_600,3_600  # 1 (S), 1 (M), 1 (L), 1 (XL) hours in seconds
-XGOV_CFG_QUORUM=500,1_000,2_000  # 5 (S), 10 (M), 20 (L) % in bps
-XGOV_CFG_WEIGHTED_QUORUM=500,1_000,2_000  # 5 (S), 10 (M), 20 (L) % in bps
+XGOV_CFG_QUORUM=500,0,2_000  # 5 (S), 0 (M), 20 (L) % in bps
+XGOV_CFG_WEIGHTED_QUORUM=500,0,2_000  # 5 (S), 0 (M), 20 (L) % in bps

.github/workflows/xgov-beta-sc-cd.yml

@@ -168,5 +168,5 @@ jobs:
           XGOV_CFG_MAX_REQUESTED_AMOUNT: ${{ vars.MAX_REQUESTED_AMOUNT || '10_000_000,20_000_000,30_000_000' }} # defaults: 10 (S), 20 (M), 30 (L) ALGO in microALGO
           XGOV_CFG_DISCUSSION_DURATION: ${{ vars.DISCUSSION_DURATION || '60,60,60,60' }} # defaults: 1 (S), 1 (M), 1 (L), 1 (XL) minute in seconds
           XGOV_CFG_VOTING_DURATION: ${{ vars.VOTING_DURATION || '3_600,3_600,3_600,3_600' }} # defaults: 1 (S), 1 (M), 1 (L), 1 (XL) hours in seconds
-          XGOV_CFG_QUORUM: ${{ vars.QUORUM || '500,1_000,2_000' }} # defaults: 5 (S), 10 (M), 20 (L) % in bps
-          XGOV_CFG_WEIGHTED_QUORUM: ${{ vars.WEIGHTED_QUORUM || '500,1_000,2_000' }} # defaults: 5 (S), 10 (M), 20 (L) % in bps
+          XGOV_CFG_QUORUM: ${{ vars.QUORUM || '500,0,2_000' }} # defaults: 5 (S), 0 (M), 20 (L) % in bps
+          XGOV_CFG_WEIGHTED_QUORUM: ${{ vars.WEIGHTED_QUORUM || '500,0,2_000' }} # defaults: 5 (S), 0 (M), 20 (L) % in bps

docs/SUMMARY.md

@@ -17,6 +17,7 @@
 - [xGov Committee](./specs/xgov-committee.md)
 - [Proposers](./specs/proposers.md)
 - [Proposal](./specs/proposal.md)
+  - [Escrow](./specs/proposal-escrow.md)
   - [Creation](./specs/proposal-creation.md)
   - [Discussion and Submission](./specs/proposal-submission.md)
   - [Vote and Review](./specs/proposal-vote.md)

docs/implementation/configuration.md

@@ -17,9 +17,7 @@
 | Voting duration Small           |     \\( 1 \\)     |          Week          |       \\( 604{,}800 \\)       | seconds  |
 | Voting duration Medium          |     \\( 1 \\)     |          Week          |       \\( 604{,}800 \\)       | seconds  |
 | Voting duration Large           |     \\( 2 \\)     |          Week          |     \\( 1{,}209{,}600 \\)     | seconds  |
-| Quorum Small                    |    \\( 30 \\)     |           %            |        \\( 3{,}000 \\)        |   bps    |
-| Quorum Medium                   |    \\( 50 \\)     |           %            |        \\( 5{,}000 \\)        |   bps    |
-| Quorum Large                    |    \\( 70 \\)     |           %            |        \\( 7{,}000 \\)        |   bps    |
-| Weighted Quorum Small           |    \\( 50 \\)     |           %            |         \\( 5,000 \\)         |   bps    |
-| Weighted Quorum Medium          |    \\( 60 \\)     |           %            |         \\( 6,000 \\)         |   bps    |
-| Weighted Quorum Large           |    \\( 70 \\)     |           %            |         \\( 7,000 \\)         |   bps    |
+| Quorum Min                      |    \\( 30 \\)     |           %            |        \\( 3{,}000 \\)        |   bps    |
+| Quorum Max                      |    \\( 70 \\)     |           %            |        \\( 7{,}000 \\)        |   bps    |
+| Weighted Quorum Min             |    \\( 50 \\)     |           %            |        \\( 5{,}000 \\)        |   bps    |
+| Weighted Quorum Max             |    \\( 70 \\)     |           %            |        \\( 7{,}000 \\)        |   bps    |

docs/specs/proposal-escrow.md

@@ -0,0 +1,31 @@
+# Escrow
+
+The Proposal Escrow is an Address controlled by the Proposal Application.
+
+## Escrow Inflows
+
+| FLOW                        | FROM          | TO              |         AMOUNT          | METHOD                             | CONDITION |
+|:----------------------------|:--------------|:----------------|:-----------------------:|:-----------------------------------|:----------|
+| Open Proposal               | xGov Treasury | Proposal Escrow |  Partial Proposal Fee   | `open_proposal` (on xGov Registry) |           |
+| Deposit Proposal Commitment | Proposer      | Proposal Escrow | Proposal Locked Deposit | `open`                             |           |
+
+## Escrow Outflows
+
+| FLOW                       | FROM            | TO            |             AMOUNT             | METHOD     | CONDITION                           |
+|:---------------------------|:----------------|:--------------|:------------------------------:|:-----------|:------------------------------------|
+| Operations Funding         | Proposal Escrow | xGov Daemon   |     % of Open Proposal Fee     | `submit`   |                                     |
+| Return Proposal Commitment | Proposal Escrow | Proposer      |    Proposal Locked Deposit     | `drop`     |                                     |
+| Return Proposal Commitment | Proposal Escrow | Proposer      |    Proposal Locked Deposit     | `scrutiny` | Proposal is rejected                |
+| Return Proposal Commitment | Proposal Escrow | Proposer      |    Proposal Locked Deposit     | `finalize` | Proposal is dropped for staleness   |
+| Return Proposal Commitment | Proposal Escrow | Proposer      |    Proposal Locked Deposit     | `review`   | Veto is not applied (`block=False`) |
+| Slash Proposal Commitment  | Proposal Escrow | xGov Treasury |    Proposal Locked Deposit     | `review`   | Veto is applied (`block=True`)      |
+| Claim Voters MBR           | Proposal Escrow | xGov Treasury |         Voters Box MBR         | `finalize` |                                     |
+| Close Out Proposal         | Proposal Escrow | xGov Treasury | Metadata Box MBR + App Account | `delete`   |                                     |
+
+## Escrow MBRs
+
+- Proposal Application Account
+
+- Metadata Box
+
+- xGov Committee Voters Boxes

docs/specs/proposal-submission.md

@@ -27,12 +27,22 @@ from the Proposal Escrow to the xGov Daemon to cover the operation fees.
 > The xGov Manager **MAY** update the percentage of the Open Proposal Fee transferred
 > to the xGov Daemon.
 
-## xGov Committee Assignment
+## Vote Distribution
 
-The xGov Daemon **SHALL** assign the xGov Committee of the Submitted Proposal.
+$$
+\newcommand \Comm {\mathsf{Comm}}
+\newcommand \Members {\mathrm{Members}}
+\newcommand \Votes {\mathrm{Votes}}
+$$
 
-The assigned xGov Committee **MUST** have the size (total members) and voting power
-(total votes) of the xGov Committee ID (see [xGov Committee section](./xgov-committee.md)).
+The xGov Daemon **SHALL** distribute the votes to the xGov Committee (\\( \Comm \\))
+assigned to the Proposal.
+
+The distributed votes **MUST** be equal to the xGov Committee Voting Power
+(\\( \Votes(\Comm) \\)) (see [xGov Committee section](./xgov-committee.md#xgov-committee-voting-power)).
+
+The number of voters who received votes **MUST** be equal to the xGov Committee
+Members (\\( \Members(\Comm) \\)) (see [xGov Committee section](./xgov-committee.md#xgov-committee-members)).
 
 The Proposal status **MUST** be set to Voting once the xGov Committee is completely
 assigned.

docs/specs/proposal-vote.md

@@ -24,11 +24,11 @@ Vote **SHALL NOT** be modified.
 
 A Submitted Proposal is Approved _if and only if_ all the following conditions hold:
 
-- A category-dependent _democratic quorum_ of all xGov Committee (one xGov, one vote)
-is reached. _“Null”_ votes **affect** this quorum.
+- A _democratic quorum_ of all xGov Committee (one xGov, one vote) is reached. _“Null”_
+votes **affect** this quorum.
 
-- A category-dependent _weighted quorum_ of all xGov Committee voting power is reached.
-_“Null”_ votes **affect** this quorum.
+- A _weighted quorum_ of all xGov Committee voting power is reached. _“Null”_ votes
+**affect** this quorum.
 
 - The _relative majority_ of _“Approve”_ over _“Reject”_ votes is reached. _“Null”_
 votes **do not affect** the relative majority.

docs/specs/proposal.md

@@ -46,25 +46,75 @@ The Proposals have two different _funding types_:
    xGov Committee vote, after milestone reviews from the xGov Council, and if the
    xGov Council does not apply a veto according to terms and conditions.
 
-## Funding Sizes
+## Requested Amount
 
-Proposals have different _funding sizes_ based on the requested funding amount.
+The Proposal’s _requested amount_ (\\( A \\)) **MUST** be bounded as follows:
 
-The _funding size_ defines the timing of the Proposal lifecycle and the voting quorums.
+|                                |              Small              |               Medium                |                Large                |
+|:-------------------------------|:-------------------------------:|:-----------------------------------:|:-----------------------------------:|
+| Requested Amount               | \\( A_\min ≤ A < A_{S,\max} \\) | \\( A_{S,\max} ≤ A < A_{M,\max} \\) | \\( A_{M,\max} ≤ A ≤ A_{L,\max} \\) |
+
+## Funding Sizes
 
-The Proposal’s requested amount (\\( A \\)) **MUST** be bounded as follows:
+Proposals have different _funding sizes_ based on the _requested amount_ of funds.
+
+The _funding size_ defines the timing of the Proposal lifecycle.
 
 |                                |              Small              |               Medium                |                Large                |
 |:-------------------------------|:-------------------------------:|:-----------------------------------:|:-----------------------------------:|
-| Requested Amount               | \\( A_\min ≤ A < A_{S,\max} \\) | \\( A_{S,\max} ≤ A < A_{M,\max} \\) | \\( A_{M,\max} ≤ A < A_{L,\max} \\) |
 | Discussion time                |           \\( D_S \\)           |             \\( D_M \\)             |             \\( D_L \\)             |
 | Voting time (after discussion) |           \\( V_S \\)           |             \\( V_M \\)             |             \\( V_L \\)             |
-| Democratic Quorum              |         \\( Q_{d,S} \\)         |           \\( Q_{d,M} \\)           |           \\( Q_{d,L} \\)           |
-| Weighted Quorum                |         \\( Q_{w,S} \\)         |           \\( Q_{w,M} \\)           |           \\( Q_{w,L} \\)           |
 
 {{#include ../_include/styles.md:note}}
 > Refer to the [Proposal implementation configuration](../implementation/configuration.md)
-> for the parameters’ value.
+> for the Proposal lifecycle timing values.
+
+## Quorum Thresholds
+
+$$
+\newcommand \Comm {\mathsf{Comm}}
+\newcommand \Members {\mathrm{Members}}
+\newcommand \Votes {\mathrm{Votes}}
+$$
+
+Proposals have two _quorum thresholds_ based on the _requested amount_ of funds.
+
+The _quorum thresholds_ define the minimum number of (regular and weighted) votes
+required to approve a Proposal:
+
+- \\( T(A) \\), Democratic Quorum Threshold (`1` xGov, `1` Vote);
+
+- \\( T_w(A) \\), Weighted Quorum Threshold (`1` xGov, `w` Votes).
+
+Given the xGov Committee assigned to the Proposal, with its members and voting power
+(see the [xGov Committee definition](./xgov-committee.md)), the quorum thresholds
+are defined as follows:
+
+- \\( T(A) = \Members(\Comm) \times Q(A) \\), with
+
+$$
+Q(A) = Q_\min + \frac{\Delta Q}{\Delta A} \times (A - A_\min)
+$$
+
+- \\( T_w(A) = \Votes(\Comm) \times Q_w(A) \\), with
+
+$$
+Q_w(A) = Q_{w,\min} + \frac{\Delta Q_w}{\Delta A} \times (A - A_\min)
+$$
+
+Where:
+
+- \\( Q_\min = Q(A_\min) \\)
+- \\( Q_\max = Q(A_{L,\max}) \\)
+- \\( Q_{w,\min} = Q_w(A_\min) \\)
+- \\( Q_{w,\max} = Q_w(A_{L,\max}) \\)
+- \\( \Delta Q = Q_\max - Q_\min \\)
+- \\( \Delta Q_w = Q_{w,\max} - Q_{w,\min} \\)
+- \\( \Delta A = A_{L,\max} - A_\min \\)
+
+{{#include ../_include/styles.md:note}}
+> Refer to the [Proposal implementation configuration](../implementation/configuration.md)
+> for the minimum and maximum quorum values.
 
 ## Metadata
 
@@ -100,30 +150,3 @@ A Proposal **SHALL** be in one of the following enumerated statuses:
 > Example: a Proposal can be `FUNDED` and `FINALIZED`.
 
 ![Proposal Finite-State Machine](../_images/proposal-state-machine.svg "Proposal Finite-State Machine")
-
-## Escrow
-
-The Proposal Escrow is an Address controlled by the Proposal Application.
-
-### Escrow Inflows
-
-- Partial Open Proposal Fees from xGov Treasury
-
-- Proposal Commitment Lock from the Proposer
-
-### Escrow Outflows
-
-- Operation Funds to xGov Daemon on Proposal submission
-
-- Proposal Commitment Lock to the Proposer if the Proposal is not blocked with a
-veto or to the xGov Treasury otherwise
-
-- Decommissioned MBRs to xGov Treasury
-
-### Escrow MBRs
-
-- Proposal Application Account
-
-- Metadata Box
-
-- xGov Committee Voters Boxes