Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
241 lines (171 loc) · 6.6 KB

CONTRIBUTING.md

File metadata and controls

241 lines (171 loc) · 6.6 KB
Raw

Contributing to Mesh Contract

Thank you for your interest in contributing to Mesh Contract! This document outlines the process for contributing to the smart contract layer of the ThinkMesh ecosystem.

📋 Table of Contents

Code of Conduct

This project adheres to a code of conduct. By participating, you agree to uphold these values:

  • Respectful collaboration — All contributors deserve respect
  • Quality over quantity — We value well-tested, documented code
  • Security first — Smart contracts handle real funds; safety is non-negotiable

Getting Started

Prerequisites

  • Node.js >= 18.0.0
  • npm or yarn
  • Git

Setup

# Fork and clone
git clone https://github.com/YOUR_USERNAME/mesh-contract.git
cd mesh-contract

# Install dependencies
npm install

# Set up environment
cp .env.example .env
# Fill in .env with your testnet private key and RPC URLs

# Compile to verify setup
npm run compile

# Run tests to confirm everything works
npm test

Development Workflow

Branch Naming

feat/description-of-feature
fix/description-of-fix
docs/what-you-are-documenting
test/what-you-are-testing
chore/maintenance-task

Making Changes

  1. Create a branch from main
  2. Write your code with NatSpec documentation
  3. Write tests (coverage must stay above 95%)
  4. Run the full test suite: npm test
  5. Run static analysis: npm run slither (if available)
  6. Open a Pull Request

Smart Contract Standards

NatSpec Documentation

All public and external functions must include NatSpec:

/// @title ThinkToken
/// @notice ERC-20 reward token for ThinkMesh contributors
/// @dev Mintable by authorized roles only; implements ERC-20 + ERC-20Permit
contract ThinkToken {
    /// @notice Mint tokens to a contributor address
    /// @dev Only callable by MINTER_ROLE
    /// @param to The recipient address
    /// @param amount The amount of tokens to mint (18 decimals)
    function mint(address to, uint256 amount) external onlyRole(MINTER_ROLE) {
        _mint(to, amount);
    }
}

Code Style

Security Patterns

  • ✅ Use ReentrancyGuard for functions handling ETH/tokens
  • ✅ Use AccessControl or Ownable for privileged functions
  • ✅ Use Pausable for emergency stops
  • ✅ Use OpenZeppelin's Address.sendValue not raw .call
  • ❌ Never use tx.origin for authentication
  • ❌ Never store sensitive data on-chain

Testing Requirements

Coverage must remain above 95%. Run:

npm run coverage

Test Structure

Each contract should have a corresponding test file:

test/
├── ThinkToken.test.ts
├── ReputationRegistry.test.ts
├── ImpactNFT.test.ts
├── MeshDAO.test.ts
└── BountyEscrow.test.ts

Test Checklist

For every function, cover:

  • ✅ Happy path (success)
  • ✅ Access control (unauthorized callers revert)
  • ✅ Edge cases (zero amounts, max values)
  • ✅ Events emitted
  • ✅ State changes verified

Pull Request Process

  1. Fill out the PR template completely
  2. Link the relevant issue using Closes #issue-number
  3. Ensure CI passes — all checks must be green
  4. Request review from at least one core contributor
  5. Address all review comments before merge

PR Checklist

  • NatSpec documentation on all new public/external functions
  • Tests written and passing (npm test)
  • Coverage stays above 95% (npm run coverage)
  • No compiler warnings
  • .env.example updated if new env vars added
  • CHANGELOG.md updated (for non-trivial changes)

Security

Reporting Vulnerabilities

Do NOT open public GitHub issues for security vulnerabilities.

Email: security@thinkmesh.io

Include:

  • Description of the vulnerability
  • Steps to reproduce
  • Potential impact
  • Suggested fix (optional)

We will respond within 48 hours and coordinate responsible disclosure.

Bug Bounty

A formal bug bounty program is coming. For now, critical vulnerabilities discovered before mainnet launch will be acknowledged with THINK token grants upon launch.

🌐 Internationalization (i18n) Support

We use Mozilla Fluent for managing puzzle text, CLI prompts, hints, error messages, and TUI labels. Contributors can easily add support for new languages without modifying game logic.

How to Add a New Locale

  1. Locate the locales directory: Navigate to contracts/puzzle/locales/.

  2. Create a new .ftl file: Name your file using standard ISO 639-1 language codes (e.g., de.ftl for German, ja.ftl for Japanese, pt.ftl for Portuguese).

  3. Copy and translate keys: Copy string definitions from contracts/puzzle/locales/en.ftl and translate values into your target language. Preserve variable parameters like {$lang} or {$code}.

    Example (de.ftl):

    welcome-title = Willkommen zur Mesh-Rätsel-Herausforderung!
puzzle-prompt = Lösen Sie das Rätsel: Finden Sie den versteckten Hash-Schlüssel.

  4. Register the locale in contracts/puzzle/src/lib.rs: Add the locale code and resource file mapping to the LOCALES array:

    const LOCALES: &[(&str, &str)] = &[
    ("en", include_str!("../locales/en.ftl")),
    ("fr", include_str!("../locales/fr.ftl")),
    ("es", include_str!("../locales/es.ftl")),
    ("de", include_str!("../locales/de.ftl")), // <-- Add your new locale here
];

  5. Test your new locale: Run the CLI with your locale code:

    cargo run -p mesh-puzzle -- --lang de

If any keys are missing in your translation file, the i18n system automatically falls back to English (en).

💧 Support via Drips

If you find this project valuable, consider funding it through Drips. Wave 1 is active — your streaming contribution helps us ship audited contracts faster.

Thank you for helping build the on-chain backbone of collaborative problem solving! 🚀