Skip to content

Adding Bounties to Initiatives

Bounties allow anyone to contribute external ERC20 token rewards to specific initiatives. When Signals integration is wired, accepted initiatives will distribute bounties according to configurable splits between protocol fees, supporter rewards, and treasury. (Distribution is not triggered on-chain yet.)

Overview

The Bounties system enables:

  • External funding of initiatives with whitelisted ERC20 tokens
  • Automatic distribution on initiative acceptance
  • Configurable three-way splits (protocol/supporters/treasury)
  • Multiple bounties per initiative
  • Optional expiration timestamps

Key Difference from Incentives: Bounties are externally funded and initiative-specific, while Incentives are board-wide and DAO-funded.

Adding a Bounty

To add a bounty to an initiative, you need to:

  1. Ensure the token is whitelisted in the TokenRegistry
  2. Approve the Bounties contract to spend your tokens
  3. Call addBounty with the initiative ID, token address, amount, expiration, and conditions

For detailed function signatures and parameters, see the Initiative Interactions Reference.

Requirements

  • Token must be whitelisted in TokenRegistry
  • Initiative must exist
  • Caller must have sufficient balance
  • Caller must approve Bounties contract
  • Tokens are transferred immediately upon adding

Token Whitelisting

Only whitelisted tokens can be used for bounties. Board owners or token managers add tokens to the whitelist through the TokenRegistry contract. The registry validates that tokens are ERC20 compliant before adding them.

Check if a token is whitelisted before attempting to add a bounty.

Distribution Mechanics

When Bounties Are Distributed

Intended behavior: on acceptance, Signals notifies the Bounties contract to calculate and allocate rewards according to configured split percentages. This integration is not wired yet in the current protocol.

Distribution Formula

Each bounty token type is split into three portions:

  • Protocol fees (e.g., 5%)
  • Supporter rewards (e.g., 20%)
  • Treasury allocation (e.g., 75%)

Note: Percentages are configured per board and must sum to 100.

Supporter Share Calculation

Each supporter's share of the voter pool is proportional to their locked amount relative to the total locked in the initiative.

Bounty Expiration

Bounties can have an optional expiration timestamp. If set:

  • Expired bounties are excluded from distribution
  • They no longer count toward the initiative's total bounty pool
  • Future versions may include refund mechanisms for expired bounties

Set expiresAt to 0 for bounties that never expire.

Claiming Bounty Rewards

Current Status

Important: Claim/withdrawal functions are not yet implemented in the contract.

Current behavior:
  • Distribution happens automatically on acceptance
  • Balances are tracked in the contract
  • No withdrawal function to claim rewards yet
  • Funds accumulate but cannot be withdrawn

Future implementations will allow supporters to claim their allocated bounty rewards after an initiative is accepted.

Configuration & Versioning

Board owners can update the distribution split percentages using the updateSplits function. When splits are updated:

  • A new configuration version is created
  • Existing bounties use their original version's splits
  • New bounties use the current version
  • This prevents retroactive changes to existing commitments

Allocations must always sum to 100 when updating splits.

Typical Flow

  1. Deploy TokenRegistry and Bounties with initial splits.
  2. Whitelist tokens.
  3. Contributors add bounties.
  4. Acceptance triggers distribution and balance tracking.

Best Practices

For Contributors

  1. Whitelist token first - Ensure token is in TokenRegistry before contributing
  2. Set reasonable expiration - Give initiative time to gain support
  3. Diversify tokens - Consider multiple token types for broad appeal
  4. Monitor initiative - Track progress toward acceptance

For Board Owners

  1. Configure fair splits - Balance protocol sustainability and supporter incentives
  2. Whitelist carefully - Only add trusted, liquid tokens
  3. Update splits thoughtfully - Use versioning to prevent retroactive changes
  4. Communicate changes - Inform community of configuration updates

Security Considerations

  1. Token whitelisting prevents malicious tokens
  2. Immediate transfer on addBounty secures funds
  3. Versioned splits prevent retroactive changes
  4. ReentrancyGuard protects distribution
  5. SafeERC20 ensures safe token transfers

Limitations & Future Enhancements

Current Limitations:
  1. No claim/withdrawal function - Rewards accumulate but can't be claimed
  2. No refund mechanism - Expired bounties can't be reclaimed by contributors
  3. Reward preview is not implemented yet (currently returns 0)
  4. No storage optimization - Expired bounties remain in storage
Planned Features:
  • Implement reward claiming for supporters
  • Implement refund logic for expired bounties
  • Event-driven pattern for Signals integration
  • Gas optimization for large bounty lists

For technical details including function signatures, data structures, events, and code examples, see the Initiative Interactions Reference.