EVM Connector

[plamarque]

Rationale

We need a connector capable of checking activity done by users on the EVM blockchains. this could be used to implement a variety of incentive programs for web3 protocols (e.g. staking, liquidity mining).

1. Functional Requirements

The EVM Connector should be capable of:

• working across any EVM blockchain (e.g Ethereum, Polygon PoS)
• working automatically with the EVM account of the Meeds user Wallet
• checking that a user account holds a specific token
• checking that a user account sends or receives a specific token
• checking that a user account has a minimum balance of a specific token
• checking that a user account holds a specific token for a minimal duration
• capturing blockchain events raised during calls of specific smart contract

Top User Stories

Tokens Holdings

Tokens
As a program owner, I can add an automated action to reward a fixed amount of points when the user account holds any balance of an ERC20 Token I specify by entering the smart contract address.

NFTs
As a program owner, I can add an automated action to reward a fixed amount of points when the user account holds any NFT (ERC721 or ERC1155) I specify by entering the smart contract address.

Amount
As a program owner, I can add an automated action to reward a fixed amount of points when the user account holds a specific minimum balance of a specific token.

Example: I configure a weekly action that will reward 10 points when the user holds a minimum of 100 xMeeds for at least 1 week.

Duration
As a program owner, I can add an automated action to reward a fixed amount of points when the user account holds any token balance I specify by entering the smart contract address for a duration I specify.

Example: I configure a weekly action that will reward 700 points when the user holds any number of xMeeds for at least 1 week.

Token Transfers
As a program owner, I can add an automated action to reward when a user sends or receives any transferable token

Dynamic Points Allocation
As a program owner, I can add an automated action to reward a dynamic amount of points based on the balance of a specific ERC-20 token.

Example: I configure a weekly action that will reward 1 point per xMeed for holding more than 1000 xMeed for more than 7 days

Smart Contract Calls

• As a program owner, I can add an automated action to reward points when a transaction done by the user emits a specific EVM event on a specific smart contract address
• As a program owner, I can define *values to match on EVM events

Example: I configure an action that will reward points when a user redeems a Common Deed (event Redeem(,, Common,*) is triggered on XMeed contract)

Uniswap V3

• As a program owner, I can add automated action to reward points for holding Uniswap-V3 positions
• As a program owner, I can specify a minimum of liquidity for each token of the pair
• As a program owner, I can specify a price range for the token to be

Example: I configure an action that will reward 100 pts for holding positions within the price range 0.99-1.01 on the USDT/MEED pool on Uniswap

Administrator

Enable/Disable Connector

• As an administrator, I can activate or deactivate the EVM Blockchain connector

Enable/Disable User Accounts

• As an administrator, I can "enable users to link their EVM accounts", otherwise use the address configured on the user's Wallet settings

Blockchains to Watch

• As an administrator, I can add blockchains to watch by indicating an endpoint URL from a provider such as Alchemy or Infura

Example: I can add Holesky Blockchain by entering the endpoint URL found on my Alchemy app dashboard

Events
As an administrator, I can enable/disable various types of gamification events on the EVM Connector :

1. Hold a Token: to check holdings of an ERC20 token
2. Hold an NFT: to check holdings of an ERC-1155 or ERC-721 token
3. EVM Event: to listen to events emitted during transactions
4. Hold Uniswap V3 Positions : to check Uniswap V3 LP positions

Impacts

Gamification

Notifications

No new notifications.

Analytics

• Track actions triggered
• Track EVMs used
• Track token watched
• Track smart contract method

Unified Search

no newly searchable element.

2. Technical Requirements

Expected Volume & Performance

The volume of associated data added by the connector may vary and may be considerable. In fact, for each user, we will have to hold a state to initialize to compare states between different dates ( to allow comparing Blockchain data in a range of time ). This can be avoided by retrieving the information from blockchain at a specific block of time. This second solution may not be cost effective since it will impact the performances, used resources (CPU and RAM) and especially number of blockchain calls, knowing that it's paid (switch used subscription of Blockchain HTTP/Websocket Access Provider).

Security

The connected User Wallets may be publically displayed as this information may be part of the user profile. Thus, like github and twitter connectors, the access to the associated list of Wallets for a given user should be publically accessible.

Extensibility

In order to address the Dynamic Points Allocation, the Gamification API has to evolve to allow connectors to determine the attributed points for each achievement/realization.

Configurability

No requirement

Upgradability

No requirement

Existing Features

No change on exiting features.

Feature Flags

Property Name	Default Value	Target Audience	Functional Behaviour
exo.feature.EVMConnector.enabled	false	all users	activates/deactivates the EVM Connector UIs. pause/resume blockchain processing. shows/hides existing actions that depend on the EVM Connector

Other Non-Functional Requirements

No other requirement

Source code
The EVM Connector should have a dedicated code repository.

Packaging
The EVM Connector should be packaged as a separate add-on.

3. Software Architecture

Access

Vue potlets extensions will be used as made for gamification-twitter and gamification-github to inject throw extensionRegistry the extension points.

Services & processing

Gamification API with Dynamic Points

The Gamification RealizationService API has to evolve to allow retrieving attributed score/points for a given achievement using a given ConnectorPlugin when the action is automatic and has an associated Connector.

Gamification Achievement trigger flow

A scheduled Task has to be added in order to make period check (each hour by example, may be configurable through properties) on the following business logics:

• Hold a Token: to check holdings of an ERC20 token. Example: I configure a weekly action that will reward 10 points when the user holds a minimum of 100 xMeeds for at least 1 week.
• Hold an NFT: to check holdings of an ERC-1155 or ERC-721 token. I configure a weekly action that will reward 700 points when the user holds any number of xMeeds Deed for at least 1 week.
• Hold Uniswap V3 Positions : to check Uniswap V3 LP positions. I configure an action that will reward 100 pts for holding positions within the price range 0.99-1.01 on the USDT/MEED pool on Uniswap.
• EVM Event: to listen to events emitted during transactions

This scheduled Task will:

1. retrieve Blockchain events on a all configured contracts on Gamification actions from the last check block. If any change has been made, then the list of wallets having made changes has to be updated consequently.
2. check for all connected users wallets statuses if they are eligible to the configured criteria. If so, then trigger the achievement and then reinitialize the user status
3. Save last check block for each configured blockchain identified by its Netword Id

Data and persistence

A change has to be introduced in Database Model in order to include User Associated Wallets with its associated statuses. In addition, we will have to store advanced configuration of Actions.

[plamarque]

@margondicco @srenault-meeds ready for func review.

[srenault-meeds]

LGTM!
Except some items to remove from the UI (cancellation cases to check) but no blocker of course :)

[plamarque]

LGTM! Except some items to remove from the UI (cancellation cases to check) but no blocker of course :)

fixed. Also added a few user stories related to the ability to configure other EVM user accounts than the Meeds Wallet app

[plamarque]

after discussing with @MayTekayaa :

• added separate events for function calls and EVM events
• added the ability to filter according to the params of the calls
• updated mockups accordingly

[margondicco]

Hello crystal clear ;-) No objection

[plamarque]

@boubaker @MayTekayaa we have a GO-func. Ready for tech spec!

[boubaker]

@boubaker @MayTekayaa we have a GO-func. Ready for tech spec!

ok, thanks. @MayTekayaa I let you prepare the Tech requirements, don't hesitate to DM me if you need help.

[plamarque]

@MayTekayaa quick update after the first technical review :

• remove function calls case (we'll use events only)
• adding blockchains by endpoint
• updated mockups

[boubaker]

Example: I configure a weekly action that will reward 700 points when the user holds any number of xMeeds for at least 1 week.

The xMeed is an ERC20. In fat the Deed is an NFT of type ERC-1155.

[boubaker]

ready for tech review by DAO Members ( eXo : @rdenarie )

[boubaker]

ready for tech review by DAO Members ( eXo : @rdenarie )

@rdenarie FYI

[rdenarie]

Go tech