Define the bounty structure
Before writing a single line of Solidity, you must define the economic model that governs your onchain referral bounties. The structure determines whether your program drives organic growth or becomes a drain on your treasury. Smart contracts handle the automation of tracking and distribution, but they cannot fix a flawed incentive design.
Start by selecting your reward type. Fixed bounties pay a set amount for every successful action, such as a new wallet creation or first trade. This approach is predictable and easy for users to understand, but it can be expensive if adoption spikes. Percentage-based bounties take a cut of the referred user’s activity, such as trading fees. This aligns your incentives with long-term value, but it requires more complex accounting within the contract.
Next, determine the reward pool size. Your budget must be sustainable enough to attract genuine users but tight enough to prevent exploitation. If the bounty is too high, you will attract bots that drain funds without generating real value. If it is too low, you will attract no one.
Finally, define the eligibility criteria. Will you reward only the first referrer, or share it among multiple referrers? Are there caps on how much one user can earn? These rules should be encoded directly into the smart contract to ensure transparency and prevent disputes. Clear rules build trust with your community and reduce the need for manual intervention.
Choose the tracking infrastructure
You need to decide how to attribute referrals before writing a single line of code. The tracking method you pick determines whether your bounties are accurate, secure, and cost-effective. The three main options are onchain smart contracts, offchain databases, and hybrid systems.
Onchain tracking
Smart contracts handle the entire referral lifecycle directly on the blockchain. They verify wallet addresses, track interactions, and distribute rewards automatically without a central server. This approach offers full transparency and eliminates the risk of a single point of failure. However, every transaction requires gas fees, which can make small referral payouts expensive on high-traffic networks.
Offchain tracking
Offchain systems store referral data in traditional databases like PostgreSQL or MongoDB. This method is significantly cheaper and faster than onchain tracking because it avoids blockchain transaction fees. It is ideal for high-volume campaigns where speed matters more than public verifiability. The trade-off is that you must trust the central operator to keep accurate records and distribute rewards fairly.
Hybrid tracking
Hybrid systems use offchain databases for initial tracking and speed, then settle final rewards onchain. This balances cost and security by minimizing expensive blockchain writes while maintaining an immutable record of payouts. It is the most common architecture for mature referral programs that need to scale efficiently.
| Feature | Onchain | Offchain | Hybrid |
|---|---|---|---|
| Cost per Referral | High (Gas fees) | Low (Server costs) | Medium |
| Speed | Slow (Block time) | Instant | Fast |
| Security | High (Immutable) | Medium (Centralized) | High |
| Transparency | Full | None | Partial |
Onchain referral development allows full automation, with smart contracts handling everything from tracking to eligibility verification [src-serp-2]. Web3 marketing analytics increasingly tracks wallet addresses and onchain behavior instead of relying on cookies and device IDs used in traditional analytics [src-serp-3]. Your choice should depend on your budget, user base, and need for decentralization.
Deploy the referral smart contract
Writing the referral smart contract is where you define the logic for tracking users and distributing rewards. Unlike traditional web2 referral systems that rely on centralized databases, an onchain referral contract automates the entire lifecycle—tracking referrals, verifying eligibility, and distributing rewards—directly on the blockchain [src-serp-2].
This approach removes the need for manual oversight or third-party intermediaries. The contract acts as the single source of truth, ensuring that every referral link and reward payout is transparent and immutable.
To deploy a functional referral system, you need to structure your smart contract to handle three core responsibilities: storing referral mappings, validating referral actions, and executing reward distributions. Below is the step-by-step process for building and deploying this logic.
Start by defining the core data structures that will track relationships between referrers and referees. You need a mapping to store the unique referral code or link associated with each user address. Additionally, create a mapping to track the referrer of each new user, allowing you to trace the chain of referrals if necessary.
Create a function that registers new users and links them to their referrer. This function should accept the referrer’s address as a parameter and update your storage mappings accordingly. Ensure that the logic prevents self-referrals and handles edge cases, such as a user trying to register with an invalid or already-used referral code.
Define how rewards are calculated and distributed. You might choose to distribute rewards in the native token of your protocol or a specific ERC-20 token. Implement a function that triggers when a referee completes a qualifying action (e.g., making a trade or depositing funds). This function should calculate the reward amount based on your predefined rates and transfer the tokens to the referrer’s address.
Once your contract code is complete, deploy it to your target blockchain network using a tool like Hardhat or Foundry. After deployment, verify the contract source code on a block explorer like Etherscan or Solscan. Verification allows users to inspect the contract code, ensuring transparency and building trust in your referral program’s integrity.
By following these steps, you create a robust, automated referral system that scales with your user base without requiring constant manual intervention.
Verify and distribute rewards
Once a referral is recorded on-chain, the final step is confirming the action meets your criteria and sending the payout. Whether you use a smart contract to automate this or handle it manually, accuracy is non-negotiable. A single error can drain your bounty pool or alienate early advocates.
Before paying out, ensure the referrer actually drove the action. Check that the referring wallet signed the initial transaction and that the referred user completed the required onboarding steps, such as signing up or making a first deposit. Use official referral program documentation, like HackenProof’s guide, to define clear eligibility rules before deployment.
Bounties are high-value targets for sybil attacks and fraud. Verify that the new user is a unique entity and not a bot account created solely to harvest rewards. If you are running a bug bounty or security-focused referral program, consult playbooks from Immunefi to identify common exploit patterns and ensure your verification logic holds up under attack.
Distribute the reward using the method defined in your smart contract. For automated systems, the contract should trigger a token transfer to the referrer’s wallet immediately upon verification. If handling manually, send the payment from your treasury wallet and record the transaction hash on-chain for transparency. This creates an immutable proof of payment that builds trust with your community.
Common referral program mistakes
Even with smart contract security in place, structural flaws can drain your budget or dilute your community. The most frequent errors happen during the design phase, where builders prioritize vanity metrics over sustainable economics.
Ignoring Sybil Detection
A referral program without identity verification is an open invitation for Sybil attacks. Bad actors create hundreds of fake wallets to harvest rewards, leaving legitimate users with empty pockets and a broken trust model. Use tools like Gitcoin Passport or WorldID to filter out bots before distributing bounties. Without this layer, your program becomes a subsidy for fraud rather than growth.
Poor UX Friction
If claiming a reward requires more than two clicks, users will abandon the process. Complex approval flows or obscure wallet interactions kill conversion rates. Keep the referral link simple and the claim process automatic where possible. As noted by Referral Factory, clear attribution and streamlined onboarding are essential for turning momentum into a structured engine [1].
Unclear Reward Structures
Ambiguity breeds distrust. If users don’t understand how much they earn or when it arrives, they won’t promote your project. Define the exact conditions for payout in plain language. Avoid hidden caps or confusing tiered systems that require a calculator to understand.
[1] https://referral-factory.com/referral-programs/crypto
No comments yet. Be the first to share your thoughts!