queries.yaml.example

# Census3 BigQuery Queries Configuration
# Copy this file to queries.yaml and customize your queries

queries:
  # Example 1: Simple Ethereum holders with equal voting
  - name: ethereum_holders_equal
    displayName: "Ethereum Holders"
    displayAvatar: "https://example.com/avatars/eth.png"
    query: ethereum_balances
    period: 1h
    decimals: 18
    snapshotsToKeep: 24  # Keep only the 24 most recent snapshots
    parameters:
      min_balance: 1.0  # 1 ETH minimum
    weight:
      strategy: "constant"
      constant_weight: 1

  # Example 2: ERC20 token holders with cost control
  - name: justice_token_holders
    displayName: "Justice Token Holders"
    # displayAvatar is optional - if omitted, defaults to empty string
    query: erc20_holders
    period: 50m
    estimate_first: true
    cost_preset: "default"  # Simple cost control
    decimals: 18
    snapshotsToKeep: 144  # Keep only the 144 most recent snapshots
    parameters:
      token_address: "0x59d1e836f7b7210a978b25a855085cc46fd090b5"
      min_balance: 20000
    weight:
      strategy: "proportional_auto"
      target_min_weight: 1

  # Example 3: Conservative cost limits for development
  - name: ethereum_test
    query: ethereum_balances
    period: 24h
    estimate_first: true
    cost_preset: "conservative"  # 1GB/$0.10 limits
    snapshotsToKeep: 7  # Keep only the 7 most recent snapshots
    parameters:
      min_balance: 10.0
    weight:
      strategy: "constant"
      constant_weight: 1

  # Example 4: High-volume production query
  - name: ethereum_governance
    query: ethereum_balances
    period: 2h
    estimate_first: true
    cost_preset: "high_volume"  # 1TB/$50 limits
    # snapshotsToKeep: 0  # Default: keep all snapshots (unlimited)
    parameters:
      min_balance: 0.1
    weight:
      strategy: "proportional_auto"
      target_min_weight: 10
      max_weight: 100000

  # Example 5: No cost limits (advanced users)
  - name: ethereum_unlimited
    query: ethereum_balances
    period: 6h
    estimate_first: true
    cost_preset: "none"  # No cost limits
    parameters:
      min_balance: 0.01
    weight:
      strategy: "proportional_manual"
      multiplier: 100

  # Example 6: Recent activity without balance requirement
  - name: ethereum_active_users
    query: ethereum_recent_activity
    period: 24h
    estimate_first: true
    cost_preset: "default"
    parameters: {}  # No parameters needed
    weight:
      strategy: "constant"
      constant_weight: 1

  # Example 7: Disabled query (keeps snapshots accessible)
  - name: old_query
    query: ethereum_balances
    period: 12h
    disabled: true  # Disabled but snapshots remain accessible
    parameters:
      min_balance: 5.0
    weight:
      strategy: "constant"
      constant_weight: 1

# ========== ALCHEMY QUERIES ==========
# The following examples demonstrate how to use Alchemy as a data source

# Example 8: NFT holders from Alchemy (Base network)
  - name: base_nft_holders
    source: alchemy  # Specify Alchemy as the data source
    query: nft_holders
    network: base-mainnet  # Required for Alchemy queries
    period: 30m
    parameters:
      contract_address: "0x85E7DF5708902bE39891d59aBEf8E21EDE91E8BF"  # NFT contract
      min_balance: 1  # Minimum NFT count
    weight:
      strategy: "constant"
      constant_weight: 1  # Equal voting for all NFT holders

# Example 9: NFT holders with proportional voting (Ethereum)
  - name: eth_nft_proportional
    source: alchemy
    query: nft_holders
    network: eth-mainnet
    period: 1h
    parameters:
      contract_address: "0xBC4CA0EdA7647A8aB7C2061c2E118A18a936f13D"  # BAYC
      min_balance: 1
    weight:
      strategy: "proportional_auto"
      target_min_weight: 1  # 1 NFT = 1 point, 10 NFTs = 10 points
      max_weight: 100  # Cap at 100 points

# Example 10: NFT holders on Polygon
  - name: polygon_nft_holders
    source: alchemy
    query: nft_holders
    network: polygon-mainnet
    period: 2h
    parameters:
      contract_address: "0x7227e371540CF7b8e512544Ba6871472031F3335"  # Polygon NFT
      min_balance: 1
    weight:
      strategy: "proportional_manual"
      multiplier: 10  # Each NFT = 10 points

# Example 11: Haberdashery - Combined holders of two Base NFTs
  - name: haberdashery
    source: alchemy
    query: multi_nft_holders
    network: base-mainnet
    period: 4h
    parameters:
      contract_addresses:
        - "0x85E7DF5708902bE39891d59aBEf8E21EDE91E8BF"  # Base NFT 1
        - "0x980Fbdd1cF05080781Dca0AEf7026B0406743389"  # Base NFT 2
      min_balance: 1  # Must hold at least 1 NFT from either collection
    weight:
      strategy: "proportional_auto"
      target_min_weight: 1  # 1 NFT = 1 point, accumulates across both contracts
      max_weight: 50  # Cap at 50 points to prevent excessive concentration

# Example 12: Multiple NFT contracts on Ethereum (template)
  # - name: multi_eth_nft_holders
  #   source: alchemy
  #   query: multi_nft_holders
  #   network: eth-mainnet
  #   period: 4h
  #   parameters:
  #     contract_addresses:
  #       - "0xBC4CA0EdA7647A8aB7C2061c2E118A18a936f13D"  # BAYC
  #       - "0x60E4d786628Fea6478F785A6d7e704777c86a7c6"  # MAYC
  #     min_balance: 1
  #   weight:
  #     strategy: "constant"
  #     constant_weight: 1

# Example 13: Ethereum holders with Farcaster metadata
  - name: ethereum_holders_with_farcaster
    displayName: "Ethereum Holders with Farcaster"
    query: ethereum_balances
    period: 2h
    decimals: 18
    snapshotsToKeep: 12  # Keep only the 12 most recent snapshots
    storeAddresses: true  # Enable address storage for metadata processing
    parameters:
      min_balance: 0.1  # 0.1 ETH minimum
    weight:
      strategy: "proportional_auto"
      target_min_weight: 1
      max_weight: 1000
    metadata:
      farcaster:
        neynarApiKey: "YOUR_NEYNAR_API_KEY_HERE"  # Replace with your actual API key

# Cost Preset Options:
#
# "conservative" - Safe for development/testing
#   - 1 GB processing limit
#   - $0.10 cost limit
#   - 100 MB warning threshold
#
# "default" - Standard production use
#   - 100 GB processing limit
#   - $5.00 cost limit
#   - 10 GB warning threshold
#
# "high_volume" - Enterprise/high-volume use
#   - 1 TB processing limit
#   - $50.00 cost limit
#   - 100 GB warning threshold
#
# "none" - No cost limits (advanced users only)
#   - No processing limits
#   - No cost limits
#   - Use with caution!
#
# Weight Strategy Options:
#
# "constant" - Everyone gets the same weight
#   - constant_weight: integer (required)
#   - Use for: Equal voting power
#
# "proportional_auto" - Automatic scaling based on balance ratio
#   - target_min_weight: integer (required)
#   - max_weight: integer (optional cap)
#   - Formula: weight = (balance / min_balance) * target_min_weight
#   - Use for: Quadratic voting
#
# "proportional_manual" - Custom multiplier
#   - multiplier: float (required)
#   - max_weight: integer (optional cap)
#   - Formula: weight = balance * multiplier
#   - Use for: Custom weight calculations
#
# Query Control Options:
#
# disabled: true/false (optional, default: false)
#   - Disables sync but keeps existing snapshots accessible
#
# syncOnStart: true/false (optional, default: false)
#   - If true: Always syncs immediately on startup
#   - If false: Respects period timing
#
# estimate_first: true/false (optional, default: false)
#   - Enables cost estimation before query execution
#   - Recommended for all production queries
#
# snapshotsToKeep: integer (optional, default: 0 = unlimited)
#   - Number of snapshots to retain for this query
#   - When a new snapshot is created, older snapshots beyond this count are deleted
#   - Set to 0 or omit to keep all snapshots (unlimited)
#   - Examples:
#     - snapshotsToKeep: 2 = Keep only the 2 most recent snapshots
#     - snapshotsToKeep: 10 = Keep only the 10 most recent snapshots
#     - snapshotsToKeep: 100 = Keep only the 100 most recent snapshots
#
# Display Options:
#
# displayName: string (optional)
#   - Human-readable display name for the query
#   - Shown in API responses and user interfaces
#   - If omitted, defaults to the query name
#
# displayAvatar: string (optional)
#   - URL to an avatar/logo image for visual representation
#   - Should be a publicly accessible HTTPS URL
#   - If omitted, defaults to empty string
#
# Address Storage Options:
#
# storeAddresses: true/false (optional, default: false)
#   - Enables storage of original addresses for metadata processing
#   - Required for Farcaster metadata and other address-based features
#   - Addresses are stored in paginated format (1024 addresses per page)
#   - Automatically cleaned up when snapshots are deleted
#   - Disable for large censuses to save storage space
#
# Metadata Options:
#
# metadata: object (optional)
#   - Configuration for additional metadata enrichment
#   - Currently supports Farcaster metadata
#   - Requires storeAddresses: true to function properly
#
# metadata.farcaster: object (optional)
#   - Enables Farcaster metadata collection for census participants
#   - neynarApiKey: string (required) - Your Neynar API key
#   - When enabled, the service will:
#     1. Use stored addresses from the census
#     2. Filter out invalid addresses (zero addresses, malformed hex)
#     3. Query Neynar API to find associated Farcaster usernames
#     4. Store username-to-weight mappings as metadata
#     5. Expose metadata via GET /metadata/farcaster/{censusRoot}
#     6. Include metadata links in snapshot responses
#   - API calls are batched (350 addresses per request) for efficiency
#   - Metadata processing is synchronous but optional (won't fail census creation)
#   - Example response: {"users": [{"username": "alice", "weight": 100, "fid": 12345, "address": "0x..."}]}