From a1be9ac4e2f68e3cdab7e0bdf4c747af3c77b2eb Mon Sep 17 00:00:00 2001 From: siddhant Date: Mon, 10 Aug 2026 21:39:38 +0530 Subject: [PATCH 01/17] docs: add brand, maintainer, and agent guideline files Adds brand.md (brand asset locations), maintainer.md (AOSSIE maintainer/mentor/ideator roster template), and agent.md (AGENTS.md-style project instructions for AI coding agents). --- agent.md | 37 +++++++++++++++++++++++++++++++++++++ brand.md | 6 ++++++ maintainer.md | 25 +++++++++++++++++++++++++ 3 files changed, 68 insertions(+) create mode 100644 agent.md create mode 100644 brand.md create mode 100644 maintainer.md diff --git a/agent.md b/agent.md new file mode 100644 index 0000000..b8d46cc --- /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 vendored 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 [Contributors.md](Contributors.md). +- Sign off commits per the [DCO](DCO.md). diff --git a/brand.md b/brand.md new file mode 100644 index 0000000..05a42ca --- /dev/null +++ b/brand.md @@ -0,0 +1,6 @@ +The project has a logo in svg format. +The project has favicons and icons. +The project has a color palette. +The project has a typography. +The project has a Brand.md file describing all of the above. +All of the above are in a "brand" folder in the project's repo. diff --git a/maintainer.md b/maintainer.md new file mode 100644 index 0000000..026407f --- /dev/null +++ b/maintainer.md @@ -0,0 +1,25 @@ +# 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). + +--- + +> **Note:** If multiple contributors are fulfilling a role in a single repository, please include and fill out the extra columns to clarify responsibilities (e.g., `Project / Feature Idea`, `Area / Focus`, and `Proposal / Discussion Link` for Ideators; `Area / Focus` for Mentors and Maintainers). If there is only one person for a role, do not add these columns. + +## Ideators + +| Name | GitHub Username | Discord Username | Project / Feature Idea | Area / Focus | Proposal / Discussion Link | +| ---- | --------------- | ---------------- | -------------------------------- | --------------------- | -------------------------------------------- | +| TODO | @username | @discord_user | Context-First AI Infrastructure | AI Workflow & Skills | [Discussion](https://github.com/AOSSIE-Org) | + +## Mentors + +| Name | GitHub Username | Discord Username | Area / Focus | +| ---- | --------------- | ---------------- | ------------------------------------ | +| TODO | @username | @discord_user | whole Project Guidance & PR Reviews | + +## Maintainers + +| Name | GitHub Username | Discord Username | Area / Focus | +| ---- | --------------- | ---------------- | --------------------------------- | +| TODO | @username | @discord_user | Repository Maintenance & Merging | From ea155c1535396c11fbce7c4aa795b2fbf1fb01c0 Mon Sep 17 00:00:00 2001 From: siddhant Date: Mon, 10 Aug 2026 22:53:43 +0530 Subject: [PATCH 02/17] docs: add best practices checklist Adds a PR checklist covering code placement, testing, docs, git hygiene, and security specific to MiniChain's module layout and contract sandboxing model. --- BestPracticesChecklist.md | 39 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 39 insertions(+) create mode 100644 BestPracticesChecklist.md diff --git a/BestPracticesChecklist.md b/BestPracticesChecklist.md new file mode 100644 index 0000000..526a91b --- /dev/null +++ b/BestPracticesChecklist.md @@ -0,0 +1,39 @@ +# Best Practices Checklist + +Use this checklist before opening or merging a PR against MiniChain. + +## Code + +- [ ] New logic lives in the correct module under `minichain/` (`block.py`, `chain.py`, `state.py`, `mempool.py`, `p2p.py`, `pow.py`, `rpc.py`, `persistence.py`, `contract.py`) rather than a new ad-hoc file. +- [ ] State changes (balances, contract storage) go through `state.py`'s Merkle Patricia Trie APIs, not direct mutation. +- [ ] Contract execution changes preserve gas-per-opcode metering (`sys.settrace`) and process-level sandboxing (`multiprocessing`). +- [ ] Consensus-affecting logic (fork choice, block validity, difficulty) lives in `chain.py`/`pow.py`, not duplicated in `p2p.py`. +- [ ] New JSON-RPC methods follow the `mc_*` naming convention and are documented. +- [ ] No hardcoded secrets, private keys, or node addresses. +- [ ] No edits to `genesis.json`, a node's `--datadir`, or vendored binaries (`bore_bin/`, `bore.zip`) as part of a feature/fix. + +## Tests + +- [ ] New/changed behavior has a corresponding test in `tests/`, named to mirror the module it covers (e.g. `state.py` -> `tests/test_core.py` or a dedicated `tests/test_.py`). +- [ ] `pytest` passes locally. +- [ ] `pytest --cov=minichain` shows coverage did not regress for touched modules. +- [ ] Edge cases covered: invalid transactions/signatures, chain reorgs, malformed P2P messages, contract gas exhaustion, as relevant to the change. + +## Documentation + +- [ ] `README.md` updated if user-facing CLI/RPC behavior changed (do not hand-edit the coverage badge/table — it's CI-generated). +- [ ] `agent.md` updated if a new project-wide convention or boundary was introduced. +- [ ] Docstrings/comments added only where the *why* isn't obvious from the code. + +## Git / PR Hygiene + +- [ ] Branch created off `main`. +- [ ] Commits are signed off per [DCO.md](DCO.md). +- [ ] PR description explains the problem and the fix, per [Contributors.md](Contributors.md). +- [ ] No unrelated changes bundled into the PR (formatting-only diffs, unrelated files). + +## Security + +- [ ] Signature verification (Ed25519 via `pynacl`) is not weakened or bypassed. +- [ ] Contract sandboxing boundaries are not loosened without explicit discussion. +- [ ] Any new external input (RPC params, P2P payloads, contract bytecode) is validated before use. From 8cca89059d656392a60f040c7af2789a91f90905 Mon Sep 17 00:00:00 2001 From: siddhant Date: Mon, 10 Aug 2026 23:09:08 +0530 Subject: [PATCH 03/17] docs: fill in maintainer.md with actual roles Adds Bruno as ideator/mentor/maintainer and Siddhant as maintainer, drops the placeholder note, and removes the Area/Focus column from every table. --- maintainer.md | 23 ++++++++++++----------- 1 file changed, 12 insertions(+), 11 deletions(-) diff --git a/maintainer.md b/maintainer.md index 026407f..cd0e718 100644 --- a/maintainer.md +++ b/maintainer.md @@ -4,22 +4,23 @@ This document lists the individuals fulfilling the key roles of [Maintainer](htt --- -> **Note:** If multiple contributors are fulfilling a role in a single repository, please include and fill out the extra columns to clarify responsibilities (e.g., `Project / Feature Idea`, `Area / Focus`, and `Proposal / Discussion Link` for Ideators; `Area / Focus` for Mentors and Maintainers). If there is only one person for a role, do not add these columns. - ## Ideators -| Name | GitHub Username | Discord Username | Project / Feature Idea | Area / Focus | Proposal / Discussion Link | -| ---- | --------------- | ---------------- | -------------------------------- | --------------------- | -------------------------------------------- | -| TODO | @username | @discord_user | Context-First AI Infrastructure | AI Workflow & Skills | [Discussion](https://github.com/AOSSIE-Org) | +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 | Area / Focus | -| ---- | --------------- | ---------------- | ------------------------------------ | -| TODO | @username | @discord_user | whole Project Guidance & PR Reviews | +| Name | GitHub Username | Discord Username | +| ----- | ----------------- | ----------------- | +| Bruno | @zahnentferner | @b.wp | ## Maintainers -| Name | GitHub Username | Discord Username | Area / Focus | -| ---- | --------------- | ---------------- | --------------------------------- | -| TODO | @username | @discord_user | Repository Maintenance & Merging | +| Name | GitHub Username | Discord Username | +| -------- | ----------------- | -------------------- | +| Bruno | @zahnentferner | @b.wp | +| Siddhant | @siddhant | @siddhantcookie | From 0fe6fe5e372e8bace0574199c6244f1c8bf9bc41 Mon Sep 17 00:00:00 2001 From: siddhant Date: Mon, 10 Aug 2026 23:13:11 +0530 Subject: [PATCH 04/17] docs: move project docs into docs/, add brand/ folder with assets Moves agent.md, maintainer.md, BestPracticesChecklist.md, and brand.md into docs/, fixing their relative links to Contributors.md/DCO.md. Adds a brand/ folder (logo.svg, org-logo.svg, favicon.svg copied from public/) plus brand/Brand.md, a real brand guide covering logo usage, the color palette pulled from the logo's own gradient, and a recommended typography pairing. docs/brand.md now hyperlinks into brand/ instead of just asserting it exists. --- brand.md | 6 -- brand/Brand.md | 63 ++++++++++++++ brand/favicon.svg | 84 +++++++++++++++++++ brand/logo.svg | 84 +++++++++++++++++++ brand/org-logo.svg | 14 ++++ .../BestPracticesChecklist.md | 4 +- agent.md => docs/agent.md | 4 +- docs/brand.md | 11 +++ maintainer.md => docs/maintainer.md | 0 9 files changed, 260 insertions(+), 10 deletions(-) delete mode 100644 brand.md create mode 100644 brand/Brand.md create mode 100644 brand/favicon.svg create mode 100644 brand/logo.svg create mode 100644 brand/org-logo.svg rename BestPracticesChecklist.md => docs/BestPracticesChecklist.md (96%) rename agent.md => docs/agent.md (96%) create mode 100644 docs/brand.md rename maintainer.md => docs/maintainer.md (100%) diff --git a/brand.md b/brand.md deleted file mode 100644 index 05a42ca..0000000 --- a/brand.md +++ /dev/null @@ -1,6 +0,0 @@ -The project has a logo in svg format. -The project has favicons and icons. -The project has a color palette. -The project has a typography. -The project has a Brand.md file describing all of the above. -All of the above are in a "brand" folder in the project's repo. diff --git a/brand/Brand.md b/brand/Brand.md new file mode 100644 index 0000000..92fed4a --- /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 an octahedron-style wireframe: eight triangular edges 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 mark is designed as a regular octahedron 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/BestPracticesChecklist.md b/docs/BestPracticesChecklist.md similarity index 96% rename from BestPracticesChecklist.md rename to docs/BestPracticesChecklist.md index 526a91b..d9fe204 100644 --- a/BestPracticesChecklist.md +++ b/docs/BestPracticesChecklist.md @@ -28,8 +28,8 @@ Use this checklist before opening or merging a PR against MiniChain. ## Git / PR Hygiene - [ ] Branch created off `main`. -- [ ] Commits are signed off per [DCO.md](DCO.md). -- [ ] PR description explains the problem and the fix, per [Contributors.md](Contributors.md). +- [ ] Commits are signed off per [DCO.md](../DCO.md). +- [ ] PR description explains the problem and the fix, per [Contributors.md](../Contributors.md). - [ ] No unrelated changes bundled into the PR (formatting-only diffs, unrelated files). ## Security diff --git a/agent.md b/docs/agent.md similarity index 96% rename from agent.md rename to docs/agent.md index b8d46cc..8d03edf 100644 --- a/agent.md +++ b/docs/agent.md @@ -33,5 +33,5 @@ Python 3.10+, no web framework. Core libs: `pynacl` (Ed25519 signing), `trie` (M ## Git Workflow - Branch off `main`. -- Open PRs against `main`; describe the problem and the fix, per [Contributors.md](Contributors.md). -- Sign off commits per the [DCO](DCO.md). +- Open PRs against `main`; describe the problem and the fix, per [Contributors.md](../Contributors.md). +- Sign off commits per the [DCO](../DCO.md). 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/maintainer.md b/docs/maintainer.md similarity index 100% rename from maintainer.md rename to docs/maintainer.md From ed81aa478231c14aba4bb4c3f3092358ed7809bb Mon Sep 17 00:00:00 2001 From: siddhant Date: Tue, 11 Aug 2026 00:28:37 +0530 Subject: [PATCH 05/17] docs: move agent.md back to repo root AGENTS.md-style files are only auto-discovered by AI coding tools when placed at the repository root, unlike CONTRIBUTING-style community health files which GitHub also recognizes under docs/ or .github/. maintainer.md, BestPracticesChecklist.md, and brand.md stay in docs/ since they have no such discovery requirement. --- docs/agent.md => agent.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) rename docs/agent.md => agent.md (96%) diff --git a/docs/agent.md b/agent.md similarity index 96% rename from docs/agent.md rename to agent.md index 8d03edf..b8d46cc 100644 --- a/docs/agent.md +++ b/agent.md @@ -33,5 +33,5 @@ Python 3.10+, no web framework. Core libs: `pynacl` (Ed25519 signing), `trie` (M ## Git Workflow - Branch off `main`. -- Open PRs against `main`; describe the problem and the fix, per [Contributors.md](../Contributors.md). -- Sign off commits per the [DCO](../DCO.md). +- Open PRs against `main`; describe the problem and the fix, per [Contributors.md](Contributors.md). +- Sign off commits per the [DCO](DCO.md). From 9460270a7b0d44d85dcbfa16986dcf2a9cfc8e92 Mon Sep 17 00:00:00 2001 From: siddhant Date: Tue, 11 Aug 2026 00:29:58 +0530 Subject: [PATCH 06/17] docs: rename Contributors.md to CONTRIBUTING.md Matches GitHub's recognized community-health filename so it surfaces automatically in the contribute/new-issue/new-PR UI. Updates references in agent.md and docs/BestPracticesChecklist.md accordingly. --- Contributors.md => CONTRIBUTING.md | 0 agent.md | 2 +- docs/BestPracticesChecklist.md | 2 +- 3 files changed, 2 insertions(+), 2 deletions(-) rename Contributors.md => CONTRIBUTING.md (100%) diff --git a/Contributors.md b/CONTRIBUTING.md similarity index 100% rename from Contributors.md rename to CONTRIBUTING.md diff --git a/agent.md b/agent.md index b8d46cc..3384b7f 100644 --- a/agent.md +++ b/agent.md @@ -33,5 +33,5 @@ Python 3.10+, no web framework. Core libs: `pynacl` (Ed25519 signing), `trie` (M ## Git Workflow - Branch off `main`. -- Open PRs against `main`; describe the problem and the fix, per [Contributors.md](Contributors.md). +- 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/docs/BestPracticesChecklist.md b/docs/BestPracticesChecklist.md index d9fe204..19c3c60 100644 --- a/docs/BestPracticesChecklist.md +++ b/docs/BestPracticesChecklist.md @@ -29,7 +29,7 @@ Use this checklist before opening or merging a PR against MiniChain. - [ ] Branch created off `main`. - [ ] Commits are signed off per [DCO.md](../DCO.md). -- [ ] PR description explains the problem and the fix, per [Contributors.md](../Contributors.md). +- [ ] PR description explains the problem and the fix, per [CONTRIBUTING.md](../CONTRIBUTING.md). - [ ] No unrelated changes bundled into the PR (formatting-only diffs, unrelated files). ## Security From 3c6c2d839e95395bb962410342b4644727cc40ff Mon Sep 17 00:00:00 2001 From: siddhant Date: Tue, 11 Aug 2026 00:35:15 +0530 Subject: [PATCH 07/17] docs: turn CONTRIBUTING.md into a real guideline, adopt AOSSIE checklist CONTRIBUTING.md now leads with "discuss it first" in the project's Discord (linking the channel from maintainer.md and the Stability Nexus server invite), followed by a Must/Should/Suggested contribution checklist and a step-by-step workflow. The original contributor table is preserved at the bottom. Replaces docs/BestPracticesChecklist.md with the AOSSIE Best Practices Checklist template (adapted from the OpenSSF Best Practices Badge), covering criteria not auto-detected by OpenSSF Scorecard. --- CONTRIBUTING.md | 60 ++++++- docs/BestPracticesChecklist.md | 275 +++++++++++++++++++++++++++++---- 2 files changed, 299 insertions(+), 36 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index e0e23b1..d50343c 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,15 +1,59 @@ -This file contains information about people who contribute to this project. +# Contributing to MiniChain -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). +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. **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. + +--- ## Contributors By having yourself in the table below, all your contributions to this project 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 | +| Name | Github Username | Discord Username | Email Address | +| --------------------------------- | ------------------- | ------------------- | ------------------------------ | +| Bruno Woltzenlogel Paleo | @Zahnentferner | @b.wp | zahnentferner@gmail.com | +| TODO | TODO | TODO | TODO | diff --git a/docs/BestPracticesChecklist.md b/docs/BestPracticesChecklist.md index 19c3c60..0f09b80 100644 --- a/docs/BestPracticesChecklist.md +++ b/docs/BestPracticesChecklist.md @@ -1,39 +1,258 @@ -# Best Practices Checklist +# AOSSIE Best Practices Checklist -Use this checklist before opening or merging a PR against MiniChain. +> 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. -## Code +> **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 -- [ ] New logic lives in the correct module under `minichain/` (`block.py`, `chain.py`, `state.py`, `mempool.py`, `p2p.py`, `pow.py`, `rpc.py`, `persistence.py`, `contract.py`) rather than a new ad-hoc file. -- [ ] State changes (balances, contract storage) go through `state.py`'s Merkle Patricia Trie APIs, not direct mutation. -- [ ] Contract execution changes preserve gas-per-opcode metering (`sys.settrace`) and process-level sandboxing (`multiprocessing`). -- [ ] Consensus-affecting logic (fork choice, block validity, difficulty) lives in `chain.py`/`pow.py`, not duplicated in `p2p.py`. -- [ ] New JSON-RPC methods follow the `mc_*` naming convention and are documented. -- [ ] No hardcoded secrets, private keys, or node addresses. -- [ ] No edits to `genesis.json`, a node's `--datadir`, or vendored binaries (`bore_bin/`, `bore.zip`) as part of a feature/fix. +--- -## Tests +## Score Summary -- [ ] New/changed behavior has a corresponding test in `tests/`, named to mirror the module it covers (e.g. `state.py` -> `tests/test_core.py` or a dedicated `tests/test_.py`). -- [ ] `pytest` passes locally. -- [ ] `pytest --cov=minichain` shows coverage did not regress for touched modules. -- [ ] Edge cases covered: invalid transactions/signatures, chain reorgs, malformed P2P messages, contract gas exhaustion, as relevant to the change. + +| Category | Met | Total | Status | +|--------------------|-----|-------|--------| +| Basics | 0 | 8 | 🔴 | +| Change Control | 0 | 6 | 🔴 | +| Reporting | 0 | 8 | 🔴 | +| Quality | 0 | 11 | 🔴 | +| Security | 0 | 9 | 🔴 | +| Analysis | 0 | 7 | 🔴 | +| **Total** | **0** | **49** | **0%** | +--- -## Documentation +## 🏗️ Basics -- [ ] `README.md` updated if user-facing CLI/RPC behavior changed (do not hand-edit the coverage badge/table — it's CI-generated). -- [ ] `agent.md` updated if a new project-wide convention or boundary was introduced. -- [ ] Docstrings/comments added only where the *why* isn't obvious from the code. +### Project Website & Documentation -## Git / PR Hygiene +- [ ] 🔴 **description_good** — The project README/website clearly describes what the software does and what problem it solves. + - *Evidence URL:* -- [ ] Branch created off `main`. -- [ ] Commits are signed off per [DCO.md](../DCO.md). -- [ ] PR description explains the problem and the fix, per [CONTRIBUTING.md](../CONTRIBUTING.md). -- [ ] No unrelated changes bundled into the PR (formatting-only diffs, unrelated files). +- [ ] 🔴 **interact** — The project provides information on how to obtain the software, submit bug reports, and contribute. + - *Evidence URL:* -## Security +- [ ] 🔴 **contribution** — `CONTRIBUTING.md` explains the contribution process (e.g., PRs are used, how to open one). + - *Evidence URL:* -- [ ] Signature verification (Ed25519 via `pynacl`) is not weakened or bypassed. -- [ ] Contract sandboxing boundaries are not loosened without explicit discussion. -- [ ] Any new external input (RPC params, P2P payloads, contract bytecode) is validated before use. +- [ ] 🟡 **contribution_requirements** — `CONTRIBUTING.md` references acceptable contribution standards (coding style, tests required, etc.). + - *Evidence URL:* + +- [ ] 🔴 **documentation_basics** — Basic documentation exists for the software (README, Wiki, or docs folder). + - *Evidence URL:* `[ ]` N/A — *Justification:* + +- [ ] 🔴 **documentation_interface** — Reference documentation describes the external interface (API inputs/outputs, CLI flags, config schema, etc.). + - *Evidence URL:* `[ ]` N/A — *Justification:* + +### Other Basics + +- [ ] 🔴 **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:* + +- [ ] 🟡 **english** — Documentation is provided in English and English bug reports/comments are accepted. + - *Note:* + +--- + +## 🔄 Change Control + +### Version Control + +- [ ] 🔵 **repo_distributed** — Project uses a distributed VCS (e.g., git). *(SUGGESTED)* + - *Evidence URL:* + +### Version Numbering + +- [ ] 🔴 **version_unique** — Each release has a unique version identifier (e.g., v1.0.0). + - *Evidence URL:* + +- [ ] 🔵 **version_semver** — Project uses [SemVer](https://semver.org) or [CalVer](https://calver.org/) format. *(SUGGESTED)* + - *Note:* + +- [ ] 🔵 **version_tags** — Releases are tagged in the VCS (e.g., `git tag v1.0.0`). *(SUGGESTED)* + - *Evidence URL:* + +### Release Notes + +- [ ] 🔴 **release_notes** — Each release includes human-readable release notes summarizing major changes. Raw `git log` output is NOT acceptable. + - *Evidence URL:* `[ ]` N/A — *Justification (continuous delivery / no external reuse):* + +- [ ] 🔴 **release_notes_vulns** — Release notes identify every publicly known vulnerability (with CVE) fixed in that release. + - *Evidence URL:* `[ ]` N/A — *Justification (no publicly known vulns / users can't self-update):* + +--- + +## 🐛 Reporting + +### Bug Reporting + +- [ ] 🔴 **report_process** — A bug-reporting process exists (e.g., GitHub Issues link in README). + - *Evidence URL:* + +- [ ] 🟡 **report_tracker** — An issue tracker (e.g., GitHub Issues) is used to track individual bugs. + - *Evidence URL:* + +- [ ] 🔴 **report_responses** — A majority of bug reports submitted in the last 2–12 months have been acknowledged (response ≠ fix). + - *Self-certification note:* + +- [ ] 🟡 **enhancement_responses** — More than 50% of enhancement requests in the last 2–12 months have received a response. + - *Self-certification note:* + +- [ ] 🔴 **report_archive** — Reports and responses are publicly archived and searchable (GitHub Issues satisfies this). + - *Evidence URL:* + +### Vulnerability Reporting + +- [ ] 🔴 **vulnerability_report_process** — A vulnerability reporting process is documented (e.g., `SECURITY.md`). + - *Evidence URL:* + +- [ ] 🟡 **vulnerability_report_private** — If private vulnerability reporting is supported, the method for private submission is documented. + - *Evidence URL:* `[ ]` N/A — *Justification:* + +- [ ] 🔴 **vulnerability_report_response** — Initial response to any vulnerability report received in the last 6 months was within 14 days. + - *Self-certification note:* `[ ]` N/A — *Justification (no reports received):* + +--- + +## ✅ Quality + +### Build System + +- [ ] 🔴 **build** — If the project requires building, a working build system exists that can auto-rebuild from source. + - *Evidence URL:* `[ ]` N/A — *Justification (interpreted language / no build step):* + +- [ ] 🔵 **build_common_tools** — Common build tools are used (npm, pip, cargo, make, gradle, etc.). *(SUGGESTED)* + - *Evidence URL:* `[ ]` N/A + +- [ ] 🟡 **build_floss_tools** — The project can be built using only FLOSS tools. + - *Note:* `[ ]` N/A + +### Automated Testing + +- [ ] 🔵 **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:* + +- [ ] 🔵 **test_most** — The test suite covers most code branches, input fields, and functionality. *(SUGGESTED)* + - *Estimated coverage %:* + +### New Functionality Testing Policy + +- [ ] 🔴 **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):* + +- [ ] 🔴 **tests_are_added** — Evidence exists that the test policy has been followed in recent major changes (e.g., PRs include tests). + - *Evidence URL (recent PR with tests):* + +- [ ] 🔵 **tests_documented_added** — The test policy is documented in contribution instructions. *(SUGGESTED)* + - *Evidence URL:* + +### 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:* + +- [ ] 🔴 **warnings_fixed** — Warnings from the linter are addressed (not suppressed without reason). + - *Note:* + +- [ ] 🔵 **warnings_strict** — Project uses maximum strictness in linter config where practical. *(SUGGESTED)* + - *Note:* + +--- + +## 🔐 Security + +### Secure Development Knowledge + +- [ ] 🔴 **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:* + +- [ ] 🔴 **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:* + +### Cryptography (mark N/A if project does not handle cryptography) + +- [ ] 🔴 **crypto_published** — Only publicly reviewed cryptographic protocols/algorithms are used by default. + - *Note:* `[ ]` N/A + +- [ ] 🟡 **crypto_call** — Project calls an established crypto library rather than reimplementing crypto functions. + - *Library used:* `[ ]` N/A + +- [ ] 🔴 **crypto_working** — No broken algorithms (MD4, MD5, single DES, RC4, Dual_EC_DRBG) used unless required for interoperability (must be documented). + - *Note:* `[ ]` N/A + +- [ ] 🔴 **crypto_keylength** — Key lengths meet [NIST 2030 minimums](https://www.keylength.com/en/4/) by default. + - *Note:* `[ ]` N/A + +- [ ] 🔴 **crypto_password_storage** — Passwords for external users are stored as iterated salted hashes (Argon2id, bcrypt, scrypt, PBKDF2). + - *Note:* `[ ]` N/A — *Justification (project doesn't store passwords):* + +- [ ] 🔴 **crypto_random** — Cryptographic keys and nonces are generated using a CSPRNG; insecure generators (Math.random, rand()) are NOT used for security purposes. + - *Note:* `[ ]` N/A + +- [ ] 🟡 **delivery_unsigned** — Cryptographic hashes are NOT retrieved over plain HTTP without a signature check. + - *Note:* + +--- + +## 🔬 Analysis + +### Static Code Analysis + +- [ ] 🔴 **static_analysis_fixed** — All medium+ severity vulnerabilities found by static analysis are fixed in a timely manner after confirmation. + - *Note:* `[ ]` 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:* `[ ]` N/A + +- [ ] 🔵 **static_analysis_often** — Static analysis runs on every commit or at least daily (CI integration). *(SUGGESTED)* + - *Evidence URL:* `[ ]` 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:* `[ ]` N/A — *Justification:* + +- [ ] 🔵 **dynamic_analysis_enable_assertions** — Dynamic analysis / testing runs with assertions enabled (not just production mode). *(SUGGESTED)* + - *Note:* + +- [ ] 🔴 **dynamic_analysis_fixed** — Medium+ severity vulnerabilities found by dynamic analysis are fixed in a timely manner. + - *Note:* `[ ]` N/A + +- [ ] 🔵 **dynamic_analysis_unsafe** — If the project uses memory-unsafe languages (C/C++), memory safety tools (Valgrind, AddressSanitizer) are used. *(SUGGESTED)* + - *Note:* `[ ]` N/A — *Justification (project uses memory-safe languages):* + +--- + +## 📎 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. + +--- + +*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.* From a3920f1253b487af37f1f8e0397827bc23b9c7fa Mon Sep 17 00:00:00 2001 From: siddhant Date: Tue, 11 Aug 2026 00:35:34 +0530 Subject: [PATCH 08/17] docs: drop contributor table from CONTRIBUTING.md CONTRIBUTING.md is a guideline, not a roster; keeps the DCO reference without the table. --- CONTRIBUTING.md | 12 +----------- 1 file changed, 1 insertion(+), 11 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index d50343c..b98782c 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -46,14 +46,4 @@ Only after that discussion should you start implementation — this is the first - 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. ---- - -## Contributors - -By having yourself in the table below, all your contributions to this project -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 | +All contributions to this project are made under the terms of the [Developer Certificate of Origin](DCO.md). From f16ebb235b59b7ab0d00121b80cbecb61a72dbad Mon Sep 17 00:00:00 2001 From: siddhant Date: Tue, 11 Aug 2026 00:41:33 +0530 Subject: [PATCH 09/17] docs: fill in BestPracticesChecklist.md against actual repo state Walked every criterion against the codebase, CI workflows, and existing docs: description/interaction/contribution basics are met via README + CONTRIBUTING.md; crypto criteria are met (PyNaCl Ed25519 + SHA-256 only, CSPRNG key generation); memory-safety and password-storage items are N/A (pure Python, no passwords). Gaps found and left unmet with evidence: no SECURITY.md (vulnerability_report_process), no linter configured in CI (all warnings_* items), no static/dynamic analysis tooling beyond CodeRabbit's AI review (Analysis category), no tagged releases (Change Control version/release items), and uneven test coverage (test_most, 67% overall per the coverage badge). Issue response-time criteria are left unmet as not verifiable from repo contents alone. Score summary updated to 35/49 (71%). --- docs/BestPracticesChecklist.md | 190 +++++++++++++++++---------------- 1 file changed, 98 insertions(+), 92 deletions(-) diff --git a/docs/BestPracticesChecklist.md b/docs/BestPracticesChecklist.md index 0f09b80..63fcd7b 100644 --- a/docs/BestPracticesChecklist.md +++ b/docs/BestPracticesChecklist.md @@ -17,6 +17,8 @@ > - 🟡 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. --- @@ -25,44 +27,44 @@ | Category | Met | Total | Status | |--------------------|-----|-------|--------| -| Basics | 0 | 8 | 🔴 | -| Change Control | 0 | 6 | 🔴 | -| Reporting | 0 | 8 | 🔴 | -| Quality | 0 | 11 | 🔴 | -| Security | 0 | 9 | 🔴 | -| Analysis | 0 | 7 | 🔴 | -| **Total** | **0** | **49** | **0%** | +| Basics | 8 | 8 | 🟢 | +| Change Control | 3 | 6 | 🟡 | +| Reporting | 5 | 8 | 🟡 | +| Quality | 7 | 11 | 🟡 | +| Security | 9 | 9 | 🟢 | +| Analysis | 3 | 7 | 🔴 | +| **Total** | **35** | **49** | **71%** | --- ## 🏗️ Basics ### Project Website & Documentation -- [ ] 🔴 **description_good** — The project README/website clearly describes what the software does and what problem it solves. - - *Evidence URL:* +- [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." -- [ ] 🔴 **interact** — The project provides information on how to obtain the software, submit bug reports, and contribute. - - *Evidence URL:* +- [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) -- [ ] 🔴 **contribution** — `CONTRIBUTING.md` explains the contribution process (e.g., PRs are used, how to open one). - - *Evidence URL:* +- [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) -- [ ] 🟡 **contribution_requirements** — `CONTRIBUTING.md` references acceptable contribution standards (coding style, tests required, etc.). - - *Evidence URL:* +- [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)) -- [ ] 🔴 **documentation_basics** — Basic documentation exists for the software (README, Wiki, or docs folder). - - *Evidence URL:* `[ ]` N/A — *Justification:* +- [x] 🔴 **documentation_basics** — Basic documentation exists for the software (README, Wiki, or docs folder). + - *Evidence URL:* [README.md](../README.md), [docs/](.) `[ ]` N/A — *Justification:* -- [ ] 🔴 **documentation_interface** — Reference documentation describes the external interface (API inputs/outputs, CLI flags, config schema, etc.). - - *Evidence URL:* `[ ]` 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 -- [ ] 🔴 **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:* +- [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) -- [ ] 🟡 **english** — Documentation is provided in English and English bug reports/comments are accepted. - - *Note:* +- [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. --- @@ -70,27 +72,27 @@ ### Version Control -- [ ] 🔵 **repo_distributed** — Project uses a distributed VCS (e.g., git). *(SUGGESTED)* - - *Evidence URL:* +- [x] 🔵 **repo_distributed** — Project uses a distributed VCS (e.g., git). *(SUGGESTED)* + - *Evidence URL:* Git repository, hosted at `StabilityNexus/MiniChain` on GitHub. ### Version Numbering - [ ] 🔴 **version_unique** — Each release has a unique version identifier (e.g., v1.0.0). - - *Evidence URL:* + - *Evidence URL:* None — no tagged releases exist yet (`git tag` is empty). - [ ] 🔵 **version_semver** — Project uses [SemVer](https://semver.org) or [CalVer](https://calver.org/) format. *(SUGGESTED)* - - *Note:* + - *Note:* No versioning scheme is in use yet; no `__version__`/package version found in the repo. - [ ] 🔵 **version_tags** — Releases are tagged in the VCS (e.g., `git tag v1.0.0`). *(SUGGESTED)* - - *Evidence URL:* + - *Evidence URL:* None — repository has no tags. ### Release Notes -- [ ] 🔴 **release_notes** — Each release includes human-readable release notes summarizing major changes. Raw `git log` output is NOT acceptable. - - *Evidence URL:* `[ ]` N/A — *Justification (continuous delivery / no external reuse):* +- [x] 🔴 **release_notes** — Each release includes human-readable release notes summarizing major changes. Raw `git log` output is NOT acceptable. + - *Evidence URL:* `[x]` N/A — *Justification: project has not cut any releases yet; it is developed via continuous commits to `main`. Revisit once the first tagged release is planned.* -- [ ] 🔴 **release_notes_vulns** — Release notes identify every publicly known vulnerability (with CVE) fixed in that release. - - *Evidence URL:* `[ ]` N/A — *Justification (no publicly known vulns / users can't self-update):* +- [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.* --- @@ -98,31 +100,31 @@ ### Bug Reporting -- [ ] 🔴 **report_process** — A bug-reporting process exists (e.g., GitHub Issues link in README). - - *Evidence URL:* +- [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." -- [ ] 🟡 **report_tracker** — An issue tracker (e.g., GitHub Issues) is used to track individual bugs. - - *Evidence URL:* +- [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:* + - *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:* + - *Self-certification note:* Not verifiable from repo contents alone — needs a manual check of GitHub Issues response times. -- [ ] 🔴 **report_archive** — Reports and responses are publicly archived and searchable (GitHub Issues satisfies this). - - *Evidence URL:* +- [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 - [ ] 🔴 **vulnerability_report_process** — A vulnerability reporting process is documented (e.g., `SECURITY.md`). - - *Evidence URL:* + - *Evidence URL:* None — no `SECURITY.md` exists in the repo yet. -- [ ] 🟡 **vulnerability_report_private** — If private vulnerability reporting is supported, the method for private submission is documented. - - *Evidence URL:* `[ ]` N/A — *Justification:* +- [x] 🟡 **vulnerability_report_private** — If private vulnerability reporting is supported, the method for private submission is documented. + - *Evidence URL:* `[x]` N/A — *Justification: no private vulnerability reporting channel exists yet (no `SECURITY.md` / GitHub private vulnerability reporting not enabled).* -- [ ] 🔴 **vulnerability_report_response** — Initial response to any vulnerability report received in the last 6 months was within 14 days. - - *Self-certification note:* `[ ]` N/A — *Justification (no reports received):* +- [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.* --- @@ -130,44 +132,44 @@ ### Build System -- [ ] 🔴 **build** — If the project requires building, a working build system exists that can auto-rebuild from source. - - *Evidence URL:* `[ ]` N/A — *Justification (interpreted language / no build step):* +- [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`.* -- [ ] 🔵 **build_common_tools** — Common build tools are used (npm, pip, cargo, make, gradle, etc.). *(SUGGESTED)* - - *Evidence URL:* `[ ]` N/A +- [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`. -- [ ] 🟡 **build_floss_tools** — The project can be built using only FLOSS tools. - - *Note:* `[ ]` N/A +- [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 -- [ ] 🔵 **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:* +- [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 %:* + - *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 -- [ ] 🔴 **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):* +- [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." -- [ ] 🔴 **tests_are_added** — Evidence exists that the test policy has been followed in recent major changes (e.g., PRs include tests). - - *Evidence URL (recent PR with tests):* +- [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). -- [ ] 🔵 **tests_documented_added** — The test policy is documented in contribution instructions. *(SUGGESTED)* - - *Evidence URL:* +- [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:* + - *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:* + - *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:* + - *Note:* No linter configured yet. --- @@ -175,34 +177,34 @@ ### Secure Development Knowledge -- [ ] 🔴 **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:* +- [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)). -- [ ] 🔴 **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:* +- [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 (mark N/A if project does not handle cryptography) +### Cryptography -- [ ] 🔴 **crypto_published** — Only publicly reviewed cryptographic protocols/algorithms are used by default. - - *Note:* `[ ]` N/A +- [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 -- [ ] 🟡 **crypto_call** — Project calls an established crypto library rather than reimplementing crypto functions. - - *Library used:* `[ ]` 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 -- [ ] 🔴 **crypto_working** — No broken algorithms (MD4, MD5, single DES, RC4, Dual_EC_DRBG) used unless required for interoperability (must be documented). - - *Note:* `[ ]` 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 -- [ ] 🔴 **crypto_keylength** — Key lengths meet [NIST 2030 minimums](https://www.keylength.com/en/4/) by default. - - *Note:* `[ ]` 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 -- [ ] 🔴 **crypto_password_storage** — Passwords for external users are stored as iterated salted hashes (Argon2id, bcrypt, scrypt, PBKDF2). - - *Note:* `[ ]` N/A — *Justification (project doesn't store passwords):* +- [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.* -- [ ] 🔴 **crypto_random** — Cryptographic keys and nonces are generated using a CSPRNG; insecure generators (Math.random, rand()) are NOT used for security purposes. - - *Note:* `[ ]` N/A +- [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 -- [ ] 🟡 **delivery_unsigned** — Cryptographic hashes are NOT retrieved over plain HTTP without a signature check. - - *Note:* +- [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.* --- @@ -211,27 +213,27 @@ ### Static Code Analysis - [ ] 🔴 **static_analysis_fixed** — All medium+ severity vulnerabilities found by static analysis are fixed in a timely manner after confirmation. - - *Note:* `[ ]` N/A + - *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:* `[ ]` N/A + - *Tool + ruleset:* None configured. `[ ]` N/A - [ ] 🔵 **static_analysis_often** — Static analysis runs on every commit or at least daily (CI integration). *(SUGGESTED)* - - *Evidence URL:* `[ ]` N/A + - *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:* `[ ]` N/A — *Justification:* + - *Tool used:* None found. `[ ]` N/A — *Justification:* -- [ ] 🔵 **dynamic_analysis_enable_assertions** — Dynamic analysis / testing runs with assertions enabled (not just production mode). *(SUGGESTED)* - - *Note:* +- [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. -- [ ] 🔴 **dynamic_analysis_fixed** — Medium+ severity vulnerabilities found by dynamic analysis are fixed in a timely manner. - - *Note:* `[ ]` N/A +- [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.* -- [ ] 🔵 **dynamic_analysis_unsafe** — If the project uses memory-unsafe languages (C/C++), memory safety tools (Valgrind, AddressSanitizer) are used. *(SUGGESTED)* - - *Note:* `[ ]` N/A — *Justification (project uses memory-safe languages):* +- [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.* --- @@ -252,6 +254,10 @@ - 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 `SECURITY.md` (blocks `vulnerability_report_process`), no linter in CI (blocks all three `warnings_*` items), and no static/dynamic analysis tooling (blocks all of Analysis except the N/A items). Tagging a first release would also unlock 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 From 5bcd0a65f2f06f5fffaa5d0a75045dd1cd11f4ba Mon Sep 17 00:00:00 2001 From: siddhant Date: Tue, 11 Aug 2026 02:08:21 +0530 Subject: [PATCH 10/17] docs: add SECURITY.md, update checklist to reflect it Adds a SECURITY.md with private reporting channels (GitHub Security Advisories, email), response-time expectations, and vulnerability scope specific to MiniChain (signature forgery, contract sandbox escape, consensus manipulation, P2P DoS, RPC abuse). Flips vulnerability_report_process and vulnerability_report_private to Met in docs/BestPracticesChecklist.md now that the process is documented. Score updated to 36/49 (73%). --- SECURITY.md | 43 ++++++++++++++++++++++++++++++++++ docs/BestPracticesChecklist.md | 12 +++++----- 2 files changed, 49 insertions(+), 6 deletions(-) create mode 100644 SECURITY.md diff --git a/SECURITY.md b/SECURITY.md new file mode 100644 index 0000000..b338a09 --- /dev/null +++ b/SECURITY.md @@ -0,0 +1,43 @@ +# Security Policy + +## Supported Versions + +MiniChain does not yet have tagged releases or a formal versioning scheme. Security fixes are applied to the latest commit on `main`, which is the only version supported. + +## 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 via the "Security" tab on the [MiniChain repository](https://github.com/StabilityNexus/MiniChain/security/advisories/new). +2. **Email:** [zahnentferner@gmail.com](mailto:zahnentferner@gmail.com) — include "MiniChain Security" in the subject line. + +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 vendored 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/docs/BestPracticesChecklist.md b/docs/BestPracticesChecklist.md index 63fcd7b..e4da3ab 100644 --- a/docs/BestPracticesChecklist.md +++ b/docs/BestPracticesChecklist.md @@ -29,11 +29,11 @@ |--------------------|-----|-------|--------| | Basics | 8 | 8 | 🟢 | | Change Control | 3 | 6 | 🟡 | -| Reporting | 5 | 8 | 🟡 | +| Reporting | 6 | 8 | 🟡 | | Quality | 7 | 11 | 🟡 | | Security | 9 | 9 | 🟢 | | Analysis | 3 | 7 | 🔴 | -| **Total** | **35** | **49** | **71%** | +| **Total** | **36** | **49** | **73%** | --- ## 🏗️ Basics @@ -117,11 +117,11 @@ ### Vulnerability Reporting -- [ ] 🔴 **vulnerability_report_process** — A vulnerability reporting process is documented (e.g., `SECURITY.md`). - - *Evidence URL:* None — no `SECURITY.md` exists in the repo yet. +- [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:* `[x]` N/A — *Justification: no private vulnerability reporting channel exists yet (no `SECURITY.md` / GitHub private vulnerability reporting not enabled).* + - *Evidence URL:* [SECURITY.md § Reporting a Vulnerability](../SECURITY.md#reporting-a-vulnerability) — documents GitHub Security Advisories and a private email address. - [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.* @@ -255,7 +255,7 @@ - For `dynamic_analysis`: consider adversarial input testing as a form of dynamic analysis. ### MiniChain-Specific Notes -- Biggest open gaps found by this pass: no `SECURITY.md` (blocks `vulnerability_report_process`), no linter in CI (blocks all three `warnings_*` items), and no static/dynamic analysis tooling (blocks all of Analysis except the N/A items). Tagging a first release would also unlock the Change Control items. +- 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). Tagging a first release would also unlock the Change Control items. [SECURITY.md](../SECURITY.md) was added, closing the `vulnerability_report_process`/`vulnerability_report_private` gaps. - `report_responses` / `enhancement_responses` need a manual pass over GitHub Issues history — not derivable from the repo contents. --- From 98387792727cb59d34900d4fd8d2fa2938ccd066 Mon Sep 17 00:00:00 2001 From: siddhant Date: Tue, 11 Aug 2026 02:10:48 +0530 Subject: [PATCH 11/17] docs: drop email contact from SECURITY.md, use GitHub reporting only Keeps GitHub Private Vulnerability Reporting as the sole private channel instead of publishing a personal email address. --- SECURITY.md | 5 +---- docs/BestPracticesChecklist.md | 2 +- 2 files changed, 2 insertions(+), 5 deletions(-) diff --git a/SECURITY.md b/SECURITY.md index b338a09..0c8c95c 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -8,10 +8,7 @@ MiniChain does not yet have tagged releases or a formal versioning scheme. Secur **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 via the "Security" tab on the [MiniChain repository](https://github.com/StabilityNexus/MiniChain/security/advisories/new). -2. **Email:** [zahnentferner@gmail.com](mailto:zahnentferner@gmail.com) — include "MiniChain Security" in the subject line. +Instead, report it privately via **GitHub Private Vulnerability Reporting**: open a report using the "Security" tab on the [MiniChain repository](https://github.com/StabilityNexus/MiniChain/security/advisories/new). Please include as much of the following as you can: diff --git a/docs/BestPracticesChecklist.md b/docs/BestPracticesChecklist.md index e4da3ab..4384a49 100644 --- a/docs/BestPracticesChecklist.md +++ b/docs/BestPracticesChecklist.md @@ -121,7 +121,7 @@ - *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 Security Advisories and a private email address. + - *Evidence URL:* [SECURITY.md § Reporting a Vulnerability](../SECURITY.md#reporting-a-vulnerability) — documents GitHub Private Vulnerability Reporting via the Security tab. - [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.* From 88abd1e78942b62eedeefc16c9fcbf708721453e Mon Sep 17 00:00:00 2001 From: siddhant Date: Tue, 11 Aug 2026 02:13:22 +0530 Subject: [PATCH 12/17] docs: add Discord DM as a private vulnerability reporting fallback Points reporters to the maintainers listed in docs/maintainer.md for a private Discord DM, alongside GitHub Private Vulnerability Reporting. --- SECURITY.md | 5 ++++- docs/BestPracticesChecklist.md | 2 +- 2 files changed, 5 insertions(+), 2 deletions(-) diff --git a/SECURITY.md b/SECURITY.md index 0c8c95c..20284cd 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -8,7 +8,10 @@ MiniChain does not yet have tagged releases or a formal versioning scheme. Secur **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 via **GitHub Private Vulnerability Reporting**: open a report using the "Security" tab on the [MiniChain repository](https://github.com/StabilityNexus/MiniChain/security/advisories/new). +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) on the [Stability Nexus Discord](https://discord.gg/YzDKeEfWtS) — do not post details in a public channel. Please include as much of the following as you can: diff --git a/docs/BestPracticesChecklist.md b/docs/BestPracticesChecklist.md index 4384a49..040f009 100644 --- a/docs/BestPracticesChecklist.md +++ b/docs/BestPracticesChecklist.md @@ -121,7 +121,7 @@ - *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. + - *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.* From 08680f5a4d43aa01b7eeaad91468d290d6810d62 Mon Sep 17 00:00:00 2001 From: siddhant Date: Tue, 11 Aug 2026 02:16:10 +0530 Subject: [PATCH 13/17] final docs --- SECURITY.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/SECURITY.md b/SECURITY.md index 20284cd..593732a 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -11,7 +11,7 @@ MiniChain does not yet have tagged releases or a formal versioning scheme. Secur 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) on the [Stability Nexus Discord](https://discord.gg/YzDKeEfWtS) — do not post details in a public channel. +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: From e326f2ec6073241ea293c1da7208353127198102 Mon Sep 17 00:00:00 2001 From: siddhant Date: Tue, 11 Aug 2026 02:20:11 +0530 Subject: [PATCH 14/17] docs: restore Contributors.md, link it from CONTRIBUTING.md Contributors.md was folded into CONTRIBUTING.md's rename; restores it as a standalone contributor roster (original content) with Siddhant added, and points CONTRIBUTING.md at it as the place to add yourself after opening a PR. --- CONTRIBUTING.md | 5 +++-- Contributors.md | 16 ++++++++++++++++ 2 files changed, 19 insertions(+), 2 deletions(-) create mode 100644 Contributors.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index b98782c..b4f00ea 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -39,11 +39,12 @@ Only after that discussion should you start implementation — this is the first pytest ``` 6. **Sign off your commits** per the [DCO](DCO.md) (`git commit -s`). -7. **Open a pull request** against `main`, describing the problem and the fix, and linking back to the Discord discussion or issue. +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). +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 new file mode 100644 index 0000000..7df664f --- /dev/null +++ b/Contributors.md @@ -0,0 +1,16 @@ +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). + +## Contributors + +By having yourself in the table below, all your contributions to this project +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 | +| Siddhant | @siddhant | @siddhantcookie | TODO | +| TODO | TODO | TODO | TODO | From bcc880f8f5af4b1c0493c33f5c01c38e88d8613b Mon Sep 17 00:00:00 2001 From: siddhant Date: Tue, 11 Aug 2026 02:21:09 +0530 Subject: [PATCH 15/17] docs: add Siddhant's email to Contributors.md --- Contributors.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Contributors.md b/Contributors.md index 7df664f..3dbd964 100644 --- a/Contributors.md +++ b/Contributors.md @@ -12,5 +12,5 @@ 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 | -| Siddhant | @siddhant | @siddhantcookie | TODO | +| Siddhant | @siddhant | @siddhantcookie | siddhantkk27@gmail.com | | TODO | TODO | TODO | TODO | From c662a36d4bbbfc87b74ca5cfa0a6972330b2cce8 Mon Sep 17 00:00:00 2001 From: siddhant Date: Tue, 11 Aug 2026 02:21:40 +0530 Subject: [PATCH 16/17] docs: point Contributors.md at the actual Discord server and channel Replaces the old invite link and TODO channel placeholder with the Stability Nexus Discord invite and MiniChain discussion channel already used in maintainer.md/CONTRIBUTING.md. --- Contributors.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Contributors.md b/Contributors.md index 3dbd964..106f967 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 From aba16aad7f41bf5164504f0bb34ca9efd1e215a3 Mon Sep 17 00:00:00 2001 From: siddhant Date: Wed, 12 Aug 2026 01:56:07 +0530 Subject: [PATCH 17/17] docs: address PR review feedback from Zahnentferner - brand/Brand.md: logo is a 4D hypercube (tesseract) projection, not an octahedron. - agent.md: "vendored" -> "vendor". - Contributors.md: drop the leftover TODO row. - SECURITY.md: Supported Versions now reflects the tag-triggered release workflow (SemVer vX.Y.Z tags, pyproject.toml version) instead of claiming no releases exist. Also updates docs/BestPracticesChecklist.md's Change Control section to Met now that tagged SemVer releases with auto-generated release notes exist. Score: 39/49 (80%). --- Contributors.md | 1 - SECURITY.md | 10 ++++++++-- agent.md | 2 +- brand/Brand.md | 4 ++-- docs/BestPracticesChecklist.md | 20 ++++++++++---------- 5 files changed, 21 insertions(+), 16 deletions(-) diff --git a/Contributors.md b/Contributors.md index 106f967..5e2e569 100644 --- a/Contributors.md +++ b/Contributors.md @@ -13,4 +13,3 @@ are made under the terms of the [Developer Certificate of Origin](DCO.md). | -------------------------------- | ------------------ | ------------------ | ---------------------------- | | Bruno Woltzenlogel Paleo | @Zahnentferner | @b.wp | zahnentferner@gmail.com | | Siddhant | @siddhant | @siddhantcookie | siddhantkk27@gmail.com | -| TODO | TODO | TODO | TODO | diff --git a/SECURITY.md b/SECURITY.md index 593732a..9459ac5 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -2,7 +2,13 @@ ## Supported Versions -MiniChain does not yet have tagged releases or a formal versioning scheme. Security fixes are applied to the latest commit on `main`, which is the only version supported. +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 @@ -36,7 +42,7 @@ Given MiniChain's goals — education, research, and innovation on a minimal blo - 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 vendored third-party binaries (`bore_bin/`, `bore.zip`) should be reported upstream to their respective projects. +Out of scope: issues in vendor third-party binaries (`bore_bin/`, `bore.zip`) should be reported upstream to their respective projects. ## Questions diff --git a/agent.md b/agent.md index 3384b7f..f12c703 100644 --- a/agent.md +++ b/agent.md @@ -27,7 +27,7 @@ Python 3.10+, no web framework. Core libs: `pynacl` (Ed25519 signing), `trie` (M ## 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 vendored binaries — do not edit or regenerate them by hand. +- `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 diff --git a/brand/Brand.md b/brand/Brand.md index 92fed4a..b8e899c 100644 --- a/brand/Brand.md +++ b/brand/Brand.md @@ -4,7 +4,7 @@ MiniChain is a minimal, fully functional blockchain implemented in Python, built ## Logo -MiniChain's mark is an octahedron-style wireframe: eight triangular edges 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. +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. @@ -13,7 +13,7 @@ MiniChain's mark is an octahedron-style wireframe: eight triangular edges radiat - 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 mark is designed as a regular octahedron and should scale uniformly. +- 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 diff --git a/docs/BestPracticesChecklist.md b/docs/BestPracticesChecklist.md index 040f009..d8aecd5 100644 --- a/docs/BestPracticesChecklist.md +++ b/docs/BestPracticesChecklist.md @@ -28,12 +28,12 @@ | Category | Met | Total | Status | |--------------------|-----|-------|--------| | Basics | 8 | 8 | 🟢 | -| Change Control | 3 | 6 | 🟡 | +| Change Control | 6 | 6 | 🟢 | | Reporting | 6 | 8 | 🟡 | | Quality | 7 | 11 | 🟡 | | Security | 9 | 9 | 🟢 | | Analysis | 3 | 7 | 🔴 | -| **Total** | **36** | **49** | **73%** | +| **Total** | **39** | **49** | **80%** | --- ## 🏗️ Basics @@ -77,19 +77,19 @@ ### Version Numbering -- [ ] 🔴 **version_unique** — Each release has a unique version identifier (e.g., v1.0.0). - - *Evidence URL:* None — no tagged releases exist yet (`git tag` is empty). +- [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). -- [ ] 🔵 **version_semver** — Project uses [SemVer](https://semver.org) or [CalVer](https://calver.org/) format. *(SUGGESTED)* - - *Note:* No versioning scheme is in use yet; no `__version__`/package version found in the repo. +- [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. -- [ ] 🔵 **version_tags** — Releases are tagged in the VCS (e.g., `git tag v1.0.0`). *(SUGGESTED)* - - *Evidence URL:* None — repository has no tags. +- [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:* `[x]` N/A — *Justification: project has not cut any releases yet; it is developed via continuous commits to `main`. Revisit once the first tagged release is planned.* + - *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.* @@ -255,7 +255,7 @@ - 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). Tagging a first release would also unlock the Change Control items. [SECURITY.md](../SECURITY.md) was added, closing the `vulnerability_report_process`/`vulnerability_report_private` gaps. +- 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. ---