Skip to content

Tracking Initiative Support

The Signals protocol provides comprehensive view functions to query initiative support data, including current weight, historical weight, supporters, and individual lock positions.

Overview

You can track initiative support through several types of queries:

  1. Initiative data - Get basic information about the initiative
  2. Weight tracking - Query current and historical weight
  3. Lock positions - View individual lock details
  4. Supporter activity - Derive supporters from lock data or events
  5. Position enumeration - List NFT positions by owner

Key Concepts

Weight vs. Token Amount

  • Token Amount: The raw number of tokens locked in an initiative
  • Weight: The voting power those tokens contribute, which decays over time based on lock duration and elapsed time

Weight determines when an initiative reaches the acceptance threshold.

Current vs. Historical Queries

Many query functions accept a timestamp parameter:

  • Current: Use getWeight(initiativeId) for weight at the current block
  • Historical: Use getWeightAt(initiativeId, timestamp) for weight at a specific time

Historical queries are useful for creating charts and verifying past data.

Common Query Patterns

Check Initiative Progress

To see how close an initiative is to acceptance:

  1. Get the current weight using getWeight()
  2. Get the acceptance threshold
  3. Calculate progress percentage

View Your Positions

To see all your lock positions:

  1. Use ERC721Enumerable (balanceOf, tokenOfOwnerByIndex) to enumerate NFT token IDs you own
  2. For each token ID, use getTokenLock(tokenId) to get lock details
  3. Check which initiatives you're supporting

Monitor Supporter Activity

To track an initiative's support:

  1. Use locksForInitiative(initiativeId) to get all lock positions
  2. For each lock, call getTokenLock(tokenId) and read the supporter address
  3. Aggregate stats (total locked, average duration, unique supporters) or use the indexer

Weight Decay

Weight decays over time based on the board's configuration:

  • Linear Decay: Weight decreases steadily
  • Exponential Decay: Weight decreases at an accelerating rate

Query functions automatically account for decay when calculating weight. The weight you see reflects the current voting power, not the original locked amount.

Events for Real-Time Tracking

For real-time updates, monitor these events:

  • InitiativeProposed - New initiative created
  • InitiativeSupported - Someone locked tokens
  • InitiativeAccepted - Owner accepted the initiative
  • InitiativeExpired - Initiative expired due to inactivity
  • Redeemed - Someone redeemed their lock position
  • Transfer - NFT position was transferred

Using the Indexer

For efficient querying and historical data, consider using the indexer API (if available). The indexer provides:

  • Aggregated initiative data with weight/supporters
  • Historical weight snapshots
  • Lock position details
  • Event history

Querying the indexer is faster and more cost-effective than making multiple contract calls.

Best Practices

  1. Use historical queries for charts - Call getWeightAt() with past timestamps
  2. Cache static data - Board configuration doesn't change frequently
  3. Index events off-chain - Don't query events directly from the contract
  4. Batch read calls - Use multicall for multiple queries
  5. Use indexer when available - Faster than direct contract queries

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