Adding Bounties

Function Signature

function addBounty(
    uint256 _initiativeId,
    address _token,
    uint256 _amount,
    uint256 _expiresAt,
    Conditions _terms
) external payable

Parameters

Parameter	Type	Description
`_initiativeId`	`uint256`	Initiative ID to attach bounty to
`_token`	`address`	ERC20 token address (must be whitelisted)
`_amount`	`uint256`	Amount of tokens to contribute
`_expiresAt`	`uint256`	Unix timestamp when bounty expires (0 = never)
`_terms`	`Conditions`	Distribution conditions (stored but not enforced yet)

Token approval: callers must approve the Bounties contract for _amount on the bounty token before calling addBounty.

TokenRegistry Functions

// Add token to whitelist (TOKEN_MANAGER_ROLE only)
function allow(address _token) external onlyRole(TOKEN_MANAGER_ROLE)
 
// Remove token from whitelist
function deny(address _token) external onlyRole(TOKEN_MANAGER_ROLE)
 
// Check if token is whitelisted
function isAllowed(address _token) external view returns (bool)

Distribution Formula

// For each token type:
protocolAmount = (totalAmount * protocolAllocation) / 100
voterAmount = (totalAmount * voterAllocation) / 100
treasuryAmount = (totalAmount * treasuryAllocation) / 100

Note: Allocations are percentages that must sum to 100.

Supporter Share Calculation

supporterShare = (lockedAmount / totalLocked) * voterAmount

Bounty Data Structure

struct Bounty {
    uint256 initiativeId;
    IERC20 token;
    uint256 amount;
    uint256 paid;              // Future use
    uint256 refunded;          // Future use
    uint256 expiresAt;         // 0 = never expires
    address contributor;
    Conditions terms;
}

Querying Bounties

Get Aggregated Bounties

function getBounties(uint256 _initiativeId) external view
    returns (
        address[] memory tokens,
        uint256[] memory amounts,
        uint256 expiredCount
    )

Returns aggregated bounties by token type, excluding expired bounties.

Preview Rewards

function previewRewards(uint256 _initiativeId, uint256 _tokenId)
    external view returns (uint256)

Current status: reward preview is not implemented yet and currently returns 0.

Configuration & Versioning

Update Distribution Splits

function updateSplits(
    uint256[3] memory _allocations,
    address[3] memory _receivers
) external onlyOwner

Requirements:

Only owner can call
Allocations must sum to 100
Creates new version (doesn't affect existing bounties)

Versioning Structure

uint256 public version  // Current version
mapping(uint256 => uint256[3]) public allocations  // Historical
mapping(uint256 => address[3]) public receivers    // Historical

Events Emitted

event BountyAdded(
    uint256 indexed bountyId,
    uint256 indexed initiativeId,
    address indexed token,
    uint256 amount,
    uint256 expiresAt,
    Conditions terms
)
 
event BountiesUpdated(uint256 version)

Validation & Errors

Error	Condition	Solution
`Bounties_TokenNotRegistered`	Token not whitelisted	Add token to TokenRegistry
`Bounties_InvalidInitiative`	Initiative doesn't exist	Use valid initiative ID
`Bounties_InsufficientBalance`	Not enough tokens	Acquire more tokens
`Bounties_InsufficientAllowance`	Not approved	Approve Bounties contract
`Bounties_InvalidAllocation`	Allocations don't sum to 100	Fix split configuration
`Bounties_NotAuthorized`	Caller not authorized	Must be Signals contract or owner

Integration Status

Signals does not currently invoke the Bounties contract on acceptance or expiration. Distribution and refunds are not triggered on-chain yet.

Frontend Integration

Use getBounties and balances to surface bounty totals and supporter balances. previewRewards currently returns 0.