Expenditures Extension Brief

[arrenv]

Summary

Expenditures offers a more advanced payment system. It provides functionality to make payments to multiple recipients, in multiple different tokens, of varying amounts, and with differing claim delays all in one action. E.g. five recipients, each receiving CLNY + xDai in differing amounts with varying claim delays.

This feature will require the development of a new extension to interact with the existing base expenditures contract and enable the required additional functionality. This is defined in the breakdown below.

Design for reference: Figma Link

Overview

• Multiple states of expenditure
• Staking to create an Expenditure
• Single motion when funding multiple tokens
• Allow partial funding when underfunded
• Single motion when updating multiple values
• Releasing funds
• Can change the 'Owner'
• Account for over-funding
• Expenditure metadata updates
• Handle differing claim delays
• Deleting and Canceling an expenditure

Breakdown

Multiple states of expenditure

There is a need to have multiple states/statuses of an expenditure. These include:

• Draft: The expenditure is staked, however, any details on the expenditure can be changed by the owner without requiring Administration permissions or a motion.
• Locked: The values of the expenditure are locked. Any updates to the details will require Arbitration permission or a motion.
• Funded: The expenditure is fully funded and can be released by the owner at any time.
• Released: The funds for expenditure can be released and starts the claim delay.
• Claimed: All recipients have claimed their payments and there are no funds remaining in the expenditure funding pot.
• Cancelled: The expenditure has been cancelled.

Staking to create an Expenditure (without a Motion)

In order to minimise the number of required motions to create an expenditure, it is required that a staking mechanism be put in place. While this could still be up for discussion, at this stage the calculation for determining the amount to be staked will be the same that is used to stake on a motion (for lack of a better solution at the moment).

Single motion when funding multiple tokens

Funding an expenditure will require a motion (if Motions & Disputes extension is enabled) and when multiple tokens are required to be funded as a part of an expenditure, it is required that only one motion is created.

Handle state and partial funding when underfunded

When changes are made to an already funded expenditure to increase the amount due, it is required to update the status of the expenditure back to unfunded. It will also require the ability to calculate how much is required to fund and allow funding for that amount.

Single motion when updating multiple values

To avoid the creation of multiple motions when making updates to a locked expenditure, it is necessary to allow for the updating of any number of values in a single motion.

Releasing funds

Only the 'Owner' of an expenditure, a Motion, or the Arbitration permission will be able to trigger the 'Release Funds' function of an expenditure, this will start the claim delay for each of the recipients to then be able to claim their payments.

## Can change the 'Owner'
As the 'Owner' is the only one who can 'Release Funds', there needs to be the capability to change the 'Owner'. This should be allowable with the right permissions or via a motion. Given the owner stakes the expenditure originally, it will be necessary to keep track of the address that staked so that their stake can be returned. Not necessary with motions being able to release funds.

Account for over-funding

We need to be able to account for over-funding in the expenditure funding pot, for example a change is made to reduce an expenditure after initial funding. Handling over-funding should happen during the claim period, where the first person to claim will also calculate the over-funding and return it to the original domain funding pot of the expenditure.

Expenditure metadata updates

Similar to how ColonyMetadata works, it will also be required to be able to change details stored on IPFS, such as title and description, on an expenditure with a motion.

Handle differing claim delays

It will be required to be able to handle varying claim delays for multiple recipients or even the same recipient as a separate payment. From my understanding, this is already possible in expenditures, however I am making note of it here.

Deleting and Canceling an expenditure

Delete: It should be possible to delete an expenditure that is still in Draft and not locked. This should return the stake with no penalty to the stake or their reputation.

Cancel: It should be possible to cancel an expenditure that is in a locked, funded or released state. This will require Arbitration permission or a motion to do. The person cancelling will be able to punish the original address that staked or decide not to punish them. The punishment calculation will be the owners full stake and the equivalent in reputation.

[kronosapiens]

Regarding the "claimed" state -- I would suggest not implementing this in the contracts but rather making it a UI concept only. We don't currently track "total claimed" which we would likely need to to make this happen. The frontend can check balances & look at events to figure out what claims have been made and show a "claimed" state. Would that be acceptable?

[arrenv]

@kronosapiens Thanks for looking into it, I remember we discussed this during the Sync. It sounds acceptable to me.

[kronosapiens]

Ditto regarding the "underfunded" state -- the frontend will have to look at events to figure out which tokens are involved in an expenditure & work out how funding if any is necessary. Once you know which tokens you can figure out under/over funding based on on-chain data, but you'll need to use events to figure out which tokens are involved.

[arrenv]

@kronosapiens Thanks, sounds fine.

[kronosapiens]

Regarding the "single motion to update multiple values" -- do we have specific examples in mind? It is already possible to set bulk values of the same type, such as setting multiple recipients, multiple token payouts, multiple claim delays, etc. Do we need something more advanced than this?

[arrenv]

Regarding the "single motion to update multiple values" -- do we have specific examples in mind? It is already possible to set bulk values of the same type, such as setting multiple recipients, multiple token payouts, multiple claim delays, etc. Do we need something more advanced than this?

This may just be a case of how the original UI was designed, where, every change in the locked state created a separate motion. If it is already possible to change multiple values in one request, then this likely does not need any extra work.

Your example pretty much covers it, i.e. be able to change multiple recipients, multiple token payouts, multiple claim delays all in the same request i.e. a single motion.

[kronosapiens]

Ok, but to be clear, changing multiple recipients and changing multiple token payouts would require two motions -- one for the recipients, one for the payouts.

[arrenv]

In that case, then yes. The more advanced functionality I suppose is being able to change all options in a single motion. It would make for a challenging UI to separate these into separate motions.

By your description, it would also mean that if you wanted to update one recipients token and claim delay, it would require two separate motions.

[kronosapiens]

Regarding staking, have we decided what the criteria should be? I'm guessing some % of the reputation in the domain, is that right?

[kronosapiens]

For "all the options" does this also include all payouts for several tokens? I'm just trying to think of the interface here -- changing different payouts in different tokens in different slots, in a single transaction?

[arrenv]

Regarding staking, have we decided what the criteria should be? I'm guessing some % of the reputation in the domain, is that right?

Yes, it was agreed that until a better approach can be worked out. It should use the same calculation as motions.

For "all the options" does this also include all payouts for several tokens? I'm just trying to think of the interface here -- changing different payouts in different tokens in different slots, in a single transaction?

From an interface perspective, the UI is either in locked mode or edit mode. The edit mode allows for all fields to be edited, then to finalise the edits, they update them all in one go. This design shows this from an interface perspective - https://www.figma.com/file/dCtvv76S8mk5HNApjwmBto/Expenditures?node-id=2416%3A314175

[area]

When stakes are used to create an expenditure, and ownership is transferred, what happens to the stake? Relatedly, if the appropriate person is punished, what happens to the tokens?

[arrenv]

I was following along here and put a response there as well - #1045

Without fully understanding the logistics yet. My thoughts are that the stakes should be sent to the Colony, this will make the functionality more reusable. Also, it would reduce the risk of lost funds when extensions are deprecated.

In terms of punishment, the Colony keeping the funds makes sense to me.

[area]

And what about when ownership is transferred? Is the original creator still 'on the hook' with their tokens at risk, or does the new owner somehow have to supply the stake so the old owner can be made whole? And presumably, this is different if the owner is being changed willingly ("I have no time to manage this any more") vs against their will?

[arrenv]

We removed the need for Ownership to be transferred, as the funds can be released by a motion. So, essentially after they have locked the expenditure, control is out of their hands.

[area]

There is no scenario where ownership would need to be transferred before the expenditure was locked?

EDIT: To be honest, ownership can be transferred, regardless, because it was decided that the user, not the extension, should be the owner. So there's nothing that can be done other than have the original user on the hook.

[arrenv]

I can't think of a necessary scenario in my opinion, they could just create a new Expenditure.

Ok, from a UI perspective there won't be the ability to change owners, but from a contract perspective, it sounds reasonable to me that the original user be on the hook.