From c433a4acaa8ef8b037ce5fb70238bd553aef49dc Mon Sep 17 00:00:00 2001 From: martinvibes Date: Sun, 21 Sep 2025 09:46:39 +0100 Subject: [PATCH] refactor: update README for improved clarity and structure --- README.md | 208 ++++++++++++++++++++++++++++++++++++++---------------- 1 file changed, 146 insertions(+), 62 deletions(-) diff --git a/README.md b/README.md index 654ffc0..a6c1122 100644 --- a/README.md +++ b/README.md @@ -12,58 +12,59 @@ Traditional voting systems face numerous challenges, including: -- *Lack of Trust:* Concerns about election fraud, tampering, and lack of transparency undermine confidence in results. -- *High Costs:* Organizing and securing traditional voting processes is often expensive and resource-intensive. -- *Accessibility Barriers:* Physical voting locations and paper-based systems exclude many participants due to geographical or mobility constraints. -- *Privacy Issues:* Ensuring voter anonymity while maintaining security is a persistent challenge. -- *Low Engagement:* Without incentives or modernized systems, many people are disengaged from the voting process. +- _Lack of Trust:_ Concerns about election fraud, tampering, and lack of transparency undermine confidence in results. +- _High Costs:_ Organizing and securing traditional voting processes is often expensive and resource-intensive. +- _Accessibility Barriers:_ Physical voting locations and paper-based systems exclude many participants due to geographical or mobility constraints. +- _Privacy Issues:_ Ensuring voter anonymity while maintaining security is a persistent challenge. +- _Low Engagement:_ Without incentives or modernized systems, many people are disengaged from the voting process. ## Solution -DeVote addresses these challenges with an innovative, blockchain-powered platform built on *Starknet*, a Layer 2 Ethereum solution. Our platform ensures: +DeVote addresses these challenges with an innovative, blockchain-powered platform built on _Starknet_, a Layer 2 Ethereum solution. Our platform ensures: -- *Transparency:* All voting records are publicly verifiable on the blockchain, eliminating doubts about integrity. πŸ” -- *Cost-Effectiveness:* Leveraging Starknet reduces transaction costs significantly, making decentralized voting feasible for communities of all sizes. πŸ’° -- *Accessibility:* Users can vote from anywhere with internet access, removing geographical and mobility barriers. 🌐 -- *Privacy and Security:* The project uses hashed IDs to protect voters' identities. This interim measure ensures a secure voting process, with plans to incorporate ZK technology to elevate privacy standards further. πŸ”’ -- *Community Engagement:* We plan to implement an NFT incentive program in the future to reward participants after voting a certain number of times. This feature aims to foster ongoing participation and engagement, contingent on the growth of the project through grants or rewards. πŸ† πŸ† -- *Guidance:* Our goal is to ensure users have the best possible voting experience. That’s why we developed an AI Agent to assist voters, guiding them through the process and addressing any questions they may have along the way. πŸ€– +- _Transparency:_ All voting records are publicly verifiable on the blockchain, eliminating doubts about integrity. πŸ” +- _Cost-Effectiveness:_ Leveraging Starknet reduces transaction costs significantly, making decentralized voting feasible for communities of all sizes. πŸ’° +- _Accessibility:_ Users can vote from anywhere with internet access, removing geographical and mobility barriers. 🌐 +- _Privacy and Security:_ The project uses hashed IDs to protect voters' identities. This interim measure ensures a secure voting process, with plans to incorporate ZK technology to elevate privacy standards further. πŸ”’ +- _Community Engagement:_ We plan to implement an NFT incentive program in the future to reward participants after voting a certain number of times. This feature aims to foster ongoing participation and engagement, contingent on the growth of the project through grants or rewards. πŸ† πŸ† +- _Guidance:_ Our goal is to ensure users have the best possible voting experience. That’s why we developed an AI Agent to assist voters, guiding them through the process and addressing any questions they may have along the way. πŸ€– ## Ways to Implement the Project (Use Cases) -### 1. *Local Governance and Community Projects* +### 1. _Local Governance and Community Projects_ -- *Example:* The community of Tamarindo is set to be the first testers of DeVote, using the platform to decide on local matters such as event hosting, renovations, or budget allocations. -- *Impact:* Increased community involvement, better planning, reduced administrative costs, and enhanced transparency in decision-making. +- _Example:_ The community of Tamarindo is set to be the first testers of DeVote, using the platform to decide on local matters such as event hosting, renovations, or budget allocations. +- _Impact:_ Increased community involvement, better planning, reduced administrative costs, and enhanced transparency in decision-making. -### 2. *Non-Profit Organizations and NGOs* +### 2. _Non-Profit Organizations and NGOs_ - Enable members to vote on key issues such as project funding, leadership elections, or policy changes. -- *Impact:* Empowering diverse members across geographical locations to have an equal say in decision-making.Β  +- _Impact:_ Empowering diverse members across geographical locations to have an equal say in decision-making. -### 3. *Corporate Decision-Making* +### 3. _Corporate Decision-Making_ - Use DeVote to gather employee feedback, conduct shareholder meetings, or decide on company policies. -- *Impact:* Streamlined processes and increased trust in corporate governance.Β  +- _Impact:_ Streamlined processes and increased trust in corporate governance. -### 4. *Educational Institutions* +### 4. _Educational Institutions_ - Allow students, faculty, and stakeholders to vote on matters such as curriculum changes, event planning, or administrative policies. -- *Impact:* Democratized decision-making and better representation of all voices.Β  +- _Impact:_ Democratized decision-making and better representation of all voices. -### 5. *Grassroots Movements and Activism* +### 5. _Grassroots Movements and Activism_ - Provide a secure and anonymous way for activists to vote on initiatives, priorities, or strategies without fear of retaliation. -- *Impact:* Enhanced coordination and collective action.Β  +- _Impact:_ Enhanced coordination and collective action. -### 6. *Collaborative NFT Projects* +### 6. _Collaborative NFT Projects_ - Enable decentralized governance for NFT projects, where holders can vote on roadmap decisions or allocation of funds. -- *Impact:* Building stronger communities around NFT ecosystems while ensuring democratic decision-making.Β  +- _Impact:_ Building stronger communities around NFT ecosystems while ensuring democratic decision-making. --- # Technical Setup For Developers + Ensure that the following tools are installed: - **Node.js** (v18.x or later) @@ -71,6 +72,7 @@ Ensure that the following tools are installed: - **Yarn** (v1.22.x or later) Install via npm: + ```bash npm install -g yarn ``` @@ -92,10 +94,18 @@ Ensure that the following tools are installed: This monorepo is organized as follows: ``` -/ai-agent β†’ AI-specific logic or services -/Backend β†’ Backend services and APIs -/Frontend β†’ Next.js frontend application -/contracts β†’ Starknet smart contracts +/DevoteApp β†’ Next.js frontend application with API routes +β”œβ”€β”€ app/ β†’ Next.js 13+ app router pages and API routes +β”œβ”€β”€ components/ β†’ React components and UI elements +β”œβ”€β”€ hooks/ β†’ Custom React hooks +β”œβ”€β”€ lib/ β†’ Utility functions and services +β”œβ”€β”€ models/ β†’ MongoDB/Mongoose schemas +β”œβ”€β”€ interfaces/ β†’ TypeScript interfaces +└── public/ β†’ Static assets + +/CairoContracts β†’ Starknet smart contracts (Cairo) +β”œβ”€β”€ src/ β†’ Cairo contract source files +└── Scarb.toml β†’ Scarb configuration ``` --- @@ -113,64 +123,90 @@ cd ### 2️⃣ Install Dependencies -Using Yarn, install all required packages: +Navigate to the DevoteApp directory and install dependencies: ```bash +cd DevoteApp yarn install ``` -> This command installs all dependencies defined in the root and nested `package.json` files. +> This installs all required packages for the Next.js application. ### 3️⃣ Configuration Instructions -Create a `.env.local` file in the root or inside the `Frontend/` directory: +Create a `.env.local` file in the `DevoteApp/` directory with the following variables: ```env -NEXT_PUBLIC_API_URL=http://localhost:3000/api -DATABASE_URL=postgresql://user:password@localhost:5432/devotedb -STARKNET_RPC_URL=http://localhost:5050 -# Add other required variables +# Database Configuration +MONGO_URI=mongodb://localhost:27017/devote + +# Email Configuration (for user notifications) +EMAIL_SMTP_HOST=smtp.gmail.com +EMAIL_SMTP_PORT=587 +EMAIL_SMTP_SECURE=false +EMAIL_USER=your-email@gmail.com +EMAIL_PASS=your-app-password + +# Frontend URL +FRONTEND_URL=http://localhost:3000 + +# OpenAI Configuration (for AI Agent) +OPENAI_API_KEY=your-openai-api-key + +# KYC/SumSub Configuration (for identity verification) +SUMSUB_TOKEN=your-sumsub-app-token +SUMSUB_API_KEY=your-sumsub-secret-key +NEXT_PUBLIC_SUMSUB_ACCESS_TOKEN=your-sumsub-access-token + +# Starknet Wallet Configuration (for admin operations) +NEXT_PUBLIC_DEVOTE_PUBLIC_WALLET=your-devote-wallet-address +NEXT_PUBLIC_DEVOTE_SECRET_KEY_ENCRYPTED=your-encrypted-private-key + +# Secret Token (for admin access) +NEXT_PUBLIC_SECRET_TOKEN=your-secret-admin-token ``` -### 4️⃣ Database Setup (if applicable) +> **Note:** Replace all placeholder values with your actual credentials. Some services like SumSub and OpenAI require account setup. -If the project uses PostgreSQL: +### 4️⃣ Database Setup -- Ensure PostgreSQL is running. -- Apply migrations: - ```bash - yarn db:migrate - ``` +The project uses MongoDB. Ensure MongoDB is running locally or use MongoDB Atlas: + +**Local MongoDB:** + +- Install and start MongoDB locally +- The connection string should be: `mongodb://localhost:27017/devote` + +**MongoDB Atlas (Cloud):** + +- Create a free account at [MongoDB Atlas](https://www.mongodb.com/cloud/atlas) +- Create a new cluster and get your connection string +- Update `MONGO_URI` in your `.env.local` file ### 5️⃣ Smart Contract Setup -To deploy and interact with Starknet smart contracts: +To work with the Cairo contracts: ```bash -cd contracts -starknet-compile contract.cairo --output contract.json -starknet deploy --contract contract.json +cd CairoContracts +scarb build # Compile contracts +scarb test # Run tests ``` --- ## ▢️ Running the Application -### Run the **Frontend** +### Run the **Next.js Application** ```bash -cd Frontend +cd DevoteApp yarn dev ``` πŸ“ Visit: `http://localhost:3000` -### Run the **Backend** - -```bash -cd Backend -yarn start -``` +> The application includes both frontend and API routes in a single Next.js app. ### Run the **Starknet Devnet** (for smart contracts testing) @@ -180,17 +216,60 @@ starknet-devnet --host 127.0.0.1 --port 5050 --- +## πŸ‘€ Demo User Setup + +### Creating a Demo User + +To test the application, you can create a demo user through the admin interface: + +1. **Access Admin Panel:** + + ``` + http://localhost:3000/secret?token=YOUR_SECRET_TOKEN + ``` + + Replace `YOUR_SECRET_TOKEN` with the value you set in `NEXT_PUBLIC_SECRET_TOKEN` + +2. **Create Super User:** + + - Fill out the form with: + - Email: `demo@example.com` + - Full Name: `Demo User` + - INE: `123456789` (demo ID) + - Password: `demo123` + - Click "Create Superuser" + - Fund the generated wallet with Sepolia ETH using the [Starknet Faucet](https://starknet-faucet.vercel.app/) + +3. **Alternative: Test Login Page:** + ``` + http://localhost:3000/test-login + ``` + This page allows you to generate test wallets and deploy them for testing purposes. + +### Demo User Credentials + +- **Email:** `demo@example.com` +- **Password:** `demo123` +- **Wallet:** Auto-generated and deployed during creation +- **Status:** Admin user with full permissions + +> **Note:** The demo user will have admin privileges and can create proposals, manage users, and oversee voting processes. + +--- + ## πŸ§ͺ Running Tests To run tests for different components: -- Frontend: +- Next.js Application: ```bash + cd DevoteApp yarn test ``` -- Smart Contracts: +- Cairo Smart Contracts: ```bash - starknet test + cd CairoContracts + scarb test ``` --- @@ -200,7 +279,7 @@ To run tests for different components: Ensure code consistency: ```bash -yarn format +cd DevoteApp yarn lint ``` @@ -209,15 +288,20 @@ yarn lint ## πŸ›‘ Troubleshooting ### Common Issues: -- **Port conflicts** β†’ Ensure no other services are running on required ports. -- **Database errors** β†’ Verify PostgreSQL is running and credentials are correct. + +- **Port conflicts** β†’ Ensure no other services are running on port 3000. +- **Database errors** β†’ Verify MongoDB is running and connection string is correct. +- **Environment variables** β†’ Check that all required variables are set in `.env.local`. +- **Email issues** β†’ Verify SMTP credentials and ensure 2FA is disabled or using app passwords. +- **KYC/SumSub errors** β†’ Ensure SumSub credentials are valid and account is active. - **Smart contract issues** β†’ Restart Starknet Devnet and redeploy contracts. --- + ## 🧭 You're all set! You’re now ready to explore and contribute to the DEVOTE project. Happy coding! πŸ’»βœ¨ 🌟 DeVote is not just a dApp but a movement towards creating a world where every voice matters and decisions are made collectively, transparently, and securely. -**Trust. Vote. Transform.** \ No newline at end of file +**Trust. Vote. Transform.**