Docs/contributing maintainers agents #136
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,50 @@ | ||
| # Contributing to MiniChain | ||
|
|
||
| Thanks for your interest in contributing to MiniChain! This document explains how to get involved, from discussing an idea to getting a pull request merged. | ||
|
|
||
| ## Before You Start: Discuss It First | ||
|
|
||
| **Every contribution — bug fix, feature, or refactor — should be discussed before you start writing code.** This avoids duplicate work and makes sure the change fits the project's minimality-first philosophy. | ||
|
|
||
| 1. Join the [Stability Nexus Discord server](https://discord.gg/YzDKeEfWtS). | ||
| 2. Discuss your issue, bug, or feature idea in the project's channel/thread: [MiniChain discussion](https://discord.com/channels/995968619034984528/1471163521877410045). | ||
| 3. If it's a confirmed bug or an agreed-upon feature, open a matching GitHub Issue in this repository describing the problem and the proposed approach. | ||
|
|
||
| Only after that discussion should you start implementation — this is the first and most important rule below. | ||
|
|
||
| ## Contribution Checklist | ||
|
|
||
| - 🔴 **MUST** — Discuss non-trivial changes in Discord (see above) or in a GitHub Issue before opening a PR. | ||
| - 🔴 **MUST** — Follow the module layout and architecture constraints described in [agent.md](agent.md) (one concern per module under `minichain/`, state changes go through `state.py`, etc.). | ||
| - 🔴 **MUST** — Add or update tests under `tests/` for any new or changed behavior. | ||
| - 🔴 **MUST** — Run `pytest` locally and confirm it passes before opening a PR. | ||
| - 🔴 **MUST** — Sign off every commit per the [Developer Certificate of Origin](DCO.md). | ||
| - 🟡 **SHOULD** — Keep PRs focused on a single logical change; split unrelated changes into separate PRs. | ||
| - 🟡 **SHOULD** — Update relevant docs ([README.md](README.md), [agent.md](agent.md), [brand/Brand.md](brand/Brand.md)) when behavior, commands, or conventions change. | ||
| - 🟡 **SHOULD** — Check `pytest --cov=minichain` to make sure coverage on touched modules doesn't regress. | ||
| - 🔵 **SUGGESTED** — Link the Discord discussion or GitHub Issue in your PR description for context. | ||
| - 🔵 **SUGGESTED** — Prefer small, incremental PRs over large ones when the change can reasonably be split. | ||
|
|
||
| ## How to Contribute | ||
|
|
||
| 1. **Discuss** the change in Discord or a GitHub Issue (see above). | ||
| 2. **Fork** the repository and create a branch off `main`. | ||
| 3. **Install dependencies:** | ||
| ```bash | ||
| pip install -r requirements.txt -r requirements-test.txt | ||
| ``` | ||
| 4. **Make your changes**, following the conventions in [agent.md](agent.md). | ||
| 5. **Test:** | ||
| ```bash | ||
| pytest | ||
| ``` | ||
| 6. **Sign off your commits** per the [DCO](DCO.md) (`git commit -s`). | ||
| 7. **Add yourself** to [Contributors.md](Contributors.md) if you aren't listed yet. | ||
|
Contributor
There was a problem hiding this comment. 🔒 Security & Privacy | 🟠 Major | ⚡ Quick win The contributor workflow promotes public email collection. Make roster participation optional and publish email addresses only with explicit consent.
📍 Affects 2 files
🤖 Prompt for AI Agents |
||
| 8. **Open a pull request** against `main`, describing the problem and the fix, and linking back to the Discord discussion or issue. | ||
|
|
||
| ## Getting Help | ||
|
|
||
| - Ask questions in the [Stability Nexus Discord](https://discord.gg/YzDKeEfWtS). | ||
| - Please do not contact contributors directly — keep discussion in Discord or GitHub Issues so it stays public and searchable. | ||
|
|
||
| All contributions to this project are made under the terms of the [Developer Certificate of Origin](DCO.md). See [Contributors.md](Contributors.md) for the list of people who have contributed. | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,49 @@ | ||
| # Security Policy | ||
|
|
||
| ## Supported Versions | ||
|
|
||
| MiniChain is released via tagged versions (`vX.Y.Z`, [SemVer](https://semver.org)), built and published automatically by [.github/workflows/release.yml](.github/workflows/release.yml) whenever a matching tag is pushed. While the project is pre-1.0 (currently `0.1.0-beta`), only the latest tagged release and `main` receive security fixes — older tags are not backported to. | ||
|
|
||
| | Version | Supported | | ||
| | ---------------- | -------------------- | | ||
| | Latest tagged release | ✅ | | ||
| | `main` (unreleased) | ✅ | | ||
| | Older tagged releases | ❌ | | ||
|
|
||
| ## Reporting a Vulnerability | ||
|
|
||
| **Please do not open a public GitHub Issue for security vulnerabilities.** Publicly disclosing a vulnerability before it's fixed can put users at risk. | ||
|
|
||
| Instead, report it privately using one of these channels: | ||
|
|
||
| 1. **GitHub Private Vulnerability Reporting** (preferred): open a report using the "Security" tab on the [MiniChain repository](https://github.com/StabilityNexus/MiniChain/security/advisories/new). | ||
| 2. **Discord DM:** send a direct message to one of the maintainers listed in [docs/maintainer.md](docs/maintainer.md)— do not post details in a public channel. | ||
|
Comment on lines
+19
to
+20
Contributor
There was a problem hiding this comment. 🔒 Security & Privacy | 🟠 Major | ⚡ Quick win The vulnerability-reporting guidance treats Discord DM as a private security channel. Use a controlled private intake channel instead. Keep Discord limited to non-sensitive coordination.
📍 Affects 2 files
🤖 Prompt for AI Agents |
||
|
|
||
| Please include as much of the following as you can: | ||
|
|
||
| - A description of the vulnerability and its potential impact. | ||
| - Steps to reproduce it (proof-of-concept code, a malicious contract, a crafted P2P message, etc.). | ||
| - The affected file(s)/module(s), if known. | ||
| - Any suggested fix or mitigation. | ||
|
|
||
| ## What to Expect | ||
|
|
||
| - We aim to acknowledge new reports within **14 days**. | ||
| - We'll work with you to understand and validate the issue, and will keep you updated as a fix is developed. | ||
| - Once a fix is released, we'll credit you in the release notes/changelog unless you'd prefer to remain anonymous. | ||
|
|
||
| ## Scope | ||
|
|
||
| Given MiniChain's goals — education, research, and innovation on a minimal blockchain — vulnerabilities of particular interest include: | ||
|
|
||
| - Transaction signature forgery or verification bypass (see `minichain/transaction.py`). | ||
| - Smart contract sandbox escape or gas-metering bypass (see `minichain/contract.py`). | ||
| - Consensus/fork-choice manipulation or state root corruption (see `minichain/chain.py`, `minichain/state.py`, `minichain/pow.py`). | ||
| - P2P protocol issues that allow a peer to crash, partition, or deny service to a node (see `minichain/p2p.py`). | ||
| - JSON-RPC issues that allow unauthorized access to node data or funds (see `minichain/rpc.py`). | ||
|
|
||
| Out of scope: issues in vendor third-party binaries (`bore_bin/`, `bore.zip`) should be reported upstream to their respective projects. | ||
|
|
||
| ## Questions | ||
|
|
||
| For non-security questions, use the [Stability Nexus Discord](https://discord.gg/YzDKeEfWtS) or open a regular GitHub Issue, per [CONTRIBUTING.md](CONTRIBUTING.md). | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,37 @@ | ||
| # AGENTS.md | ||
|
Contributor
There was a problem hiding this comment. 🗄️ Data Integrity & Integration | 🟡 Minor | ⚡ Quick win 🧩 Analysis chain🏁 Script executed: #!/bin/bash
set -euo pipefail
echo "Tracked agent instruction files:"
git ls-files | grep -E '(^|/)(AGENTS|agent)\.md$' || true
echo "Repository references:"
rg -n '(^|/)(AGENTS|agent)\.md' CONTRIBUTING.md docs/BestPracticesChecklist.md agent.mdRepository: StabilityNexus/MiniChain Length of output: 850 🏁 Script executed: #!/bin/bash
set -euo pipefail
echo "Instruction file contents:"
sed -n '1,220p' agent.md
echo
echo "Agent-related discovery and documentation references:"
rg -n -i --hidden --glob '!*.git*' \
'AGENTS\.md|agent\.md|agents? instruction|agent loader|discover' .
echo
echo "Repository root files:"
git ls-files | sed -n '1,120p'Repository: StabilityNexus/MiniChain Length of output: 5170 🌐 Web query:
💡 Result: AGENTS.md is an open, community-driven format used to provide context and instructions to AI coding agents [1][2][3]. Filename Requirements The filename must be exactly AGENTS.md, using uppercase letters [4][5][6]. This requirement is strictly case-sensitive; lowercase variants such as agents.md are generally ignored [5]. Some implementations may support alternative or fallback filenames (such as AGENTS.override.md or project-specific alternatives) depending on the specific tool's configuration [7][6][8], but AGENTS.md is the standard, widely recognized name [1][3]. Discovery and Precedence Discovery rules can vary by implementation, though there are two primary models: 1. Nearest-Ancestor-Only: The agent searches from the current working directory upward until it finds the first AGENTS.md file in the directory tree. It uses only that file and ignores any others found higher up [9][6]. 2. Root-Down Concatenation: The agent walks from the project root down to the current working directory, collecting every AGENTS.md file it encounters along the path. These files are then concatenated (often joined by blank lines) to form the final instruction set. In this model, files closer to the current directory typically override earlier, more global guidance [7][6][10]. Because the original format specification is high-level, developers should verify the specific discovery behavior of their chosen agent tool [10]. The files are standard Markdown and are typically placed in the repository root or the root of subprojects within a monorepo to provide tailored, localized instructions [1][9][5]. Citations:
🏁 Script executed: #!/bin/bash
set -euo pipefail
echo "Test files and module-to-test references:"
rg -n 'minichain/[A-Za-z0-9_]+\.py|tests/test_[A-Za-z0-9_]+\.py|mirror module|1:1' agent.md CONTRIBUTING.md README.md tests minichain
echo
echo "Relevant test file names:"
git ls-files 'tests/*.py' | sortRepository: StabilityNexus/MiniChain Length of output: 16350 Rename Standard agent discovery uses the case-sensitive filename 🤖 Prompt for AI Agents |
||
|
|
||
| ## 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_<feature>.py`). Follow the existing file when extending coverage for a module rather than adding a new ad-hoc test file. | ||
|
Contributor
There was a problem hiding this comment. 📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win Use one test-file naming rule. The text says test names mirror module names 1:1, but the example maps 🤖 Prompt for AI Agents |
||
|
|
||
| ## Architecture Constraints | ||
|
|
||
| - `state.py` owns the Merkle Patricia Trie state root; block validation and contract execution must go through it rather than mutating account balances directly. | ||
| - `p2p.py` implements the fork-choice rule for chain sync — new consensus-affecting logic belongs in `chain.py`/`pow.py`, not duplicated in the networking layer. | ||
| - `rpc.py` exposes read/write JSON-RPC 2.0 methods (`mc_*`) on port 8545; keep new RPC methods consistent with that naming prefix. | ||
|
|
||
| ## Boundaries | ||
|
|
||
| - Never modify `genesis.json` or files under a node's `--datadir` (persisted chain/state data) as part of a code change. | ||
| - `bore_bin/` and `bore.zip` are vendor binaries — do not edit or regenerate them by hand. | ||
| - Don't hand-edit the coverage badge/table in `README.md`; it's generated by CI. | ||
|
|
||
| ## Git Workflow | ||
|
|
||
| - Branch off `main`. | ||
| - Open PRs against `main`; describe the problem and the fix, per [CONTRIBUTING.md](CONTRIBUTING.md). | ||
| - Sign off commits per the [DCO](DCO.md). | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change | ||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| @@ -0,0 +1,63 @@ | ||||||||||||||||
| # MiniChain Brand Guide | ||||||||||||||||
|
|
||||||||||||||||
| MiniChain is a minimal, fully functional blockchain implemented in Python, built by [Stability Nexus](https://stability.nexus/) with three goals: **education**, **research**, and **innovation**. The brand should read the same way the codebase does — clean, minimal, and unpretentious. No visual noise, no unnecessary ornamentation. | ||||||||||||||||
|
|
||||||||||||||||
| ## Logo | ||||||||||||||||
|
|
||||||||||||||||
| MiniChain's mark is a 4D hypercube (tesseract) projected onto 2 dimensions: eight overlapping edge-paths radiating from a central point, each vertex marked with a glowing node. It's meant to evoke a network graph — nodes connected by edges — rather than a literal chain, which fits a project about distributed state rather than links in a chain. | ||||||||||||||||
|
|
||||||||||||||||
| - [`logo.svg`](logo.svg) — the MiniChain mark, 330×330, transparent background. Use this as the primary logo wherever MiniChain is referenced on its own. | ||||||||||||||||
| - [`org-logo.svg`](org-logo.svg) — the Stability Nexus organization mark, 500×500. Use alongside the MiniChain logo when representing the org/project pairing (as in the [README](../README.md) header), never as a substitute for it. | ||||||||||||||||
|
|
||||||||||||||||
| **Usage rules** | ||||||||||||||||
|
|
||||||||||||||||
| - Keep clear space around the logo equal to at least the radius of one vertex node. | ||||||||||||||||
| - Do not recolor the gradient — it is the identifying feature of the mark. | ||||||||||||||||
| - Do not stretch or skew; the projection's proportions are fixed and should scale uniformly. | ||||||||||||||||
| - Minimum display size: 32px, below which the vertex nodes become illegible. | ||||||||||||||||
|
|
||||||||||||||||
| ## Favicons and Icons | ||||||||||||||||
|
|
||||||||||||||||
| - [`favicon.svg`](favicon.svg) — the MiniChain mark, suitable for use as a browser tab icon / site favicon. Reuses the same source as `logo.svg` since the mark is simple enough to stay legible at small sizes without a separate simplified variant. | ||||||||||||||||
| - For platforms that require raster favicons (`.ico`, PNG sizes like 16×16/32×32/180×180 for Apple touch icons), export from `favicon.svg` at build time rather than hand-maintaining bitmap copies. | ||||||||||||||||
|
|
||||||||||||||||
| ## Color Palette | ||||||||||||||||
|
|
||||||||||||||||
| Pulled directly from the logo's gradient and glow layers: | ||||||||||||||||
|
|
||||||||||||||||
| | Swatch | Hex | Role | | ||||||||||||||||
| | ------ | --- | ---- | | ||||||||||||||||
| | 🟩 | `#228B22` | Primary — forest green, gradient start | | ||||||||||||||||
| | 🟢 | `#5A981A` | Primary support — edge glow | | ||||||||||||||||
| | 🟡 | `#C8B209` | Accent — gradient midpoint | | ||||||||||||||||
| | 🟠 | `#FFBF00` | Accent — gradient end | | ||||||||||||||||
| | 🟡 | `#FFC517` | Highlight — gold glow, used as the badge label color in the README | | ||||||||||||||||
| | 🫒 | `#91A511` | Node fill — vertex points | | ||||||||||||||||
|
|
||||||||||||||||
| **Usage rules** | ||||||||||||||||
|
|
||||||||||||||||
| - `#228B22` is the primary brand color — use it for the dominant accent in any MiniChain-branded surface (badges, links, headings). | ||||||||||||||||
| - `#FFC517` / `#FFBF00` are gold accents — use sparingly, for highlights and call-to-action elements, not body text or large fills. | ||||||||||||||||
| - Maintain WCAG AA contrast (4.5:1 for body text) when pairing these colors with text; the greens and golds above are tuned for use on dark or neutral backgrounds, not as text-on-white body copy. | ||||||||||||||||
|
Comment on lines
+39
to
+41
Contributor
There was a problem hiding this comment. 🎯 Functional Correctness | 🟠 Major | ⚡ Quick win Restrict
Proposed clarification-- `#228B22` is the primary brand color — use it for the dominant accent in any MiniChain-branded surface (badges, links, headings).
+- `#228B22` is the primary brand color — use it for accents on approved backgrounds. Do not use it for normal-size text on white.
+- Define approved text/background pairs that meet WCAG AA contrast.📝 Committable suggestion
Suggested change
🤖 Prompt for AI Agents |
||||||||||||||||
|
|
||||||||||||||||
| ## 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 | ||||||||||||||||
| ``` | ||||||||||||||||
|
Comment on lines
+57
to
+63
Contributor
There was a problem hiding this comment. 📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win Specify a language for the fenced code block.
Proposed fix-```
+```text📝 Committable suggestion
Suggested change
🧰 Tools🪛 markdownlint-cli2 (0.23.2)[warning] 57-57: Fenced code blocks should have a language specified (MD040, fenced-code-language) 🤖 Prompt for AI AgentsSource: Linters/SAST tools |
||||||||||||||||
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Oops, something went wrong.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Uh oh!
There was an error while loading. Please reload this page.