B3TR - Incentive Token

Address: 0x5ef79995FE8a89e0812330E4378eB2660ceDe699

B3TR is the incentive token of VeBetterDAO. Its functions include:

1. General incentive token for VeBetterDAO, including DAO Treasury Management

2. Value carrier and monetization mechanism for active participants and innovative enterprise models

3. Incentive token for sustainability applications

4. Back VOT3 tokens 1:1, the token required for VeBetterDAO governance

The total supply of B3TR is capped at 1,000,000,000 tokens, with a weekly issuance schedule carried out over 12 years.

VOT3 - Governance Token

Address: 0x76Ca782B59C74d088C7D2Cce2f211BC00836c602

VOT3 is the governance token of the VeBetterDAO. Its functions include:

1. Required to take part in governance

2. Convertible, 1:1 between B3TR and VOT3

You can convert back and forth between B3TR and VOT3 whenever you want, with the only limitation that you cannot convert VOT3 tokens sent to you by other wallets into B3TR, just the amount you originally converted.

The Treasury is the beating heart of any DAO, representing the store of wealth and source of funds for the ecosystem. Adhering to the core principles of Web3, the VeBetterDAO Treasury will be transparent, fiscally efficient, and auditable.

Treasury management follows the rules and protocols defined in VeBetterDAO Governance. The uncompromising principle of the Treasury Pool is that tokens will only be used for expanding and building the VeBetterDAO ecosystem, making the world better in the process.

Implementation

Treasury will hold all assets belonging to the DAO. Such assets include VET, VTHO, B3TR, VOT3 and any other ERC-20 or ERC-721 tokens that have been transferred to the Treasury contract address.

Tokens can only be transferred from the Treasury to another address via a governance proposal. The same goes for converting to B3TR/ VOT3 .

Token balances can be viewed by anyone by calling one of the balance functions.

In the case that the Treasury needs to stop all transactions, the smart contract can be paused.

This contract cannot transfer tokens out that are non-native or non ERC-721 or ERC-20.

Contract Functionality

Transfer Limits

Each token has a transfer limit in place to avoid moving huge sums of money in a single operation. Those limits can be updated by governance and are token-specific.

Current limits are:

• 200,000 VET

• 200,000 B3TR

• 3,000,000 VTHO

• 50,000 VOT3

B3TR tokens are emitted weekly to three pools based on the schedule outlined in the next section. A smart contract is required to control these emissions.

Emissions Schedule

B3TR token has ~1 billion total supply, that will be emitted weekly over a period of 634 weeks or 12 years.

N.B. We will use the term cycle instead of week when referring to the emissions schedule.

Emissions Parameters

The Emissions smart contract contains parameters for the emissions scheduling.

Triggering Emissions

Emissions need some sort of trigger, as it is not possible for a smart contract to invoke itself. There is a public function that can be triggered by any account. In addition to this, the foundation automatically triggers the emissions, if this operation fails, any other user can trigger it.

The pool’s purpose is to finance sustainable apps that join the VeBetter ecosystem. The purpose of the apps is to use those tokens to reward and incentivize sustainable actions through their applications.

Allocation rounds

Distribution of B3TR from the x-allocation pool to the apps happens in cycles, which we will refer to from now on as rounds. Each round will last 1 week, and funds will be distributed once the round ends.

Apps receive B3TR tokens based on the support that they receive from the VOT3 holders through voting.

All unallocated funds of that round are sent to the Treasury contract.

Rules

• Voting Token: The token used for voting is VOT3.

• Voting Frequency: Each round of voting lasts one week, though this period could change in the future.

• Votes Snapshot: The VOT3 holdings and better action are snapshotted at the start of each round. VOT3 tokens acquired and better action done after that moment won't be considered when casting the vote.

• Voting Flexibility: Within each round, users can vote only once but have the flexibility to allocate their votes among multiple apps. For example, a user with 100 VOT3 might assign 30 VOT3 to app #1, 20 VOT3 to app #2, and 50 VOT3 to app #3.

• Resetting Votes: At the beginning of each round, all previous votes are reset, requiring users to cast their votes again. This design encourages the community to return and vote regularly, hence the introduction of a "vote-2-earn" mechanism, where users are rewarded for voting.

• Allocation Shares: At the end of each round, the smart contract calculates the ranking and determines the distribution of funds among the apps.

• Quorum Requirements: To ensure broad community involvement, each round must meet a specific quorum to validate the results. If the quorum is not reached, the distribution still occurs but is based on the percentages from the last valid round.

Voting Process

Each emission distribution starts a new allocation round for x2earn applications.

At the start of each round, a snapshot of the VOT3 holdings is made.

There can be only two possible outcomes of a round: it succeeds or fails. To succeed the only requirement is that the quorum, which is currently 1% of total VOT3 supply, is reached.

A user can cast his votes only when the round is active and only one time per round, by passing an array of x-application IDs and the fraction of votes he wants to allocate to each.

Earnings calculation

• Allocation Structure: The distribution from the X-Allocation Pool to the apps is divided into two parts:

  • 30% is evenly distributed among all qualified applications, ensuring a base level of funding for each app.

  • 70% is distributed based on the percentage of votes each app receives.

• Cap on Allocation: To prevent any one project from dominating, there's a cap on how much each app can receive from the 70% pool. This cap ensures that at least six projects participate in the voting each week.

• Redistribution: Any leftover funds from the X-Allocation Pool will be sent to the Treasury and can be redistributed through DAO voting.

Both the minimum and maximum caps can be changed by the governance.

Quorum impact on distribution

When the quorum is not reached during an allocation voting round, it can impact the distribution process. Let's assume we have 2 rounds, where the first one succeeded and the second one did not, here is how it would work:

• Total Funding for Current Round: The total amount for distribution is derived from the current round, regardless of what happened in previous rounds.

  • Example: If Round 1 had 90,000 B3TR to distribute, but Round 2 had 80,000, the allocations in Round 2 will use the 80,000 units as the funding pool.

• Base Allocation: Every application in the current round receives a minimum allocation from the total funding pool, even if the quorum isn't met. This is calculated based on the current round's funding amount.

• Variable Allocation: This additional funding is determined by the voting results from the last successful round (e.g., if Round 1 succeeded, the votes from that round influence allocations in Round 2).

  • If quorum fails in the current round, variable allocations calculation will rely on the last successful round votes.

  • New applications in a failed round, with no previous votes to draw from, will only receive the base allocation.

Distribution trigger

Distributions are not automatically sent by the contract but need to be triggered. The claim function is public and anyone can claim the allocation for the apps. The VeBetterDAO team however created a scheduler service to execute this action at the start of each new round.

Quadratic Funding

Quadratic Funding (QF) is a mechanism used by VeBetter DAO to amplify available resources and democratize fund allocation.

In this system, the proportion of the emissions pool allocated to each project is calculated by squaring the sum of the square roots of individual votes for the project and then normalizing this by the square of the total votes across all projects

where j indexes the voters for each project

where j indexes the voters, and k indexes all projects considered in the QF model for the round.

This formula ensures that the allocation is heavily influenced by the number of distinct supporters rather than the sum of their votes alone. As a result, projects that have broader community support, regardless of the size of individual votes, receive a more significant portion of the emissions pool.

This funding model emphasizes community consensus, ensuring that projects with the widest appeal, rather than those with the most concentrated VOT3 backing, receive the greatest B3TR allocation.

Linear Voting

By default, QF is enabled for all voting rounds. However, admins have the option to disable QF. If QF is disabled, linear voting will be used, where the allocation is directly proportional to the number of votes received.

• Important Note: If QF is disabled by an admin in the middle of a round, the change will only take effect starting from the following round.

Upgradeable parameters

The following properties can be updated by the governance:

• Voting Period: currently this equals Emission's cycles, and can never be higher than it.

• Quorum: percentage of VOT3 / Total supply participating in allocation voting.

• Base Allocation Percentage: percentage of round allocations to be divided among the apps each round, currently set at 30%.

• Allocation Cap: the maximum amount of votes (in percentage) that an app can receive, currently set at 20%.

The ‘X’ in X-2-Earn refers to the mathematical concept of the unknown variable. ‘X’ can be applied to any kind of sustainability ecosystem with an earn mechanism. For example, ‘Plant-2-Earn', for an ecosystem that rewards tree planting. Sweat-2-Earn, for dApps that reward working out, and so on. B3TR tokens distributed to X-2-Earn dApps are, in part, intended as a source of incentivization for users. They may serve other purposes, such as encouraging builders, or for marketing and sponsorships etc. B3TR reward distribution plans are at the discretion of projects and the voting community who will approve or disapprove of a project’s reward proposals through voting.

Join VeBetterDAO

As of the beginning of November, VeBetter DAO allows apps to join the ecosystem through the endorsement of VeChain node holders. This shift from admin-controlled app selection to vechain community-based endorsement reflects the DAO’s commitment to decentralization.

• Background Check and Creator NFT Requirement: XApp creators begin by filling out a form on the VeBetter DAO platform to initiate the process. If they pass the screening, they are minted a Creator NFT, which verifies them for participation in the endorsement process.

• On-Chain XApp Submission: Once they have received the Creator NFT, XApp creators can submit their XApp on-chain for endorsement consideration. This submission officially registers the XApp on the VeBetter DAO platform, pending endorsements from VeChain node holders.

• Connecting with Endorsers: After receiving the Creator NFT, XApp creators gain access to the VeBetter DAO Discord server, where they can connect with VeChain node holders who may endorse their XApp. This community platform allows them to build relationships with potential endorsers and formally submit their XApp for consideration on the VeBetter DAO platform.

• XApp Endorsement: XApps must accumulate an endorsement score of 100 to become eligible for allocation rounds. Achieving this threshold enables an XApp to participate in weekly rounds to receive a share of the B3TR allocation pool.

VeChain Node Scores

VeChain node holders are key decision-makers in the X2Earn endorsement process. Each type of VeChain node, represented by an NFT in the holder’s wallet, has an assigned endorsement score based on its level. These scores determine the impact each endorsement has on an XApp’s eligibility.

A wallet can only hold one of these VeChain Node NFTs at a time, and to obtain a node, users must maintain a specific amount of VET in their wallet (see vechain nodes for more info). The cumulative endorsement scores from nodes determine an XApp’s eligibility to join VeBetter DAO and participate in allocation rounds.

Voting Eligibility and Endorsement Status

Once an XApp is endorsed, reaching a cumulative endorsement score of 100, it becomes eligible to receive funds in the allocation rounds. This eligibility can be adjusted by VeChain node holders based on the app's performance and compliance.

XApp Endorsement

An XApp is officially considered endorsed when it accumulates an endorsement score of 100. This score is the sum of all VeChain node endorsements for the app. Upon reaching this threshold, the XApp automatically qualifies for the next XAllocation Voting round and will continue participating in future rounds as long as its score remains at or above 100.

• Endorsement Limitations: Each VeChain Node NFT can endorse only one XApp at a time. Similarly, each account can endorse only one XApp unless it leverages the NodeManagement contract to delegate multiple VeChain nodes.

• Endorsement Cap: Once an XApp reaches the endorsed status with a score of 100, it cannot receive additional endorsements from other nodes.

XApp Un-Endorsement and Grace Period

Node holders have the authority to withdraw their endorsement if they no longer wish to support a specific XApp. If an XApp’s score falls below the 100-point threshold, it enters a grace period. During this time, the XApp has a limited opportunity to regain endorsements and restore its score to 100. If it fails to meet this requirement before the grace period ends, it will be removed from the XAllocation voting round.

• Retention of Past Allocations: Although the XApp is removed from future allocation rounds, it still retains any allocations received from previous rounds. The XApp may rejoin allocation rounds if it regains the necessary endorsement score of 100.

Integrity Checks

To ensure the consistency and validity of endorsements, VeBetter DAO conducts periodic checks on endorsing nodes.

App ID

When your app is submitted to the contract an appId is generated by hashing the app name. This id cannot be updated in the future, even if you change the name of your app.

Signaling

Authorized apps can report addresses they have banned, such as looters, bots or scammers. This helps VeBetterDAO and other apps detect and defend against harmful activity across the ecosystem.

If an address is flagged by mistake, VeBetterDAO or selected app admins can review the case and reset its signal counter.

Community Dashboard: https://vechain-energy.github.io/vebetterdao-signal-admin/ Build by the community, this dashboard shows all signaled wallets.

Metadata

When an app is added the following information is saved on-chain:

• name: the name of the app, cannot change once it's added.

• app ID: is the hash of the name of the app (from the previous point) and it's used as a unique identifier across all the smart contracts; once the app is added and this ID is generated it cannot be updated.

• receiver address: this is the address where the app will receive the allocation funds, also addressed to as "Treasury address".

• creation timestamp: the timestamp when the app was added.

• metadata URI: the IPFS CID containing all the information of the app, which will be used by the frontend to display the app details.

• moderators: a list of addresses that can update the metadataURI of an app.

• admin: this address can add/remove moderators, change the receiver address, transfer ownership to another admin, and update the metadata URI of the app.

The metadata URI needs to follow the following standard:

{
   "name":"My sustainable app",
   "description":"Run and get rewarded",
   "external_url":"https://openseacreatures.io/3",
   "logo":"https://storage.googleapis.com/opensea-prod.appspot.com/puffs/3.png",
   "header_image":"https://storage.googleapis.com/opensea-prod.appspot.com/puffs/3.png",
   "screenshots":[
      "https://storage.googleapis.com/opensea-prod.appspot.com/puffs/3.png",
      "https://storage.googleapis.com/opensea-prod.appspot.com/puffs/3.png",
      "https://storage.googleapis.com/opensea-prod.appspot.com/puffs/3.png"
   ],
   "social_urls":[
      {
         "name":"YouTube",
         "url":"https://www.youtube.com/@DLoaw"
      },
      {
         "name":"Instagram",
         "url":"https://www.instagram.com/@DLoaw"
      }
   ],
   "app_urls":[
      {
         "code":"play_store",
         "url":"https://www.playstore.com/@DLoaw"
      },
      {
         "code":"apple_store",
         "url":"https://www.applestore.com/@DLoaw"
      },
      {
         "code":"web_app",
         "url":"https://www.myapp.com"
      }
   ],
   "tweets": []
}

The B3TR contract was verified on Sourcify and can be reviewed at the following URL: https://repo.sourcify.dev/100009/0x5ef79995FE8a89e0812330E4378eB2660ceDe699

More contracts were verified on Sourcify, so just search on Sourcify the contract address you want to audit.

Anyone holding VOT3 is a member of the DAO and can take part in voting events. VOT3 is the VeBetterDAO’s governance token, required to vote, and obtained by swapping from B3TR at a 1:1 ratio. All members can vote on proposals, participate in governance discussions, and access the Treasury, with the only minimum requirement of holding at least 1 VOT3 token. This ensures we can foster an inclusive, engaging environment for everyone.

Governance Stabilization Period and Initialization

At launch, VeBetterDAO will adhere to an initial set of governance rules until it has run for one year without any technical interruptions. The Stabilization Period is critical for ensuring the long-term efficacy and viability of VeBetterDAO. To prevent exploits during the Stabilization Period, VeChain Foundation maintains the ability to pause & restart B3TR token minting, only in the case of an exploit or other major issue. Once the requirements of the Stabilization Period have been met, community stakeholders can maintain or deprecate this functionality through governance.

Proposal Submission

Proposals are the backbone of any DAO, and the community is a key part of the proposal process. VeBetterDAO will maintain a forum for proposal submission, discussion, and voting. The forum will feature a dashboard detailing voting results, historical records, and proposal details. For a proposal to reach the final stages and be implemented, it must go through a predefined process, including initial forum-based community discussion, and a community ‘temperature check,’ before on-chain voting and implementation.

Community support

Every time a proposal is created, a deposit threshold of VOT3 tokens, calculated upon the total supply of B3TR, is calculated and must be met for the proposal to become active.

This deposit functions as a temperature check—if the community believes the proposal is worth considering, they can contribute a certain amount of VOT3. If enough VOT3 is deposited (reaching the threshold) before the end of the waiting period, the proposal becomes active; otherwise, it is automatically canceled.

Users can withdraw their VOT3 deposits once the proposal is canceled or the voting period starts.

While tokens are locked for supporting the proposal they cannot be used to vote in allocation rounds or other proposals. This means that if we are in Round #2 and you support a proposal that will start in Round #4 you won't be able to access those tokens/vote in Round #3 and Round #4.

Governance Process

The governance process is the following: propose → vote → execute if succeeded.

Let's break it down:

1. Everyone can create a proposal. When creating a proposal the user specifies a description and an action to be performed on proposal success. The action can be: - Call the function x() of the contract with address 0x00000 with the following parameters. - Call multiple functions of different contracts with different parameters in a specific order. - Do nothing. E.g.: “Let’s add feature X”. Even if the outcome is “YES” there is no on-chain action to perform immediately because it needs off-chain developers' involvement. When the proposal is created a snapshot of the total supply of VOT3 tokens and balances of each VOT3 holder is taken and used to calculate individual voting power. Proposals are aligned with the allocation rounds voting periods, so the proposer must also specify the round when the proposal should become active.

2. After the proposal is created there is a waiting period before the proposal becomes active (can receive votes). During this waiting period, there is a temperature check and the community must fund the proposal with VOT3 tokens. Each proposal has a deposit threshold to reach, and if this threshold is not reached then the proposal gets automatically canceled. During this waiting period, the proposal can be canceled by the user who created it or by an admin of the DAO.

3. Once the proposal is active VOT3 holders can vote AGAINST/YES/ABSTAIN for that proposal. Each proposal will remain active for the duration of the round. When you cast your vote all 100% of your voting power will be used.

4. Once the voting period is over, if the quorum is reached and the majority voted in favor, the proposal is considered successful and can proceed to be executed. A Timelock is used for this operation, which adds a delay to proposal execution.

Quorum

Quorum is 30% of the total supply of VOT3. All types of votes (yes, no and abstain) are considered when calculating if quorum is reached.

Voting rewards are distributed regardless of what type of vote was cast.

Vote Outcome

If a quorum is not reached then the proposal is considered defeated.

If a quorum is reached then "yes" and "no" votes are counted, if "yes" votes are more than "no" votes then the proposal is considered succeeded.

Voting rewards are distributed regardless of the vote outcome.

Execution

The VeBetterDAO's Governance contract can execute actions on all contracts deployed on the vechain blockchain, provided the respective contracts permit those actions.

We added a timelock to governance decisions, this allows users to exit the system if they disagree with a decision before it is executed. We are using OpenZeppelin’s TimelockController in combination with the GovernorTimelockControl module to achieve this. To execute a proposal it first needs to be queued to Timelock contract and wait a specified amount of time before being able to execute it.

Initially only selected admins will be able to execute proposals.

Vote Delegation

For DAOs that use the Governor contract (as we do), only delegated tokens can participate in voting. What does this mean for you, a token holder?

You must set up delegation if you want to participate in governance votes. This includes delegating to others or voting yourself.

If you wish to vote on proposals directly, delegate your voting power to your own address. Or, you can delegate your voting power to another community member and let them vote on your behalf.

Currently, we have an auto-delegation feature in our smart contract that will automatically delegate to you when you convert B3TR to VOT3 or someone sends you VOT3 tokens. However this auto-delegation feature is not enabled for smart contracts, so if you are writing a smart contract that wants to receive VOT3 tokens and participate in governance you will need to manually delegate. This needs to be done only once.

Quadratic Voting

🚨 Note: QV is currently disabled starting from Round 12 onwards. Linear voting is now in effect (see details below).

Quadratic Voting (QV) is a method used to re-calibrate voting power within the VeBetter DAO, specifically for the B3TR Governance model. Unlike traditional voting mechanisms that may disproportionately empower large token holders, QV modifies this by determining voting power based on the square root of the number of VOT3 tokens held. This approach ensures that while voting power increases with more tokens, it does so at a diminishing rate.

The formula shown below reduces the influence larger stakeholders might have, promoting a more balanced and fair decision-making process.

Each voter casts their vote as FOR, AGAINST, or ABSTAIN on proposals, with the effective weight of these votes directly linked to their recalculated voting power​. This structure not only aligns with standard quadratic voting practices but also ensures governance is more reflective of the wider community preferences.

Linear Voting

By default, QV is enabled for all voting rounds. However, governance and admins can choose to disable QV, switching to linear voting. In linear voting, voting power is directly proportional to the number of VOT3 tokens a user holds.

• Important Note: If QV is disabled by an admin during an ongoing round, the change will only take effect starting from the next round.

Upgradeable parameters

The following parameters can be updated by governance:

• Quorum: currently set at 30% of total VOT3 supply

• Deposit Threshold: percentage of the total supply of B3TR tokens that need to be deposited in VOT3 to create a proposal, currently set at 2%

• Voting Threshold: the minimum amount of tokens needed to cast a vote, currently set at 1

• Minimum Voting Delay: the minimum delay a proposal must be in a PENDING state before voting can start, currently set at 3 days

• Timelock Minimum Delay: time to wait before a proposal can be executed after it was queued

• Voting Period: the duration of the proposal; it is not possible however change this on the governance contract itself since it's aligned with the Emissions cycles, so the cycle duration should be updated to see the same changes in governance.

• Enable / Disable Functions Restrictions: if disabled there isn't any restriction on what contracts and functions can be called when creating a proposal

• Whitelist Functions: if function restrictions are enabled then whitelist a target and function

Putting it all together we get a picture of the connections of all smart contracts with hierarchies and usages between each other.

The following is the list of all smart contracts listed alphabetically:

B3TR

This contract governs the issuance and management of B3TR fungible tokens within the VeBetter ecosystem, allowing for minting under a capped total supply.

Extends ERC20 Token Standard with capping, pausing, and access control functionalities to manage B3TR tokens in the VeBetter ecosystem.

Address: 0x5ef79995FE8a89e0812330E4378eB2660ceDe699

B3TRProxy

This contract implements an upgradeable proxy for all of our upgradeable contracts. It is upgradeable because calls are delegated to an implementation address that can be changed. This address is stored in storage in the location specified by https://eips.ethereum.org/EIPS/eip-1967[EIP1967], so that it doesn't conflict with the storage layout of the implementation behind the proxy.

Forked from Openzeppelin.

B3TRGovernor

This contract is the main governance contract for the VeBetterDAO ecosystem. Anyone can create a proposal to both change the state of the contract, to execute a transaction on the timelock or to ask for a vote from the community without performing any on-chain action. In order for the proposal to become active, the community needs to deposit a certain amount of VOT3 tokens. This is used as a heath check for the proposal, and funds are returned to the depositors after vote is concluded. Votes for proposals start periodically, based on the allocation rounds (see xAllocationVoting contract), and the round in which the proposal should be active is specified by the proposer during the proposal creation.

A minimum amount of voting power is required in order to vote on a proposal. The voting power is calculated through the quadratic vote formula based on the amount of VOT3 tokens held by the voter at the block when the proposal becomes active.

Once a proposal succeeds, it can be executed by the timelock contract.

The contract is upgradeable and uses the UUPS pattern.

Manages the governance process for the VeBetterDAO ecosystem, allowing users to create and vote on proposals with VOT3 token deposits. This contract leverages OpenZeppelin's AccessControl and UUPSUpgradeable libraries for role-based access control and upgradeability. The core functionality, including proposal management, voting mechanisms, quorum calculations, and deposit logic, is modularly organized in external libraries, ensuring maintainability, flexibility, and ease of upgrades.

Address: 0x1c65C25fABe2fc1bCb82f253fA0C916a322f777C

Emissions

This contract is responsible for the scheduled distribution of emissions based on predefined cycles and decay settings.

Manages the periodic distribution of B3TR tokens to XAllocation, Vote2Earn, and Treasury allocations. This contract leverages openzeppelin's AccessControl, ReentrancyGuard, and UUPSUpgradeable libraries for access control, reentrancy protection, and upgradability.

Address: 0xDf94739bd169C84fe6478D8420Bb807F1f47b135

GalaxyMember

This contract manages the unique assets owned by users within the Galaxy Member ecosystem.

Extends ERC721 Non-Fungible Token Standard basic implementation with upgradeable pattern, burnable, pausable, and access control functionalities.

Address: 0x93B8cD34A7Fc4f53271b9011161F7A2B5fEA9D1F

NodeManagement

This contract acts as a proxy between Vechain Node Contracts and VeBetter DAO, enabling node holders to delegate and manage multiple nodes within a single account.

Address: 0xB0EF9D89C6b49CbA6BBF86Bf2FDf0Eee4968c6AB

Timelock

This contract is used to perform the actions of the B3TRGovernor contract with a time delay. The proposers and executors roles should be assigned only to the B3TRGovernor contract.

Address: 0x7B7EaF620d88E38782c6491D7Ce0B8D8cF3227e4

Treasury

This contract is designed to manage all assets owned by the VeBetter DAO

This contract handles the receiving and transferring of assets, leveraging upgradeable, pausable, and access control features.

Address: 0xD5903BCc66e439c753e525F8AF2FeC7be2429593

VOT3

This contract governs the issuance and management of VOT3 tokens, which are the tokens used for voting in the VeBetter DAO Ecosystem.

Extends ERC20 Fungible Token Standard basic implementation with upgradeability, pausability, ability for gasless transactions and governance capabilities.

Address: 0x76Ca782B59C74d088C7D2Cce2f211BC00836c602

VoterRewards

This contract handles the rewards for voters in the VeBetterDAO ecosystem. It calculates the rewards for voters based on their voting power and the level of their Galaxy Member NFT.

The contract is

• upgradeable using UUPSUpgradeable.

• using AccessControl to handle the admin and upgrader roles.

• using ReentrancyGuard to prevent reentrancy attacks.

• using Initializable to initialize the contract.

• following the ERC-7201 standard for storage layout.

Address: 0x838A33AF756a6366f93e201423E1425f67eC0Fa7

X2EarnApps

This contract handles the x-2-earn applications of the VeBetterDAO ecosystem. The contract allows the insert, management, and eligibility of apps for the B3TR allocation rounds.

The contract is using AccessControl to handle the admin and upgrader roles. Only users with the DEFAULT_ADMIN_ROLE can add new apps, set the base URI, and set the voting eligibility for an app. Admins can also control the app metadata and management. Each app has a set of admins and moderators (built without using AccessControl) that can manage the app metadata and management.

Address: 0x8392B7CCc763dB03b47afcD8E8f5e24F9cf0554D

X2EarnCreators

This contract is designed to manage new XApp submissions within VeBetter DAO, ensuring only verified creators can enter the ecosystem. This contract supports Creator NFTs, non-transferable ERC721 tokens, to grant creators access to the endorsement process.

Extends ERC721 Non-Fungible Token Standard basic implementation with upgradeable pattern, pausable, and access control functionalities.

Address: 0xe8e96a768ffd00417d4bd985bec9EcfC6F732a7f

X2EarnRewardsPool

This contract is used by x2Earn apps to reward users that performed sustainable actions. The XAllocationPool contract or other contracts/users can deposit funds into this contract by specifying the app that can access the funds.

Admins of x2Earn apps can withdraw funds from the rewards pool, which are sent to the team wallet address. The contract is upgradeable through the UUPS proxy pattern and UPGRADER_ROLE can authorize the upgrade.

Address: 0x6Bee7DDab6c99d5B2Af0554EaEA484CE18F52631

XAllocationPool

This contract receives B3TR tokens from the Emissions contract and distributes them to the rewards pool contract and x2earn apps based on the allocation round outcome. Funds can be claimed at the end of each allocation round.

Interacts with the Emissions contract to get the amount of B3TR available for distribution in each round, and the x2EarnApps contract to check app existence and receiver address. The contract is using AccessControl to handle roles for upgrading the contract and external contract addresses.

Address: 0x4191776F05f4bE4848d3f4d587345078B439C7d3

XAllocationVoting

This contract handles the voting for the most supported x2Earn applications through periodic allocation rounds. The user's voting power is calculated on his VOT3 holdings at the start of each round, using a "Quadratic Funding" formula.

Rounds are started by the Emissions contract. Interacts with the X2EarnApps contract to get the app data (eg: app IDs, app existence, eligible apps for each round). Interacts with the VotingRewards contract to save the user from casting a vote. The contract is using AccessControl to handle roles for admin, governance, and round-starting operations.

Address: 0x89A00Bb0947a30FF95BEeF77a66AEdE3842Fe5B7

B3TR Multisig

The B3TR Multisig contract facilitates multisignature operations for enhanced security and collaborative management of the wallet. This contract requires approvals from multiple stakeholders before any transaction can be executed, ensuring that all actions are transparent and consensual.

This contract is not upgradable.

Libraries

Some contracts (eg: B3TRGovernor) store their logic inside libraries to optimize the contract size. The following is the list of libraries we created and the addresses they are deployed to.

GovernorClockLogic

Library for managing the clock logic as specified in EIP-6372, with fallback to block numbers.

This library interacts with the IVOT3 interface to get the clock time or mode.

GovernorConfigurator

Library for managing the configuration of a Governor contract.

This library provides functions to set and get various configuration parameters and contracts used by the Governor contract.

GovernorDepositLogic

Library for managing deposits related to proposals in the Governor contract.

This library provides functions to deposit and withdraw tokens for proposals, and to get deposit-related information.

GovernorFunctionRestrictionsLogic

Library for managing function restrictions within the Governor contract.

This library provides functions to whitelist or restrict functions that can be called by proposals.

GovernorProposalLogic

Library for managing proposals in the Governor contract.

This library provides functions to create, cancel, execute, and validate proposals.

GovernorQuorumLogic

Library for managing quorum numerators using checkpointed data structures.

GovernorStateLogic

Library for Governor state logic, managing the state transitions and validations of governance proposals.

GovernorVotesLogic

Library for handling voting logic in the Governor contract.

Contracts Upgradeability

Resources

Library updates

In B3TRGovernorwe are utilizing libraries inside some of the modules. To upgrade the functionalities inside these libraries the following steps must be done.

1. Update library

2. Deploy new library

3. Deploy new implementation contract connecting updated library with new library address

4. Upgrade the proxy to use this new implementation smart contract using the upgradeToAndCall function .

B3TR tokens will be sent weekly to the Vote2Earn pool. The purpose of these funds and this pool is to incentivize people to engage in the platform by voting on proposals and allocation rounds. B3TR tokens will be rewarded to users who have voted in the previous voting cycle, both in general governance proposals and allocation rounds.

All funds received by the Vote2Earn pool as part of the B3TR emissions will be used as voter rewards.

Galaxy Member NFT: Unlock Greater Rewards with Upgrades

VeBetter DAO utilizes an upgradeable NFT system, the Galaxy Member (GM) NFT, to determine user privilege and reward levels. The higher your GM NFT level, the greater the B3TR token rewards you can earn during governance and xallocation voting participation.

Unlocking GM NFT Levels

There are two ways to upgrade your GM NFT:

1. Using B3TR Tokens:

   • Donate the required B3TR tokens to upgrade your GM NFT level.

   • Each level requires progressively more B3TR to unlock.

2. For Free (Node Holders):

B3TR Requirements for Upgrades

Benefits of Upgrading Your GM NFT

• Maximized Rewards:

  • Higher levels provide greater multipliers for governance rewards.

• Flexibility:

  • Use B3TR for upgrades or enjoy free upgrades as a VeChain Node holder.

• Dynamic Participation:

  • Contribute actively to the ecosystem with enhanced rewards.

By participating in governance and upgrading your GM NFT, you can maximize your rewards and actively contribute to the growth of the VeBetter DAO ecosystem.

Linear Rewards

Reward Formula

1) First calculate the weighted vote for a single user:

Where:

• t is the amount of VOT3 tokens held by the user at the snapshot

• NFTMultiplier is the level multiplier percentage for the voter's Galaxy Member NFT level

2) Then, calculate the total weighted votes for the cycle (by summing votes from all users):

3) Finally, calculate the reward:

Example:

Given:

• Total participants: 1,000 voters

• Emissions (E): 1,000,000 B3TR

• Voter's votes (V): 10,000

• Level multiplier (M): 10%

• Total weighted votes from all participants: 5,300,000

Calculation:

This means out of 1,000 participants, this voter's 11,000 weighted votes represent about 0.2075% of all weighted votes, earning them 2,075 B3TR from the emission pool.

Quadratic Rewarding (disabled from round 23)

Quadratic Rewarding (QR) in VeBetterDAO is the approach used for distributing voting rewards. Under QR approach, the rewards a user receives will be determined by the square root of their VOT3 token holdings. This method ensures that while users with more tokens still receive higher rewards, the rate of increase in rewards does not grow linearly with the number of tokens held. Instead, it rises at a decreasing rate, promoting a fairer distribution of rewards and helping to close the wealth gap within our community.

Reward Formulas

QR divides rewards into two categories based on the type of voting: X Allocation and General Governance. Both types incorporate an NFT Multiplier to adjust the influence of a user’s tokens based on their GM NFT level, promoting active and sustained participation.

X Allocation Reward Calculation

where:

General Governance Reward Calculation

where:

Total Rewards Calculation

1. B3TR Token: The incentive ERC-20 token with a 1 billion cap, used within the ecosystem for rewards and governance.

2. Governance System:

   • B3TRGovernor: Facilitates decentralized governance where any community member can create proposals. Proposals require a deposit of VOT3 tokens to become active, and successful proposals are executed via the TimeLock contract.

   • TimeLock: Ensures a time delay in the execution of governance decisions for security and transparency.

3. Incentive Mechanisms:

   • Emissions: Manages the periodic distribution of B3TR tokens to various allocations including XAllocation, Vote2Earn, and Treasury.

   • VoterRewards: Rewards voters based on their voting power and Galaxy Member NFT level.

   • X2Earn Apps and Rewards: Supports x-2-earn applications by managing the insertion, management, and eligibility of apps for B3TR allocation rounds. Rewards users for sustainable actions within these apps through the X2EarnRewardsPool.

4. User Privileges and Rewards:

   • GalaxyMember: An upgradeable NFT system that determines user privileges and B3TR token rewards based on the NFT level.

5. Asset Management:

   • Treasury: Holds all DAO assets, including various ERC-20 and ERC-721 tokens. Asset transfers are governed by community proposals.

6. Voting and Allocation:

   • XAllocationPool: Distributes weekly B3TR emissions for x2earn apps.

   • XAllocationVoting: Manages voting for x2Earn application support, using a "Quadratic Funding" formula to calculate voting power based on VOT3 holdings.

VeBetterDAO leverages these contracts to create a robust and democratic ecosystem where community members can actively participate in governance, earn rewards, and contribute to the platform's growth.

Resources

Contracts addresses

Contracts have been deployed on the vechain mainnet at the following addresses.

To maintain a secure and flexible smart contract system, we leverage roles to manage administrative tasks and define who has the authority to perform specific actions. These roles control everything from minting tokens to upgrading contracts, pausing operations, and setting governance parameters.

The central goal of this structure is to gradually decentralize power from individual wallets to the DAO (the B3TRGovernor governance contract).

Roles

This document categorizes roles and outlines their functionalities, detailing what permissions each role grants. Here's a quick summary of some common roles and what they do:

• DEFAULT_ADMIN_ROLE: The superuser role with the ability to grant, revoke, and renounce roles.

• PAUSER_ROLE: Controls the ability to pause and unpause contract functionality.

• MINTER_ROLE: Allows for token minting.

• UPGRADER_ROLE: Permits contract upgrades and modifications.

• CONTRACTS_ADDRESS_MANAGER_ROLE: Manages critical contract addresses.

• DECAY_SETTINGS_MANAGER_ROLE: Manages parameters surrounding cycle lengths, allocation percentages and decay rates in the Emission contract.

• GOVERNANCE_ROLE: Involved in governance decisions, proposal management, and voting.

All roles have in common the following functionality: they can renounce that role.

Once there isn’t any address that has the DEFAULT_ADMIN_ROLE then it won’t be possible to grant or revoke any role. If some contract is upgradeable and the DAO has the UPGRADER_ROLE then the DAO could decide to upgrade the contract and assign the role to whoever they want.

Permissions

The ultimate aim is to create a self-governing system where no single entity holds absolute control. This section of the page provides a detailed plan for achieving this goal, outlining the steps for transitioning roles to the B3TRGovernor contract, removing direct admin control, and enabling decentralized governance.

Follow the outlined steps to understand the current state of role assignments and the specific actions required to achieve a more autonomous system. Through this journey, we aim to establish a resilient and community-driven ecosystem where the power of decision-making rests in the hands of the DAO and its stakeholders.

Contract: B3TR

Steps for full decentralization:

• After we migrate to mainnet we revoke the MINTER_ROLE from the admin wallet.

• When we no longer want the power to pause the contract we revoke the PAUSER_ROLE.

• We renounce the DEFAULT_ADMIN_ROLE

Contract: B3TRGovernor

Steps for full decentralization:

• B3TRGovernor is already responsible for upgrading, changing voting or deposit threshold, min voting delay, and quorum.

• We grant the GOVERNOR_FUNCTIONS_SETTINGS_ROLE to the B3TRGovernor, and revoke it from the current wallet. Now governance can vote on whitelisting other functions or completely remove whitelisting of functions on proposal creation.

• We grant the CONTRACTS_ADDRESS_MANAGER_ROLE to the B3TRGovernor, and revoke it from the current wallet.

• We renounce the PAUSER_ROLE or grant it to the B3TRGovernor

• We renounce the DEFAULT_ADMIN_ROLE and PROPOSAL_EXECUTOR_ROLE

Contract: Emissions

Steps for full decentralization:

• We renounce the MINTER_ROLE once we complete the mainnet migration

• We grant the UPGRADER_ROLE to the B3TRGovernor and revoke it from the current wallet

• We grant the DEFAULT_ADMIN_ROLE to the B3TRGovernor and revoke it from the current wallet

• We grant the CONTRACTS_ADDRESS_MANAGER_ROLE to the B3TRGovernor and revoke it from the current wallet

• We grant the DECAY_SETTINGS_MANAGER_ROLE to the B3TRGovernor and revoke it from the current wallet

Contract: GalaxyMember

Steps for full decentralization:

• We renounce the MINTER_ROLE once we complete the mainnet migration

• We grant the UPGRADER_ROLE to the B3TRGovernor and revoke it from the current wallet

• We grant the CONTRACTS_ADDRESS_MANAGER_ROLE to the B3TRGovernor and revoke it from the current wallet

• We renounce the PAUSER_ROLE

• We grant the DEFAULT_ADMIN_ROLE to the B3TRGovernor and revoke it from the current wallet

Contract: Timelock

Steps for full decentralization:

• We grant the UPGRADER_ROLE to the B3TRGovernor and revoke it from current wallet

• We renounce the DEFAULT_ADMIN_ROLE and now Timelock is self-administrating, which means that if the DAO wants to change the proposer or executor they will need to create a proposal that calls the Timelock contract to grant/revoke that role

Contract: Treasury

Steps for full decentralization:

• The B3TRGovernor already has the GOVERNANCE_ROLE, if we have some admin that has this role then we need to renounce it

• We grant the UPGRADER_ROLE to the B3TRGovernor and revoke it from the current wallet

• We renounce the PAUSER_ROLE

• We can grant the DEFAULT_ADMIN_ROLE to the B3TRGovernor or renounce it

Contract: VOT3

Steps for full decentralization:

• We grant the UPGRADER_ROLE to the B3TRGovernor and revoke it from the current wallet.

• When we no longer want the power to pause the contract we revoke the PAUSER_ROLE.

• We renounce the DEFAULT_ADMIN_ROLE role.

Contract: VoterRewards

Steps for full decentralization:

• VOTE_REGISTRAR_ROLE should be assigned only to the contracts performing voting

• We grant the UPGRADER_ROLE to the B3TRGovernor and revoke it from the current wallet

• We grant the CONTRACTS_ADDRESS_MANAGER_ROLE to the B3TRGovernor and revoke it from the current wallet

• We grant the DEFAULT_ADMIN_ROLE to the B3TRGovernor and revoke it from current wallet

Contract: X2EarnApps

Steps for full decentralization:

• We grant the UPGRADER_ROLE to the B3TRGovernor and revoke it from the current wallet

• We grant the GOVERNANCE_ROLE to the B3TRGovernor and revoke it from current wallet

• We grant the DEFAULT_ADMIN_ROLE to the B3TRGovernor and revoke it from current wallet

NB: This contract will be upgraded to handle app endorsement, so the “Add app” functionality triggered by a GOVERNANCE_ROLE could be removed in a future release

Contract: X2EarnRewardsPool

Steps for full decentralization:

• We grant the UPGRADER_ROLE to the B3TRGovernor and revoke it from the current wallet

• We grant the CONTRACTS_ADDRESS_MANAGER_ROLE to the B3TRGovernor and revoke it from the current wallet

• We renounce the DEFAULT_ADMIN_ROLE role

Contract: XAllocationPool

Steps for full decentralization:

• We grant the UPGRADER_ROLE to the B3TRGovernor and revoke it from the current wallet

• We grant the CONTRACTS_ADDRESS_MANAGER_ROLE to the B3TRGovernor and revoke it from the current wallet

• We grant the DEFAULT_ADMIN_ROLE to the B3TRGovernor and revoke it from current wallet

Contract: XAllocationVoting

Steps for full decentralization:

• ROUND_STARTER_ROLE should always be the Emissions contract

• Renaunce GOVERNANCE_ROLE

• We grant the UPGRADER_ROLE to the B3TRGovernor and revoke it from the current wallet

• We grant the CONTRACTS_ADDRESS_MANAGER_ROLE to the B3TRGovernor and revoke it from the current wallet

• We grant the DEFAULT_ADMIN_ROLE to the B3TRGovernor and revoke it from current wallet

Setup a lambda function or an endpoint that will send the B3TR tokens to the user, providing also a proof and impacts of the rewarding action.

We will use @vechain/sdk-network and @vechain/vebetterdao-contracts to interact with VeBetterDAO's X2EarnRewardsPool contract to distribute the rewards.

Run the following command to install the packages:

yarn add @vechain/sdk-network @vechain/vebetterdao-contracts

To distribute the rewards you will need 2 information:

• Node URL

TESTNET: https://testnet.vechain.org
MAINNET: https://mainnet.vechain.org

• Your APP_ID on VeBetterDAO: create app here to obtain the APP_ID.

Now you can distribute the reward like this:

import {
  ProviderInternalHDWallet,
  ThorClient,
  VeChainProvider,
  VeChainSigner,
} from "@vechain/sdk-network";
import { X2EarnRewardsPool } from "@vechain/vebetterdao-contracts";

function rewardUser() {
    // To transfer B3TR we first need to connect to the blockchain with
    // a wallet capable of signing and broadcastisting transactions
    const thor = ThorClient.at(process.env.NODE_URL || "");
    const provider = new VeChainProvider(
      thor,
      new ProviderInternalHDWallet(
        process.env.REWARD_SENDER_MNEMONIC?.split(" ") || []
      )
    );
    const rootSigner = await provider.getSigner();

    // Call the VeBetterDAO smart contract
    const x2EarnRewardsPoolContract = thor.contracts.load(
      process.env.X2EARN_REWARDS_POOL_ADDRESS || "",
      X2EarnRewardsPool.abi,
      rootSigner as VeChainSigner
    );
    
    const tx =
      await x2EarnRewardsPoolContract.transact.distributeRewardDeprecated(
        process.env.VEBETTERDAO_APP_ID || "",
        10,
        address,
        JSON.stringify({
          version: 2,
          description: "User refilled water from a sustainable source",
          proof: {
            image: "https://image.png",
            link: "https://twitter.com/tweet/1",
          },
          impact: {
             carbon: 100,
             water: 200
          }
        })
      );

    await tx.wait();
}

import {
  ProviderInternalHDWallet,
  ThorClient,
  VeChainProvider,
  VeChainSigner,
} from "@vechain/sdk-network";
import { X2EarnRewardsPool } from "@vechain/vebetterdao-contracts";

const PRIVATE_KEY = ""
const ACCOUNT_ADDRESS_OF_PK = ""

function rewardUser() {
    // To transfer B3TR we first need to connect to the blockchain with
    // a wallet capable of signing and broadcastisting transactions
    const thor = ThorClient.at(process.env.NODE_URL || "");
    const wallet = new ProviderInternalBaseWallet(
        [
            {
                privateKey: Buffer.from(
                    PRIVATE_KEY.slice(2),
                    'hex',
                ),
                address: ACCOUNT_ADDRESS_OF_PK,
            },
        ],
    );
    const provider = new VeChainProvider(
        thor,
        wallet,
        false,
    );
    const signer = await provider.getSigner(
        ACCOUNT_ADDRESS_OF_PK,
    );

    // Call the VeBetterDAO smart contract
    const x2EarnRewardsPoolContract = thor.contracts.load(
      process.env.X2EARN_REWARDS_POOL_ADDRESS || "",
      X2EarnRewardsPool.abi,
      rootSigner as VeChainSigner
    );
    
    const tx =
      await x2EarnRewardsPoolContract.transact.distributeRewardDeprecated(
        process.env.VEBETTERDAO_APP_ID || "",
        10,
        address,
        JSON.stringify({
          version: 2,
          description: "User refilled water from a sustainable source",
          proof: {
            image: "https://image.png",
            link: "https://twitter.com/tweet/1",
          },
          impact: {
             carbon: 100,
             water: 200
          }
        })
      );

    await tx.wait();
}

Emissions

The parameters related to emissions are adjustable; however, modifying them without careful consideration could negatively impact the overall emissions. It is crucial to maintain these settings as stable as possible.

Roles and Security

Our DAO has multiple roles, each with its admin powers, which presents a potential vector for attack. We acknowledge this risk and have implemented best practices for securing the private keys associated with these roles. These measures are crucial in protecting our system from unauthorized access and potential security breaches.

Initial centralization

We are committed to gradually transitioning to a fully decentralized system. This transition aims to reduce the reliance on centralized admin powers, thereby enhancing the security and robustness of our governance structure. The move towards decentralization is a deliberate process to ensure stability and maintain trust as we shift control from centralized figures to the DAO members.

X2Earn dApps should consider implementing necessary security measures to guard against farmers unfairly obtaining b3tr tokens.

Farming Approaches

• Single Person, Single Wallet -> In this scenario the attacker is a single person using a single wallet address. They try to repeat the same claim for b3tr rewards multiple times for the same wallet address. If the dApp is using AI for image validation, they could attempt to use a fake image over and over again.

• Single Person, Multiple Wallets -> In this scenario the attacker is a single person but now using multiple wallet addresses. For example they might submit a claim for a reward, then logout of the dApp then login with a different wallet address in VeWorld and repeat the same claim. The attacker then repeats this exercise switching between different accounts to make multiple claims for rewards.

• Scripts (aka Bots) -> This is where the attacker has coded a script that submits a claim for rewards. The script might try a single wallet or use multiple wallets to submit the claim for a reward. If the dApp is using AI for image verification, the script might generate a new image or adjust a previously created image.

• Multiple Collaborating People, Multiple Wallets -> In this scenario a group of attackers are collaborating together, they may share the same wallet, share social login details. As they are collaborating together they are collecting rewards for the group, which they can share between the group later.

• Exploiting Vulnerabilities -> In this scenario the attacker exploits vulnerabilities in smart contracts or back-end API services to create Bots or manually bypass the front-end of the dApp.

Potential Solutions

Securing Back-End APIs

• Certificate based authentication -> For example if there is a /account endpoint this should be secured with the signed certificate the user signs in VeWorld. The back-end can then validate the certificate, and use the signed address in from the certificate to identify the users wallet.

• Captcha verification -> For example if there is a /claim endpoint this should be secured with a ReCaptcha. This is to protect against scripted/bot attacks, as it ensures that the back-end APIs can only be used from the front-end of the dApp.

• CORS domains -> This is to ensure that the back-end API's can only be called with a request from the same domain. For example if the API is running at api.myapp.com and a request to it is made from api.fakeapp.com, it will be rejected.

• Rate limiting -> Depending on the design of the dApp a user will only be allowed to make a limited number of claims for rewards per day, per week. There are different strategies here, for example:

  • Inspecting the date-time when the users address last received a reward, and not allowing more claims for a time period after that. For example a user can't make another claim until 24hrs after their previously paid reward. This can be implemented in the back-end database or by reading the last reward event on-chain.

  • Determining the current round (week) and how many claims the user has submitted in that timeframe. Thus limiting the user to a fixed number of claims per week.

  • Using device identification techniques to uniquely identify the mobile device the user is using, and limiting the number of claims for rewards not just on address but also on device.

How Sustainable Actions are Verified

• AI based validation -> The prompts used to validate an image should be thoroughly tested to ensure that the AI is validating as expected. If the AI is used to extract data out of an image (e.g. A receipt) it should be tested to ensure that hallucinations are not occurring. The AI should be asked to produce a confidence score, if that is below a threshold the image could be flagged for manual verification.

• No unique identifier -> To verify a sustainable action there should be some indisputable evidence of it. For example a social media post, data from an external system, a receipt as proof of purchase or a date-time stamp. In the case of AI image verification, the AI should be prompted to recognise relevant data in the image that can be used for a uniqueness check.

Suspicious Behaviour & Ban List

dApps should have the means to identify suspicious behaviour within their dApp, for example rewards being paid every 10 seconds to accounts that have no other transaction history. DApps should have the means to ban accounts or entire devices from using their service.

Management of Private Keys

The distributor account private key should be secure within the dApp and not be able to be sniffed in the traffic the dApp generates. If the dApp is using back-end contracts or APIs to sign the reward transaction these should have a secure way of storing the private keys.

Device Fingerprinting

Farmers might attempt to install VeWorld (or your native app), multiple times on the same device, and use a different wallet per instance of the app. This is especially true of Android devices, where software exists to allow multiple instances of an app to be installed. A dApp should consider using tools such as FingerprintJS (or its paid version), to identify a users device, and ban the device rather than just the users account(s). If developing a native dApp, protections against multiple installs should be built into the dApp.

Other Strategies

• Management of funds -> The allocation the dApp receives from the DAO on a weekly basis is at risk if there are vulnerabilities within the dApp. The dApp owner if concerned about farmers should reduce the b3tr balance of the dApp by withdrawing funds to their treasury account and drip feeding it back to the dapp when needed. Once the concerns are alleviated this strategy can end. The dApp owner can also mitigate this risk by setting a portion of the weekly allocation for distribution and another portion as treasury funds. Treasury funds can be withdrawn at any time.

• Identify verification -> DApps can also offer login methods other to VeWorld, for example Google, Facebook, Twitter. In these cases dApp owners should consider validation of the users social media profiles, for example does the facebook profile have a complete profile, was the google account created in last 30mins. DApps could also consider sending verification emails.

• Progressive unlocking -> A new account in the dApp might have tigher rate limits and lower rewards. As the user continues to use the dApp they progressively unlock higher rate limits and higher rewards. This means an attacker has to spend more efforts to reach the higher rewards slowing their progress.

• Scaling Rewards by Demand -> This is a strategy to scale down user rewards in peek demands and scale them back up at quiet times. The goal is to make the weekly allocation a dApp received last the full week, but also guard against spikes in users (or bots) claiming rewards. One way to do this is to compute the average rewards per second since the start of the week, and project it forward to the end of the week, and see if above/below the dApps weekly budget. If above budget, the dApp can then scale down users rewards until back on track.

Conclusion

Stopping farmers is a difficult task and in some scenarios very difficult to achieve without impacting genuine users. Often the approach is to slow the farmers progress so that their effort/reward ratio is no longer worth it.

The proof will be stored on-chain in the form of an emitted event and will have the following JSON format:

{
   version: 2,
   description: 'The description of the action',
   proof: { 
      image: 'https://image.png', 
      link: 'https://twitter.com/tweet/1' 
   },
   impact: { 
      carbon: 100, 
      water: 200 
   }
}

Parameters

You will provide this proof as a parameter when calling the distribute rewards function in the X2EarnRewardsPool contract.

• proofTypes: an array with the proof types that you are providing. Eg: ["link", "image"]

• proofValues: an array with the values of the types provided in the previous array. Eg: ["https://twitter.com/tweet/1233121231", "https://whatever.com/image.png"]

• impactCodes: an array with the codes of impacts you are providing. Eg: ["water", "timber"]

• impactValues: an array with the values of the impacts provided in the previous array. Eg: [1000, 23]

• description: you can attach also a description to your action, it's optional.

When calling this function it is mandatory to provide at least proof or impact, if none of them is provided then the transaction will revert.

The transaction will revert also if something is wrong with the data you pass.

Examples

To provide proofs and impacts you need to distribute the rewards through the X2EarnRewardsPool contract with the following function:

import { ProviderInternalHDWallet, ThorClient, VeChainProvider, VeChainSigner } from "@vechain/sdk-network"
import { X2EarnRewardsPool } from "@vechain/vebetterdao-contracts"

const thor = ThorClient.fromUrl("https://mainnet.vechain.org")
const provider = new VeChainProvider(
  thor,
  new ProviderInternalHDWallet("your space separated mnemonic".split(" ")),
)
const rootSigner = await provider.getSigner()

// Call the method
const x2EarnRewardsPoolContract = thor.contracts.load(X2EarnRewardsPool.address.mainnet, X2EarnRewardsPool.abi, rootSigner as VeChainSigner)
const tx = await x2EarnRewardsPoolContract.transact.distributeRewardWithProof(
  APP_ID,
  amount,
  receiverAddress,
  ["link", "image"],
  ["https://link-to-proof.com", "https://link-to-image.com/1.png"],
  ["waste_mass"],
  [100],
  "User performed a sustainable action on my app",
)

await tx.wait()

import "./interfaces/IX2EarnRewardsPool.sol";

contract MyContract {
    function sendReward() onlyAdmin {
        // this declaration is needed because solidity has 
        // an issue with dynamic vs fixed-size arrays
        string[] memory proofTypes = new string[](1);
        proofTypes[0] = "link";
        
        string[] memory proofUrls = new string[](1);
        proofUrls[0] = action.proofUrl;
        
        string[] memory impactTypes = new string[](1);
        impactTypes[0] = "waste_mass";
            
        uint256[] memory impactValues = new uint256[](1);
        // let's pretend you have another function that calculates your impact
        impactValues[0] = calculateWasteMass(
            challenge.litterSize,
            challenge.litterCount
        );
        
        IX2EarnRewardsPool x2EarnRewardsPool = IX2EarnRewardsPool(x2EarnRewardsPoolAddress);
        
        // If distributeReward fails, it will revert
        x2EarnRewardsPool.distributeRewardWithProof(
            VBD_APP_ID,
            rewardAmount,
            receiver,
            proofTypes,
            proofUrls,
            impactTypes,
            impactValues,
            "User participated in a solo cleanup"
        );
    }
}

Proofs

You can attach proof of the user's sustainable action when you distribute the reward. The proof can be a link, video, photo, and text. You can provide more than one proof (eg: a photo and a link).

The current proof types supported are:

"image"
"link"
"text"
"video"

Impacts

Determining the environmental impact of each sustainable action will require the development of a set of criteria and metrics for each type of action.

Categories

1. Carbon Footprint Reduction Key: carbon Description: Measures the decrease in greenhouse gas emissions. Metric: Grams (g) of CO2 equivalent reduced or removed.

2. Resource Conservation Key: water (for water conservation), energy (for electricity conservation) Description: Assesses the reduction in the use of natural resources like water, electricity, and raw materials. Metric: Milliliters (ml) of water saved, watt-hours (Wh) of electricity saved.

3. Waste Reduction Key: waste_mass Description: Evaluates the decrease in waste generated and improves waste management. Metric: Grams (g) of waste diverted from landfills, number of items recycled.

4. Timber Conservation Key: timber Description: Measures the reduction in the use or waste of timber resources. Metric: Grams (g) of timber saved.

5. Plastic Reduction Key: plastic Description: Evaluates the decrease in the use or waste of plastic materials. Metric: Grams (g) of plastic saved or reduced.

6. Education Time Key: education_time Description: Measures the amount of time a user spends learning about a sustainability topic. Metric: Seconds spent learning.

7. Trees Planted Key: trees_planted Description: Tracks the number of trees planted as part of sustainability efforts. Metric: Number of trees planted.

8. Calories Burned Key: calories_burned Description: Measures the energy expenditure from physical activity or exercise, promoting health and sustainability. Metric: Calories (kcal) burned.

9. Sleep Quality Key: sleep_quality_percentage Description: Assesses the quality of sleep as a percentage, encouraging better health and productivity. Metric: Percentage (%) of sleep quality improvement.

10. Clean Energy Production Key: clean_energy_production_wh Description: Measures the amount of clean energy produced, contributing to sustainable energy solutions. Metric: Watt-hours (Wh) of clean energy generated.

The following are the impact codes you will need to use:

"carbon"
"water"
"energy"
"waste_mass"
"education_time",
"timber"
"plastic"
"trees_planted"
"calories_burned"
"sleep_quality_percentage"
"clean_energy_production_wh"

We ask each app to find a way to calculate the impact they are having based on the previously listed categories. If your app does not fit in any of the above categories please feel free to submit your own category and impact definition.

Deprecated template (version 1)

If no "version" field is found in the the json proof then you should consider it as version 1.

{
  "app_name": "cleanify",
  "action_type": "litter_picking",
  "proof": {
    "proof_type": "link",
    "proof_data": "https://x.com/TengMab95659/status/1814152547202195788"
  },
  "metadata": {
    "description": "@TengMab95659 picked up 8 small pieces of litter.",
    "additional_info": ""
  },
  "impact": {
    "waste_mass": "300",
    "biodiversity": "1"
  },
}

Deprecated impacts:

waste_items
people
biodiversity

The X2Earn Creator NFTs are integral to VeBetter DAO’s process for managing and validating new XApp submissions. These NFTs serve as an access key for creators, enabling them to submit their applications on-chain and engage with the VeBetter DAO endorsement process through VeChain node holders.

Overview

• Purpose: X2Earn Creator NFTs are used within VeBetter DAO to authorize new XApp submissions and provide access to the endorsers (VeChain node holders). These NFTs ensure that only vetted and verified creators can submit apps for consideration.

• Standard: Creator NFTs are non-transferable tokens compliant with the ERC721 standard, implemented using the OpenZeppelin (OZ) library.

Minting and Eligibility

• Minting Authority: Only the X2Earn App Review Panel has the authority to mint Creator NFTs. The panel grants these NFTs if they deem the app suitable, legitimate, and ready for the endorsement process within VeBetter DAO.

• Non-Transferability: Creator NFTs are non-transferable, meaning they cannot be sold or transferred to another user, ensuring that only the verified creator retains access.

Functionality and Permissions

• Submission Access: Once an app creator is granted a Creator NFT, they can submit their XApp on-chain for endorsement. This submission formally registers the app within the VeBetter DAO ecosystem, allowing it to seek endorsements from node holders.

• Additional NFTs for Team Members: After the initial on-chain submission, the XApp admin (creator) can mint up to two additional Creator NFTs for other team members. This provides extended access for specific collaborators without the need to undergo the entire verification process.

• Single NFT Limit: A user can hold only one Creator NFT at any time. However, if they are involved in multiple XApps, they only need one Creator NFT to submit additional XApps; a new NFT is not required for each project.

Blacklisting and Burn Mechanism

• Blacklisting Policy: If an XApp is blacklisted for any reason, and the creator is not associated with any other active XApp, their Creator NFT will be burned. This prevents creators of non-compliant or blacklisted apps from submitting new projects without re-approval.

• NFT Burn: The burning mechanism ensures that blacklisted creators cannot bypass VeBetter DAO’s review process by holding onto their Creator NFT. This policy enhances the integrity of the ecosystem by holding creators accountable for their submissions.

Key Points for Developers

• Token Standard: ERC721 (non-transferable)

• Minting Authority: X2Earn App Review Panel

• Max NFTs per User: One NFT per user, regardless of the number of XApps

• Additional NFTs: Admins can mint up to two extra NFTs for team members

• Burn Policy: Creator NFT is burned if the associated XApp is blacklisted and the user has no other active XApps

Ownership of a GM NFT with a level above Earth should be sufficient to prove personhood. The capital outlay to achieve these NFTs should be enough to discourage their usage in Sybil attacks and prove the investment deployed for better action to VeBetter DAO.

You have two testing environments: testnet and an instance of the blockchain running locally (a solo node).

Testing your app on testnet is more straightforward since all contracts are already deployed by us and you can use our testnet dApp to add apps, interact with smart contracts, and manage reward distribution.

Testing on solo will be a bit more complicated because you will need to deploy some mocked VeBetterDAO contracts by yourself, but we tried to make that easy as well.

Testnet

Use our testnet environment, running on vechain testnet network, to create apps, interact with smart contracts, and manage reward distribution.

• Go to https://dev.testnet.governance.vebetterdao.org

• Add an app

• Now you will need to get some B3TR tokens: claim them from the Faucet

• Deposit the B3TR tokens to your app balance so you can distribute them: go to your managed app page, and click "Deposit" in the app balance section

• To allow your contract to distribute the rewards you need to click the cogs icon to enter the Settings section of your app and add the address of your contract (that will call the distributeReward function) as a "Reward Distributor".

That's it, you are all set and can distribute rewards through your backend or smart contract.

If you need to simulate allocation rounds, go to the Admin section and press the "Start round" button. In testnet rounds last 10 minutes, but apart from this everything else is the same as mainnet.

Testnet contracts addresses:

"B3TR": "0xbf64cf86894Ee0877C4e7d03936e35Ee8D8b864F",
"B3TRGovernor": "0xDF5E114D391CAC840529802fe8D01f6bdeBE41eC",
"Emissions": "0x148d21032F4a7b4aeF236E2E9C0c5bF62d10f8EB",
"GalaxyMember": "0xCf73039913e05aa1838d5869E72290d2b454C1E8",
"TimeLock": "0x30ee94F303643902a68aD8A7A6456cA69d763192",
"Treasury": "0x039893EBe092A2D22B08E2b029735D211bfF7F50",
"VOT3": "0xa704c45971995467696EE9544Da77DD42Bc9706E",
"VoterRewards": "0x2E47fc4aabB3403037fB5E1f38995E7a91Ce8Ed2",
"X2EarnApps": "0xcB23Eb1bBD5c07553795b9538b1061D0f4ABA153",
"X2EarnRewardsPool": "0x5F8f86B8D0Fa93cdaE20936d150175dF0205fB38",
"XAllocationPool": "0x9B9CA9D0C41Add1d204f90BA0E9a6844f1843A84",
"XAllocationVoting": "0x5859ff910d8b0c127364c98E24233b0af7443c1c",
"B3TRFaucet": "0x5e9c1F0f52aC6b5004122059053b00017EAfB561"

Local node

Testing on the solo node (aka: local node running on your computer simulating VeChain blockchain) is a bit more complicated than testing on testnet, since you will need to deploy the VeBetterDAO contracts locally and interact with them to create your app, obtain the APP_ID, start an allocation round, vote, start round again, and add the reward distributor.

We recommend following the testnet path, but if you need to do it on the solo network you will need to mock a few VeBetterDAO contracts:

• B3TR token mock: you need a fake token to distribute

• X2EarnApps mock: you need a contract where to add your app, generate an APP_ID and add a reward distributor

• X2EarnRewardsPool mock: you need a contract to distribute the rewards

While the X2EarnRewardsPoolMock contract can be the exact same contract deployed on mainnet and testnet, the other two can be customized in order to have only the essential logic needed for running tests.

You can take a look at the mocked contracts in the X-App-Template repository, under the contracts/mocks folder.

After you added the mock contracts to your repository you should adjust the deploy script in a way that you will deploy and configure the mocked contracts only if you are deploying to the vechain_solo network.

Your script should look something like this:

import { ethers, network } from "hardhat";
import { Challenges, Cleanify, RolesManager } from "../../typechain-types";
import { networkConfig } from "@repo/config";
import { deployProxy } from "../helpers/upgrades";
import { faker } from "@faker-js/faker";

let REWARD_TOKEN_ADDRESS = "0xE5FEfcB230364ef7f9B5B0df6DA81B227726612b"; // mainnet address

export async function deploy(): Promise<{
    mySustainableContractAddress: string;
}> {
    console.log(
        `Deploying on ${network.name} (${networkConfig.network.defaultNodeUrl})...`
    );

    console.log(`Deploying my app contract...`);
    const MySustainableContract = await ethers.getContractFactory("MySustainableContract");
    const mySustainableContract = await MySustainableContract.deploy();
    await mySustainableContract.waitForDeployment();
    console.log(`Sustainable Contract deployed to ${await mySustainableContract.getAddress()}`);

    if (network.name === "vechain_solo") {
        console.log(`Deploying mock RewardToken...`);
        const RewardToken = await ethers.getContractFactory("B3TR_Mock");
        const rewardToken = await RewardToken.deploy();
        await rewardToken.waitForDeployment();
        REWARD_TOKEN_ADDRESS = await rewardToken.getAddress();
        console.log(`RewardToken deployed to ${REWARD_TOKEN_ADDRESS}`);

        console.log("Deploying X2EarnApps mock contract...");
        const X2EarnApps = await ethers.getContractFactory("X2EarnAppsMock");
        const x2EarnApps = await X2EarnApps.deploy();
        await x2EarnApps.waitForDeployment();
        console.log(`X2EarnApps deployed to ${await x2EarnApps.getAddress()}`);

        console.log("Deploying X2EarnRewardsPool mock contract...");
        const X2EarnRewardsPool = await ethers.getContractFactory(
            "X2EarnRewardsPoolMock"
        );
        const x2EarnRewardsPool = await X2EarnRewardsPool.deploy(
            deployer.address,
            REWARD_TOKEN_ADDRESS,
            await x2EarnApps.getAddress()
        );
        await x2EarnRewardsPool.waitForDeployment();
        console.log(
            `X2EarnRewardsPool deployed to ${await x2EarnRewardsPool.getAddress()}`
        );

        console.log("Adding app in X2EarnApps...");
        await x2EarnApps.addApp(deployer.address, deployer.address, "MySustainableApp");
        const appID = await x2EarnApps.hashAppName("MySustainableApp");

        console.log(`Funding contract...`);
        await rewardToken.approve(
            await x2EarnRewardsPool.getAddress(),
            ethers.parseEther("10000")
        );
        await x2EarnRewardsPool.deposit(ethers.parseEther("2000"), appID);
        console.log("Funded");

        console.log("Add MySustainableContract as distributor...");
        await x2EarnApps.addRewardDistributor(
            appID,
            await mySustainableContract.getAddress()
        );
        console.log("Added");

        console.log(
            "Set APP_ID and X2EarnRewardsPool address in Challenges contract..."
        );
        await mySustainableContract.setVBDAppId(appID);
        await mySustainableContract.setX2EarnRewardsPool(
            await x2EarnRewardsPool.getAddress()
        );
        console.log("Set");
    }
    
    return {
        mySustainableContract: await mySustainableContract.getAddress()
    };
}

That's it, you can now deploy your contracts locally/run tests where you simulate the VeBetterDAO contracts, your app added to the ecosystem, and tokens distribution.

To enhance the transparency of the VeBetterDAO platform and x2earn apps, following also the "dApp Tracker" proposal, we have developed a centralized reward distributor contract. This contract must be used by the apps to ensure that every transfer of a B3TR token related to a sustainable action is publicly tracked and accessible to the community.

You need to call this contract to distribute the rewards.

In this example, we assume that you are building a smart contract where users can submit some sustainable action that is being approved/rejected by some moderator. If the action is approved the user can claim his rewards. No backend is involved.

Your contract should look like this:

// SPDX-License-Identifier: MIT
pragma solidity 0.8.20;

// can find here: https://github.com/vechain/vebetterdao-contracts/tree/main/contracts/interfaces
import "./interfaces/IX2EarnRewardsPool.sol";

/**
 * Example contract with key functionality to interact with the x2Earn rewards pool
 * and distribute rewards.
 * You can customize this contract in the way 
 */
contract MySustainableAppContract {
    IX2EarnRewardsPool public x2EarnRewardsPool;
    bytes32 public VBD_APP_ID;
    
    // a dummy mapping pretending you have a way to track and 
    // validate user actions on chain.
    mapping(uint256 actionId => ActionStruct) public sustainableActions;
    mapping(uint256 actionId => bool) public rewardsClaimed;
    
    // You will need to setup the address of the X2EarnRewardsPool contract
    // and your APP_ID on VeBetterDAO
    constructor(IX2EarnRewardsPool _x2EarnRewardsPool, bytes32 _VBD_APP_ID) {
        x2EarnRewardsPool = _x2EarnRewardsPool;
        VBD_APP_ID = _VBD_APP_ID;
    }

    /**
     * @notice A function that allows a user to claim a reward for a specific
     * sustainable action that they performed.
     * 
     * IMPORTANT: the address of this contract must be set as a distributor 
     * of your APP in order to move funds from the X2EarnRewardsPool contract. 
     * You can set this on the VeBetterDAO governance app.
     */
    function claimReward(uint256 _actionId) external {
        // ... some code to check if the action is valid and user can claim

        // If distributeReward fails, it will revert
        x2EarnRewardsPool.distributeReward(
            VBD_APP_ID,
            actions[_actionId].rewardAmount,
            msg.sender, // this is the user calling the claimReward function
            "" // proof and impacts not provided
        );

        rewardClaimed[_actionId] = true;

        emit RewardClaimed(_actionId, msg.sender);
    }
}

Requirements

If you want to create an x2earn app it needs to have the following features:

• Be able to distribute B3TR tokens on the VeChain blockchain

• Be able to submit a proof (in JSON format) of the sustainable action the user was rewarded for

Bonus:

• Allow the user to connect with their wallet to your app

This guide provides instructions for setting up a project within the VeBetterDAO ecosystem. Your app will participate in weekly allocation rounds, receive B3TR tokens at the beginning of each round, and distribute these

Test Environment

Use our Test Environment to create a test app running in the VeBetterDAO ecosystem.

Distribute B3TR

Now that you have your app running in testnet and have some B3TR tokens deposited in your app's rewards pool you can connect a smart contract or a backend and distribute those funds to your users.

Proofs and Impacts

Every time you reward a user you also need to specify the reason, the proof of the user's action and the sustainability impact it had.

Resources

Have doubts? Check our additional resources specifically picked for you to speed up your development.

Submit App

When your app is ready submit it to VeBetterDAO and join the movement!

Security

As of the start of November the VeChain node holders, referred to as "endorsers," are serving as the primary decision-makers in determining which XApps are admitted to the VeBetter DAO ecosystem. Developers and innovators can engage with the ecosystem and submit their X2Earn applications through a structured process that includes community endorsement and voting.

Submission Process

To submit an app to the VeBetter DAO ecosystem, every project must first acquire a Creator NFT, which verifies the creator and allows them to participate in the endorsement process. Here’s how it works:

1. Acquiring the Creator NFT

   • Application Process: XApp creators begin by filling out a form on the VeBetter DAO platform, which initiates a background check to verify the team and the app’s legitimacy.

   • Alternative Paths: Creators can also apply for a grant through the VeChain Grants program. If successful, they will receive funding as well as a Creator NFT, which validates their project within the ecosystem.

2. On-Chain XApp Submission After receiving the Creator NFT, XApp creators can submit their app on-chain for endorsement consideration. This official submission registers the app on the VeBetter DAO platform, allowing it to seek endorsements from VeChain node holders.

3. Connecting with Endorsers Upon acquiring the Creator NFT, XApp creators gain access to the VeBetter DAO XApps Creators Discord server, where they can network with VeChain node holders who may endorse their app. This community platform provides opportunities for creators to present their app, build relationships with potential endorsers, and gain the necessary endorsement score to enter allocation rounds.

4. Endorsement and Funding Eligibility Once an app is submitted and endorsed with a cumulative score of 100, it will officially be added to the VeBetterDAO ecosystem. It will be eligible to be weekly funded with B3TR tokens as a result of the allocation rounds: you will compete against other apps to receive as many B3TR tokens as possible, with holders of the token that will vote for the app they think deserves it the most.

On-Chain App Submission Requirements

When asubmitting your app to VeBetterDAO you will need to provide 2 important information:

• Treasury address: this is the address where B3TR tokens will be sent in case you will need to withdraw some tokens from the received weekly allocations (eg: you need some B3TR for marketing, team shares, etc.). This address can be a multi-sig or a simple EOA, it's up to you.

• Admin address: this is the address that has superpowers for your app; it can update any details of the app, change the Treasury address, or move the ownership to another wallet. You can use the same wallet you use for the Treasury, another multi-sig, or a simple EOA as well.

Your APP ID

Once your app is added you will obtain an APP_ID that VeBetterDAO and other projects will use to recognize your app. You will also need to use your Admin address to add a Reward Distributor to distribute your rewards to the users. This is a simple address and it should belong to the contract or wallet that you will use to distribute the rewards. Be aware that this address can also withdraw funds, so protect its access correctly.

B3TR Allocations

You will receive your first B3TR tokens at least one week after joining VeBetterDAO, following the completion of at least one voting round. Therefore, you will need to address the scenario where people might see your app in VeBetterDAO and attempt to use it before you are able to distribute rewards.

Every app receives B3TR from weekly allocation rounds in a contract called X2EarnRewardsPool and those rewards are now configurable by the app admin. In fact, you can split allocated tokens between distributable rewards pool for your user and a treasury pool, withdrawal for operational needs. You also have the possibility to pause distribution anytime, this won't affect the reward pool unless you move funds to the app balance.

This dual-pool mechanism allows you to have more control over your distribution funds. You can manage these configurations directly from the app admin dashboard in the VeBetterDAO app. Or by interacting with our X2EarnRewardsPool contract.

Q&A

// Option 1: Refill your rewards pool with additional funds
// @param amount The amount of tokens to add to your rewards pool
X2EarnRewardsPool.increaseRewardsPoolBalance(bytes32 appId, uint256 amount)


// Option 2: Toggle rewards functionality on/off
// @param enable Set to false to disable rewards, true to enable
X2EarnRewardsPool.toggleRewardsPoolBalance(bytes32 appId, bool enable)

To aid in the development process, we've created several valuable resources:

VePassport is a system that allows dApps on VeChain to determine whether a wallet belongs to a bot or a real person. The dApps using this technology include, first and foremost, VeBetter DAO, which verifies the authenticity of wallets during voting. Other dApps within the VeBetter DAO ecosystem, often facing issues with fake accounts and Sybil attacks, can also access this information.

This decentralized identification framework enables a secure, Sybil-resistant environment that drives participation and promotes a more transparent, sustainable ecosystem.

Proof of Personhood

There are several modules that VePassport uses to determine if a wallet is a bot or if it belongs to a real user:

• Proof of Participation in the VeBetterDAO Ecosystem

• Proof of Investment

• Proof of Identity

• Whitelisting and Blacklisting

• Bot Signaling

In the current implementation to determine if a wallet is legitimate, several factors are considered: whether it is on the whitelist or blacklisted, and the number of actions performed within a specific time range, while Proof of Investment and Identity will be integrated with the next releases.

Apps can interact with VePassport to check if a user is a person (now or in a specific block number) or can call each module separately to only get the participation score, or if the user is KYCed, or if it's whitelisted, blackilsted or signaled as a bot by other apps.

VePassport is designed to be expanded in the future with new modules.

Proof of Participation

Users need to complete 3 Better actions within a 12-week period to be considered a person. This requirement encourages greater participation in the ecosystem and ensures users are active contributors to the DAO.

An action is defined as a reward that you receive from an app (e.g., receiving a reward for drinking coffee in a sustainable cup with Mugshot).

Every time a user engages with an app and receives a reward their passport accumulates points. The amount of points is determined by the security level of the app he interacted with. An app with a low security score is worth 100 points, medium is 200, high is 400, and none is 0.

Proof of Investment

Another way to verify a wallet’s legitimacy is through the GM NFT level that the wallet holds. If the address holds a GM NFT with a level higher than 1 then it indicates that the owner has made a significant investment, since upgrading levels on that NFT is not free, suggesting that the wallet is more likely to be genuine.

Whitelisting, Blacklisting, and Bot Signalling

X2earn apps can also flag a wallet as a bot or suspicious user. If a wallet receives enough signals to exceed a certain threshold, it will not be considered a real person.

Additionally, some authorized entities can blacklist or whitelist a wallet. Blacklisting might occur if a wallet is found to be part of a network of fake accounts. If a wallet is mistakenly blacklisted, it can request to be reinstated.

Similarly, a wallet can be added to the whitelist, especially if the user has completed a KYC (Know Your Customer) process, thereby ensuring that the account is legitimate.

Proof of Identity

Various levels of KYC (Know Your Customer) can be applied in the future, ranging from linking social profiles to full identity verification. This feature will remain optional, and will instantly provide layers of security and trust for user identities.

Delegation

To better increase the interoperability across the VeBetterDAO and VeChain ecosystem, VePassport offers the possibility to delegate your passport to other addresses.

You can even customize your passport by attaching to it other accounts you own.

Every person and contract can interact with VePassport to check if an address can be considered a person. Additionally, modules can be called separately, allowing a certain amount of flexibility to implement custom personhood checks.

In the following pages, you can browse each module's endpoints and learn how the VePassport personhood check is performed.

Authorized apps can signal addresses they ban on their platform (e.g., looters, bots, scammers), helping the DAO and other apps to recognize and protect against them.

VeBetterDAO or other selected apps can reset the signal counter if a user is wrongly identified as a bot.

Dashboard: https://vechain-energy.github.io/vebetterdao-signal-admin/

Endpoints

Other apps or contracts can interact with the Bot Signalling module through the following functions of the VePassport contract:

  interface IVeBetterPassport {
    ...
    function signalUser(address _user) external;
    function signalUserWithReason(address _user, string memory reason) external;
    function signaledCounter(address _user) external view returns (uint256);
    function signalingThreshold() external view returns (uint256);
    function appTotalSignalsCounter(bytes32 app) external view returns (uint256);
    ...
  }

Threshold

Any app can call the signaledCounter function to get how many times a user was signalled and can decide on their own how to interpret that value.

When calling the isPerson function though, the signalled counter will be compared to a threshold set in our contract, currently set to 2. For example, if the address was signalled more than 2 times, it will not pass the personhood check.

Snippet

The following is a snippet of how to signal addresses by using the vechain SDK.

import {
  ThorClient,
  ProviderInternalBaseWallet,
  VeChainProvider,
} from '@vechain/sdk-network';
import { ErrorDecoder } from 'ethers-decode-error';
import passportAbi from './passport.json' assert { type: 'json' };

// get passport contract with signer from a helper function
const passport = await getPassportContract();

// what to signal
const addressToSignal = '0x0000000000000000000000000000000000000000';
const reason = 'test';
console.log('Address to signal is', addressToSignal, 'for', reason);

// log current signal count
const [counter] = await passport.read.signaledCounter(addressToSignal);
console.log('Signals received for address are', counter);

// send a signal
const tx = await passport.transact.signalUserWithReason(
  addressToSignal,
  reason
);

console.log('Signal sent in tx', tx.id);

async function getPassportContract() {
  // config sender
  const privateKey =
    '0x09b76a9e3c0f154ca2c6f9b9580ad5f6771493866553df98b10c38ddce987847';
  const address = '0x00351f449190a9C2A41e6989c98fe5fC5eB50000';
  const wallet = new ProviderInternalBaseWallet([
    { privateKey: Buffer.from(privateKey.slice(2), 'hex'), address },
  ]);

  // connect to network
  const thor = ThorClient.at('https://mainnet.vechain.org');

  const provider = new VeChainProvider(
    // Thor client used by the provider
    thor,

    // Internal wallet used by the provider (needed to call the getSigner() method)
    wallet,

    // Enable fee delegation
    false
  );

  const signer = await provider.getSigner(address);

  // contract config
  const passport = thor.contracts.load(
    // VePassport address
    '0x35a267671d8EDD607B2056A9a13E7ba7CF53c8b3',

    // the interface definition
    passportAbi,

    // origin signing transactions
    signer
  );

  return passport;
}

Permission Request

Reach us to obtain the permissions to bot signaling.

To better increase the interoperability across the VeBetterDAO ecosystem VePassport offers the possibility to link multiple addresses under a single passport. All sustainable actions performed with the linked accounts will help increment the score of the passport and better represent your onchain identity.

A passport is the primary identity of the user (often a user's main VeWorld Wallet), and entities are additional wallet addresses that a user can attach to their passport. Users can link multiple entities (e.g., hardware wallets, account abstraction wallets, regular wallets) to a single passport. Once an entity is attached, its interactions, scores, and other attributes (e.g. whitelisted, bot signals etc.) are aggregated into the passport, reflecting the combined activity.

Currently, there is a limitation of a maximum of 5 entities per passport.

When linking a wallet, the scores are not immediately transferred. Instead, once the link is established, all of the linker’s scores, from the time of the link, are credited to the linked account. After the wallet addresses are linked, only the main account — the passport address — retains the right to vote.

Endpoints

  interface IVeBetterPassport {
  ...
    function linkEntityToPassportWithSignature(address entity, uint256 deadline, bytes memory signature) external;
    function linkEntityToPassport(address passport) external;
    function acceptEntityLink(address entity) external;
    function removeEntityLink(address entity) external;
    function denyIncomingPendingEntityLink(address entity) external;
    function cancelOutgoingPendingEntityLink() external;
    
    function isPassport(address user) external view returns (bool);
    function isPassportInTimepoint(address user, uint256 timepoint) external view returns (bool);
    
    function isEntity(address user) external view returns (bool);
    function isEntityInTimepoint(address user, uint256 timepoint) external view returns (bool);
  ...
  }

The following are the roles available in the VePassport contract, with their functionality and current assignees.

As a VeChain Node holder, you have unique opportunities to enhance your participation in the ecosystem. By linking your VeChain Node to a Galaxy Member (GM) NFT, you can unlock additional rewards, boost your GM NFT level, and significantly increase your influence in governance.

This guide explains how VeChain Node holders can link their nodes to GM NFTs, the benefits of doing so, and the steps to get started.

Why Link Your VeChain Node to a GM NFT?

Linking your VeChain Node to a GM NFT provides multiple advantages:

1. Unlock Free Level Upgrades:

   • Your node's type determines the free upgrade level of your GM NFT.

   • Higher levels increase your voter rewards which in return increases your influence in governance.

2. Boost Voter Rewards:

   • Higher GM NFT levels provide multipliers for voter rewards.

   • Multiplier percentages increase with GM NFT levels, enhancing the value of your votes.

3. Dynamic Benefits:

   • If your node level is upgraded, the GM NFT's level is also upgraded dynamically.

   • Nodes can be detached and reassigned as needed.

VeChain Nodes and Free Upgrade Levels

When you link a VeChain Node to a GM NFT, the NFT receives a free upgrade based on the node type: