Merge pull request #136 from StabilityNexus/docs/contributing-maintainers-agents

Docs/contributing maintainers agents

Author: Zahnentferner

CONTRIBUTING.md

@@ -0,0 +1,50 @@
+# Contributing to MiniChain
+
+Thanks for your interest in contributing to MiniChain! This document explains how to get involved, from discussing an idea to getting a pull request merged.
+
+## Before You Start: Discuss It First
+
+**Every contribution — bug fix, feature, or refactor — should be discussed before you start writing code.** This avoids duplicate work and makes sure the change fits the project's minimality-first philosophy.
+
+1. Join the [Stability Nexus Discord server](https://discord.gg/YzDKeEfWtS).
+2. Discuss your issue, bug, or feature idea in the project's channel/thread: [MiniChain discussion](https://discord.com/channels/995968619034984528/1471163521877410045).
+3. If it's a confirmed bug or an agreed-upon feature, open a matching GitHub Issue in this repository describing the problem and the proposed approach.
+
+Only after that discussion should you start implementation — this is the first and most important rule below.
+
+## Contribution Checklist
+
+- 🔴 **MUST** — Discuss non-trivial changes in Discord (see above) or in a GitHub Issue before opening a PR.
+- 🔴 **MUST** — Follow the module layout and architecture constraints described in [agent.md](agent.md) (one concern per module under `minichain/`, state changes go through `state.py`, etc.).
+- 🔴 **MUST** — Add or update tests under `tests/` for any new or changed behavior.
+- 🔴 **MUST** — Run `pytest` locally and confirm it passes before opening a PR.
+- 🔴 **MUST** — Sign off every commit per the [Developer Certificate of Origin](DCO.md).
+- 🟡 **SHOULD** — Keep PRs focused on a single logical change; split unrelated changes into separate PRs.
+- 🟡 **SHOULD** — Update relevant docs ([README.md](README.md), [agent.md](agent.md), [brand/Brand.md](brand/Brand.md)) when behavior, commands, or conventions change.
+- 🟡 **SHOULD** — Check `pytest --cov=minichain` to make sure coverage on touched modules doesn't regress.
+- 🔵 **SUGGESTED** — Link the Discord discussion or GitHub Issue in your PR description for context.
+- 🔵 **SUGGESTED** — Prefer small, incremental PRs over large ones when the change can reasonably be split.
+
+## How to Contribute
+
+1. **Discuss** the change in Discord or a GitHub Issue (see above).
+2. **Fork** the repository and create a branch off `main`.
+3. **Install dependencies:**
+   ```bash
+   pip install -r requirements.txt -r requirements-test.txt
+   ```
+4. **Make your changes**, following the conventions in [agent.md](agent.md).
+5. **Test:**
+   ```bash
+   pytest
+   ```
+6. **Sign off your commits** per the [DCO](DCO.md) (`git commit -s`).
+7. **Add yourself** to [Contributors.md](Contributors.md) if you aren't listed yet.
+8. **Open a pull request** against `main`, describing the problem and the fix, and linking back to the Discord discussion or issue.
+
+## Getting Help
+
+- Ask questions in the [Stability Nexus Discord](https://discord.gg/YzDKeEfWtS).
+- Please do not contact contributors directly — keep discussion in Discord or GitHub Issues so it stays public and searchable.
+
+All contributions to this project are made under the terms of the [Developer Certificate of Origin](DCO.md). See [Contributors.md](Contributors.md) for the list of people who have contributed.

Contributors.md

@@ -1,8 +1,8 @@
 This file contains information about people who contribute to this project.
 
 Please do not contact these people directly. 
-Instead, join our [Discord](https://discord.gg/fuuWX4AbJt) and communicate about 
-this project in the [TODO channel](TODO).
+Instead, join our [Discord](https://discord.gg/YzDKeEfWtS) and communicate about 
+this project in the [MiniChain channel](https://discord.com/channels/995968619034984528/1471163521877410045).
 
 ## Contributors
 
@@ -12,4 +12,4 @@ are made under the terms of the [Developer Certificate of Origin](DCO.md).
 | Name                             | Github Username    | Discord Username   | Email Address                |     
 | -------------------------------- | ------------------ | ------------------ | ---------------------------- |
 | Bruno Woltzenlogel Paleo         | @Zahnentferner     | @b.wp              | zahnentferner@gmail.com      |
-| TODO                             | TODO               | TODO               | TODO                         |
+| Siddhant                         | @siddhant          | @siddhantcookie     | siddhantkk27@gmail.com       |

SECURITY.md

@@ -0,0 +1,49 @@
+# Security Policy
+
+## Supported Versions
+
+MiniChain is released via tagged versions (`vX.Y.Z`, [SemVer](https://semver.org)), built and published automatically by [.github/workflows/release.yml](.github/workflows/release.yml) whenever a matching tag is pushed. While the project is pre-1.0 (currently `0.1.0-beta`), only the latest tagged release and `main` receive security fixes — older tags are not backported to.
+
+| Version         | Supported          |
+| ---------------- | -------------------- |
+| Latest tagged release | ✅ |
+| `main` (unreleased) | ✅ |
+| Older tagged releases | ❌ |
+
+## Reporting a Vulnerability
+
+**Please do not open a public GitHub Issue for security vulnerabilities.** Publicly disclosing a vulnerability before it's fixed can put users at risk.
+
+Instead, report it privately using one of these channels:
+
+1. **GitHub Private Vulnerability Reporting** (preferred): open a report using the "Security" tab on the [MiniChain repository](https://github.com/StabilityNexus/MiniChain/security/advisories/new).
+2. **Discord DM:** send a direct message to one of the maintainers listed in [docs/maintainer.md](docs/maintainer.md)— do not post details in a public channel.
+
+Please include as much of the following as you can:
+
+- A description of the vulnerability and its potential impact.
+- Steps to reproduce it (proof-of-concept code, a malicious contract, a crafted P2P message, etc.).
+- The affected file(s)/module(s), if known.
+- Any suggested fix or mitigation.
+
+## What to Expect
+
+- We aim to acknowledge new reports within **14 days**.
+- We'll work with you to understand and validate the issue, and will keep you updated as a fix is developed.
+- Once a fix is released, we'll credit you in the release notes/changelog unless you'd prefer to remain anonymous.
+
+## Scope
+
+Given MiniChain's goals — education, research, and innovation on a minimal blockchain — vulnerabilities of particular interest include:
+
+- Transaction signature forgery or verification bypass (see `minichain/transaction.py`).
+- Smart contract sandbox escape or gas-metering bypass (see `minichain/contract.py`).
+- Consensus/fork-choice manipulation or state root corruption (see `minichain/chain.py`, `minichain/state.py`, `minichain/pow.py`).
+- P2P protocol issues that allow a peer to crash, partition, or deny service to a node (see `minichain/p2p.py`).
+- JSON-RPC issues that allow unauthorized access to node data or funds (see `minichain/rpc.py`).
+
+Out of scope: issues in vendor third-party binaries (`bore_bin/`, `bore.zip`) should be reported upstream to their respective projects.
+
+## Questions
+
+For non-security questions, use the [Stability Nexus Discord](https://discord.gg/YzDKeEfWtS) or open a regular GitHub Issue, per [CONTRIBUTING.md](CONTRIBUTING.md).

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_<feature>.py`). Follow the existing file when extending coverage for a module rather than adding a new ad-hoc test file.
+
+## Architecture Constraints
+
+- `state.py` owns the Merkle Patricia Trie state root; block validation and contract execution must go through it rather than mutating account balances directly.
+- `p2p.py` implements the fork-choice rule for chain sync — new consensus-affecting logic belongs in `chain.py`/`pow.py`, not duplicated in the networking layer.
+- `rpc.py` exposes read/write JSON-RPC 2.0 methods (`mc_*`) on port 8545; keep new RPC methods consistent with that naming prefix.
+
+## Boundaries
+
+- Never modify `genesis.json` or files under a node's `--datadir` (persisted chain/state data) as part of a code change.
+- `bore_bin/` and `bore.zip` are vendor binaries — do not edit or regenerate them by hand.
+- Don't hand-edit the coverage badge/table in `README.md`; it's generated by CI.
+
+## Git Workflow
+
+- Branch off `main`.
+- Open PRs against `main`; describe the problem and the fix, per [CONTRIBUTING.md](CONTRIBUTING.md).
+- Sign off commits per the [DCO](DCO.md).

brand/Brand.md

@@ -0,0 +1,63 @@
+# MiniChain Brand Guide
+
+MiniChain is a minimal, fully functional blockchain implemented in Python, built by [Stability Nexus](https://stability.nexus/) with three goals: **education**, **research**, and **innovation**. The brand should read the same way the codebase does — clean, minimal, and unpretentious. No visual noise, no unnecessary ornamentation.
+
+## Logo
+
+MiniChain's mark is a 4D hypercube (tesseract) projected onto 2 dimensions: eight overlapping edge-paths radiating from a central point, each vertex marked with a glowing node. It's meant to evoke a network graph — nodes connected by edges — rather than a literal chain, which fits a project about distributed state rather than links in a chain.
+
+- [`logo.svg`](logo.svg) — the MiniChain mark, 330×330, transparent background. Use this as the primary logo wherever MiniChain is referenced on its own.
+- [`org-logo.svg`](org-logo.svg) — the Stability Nexus organization mark, 500×500. Use alongside the MiniChain logo when representing the org/project pairing (as in the [README](../README.md) header), never as a substitute for it.
+
+**Usage rules**
+
+- Keep clear space around the logo equal to at least the radius of one vertex node.
+- Do not recolor the gradient — it is the identifying feature of the mark.
+- Do not stretch or skew; the projection's proportions are fixed and should scale uniformly.
+- Minimum display size: 32px, below which the vertex nodes become illegible.
+
+## Favicons and Icons
+
+- [`favicon.svg`](favicon.svg) — the MiniChain mark, suitable for use as a browser tab icon / site favicon. Reuses the same source as `logo.svg` since the mark is simple enough to stay legible at small sizes without a separate simplified variant.
+- For platforms that require raster favicons (`.ico`, PNG sizes like 16×16/32×32/180×180 for Apple touch icons), export from `favicon.svg` at build time rather than hand-maintaining bitmap copies.
+
+## Color Palette
+
+Pulled directly from the logo's gradient and glow layers:
+
+| Swatch | Hex | Role |
+| ------ | --- | ---- |
+| 🟩 | `#228B22` | Primary — forest green, gradient start |
+| 🟢 | `#5A981A` | Primary support — edge glow |
+| 🟡 | `#C8B209` | Accent — gradient midpoint |
+| 🟠 | `#FFBF00` | Accent — gradient end |
+| 🟡 | `#FFC517` | Highlight — gold glow, used as the badge label color in the README |
+| 🫒 | `#91A511` | Node fill — vertex points |
+
+**Usage rules**
+
+- `#228B22` is the primary brand color — use it for the dominant accent in any MiniChain-branded surface (badges, links, headings).
+- `#FFC517` / `#FFBF00` are gold accents — use sparingly, for highlights and call-to-action elements, not body text or large fills.
+- Maintain WCAG AA contrast (4.5:1 for body text) when pairing these colors with text; the greens and golds above are tuned for use on dark or neutral backgrounds, not as text-on-white body copy.
+
+## Typography
+
+MiniChain doesn't currently ship custom web fonts — GitHub-rendered Markdown (README, docs) uses GitHub's default system font stack. For any future site, dashboard, or block explorer built for the project, the recommended pairing is:
+
+- **Headings / UI:** [Space Grotesk](https://fonts.google.com/specimen/Space+Grotesk) — a geometric sans with a slightly technical feel that matches the wireframe logo, without being a generic startup sans.
+- **Body text:** [Inter](https://fonts.google.com/specimen/Inter) — high legibility at small sizes, wide language support.
+- **Code / addresses / hashes:** [JetBrains Mono](https://www.jetbrains.com/lp/mono/) — monospace, disambiguates `0`/`O` and `1`/`l`/`I`, which matters for public keys, transaction hashes, and CLI output.
+
+Fall back to the system font stack (`-apple-system, Segoe UI, Roboto, sans-serif`) if none of the above are loaded, rather than a generic web-safe serif.
+
+## File Location
+
+All brand assets and this guide live in the [`brand/`](.) folder at the repository root:
+
+```
+brand/
+├── Brand.md       # this file
+├── logo.svg        # primary MiniChain mark
+├── org-logo.svg     # Stability Nexus organization mark
+└── favicon.svg      # favicon-ready MiniChain mark
+```