cRepute: On-Chain Reputation & Reviews on Celo

cRepute is a decentralized reputation and review system built on the Celo blockchain. It serves as a trust layer for dApps, marketplaces, and services, allowing users to leave ratings and reviews for any Ethereum address. Designed with security, auditability, and extensibility in mind, cRepute provides transparent, on-chain reputation data that can be easily integrated into frontend applications.

🚀 Features

• Decentralized Reviews: Any address can review any other address with ratings (1-5 stars) and text comments.
• One Review Per Pair: Each reviewer-subject pair maintains a single review, with updates allowed.
• On-Chain Aggregation: Automatic calculation of average ratings and review statistics.
• Celo Optimized: Built for the Celo ecosystem with gas-efficient operations.
• Audit-Ready: Clean, secure Solidity code following Cyfrin best practices.
• Extensible Design: Easy to integrate with dApps for booking, marketplaces, or social platforms.

📋 Table of Contents

• Overview
• Architecture
• Data Flow
• Smart Contract API
• Installation
• Development
• Testing
• Deployment
• Integration Guide
• Security
• Contributing
• License

📖 Overview

cRepute enables transparent reputation building on Celo by storing reviews immutably on-chain. Each subject (address) accumulates reviews from multiple reviewers, with aggregated statistics available for dApp integration.

Key Concepts

• Subject: The address being reviewed (e.g., a seller, service provider).
• Reviewer: The address leaving the review.
• Review: Contains rating (1-5), comment, context, and timestamps.
• Stats: Per-subject aggregation of total reviews, sum of ratings, and last update time.

Use Cases

• Marketplaces: Rate sellers and buyers.
• Service Platforms: Review freelancers or providers.
• Social dApps: Build user reputation.
• Booking Systems: Rate accommodations or experiences.

🏗️ Architecture

cRepute follows a modular, secure architecture optimized for the Celo network.

System Components

┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│   Frontend      │    │  Smart Contract  │    │   Off-Chain     │
│   dApp          │◄──►│    cRepute.sol   │    │   Indexing      │
│                 │    │                  │    │   (Optional)    │
└─────────────────┘    └──────────────────┘    └─────────────────┘
         │                       │                       │
         └───────────────────────┼───────────────────────┘
                                 ▼
                    ┌─────────────────────┐
                    │   Celo Blockchain   │
                    │   (Alfajores/Main)  │
                    └─────────────────────┘

Smart Contract Structure

• State Variables: Secure storage with s_ prefix for private mappings.
• Functions: External/public for interactions, view/pure for reads.
• Events: Indexed for efficient off-chain monitoring.
• Errors: Custom errors for gas-efficient reverts.

Data Model

struct Review {
    address reviewer;
    address subject;
    uint8 rating;      // 1-5
    string comment;
    string context;    // e.g., "Marketplace", orderId
    uint256 createdAt;
    uint256 updatedAt;
}

struct SubjectStats {
    uint256 totalReviews;
    uint256 sumRatings;
    uint256 lastUpdated;
}

🔄 Data Flow

sequenceDiagram
    participant User
    participant Frontend
    participant cRepute
    participant Blockchain

    User->>Frontend: Submit Review
    Frontend->>cRepute: submitReview(subject, rating, comment, context)
    cRepute->>cRepute: Validate inputs
    cRepute->>cRepute: Update/Create review
    cRepute->>cRepute: Update subject stats
    cRepute->>Blockchain: Emit ReviewCreated/Updated
    cRepute->>Frontend: Transaction confirmed
    Frontend->>User: Review submitted

    User->>Frontend: View Reputation
    Frontend->>cRepute: getSubjectStats(subject)
    Frontend->>cRepute: getAverageRating(subject)
    cRepute->>Frontend: Return aggregated data
    Frontend->>User: Display reputation

Loading

Review Submission Flow

1. Validation: Check rating range, non-zero subject, non-empty comment.
2. Existence Check: Determine if new review or update.
3. Storage Update: Save review data and update statistics.
4. Event Emission: Notify off-chain listeners.
5. Confirmation: Return success to user.

🔧 Smart Contract API

Core Functions

Write Functions

• submitReview(address subject, uint8 rating, string comment, string context): Submit or update a review.
• deleteReview(address subject): Delete own review for a subject.

Read Functions

• getReview(uint256 reviewId): Get review by ID.
• getReviewFor(address subject, address reviewer): Get review for pair.
• getSubjectStats(address subject): Get aggregated stats.
• getAverageRating(address subject): Get average rating with 18 decimals.
• getNextReviewId(): Get next review ID for iteration.

Events

• ReviewCreated(uint256 reviewId, address subject, address reviewer, uint8 rating)
• ReviewUpdated(uint256 reviewId, address subject, address reviewer, uint8 rating)
• ReviewDeleted(uint256 reviewId, address subject, address reviewer)

Errors

• cRepute__InvalidRating(): Rating outside 1-5 range.
• cRepute__ZeroAddressSubject(): Subject is zero address.
• cRepute__ReviewDoesNotExist(): Review not found.
• cRepute__EmptyCommentNotAllowed(): Comment is empty.

🛠️ Installation

Prerequisites

• Foundry (latest version)
• Node.js (for frontend integration)
• Git

Clone Repository

git clone <repository-url>
cd cRepute

Install Dependencies

forge install

💻 Development

Build Contract

forge build

Run Tests

forge test

Format Code

forge fmt

Gas Analysis

forge snapshot

🧪 Testing

cRepute includes comprehensive tests covering:

• Happy path: Creating and updating reviews
• Edge cases: Invalid inputs, zero addresses
• Security: Access controls, reentrancy protection
• Math: Correct average calculations

# Run all tests
forge test

# Run specific test
forge test --match testSubmitReviewCreatesNewReview

# Run with gas reporting
forge test --gas-report

🚀 Deployment

Local Development

# Start local Celo node (or use Anvil)
anvil

# Deploy to local
forge script script/DeploycRepute.s.sol --rpc-url http://localhost:8545 --private-key <your-key> --broadcast

Celo Testnet (Alfajores)

# Deploy to Alfajores
forge script script/DeploycRepute.s.sol --rpc-url https://alfajores-forno.celo-testnet.org --private-key <your-key> --broadcast --verify

Celo Mainnet

# Deploy to Mainnet
forge script script/DeploycRepute.s.sol --rpc-url https://forno.celo.org --private-key <your-key> --broadcast --verify

Note: Replace <your-key> with your deployer private key. Never commit private keys to version control.

🔗 Integration Guide

Frontend Integration

// Connect to contract
const contract = new ethers.Contract(address, abi, signer);

// Submit review
await contract.submitReview(subjectAddress, 5, "Excellent service!", "Marketplace");

// Get reputation
const stats = await contract.getSubjectStats(subjectAddress);
const average = await contract.getAverageRating(subjectAddress);

Off-Chain Indexing

For efficient queries, consider indexing events with:

• The Graph Protocol
• Covalent API
• Custom indexer

dApp Examples

• Marketplace: Display seller ratings on product pages.
• Booking: Show host reputation in listings.
• Social: User profiles with reputation scores.

🔒 Security

cRepute is designed with security as priority:

• Input Validation: Comprehensive checks on all inputs.
• Access Control: Only reviewers can modify their reviews.
• Gas Optimization: Efficient storage and computation.
• Audit-Ready: Clean code following Solidity best practices.

Known Limitations

• No built-in spam protection (consider rate limiting in dApps).
• No moderation system (reviews are permanent).
• Gas costs scale with review length.

Future Enhancements

• Tokenized reputation (ERC-20 integration).
• Proof-of-payment gating.
• Off-chain storage for long comments.
• Multi-signature moderation.

🤝 Contributing

We welcome contributions! Please follow these steps:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit changes (git commit -m 'Add amazing feature')
4. Push to branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Development Guidelines

• Follow Cyfrin Solidity style guide
• Write comprehensive tests for new features
• Update documentation
• Ensure all tests pass

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• Built with Foundry
• Inspired by Cyfrin Updraft courses
• Designed for the Celo ecosystem

---

See where you stand

The leaderboard updates daily and tracks your activity across: • Your project impact on KarmaGAP • Judge scores given at the end of the month • Engagement in the Celo channel on Farcaster

Check out the guide to get the most out of your activity. $ forge script script/Counter.s.sol:CounterScript --rpc-url <your_rpc_url> --private-key <your_private_key>

### Cast

```shell
$ cast <subcommand>

Help

$ forge --help
$ anvil --help
$ cast --help