Single GrantsRound Contract Spec

[apbendi]

This issue is a minimal spec for a smart contract implementing a single matching grant round.

• [ ] Has an owner with special internal privileges (see below)
• [ ] Has a startTime timestamp that must in the future at the time of deployment
• [ ] Has an endTime timestamp that must be after the startTime
• [ ] Has a donationToken address that is assumed to be an ERC20 implementation
• [ ] Has a registry address that refers to a GrantsRegistry instance
• [ ] Has a string metaPtr variable that is set at deployment
• [ ] Has a minContribution variable that is set at deployment, representing the minimum matching contribution that can be made to a grant during the round
• [ ] Has a hasPaidOut boolean variable that defaults to false, and toggles only when the owner calls the payout method (see below)
• [ ] At any point before endTime, (including before the startTime), the Round can accept matching pool donations in donationToken via a special method. Internally, the method should use transferFrom to take custody of the funds and emit an event.
• [ ] During the active period, the Round can accept matching donations for a specific Grant via a special method.
  • [ ] The method should take the grantId as a parameter, and verify that the Grant exists in the GrantRegistry
  • [ ] The method should ensure the amount is greater than or equal to the minContribution amount
  • [ ] The method should use transferFrom to send the funds the Grant's payee address
  • [ ] The method should emit an event
• [ ] After the active period, the Round should disallow matching pool donations and grant contributions
• [ ] After the active period, the owner should be able to transfer all matching pool funds to a payoutAddress via a special method call. Only the owner should be able to call this method, and only after the endTime has passed.

Open Questions:

• Should matching donations be allowed while the round is active, or only before?
• Should a minimum round duration be enforced in any way at deployment?

Notes:

• For simplicity and further consideration, I've left any concept of whitelisting or curating grants from the round out of this spec. The only requirement is that the grant exist in the Registry.

[thelostone-mc]

Should matching donations be allowed while the round is active, or only before?

I'd say it should ! The reason being this only affects how the distribution is calculated and it allows projects to get in more funds

Should a minimum round duration be enforced in any way at deployment?

Feels more like a nice to have than a necessity. Any reason you think this might be beneficial?

===============

Open Questions

• Would we allow the start-date / end-date to be extended ?
• Can we set min contribution to be set for each GrantRound. Could be defaulted/set to. This discourages spam donations.
• Is there a variable for grantRoundStatus? (something like 0 -> raising. 1 -> active, 2 -> done, 3 -> payout complete as opposed to relying on start and end date)
• Can grants be added/removed once the round starts. (Also having the grantRoundStatus -> might making the condition checking easier as opposed to relying on the dates)
• Is there a variable for metadataPtr?
• Is there a variable for totalPot?
• Is there a variable for grants (or is this Offchain )

More advanced but worth thinking

• Is there a variable excludedAddressPtr ? (This is where certain addresses contributions must to be ignored while calculating the distribution) This could live
  • on the dapp (centralized)
  • off chain with a ptr excludedAddressPtr
  • along with metadataPtr If it's on the contract -> it can be updated only the owner. This way while the contract doesn't deal with sybil detection. It provides a means to store that data and use that while deriving the distribution

I was playing around with subgraph and this was what I was assuming the contract would have when I wrote that up https://github.com/dcgtc/dgrants/issues/10

[apbendi]

I'd say it should ! The reason being this only affects how the distribution is calculated and it allows projects to get in more funds

I've updated the spec to reflect this, unless anyone else has an objection

Feels more like a nice to have than a necessity. Any reason you think this might be beneficial?

Just as a sanity check at deployment, basically. Agree it's probably not needed.

Would we allow the start-date / end-date to be extended ?

This one feels like a nice to have to me, at best, an anti-feature at worst (could it be exploited or used to manipulate the results or grief grantees by making matching funds unavailable, etc..)

Is there a variable for grantRoundStatus? (something like 0 -> raising. 1 -> active, 2 -> done, 3 -> payout complete as opposed to relying on start and end date)

This can be derived from the start & end timestamps along with the current timestamp. Are you proposing a convenience method that would return the state or something like that?

Can grants be added/removed once the round starts.

Since there was not consensus on whitelisting grants explicitly on chain, I left this out of the spec completely for now. The only requirement enforced is that the grantId is a valid one. The assumption is that non-qualifying grants would simply be left out of the matching calculation.

Is there a variable for metadataPtr?

I've updated the spec to include this.

Is there a variable for totalPot?

This would just be token.balanceOf(roundContractAddress)

Is there a variable excludedAddressPtr ?

I'm not sure what you mean here. Is this in relation to contributors, and whether their contribution would be ignored by matching? If so, I think this is mixing of concerns and not something the Round would worry about.

cc @corydickson see above where I've added a couple of points to the spec

[thelostone-mc]

This can be derived from the start & end timestamps along with the current timestamp. Are you proposing a convenience method that would return the state or something like that?

A convience method help but doesn't need to be on the contracts. We could build this out in subgraphs maybe ! I was asking if we see value GrantRound having more than 2 states Eg : is there value in creating a distinction between when a round ends and when payouts are done or is that an overkill ? ( I feel it is but just wanted to ask if anyone else sees a value here )

I'm not sure what you mean here. Is this in relation to contributors, and whether their contribution would be ignored by matching? If so, I think this is mixing of concerns and not something the Round would worry about.

Ah so we leave that to decision to whoever is calculating the distribution to ignore contributions AKA the list of bad addresses are not stored off/on chain ?

[corydickson]

@thelostone-mc I think it makes sense to have some public boolean to represent when payout has been completed so there is a way to verify that the owner of the contract has released the funds and one does not necessarily need to consume an event to do so. Furthermore if we decide to add extensions to the start and end time, this can be an additional check prior to updating these values, i.e. ensure the grant has not been payed out previously.

Thoughts @apbendi ?

[apbendi]

I can see a payout bool being useful, so I've added that to the spec @corydickson. Good idea @thelostone-mc.

Ah so we leave that to decision to whoever is calculating the distribution to ignore contributions AKA the list of bad addresses are not stored off/on chain ?

The details are debatable, but right now I feel it doesn't belong in the Round contract. Could be convinced otherwise down the road, but as I see it now, it makes sense for it to be done by a separate sybil module, or in the matching calculation.

[frankchen07]

Should matching donations be allowed while the round is active, or only before?

To be clear this means there's start time bound, or am I understanding that incorrectly?

start end date extensions

agree this is a nice to have, would recommend excluding from the MVP.

grants added or removed once the round starts

I can see this possibly being an attack vector that eventually skews the results if there's a matching contract involved (removal of grants will free up the pot, changes the CLR matches). Not a huge deal right now.

convenience method to return the state

also unsure what you're asking here, perhaps something to discuss, but perhaps out of scope for the MVP - start and end dates should be enough proxy information. edit: I saw Aditya's ticket about the subgraph, perhaps it's just a way to index and quickly query the state of GrantRounds? Maybe the answer is build a dumb version first then we optimize.

ignoring fraudulent contributions

I remember Philip and I talking about managing payout through a payout proposal (after contributions are made). It's analogous to the centralized version of "using Blockscience and then Aditya & Frank re-running results), it's just done programmatically. Unsure of what form that will take though.

[phutchins]

I wrote up my thoughts on what the end of a GrantRound should look like which might help with some of these questions. My thoughts are as follows.

• When the end date for a grant round has been reached…
• There may be a period (24hr?) where the round owner could extend the round (if the round were set to enable that possibility, participants would be able to tell if a round had the ability to be extended, and in what circumstances)
• If the admin extends a round, it continues to run as normal for whatever the extension period is set for then it ends (maybe can extend again, maybe not)
• The round is then moved to the state where it is awaiting matching proposal to be added (maybe to the round contract or somewhere that the round contract can interact with)
• A DAO or other party would generate and push a final list of any grants that were found during the round to be fraudulent or “bad” which would exclude those grants from any matching
• Some service/dao/party external from that contract would run some open source software against the blockchain and generate payout detail data that could be pushed to the blockchain or used to update the blockchain in some way to enable/unlock payouts for eligible grants
• Anyone that so desired could run the same software to generate the payout data and verify that it matches what was being used to do the actual payout
• Once uploaded and marked as ready for review, the payout data could not be changed unless the process was started over due to a DAO failing the set of payout data
• If payout data was failed by the DAO, the process of generating payout data and pushing to the contract should be started over again
• Once a set of payout data is approved by a DAO (or controlling entity or group), the funds are either
• Automatically released to the designated payout addresses
• Unlocked so that the payout address can claim and pull their funds
• Once all funds are delivered or collected, the round is closed but left such that it can be audited any time in the future

Regarding some of the questions we are discussing... Per my thoughts above, it seems like the GrantRound contract should have the necessary pieces to:

1. link a proposed payout data set (i.e. pointer to payout data similar to metadata pointer) - This would include details on any grants removed from matching and the reason for each (we would eventually need a way for anyone to dispute a specific exclusion or choice related to this data but out of scope for now)
2. hash to verify payout data integrity
3. ability to accept approval or denial from an address (eventually will be a multisig controlled by DAO) for payouts
4. some way to trigger payouts utilizing the funds from the GrantRound contract but only if the data is approved and verified (could use some discussion on this around how this works and where the code for this goes. I have some ideas.)

grants being added or removed once the round starts For this one I think we need to break it down into the reasons that anyone would want to add/remove a grant from a round once it has started and the affects of that action. A) Adding Grants: a.1. A new grant has been created that fits into the round based on the rounds themes a.2 A new theme has been added to the round B) Removing Grants: b.1. A grant has been determined to be fraudulent b.2. A grant has been determined not to fit the requirements of the round or entity b.3. A theme has been removed from the round

a.1. - I think this could be a setting on the GrantRound to determine if the owner wants this to be possible. a.2. - This doesn't feel like a good idea to me. After money has been put on the table assuming a set of conditions were true, those conditions would change if we were to allow this. (enforcing this would be hard until we got more programatic with grant selection and lists) b.1. - This totally makes sense and we would want to stop them from receiving any donation as well as matching funds b.2. - This should be caught before being added to a round or being approved through curation. If it did not however, it could be excluded from matching. b.3. - This is really something that shouldn't happen once the round has started.

round state I do think that a round should have a state. I initially had it in the contract but had it being manually set which shouldn't be necessary. I do think that there should be a state (or states) after round end for waiting for payout data (or payout data contract), waiting for payout data approval, payout approved, payout complete. Something along those lines.

[frankchen07]

great writeup, thanks Ben - some thoughts:

Some service/dao/party external from that contract would run some open source software against the blockchain and generate payout detail data that could be pushed to the blockchain or used to update the blockchain in some way to enable/unlock payouts for eligible grants

this feels very similar to what we do for centralized grants. I'm wondering if this is just an artifact that we hope to deprecate, and instead, once a round starts, we somehow (magically) compute the QF matching and prevent a high percentage of sybil and collusion attacks so payout at the end can be more automated. This fits within a more decentralized way of doing things. It's more ideal, but I'm also discounting a lot of the technical challenges involved there. Perhaps it's a stretch goal.

adding grants

agree that once the round kicks off, it represents an agreed-upon state for that round. Adding in Grants after the fact eventually leads to matching contract differences (possibly less money to go around) and the possibility of fraudulent grants making their way in.

the opposite way, removing grants from a round, benefit everyone except the grant being removed. The only reason that I see to prevent this from happening is to keep in-step with the "non-mutability" of a round once it's been started (if folks can't add, then they can't remove either).

round state

do we think we're over-engineering the possible states that might occur after a round ends? While it makes sense to me, it could be fruitful to leave it open and see how usage organically falls (instead of drawing out a path in the grass, we can just analyze the trample pattern after the fact).

[apbendi]

closed with #17