Vebetterdao

VeBetterDAO Skill

CRITICAL RULES

1. Read reference files FIRST. When the user's request involves any topic in the reference map below, read those files before doing anything else — before writing code, before making decisions. Briefly mention which files you are reading so the user can confirm the skill is active (e.g., "Reading VeBetterDAO reference..."). 2. Information priority for VeChain topics: (a) Reference files in this skill — always the primary source. (b) VeChain MCP tools — use @vechain/mcp-server for on-chain data, transaction building, and live network queries; use Kapa AI MCP for VeChain documentation lookups. (c) Web search — only as a last resort, and only for topics NOT covered in the reference files. 3. Prefer working directly in the main conversation for VeChain tasks. Plan mode and subagents do not inherit skill context and may fall back to web search instead of using reference files. 4. After compaction or context loss, re-read this SKILL.md to restore awareness of the reference map and operating procedure before continuing work.

Scope

Use this Skill for VeBetterDAO ecosystem development:

• X2Earn sustainability app development
• B3TR and VOT3 token integration
• Reward distribution (smart contract, hybrid, backend-only patterns)
• Sustainability proofs and impact codes
• App submission process to VeBetterDAO
• Governance: VeVote, proposals, voting, quadratic funding, allocation rounds
• Navigators: delegation, staking, freshness/intent multipliers, slashing
• B3MO Quests: quest creation, invitations, joining/leaving, claims, refunds, and indexer/frontend flows

Operating procedure

1. Clarify before implementing

When the user's request is ambiguous, ask before building. Key questions:

• Which reward distribution pattern? (smart contract / hybrid / backend-only)
• Mainnet or testnet deployment?
• Does the app already have VeBetterDAO integration?

2. Implement with VeChain-specific correctness

• Network: always explicit (mainnet/testnet/solo)
• Tokens: B3TR for rewards, VOT3 for governance voting
• Use correct contract addresses for the target network

3. Verify and deliver

A task is not complete until all applicable gates pass:

1. Code compiles — no build errors 2. Tests pass — existing tests still pass; new logic has test coverage 3. Risk notes documented — any token-transfer or governance implications are called out

Reference files

Read the matching files BEFORE doing anything else. See Critical Rules above.

• VeBetterDAO: references/vebetterdao.md — read for X2Earn, B3TR, sustainability, rewards, VeBetterDAO, impact codes, app submission.
• Governance: references/governance.md — read for VeVote, governance, voting, VOT3, proposal, steering committee, quadratic funding, allocation rounds.
• B3MO Quests: references/b3mo-quests.md — read for B3MO quests, quests, b3mo-quests, B3TRChallenges, SplitWin, MaxActions, quest invite, join quest, leave quest, claim prize, claim refund, quest indexer.
• Contracts: tokens & apps: references/contracts-tokens-apps.md — read for B3TR, VOT3, Emissions, XAllocationVoting, XAllocationPool, X2EarnRewardsPool, X2EarnApps, X2EarnCreator, DBAPool, endorsement, reward distribution.
• Contracts: governance & identity: references/contracts-governance-identity.md — read for B3TRGovernor, proposals, VoterRewards, GalaxyMember, Treasury, TimeLock, RelayerRewardsPool, GrantsManager, B3TRMultiSig, VeBetterPassport, signaling, entity linking, upgradeability.
• Navigators: references/navigators.md — navigator, navigators, delegation, staking, slashing, NavigatorRegistry, freshness multiplier, governance intent multiplier, navigator fee, citizen voting.

VeBetterDAO B3MO Quests

When to use

Use when the user asks about: B3MO quests, quests, /b3mo-quests, B3TRChallenges, SplitWin, MaxActions, quest invitations, joining/leaving/declining quests, claim/refund flows, quest indexer endpoints, or the B3MO quests frontend.

What are B3MO Quests?

B3MO Quests are peer-to-peer or sponsored competitions where users complete X2Earn app actions to win B3TR.

Naming rule: call the feature B3MO Quests or quests in prose and user-facing copy. challenge only appears where it is still the technical contract/API/code name, such as B3TRChallenges, getChallengeStatus, or /api/v1/b3tr/challenges.

Two core modes:

• MaxActions: capped participant pool; top scorer(s) win the pool.
• SplitWin: sponsored-only, uncapped joins; first users reaching the threshold claim fixed prize slots.

Quest kind:

• Stake: participants put up stake; winners/refunds depend on settlement.
• Sponsored: creator funds prize pool; users join without staking.

Visibility:

• Public: discoverable and joinable while pending.
• Private: join via invitation.

Core Contract

• Contract: B3TRChallenges
• Interface: IChallenges
• Types library: ChallengeTypes
• Frontend config address commonly exposed as challengesContractAddress
• Frontend ABI usually comes from B3TRChallenges__factory

Key statuses:

• Pending: created, joinable/acceptable, not started.
• Active: started; participants can accumulate actions.
• Completed: settled; winners/refunds can claim depending on mode.
• Cancelled: creator cancelled before activation.
• Invalid: quest could not activate, usually because constraints were not met.

Important view functions:

• getChallenge(id): full on-chain quest struct/view.
• getChallengeStatus(id): preferred computed status; reflects time-based transitions without syncChallenge.
• getChallengeParticipants(id): joined users.
• getChallengeInvited(id): invited users.
• getChallengeDeclined(id): users who declined.
• getChallengeWinners(id): winners for settled or SplitWin claims.
• getChallengeSelectedApps(id): X2Earn apps whose actions count.
• getParticipantStatus(id, account): None, Invited, Declined, Joined.
• isInvitationEligible(id, account): whether an account can accept/re-accept.
• isSplitWinWinner(id, account): whether account already won a SplitWin slot.
• getParticipantActions(id, participant): live action count.
• maxParticipants(): default max for MaxActions.
• minBetAmount(): minimum stake in wei.

Important nuance: after ChallengeLeft, getParticipantStatus returns None, not a stored Left state. To detect users who left, consult the ChallengeLeft event or an indexer record derived from it.

Lifecycle Events

All lifecycle events use challengeId as the first indexed topic because this is the contract-level identifier.

• ChallengeCreated: indexed creator and endRound; new quest and metadata.
• SplitWinConfigured: SplitWin config, emitted after creation.
• ChallengeInviteAdded: indexed invitee; private invitation.
• ChallengeJoined: indexed participant; user joined.
• ChallengeLeft: indexed participant; user left before start.
• ChallengeDeclined: indexed participant; invitee declined.
• ChallengeCancelled: creator cancelled pending quest.
• ChallengeActivated: pending to active.
• ChallengeInvalidated: pending to invalid.
• ChallengeCompleted: active to completed, includes settlement data.
• ChallengePayoutClaimed: indexed account; MaxActions payout claimed.
• ChallengeRefundClaimed: indexed account; cancelled/invalid refund claimed.
• SplitWinPrizeClaimed: indexed winner; SplitWin slot prize claimed.
• SplitWinCreatorRefunded: indexed creator; creator reclaimed unclaimed SplitWin slots after end.

Settlement and Claim Rules

Settlement modes:

• None: no settlement yet.
• TopWinners: best scorers claim prize.
• CreatorRefund: creator recovers pool.
• SplitWinCompleted: SplitWin completed after slots are claimed or reclaimed.

Frontend/domain flags commonly derived from raw state:

• canJoin: pending, public, not joined, not creator, not at participant limit.
• canAccept: pending invite or eligible invitee, not at limit. Declined users may re-accept if still eligible.
• canComplete: MaxActions active quest past endRound, creator or joined participant.
• canClaim: MaxActions completed quest where joined participant has bestScore, or creator refund settlement applies.
• canClaimSplitWin: SplitWin active, joined, in time window, actions >= threshold, slots left.
• canClaimCreatorSplitWinRefund: SplitWin creator, current round after endRound, slots left, creator refund not yet claimed.
• canRefund: cancelled or invalid quest; for Stake, joined users refund; for Sponsored, creator refunds.

Wei boundary: stakeAmount, totalPrize, and prizePerWinner are wei on-chain. Convert with formatEther at frontend boundaries. threshold and bestScore are action counts, not B3TR amounts.

Frontend / Indexer Pattern

Common route: /b3mo-quests.

Recommended data split:

• List sections use indexer endpoints for pagination and segmentation.
• Detail views can still use direct contract calls plus event scans when immediate post-transaction freshness matters.
• Contract multicall enriches indexer quest IDs with live computed status, participant status, invitation eligibility, winner state, action counts, and claim flags.

Typical indexer endpoints:

• GET /api/v1/b3tr/challenges?status=...: public quests by status.
• GET /api/v1/b3tr/users/{wallet}/challenges?filter=...: wallet-scoped quest sections.

Typical wallet filters:

• NeededAction: invites, claimable, finalizable, reclaimable.
• MyChallenges: user-created or participating current quests.
• OpenToJoin: joinable quests.
• OthersActive: active public/social discovery quests.
• History: terminal quests plus left/declined current quests.

After write transactions, invalidate all quest query keys and schedule delayed refetches to catch indexer/event lag.

UX and Copy Conventions

• User-facing copy should say B3MO Quest(s) or Quest(s).
• Avoid saying "challenge" in product copy, docs headings, and feature descriptions.
• Keep challenge only for existing contract/API/code identifiers.
• Status labels should come from a shared helper, not handwritten string formatting.
• Action buttons should be driven by domain flags (canJoin, canAccept, canClaim, etc.), not duplicated UI logic.

Implementation Rules

• Prefer getChallengeStatus(id) over stored struct status for read paths.
• Keep event-derived states when the contract does not store them directly, especially users who left and claim history.
• For invited users leaving a pending quest, leave + decline may need to be chained so the user does not remain invitation-eligible.
• Do not format action counts as token amounts.
• Preserve fast post-transaction UX with broad invalidation plus delayed refetches.

VeBetterDAO Contracts — Governance & Identity

When to use

Use when the user asks about: B3TRGovernor, proposals, VoterRewards, GalaxyMember, Treasury, TimeLock, RelayerRewardsPool, NavigatorRegistry, GrantsManager, B3TRMultiSig, VeBetterPassport, signaling, entity linking, delegation, contract upgradeability, or UUPS proxy pattern.

Full source: github.com/vechain/vebetterdao-contracts Auto-generated docs: vechain.github.io/vebetterdao-contracts

---

B3TRGovernor (V11)

Main governance contract. Community creates proposals, deposits VOT3, votes with quadratic voting, executes through TimeLock, and (V11) pays out an on-chain implementation cost after delivery is confirmed. V11 added the Community Execution Framework on top of V10's navigator governance voting and relayer integration.

V10 storage: INavigatorRegistry navigatorRegistry, IRelayerRewardsPool relayerRewardsPool, mapping(uint256 => uint256[]) proposalsForRound (populated at proposal creation).

V11 storage additions: proposalMaxBudget, proposalPayee, proposalDescription, proposalImplementationDiscussion, proposalContributors, proposalPayeesFinalized, proposalPaid, proposalDevelopmentState, maxContributorsPerProposal (currently 20, no runtime setter).

ProposalState enum (V11): adds InDevelopment and Completed after Executed.

V10 events: NavigatorGovernanceVoteCast, NavigatorGovernanceVoteSkipped.

V11 events: ProposalBudgetSet(proposalId, maxBudget), ProposalInDevelopment(proposalId), ProposalInDevelopmentDetails(proposalId, payee, description, implementationDiscussion), ProposalContributorsSet(proposalId, contributors), ProposalCompleted(proposalId), ProposalPayoutClaimed(proposalId, payee, amount), ProposalDevelopmentStateReset(proposalId).

V11 errors: InvalidPayeeAddress, MissingProposalBudget, TooManyContributors, PayeesAlreadyFinalized, PayoutAlreadyClaimed, NotReadyToClaim, UnauthorizedCommunityExecution.

V11 Treasury role: Governor must hold Treasury.GOVERNANCE_ROLE to forward claimPayout via Treasury.transferB3TR(payee, maxBudget) — granted as part of the V11 upgrade.

V10 `castNavigatorVote` skip-or-vote flow: 1. Navigator dead at snapshot → revert NotDelegatedToNavigator 2. Navigator dead NOW → skip via pool.reduceUserGovernanceVote, emit NavigatorGovernanceVoteSkipped 3. Navigator alive + decision set → vote normally 4. Navigator alive + no decision + skip window (720 blocks before deadline) → skip 5. Navigator alive + no decision + skip window not reached → revert GovernanceSkipWindowNotReached

Proposal types: STANDARD (0) and GRANT (1) with type-specific thresholds.

Integrates with VeBetterPassport for voter identity verification. Logic stored in external libraries (GovernorClockLogic, GovernorConfigurator, GovernorDepositLogic, GovernorFunctionRestrictionsLogic, GovernorProposalLogic, GovernorQuorumLogic, GovernorStateLogic, GovernorVotesLogic).

VoterRewards (V7)

Calculates and distributes rewards to voters based on voting power and Galaxy Member NFT levels. V7 added rewards multipliers (freshness + governance intent) and navigator fee deduction.

V7 storage: 5 Checkpoints.Trace208 for multiplier values (freshnessMultiplierTier1/2/3, intentMultiplierForAgainst, intentMultiplierAbstain), INavigatorRegistry navigatorRegistry.

V7 fee flow: Navigator fee deducted first from gross reward (citizens only, → NavigatorRegistry escrow), then relayer fee from remainder (auto-voters + citizens, → RelayerRewardsPool). CLAIM action registered for both.

Separate GM rewards pool (v5+). Relayer fee integration (v6). Navigator fees + multipliers (v7).

GalaxyMember (NFT)

ERC-721 with level progression, node attachment, and voting rewards multiplier.

V6 replaced node management with Stargate NFT integration.

Treasury

Manages DAO assets. Receives emissions + unallocated funds.

All transfers require GOVERNANCE_ROLE and contract must be unpaused.

Transfer limits (per operation, governance-updatable): 200,000 VET, 200,000 B3TR, 3,000,000 VTHO, 50,000 VOT3. Cannot transfer non-native or non ERC-721/ERC-20 tokens.

TimeLock

Executes governance actions from B3TRGovernor with a mandatory time delay. B3TRGovernor should be the sole proposer and executor.

RelayerRewardsPool (V3)

Manages rewards for relayers performing auto-voting and navigator citizen voting. V3 added per-user skip tracking and governance action support.

V3 storage: activeProposalsForRound[roundId], userAllocationVoteReduced[roundId][user], userGovernanceVoteReduced[roundId][user][proposalId], userClaimReduced[roundId][user].

NavigatorRegistry (V1)

UUPS upgradeable contract managing navigator registration, citizen delegation, voting preferences, fees, slashing, and lifecycle. Facade with 6 external libraries. Staked B3TR is converted to VOT3 under the hood and counts as the navigator's voting power (checkpointed via Checkpoints.Trace208). NavigatorRegistry self-delegates on VOT3 during initialization.

Storage: Checkpoints.Trace208 totalDelegatedCitizens, mapping(address => Checkpoints.Trace208) stakedAmount (checkpointed for snapshot voting power), mapping(address => uint256) navigatorCitizenCount, fee escrow per navigator per round.

Libraries: NavigatorStakingUtils, NavigatorDelegationUtils, NavigatorVotingUtils, NavigatorFeeUtils, NavigatorSlashingUtils, NavigatorLifecycleUtils.

GrantsManager

Milestone-based grant distribution.

B3TRMultiSig

Multi-signature wallet requiring multiple owner confirmations (max 50 owners).

VeBetterPassport

Sybil resistance contract. Determines if a wallet is a real person based on participation score, blacklisting, GM holdings, and entity linking. Used by XAllocationVoting and B3TRGovernor for voter eligibility.

Core identity checks:

Participation scoring:

Entity linking (link multiple wallets to one passport):

Delegation (delegate personhood to another address):

Signaling (flag suspicious users):

B3TRProxy

EIP-1967 upgradeable proxy. Delegates all calls to the current implementation address. Read implementation via storage slot 0x360894a13ba1a3210667c828492db98dca3e2076cc3735a920a3ca505d382bbc.

---

Contract Upgradeability

All upgradeable contracts use UUPS proxy pattern with ERC-7201 storage layout.

B3TRGovernor and NavigatorRegistry store logic in external libraries. To upgrade library logic: deploy new library → deploy new implementation linking the library → upgradeToAndCall.

VeBetterDAO Contracts — Tokens & X2Earn Apps

When to use

Use when the user asks about: B3TR, VOT3, Emissions, XAllocationVoting, XAllocationPool, X2EarnRewardsPool, X2EarnApps, X2EarnCreator, DBAPool, token minting, voting rounds, app submission, endorsement, reward distribution, or impact tracking.

Full source: github.com/vechain/vebetterdao-contracts Auto-generated docs: vechain.github.io/vebetterdao-contracts

---

Contract Map

Emissions ──distribute()──> XAllocationPool + VoterRewards + Treasury + GalaxyMember
                                  │                 │
                    claim()       │    registerVote()│    claimReward()
                         ▼        │                 ▼
               X2EarnRewardsPool  │          VoterRewards
                    │             │                 │
   distributeReward()             │         claimReward()
                    ▼             │                 ▼
               Users (B3TR)       │          Voters (B3TR)
                                  │
                    XAllocationVoting ◄── VOT3 holders vote
                                  │
                    B3TRGovernor ──queue()──> TimeLock ──execute()──> Treasury

All upgradeable contracts use UUPS proxy pattern with ERC-7201 storage layout.

---

B3TR (ERC-20 Token)

Capped ERC-20 token. 1B total supply over 12 years.

Key function: tokenDetails() — returns name, symbol, decimals, totalSupply, cap in one call.

VOT3 (Governance Token, V2)

ERC-20 with voting power. Obtained by converting B3TR 1:1. V2 added NavigatorRegistry integration for delegation lock.

V2 delegation lock: _update() enforces balanceOf(from) - amount >= NavigatorRegistry.getDelegatedAmount(from). VOT3 stores only the registry address — no mapping, no role grant. balanceOf() returns full balance including delegated.

Roles: UPGRADER_ROLE, PAUSER_ROLE.

Emissions

Manages periodic B3TR distribution across XAllocations, Vote2Earn, Treasury, and GM pool with cycle-based decay.

XAllocationVoting (V9)

Periodic voting rounds for allocating funds to X2Earn apps. Uses quadratic funding with VOT3 voting power at round start. V9 added navigator citizen voting, freshness multiplier, and external library architecture.

V9 freshness: countVote() computes XOR fingerprint of voted app IDs via FreshnessUtils, applies freshness multiplier from VoterRewards checkpoints to reward weight (not voting power).

V9 events: NavigatorVoteSkipped(citizen, navigator, roundId), FreshnessMultiplierApplied.

Integrates with: X2EarnApps, VoterRewards, Emissions, VeBetterPassport, NavigatorRegistry, B3TRGovernor, RelayerRewardsPool.

XAllocationPool

Distributes weekly B3TR emissions to X2Earn apps based on voting results. Apps claim at round end.

Unallocated amounts (apps that didn't claim, rounding remainders) are sent to Treasury.

X2EarnRewardsPool

Reward pool for X2Earn apps to distribute B3TR to users for sustainable actions.

Storage maps app IDs to: available funds, rewards pool balances, enabled status, pause state.

X2EarnApps

Manages X2Earn application lifecycle: submission, endorsement, eligibility, admins/moderators/creators, reward distributors, and metadata.

App submission & management:

Endorsement system (V8 — flexible, partial points):

Query helpers: isEligible(appId, timepoint), isEligibleNow(appId), isBlacklisted(appId), isAppUnendorsed(appId), isAppAdmin(appId, addr), isAppModerator(appId, addr), isRewardDistributor(appId, addr), isCreatorOfAnyApp(addr), gracePeriod(), cooldownPeriod().

Limits: MAX_MODERATORS, MAX_REWARD_DISTRIBUTORS, MAX_CREATORS per app.

X2EarnCreator (NFT)

Non-transferable ERC-721 for VeBetterDAO creators. One per address.

Blocks all transfers (transferFrom reverts). Roles: MINTER_ROLE, BURNER_ROLE, PAUSER_ROLE.

DBAPool (Dynamic Base Allocation)

Distributes surplus B3TR from XAllocationPool to eligible apps using merit-capped flat distribution.

Role: DISTRIBUTOR_ROLE.

Governance (VeVote & VeBetterDAO)

When to use

Use when the user asks about: voting, proposals, steering committee elections, VOT3 governance, on-chain voting mechanisms.

Two Governance Systems

---

VeVote (Protocol Governance)

On-chain governance platform where Validators and Node holders vote on proposals. All votes are recorded on-chain (tamper-proof, publicly verifiable).

Proposal Types

• Steering Committee Voting -- Election of the Board of Steering Committee
• All Stakeholders Voting -- Protocol changes (e.g., VIP-253 Hayabusa upgrade)

Voting Power

Weighted by Stargate NFT tier level (highest to lowest):

Mjolnir X → Thunder X → Strength X → VeThor X → Mjolnir → Thunder → Strength → Flash → Lightning → Dawn

Voting units in the contract are scaled by 100 to avoid underflow (e.g., 150 = 1.5x).

Voting Rules

• Total voting power applied to the option you select
• One vote per wallet per proposal, cannot be changed
• Options: For, Against, Abstain
• Power calculated at the moment of vote (not at proposal start)

Delegation

Via Stargate NFT Node Manager feature: an NFT owner assigns a secondary wallet that gains full voting power for managed NFT(s).

Contract Address

Developer Resources

• Monorepo: github.com/vechain/vevote -- packages/contracts/ + apps/frontend/
• Legacy contracts: github.com/vechain/vevote-contracts
• Stack: Solidity + Hardhat (contracts), React + Vite (frontend), VeChain Kit (wallet)

---

VeBetterDAO Governance

Uses OpenZeppelin Governor pattern (AccessControl + UUPSUpgradeable).

Voting Token: VOT3

• Obtained by swapping B3TR at 1:1 ratio (auto-delegates to holder on receipt)
• Minimum 1 VOT3 to participate in governance
• See vebetterdao.md for B3TR/VOT3 token details and contract addresses

Proposal Requirements

• Must hold a GM Moon NFT (level 2+)
• Must create a Discourse thread at least 3 days before submitting

Proposal Types

• Actionable: triggers on-chain action (treasury transfer, contract call)
• Non-Actionable: expresses direction/idea without immediate on-chain execution

Governance Proposals

1. Proposer creates proposal with VOT3 deposit (V11 propose takes 7 args incl. maxBudget for the optional B3TR implementation cost; pass 0 to skip the community-execution flow) 2. Deposit threshold: 2% of total B3TR supply must be deposited in VOT3 → temperature check (capped at 5M VOT3) 3. If threshold reached before waiting period ends → proposal becomes active 4. Voting period opens; quorum: 30% of total VOT3 supply (FOR + AGAINST + ABSTAIN all count) 5. If quorum met and "yes" > "no" → queued to TimeLock → executed after delay 6. After Executed (or Succeeded for non-actionable) → V11 Community Execution flow takes over (see section below)

Deposits count as allocation voting power: locked VOT3 deposits are included in the XAllocation snapshot and grant voting power in allocation rounds even while locked.

Community Execution Framework (V11)

Standard proposals with maxBudget > 0 carry an on-chain B3TR implementation cost that is paid out after delivery. Grants are NOT in this flow — they use milestone payouts via proposeGrant.

Lifecycle (V11 states):

Pending → Active → Succeeded → Queued → Executed → InDevelopment → Completed → (Paid)
                  ↘ Defeated / DepositNotMet / Canceled

Key entrypoints on `B3TRGovernor` v11:

Funds flow: maxBudget is a commitment, not an escrow. B3TR stays in Treasury until claimPayout, which calls Treasury.transferB3TR(payee, maxBudget). The Governor must hold Treasury.GOVERNANCE_ROLE (granted as part of the V11 upgrade).

Contributors: contributors[] is an on-chain string array (GitHub/X handles or URLs) for attribution only, capped at maxContributorsPerProposal (currently 20). The single payee receives the full budget — distribution to contributors happens off-chain.

Events: ProposalBudgetSet, ProposalInDevelopment, ProposalInDevelopmentDetails, ProposalContributorsSet, ProposalCompleted, ProposalPayoutClaimed, ProposalDevelopmentStateReset.

Key errors: InvalidPayeeAddress, MissingProposalBudget, TooManyContributors, PayeesAlreadyFinalized, PayoutAlreadyClaimed, NotReadyToClaim, UnauthorizedCommunityExecution.

Allocation Rounds

• Weekly rounds where VOT3 holders vote on X2Earn app funding
• 100% vote-based allocation (no base allocation; base allocation % = 0 since Jan 2025)
• Allocation cap: 20% per app (ensures at least 6 apps participate)
• Quadratic Funding formula: allocation proportional to (sum of sqrt(votes))^2, emphasizing number of distinct supporters over vote size. Admins can disable QF (switches to linear; takes effect next round)
• Quorum: 1% of total VOT3 supply. If not met, distribution still occurs using last valid round's vote percentages. New apps in a failed round only receive base allocation (currently 0%)
• Snapshot: VOT3 holdings and completed actions are snapshotted at round start; changes after that don't count
• Voting: one vote per user per round; can split across multiple apps (e.g., 30 VOT3 to app A, 70 to app B)
• Distribution trigger: claim() is public — anyone can call it. VeBetterDAO team runs a scheduler to trigger at each new round
• Unallocated/unclaimed funds go to Treasury

Vote Delegation

• Auto-delegation enabled: converting B3TR → VOT3 or receiving VOT3 auto-delegates to your address
• Important for smart contracts: auto-delegation does NOT work for contracts; if a contract receives VOT3 and wants to participate in governance, it must call delegate() manually (one-time)

Voter Rewards

• Vote2Earn Pool: Rewards all participants proportionally to VOT3 balance (linear since round 23; quadratic rewarding disabled)
• GM Rewards Pool: 5% of weekly emissions → voters with GM NFT (Moon level 2+), weighted by GM NFT reward weight
• Participation in both governance proposals and XAllocation votes counts for rewards

GM NFT Levels

Upgradeable Governance Parameters

• Voting Period: must equal or be shorter than Emissions cycle
• Quorum: 30% of total VOT3 supply
• Deposit Threshold: 2% of total B3TR supply (in VOT3), capped at 5M VOT3
• Voting Threshold: minimum 1 VOT3 to vote
• Minimum Voting Delay: 3 days (PENDING → active)
• Timelock Minimum Delay: wait time before execution after queuing
• Function Restrictions: can enable/disable whitelist of callable contract functions
• Allocation Cap: 20% max per app
• Base Allocation %: 0% (currently all vote-based)
• `maxContributorsPerProposal` (V11): cap on V11 contributors array — currently 20, set at V11 upgrade, no runtime setter (changing requires a Governor upgrade)

---

VePassport (Voting Eligibility)

Verifies wallet authenticity for VeBetterDAO allocation round voting. Requires 3 sustainable actions in the last 12 rounds.

Navigators (Delegation & Multipliers)

When to use

Use when the user asks about: navigators, delegation, navigator staking, freshness multiplier, governance intent multiplier, navigator fees, slashing, NavigatorRegistry, or professional voting delegates.

For full implementation detail, use the dedicated vebetterdao-navigators skill.

Overview

Navigators are professional voting delegates who stake B3TR to vote on behalf of citizens in both allocation rounds and governance proposals. The feature ships in two phases (released together):

1. Rewards Multipliers — freshness (allocation) + governance intent multipliers that adjust reward weight 2. Navigator Delegation System — staking, delegation, voting, fees, slashing, lifecycle

Rewards Multipliers

Multipliers adjust reward weight only — on-chain voting power is never modified. Scale: basis points (10000 = 1x). Stored as Checkpoints.Trace208 in VoterRewards.

Freshness Multiplier (Allocation Voting)

Applied in RoundVotesCountingUtils.countVote() via FreshnessUtils library. XOR fingerprint of voted app IDs detects changes.

First-time voters get x3. Citizens inherit navigator's freshness.

Governance Intent Multiplier (Proposal Voting)

Applied in GovernorVotesLogic before registerVote(). Per-proposal, independent.

Citizens inherit navigator's decision multiplier. Freshness scales allocation reward weight; intent scales governance reward weight. GM is not stacked with them — when the GM pool is funded (v5+ live config), GM accumulates its own separate per-voter weight claimed against the GM pool, independent of allocation/governance reward weight.

Navigator System

Registration & Staking

• Permissionless — stake minimum 50,000 B3TR in NavigatorRegistry
• Staked B3TR is converted to VOT3 under the hood — counts as navigator's voting power (checkpointed)
• NavigatorRegistry self-delegates on VOT3 during initialization; per-navigator amounts queried via getStakedAmountAtTimepoint
• 10:1 delegation ratio: stake >= 10% of total delegated VOT3
• Max stake: 1% of circulating VOT3 (enforced at deposit only)
• On slash/withdraw: VOT3 converted back to B3TR before transfer
• On-chain reports mandatory at least once every 2 rounds

Delegation

• Citizens delegate specific VOT3 amount (not full balance) — stays in wallet, but locked
• VOT3 reads lock from NavigatorRegistry (getDelegatedAmount) — no mapping on VOT3
• One navigator per citizen, snapshotted at round start
• Partial undelegation allowed (takes effect next round)
• No personhood check to delegate. Personhood validated at vote time (snapshot); non-person citizens are skipped
• Citizens can't vote manually while delegated
• Auto-voting disabled on delegation

Voting

• Allocation: XAllocationVoting.castNavigatorVote(citizen, roundId) — navigator's custom percentages (basis points, sum to 10000)
• Governance: B3TRGovernor.castNavigatorVote(proposalId, citizen) — navigator's decision (For/Against/Abstain)
• Voting power = delegated amount at snapshot (checkpointed), not full balance
• Navigator setting preferences/decisions = their own vote (personal VOT3 + staked B3TR converted to VOT3)

Rewards & Fees

1. Navigator fee = gross * navigatorFeePercentage / 10000 (→ NavigatorRegistry escrow)
2. Relayer fee = calculated on remainder (→ RelayerRewardsPool)
3. Citizen receives the rest

• Citizen's own GM level applies. Relayer fee applies to both auto-voters and citizens
• Fee escrow: 4-round rolling unlock in NavigatorRegistry

Slashing

• Minor: 5% of current remaining stake (compounding), reportable by anyone via reportRoundInfractions(navigator, roundId, proposalIds) after round ends
• Six infractions: missed allocation vote, missed governance vote, stale preferences (>= 3 rounds), missed report, late preferences, below minimum stake
• Infractions 1-5 require delegations at round snapshot; infraction 6 (below min stake) applies regardless of delegations
• Below min stake uses two-checkpoint check: below at round start AND still below at round end — gives navigator one full round to recover
• At most one minor slash per round
• Major: governance process, up to 100% of stake + locked fees + removal

Lifecycle

• Exit: announceExit() — 1 round notice, self-enforcing via checkpoint timing (no finalizeExit)
• Deactivation: governance proposal with slash amount
• Both trigger lazy invalidation — citizen delegations void at view level, VOT3 auto-unlocked

Relayer Integration

• Citizens ARE counted in expected actions: allocationUsers = autoVoting + citizens, governanceUsers = citizens only
• castNavigatorVote includes skip-or-vote logic with 720-block skip window (skips for: citizen not a person at snapshot, navigator dead now, no preferences/decision at skip window)
• Per-user skip tracking in RelayerRewardsPool V3 (reduceUserAllocationVote, reduceUserGovernanceVote)
• Governance votes registered as RelayerAction.VOTE — relayers earn credit

Contract: NavigatorRegistry

UUPS upgradeable facade with 6 external libraries: NavigatorStakingUtils, NavigatorDelegationUtils, NavigatorVotingUtils, NavigatorFeeUtils, NavigatorSlashingUtils, NavigatorLifecycleUtils.

Key storage:

• Checkpoints.Trace208 totalDelegatedCitizens — global citizen count (used by XAllocationVoting.startNewRound)
• mapping(address => uint256) navigatorCitizenCount — per-navigator count
• mapping(navigator => mapping(round => amount)) fee escrow

Key functions: delegate, increaseDelegation, reduceDelegation, undelegate, register, addStake, reduceStake, withdrawStake, setAllocationPreferences, setGovernanceDecision, submitReport, announceExit, reportRoundInfractions, claimFee, depositNavigatorFee.

Modified Contracts

VeBetterDAO (X2Earn Sustainability Apps)

When to use

Use when the user asks about:

• Building X2Earn or sustainability-rewarding apps
• Distributing B3TR token rewards to users
• VeBetterDAO allocation rounds and voting
• Submitting an app to VeBetterDAO
• B3TR / VOT3 tokens
• Sustainability proofs and impact tracking

What is VeBetterDAO?

VeBetterDAO is a DAO on VeChainThor that incentivizes sustainable behavior through token rewards. Developers build X2Earn apps (sustainability-focused applications) that reward users with B3TR tokens for performing verifiable sustainable actions -- recycling, reducing carbon footprints, buying sustainable goods, etc.

The community governs fund allocation through weekly allocation rounds where VOT3 holders vote on which apps receive funding, using a quadratic funding formula.

Core Tokens

Architecture Overview

B3TR Token Emissions (weekly, 12-year schedule)
        |
        v
  +-----+------+--------+
  |             |        |
  v             v        v
XAllocation   Vote2Earn  Treasury
  Pool         Pool
  |
  v
XAllocationVoting (Quadratic Funding, VOT3-weighted)
  |
  v
Per-App Allocation (base + variable based on votes)
  |
  v
X2EarnRewardsPool (apps distribute to users)
  |
  v
Users receive B3TR for sustainable actions

Three Integration Patterns

Pattern 1: Smart Contracts Only

All reward validation and distribution logic on-chain via a custom Solidity contract that calls X2EarnRewardsPool.

Pattern 2: Smart Contracts + Backend

Validation logic in a backend, distribution triggered through a smart contract.

Pattern 3: Backend Only (most web2-friendly)

All logic in a traditional backend using @vechain/sdk-network to interact with X2EarnRewardsPool directly. No custom smart contract deployment needed.

Reward Distribution

Solidity: Basic Reward Distributor

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

interface IX2EarnRewardsPool {
    function distributeReward(
        bytes32 appId,
        uint256 amount,
        address receiver,
        string memory proof
    ) external;

    function distributeRewardWithProof(
        bytes32 appId,
        uint256 amount,
        address receiver,
        string[] memory proofTypes,
        string[] memory proofValues,
        string[] memory impactCodes,
        uint256[] memory impactValues,
        string memory description
    ) external;
}

contract MyRewardDistributor {
    IX2EarnRewardsPool public x2EarnRewardsPool;
    bytes32 public APP_ID;

    constructor(address _x2EarnRewardsPool, bytes32 _appId) {
        x2EarnRewardsPool = IX2EarnRewardsPool(_x2EarnRewardsPool);
        APP_ID = _appId;
    }

    function rewardUser(address receiver, uint256 rewardAmount) external {
        x2EarnRewardsPool.distributeReward(APP_ID, rewardAmount, receiver, "");
    }

    function rewardUserWithProof(
        address receiver,
        uint256 rewardAmount,
        string[] memory proofTypes,
        string[] memory proofValues,
        string[] memory impactCodes,
        uint256[] memory impactValues,
        string memory description
    ) external {
        x2EarnRewardsPool.distributeRewardWithProof(
            APP_ID, rewardAmount, receiver,
            proofTypes, proofValues, impactCodes, impactValues, description
        );
    }
}

Important: The deployed contract address must be registered as a "Reward Distributor" for your app via the VeBetterDAO governance dApp.

JavaScript: Backend Reward Distribution

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

const thorClient = ThorClient.at("https://testnet.vechain.org");

const wallet = new ProviderInternalHDWallet(
    mnemonic.split(" "),
    1, 0, true  // testnet
);

const provider = new VeChainProvider(thorClient, wallet);
const signer = await provider.getSigner();

// Load X2EarnRewardsPool contract
const rewardsPool = thorClient.contracts.load(
    X2_EARN_REWARDS_POOL_ADDRESS,
    x2EarnRewardsPoolABI,
    signer
);

// Distribute reward without proofs
await rewardsPool.transact.distributeReward(
    APP_ID,
    ethers.parseEther("10"),  // 10 B3TR
    receiverAddress,
    ""
);

// Distribute reward with sustainability proofs
await rewardsPool.transact.distributeRewardWithProof(
    APP_ID,
    ethers.parseEther("10"),
    receiverAddress,
    ["link", "photo"],                    // proof types
    ["https://proof.url", "ipfs://..."],  // proof values
    ["waste_mass", "carbon"],             // impact codes
    [100, 50],                            // impact values
    "Recycled 100g of plastic waste"
);

Batch Distribution with Multi-Clause

import { ABIContract } from '@vechain/sdk-core';

const clauses = users.map(user => ({
    to: X2_EARN_REWARDS_POOL_ADDRESS,
    value: '0x0',
    data: ABIContract.encodeFunctionInput(
        x2EarnRewardsPoolABI,
        'distributeReward',
        [APP_ID, ethers.parseEther(user.amount), user.address, ""]
    ),
}));

// Send as multi-clause transaction

Sustainability Proofs and Impact

Available Proof Types

link, photo, video, text

Available Impact Codes

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

Mandatory rule: At least proof OR impact must be provided when using distributeRewardWithProof; if neither is provided, the transaction reverts.

Distribution with Metadata

x2EarnRewardsPool.distributeRewardWithProofAndMetadata(
    appId, amount, receiver,
    proofTypes, proofValues,
    impactCodes, impactValues,
    description,
    jsonMetadata  // JSON string with location, referral, campaign info
)

Submitting an App to VeBetterDAO

1. Acquire a Creator NFT: Fill out a form on the VeBetter platform for a background check, or apply for a VeChain Grant (receive funding + Creator NFT). 2. On-Chain Submission: Submit the app on-chain for endorsement consideration. 3. Get Endorsed: Connect with VeChain node holders via the VeBetter XApps Creators Discord. Need a cumulative endorsement score of 100 (a single MjolnirX node = 100 points, Strength node = 2 points). 4. Enter Allocation Rounds: Once endorsed to 100, the app is eligible for weekly B3TR funding.

Contract Addresses

Mainnet

Testnet

Developer Resources

• X-App-Template: github.com/vechain/x-app-template -- Demo sustainability app with mocked contracts
• VeBetterDAO Contracts: github.com/vechain/vebetterdao-contracts -- Full smart contract source for ABI/TypeChain generation
• Test Environment: staging.testnet.governance.vebetterdao.org -- Testnet dApp for managing apps and testing distribution
• Documentation: docs.vebetterdao.org

Getting Started Checklist

1. Get B3TR tokens on testnet 2. Register your app on the testnet governance dApp 3. Add a reward distributor (the PUBLIC ADDRESS of the wallet or contract calling distributeRewards) 4. Choose integration pattern (smart contract, hybrid, or backend-only) 5. Implement reward distribution with sustainability proofs 6. Test on testnet environment 7. Acquire Creator NFT and get endorsed to 100 points for mainnet