search

Meeds-io / MIPs

The Meeds Improvement Proposal repository
0 stars 0 forks source link

User Engagement Minting #58

Closed srenault-meeds closed 7 months ago

srenault-meeds commented 1 year ago

Rationale

The Meeds DAO's Whitepaper explains it well: we aim to reward user engagement of each Hub running in the WoM. Cf. Whitepaper - https://mirror.xyz/meedsdao.eth/EDh9QfsuuIDNS0yKcQDtGdXc25vfkpnnKpc3RYUTJgc

1. Functional Requirements

To accomplish this, 4 major use cases will be adressed:

  1. Collect data regarding user engagement

    • Any action that have been achieved during the period will be collected, no matter it is an automatic action or a manual action
    • Collect data from each hub for user engagement: achievements, total of users, engaged users (user who has reached a minimum of points - threshold to adjust if needed), Meeds Distribution previous period

  2. Display UEM informations of each hub

    • from the hub explorer, each hub card will list users, rewards payment average and periodicity, and engagement score
    • Each hub card will suggest an option to access detail of engagement informations. Thus, anyone can list for a Hub detailed informations (users, recipients, participants, WoM joined date, rewards periodicity, last reward sent, rewards average since the joined date, its index VS other hub of the WoM (per city)
    • By clicking to engagement score, an explainer opens so anyone can understand the formula for transparency sake
    • of course, when clicking to the hub card directly, I can access its login page or its public page if made visible

  3. Review user engagement and reward for UEM

    • Provide a way for WoM Manager to review current and past user engagement data for each hub and globally of course
    • Suggest to generate random data based on a budget to study upcoming rewards before sending
    • Provide a way to send rewards for a period (rewards are computed on a weekly basis (updatable if needed)
    • Once rewards are sent, hub managers can claim it from their reward page

  4. Inform owners and hosts about the reward to claim

    • Send notifications to owners and tenants (email) about the reward to claim: this email sends the user to go to the dApp a. red dot additional info is displayed in the dApp b. from the dApp "Owners page" or "Tenants page", access the detail of the index by clicking to it -> sends the user to the detail page (same as the one proposed when accessing it from the hub explorer) c. from the reward page in the hub, a "claim" button is suggested to get the rewards from the UEM (depending on the share between owners and tenants when the case is identified)
    • UEM index and rewards should be inalterable
    • Rewards can only claimed by the Hub's admin wallet
    • Rewards accumulate and can be claimed at any time
    • UEM weekly budget can be changed by an onchain param.

2. Terminology

3. Technical Requirements

Expected Volume & Performance

Security

The security requirements of the UEM technical design are:

Extensibility

The wallet addon has to allow through extensions adding informations about UEM from the deeds-tenant addon. In fact, both administration UIs (Wallet administration and rewards Administration) has to allow such an extension to display:

Configurability

No configuration requirement.

Upgradability

The UEM & WoM contracts has to be upgradable so that the association can vote to change the UEM formula computing.

Existing Features

Existing Features of Meeds Packages shouldn't being altered by the introduction of deeds-tenant addon.

Feature Flags

No feature flag is needed.

4. Software Architecture

Data and persistence

The Data Model that will be used un UEM Blockchain Contract will define the following entities:

This data structure will be used to store informations sent by Hubs about their periodic rewards. Those information will be stored as it was sent without alteration nor computing.

This data structure will be copied from the WoM Contract (see MIP #106 ). It's a snapshot of the associated Deed to the Hub at the time of report sending. The Deed information, as described in the whitepaper, will be used to compute the Hub score.

This data structure will be computed once the report is received and will be unaltered but the fraud flag. This flag can be set to true by another contract that can adopt a dedicated business logic to mark a contract as fraud or not. This will allow to decentralize the governance of Hub reports denunciations and slashing.

This data structure aggregates information about the reports included in the current Reward period including the fixedGlobalIndex which is the sum of all Hubs scores and which will be used in Claimable amount computing.

This data structure is the result of all UEM engine computing which will allow Deed Owner/Tenant to receive UEM rewards through a claim method in the blockchain.

[!IMPORTANT] Those information will be duplicated as is in the dapp to allow accessing it through REST API calls without having to request the blockchain each time it will be needed.

[!NOTE] Each Hub has to store the information about Hub Reward Report either it was sent or not, which will be stored using SettingService with Key and Value which corresponds to Hub Report Blockchain Id and Hub Reward Internal Period Id.

Services & processing

[!IMPORTANT] Please make sure to read the technical design detailed in the MIP #106 (Connect Hub To The WoM) before going further here.

Considering that we aim to have thousands of Hubs hosted in the WoM and rewarded by the UEM, the big concern is to scale the UEM so that it doesn't require any action to weekly send rewards. In addition, we aim to decentralize the Hub reports data sending so that all actions are transparent and secure on the blockchain. To do this, the Choice of using Polygon instead of Ethereum was obvious to reduce Gas Fees in favor of the decentralization of the UEM.

Hub Report Sending

UEM-Software-Architecture-SequenceDiagramV2-Send Hub Reports drawio

The above diagram describes the sequence diagram of Hub Report sending Transaction. It demonstrates as well how the different Blockchain Contract Data structures are altered by this kind of transaction.

When transaction sending fails (or the transaction local estimation/simulation fails), the error is stored in the Hub so that it gives the detail to the Hub Manager/Owner to fix the error. (by sending Matic to the Admin Wallet per exemple when no funds are remaining in the admin wallet to send transactions to the blockchain)

Access

The Hubs Reports and UEM rewards should be accessible from blockchain and publically available from https://wom.meeds.io.

The Hub listing, reports and rewards should be accessible through URLs:

On the UEM contract in the Blockchain, those list of operations will be available to retrieve information:

[!CAUTION] The current UEM period rewards aren't claimable until the period is finished

5. Annexes

Reasoning that explain the technical choices

This is the third version (V3) of UEM technical design

The first technical design (v1) proposed a full centralization of UEM rewards and which includes that:

The disadvantage of this first solution was that Hub reports are aggregated in a centralized server inside a database which is alterable and which, due to a bug, can compute a bad score for a giving report. In addition, centralizing such an information will reduce the credibility of the project and will give the governance of UEM rewarding administration, in an opaque way, to a unique organization. (anti DAO)

The second technical design (v2) proposed to make the Hub reports sending decentralized and made from the Hub itself to a Blockchain contract in order to allow the traceability of reports sent by each Hub. To allow sending report to this contract, we needed to have a contract which describes the list of Hub addresses who are allowed to send reports to the UEM which will be considered valid by default. This new contract is considered as the WoM and already detailed in MIP #106 (Created after this one for the V2 of Technical Design).

The disadvantage of this second solution, which was the same as the first version, is that rewards are sent and not claimed, thus the Hubs has to wait for Rewards sending operation, in addition to the fact that the rewards sending will require multiple transactions to send by a Wallet managed by the DAO (anti decentralization as well).

For those both concerns, the V3 was designed in order to decentralize the Reports sending and rewards claiming. Thus the DAO will just have to send Meeds to the UEM contract and configure the periodic Meeds to share between Hubs.

Some other concerns aren't addressed yet by this third version, which is the Fraud Detection mechanism and how it should be decentralized and follows a voting system instead of a centralization of Fraud decision. Should the Fraud detection follow a voting system or should it be automatically made through some business rules that could be determined after UEM rewarding experimentation ? Is the UEM formula fair enough to measure the Hubs engagement and to recognize Hubs engagements ? How the UEM total amount has to be computed and retrieved from TokenFactory contract from Etheruem Blockchain to receive the 30% of Users Mintium share of automatic and periodic minted Tokens ?

Contracts Deployment

The WoM and UEM contracts has been made upgradable to allow the DAO voting on formula changes to make the Mintium fair enough for all participating Hubs. Thus the ERC1967Proxy will be used. You can use the following steps in order to deploy the contracts (using Remix IDE):

  1. Change All contracts to use solidity 0.8.20 (limitation in Java Web3J Maven Plugin, thus added using 0.8.9 in source code only)
  2. Deploy WoM.sol
  3. Deploy WoMProxy.sol using the following parameters:
    • logic_ = address of the first deployed contract (WoM.sol)
    • data_ = 0x8129fc1c (Abi encoding of empty initialize method, use https://abi.hashex.org/ by example)
  4. Deploy UserEngagementMinting.sol
  5. Deploy UserEngagementMintingProxy.sol using the following parameters:
    • logic_ = address of the deployed contract (UserEngagementMinting.sol)
    • data_ = 0x + ABI encoding of image
  6. Once UEMProxy deployed, invoke Method setPeriodicRewardAmount to set the periodic amount of Meeds that will be sent by the UEM to participating Hubs (Load UserEngagementMinting.sol using address of newly deployed proxy to access UEM functions through the proxy address)
  7. Send Meeds Tokens to UEMProxy which will be claimable by Deed Owners and Managers
  8. Add WoM Manager Address on WoMProxy address through addManager which will make the automatic bridging of Deeds from Ethereum Blockchain to Polygon (see MIP #106 for more details)
  9. Send Matic to WoM Manager Address to allow bridging automatically the deed between blockchains.
boubaker commented 1 year ago

@bourasom could you please take a look at Deployment Architecture so that I can continue on designing the Software Architecture. Thanks in advance for your collaboration.

plamarque commented 1 year ago
  1. Update gamification events removed (out of scope)

e. from the reward page in the hub, reward admin can review achievement from the rewards list with way to reject f. from the reward page in the hub, reward admin can list rewards per program with ability to define a program budget and the rules (program owner can manage its budget and send rewards OR program owner can only review achievement) removed (out of scope)

d. removed mention of merke tree (non functional)

  • If not claimed, then the reward can be claimed after and once a period (to identify) is passed with unclaimed rewards, then it goes back to the meeds dao. Indeed, claim has not been done so it is expired dropped the requirement. Replace by : "Rewards accumulate and can be claimed at any time"

added new requirements

  • any community member should be able to verify the full score and rewards for any UEM period
  • UEM index and rewards should be inalterable

added requirement

UEM weekly budget can be changed by an onchain param.

srenault-meeds commented 8 months ago

Reviewed the scope accordingly to internal discussions

srenault-meeds commented 8 months ago

to check please @margondicco

boubaker commented 8 months ago

user who has reached a minimum of points - threshold to adjust if needed

We don't have a way to verify this information on blockchain, thus no need to add this requirement

Provide a way for WoM Manager to review current and past user engagement data for each hub and globally of course

Not only for WoM Manager. IMO, we should provide this way for everyone who should anonymously access those information so that all other Hubs can audit and identify cheaters. We should even think of a way to let other Hubs declare a Hub Rewarding Report as fraudulent. In fact, the UEM engine has to be as much autonomous as possible and as much as decentralized as possible, so that it's governed by hubs participating to the UEM and not centralized by any party. This to make sure that we continue to be transparent about the sent Rewards and guarantee fairness as much as possible.

Suggest to generate random data based on a budget to study upcoming rewards before sending

This need should not be expressed here IMO since it's an internal method for testing the Formula. I would rather say that we should just describe the expected outcome as a product feature.

Provide a way to send rewards

The rewards will not be sent, it will be claimable. In fact, the UEM Rewards have to be, like for LP Tokens Staking, autonomous and without needing a centralized ~DAO member who has to be the validator~.

Rewards can only claimed by the Hub's admin wallet

In fact, the Deed Owner and Tenant can claim their shares and the Hub's wallet isn't the target of rewards. The Deed Manager can claim its rewards knowing that we can suggest to send those rewards to the Hub Wallet in order to redistribute those earnigs with the Hub community if needed... to be discussed more if needed (I think this will need further ideation to know how to design the flow)

srenault-meeds commented 8 months ago

Thanks.

We don't have a way to verify this information on blockchain, thus no need to add this requirement

Indeed, it is only a definition of what an engaged user is. I will update this.

Not only for WoM Manager.

Indeed, this is why I propose a summary of such informations for anyone who wants to know more about the score's details, etc. This is described above Check this >

Each hub card will suggest an option to access detail of engagement informations.

Regarding this:

The rewards will not be sent, it will be claimable.

Ok, claimable I know. But for me, it had to be "approved". As I understand, you suggest that no for more decentralization. Thus, I have a question. How does the DAO check if cheating have been done during the period? Do we have a way to "give" a malus to cheater for next rewards? cc @plamarque

boubaker commented 8 months ago

How does the DAO check if cheating have been done during the period? Do we have a way to "give" a malus to cheater for next rewards?

Very good question! But ~DAO check~, rather to replace with WoM Hub Owners (participants on the WoM only). We can use the voting rights of the Deed so that during the current UEM period, any WoM Hub can submit a fraud report on Blockchain so that autonomously the WoM members decides if the submitted reports of others are fraudulent.

margondicco commented 7 months ago

Go fonc of course

boubaker commented 7 months ago

Ready for technical specification review by DAO members (eXo : @rdenarie , DAO secretary @plamarque )

rdenarie commented 7 months ago

go tech

boubaker commented 7 months ago

ACC & PRs ready to review ( eXo : @rdenarie )

rdenarie commented 7 months ago

Hello, You can proceed to the merge.

boubaker commented 7 months ago

Hello, You can proceed to the merge.

Thanks, merged to develop