Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
29 changes: 29 additions & 0 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,29 @@
name: CI

on:
push:
branches: [main]
pull_request:

jobs:
test:
runs-on: ubuntu-latest
Comment on lines +8 to +10
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🧹 Nitpick | 🔵 Trivial

🧩 Analysis chain

🏁 Script executed:

# Find and display the CI workflow file
fd -e yml -g 'ci.yml' --exec cat -n {}

Repository: StabilityNexus/MiniChain

Length of output: 50


🏁 Script executed:

# Find and display pyproject.toml if it exists
fd -e toml -g 'pyproject.toml' --exec cat -n {}

Repository: StabilityNexus/MiniChain

Length of output: 1044


🏁 Script executed:

# List files in .github/workflows directory
ls -la .github/workflows/ 2>/dev/null || echo "Directory not found"

Repository: StabilityNexus/MiniChain

Length of output: 231


🏁 Script executed:

# Find all yml/yaml files in .github directory
fd -e yml -o -e yaml . .github/ 2>/dev/null | head -20

Repository: StabilityNexus/MiniChain

Length of output: 50


🏁 Script executed:

# Search for CI configuration files more broadly
find .github -type f \( -name "*.yml" -o -name "*.yaml" \) 2>/dev/null

Repository: StabilityNexus/MiniChain

Length of output: 92


🏁 Script executed:

cat -n .github/workflows/ci.yml

Repository: StabilityNexus/MiniChain

Length of output: 782


Add Python version matrix to test against supported versions.

The CI currently tests only against Python 3.11, but pyproject.toml declares requires-python = ">=3.11". Testing against multiple supported versions catches compatibility regressions early:

♻️ Proposed refactor
 jobs:
   test:
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12"]
     runs-on: ubuntu-latest
     steps:
       ...
       - name: Setup Python
         uses: actions/setup-python@v5
         with:
-          python-version: "3.11"
+          python-version: ${{ matrix.python-version }}
+          cache: "pip"
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.

In @.github/workflows/ci.yml around lines 8 - 10, The CI job named "test"
currently runs only on a single runner; add a strategy matrix to the "test" job
to run across supported Python versions (e.g., matrix.python-version:
["3.11","3.12"]) and update the test steps to use actions/setup-python with
python-version: ${{ matrix.python-version }} so the "test" job executes for each
Python version declared in the matrix.

steps:
- name: Checkout
uses: actions/checkout@v4

- name: Setup Python
uses: actions/setup-python@v5
with:
python-version: "3.11"
Comment on lines +15 to +18
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🧹 Nitpick | 🔵 Trivial

Add pip dependency caching to speed up CI.

setup-python@v5 natively supports pip caching via a single cache key; without it every run re-downloads and reinstalls all packages from scratch.

⚡ Proposed fix
       - name: Setup Python
         uses: actions/setup-python@v5
         with:
           python-version: "3.11"
+          cache: "pip"
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
- name: Setup Python
uses: actions/setup-python@v5
with:
python-version: "3.11"
- name: Setup Python
uses: actions/setup-python@v5
with:
python-version: "3.11"
cache: "pip"
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.

In @.github/workflows/ci.yml around lines 15 - 18, The Setup Python step using
actions/setup-python@v5 is missing pip dependency caching; add the cache key
(cache: "pip") to the step that invokes actions/setup-python@v5 (the block
containing python-version: "3.11") so GitHub Actions will cache and restore pip
wheels between runs and speed up CI.


- name: Install dependencies
run: |
python -m pip install --upgrade pip
python -m pip install -e .[dev]
- name: Lint
run: make lint

- name: Run tests
run: make test
14 changes: 14 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -258,6 +258,17 @@ pythontex-files-*/
# easy-todo
*.lod

# MiniChain local planning docs (do not commit)
issues.md
architectureProposal.md

# Python caches and virtualenvs
__pycache__/
*.py[cod]
.pytest_cache/
.ruff_cache/
.venv/
Comment on lines +265 to +270
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

venv/ and env/ virtualenv directories are not covered.

Line 270 covers .venv/ only. Developers using python -m venv venv or python -m venv env (both extremely common naming conventions) will find those directories unignored. Consider adding:

🔧 Proposed fix
 # Python caches and virtualenvs
 __pycache__/
 *.py[cod]
 .pytest_cache/
 .ruff_cache/
 .venv/
+venv/
+env/
+dist/
+*.egg-info/
+.coverage
+htmlcov/
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
# Python caches and virtualenvs
__pycache__/
*.py[cod]
.pytest_cache/
.ruff_cache/
.venv/
# Python caches and virtualenvs
__pycache__/
*.py[cod]
.pytest_cache/
.ruff_cache/
.venv/
venv/
env/
dist/
*.egg-info/
.coverage
htmlcov/
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.

In @.gitignore around lines 265 - 270, The .gitignore currently ignores ".venv/"
but not other common virtualenv directories; update the .gitignore to also
ignore "venv/" and "env/" so developers who create virtual environments with
python -m venv venv or python -m venv env don't accidentally commit them—add
entries for venv/ and env/ alongside the existing .venv/ rule to cover all three
common virtualenv directories.


# xcolor
*.xcp

Expand Down Expand Up @@ -324,3 +335,6 @@ TSWLatexianTemp*
# option is specified. Footnotes are the stored in a file with suffix Notes.bib.
# Uncomment the next line to have this generated file ignored.
#*Notes.bib


docs/
Comment on lines +338 to +340
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

docs/ exclusion silently prevents committing any future documentation.

This blanket pattern will block generated or authored docs from ever being tracked without an explicit git add -f or negation rule. If generated API docs (e.g., Sphinx _build/) are the actual target, prefer a more targeted pattern:

🔧 More targeted alternative
-docs/
+docs/_build/
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
docs/
docs/_build/
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.

In @.gitignore around lines 338 - 340, The current ignore pattern "docs/" will
silently prevent committing any documentation; update the pattern to be more
targeted (for example ignore specific generated output like "docs/_build/" or
"/docs/_build/" or add negation rules such as "!docs/*.md" or "!/docs/**" to
allow authored docs) so authored docs can be tracked; locate the "docs/" entry
in the .gitignore and replace or refine it with the targeted pattern(s) that
match only generated artefacts or add negation rules to permit committed
documentation.

21 changes: 21 additions & 0 deletions Makefile
Original file line number Diff line number Diff line change
@@ -0,0 +1,21 @@
PYTHON ?= python3

.PHONY: install dev-install test lint format start-node

install:
$(PYTHON) -m pip install .

dev-install:
$(PYTHON) -m pip install -e .[dev]

test:
$(PYTHON) -m pytest

lint:
$(PYTHON) -m ruff check src tests

format:
$(PYTHON) -m ruff format src tests

start-node:
PYTHONPATH=src $(PYTHON) -m minichain --host 127.0.0.1 --port 7000
265 changes: 50 additions & 215 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,236 +1,71 @@
<!-- Don't delete it -->
<div name="readme-top"></div>
# MiniChain

<!-- Organization Logo -->
<div align="center" style="display: flex; align-items: center; justify-content: center; gap: 16px;">
<img alt="Stability Nexus" src="public/stability.svg" width="175">
<img src="public/todo-project-logo.svg" width="175" />
</div>
MiniChain is a minimal, research-oriented blockchain implementation in Python. This repository currently contains the project scaffolding and development environment for the v0 core chain roadmap.

&nbsp;
## Current Status

<!-- Organization Name -->
<div align="center">
Issue #1 (project scaffolding) is implemented with:

[![Static Badge](https://img.shields.io/badge/Stability_Nexus-/TODO-228B22?style=for-the-badge&labelColor=FFC517)](https://TODO.stability.nexus/)
- Python package layout under `src/minichain`
- Placeholder component modules for:
- `crypto`, `transaction`, `block`, `state`, `mempool`, `consensus`, `network`, `storage`, `node`
- `pyproject.toml` project configuration
- `Makefile` for common developer tasks
- Basic CI workflow (`.github/workflows/ci.yml`)
- Baseline tests under `tests/`
Comment on lines +5 to +15
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

"Current Status" section only reflects Issue #1 scaffolding.

This PR adds cryptographic utilities, deterministic serialization, and transaction validation (Issue #8), but the status section doesn't mention these additions. The section will mislead new contributors about what is actually implemented.

🧰 Tools
🪛 LanguageTool

[uncategorized] ~14-~14: The official name of this software platform is spelled with a capital “H”.
Context: ...on developer tasks - Basic CI workflow (.github/workflows/ci.yml) - Baseline tests und...

(GITHUB)

🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.

In `@README.md` around lines 5 - 15, Update the "Current Status" section to
reflect the new features added by this PR: explicitly mention Issue `#8` and list
the implemented components — cryptographic utilities, deterministic
serialization, and transaction validation — and note any new or updated modules
(e.g., the crypto utilities and transaction validation code under
src/minichain). Keep the same terse bullet style as existing items and ensure
the text clearly indicates these additions are implemented so new contributors
aren't misled.


<!-- Correct deployed url to be added -->
## Requirements

</div>
- Python 3.11+

<!-- Organization/Project Social Handles -->
<p align="center">
<!-- Telegram -->
<a href="https://t.me/StabilityNexus">
<img src="https://img.shields.io/badge/Telegram-black?style=flat&logo=telegram&logoColor=white&logoSize=auto&color=24A1DE" alt="Telegram Badge"/></a>
&nbsp;&nbsp;
<!-- X (formerly Twitter) -->
<a href="https://x.com/StabilityNexus">
<img src="https://img.shields.io/twitter/follow/StabilityNexus" alt="X (formerly Twitter) Badge"/></a>
&nbsp;&nbsp;
<!-- Discord -->
<a href="https://discord.gg/YzDKeEfWtS">
<img src="https://img.shields.io/discord/995968619034984528?style=flat&logo=discord&logoColor=white&logoSize=auto&label=Discord&labelColor=5865F2&color=57F287" alt="Discord Badge"/></a>
&nbsp;&nbsp;
<!-- Medium -->
<a href="https://news.stability.nexus/">
<img src="https://img.shields.io/badge/Medium-black?style=flat&logo=medium&logoColor=black&logoSize=auto&color=white" alt="Medium Badge"></a>
&nbsp;&nbsp;
<!-- LinkedIn -->
<a href="https://linkedin.com/company/stability-nexus">
<img src="https://img.shields.io/badge/LinkedIn-black?style=flat&logo=LinkedIn&logoColor=white&logoSize=auto&color=0A66C2" alt="LinkedIn Badge"></a>
&nbsp;&nbsp;
<!-- Youtube -->
<a href="https://www.youtube.com/@StabilityNexus">
<img src="https://img.shields.io/youtube/channel/subscribers/UCZOG4YhFQdlGaLugr_e5BKw?style=flat&logo=youtube&logoColor=white&logoSize=auto&labelColor=FF0000&color=FF0000" alt="Youtube Badge"></a>
</p>

---

<div align="center">
<h1>MiniChain</h1>
</div>

MiniChain is a minimal fully functional blockchain implemented in Python.

### Background and Motivation

* Most well-known blockchains are now several years old and have accumulated a lot of technical debt.
Simply forking their codebases is not an optimal option for starting a new chain.

* MiniChain will be focused on research. Its primary purpose is not to be yet another blockchain
trying to be the one blockchain to kill them all, but rather to serve as a clean codebase that can be a benchmark for research of
variations of the technology. (We hope that MiniChain will be as valuable for blockchain research as, for instance,
MiniSat was valuable for satisfiability and automated reasoning research. MiniSat had less than 600 lines of C++ code.)

* MiniChain will be focused on education. By having a clean and small codebase, devs will be able to understand
blockchains by looking at the codebase.

* The blockchain space is again going through a phase where many new blockchains are being launched.
Back in 2017 and 2018, such an expansion period led to many general frameworks for blockchains,
such as Scorex and various Hyperledger frameworks. But most of these frameworks suffered from speculative generality and
were bloated. They focused on extensibility and configurability. MiniChain has a different philosophy:
focus on minimality and, therefore, ease of modification.

* Recent advances in networking and crypto libraries for Python make it possible to develop MiniChain in Python.
Given that Python is one of the easiest languages to learn and results in usually boilerplate-minimized and easy to read code,
implementing MiniChain in Python aligns with MiniChain's educational goal.


### Overview of Tasks

* Develop a fully functional minimal blockchain in Python, with all the expected components:
peer-to-peer networking, consensus, mempool, ledger, ...

* Bonus task: add smart contracts to the blockchain.

Candidates are expected to refine these tasks in their GSoC proposals.
It is encouraged that you develop an initial prototype during the application phase.

### Requirements

* Use [PyNaCl](https://pynacl.readthedocs.io/en/latest/) library for hashing, signing transactions and verifying signatures.
* Use [Py-libp2p](https://github.com/libp2p/py-libp2p/tree/main) for p2p networking.
* Implement Proof-of-Work as the consensus protocol.
* Use accounts (instead of UTxO) as the accounting model for the ledger.
* Use as few lines of code as possible without compromising readability and understandability.
* For the bonus task, make Python itself be the language used for smart contracts, but watch out for security concerns related to executing arbitrary code from untrusted sources.

### Resources

* Read this book: https://www.marabu.dev/blockchain-foundations.pdf


---

## Project Maturity

TODO: In the checklist below, mark the items that have been completed and delete items that are not applicable to the current project:

* [ ] The project has a logo.
* [ ] The project has a favicon.
* [ ] The protocol:
- [ ] has been described and formally specified in a paper.
- [ ] has had its main properties mathematically proven.
- [ ] has been formally verified.
* [ ] The smart contracts:
- [ ] were thoroughly reviewed by at least two knights of The Stable Order.
- [ ] were deployed to:
- [ ] Ergo
- [ ] Cardano
- [ ] EVM Chains:
- [ ] Ethereum Classic
- [ ] Ethereum
- [ ] Polygon
- [ ] BSC
- [ ] Base
* [ ] The mobile app:
- [ ] has an _About_ page containing the Stability Nexus's logo and pointing to the social media accounts of the Stability Nexus.
- [ ] is available for download as a release in this repo.
- [ ] is available in the relevant app stores.
* [ ] The web frontend:
- [ ] has proper title and metadata.
- [ ] has proper open graph metadata, to ensure that it is shown well when shared in social media (Discord, Telegram, Twitter, LinkedIn).
- [ ] has a footer, containing the Stability Nexus's logo and pointing to the social media accounts of the Stability Nexus.
- [ ] is fully static and client-side.
- [ ] is deployed to Github Pages via a Github Workflow.
- [ ] is accessible through the https://TODO:PROJECT-NAME.stability.nexus domain.
* [ ] the project is listed in [https://stability.nexus/protocols](https://stability.nexus/protocols).

---

## Tech Stack

TODO:

### Frontend

TODO:

- Next.js 14+ (React)
- TypeScript
- TailwindCSS
- shadcn/ui

### Blockchain

TODO:

- Wagmi
- Solidity Smart Contracts
- Ethers.js

---

## Getting Started

### Prerequisites

TODO

- Node.js 18+
- npm/yarn/pnpm
- MetaMask or any other web3 wallet browser extension

### Installation

TODO

#### 1. Clone the Repository
## Setup

```bash
git clone https://github.com/StabilityNexus/TODO.git
cd TODO
python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
make dev-install
```

#### 2. Install Dependencies

Using your preferred package manager:
If you also want networking dependencies:

```bash
npm install
# or
yarn install
# or
pnpm install
python -m pip install -e .[network]
```

#### 3. Run the Development Server

Start the app locally:
## Common Commands

```bash
npm run dev
# or
yarn dev
# or
pnpm dev
make test # run unit tests
make lint # run ruff checks
make format # format with ruff
make start-node # run scaffold node entrypoint
```

#### 4. Open your Browser

Navigate to [http://localhost:3000](http://localhost:3000) to see the application.

---

## Contributing

We welcome contributions of all kinds! To contribute:

1. Fork the repository and create your feature branch (`git checkout -b feature/AmazingFeature`).
2. Commit your changes (`git commit -m 'Add some AmazingFeature'`).
3. Run the development workflow commands to ensure code quality:
- `npm run format:write`
- `npm run lint:fix`
- `npm run typecheck`
4. Push your branch (`git push origin feature/AmazingFeature`).
5. Open a Pull Request for review.
## Run the Node Entrypoint

If you encounter bugs, need help, or have feature requests:

- Please open an issue in this repository providing detailed information.
- Describe the problem clearly and include any relevant logs or screenshots.

We appreciate your feedback and contributions!
```bash
PYTHONPATH=src python -m minichain --host 127.0.0.1 --port 7000
```

© 2025 The Stable Order.
## Repository Layout

```text
.github/workflows/ci.yml
src/minichain/
__init__.py
__main__.py
crypto.py
transaction.py
block.py
state.py
mempool.py
consensus.py
network.py
storage.py
node.py
tests/
test_scaffold.py
issues.md
architectureProposal.md
Comment on lines +53 to +70
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

serialization.py is missing from the repository layout.

src/minichain/serialization.py is a real module referenced in both COMPONENT_MODULES (tests/test_scaffold.py) and tests/test_serialization.py, but it is absent from the layout listing.

📝 Proposed fix
 src/minichain/
   __init__.py
   __main__.py
   crypto.py
+  serialization.py
   transaction.py
   block.py
   state.py
   mempool.py
   consensus.py
   network.py
   storage.py
   node.py
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.

In `@README.md` around lines 53 - 70, The README layout omits the real module
src/minichain/serialization.py which tests reference; add a new module file
named serialization.py under src/minichain implementing the serialization
functionality expected by tests (ensure it exports the functions/classes
referenced by COMPONENT_MODULES and tests/test_serialization.py), and update the
README listing to include "serialization.py" in the src/minichain/ file list so
the repository layout matches the actual modules used by tests.

```
Loading