Skip to content

Add Support to an Initiative

Supporting an initiative allows community members to lock tokens to signal their backing for a proposed idea. Support is represented by an ERC721 NFT that can be redeemed once the initiative is accepted or expired.

Overview

When you support an initiative, you:

  1. Lock ERC20 tokens for a specified duration
  2. Receive an ERC721 NFT representing your lock position
  3. Contribute weight toward the initiative's acceptance threshold
  4. Become eligible for incentive rewards (if configured)

How to Support

To support an initiative, call supportInitiative() with:

  • The initiative ID you want to support
  • The amount of tokens to lock (in wei)
  • The lock duration (measured in intervals, not seconds)

You'll receive an NFT token ID representing your lock position.

See the Initiative Interactions Reference for detailed function signatures and parameters.

Prerequisites

Before supporting an initiative, ensure:

  1. Board is open - Current time ≥ opensAt and < closesAt
  2. Initiative exists and is in Proposed state - Cannot support accepted or expired initiatives
  3. You meet participant requirements - Check eligibility with accountCanSupport(address, amount)
  4. You have sufficient tokens and approval - Balance ≥ amount and approved the Signals contract

Token Approval

You must approve the Signals contract to spend your tokens before calling supportInitiative. The contract will transfer your tokens when you lock them.

Participant Eligibility

Boards configure participant requirements using four fields (token, minBalance, minHoldingDuration, minLockAmount). The token controls which ERC20/IVotes balance is checked—it can be the underlying lock token or a separate governance token. Different patterns emerge based on which fields are set:

1. None (Most Permissive)

Anyone can participate - just need tokens to lock.

ParticipantRequirements({
    token: UNDERLYING_TOKEN,
    minBalance: 0,
    minHoldingDuration: 0,
    minLockAmount: 0
})

2. Minimum Balance

Participants must hold a minimum token balance at support time. Optionally, a minimum lock amount can be enforced.

ParticipantRequirements({
    token: UNDERLYING_TOKEN,
    minBalance: 10_000 * 1e18,    // Must hold 10k tokens
    minHoldingDuration: 0,
    minLockAmount: 1_000 * 1e18   // Must lock at least 1k tokens
})

This prevents low-balance sybil attacks and ensures supporters lock meaningful amounts.

3. Minimum Balance and Duration (Most Restrictive)

Participants must:

  • Currently hold ≥ minBalance tokens
  • Have held ≥ minBalance for ≥ minHoldingDuration blocks (historical balance check)
  • Lock ≥ minLockAmount tokens (must be ≤ minBalance)
  • Token must support ERC20Votes (checkpoint functionality)
ParticipantRequirements({
    token: GOVERNANCE_TOKEN,      // Can differ from the locking token
    minBalance: 10_000 * 1e18,
    minHoldingDuration: 50400,    // ~7 days at 12s/block
    minLockAmount: 1_000 * 1e18
})

This ensures only committed token holders can participate.

Weight Contribution

Your support contributes weight toward the initiative's acceptance threshold. Weight is calculated based on:

  • Lock amount
  • Lock duration
  • Time decay (based on board's decay curve)

Initial Weight

Your initial weight = amount × lockDuration

For example:

  • Lock 100 tokens for 10 intervals
  • Initial weight = 100 × 10 = 1,000

Weight Decay

Weight decays over time based on the board's decay curve:

Linear Decay: Weight decreases steadily over time Exponential Decay: Weight decreases at an accelerating rate

Weight never drops below the nominal lock amount until the lock expires.

Acceptance Threshold

The threshold an initiative must reach is calculated as:

threshold = max(
    totalSupply * thresholdPercentTotalSupplyWAD / 1e18,
    minThreshold
)

Query the current threshold with getAcceptanceThreshold().

NFT Lock Position

When you support an initiative, you receive an ERC721 NFT representing your lock position.

NFT Properties

  • Name: {underlyingToken.name()} Locked Support
  • Symbol: sx{underlyingToken.symbol()}
  • Transferable: Yes - you can trade your lock position
  • Redeemable: Holder can redeem underlying tokens after acceptance/expiration

The NFT contains all lock details including amount, duration, and creation timestamp.

Multiple Lock Positions

You can support the same initiative multiple times with different amounts and durations. Each support creates a separate NFT with independent:

  • Lock duration
  • Amount
  • Creation timestamp
  • Decay calculation

Redemption

You cannot withdraw tokens early. Redemption is only available when:

  1. Initiative is Accepted
    • Must wait for releaseLockDuration to pass (if configured)
    • Auto-claims incentive rewards on redemption
  2. Initiative is Expired
    • Immediate redemption available
    • No incentive rewards
  3. Lock Duration Passed
    • Can redeem once your lock duration expires
    • Initiative state doesn't matter
  4. Board is Cancelled
    • Emergency override - all locks become immediately redeemable
    • Bypasses release timelock

See the Reclaiming Locked Tokens guide for redemption details.

Integration with Incentives

If the board has incentives enabled:

  • Early supporters get more rewards - Time-weighted based on when you lock
  • Rewards are calculated on redemption - Based on your credited weight and time buckets
  • Auto-claimed on redemption - No need to manually claim
  • Multiple locks are weighted independently - Each position earns rewards

The pool does not expose per-supporter reward previews before redemption.

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