Are you an LLM? Read llms.txt for a summary of the docs, or llms-full.txt for the full context.
Skip to content

Proposing an Initiative

An initiative is a proposal submitted to a Signals board. Anyone who meets the board's proposer requirements can create one. Both methods accept a title, description (markdown supported), and up to 5 attachments (URIs pointing to supporting documents, designs, or forum posts).

Check eligibility before proposing with accountCanPropose(address, lockAmount). This returns whether the address meets the board's proposer requirements.

proposeInitiative()

Creates the initiative without locking tokens. Other supporters can lock tokens behind it afterward.

function proposeInitiative(Metadata calldata metadata) external returns (uint256 initiativeId)

proposeInitiativeWithLock()

Creates the initiative and locks your tokens in a single transaction. This gives the initiative immediate support weight and signals that the proposer has skin in the game.

function proposeInitiativeWithLock(
    Metadata calldata metadata,
    uint256 amount,
    uint256 lockDuration
) external returns (uint256 initiativeId, uint256 tokenId)

You must first approve the Signals contract to transfer your tokens. The contract uses safeTransferFrom to pull the locked amount.

Attachments

Attachments let you include supporting resources like proposal documents, designs, or forum posts.

  • Up to 5 attachments per initiative
  • Each attachment requires a non-empty URI (https://, ipfs://, or on-chain pointer)
  • MIME type and description fields are optional hints for clients
  • Pass an empty array if you don't need attachments

Proposer eligibility

Boards configure proposer requirements at deployment. There are three levels:

  • No requirements: anyone can propose. Set minBalance: 0 and minHoldingDuration: 0.
  • Minimum balance: proposers must hold at least minBalance tokens at the time of proposal.
  • Minimum balance and holding duration: proposers must hold at least minBalance tokens and have held them for at least minHoldingDuration blocks. This requires the token to support ERC20Votes checkpoints.

Lock duration is measured in intervals

When proposing with a lock, you specify duration as a number of intervals, not seconds. The board's lockInterval parameter defines how long one interval is (typically 1 day). A duration of 30 on a board with lockInterval = 1 day locks your tokens for 30 days. The maximum is capped by maxLockIntervals.

After proposal

Your initiative starts in the Proposed state. From here it can be:

  • Accepted when its aggregate support weight crosses the board's acceptance threshold
  • Expired by the board owner if no new support is added within the inactivityTimeout window

See Lock Tokens to Support an Initiative for how other token holders add support, and Accepting and Expiring Initiatives for how initiatives change state.