@vechain/vebetterdao-relayer-node
v0.0.4
Published
Standalone relayer node for VeBetterDAO auto-voting and reward claiming
Keywords
Readme
#######
################
####################
########### #########
######### #########
####### ######### #########
######### ######### ##########
########## ######## ####################
########## ######### #########################
################### ############################
################# ########## ########
############## ### ########
############ #########
########## ##########
######## ###########
### ############
##############
#################
##############
#########What Is This?
VeBetterDAO users can enable auto-voting to automate their weekly X Allocation votes. They pick up to 15 favorite apps, toggle it on, and a relayer handles the rest: casting votes, claiming rewards, all gasless. Tokens never leave the user's wallet.
This repo is a standalone relayer node. Run it, and it will:
- Discover all users who have auto-voting enabled
- Cast
castVoteOnBehalfOffor each user during the active round - Claim rewards via
claimRewardfor each user after the round ends - Loop every 5 minutes
Economics: Each user pays a 10% fee on rewards (capped at 100 B3TR per round). That fee flows into the RelayerRewardsPool. Your share is proportional to your weighted actions (vote = 3 pts, claim = 1 pt). Gas costs ~0.11 B3TR per user; average fee earned ~9-19 B3TR per user.
Quick Start
From npm (requires the package to be published):
MNEMONIC="your twelve word mnemonic phrase here" npx @vechain/vebetterdao-relayer-node
# Testnet
RELAYER_NETWORK=testnet-staging MNEMONIC="..." npx @vechain/vebetterdao-relayer-nodeFrom source (clone and build):
git clone https://github.com/vechain/vebetterdao-relayer-node.git
cd vebetterdao-relayer-node
npm install && npm run build
MNEMONIC="your twelve word mnemonic phrase here" node dist/index.jsAlternative: global install
npm install -g @vechain/vebetterdao-relayer-node
MNEMONIC="..." vbd-relayer(Only works after the package is published to npm.)
Alternative: Docker
Pre-built image (after the repo has been pushed to main on GitHub, image is built at GHCR; use tag latest or main):
docker run -it --env MNEMONIC="your twelve word mnemonic phrase here" ghcr.io/vechain/vebetterdao-relayer-node:latestBuild locally (works without publishing):
git clone https://github.com/vechain/vebetterdao-relayer-node.git
cd vebetterdao-relayer-node
docker build -t vbd-relayer .
docker run -it --env MNEMONIC="your twelve word mnemonic phrase here" vbd-relayerBecoming a Relayer
Your wallet must be registered on-chain in the RelayerRewardsPool contract before you can earn fees. During the MVP phase, registration is managed by the pool admin. Check the governance proposal and community discussion for the latest on the registration process.
You can run the node without registration to test, but votes cast during the early access window (first ~5 days after round start) require registration. After early access, anyone can cast votes.
Terminal Dashboard
The node renders a live dashboard that refreshes each cycle:
+------------------------------------------------------------------+
| VeBetterDAO Relayer Node |
+------------------------------------------------------------------+
| Network mainnet Block 24,237,183 |
| Node mainnet.vechain.org |
| Address 0xABCD...1234 + Registered |
+------------------------------------------------------------------+
| ROUND #88 * Active |
| Snapshot 24190328 Deadline 24250807 |
| Auto-voters 1209 Relayers 1 |
| Voters 20949 Total VOT3 206160737.01 VOT3 |
+------------------------------------------------------------------+
| Vote Wt 3 Claim Wt 1 |
| Fee 10.00% Cap 100.00 B3TR |
| Early Access 43200 blocks |
+------------------------------------------------------------------+
| THIS ROUND |
| Completion 75.00% Missed 295 |
| Pool 5000.00 B3TR Your share 1500 B3TR |
| Actions 120 (wt: 360) Total acts 2360 |
| |
| PREVIOUS ROUND #87 |
| Pool 5746.01 B3TR Your share 1200 B3TR |
| Actions 150 + Claimable |
+------------------------------------------------------------------+
--- Activity Log --------------------------------------------------
[10:30:15] Starting cast-vote cycle...
[10:30:16] Found 1209 auto-voting users
[10:30:18] 295 users need voting (914 already voted)
[10:30:19] Batch 1/6 (50 users): + 50 OK (tx: 0x1234abcd...)How It Works
Each cycle:
- Fetch state -- current round, auto-voting users, reward pool, fee config
- Cast votes -- filter users who haven't voted, batch
castVoteOnBehalfOfcalls (multi-clause txs with gas simulation and failure isolation) - Claim rewards -- call
claimRewardfor previous round users (fee is deducted inside the contract and deposited to the pool) - Refresh dashboard -- update stats, sleep until next cycle
Reward Distribution
Relayer rewards follow an all-or-nothing model: the pool only unlocks when ALL auto-voting users have been served (completedWeightedActions >= totalWeightedActions). This incentivizes relayers to process every user. Your share is:
relayerShare = (yourWeightedActions / totalCompletedWeightedActions) * poolAmountEarly Access
Registered relayers get a head start. For the first ~5 days (43,200 blocks) after a round starts, only registered relayers can cast votes. Similarly, only registered relayers can claim rewards for ~5 days after a round ends. After that, anyone can act.
Environment Variables
| Variable | Required | Default | Description |
|---|---|---|---|
| MNEMONIC | One of | -- | BIP39 mnemonic phrase |
| RELAYER_PRIVATE_KEY | these two | -- | Hex private key (with or without 0x) |
| RELAYER_NETWORK | No | mainnet | mainnet or testnet-staging |
| NODE_URL | No | Per network | Override Thor node URL |
| BATCH_SIZE | No | 50 | Users per transaction batch |
| DRY_RUN | No | 0 | 1 to simulate without sending transactions |
| POLL_INTERVAL_MS | No | 300000 | Milliseconds between cycles (min 60,000) |
| RUN_ONCE | No | 0 | 1 to run a single cycle and exit |
Contracts
| Contract | Purpose | Key Functions |
|---|---|---|
| XAllocationVoting | Round info, auto-voting users, vote execution | castVoteOnBehalfOf, currentRoundId, hasVoted, AutoVotingToggled event |
| VoterRewards | Reward claiming with fee deduction | claimReward (deducts 10% fee, deposits to pool) |
| RelayerRewardsPool | Registration, action tracking, reward distribution | claimableRewards, isRewardClaimable, getRegisteredRelayers, weights |
Mainnet and testnet-staging addresses are in src/config.ts.
Full contract source: vechain/vebetterdao-contracts
Project Structure
src/
index.ts # Entry point -- env parsing, wallet derivation, main loop
config.ts # Network configs with contract addresses
contracts.ts # On-chain reads (view functions + event pagination)
relayer.ts # Batch vote casting + reward claiming with isolation/retry
display.ts # Terminal UI rendering (box drawing + chalk)
types.ts # Shared interfacesDevelopment
# Run with ts-node (no build step)
MNEMONIC="..." npm run dev
# Dry run -- simulate only, no transactions sent
DRY_RUN=1 MNEMONIC="..." npm run dev
# Single cycle then exit
RUN_ONCE=1 MNEMONIC="..." npm run dev
# Build
npm run build && npm startLinks
License
MIT