---
description: 
globs: 
alwaysApply: true
---

# VoxPop Project Rules for Cursor

## Project Overview
- VoxPop is a decentralized platform for crowdsourcing public opinion to inform legislation.
- Goals: Empower citizens, ensure transparency, resist censorship, and deliver actionable policy recommendations.
- Core Features: Decentralized identity (Privado ID), liquid democracy, AI-driven analysis, community voting, and immutable storage.

## Technical Architecture
- **Blockchain**: Polygon PoS (Amoy testnet for PoC, mainnet for production).
  - Use Solidity ^0.8.20 for smart contracts.
  - Focus on gas-efficient code (e.g., minimize storage, use events).
- **Decentralized Storage**: IPFS with Pinata pinning.
  - Store full feedback off-chain; use hashes on-chain.
- **Indexing**: The Graph (subgraph for event indexing).
  - Use GraphQL for queries; AssemblyScript for subgraph logic.
- **Identity**: Privado ID with zero-knowledge proofs (ZKPs).
  - Integrate ZKP verification in smart contracts.
- **Frontend**: Next.js with Typescript, hosted on IPFS.
  - Prioritize intuitive UX; keep interactions lightweight.
- **Backend**: Minimal, decentralized services in Go or TypeScript.
  - Use Go for core logic; TypeScript for IPFS integration.
- **AI Analysis**: Off-chain with Hugging Face Transformers or spaCy (Python).
  - Process data from IPFS; submit results to blockchain.
- **Governance**: DAO (Aragon or Snapshot).
  - Implement community voting and resolution compilation.

## Data Lifecycle and Terminology
- **Perspective**: Raw user submission (stored on IPFS, hash on-chain).
- **Synthesis**: AI-driven refinement of Perspectives into Insights.
- **Insight**: Summarized public sentiment from synthesis.
- **Consensus**: Community voting to endorse Insights.
- **Contribution**: Validated Insight accepted by consensus.
- **Resolution**: Final policy recommendation from Contributions.
- Use these terms consistently in code, comments, and variable names.


## Unverified Users and Abuse Mitigation
- Unverified users can participate in a limited capacity; their actions (e.g., Perspectives, comments) do not affect official metrics or legislation unless verified.
- Unverified contributions are labeled "Unverified" and hidden by default, with user-controlled visibility toggles.
- Verified users have full privileges, including voting on Insights and contributing to legislative outcomes.
- Rate limiting: Unverified users are capped at 5 actions per day (e.g., submissions, comments), adjustable via smart contract settings.
- Human verification: CAPTCHAs or equivalent checks are required for unverified users on actions like posting or file uploads.
- Community moderation: Verified users can flag/report unverified content, feeding into a decentralized moderation queue.
- AI filtering: Automated detection of spam or bot-like behavior flags content for review, with results auditable on-chain.
- Economic barriers: Small, refundable cryptocurrency fees (e.g., 0.01 POL) apply to unverified actions to deter abuse.
- Earned trust: Unverified users can earn incremental privileges (e.g., higher limits) through consistent, unflagged participation.
- Transparency: All moderation actions and AI decisions are logged transparently, ideally on-chain, for community oversight.

## Smart Contract Guidelines
- **Methods**: 
  - `submitPerspective(string ipfsHash, string issueId)`: Record user submissions.
  - `proposeInsight(string description, uint256[] perspectiveIds)`: Submit AI-generated Insights.
  - `voteOnInsight(uint256 insightId, bool support)`: Enable community voting.
  - `acceptContribution(uint256 insightId)`: Validate Insights as Contributions.
  - `compileResolution(string resolution)`: Finalize Resolutions.
- **Events**: Emit for each method (e.g., `PerspectiveSubmitted`, `InsightProposed`).
- **Validation**: Restrict key methods (e.g., `proposeInsight`) to authorized roles (moderators or DAO).
- **Storage**: Store structs with minimal fields (e.g., `ipfsHash`, `issueId`, `zkpProof`).

## Coding Style and Conventions
- **Solidity**:
  - Use camelCase for variables (e.g., `feedbackHash`).
  - Prefix events with the method name (e.g., `event SubmitPerspective`).
  - Include detailed NatSpec comments (e.g., `@param`, `@return`).
- **Go**: 
  - Follow Go naming conventions (e.g., `submitFeedback`).
  - Use packages for modularity (e.g., `storage`, `blockchain`).
- **TypeScript**:
  - Use camelCase and explicit types (e.g., `ipfsHash: string`).
  - Organize IPFS logic in a separate module (e.g., `ipfsService.ts`).
- **Next.js with Typescript**:
  - Use descriptive model names (e.g., `PerspectiveSubmission`).
  - Keep UI components modular (e.g., `FeedbackForm.tsx`).

## Dependencies and Tools
- **Hardhat**: For smart contract development and deployment.
  - Configure for Polygon Amoy (`chainId: 80002`, RPC: `https://rpc-amoy.polygon.technology/`).
- **IPFS-http-client**: For TypeScript-based IPFS interactions.
- **Privado ID SDK**: For ZKP integration (check latest version).
- **Hugging Face Transformers**: For AI analysis (Python).
- **The Graph CLI**: For subgraph deployment.
- **Pinata SDK**: For IPFS pinning.

## Modular Verification System
- The platform must be adaptable to different governments (local, state, country) in the US and internationally.
- Use a modular design where verification methods vary by country.
- Verification is validated per country, not universally.
- For the US:
  - Verify citizenship using Privado ID.
  - Use self-attestation for voter eligibility (e.g., not a disenfranchised felon).
- For other countries, use placeholders or self-attestation until specific methods are added.
- Differentiate user types: "Verified" (citizenship confirmed) vs. "Fully Eligible" (self-attested eligibility).
- The system should support adding new verification methods easily.
- Include legal disclaimers for self-attestation.

## Architectural Preferences
- **Production**: Transition to microservices:
  - Identity Service (Go): Handles Privado ID integration.
  - Feedback Service (Go): Manages submission and blockchain calls.
  - Storage Service (TypeScript): Uploads to IPFS via Pinata.
  - AI Service (Python): Performs off-chain analysis.
  - Indexing Service (AssemblyScript): Updates The Graph subgraph.
- **Decentralization**: 
  - Host frontend on IPFS.
  - Use Polygon PoS smart contracts for core logic.
  - Avoid centralized servers; leverage P2P (e.g., libp2p) if needed.

## Validation and Security
- **Data Authenticity**: 
  - Validate on-chain via `msg.sender` and ZKP proofs.
  - Use events for off-chain verification (e.g., via The Graph).
- **Access Control**: Restrict sensitive methods (e.g., `proposeInsight`) to DAO or moderators.
- **Gas Optimization**: Minimize on-chain storage; use IPFS for large data.

## Suggestions and Comments
- Add detailed comments explaining logic (e.g., "Stores IPFS hash to link off-chain Perspective").
- Suggest gas-efficient alternatives if storage grows (e.g., mappings over arrays).
- Warn if deviating from decentralization (e.g., "Avoid centralized APIs").

## Project Goals
- Ensure suggestions align with decentralization, transparency, and user empowerment.
- Prioritize low-cost operations for grassroots adoption.
- Maintain a focus on intuitive UX for broad accessibility.

# End of Rules