Dynamic Reputation Token as a Real-World Asset (RWA)

If you find our work valuable, please consider giving us a star on GitHub!

---

Quick Start

This repository is a Hardhat-based boilerplate. To get started and generate the deployment scripts for this two-contract system, follow these steps:

1. Clone & Install:

   git clone https://github.com/ecolab-web3/dynamicreputationtoken-rwa-solidity.git
   cd dynamicreputationtoken-rwa-solidity
   npm install

2. Configure Your Environment:

   • This project requires an .env file with a private key and RPC URL.
   • Rename the .env.example file in the root directory to .env.
   • Open the new .env file and add your test wallet's private key.

3. Understand the Contract (Recommended):

   • Before deploying, take a moment to read the rest of this README and browse the contracts/ folder.
   • Understanding the smart contract's logic, its functions, and its purpose is a critical step for any developer.

4. Deploy the NFT Contract:

   • Fund your test wallet with some Fuji AVAX from a faucet.
   • Run the first deployment script:

   npx hardhat run scripts/01-deployNft.ts --network fuji

   • Copy the ServicesReputationNFT address printed in the terminal.

5. Deploy the Reputation Contract:

   • Open the file scripts/02-deployReputation.ts.
   • Paste the NFT contract address from the previous step into the nftContractAddress variable.
   • Save the file and run the second script:

   npx hardhat run scripts/02-deployReputation.ts --network fuji

   • Copy the DYNAMICREPUTATIONTOKEN_RWA address printed in the terminal.

6. Configure Permissions:

• Open the file scripts/03-configurePermissions.ts.
• Paste both contract addresses into the corresponding variables.
• Save the file and run the final script:

  npx hardhat run scripts/03-configurePermissions.ts --network fuji

Your Dynamic Reputation system is now fully deployed and configured on the Fuji Testnet.

---

Official E-co.lab Links

• Official Website: ecolab-web3.github.io
• Whitepaper: e-co-lab.gitbook.io/whitepaper
• Discord Community: discord.gg/mrSuw8AfjC
• Twitter: x.com/ecolab_web3

---

About The Project

This repository contains a smart contract ecosystem that tokenizes user reputation as a dynamic, non-transferable Real-World Asset (RWA). It's designed to solve the problem of platform-locked reputation in the gig economy, freelancer marketplaces, and other service-based platforms.

This project has been successfully migrated to a professional Hardhat environment, rigorously tested, deployed, and verified on the Avalanche Fuji Testnet.

---

Live Interaction & dApps

Please make sure your wallet (e.g., MetaMask) is connected to the Avalanche Fuji Testnet to interact with the project components.

dApp Prototypes

• Rating Portal (for Customers): This interface allows a customer to submit a rating for a service provider, which directly impacts their on-chain reputation.

  • ➡️ Access the Rating Portal (english version)
  • ➡️ Acesse o Portal de Avaliação (versão em português)

• Provider Dashboard: This dashboard allows service providers to view their dynamic reputation score and claim their monthly achievement NFTs.

  • ➡️ Access the Provider Dashboard (english version)
  • ➡️ Acesse o Painel do Prestador (versão em português)

Contract Details

1. Main Reputation Contract (DYNAMICREPUTATIONTOKEN_RWA.sol)

This is the core contract that calculates dynamic reputation scores and allows users to claim achievement awards.

• Address: 0x1c6e9aF609eD270AA0120118fFA5e4f26d2D96E7
• Interact: Read / Write on Snowtrace

2. Achievement NFT Contract (SERVICESREPUTATIONNFT_RWA.sol)

This ERC721 contract mints the monthly achievement "trophies". Its owner has been set to the Main Reputation Contract, ensuring only it can award NFTs.

• Address: 0x0e735190BdB2f4EdB6503ee85309fa0fB1D54793
• Interact: Read on Snowtrace

---

Development Environment & Testing

This project was migrated from Remix IDE to a professional Hardhat environment to ensure quality and reproducibility.

• Framework: Hardhat
• Solidity Version: 0.8.20
• Testing: A comprehensive test suite was developed using ethers.js and Chai. The suite consists of 12 passing tests covering the entire ecosystem.

Test Coverage

The project achieved the highest possible practical test coverage across its two contracts.

File	% Stmts	% Branch	% Funcs	% Lines
DYNAMICREPUTATIONTOKEN_RWA.sol	96.30	91.67	100	100
SERVICESREPUTATIONNFT_RWA.sol	100	100	100	100
All files	96.55	92.86	100	100

Note on Code Coverage: The coverage tool correctly identifies a logical branch related to division-by-zero that is not covered in DYNAMICREPUTATIONTOKEN_RWA.sol. This is intentional and a feature of the code's safety. The contract includes an explicit check if (providerReputation.ratingCount == 0) which prevents the division from ever occurring. This makes the compiler's built-in "Panic" error for division-by-zero unreachable. Therefore, while the coverage is not a perfect 100%, the test suite fully covers all reachable logic paths in the contract.

---

Overview

The core idea is to transform a service provider's reputation into a Soulbound Token (SBT) whose balance dynamically reflects their real-world service quality. High performance is further rewarded with unique, collectible Achievement NFTs. This reputation is owned by the user, is verifiable on-chain, and is portable across any platform that integrates with the system.

Key Concepts Implemented

• Two-Contract Architecture: A main contract handles the dynamic reputation logic, while a separate ERC721 contract issues achievement awards.
• Dynamic Balance: The balanceOf function calculates a provider's reputation score in real-time based on their average rating.
• Monthly Achievement NFTs: High-performing providers (average score ≥ 4.9) can call the claimMonthlyAchievement function to mint a unique, timestamped NFT.
• Soulbound & Non-Transferable: The reputation score itself cannot be transferred, ensuring it is earned, not bought.

---

Next Steps

This prototype is a functional foundation. For a production-ready system, the next steps focus on usability, data integrity, and security.

1. Implement an Upgradable Contract using the Proxy Pattern

To allow for future feature additions or bug fixes without requiring a full migration, the next logical step is to implement an upgradable contract using OpenZeppelin's Upgrades Contracts.

2. Enhance the dApp Ecosystem

The current dApps are functional prototypes. A production version would require enhancing them with a modern framework and adding features:

• Enhance Rating Portal: Improve user feedback with modals and notifications.
• Enhance Provider Dashboard: Add features like a gallery to showcase the achievement NFTs and a detailed history of ratings received.

3. Implement Strict Access Control for Ratings

The addRating function is currently public for demonstration. A real-world implementation would require a secure mechanism (e.g., using signed messages, or NFT-based "proof-of-service" receipts) to ensure only legitimate customers can submit ratings, preventing spam and manipulation.

4. Undergo a Professional Security Audit

Before any mainnet deployment, a full audit by a reputable third-party security firm is essential to ensure the safety and integrity of the system.

---

Ecosystem Recognition

E-co.lab is a recognized participant in the Avalanche Retro9000 program, a retroactive public goods funding initiative by the Avalanche Foundation. Our project has been approved for the "L1s & Infrastructure Tooling" round and is currently live for community voting by participants in the Avalanche ecosystem.

You can view our official submission and support our mission here: E-co.lab on Retro9000

---

Contributing

Contributions are what make the open-source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.

Please feel free to fork the repo and create a pull request, or open an issue with the tag "enhancement".

---

License

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