diff --git a/.github/ISSUE_TEMPLATE.md b/.github/ISSUE_TEMPLATE.md new file mode 100644 index 0000000..fd70371 --- /dev/null +++ b/.github/ISSUE_TEMPLATE.md @@ -0,0 +1,87 @@ +--- +name: Bug Report / Feature Request +about: Create a report to help us improve or suggest a new feature +title: '[TYPE] Brief description' +labels: '' +assignees: '' +--- + +## Issue Type + +- [ ] Bug Report +- [ ] Feature Request +- [ ] Documentation Update +- [ ] Question + +--- + +## For Bug Reports + +### Description +A clear and concise description of what the bug is. + +### Steps to Reproduce +1. Go to '...' +2. Click on '...' +3. Scroll down to '...' +4. See error + +### Expected Behavior +A clear and concise description of what you expected to happen. + +### Actual Behavior +A clear and concise description of what actually happened. + +### Screenshots +If applicable, add screenshots to help explain your problem. + +### Environment +- **OS**: [e.g., macOS 13.0, Ubuntu 22.04, Windows 11] +- **Browser** (if applicable): [e.g., Chrome 120, Firefox 121] +- **Node.js version**: [e.g., 20.10.0] +- **Python version**: [e.g., 3.11.5] +- **Project component**: [Backend / Frontend / Contracts] + +### Additional Context +Add any other context about the problem here. + +--- + +## For Feature Requests + +### Problem Statement +A clear and concise description of the problem you're trying to solve. +Ex. I'm always frustrated when [...] + +### Proposed Solution +A clear and concise description of what you want to happen. + +### Alternative Solutions +A clear and concise description of any alternative solutions or features you've considered. + +### Benefits +Describe the benefits of implementing this feature. +- Who will benefit? +- How will it improve the project? + +### Additional Context +Add any other context, screenshots, or examples about the feature request here. + +--- + +## Checklist + +- [ ] I have searched existing issues to avoid duplicates +- [ ] I have provided all relevant information +- [ ] I have added appropriate labels (if I have permission) +- [ ] I have read the [Contributing Guidelines](../CONTRIBUTING.md) +- [ ] For bugs: I can reproduce this issue consistently +- [ ] For features: I have considered the implementation complexity + +--- + +## Related Issues + +- Related to # +- Blocks # +- Blocked by # diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md new file mode 100644 index 0000000..1f0532e --- /dev/null +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -0,0 +1,143 @@ +## Description + + +### What does this PR do? + + +### Why is this change needed? + + +### How has this been tested? + + +--- + +## Type of Change + +- [ ] Bug fix (non-breaking change which fixes an issue) +- [ ] New feature (non-breaking change which adds functionality) +- [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected) +- [ ] Documentation update +- [ ] Code refactoring +- [ ] Performance improvement +- [ ] Test addition/update +- [ ] CI/CD change +- [ ] Dependency update + +--- + +## Checklist + + +### Code Quality +- [ ] My code follows the project's coding standards +- [ ] I have performed a self-review of my own code +- [ ] I have commented my code, particularly in hard-to-understand areas +- [ ] My changes generate no new warnings or errors +- [ ] I have removed any debugging code or console logs + +### Testing +- [ ] I have added tests that prove my fix is effective or that my feature works +- [ ] New and existing unit tests pass locally with my changes +- [ ] I have run the linters and they pass (`npm run lint`, `ruff check`) +- [ ] I have run the formatters (`npm run format`, `ruff format`) + +### Backend Specific (if applicable) +- [ ] Backend tests pass (`pytest`) +- [ ] Python code follows PEP 8 standards +- [ ] Type hints are added for new functions +- [ ] API changes are backward compatible (or breaking changes are documented) + +### Frontend Specific (if applicable) +- [ ] Frontend tests pass (`npm test`) +- [ ] TypeScript type checking passes (`npm run type-check`) +- [ ] Build succeeds (`npm run build`) +- [ ] UI changes are responsive and accessible +- [ ] Screenshots are included for UI changes + +### Smart Contracts Specific (if applicable) +- [ ] Contract tests pass (`npm test`) +- [ ] Contracts compile without warnings (`npm run compile`) +- [ ] Gas optimization has been considered +- [ ] Security best practices have been followed +- [ ] NatSpec documentation is complete + +### Documentation +- [ ] I have updated the documentation accordingly +- [ ] I have updated the README if needed +- [ ] I have added/updated code comments where necessary +- [ ] API documentation is updated (if applicable) + +### Security +- [ ] I have considered security implications of my changes +- [ ] I have not committed any secrets or credentials +- [ ] Dependencies are up to date and have no known vulnerabilities +- [ ] Input validation is implemented where needed +- [ ] No SQL injection, XSS, or other common vulnerabilities introduced + +### Git & PR Hygiene +- [ ] My branch is up to date with the base branch +- [ ] I have resolved any merge conflicts +- [ ] Commit messages follow the [Conventional Commits](https://www.conventionalcommits.org/) specification +- [ ] I have read the [Contributing Guidelines](../CONTRIBUTING.md) +- [ ] I have linked related issues (if applicable) + +--- + +## Related Issues + +Closes # +Fixes # +Related to # + +--- + +## Screenshots (if applicable) + + +### Before + + +### After + + +--- + +## Breaking Changes + + + +**Does this PR introduce breaking changes?** +- [ ] Yes +- [ ] No + + + +--- + +## Additional Notes + + +### Performance Impact + + +### Deployment Notes + + +### Future Work + + +--- + +## Reviewer Notes + + +--- + +## PR Author Checklist + +- [ ] I have filled out all relevant sections of this template +- [ ] I have marked all completed checklist items +- [ ] I have assigned appropriate reviewers +- [ ] I have added appropriate labels +- [ ] CI checks are passing diff --git a/.github/workflows/codeql.yml b/.github/workflows/codeql.yml new file mode 100644 index 0000000..576d50a --- /dev/null +++ b/.github/workflows/codeql.yml @@ -0,0 +1,78 @@ +name: "CodeQL Security Analysis" + +on: + push: + branches: [ main, develop ] + pull_request: + branches: [ main, develop ] + schedule: + # Run CodeQL analysis every Monday at 00:00 UTC + - cron: '0 0 * * 1' + workflow_dispatch: + +permissions: + contents: read + +jobs: + analyze: + name: Analyze (${{ matrix.language }}) + runs-on: ubuntu-latest + timeout-minutes: 360 + permissions: + # Required for all workflows + security-events: write + # Required to fetch internal or private CodeQL packs + packages: read + # Required for workflows in private repositories + actions: read + contents: read + + strategy: + fail-fast: false + matrix: + # CodeQL supports: 'c-cpp', 'csharp', 'go', 'java-kotlin', 'javascript-typescript', 'python', 'ruby', 'swift' + # Learn more about CodeQL language support at https://aka.ms/codeql-docs/language-support + language: [ 'javascript-typescript', 'python' ] + # Add 'solidity' analysis if using third-party Solidity analyzer + + steps: + - name: Checkout repository + uses: actions/checkout@v4 + + # Initializes the CodeQL tools for scanning + - name: Initialize CodeQL + uses: github/codeql-action/init@v3 + with: + languages: ${{ matrix.language }} + # If you wish to specify custom queries, you can do so here or in a config file. + # By default, queries listed here will override any specified in a config file. + # Prefix the list here with "+" to use these queries and those in the config file. + # For more details on CodeQL's query packs, refer to: https://docs.github.com/en/code-security/code-scanning/automatically-scanning-your-code-for-vulnerabilities-and-errors/configuring-code-scanning#using-queries-in-ql-packs + # queries: security-extended,security-and-quality + + # Autobuild attempts to build any compiled languages (C/C++, C#, Go, Java, or Swift). + # If this step fails, then you should remove it and run the build manually + - name: Autobuild + uses: github/codeql-action/autobuild@v3 + + # ℹī¸ Command-line programs to run using the OS shell. + # 📚 See https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idstepsrun + + # If the Autobuild fails above, remove it and uncomment the following three lines. + # modify them (or add more) to build your code if your project, please refer to the EXAMPLE below for guidance. + + # - name: Build Python + # if: matrix.language == 'python' + # run: | + # pip install -r backend/requirements.txt + + # - name: Build JavaScript/TypeScript + # if: matrix.language == 'javascript-typescript' + # run: | + # cd frontend && npm ci && npm run build + # cd ../contracts && npm ci && npm run compile + + - name: Perform CodeQL Analysis + uses: github/codeql-action/analyze@v3 + with: + category: "/language:${{matrix.language}}" diff --git a/.github/workflows/dependency-review.yml b/.github/workflows/dependency-review.yml new file mode 100644 index 0000000..b478ec8 --- /dev/null +++ b/.github/workflows/dependency-review.yml @@ -0,0 +1,34 @@ +name: Dependency Review + +on: + pull_request: + branches: [ main, develop ] + +permissions: + contents: read + +jobs: + dependency-review: + name: Dependency Review + runs-on: ubuntu-latest + permissions: + contents: read + pull-requests: write + + steps: + - name: Checkout code + uses: actions/checkout@v4 + + - name: Dependency Review + uses: actions/dependency-review-action@v4 + with: + # Fail the action if vulnerabilities are found + fail-on-severity: moderate + # Allow licenses (customize based on your requirements) + # deny-licenses: GPL-2.0, LGPL-2.0 + # Comment on PR with dependency changes + comment-summary-in-pr: always + # Configuration options: + # fail-on-scopes: runtime, development + # vulnerability-check: true + # license-check: true diff --git a/.github/workflows/deploy.yml b/.github/workflows/deploy.yml new file mode 100644 index 0000000..25db20f --- /dev/null +++ b/.github/workflows/deploy.yml @@ -0,0 +1,176 @@ +name: Deploy + +on: + push: + branches: [ main ] + workflow_dispatch: + inputs: + environment: + description: 'Deployment environment' + required: true + type: choice + options: + - dev + - stage + - prod + default: 'dev' + +permissions: + contents: read + id-token: write # Required for OIDC authentication + +jobs: + deploy: + name: Deploy to ${{ inputs.environment || 'dev' }} + runs-on: ubuntu-latest + environment: + name: ${{ inputs.environment || 'dev' }} + permissions: + contents: read + id-token: write + + steps: + - name: Checkout code + uses: actions/checkout@v4 + + - name: Setup Node.js + uses: actions/setup-node@v4 + with: + node-version: '20' + cache: 'npm' + cache-dependency-path: frontend/package-lock.json + + - name: Setup Python + uses: actions/setup-python@v5 + with: + python-version: '3.11' + cache: 'pip' + cache-dependency-path: backend/requirements.txt + + # OIDC Authentication Placeholder + # Configure OIDC with your cloud provider (AWS, Azure, GCP) + # Example for AWS: + # - name: Configure AWS credentials + # uses: aws-actions/configure-aws-credentials@v4 + # with: + # role-to-assume: arn:aws:iam::ACCOUNT_ID:role/GitHubActionsRole + # aws-region: us-east-1 + + # Example for Azure: + # - name: Azure Login + # uses: azure/login@v2 + # with: + # client-id: ${{ secrets.AZURE_CLIENT_ID }} + # tenant-id: ${{ secrets.AZURE_TENANT_ID }} + # subscription-id: ${{ secrets.AZURE_SUBSCRIPTION_ID }} + + # Example for GCP: + # - name: Authenticate to Google Cloud + # uses: google-github-actions/auth@v2 + # with: + # workload_identity_provider: 'projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/providers/PROVIDER_ID' + # service_account: 'SERVICE_ACCOUNT@PROJECT_ID.iam.gserviceaccount.com' + + - name: Load environment variables + run: | + echo "Environment: ${{ inputs.environment || 'dev' }}" + # Required secrets/variables for deployment: + # WEB3_RPC_URL: Blockchain RPC endpoint + # OPENAI_API_KEY: OpenAI API key for AI features + # SLACK_BOT_TOKEN: Slack integration (optional) + # DISCORD_BOT_TOKEN: Discord integration (optional) + # DB_URL: Database connection string + # S3_BUCKET: S3 bucket for static assets (if using AWS) + # + # These should be configured as GitHub Secrets or Environment Variables + # in Settings > Secrets and variables > Actions + # or in Settings > Environments > [environment-name] + + - name: Install backend dependencies + working-directory: ./backend + run: pip install -r requirements.txt + + - name: Install frontend dependencies + working-directory: ./frontend + run: npm ci + + - name: Build frontend + working-directory: ./frontend + env: + # Example environment-specific variables + NEXT_PUBLIC_API_URL: ${{ vars.API_URL || 'https://api-dev.example.com' }} + NEXT_PUBLIC_RPC_URL: ${{ secrets.WEB3_RPC_URL || 'https://eth.llamarpc.com' }} + run: npm run build + + - name: Run backend tests + working-directory: ./backend + env: + OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY || 'test-key-placeholder' }} + MODEL_NAME: GPT-5.1-Codex-Max + ETH_RPC_URL: ${{ secrets.WEB3_RPC_URL || 'https://eth.llamarpc.com' }} + run: pytest + + # Deployment steps (customize based on your deployment target) + - name: Deploy Backend + run: | + echo "Deploying backend to ${{ inputs.environment || 'dev' }}" + # Add your backend deployment commands here + # Examples: + # - Deploy to AWS Lambda, ECS, or EC2 + # - Deploy to Azure App Service or Container Instances + # - Deploy to GCP Cloud Run or App Engine + # - Deploy to Kubernetes cluster + # - Deploy to VPS via SSH + + - name: Deploy Frontend + run: | + echo "Deploying frontend to ${{ inputs.environment || 'dev' }}" + # Add your frontend deployment commands here + # Examples: + # - Deploy to AWS S3 + CloudFront + # - Deploy to Vercel or Netlify + # - Deploy to Azure Static Web Apps + # - Deploy to GCP Cloud Storage + Cloud CDN + + - name: Deploy Contracts (if needed) + working-directory: ./contracts + run: | + echo "Deploying smart contracts to ${{ inputs.environment || 'dev' }}" + # Add your contract deployment commands here + # Only run for specific environments (e.g., stage, prod) + # Requires PRIVATE_KEY secret for contract deployment + # Example: npx hardhat run scripts/deploy.js --network + + - name: Notify deployment status + if: always() + run: | + echo "Deployment to ${{ inputs.environment || 'dev' }} completed with status: ${{ job.status }}" + # Add notification logic here (Slack, Discord, email, etc.) + # Example using Slack: + # curl -X POST -H 'Content-type: application/json' \ + # --data '{"text":"Deployment to ${{ inputs.environment || 'dev' }}: ${{ job.status }}"}' \ + # ${{ secrets.SLACK_WEBHOOK_URL }} + + deploy-matrix: + name: Deploy to Multiple Environments + runs-on: ubuntu-latest + # Enable this job by setting ENABLE_MULTI_ENV_DEPLOY to 'true' in repository variables + # or by removing this condition to enable multi-environment deployment on push to main + if: github.event_name == 'push' && github.ref == 'refs/heads/main' && vars.ENABLE_MULTI_ENV_DEPLOY == 'true' + strategy: + matrix: + environment: [dev, stage] # Add 'prod' when ready for production deployments + environment: + name: ${{ matrix.environment }} + permissions: + contents: read + id-token: write + + steps: + - name: Checkout code + uses: actions/checkout@v4 + + - name: Deploy to ${{ matrix.environment }} + run: | + echo "Deploying to ${{ matrix.environment }}" + # Reuse deployment steps from above diff --git a/.github/workflows/lint-test.yml b/.github/workflows/lint-test.yml new file mode 100644 index 0000000..d6de51c --- /dev/null +++ b/.github/workflows/lint-test.yml @@ -0,0 +1,96 @@ +name: Lint and Test + +on: + push: + branches: [ main, develop ] + pull_request: + branches: [ main, develop ] + workflow_dispatch: + +permissions: + contents: read + +jobs: + python-lint-test: + name: Python Lint & Test + runs-on: ubuntu-latest + if: hashFiles('backend/requirements.txt') != '' + permissions: + contents: read + + steps: + - name: Checkout code + uses: actions/checkout@v4 + + - name: Setup Python + uses: actions/setup-python@v5 + with: + python-version: '3.11' + cache: 'pip' + cache-dependency-path: backend/requirements.txt + + - name: Install Python dependencies + working-directory: ./backend + run: | + pip install -r requirements.txt + + - name: Run Ruff linter + working-directory: ./backend + run: | + ruff check . + + - name: Run Ruff formatter check + working-directory: ./backend + run: | + ruff format --check . + + - name: Run pytest + working-directory: ./backend + env: + OPENAI_API_KEY: test-key-placeholder + MODEL_NAME: GPT-5.1-Codex-Max + ETH_RPC_URL: https://eth.llamarpc.com + NETWORK: mainnet + run: | + pytest -v + + node-lint-test: + name: Node/TypeScript Lint & Test + runs-on: ubuntu-latest + strategy: + matrix: + node-version: [20.x] + directory: [frontend, contracts] + permissions: + contents: read + + steps: + - name: Checkout code + uses: actions/checkout@v4 + + - name: Setup Node.js ${{ matrix.node-version }} + uses: actions/setup-node@v4 + with: + node-version: ${{ matrix.node-version }} + cache: 'npm' + cache-dependency-path: ${{ matrix.directory }}/package-lock.json + + - name: Install dependencies + working-directory: ./${{ matrix.directory }} + run: npm ci + + - name: Run linter + working-directory: ./${{ matrix.directory }} + run: npm run lint --if-present + + - name: Check formatting + working-directory: ./${{ matrix.directory }} + run: npm run format:check --if-present + + - name: Run tests + working-directory: ./${{ matrix.directory }} + run: npm test + + - name: Build + working-directory: ./${{ matrix.directory }} + run: npm run build --if-present diff --git a/CODEOWNERS b/CODEOWNERS new file mode 100644 index 0000000..a65eced --- /dev/null +++ b/CODEOWNERS @@ -0,0 +1,42 @@ +# Code Owners for Web3AI +# +# These owners will be the default owners for everything in the repo. +# Unless a later match takes precedence, these users will be requested for +# review when someone opens a pull request. +# +# Learn more about code owners: https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners + +# Global fallback - applies to everything unless overridden below +* @lippytm + +# Backend (Python/FastAPI) +/backend/ @lippytm +/backend/**/*.py @lippytm + +# Frontend (Next.js/TypeScript) +/frontend/ @lippytm +/frontend/**/*.ts @lippytm +/frontend/**/*.tsx @lippytm + +# Smart Contracts (Solidity/Hardhat) +/contracts/ @lippytm +/contracts/**/*.sol @lippytm +/contracts/**/*.js @lippytm + +# CI/CD and GitHub Actions +/.github/ @lippytm +/.github/workflows/ @lippytm + +# Documentation +*.md @lippytm +/docs/ @lippytm + +# Configuration files +*.json @lippytm +*.yml @lippytm +*.yaml @lippytm +*.toml @lippytm + +# Security and compliance +/SECURITY.md @lippytm +/LICENSE @lippytm diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..36e4058 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,426 @@ +# Contributing to Web3AI + +First off, thank you for considering contributing to Web3AI! It's people like you that make Web3AI such a great tool. + +## Table of Contents + +- [Code of Conduct](#code-of-conduct) +- [How Can I Contribute?](#how-can-i-contribute) +- [Development Setup](#development-setup) +- [Pull Request Process](#pull-request-process) +- [Coding Standards](#coding-standards) +- [Testing Requirements](#testing-requirements) +- [Commit Message Guidelines](#commit-message-guidelines) + +## Code of Conduct + +This project and everyone participating in it is governed by our commitment to fostering an open and welcoming environment. Please be respectful and constructive in all interactions. + +### Our Standards + +- Using welcoming and inclusive language +- Being respectful of differing viewpoints and experiences +- Gracefully accepting constructive criticism +- Focusing on what is best for the community +- Showing empathy towards other community members + +## How Can I Contribute? + +### Reporting Bugs + +Before creating bug reports, please check existing issues to avoid duplicates. When creating a bug report, include as many details as possible: + +- **Use a clear and descriptive title** +- **Describe the exact steps to reproduce the problem** +- **Provide specific examples** (code snippets, screenshots, etc.) +- **Describe the behavior you observed** and what you expected +- **Include your environment details** (OS, Node version, Python version, etc.) + +### Suggesting Enhancements + +Enhancement suggestions are tracked as GitHub issues. When creating an enhancement suggestion: + +- **Use a clear and descriptive title** +- **Provide a detailed description** of the proposed enhancement +- **Explain why this enhancement would be useful** +- **Provide examples** of how the feature would be used + +### Your First Code Contribution + +Unsure where to begin? Look for issues labeled: + +- `good first issue` - Good for newcomers +- `help wanted` - Extra attention needed +- `documentation` - Improvements or additions to documentation + +## Development Setup + +### Prerequisites + +- **Python** 3.11 or higher +- **Node.js** 20.x or higher +- **npm** 9.x or higher +- **Git** for version control + +### Local Development Setup + +1. **Fork and clone the repository** + ```bash + git clone https://github.com/YOUR-USERNAME/Web3AI.git + cd Web3AI + ``` + +2. **Set up the backend (Python/FastAPI)** + ```bash + cd backend + python -m venv venv + source venv/bin/activate # On Windows: venv\Scripts\activate + pip install -r requirements.txt + cp .env.example .env + # Edit .env with your configuration + ``` + +3. **Set up the frontend (Next.js/TypeScript)** + ```bash + cd frontend + npm install + cp .env.example .env.local + # Edit .env.local with your configuration + ``` + +4. **Set up smart contracts (Hardhat)** + ```bash + cd contracts + npm install + ``` + +5. **Install pre-commit hooks (optional but recommended)** + ```bash + pip install pre-commit + pre-commit install + ``` + +### Running the Development Environment + +```bash +# Terminal 1: Backend +cd backend +source venv/bin/activate +uvicorn app.main:app --reload + +# Terminal 2: Frontend +cd frontend +npm run dev + +# Terminal 3: Local blockchain (optional) +cd contracts +npm run node +``` + +## Pull Request Process + +### Before Submitting a Pull Request + +- [ ] **Create an issue first** (unless it's a trivial change like fixing a typo) +- [ ] **Create a feature branch** from `main` +- [ ] **Follow the coding standards** outlined below +- [ ] **Write or update tests** as needed +- [ ] **Run all tests** and ensure they pass +- [ ] **Run linters** and fix any issues +- [ ] **Update documentation** if you're changing functionality +- [ ] **Keep commits atomic** and well-described + +### Pull Request Checklist + +When you submit a PR, ensure you've completed the following: + +- [ ] PR title is clear and descriptive +- [ ] PR description explains the what, why, and how of the changes +- [ ] All tests pass locally (`npm test`, `pytest`) +- [ ] All linters pass (`npm run lint`, `ruff check`) +- [ ] Code is formatted properly (`npm run format`, `ruff format`) +- [ ] New code has appropriate test coverage +- [ ] Documentation is updated (README, code comments, etc.) +- [ ] No merge conflicts with the base branch +- [ ] Screenshots included (for UI changes) +- [ ] Breaking changes are clearly documented +- [ ] Security implications have been considered +- [ ] No secrets or credentials are committed + +### Branch Naming Convention + +Use descriptive branch names following this pattern: + +- `feature/description` - New features +- `fix/description` - Bug fixes +- `docs/description` - Documentation changes +- `refactor/description` - Code refactoring +- `test/description` - Adding or updating tests +- `chore/description` - Maintenance tasks + +Examples: +- `feature/add-wallet-connect` +- `fix/contract-deployment-error` +- `docs/update-api-reference` + +### Branch Protection + +The `main` branch is protected with the following requirements: + +- **Pull request required**: Direct pushes to `main` are not allowed +- **Required reviewers**: At least 1 approval from a maintainer +- **Status checks required**: All CI checks must pass + - Python linting and tests + - Node/TypeScript linting and tests + - Smart contract compilation and tests + - CodeQL security analysis + - Dependency review +- **Up-to-date branch**: Your branch must be up to date with `main` + +## Coding Standards + +### Python (Backend) + +- **Style Guide**: Follow [PEP 8](https://pep8.org/) +- **Linter**: Use Ruff for linting and formatting +- **Type Hints**: Use type hints for function parameters and return values +- **Docstrings**: Use docstrings for modules, classes, and functions +- **Max Line Length**: 88 characters (Black default) + +```python +# Good +def process_transaction(wallet_address: str, amount: float) -> dict: + """Process a blockchain transaction. + + Args: + wallet_address: The destination wallet address + amount: The amount to transfer + + Returns: + Transaction receipt as a dictionary + """ + return {"status": "success", "amount": amount} +``` + +Run before committing: +```bash +cd backend +ruff check . +ruff format . +pytest +``` + +### TypeScript/JavaScript (Frontend) + +- **Style Guide**: Follow the [Google JavaScript Style Guide](https://google.github.io/styleguide/jsguide.html) +- **Linter**: ESLint with Next.js configuration +- **Formatter**: Prettier +- **Type Safety**: Use TypeScript with strict mode + +```typescript +// Good +interface TransactionProps { + walletAddress: string; + amount: number; +} + +export const processTransaction = async ({ + walletAddress, + amount +}: TransactionProps): Promise => { + // Implementation +}; +``` + +Run before committing: +```bash +cd frontend +npm run lint +npm run format +npm run type-check +npm test +``` + +### Solidity (Smart Contracts) + +- **Style Guide**: Follow [Solidity Style Guide](https://docs.soliditylang.org/en/latest/style-guide.html) +- **Version**: Use Solidity ^0.8.0 or higher +- **Security**: Follow [ConsenSys Smart Contract Best Practices](https://consensys.github.io/smart-contract-best-practices/) +- **Documentation**: Use NatSpec comments + +```solidity +// SPDX-License-Identifier: MIT +pragma solidity ^0.8.0; + +/// @title MyContract +/// @notice Explain what this contract does +/// @dev Additional details for developers +contract MyContract { + /// @notice Explain what this function does + /// @param amount The amount to process + /// @return success Whether the operation succeeded + function processAmount(uint256 amount) external returns (bool success) { + // Implementation + } +} +``` + +Run before committing: +```bash +cd contracts +npm run compile +npm test +``` + +## Testing Requirements + +### Backend Testing + +- **Framework**: pytest +- **Coverage**: Aim for >80% code coverage +- **Test Types**: Unit tests, integration tests +- **Location**: `backend/tests/` + +```bash +# Run all tests +pytest + +# Run with coverage +pytest --cov=app + +# Run specific test file +pytest tests/test_main.py +``` + +### Frontend Testing + +- **Framework**: Jest, React Testing Library (configure as needed) +- **Test Types**: Unit tests, component tests +- **Location**: `frontend/__tests__/` or `frontend/**/*.test.ts(x)` + +```bash +# Run tests +npm test + +# Run with coverage +npm test -- --coverage +``` + +### Smart Contract Testing + +- **Framework**: Hardhat with Mocha/Chai +- **Coverage**: Use solidity-coverage plugin +- **Test Types**: Unit tests, integration tests +- **Location**: `contracts/test/` + +```bash +# Run tests +npm test + +# Run with gas reporting +REPORT_GAS=true npm test + +# Run coverage +npm run coverage +``` + +### Writing Good Tests + +- **Descriptive names**: Test names should clearly describe what they test +- **Arrange-Act-Assert**: Structure tests with clear setup, action, and verification +- **Test one thing**: Each test should verify one specific behavior +- **Use fixtures**: Set up common test data with fixtures/factories +- **Mock external services**: Don't make real API calls in tests + +## Commit Message Guidelines + +We follow the [Conventional Commits](https://www.conventionalcommits.org/) specification: + +### Format + +``` +(): + + + +