Payout

[0xmad]

As we started to implement MACI platform specific contracts inside the maci platform repo, we can go a bit beyond core MACI and start to extend MACI core contracts to fit our platform needs. One of these is payout contracts.

The easiest and simplest way to implement payout contracts is to extend the Tally contract and add the functionality required for payout. This way the tally verification and distribution logic is all in one contract making it cheaper to use vs having a separate contract which requires to make external calls to Tally.sol (example: https://github.com/ctrlc03/minimalQF/blob/main/contracts/MinimalQFTally.sol).

What do we need in terms of payout strategies? I believe these can be quite a few different ones and we can use the one needed for the round in the round configuration.

Architecture

Components

1. Voice Credit Proxy

Responsibilities

1. Deposits: Manages incoming deposits of voice credits from users (already implemented in core protocol).
2. Claims: Processes claims made by users.
3. Payout Strategy: Implements a strategy for distributing payouts based on tally results and user deposits.

Key Functions

1. claim(uint256 index): Allow to claim funds for the vote option.
2. payout(uint256[] index): Executes the payout strategy for a specified vote options.
3. witdrawExtra(address[] receivers, uint256[] amounts): Allow coordinator to withdraw extra to specified addresses.
4. withdrawAfterCooldown(address[] receiver, uint256[] index): Allow coordinator to withdraw unclaimed funds after specified cooldown

Storage
Mappings to keep track of user balances and claims

uint256 public totalExtraAmount;
uint256 public totalAmount;
uint256 public immutabale maxContributionAmount;
uint32 public cooldown;
mapping(address => uint256) public balances;
mapping(uint256 => uint256) public claims;

2. Tally

Responsibilities

1. Claims: Processes claims made by users for voice credits.
2. Payout Strategy: Implements a strategy for distributing payouts based on tally results and user deposits.

Key Functions

1. claim(...verifyTallyResultParams): Allow to claim funds for the vote option.
2. payout(...verifyTallyResultParams[]): Executes the payout strategy for a specified vote options.

// verifyTallyResultParams
uint256 voteOptionIndex,
uint256 tallyResult,
uint256[][] calldata tallyResultProof,
uint256 tallyResultSalt,
uint8 voteOptionTreeDepth,
uint256 spentVoiceCreditsHash,
uint256 perVOSpentVoiceCreditsHash

Interaction with Voice Credit Proxy

The Tally Contract will call the paouy and claim functions of the Voice Credit Proxy to handle specified payout strategy.

Devcon configuration:

• variant of QF/Normal with cap on max contribution
• calculate funds to be distributed with chosen formula
• compare result of formula with max allocation
• anything over the max allocation gets stored in a separate variable (extra money)
• extra money can be withdrawn
• money can be used to topup contributions with small donations, maybe we can have a lower limit too and these with lower limit can be topped up from this extra money
• need to wait till all are distributed otherwise it’s gonna cause front-running between small contribution projects to take this extra money
• either all low contributions get topped up or no one gets it (admin withdraws it) and splits it evenly

Safety measures:

• Need to test these contracts extremely well
• Need a safety switch: if money is not collected in 3 months take what is there, add pause for claims
• Need an audit before Devcon