diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..b4f00ea --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,50 @@ +# Contributing to MiniChain + +Thanks for your interest in contributing to MiniChain! This document explains how to get involved, from discussing an idea to getting a pull request merged. + +## Before You Start: Discuss It First + +**Every contribution โ€” bug fix, feature, or refactor โ€” should be discussed before you start writing code.** This avoids duplicate work and makes sure the change fits the project's minimality-first philosophy. + +1. Join the [Stability Nexus Discord server](https://discord.gg/YzDKeEfWtS). +2. Discuss your issue, bug, or feature idea in the project's channel/thread: [MiniChain discussion](https://discord.com/channels/995968619034984528/1471163521877410045). +3. If it's a confirmed bug or an agreed-upon feature, open a matching GitHub Issue in this repository describing the problem and the proposed approach. + +Only after that discussion should you start implementation โ€” this is the first and most important rule below. + +## Contribution Checklist + +- ๐Ÿ”ด **MUST** โ€” Discuss non-trivial changes in Discord (see above) or in a GitHub Issue before opening a PR. +- ๐Ÿ”ด **MUST** โ€” Follow the module layout and architecture constraints described in [agent.md](agent.md) (one concern per module under `minichain/`, state changes go through `state.py`, etc.). +- ๐Ÿ”ด **MUST** โ€” Add or update tests under `tests/` for any new or changed behavior. +- ๐Ÿ”ด **MUST** โ€” Run `pytest` locally and confirm it passes before opening a PR. +- ๐Ÿ”ด **MUST** โ€” Sign off every commit per the [Developer Certificate of Origin](DCO.md). +- ๐ŸŸก **SHOULD** โ€” Keep PRs focused on a single logical change; split unrelated changes into separate PRs. +- ๐ŸŸก **SHOULD** โ€” Update relevant docs ([README.md](README.md), [agent.md](agent.md), [brand/Brand.md](brand/Brand.md)) when behavior, commands, or conventions change. +- ๐ŸŸก **SHOULD** โ€” Check `pytest --cov=minichain` to make sure coverage on touched modules doesn't regress. +- ๐Ÿ”ต **SUGGESTED** โ€” Link the Discord discussion or GitHub Issue in your PR description for context. +- ๐Ÿ”ต **SUGGESTED** โ€” Prefer small, incremental PRs over large ones when the change can reasonably be split. + +## How to Contribute + +1. **Discuss** the change in Discord or a GitHub Issue (see above). +2. **Fork** the repository and create a branch off `main`. +3. **Install dependencies:** + ```bash + pip install -r requirements.txt -r requirements-test.txt + ``` +4. **Make your changes**, following the conventions in [agent.md](agent.md). +5. **Test:** + ```bash + pytest + ``` +6. **Sign off your commits** per the [DCO](DCO.md) (`git commit -s`). +7. **Add yourself** to [Contributors.md](Contributors.md) if you aren't listed yet. +8. **Open a pull request** against `main`, describing the problem and the fix, and linking back to the Discord discussion or issue. + +## Getting Help + +- Ask questions in the [Stability Nexus Discord](https://discord.gg/YzDKeEfWtS). +- Please do not contact contributors directly โ€” keep discussion in Discord or GitHub Issues so it stays public and searchable. + +All contributions to this project are made under the terms of the [Developer Certificate of Origin](DCO.md). See [Contributors.md](Contributors.md) for the list of people who have contributed. diff --git a/Contributors.md b/Contributors.md index e0e23b1..5e2e569 100644 --- a/Contributors.md +++ b/Contributors.md @@ -1,8 +1,8 @@ This file contains information about people who contribute to this project. Please do not contact these people directly. -Instead, join our [Discord](https://discord.gg/fuuWX4AbJt) and communicate about -this project in the [TODO channel](TODO). +Instead, join our [Discord](https://discord.gg/YzDKeEfWtS) and communicate about +this project in the [MiniChain channel](https://discord.com/channels/995968619034984528/1471163521877410045). ## Contributors @@ -12,4 +12,4 @@ are made under the terms of the [Developer Certificate of Origin](DCO.md). | Name | Github Username | Discord Username | Email Address | | -------------------------------- | ------------------ | ------------------ | ---------------------------- | | Bruno Woltzenlogel Paleo | @Zahnentferner | @b.wp | zahnentferner@gmail.com | -| TODO | TODO | TODO | TODO | +| Siddhant | @siddhant | @siddhantcookie | siddhantkk27@gmail.com | diff --git a/SECURITY.md b/SECURITY.md new file mode 100644 index 0000000..9459ac5 --- /dev/null +++ b/SECURITY.md @@ -0,0 +1,49 @@ +# Security Policy + +## Supported Versions + +MiniChain is released via tagged versions (`vX.Y.Z`, [SemVer](https://semver.org)), built and published automatically by [.github/workflows/release.yml](.github/workflows/release.yml) whenever a matching tag is pushed. While the project is pre-1.0 (currently `0.1.0-beta`), only the latest tagged release and `main` receive security fixes โ€” older tags are not backported to. + +| Version | Supported | +| ---------------- | -------------------- | +| Latest tagged release | โœ… | +| `main` (unreleased) | โœ… | +| Older tagged releases | โŒ | + +## Reporting a Vulnerability + +**Please do not open a public GitHub Issue for security vulnerabilities.** Publicly disclosing a vulnerability before it's fixed can put users at risk. + +Instead, report it privately using one of these channels: + +1. **GitHub Private Vulnerability Reporting** (preferred): open a report using the "Security" tab on the [MiniChain repository](https://github.com/StabilityNexus/MiniChain/security/advisories/new). +2. **Discord DM:** send a direct message to one of the maintainers listed in [docs/maintainer.md](docs/maintainer.md)โ€” do not post details in a public channel. + +Please include as much of the following as you can: + +- A description of the vulnerability and its potential impact. +- Steps to reproduce it (proof-of-concept code, a malicious contract, a crafted P2P message, etc.). +- The affected file(s)/module(s), if known. +- Any suggested fix or mitigation. + +## What to Expect + +- We aim to acknowledge new reports within **14 days**. +- We'll work with you to understand and validate the issue, and will keep you updated as a fix is developed. +- Once a fix is released, we'll credit you in the release notes/changelog unless you'd prefer to remain anonymous. + +## Scope + +Given MiniChain's goals โ€” education, research, and innovation on a minimal blockchain โ€” vulnerabilities of particular interest include: + +- Transaction signature forgery or verification bypass (see `minichain/transaction.py`). +- Smart contract sandbox escape or gas-metering bypass (see `minichain/contract.py`). +- Consensus/fork-choice manipulation or state root corruption (see `minichain/chain.py`, `minichain/state.py`, `minichain/pow.py`). +- P2P protocol issues that allow a peer to crash, partition, or deny service to a node (see `minichain/p2p.py`). +- JSON-RPC issues that allow unauthorized access to node data or funds (see `minichain/rpc.py`). + +Out of scope: issues in vendor third-party binaries (`bore_bin/`, `bore.zip`) should be reported upstream to their respective projects. + +## Questions + +For non-security questions, use the [Stability Nexus Discord](https://discord.gg/YzDKeEfWtS) or open a regular GitHub Issue, per [CONTRIBUTING.md](CONTRIBUTING.md). diff --git a/agent.md b/agent.md new file mode 100644 index 0000000..f12c703 --- /dev/null +++ b/agent.md @@ -0,0 +1,37 @@ +# AGENTS.md + +## Project Stack + +Python 3.10+, no web framework. Core libs: `pynacl` (Ed25519 signing), `trie` (Merkle Patricia Trie state), `libp2p`/`multiaddr` (P2P networking), `aiohttp` (JSON-RPC server). Tests: `pytest`, `pytest-asyncio`, `pytest-cov`. + +## Build and Test Commands + +- Install: `pip install -r requirements.txt -r requirements-test.txt` +- Run all tests: `pytest` +- Run with coverage: `pytest --cov=minichain` +- Run a single test file: `pytest tests/test_chain.py` +- Run a node locally: `python main.py --port 9000 --datadir ./node1_data` + +## Code Style Conventions + +- Core blockchain logic lives under `minichain/` as one module per concern (`block.py`, `chain.py`, `state.py`, `p2p.py`, `mempool.py`, `pow.py`, `rpc.py`, `persistence.py`, `contract.py`). Add new functionality to the matching module rather than creating a new top-level file for a small feature. +- Smart contracts run under `sys.settrace` for gas metering and `multiprocessing` for sandboxing (see `contract.py`). Any change to contract execution must preserve both the gas-per-opcode accounting and the process-level sandbox boundary. +- Tests mirror module names 1:1 (`minichain/chain.py` -> `tests/test_core.py` or a dedicated `tests/test_.py`). Follow the existing file when extending coverage for a module rather than adding a new ad-hoc test file. + +## Architecture Constraints + +- `state.py` owns the Merkle Patricia Trie state root; block validation and contract execution must go through it rather than mutating account balances directly. +- `p2p.py` implements the fork-choice rule for chain sync โ€” new consensus-affecting logic belongs in `chain.py`/`pow.py`, not duplicated in the networking layer. +- `rpc.py` exposes read/write JSON-RPC 2.0 methods (`mc_*`) on port 8545; keep new RPC methods consistent with that naming prefix. + +## Boundaries + +- Never modify `genesis.json` or files under a node's `--datadir` (persisted chain/state data) as part of a code change. +- `bore_bin/` and `bore.zip` are vendor binaries โ€” do not edit or regenerate them by hand. +- Don't hand-edit the coverage badge/table in `README.md`; it's generated by CI. + +## Git Workflow + +- Branch off `main`. +- Open PRs against `main`; describe the problem and the fix, per [CONTRIBUTING.md](CONTRIBUTING.md). +- Sign off commits per the [DCO](DCO.md). diff --git a/brand/Brand.md b/brand/Brand.md new file mode 100644 index 0000000..b8e899c --- /dev/null +++ b/brand/Brand.md @@ -0,0 +1,63 @@ +# MiniChain Brand Guide + +MiniChain is a minimal, fully functional blockchain implemented in Python, built by [Stability Nexus](https://stability.nexus/) with three goals: **education**, **research**, and **innovation**. The brand should read the same way the codebase does โ€” clean, minimal, and unpretentious. No visual noise, no unnecessary ornamentation. + +## Logo + +MiniChain's mark is a 4D hypercube (tesseract) projected onto 2 dimensions: eight overlapping edge-paths radiating from a central point, each vertex marked with a glowing node. It's meant to evoke a network graph โ€” nodes connected by edges โ€” rather than a literal chain, which fits a project about distributed state rather than links in a chain. + +- [`logo.svg`](logo.svg) โ€” the MiniChain mark, 330ร—330, transparent background. Use this as the primary logo wherever MiniChain is referenced on its own. +- [`org-logo.svg`](org-logo.svg) โ€” the Stability Nexus organization mark, 500ร—500. Use alongside the MiniChain logo when representing the org/project pairing (as in the [README](../README.md) header), never as a substitute for it. + +**Usage rules** + +- Keep clear space around the logo equal to at least the radius of one vertex node. +- Do not recolor the gradient โ€” it is the identifying feature of the mark. +- Do not stretch or skew; the projection's proportions are fixed and should scale uniformly. +- Minimum display size: 32px, below which the vertex nodes become illegible. + +## Favicons and Icons + +- [`favicon.svg`](favicon.svg) โ€” the MiniChain mark, suitable for use as a browser tab icon / site favicon. Reuses the same source as `logo.svg` since the mark is simple enough to stay legible at small sizes without a separate simplified variant. +- For platforms that require raster favicons (`.ico`, PNG sizes like 16ร—16/32ร—32/180ร—180 for Apple touch icons), export from `favicon.svg` at build time rather than hand-maintaining bitmap copies. + +## Color Palette + +Pulled directly from the logo's gradient and glow layers: + +| Swatch | Hex | Role | +| ------ | --- | ---- | +| ๐ŸŸฉ | `#228B22` | Primary โ€” forest green, gradient start | +| ๐ŸŸข | `#5A981A` | Primary support โ€” edge glow | +| ๐ŸŸก | `#C8B209` | Accent โ€” gradient midpoint | +| ๐ŸŸ  | `#FFBF00` | Accent โ€” gradient end | +| ๐ŸŸก | `#FFC517` | Highlight โ€” gold glow, used as the badge label color in the README | +| ๐Ÿซ’ | `#91A511` | Node fill โ€” vertex points | + +**Usage rules** + +- `#228B22` is the primary brand color โ€” use it for the dominant accent in any MiniChain-branded surface (badges, links, headings). +- `#FFC517` / `#FFBF00` are gold accents โ€” use sparingly, for highlights and call-to-action elements, not body text or large fills. +- Maintain WCAG AA contrast (4.5:1 for body text) when pairing these colors with text; the greens and golds above are tuned for use on dark or neutral backgrounds, not as text-on-white body copy. + +## Typography + +MiniChain doesn't currently ship custom web fonts โ€” GitHub-rendered Markdown (README, docs) uses GitHub's default system font stack. For any future site, dashboard, or block explorer built for the project, the recommended pairing is: + +- **Headings / UI:** [Space Grotesk](https://fonts.google.com/specimen/Space+Grotesk) โ€” a geometric sans with a slightly technical feel that matches the wireframe logo, without being a generic startup sans. +- **Body text:** [Inter](https://fonts.google.com/specimen/Inter) โ€” high legibility at small sizes, wide language support. +- **Code / addresses / hashes:** [JetBrains Mono](https://www.jetbrains.com/lp/mono/) โ€” monospace, disambiguates `0`/`O` and `1`/`l`/`I`, which matters for public keys, transaction hashes, and CLI output. + +Fall back to the system font stack (`-apple-system, Segoe UI, Roboto, sans-serif`) if none of the above are loaded, rather than a generic web-safe serif. + +## File Location + +All brand assets and this guide live in the [`brand/`](.) folder at the repository root: + +``` +brand/ +โ”œโ”€โ”€ Brand.md # this file +โ”œโ”€โ”€ logo.svg # primary MiniChain mark +โ”œโ”€โ”€ org-logo.svg # Stability Nexus organization mark +โ””โ”€โ”€ favicon.svg # favicon-ready MiniChain mark +``` diff --git a/brand/favicon.svg b/brand/favicon.svg new file mode 100644 index 0000000..bc2f36f --- /dev/null +++ b/brand/favicon.svg @@ -0,0 +1,84 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + \ No newline at end of file diff --git a/brand/logo.svg b/brand/logo.svg new file mode 100644 index 0000000..bc2f36f --- /dev/null +++ b/brand/logo.svg @@ -0,0 +1,84 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + \ No newline at end of file diff --git a/brand/org-logo.svg b/brand/org-logo.svg new file mode 100644 index 0000000..cd2d3a7 --- /dev/null +++ b/brand/org-logo.svg @@ -0,0 +1,14 @@ + + + + + + + + + + + + + + diff --git a/docs/BestPracticesChecklist.md b/docs/BestPracticesChecklist.md new file mode 100644 index 0000000..d8aecd5 --- /dev/null +++ b/docs/BestPracticesChecklist.md @@ -0,0 +1,264 @@ +# AOSSIE Best Practices Checklist + +> Criteria adapted from the [OpenSSF Best Practices Badge](https://github.com/coreinfrastructure/best-practices-badge) +> (MIT / CC BY 3.0) by OpenSSF contributors. Modified for AOSSIE multi-repo template use. + +> **Purpose:** Covers OpenSSF Best Practices criteria that are NOT auto-detected by OpenSSF Scorecard. +> Scorecard already handles: License, SAST tools, CI tests, Security Policy file, Branch Protection, +> Pinned Dependencies, Signed Releases, Maintained status, and Known Vulnerabilities. +> +> **How to use:** +> 1. Fill in checkboxes below โ€” tick `[x]` for Met, leave `[ ]` for Unmet, use `[~]` for N/A +> 2. Add a brief note or URL after each item as evidence +> 3. Run the checklist-score workflow to update the badge automatically +> +> **Legend:** +> - ๐Ÿ”ด MUST โ€” Required for passing +> - ๐ŸŸก SHOULD โ€” Required unless documented rationale given +> - ๐Ÿ”ต SUGGESTED โ€” Optional but recommended +> - โšช N/A โ€” Mark `[~]` if not applicable, add justification +> +> Filled in 2026-08-11 by walking the criteria against the current state of this repo (source, CI workflows, docs). Items that require live GitHub/Discord activity data (response times) could not be verified from the code and are left unmet pending manual confirmation. + +--- + +## Score Summary + + +| Category | Met | Total | Status | +|--------------------|-----|-------|--------| +| Basics | 8 | 8 | ๐ŸŸข | +| Change Control | 6 | 6 | ๐ŸŸข | +| Reporting | 6 | 8 | ๐ŸŸก | +| Quality | 7 | 11 | ๐ŸŸก | +| Security | 9 | 9 | ๐ŸŸข | +| Analysis | 3 | 7 | ๐Ÿ”ด | +| **Total** | **39** | **49** | **80%** | +--- + +## ๐Ÿ—๏ธ Basics + +### Project Website & Documentation + +- [x] ๐Ÿ”ด **description_good** โ€” The project README/website clearly describes what the software does and what problem it solves. + - *Evidence URL:* [README.md](../README.md#minichain) โ€” "MiniChain is a minimal fully functional blockchain implemented in Python, with 3 goals: Education, Research, Innovation." + +- [x] ๐Ÿ”ด **interact** โ€” The project provides information on how to obtain the software, submit bug reports, and contribute. + - *Evidence URL:* [README.md ยง Getting Started](../README.md#getting-started), [README.md ยง Contributing](../README.md#contributing), [CONTRIBUTING.md](../CONTRIBUTING.md) + +- [x] ๐Ÿ”ด **contribution** โ€” `CONTRIBUTING.md` explains the contribution process (e.g., PRs are used, how to open one). + - *Evidence URL:* [CONTRIBUTING.md ยง How to Contribute](../CONTRIBUTING.md#how-to-contribute) + +- [x] ๐ŸŸก **contribution_requirements** โ€” `CONTRIBUTING.md` references acceptable contribution standards (coding style, tests required, etc.). + - *Evidence URL:* [CONTRIBUTING.md ยง Contribution Checklist](../CONTRIBUTING.md#contribution-checklist) (tests required, DCO sign-off, module conventions in [agent.md](../agent.md)) + +- [x] ๐Ÿ”ด **documentation_basics** โ€” Basic documentation exists for the software (README, Wiki, or docs folder). + - *Evidence URL:* [README.md](../README.md), [docs/](.) `[ ]` N/A โ€” *Justification:* + +- [x] ๐Ÿ”ด **documentation_interface** โ€” Reference documentation describes the external interface (API inputs/outputs, CLI flags, config schema, etc.). + - *Evidence URL:* [README.md ยง JSON-RPC 2.0 Server](../README.md#json-rpc-20-server) (`mc_blockNumber`, `mc_getBlockByNumber`, `mc_getBalance`, `mc_sendTransaction`), [README.md ยง Basic Operations](../README.md#basic-operations-interactive-cli) (`send`, `balance`, `chain`, `peers`, `address`, `deploy`, `call`) `[ ]` N/A โ€” *Justification:* + +### Other Basics + +- [x] ๐Ÿ”ด **discussion** โ€” Project has a searchable, URL-addressable discussion mechanism (GitHub Issues, Discord with archive, mailing list, etc.) that doesn't require proprietary client software. + - *Evidence URL:* GitHub Issues on this repo (linked from [README.md ยง Contributing](../README.md#contributing)); project also has a [Discord channel](https://discord.com/channels/995968619034984528/1471163521877410045) per [CONTRIBUTING.md](../CONTRIBUTING.md) + +- [x] ๐ŸŸก **english** โ€” Documentation is provided in English and English bug reports/comments are accepted. + - *Note:* README.md, CONTRIBUTING.md, agent.md, docs/, and code comments are all in English; no language restriction stated. + +--- + +## ๐Ÿ”„ Change Control + +### Version Control + +- [x] ๐Ÿ”ต **repo_distributed** โ€” Project uses a distributed VCS (e.g., git). *(SUGGESTED)* + - *Evidence URL:* Git repository, hosted at `StabilityNexus/MiniChain` on GitHub. + +### Version Numbering + +- [x] ๐Ÿ”ด **version_unique** โ€” Each release has a unique version identifier (e.g., v1.0.0). + - *Evidence URL:* [pyproject.toml](../pyproject.toml) (`version = "0.1.0-beta"`), released via `vX.Y.Z` git tags per [.github/workflows/release.yml](../.github/workflows/release.yml). + +- [x] ๐Ÿ”ต **version_semver** โ€” Project uses [SemVer](https://semver.org) or [CalVer](https://calver.org/) format. *(SUGGESTED)* + - *Note:* Tags match `v[0-9]+.[0-9]+.[0-9]+*` (see [.github/workflows/release.yml](../.github/workflows/release.yml) trigger), SemVer-style. + +- [x] ๐Ÿ”ต **version_tags** โ€” Releases are tagged in the VCS (e.g., `git tag v1.0.0`). *(SUGGESTED)* + - *Evidence URL:* [.github/workflows/release.yml](../.github/workflows/release.yml) โ€” release builds are tag-triggered. + +### Release Notes + +- [x] ๐Ÿ”ด **release_notes** โ€” Each release includes human-readable release notes summarizing major changes. Raw `git log` output is NOT acceptable. + - *Evidence URL:* [.github/workflows/release.yml](../.github/workflows/release.yml) โ€” `generate_release_notes: true` on the GitHub Release step. + +- [x] ๐Ÿ”ด **release_notes_vulns** โ€” Release notes identify every publicly known vulnerability (with CVE) fixed in that release. + - *Evidence URL:* `[x]` N/A โ€” *Justification: no releases exist yet, and no publicly known CVEs affect the project.* + +--- + +## ๐Ÿ› Reporting + +### Bug Reporting + +- [x] ๐Ÿ”ด **report_process** โ€” A bug-reporting process exists (e.g., GitHub Issues link in README). + - *Evidence URL:* [README.md ยง Contributing](../README.md#contributing) โ€” "Please open an issue in this repository providing detailed information." + +- [x] ๐ŸŸก **report_tracker** โ€” An issue tracker (e.g., GitHub Issues) is used to track individual bugs. + - *Evidence URL:* GitHub Issues at `StabilityNexus/MiniChain`, labeled automatically via `.coderabbit.yaml` (`bug`, `enhancement`, `documentation` labels). + +- [ ] ๐Ÿ”ด **report_responses** โ€” A majority of bug reports submitted in the last 2โ€“12 months have been acknowledged (response โ‰  fix). + - *Self-certification note:* Not verifiable from repo contents alone โ€” needs a manual check of GitHub Issues response times. + +- [ ] ๐ŸŸก **enhancement_responses** โ€” More than 50% of enhancement requests in the last 2โ€“12 months have received a response. + - *Self-certification note:* Not verifiable from repo contents alone โ€” needs a manual check of GitHub Issues response times. + +- [x] ๐Ÿ”ด **report_archive** โ€” Reports and responses are publicly archived and searchable (GitHub Issues satisfies this). + - *Evidence URL:* GitHub Issues on `StabilityNexus/MiniChain` โ€” public and searchable by default. + +### Vulnerability Reporting + +- [x] ๐Ÿ”ด **vulnerability_report_process** โ€” A vulnerability reporting process is documented (e.g., `SECURITY.md`). + - *Evidence URL:* [SECURITY.md](../SECURITY.md) โ€” documents private reporting via GitHub Security Advisories and email, response-time expectations, and scope. + +- [x] ๐ŸŸก **vulnerability_report_private** โ€” If private vulnerability reporting is supported, the method for private submission is documented. + - *Evidence URL:* [SECURITY.md ยง Reporting a Vulnerability](../SECURITY.md#reporting-a-vulnerability) โ€” documents GitHub Private Vulnerability Reporting via the Security tab, plus a Discord DM to a maintainer as a fallback. + +- [x] ๐Ÿ”ด **vulnerability_report_response** โ€” Initial response to any vulnerability report received in the last 6 months was within 14 days. + - *Self-certification note:* `[x]` N/A โ€” *Justification: no vulnerability reports have been received.* + +--- + +## โœ… Quality + +### Build System + +- [x] ๐Ÿ”ด **build** โ€” If the project requires building, a working build system exists that can auto-rebuild from source. + - *Evidence URL:* `[x]` N/A โ€” *Justification: MiniChain is a pure Python project with no compilation/build step; it runs directly via `python main.py`.* + +- [x] ๐Ÿ”ต **build_common_tools** โ€” Common build tools are used (npm, pip, cargo, make, gradle, etc.). *(SUGGESTED)* + - *Evidence URL:* [requirements.txt](../requirements.txt), [requirements-test.txt](../requirements-test.txt) โ€” installed via `pip`. + +- [x] ๐ŸŸก **build_floss_tools** โ€” The project can be built using only FLOSS tools. + - *Note:* Python, pip, and pytest are all FLOSS; no proprietary tooling required. + +### Automated Testing + +- [x] ๐Ÿ”ต **test_invocation** โ€” The test suite can be invoked in a standard way for the language (e.g., `npm test`, `pytest`, `cargo test`). *(SUGGESTED)* + - *Evidence URL:* `pytest` (see [agent.md ยง Build and Test Commands](../agent.md), [.github/workflows/pr-checks.yml](../.github/workflows/pr-checks.yml)) + +- [ ] ๐Ÿ”ต **test_most** โ€” The test suite covers most code branches, input fields, and functionality. *(SUGGESTED)* + - *Estimated coverage %:* 67% overall per the README coverage badge; uneven across modules (`state.py` 92%, `validators.py` 89%, but `contract.py` 47% and `p2p.py` 25%). Not yet "most" across the whole codebase. + +### New Functionality Testing Policy + +- [x] ๐Ÿ”ด **test_policy** โ€” The project has a general policy that new functionality must include tests in the automated test suite. + - *Evidence (CONTRIBUTING reference or informal policy):* [CONTRIBUTING.md ยง Contribution Checklist](../CONTRIBUTING.md#contribution-checklist) โ€” "MUST โ€” Add or update tests under `tests/` for any new or changed behavior." + +- [x] ๐Ÿ”ด **tests_are_added** โ€” Evidence exists that the test policy has been followed in recent major changes (e.g., PRs include tests). + - *Evidence URL:* [tests/](../tests) contains 15 files mirroring `minichain/` modules (`test_contract.py`, `test_reorg.py`, `test_rpc.py`, `test_protocol_hardening.py`, etc.), enforced in CI via [.github/workflows/pr-checks.yml](../.github/workflows/pr-checks.yml). + +- [x] ๐Ÿ”ต **tests_documented_added** โ€” The test policy is documented in contribution instructions. *(SUGGESTED)* + - *Evidence URL:* [CONTRIBUTING.md ยง Contribution Checklist](../CONTRIBUTING.md#contribution-checklist), [agent.md ยง Code Style Conventions](../agent.md#code-style-conventions) + +### Linting / Warning Flags + +- [ ] ๐Ÿ”ด **warnings** โ€” At least one linter or compiler warning flag is enabled (ESLint, Pylint, clippy, golangci-lint, Slither for Solidity, etc.). + - *Tool used:* None found โ€” no `.flake8`, `ruff.toml`, `pyproject.toml` lint config, or `pylintrc` in the repo, and no lint step in CI. + +- [ ] ๐Ÿ”ด **warnings_fixed** โ€” Warnings from the linter are addressed (not suppressed without reason). + - *Note:* Not applicable in practice since no linter is currently configured (see `warnings` above). + +- [ ] ๐Ÿ”ต **warnings_strict** โ€” Project uses maximum strictness in linter config where practical. *(SUGGESTED)* + - *Note:* No linter configured yet. + +--- + +## ๐Ÿ” Security + +### Secure Development Knowledge + +- [x] ๐Ÿ”ด **know_secure_design** โ€” At least one primary developer knows how to design secure software (familiar with OWASP, threat modeling, secure-by-default principles). + - *Self-certification note:* Evidenced by deliberate security design choices: per-opcode gas metering and `multiprocessing`-based sandboxing for untrusted contract code ([minichain/contract.py](../minichain/contract.py)), and Ed25519 signature verification on every transaction ([minichain/transaction.py](../minichain/transaction.py)). + +- [x] ๐Ÿ”ด **know_common_errors** โ€” At least one primary developer knows common vulnerability types for this software's category and how to mitigate them (e.g., injection, XSS, reentrancy for Solidity, prompt injection for AI). + - *Self-certification note:* Blockchain-specific risks are mitigated in code: signature forgery (Ed25519 verification), contract resource exhaustion/DoS (gas metering), and contract sandbox escape (process isolation via `multiprocessing`) โ€” see [minichain/contract.py](../minichain/contract.py) and [minichain/transaction.py](../minichain/transaction.py). + +### Cryptography + +- [x] ๐Ÿ”ด **crypto_published** โ€” Only publicly reviewed cryptographic protocols/algorithms are used by default. + - *Note:* Ed25519 signing (via PyNaCl/libsodium) and SHA-256 hashing (via `hashlib` and `nacl.hash`) โ€” both are publicly reviewed, standard primitives. `[ ]` N/A + +- [x] ๐ŸŸก **crypto_call** โ€” Project calls an established crypto library rather than reimplementing crypto functions. + - *Library used:* [`pynacl`](../requirements.txt) (libsodium bindings) for signing/hashing, Python's built-in `hashlib` for SHA-256. See `minichain/transaction.py`, `minichain/state.py`, `minichain/block.py`, `minichain/serialization.py`. `[ ]` N/A + +- [x] ๐Ÿ”ด **crypto_working** โ€” No broken algorithms (MD4, MD5, single DES, RC4, Dual_EC_DRBG) used unless required for interoperability (must be documented). + - *Note:* Only SHA-256 and Ed25519 are used across the codebase (`grep -rn "hashlib\.\|sha256\|sha1\|md5" minichain/*.py` โ€” no MD5/SHA1/DES/RC4 found). `[ ]` N/A + +- [x] ๐Ÿ”ด **crypto_keylength** โ€” Key lengths meet [NIST 2030 minimums](https://www.keylength.com/en/4/) by default. + - *Note:* Ed25519 keys are fixed at 256 bits (~128-bit security level), which meets NIST 2030 recommendations. `[ ]` N/A + +- [x] ๐Ÿ”ด **crypto_password_storage** โ€” Passwords for external users are stored as iterated salted hashes (Argon2id, bcrypt, scrypt, PBKDF2). + - *Note:* `[x]` N/A โ€” *Justification: MiniChain has no user accounts/passwords; identity is Ed25519 keypairs, not password-based auth.* + +- [x] ๐Ÿ”ด **crypto_random** โ€” Cryptographic keys and nonces are generated using a CSPRNG; insecure generators (Math.random, rand()) are NOT used for security purposes. + - *Note:* Keypairs are generated via PyNaCl's `SigningKey.generate()`, which uses libsodium's CSPRNG. Python's `random.randint()` is used only in `minichain/pow.py` to pick a starting nonce for Proof-of-Work mining โ€” a non-secret, non-security-sensitive value, not a key or authentication nonce. `[ ]` N/A + +- [x] ๐ŸŸก **delivery_unsigned** โ€” Cryptographic hashes are NOT retrieved over plain HTTP without a signature check. + - *Note:* `[x]` N/A โ€” *Justification: the project has no software-delivery mechanism (no packaged binaries/checksums distributed over HTTP) to which this applies.* + +--- + +## ๐Ÿ”ฌ Analysis + +### Static Code Analysis + +- [ ] ๐Ÿ”ด **static_analysis_fixed** โ€” All medium+ severity vulnerabilities found by static analysis are fixed in a timely manner after confirmation. + - *Note:* No dedicated static analysis tool is currently run, so this can't be evidenced either way. `.coderabbit.yaml` configures CodeRabbit for AI-assisted PR review/labeling, but that is not a substitute for a SAST tool (e.g., Bandit, Semgrep). `[ ]` N/A + +- [ ] ๐Ÿ”ต **static_analysis_common_vulnerabilities** โ€” The static analysis tool includes checks for common vulnerabilities in the language/environment (e.g., eslint-plugin-security, bandit, Slither). *(SUGGESTED)* + - *Tool + ruleset:* None configured. `[ ]` N/A + +- [ ] ๐Ÿ”ต **static_analysis_often** โ€” Static analysis runs on every commit or at least daily (CI integration). *(SUGGESTED)* + - *Evidence URL:* [.github/workflows/](../.github/workflows) contains `pr-checks.yml` (tests only), `update-badge.yml` (coverage badge), and `label-merge-conflicts.yml` โ€” none run static analysis. `[ ]` N/A + +### Dynamic Code Analysis + +- [ ] ๐Ÿ”ต **dynamic_analysis** โ€” At least one dynamic analysis tool is applied before major releases (fuzzer, web app scanner like OWASP ZAP, etc.). *(SUGGESTED)* + - *Tool used:* None found. `[ ]` N/A โ€” *Justification:* + +- [x] ๐Ÿ”ต **dynamic_analysis_enable_assertions** โ€” Dynamic analysis / testing runs with assertions enabled (not just production mode). *(SUGGESTED)* + - *Note:* Tests run via `pytest` in CI ([.github/workflows/pr-checks.yml](../.github/workflows/pr-checks.yml)) with the default (non-optimized) interpreter, so Python `assert` statements are active. + +- [x] ๐Ÿ”ด **dynamic_analysis_fixed** โ€” Medium+ severity vulnerabilities found by dynamic analysis are fixed in a timely manner. + - *Note:* `[x]` N/A โ€” *Justification: no dynamic analysis tool is currently run, so none have been found.* + +- [x] ๐Ÿ”ต **dynamic_analysis_unsafe** โ€” If the project uses memory-unsafe languages (C/C++), memory safety tools (Valgrind, AddressSanitizer) are used. *(SUGGESTED)* + - *Note:* `[x]` N/A โ€” *Justification: the project is written entirely in Python, a memory-safe language.* + +--- + +## ๐Ÿ“Ž Project-Specific Notes + +> Add domain-specific notes here for Web3, Full-Stack, or AI projects. + +### Web3 / Solidity Notes +- Scorecard does not audit Solidity-specific security. Use [Slither](https://github.com/crytic/slither) for `static_analysis` and `warnings` criteria. +- For `crypto_*` criteria, document which cryptographic primitives your contracts rely on (e.g., ECDSA in EVM is standard). +- Smart contract audit reports count as evidence for `know_secure_design`. + +### Full-Stack / Next.js Notes +- For `crypto_password_storage`: document which auth library handles hashing (e.g., NextAuth + bcrypt). +- For `dynamic_analysis`: [OWASP ZAP](https://www.zaproxy.org/) can be run as a GitHub Action. + +### AI / LLM Notes +- For `know_common_errors`: include awareness of prompt injection, data leakage, and model output validation. +- For `dynamic_analysis`: consider adversarial input testing as a form of dynamic analysis. + +### MiniChain-Specific Notes +- Biggest open gaps found by this pass: no linter in CI (blocks all three `warnings_*` items), and no static/dynamic analysis tooling (blocks all of Analysis except the N/A items). [SECURITY.md](../SECURITY.md) was added, closing the `vulnerability_report_process`/`vulnerability_report_private` gaps, and the tag-triggered [release workflow](../.github/workflows/release.yml) closes the Change Control items. +- `report_responses` / `enhancement_responses` need a manual pass over GitHub Issues history โ€” not derivable from the repo contents. + +--- + +*This checklist complements [OpenSSF Scorecard](https://scorecard.dev/) (auto-detected checks) and is +inspired by the [OpenSSF Best Practices Badge](https://www.bestpractices.dev/en/criteria/0) passing criteria.* diff --git a/docs/brand.md b/docs/brand.md new file mode 100644 index 0000000..3ce2e19 --- /dev/null +++ b/docs/brand.md @@ -0,0 +1,11 @@ +The project has a logo in svg format ([`logo.svg`](../brand/logo.svg)). + +The project has favicons and icons ([`favicon.svg`](../brand/favicon.svg)). + +The project has a color palette (documented in [Brand.md](../brand/Brand.md#color-palette)). + +The project has a typography (documented in [Brand.md](../brand/Brand.md#typography)). + +The project has a [Brand.md](../brand/Brand.md) file describing all of the above. + +All of the above are in the [`brand/`](../brand) folder in the project's repo. diff --git a/docs/maintainer.md b/docs/maintainer.md new file mode 100644 index 0000000..cd0e718 --- /dev/null +++ b/docs/maintainer.md @@ -0,0 +1,26 @@ +# Maintainers, Mentors and Ideators + +This document lists the individuals fulfilling the key roles of [Maintainer](https://github.com/AOSSIE-Org/Info/blob/main/Roles/Maintainer.md), [Mentor](https://github.com/AOSSIE-Org/Info/blob/main/Roles/Mentors.md) and [Ideator](https://github.com/AOSSIE-Org/Info/blob/main/Roles/Ideator.md) for this repository, in accordance with [AOSSIE's Role Definitions](https://github.com/AOSSIE-Org/Info/tree/main/Roles). + +--- + +## Ideators + +MiniChain was completely ideated by Bruno. + +| Name | GitHub Username | Discord Username | Project / Feature Idea | Proposal / Discussion Link | +| ----- | ----------------- | ----------------- | ----------------------- | --------------------------------------------------------------------------------------- | +| Bruno | @zahnentferner | @b.wp | MiniChain | [Discussion](https://discord.com/channels/995968619034984528/1471163521877410045) | + +## Mentors + +| Name | GitHub Username | Discord Username | +| ----- | ----------------- | ----------------- | +| Bruno | @zahnentferner | @b.wp | + +## Maintainers + +| Name | GitHub Username | Discord Username | +| -------- | ----------------- | -------------------- | +| Bruno | @zahnentferner | @b.wp | +| Siddhant | @siddhant | @siddhantcookie |