Snapshot-Based Loyalty Reward Distributor

WHAT IT DOES

This tool enables DAO treasurers, community managers, and project teams to distribute loyalty rewards based on snapshot-tier assignments. It connects to your wallet and reads the token contract address, snapshot block number, recipient list, loyalty tier assignments, loyalty scores, tier multipliers, allocation calculations, distribution totals, distribution history, and snapshot timestamp. The tool signs and submits transactions to distribute rewards to all recipients based on their loyalty tier and multiplier, update distribution status, record distribution metadata with timestamps, and emit distribution events for transparency. It supports batch sending to hundreds of recipients in a single transaction using the BotGentz bulk sender infrastructure with customizable tier multipliers.

HOW TO USE

1. Connect your wallet using the wallet bridge (supports MetaMask, WalletConnect, and other EVM-compatible wallets).

2. Select the target network that matches your token and treasury location.

3. Enter the token contract address you are distributing and the total reward amount (in token decimals).

4. Enter the snapshot block number for reference, and click "fetch snapshot time" to display the timestamp of that block.

5. Click "fetch token info" to verify the token decimals and symbol, and "check token balance" to confirm you have sufficient tokens.

6. In the recipient list, enter each recipient's address and their loyalty tier assignment (comma-separated, one per line). Tiers can be any string identifier (e.g., bronze, silver, gold, platinum).

7. Configure the tier multipliers — define each tier and its multiplier (one per line, e.g., "bronze:1.0, silver:2.0").

8. Set the base loyalty score (default 100), which is multiplied by the tier multiplier to determine each recipient's weighted score.

9. Click "calculate loyalty scores & allocations" to compute each recipient's score and proportional allocation.

10. Click "preview allocations" to see the first 20 recipients with their tier, score, and allocation.

11. Review the sender contract address, contract owner, fee, total distribution, weighted total, and balances before executing.

12. Click "distribute loyalty rewards" to sign and submit the batch transaction that sends tokens to all recipients based on their tier-weighted allocations.

TECHNICAL MECHANISM

The tool uses ethers.js v5.7.2 with the BotGentz BulkSend registry, which provides verified bulk sender contracts deployed across multiple EVM chains. The fee is read live from the sender contract's fee() view function rather than hardcoded, ensuring accurate payment even if the owner updates the fee. Loyalty scoring uses a tier-based multiplier system: each recipient is assigned a tier, and the tool looks up the corresponding multiplier from the user-defined tier map. The base score (default 100) is multiplied by the tier multiplier to produce the final weight: weight = base_score * tier_multiplier. Allocations are computed as (recipient_weight / total_weight) * total_amount, with rounding corrections to ensure exact sum. The tool performs per-sender balance checks before initiating the transaction (checking both native token balance for fees and token balance for the distribution) and per-sender allowance checks, approving the exact total amount. Batch sends are executed as a single transaction via the bulk sender's sendERC20() function, which distributes tokens to all recipients in one atomic operation with the fee deducted from the sender. Gas costs are reported using receipt.effectiveGasPrice for accurate post-EIP-1559 accounting.

WHAT IT CANNOT SEE

This tool operates purely on-chain and cannot verify loyalty tier accuracy — it does not check that recipients actually earned their assigned tiers or met the criteria for that tier. It cannot validate snapshot data — the tool does not verify that the snapshot block accurately reflects holdings or activity at that point in time. The tool cannot detect sybil accounts, identity fraud, or duplicate addresses that might unfairly receive multiple allocations. It cannot ensure that tier assignments are fair or that the chosen multipliers correctly reflect the community's values. The tool also cannot verify that recipients maintained loyalty criteria during the period between snapshot and distribution — a recipient could have stopped contributing but still receive rewards based on a stale tier assignment. All tier and snapshot data is accepted as entered — the tool does not cross-reference with on-chain activity or governance participation records.

PLEASE NOTE

This tool works exclusively with EVM-compatible blockchain networks (Ethereum, Polygon, Arbitrum, Optimism, Base, etc.). It requires the token to implement standard ERC-20 interface. All transactions incur gas fees plus the bulk sender contract fee, paid by the connected wallet. The tool maintains no persistent storage — all state is refreshed from the blockchain on each session. Always test with small amounts on a testnet first and ensure your token balance and allowances are sufficient. For production distributions, carefully verify tier assignments and consider using on-chain governance or attestation mechanisms to validate loyalty tier eligibility.