Coverage Report

File	Stmts	Miss	Cover	Missing
minichain
block.py	88	14	84%	11, 15, 18–24, 73, 160, 165, 174, 176
chain.py	167	33	80%	16, 21, 27, 31, 34, 38, 62–67, 74–75, 105–108, 141, 154–157, 167–168, 177–178, 181–182, 186–187, 224, 236–237
contract.py	126	73	42%	11–12, 15–20, 36–80, 115, 123, 175–178, 186–201, 209–210, 212–213, 218–219, 221–222, 224–225, 227–228
mempool.py	59	14	76%	15–16, 30–32, 37–38, 40–41, 47, 50–51, 58–60
mpt.py	14	3	79%	18–20
p2p.py	267	196	27%	27–28, 76, 79, 82, 85, 88–95, 98–99, 102–103, 108, 123, 126, 129–131, 134–136, 139, 142, 145, 149–150, 160–162, 173–187, 194–200, 209–263, 268–378
persistence.py	171	39	77%	84, 90, 92, 133, 143–144, 223–224, 244, 247–248, 270, 282–293, 296–297, 303–307, 310–313, 316–320
pow.py	39	14	64%	26, 34, 44–46, 50–52, 62, 67–71
rpc.py	79	23	71%	41–42, 45, 61, 64, 68, 73–76, 78–88, 93–95
state.py	135	24	82%	29, 48–49, 93, 105, 189–204, 225–228, 231–236
validators.py	9	1	89%	13
TOTAL	1244	434	65%

---

MiniChain

MiniChain is a minimal fully functional blockchain implemented in Python, with 3 goals:

• Education: By having a clean codebase with self-explanatory code, MiniChain allows devs to learn and deeply understand blockchains. MiniChain is implemented in Python, which is one of the most popular and easy-to-learn programming languages. MiniChain's smart contracts can be written in Python as well. Furthermore, recent advances in Python's networking and cryptography libraries allow MiniChain to fulfill its educational goal while maintaining performance and security.

• Research: By having a small codebase, MiniChain is easy to modify by researchers who are interested in exploring variations of blockchain technologies (e.g. consensus protocols, smart contract approaches, scalibility solutions, ...) and in having a benchamark against which these variations can be tested. We hope that MiniChain will be as valuable for blockchain research as, for instance, MiniSat (with its less than 600 lines of C++ code) was valuable for satisfiability and automated reasoning research.

• Innovation: MiniChain is a minimal technical-debt-free codebase that can be forked to create new custom blockchains. The blockchain space is again going through a phase where many new blockchains are being launched. Similar expansion periods in the past led either to forks of codebases that carried technical debt or to development and use of various general blockchain frameworks that suffered from speculative generality. They focused on extensibility and configurability. MiniChain has a different philosophy: it focuses on minimality and, therefore, ease of modification.

---

Getting Started

Prerequisites

• Python 3.10+
• Install dependencies:

  pip install -r requirements.txt

1. Creating a New MiniChain

To bootstrap a brand new blockchain network from scratch, simply start a node. By default, this creates a new Genesis block.

python main.py --port 9000 --datadir ./node1_data

Note: Keep this terminal open to interact with the node via the CLI.

2. Connecting to an Existing Chain

To connect a secondary node to the network, start a new instance on a different port and point it to the seed node using the --connect flag.

python main.py --port 9001 --connect 127.0.0.1:9000 --datadir ./node2_data

The node will automatically sync the blockchain state via the P2P network using the Fork-Choice rule.

3. Mining Blocks

To confirm pending transactions, you need to mine blocks. In the interactive CLI of your node, simply type:

minichain> mine

This runs the Proof-of-Work algorithm, validates transactions, computes the new state root, updates your wallet with the block reward + fees, and broadcasts the block to all connected peers.

---

Basic Operations (Interactive CLI)

Once your node is running, you can perform basic blockchain operations directly in your terminal.

Making a Transfer Send coins to another public key:

minichain> send <receiver_address> <amount> <fee>

Example: send 8b3401abedb875aff7279b5ab58cb9a0c... 100 1

Checking Balances View the state of all active accounts and contracts on the chain:

minichain> balance

Viewing Network State

minichain> chain   # View all blocks
minichain> peers   # View connected P2P nodes
minichain> address # View your own public key

---

Smart Contracts

MiniChain supports fully-functional smart contracts written directly in Python! The execution engine uses sys.settrace for precise Gas Metering (charging 1 gas per executed opcode) and multiprocessing for Sandboxed Execution to ensure network security.

Writing a Contract

Smart contracts in MiniChain have access to a persistent storage dictionary and a msg dictionary containing transaction context (sender, value, data).

Check out the /examples directory for tutorials:

• examples/counter.py - A basic state mutation example.
• examples/stablecoin.py - A minimal ERC-20 style fungible token.
• examples/dex.py - An Automated Market Maker (AMM) using the constant product formula (x * y = k).

Interacting via CLI

Start the interactive node using python main.py and use the following commands:

1. Deploy: deploy <filepath> [amount] [fee]
2. Call: call <contract_address> <payload> [amount] [fee]

Example deployment:

minichain> deploy examples/counter.py 0 100

---

JSON-RPC 2.0 Server

MiniChain automatically spins up a JSON-RPC 2.0 server alongside the P2P node. By default, it binds to port 8545 (the standard EVM RPC port). External wallets and dApps can use this to interact with the chain asynchronously.

Example Request (Get Block Number):

curl -X POST http://127.0.0.1:8545/ \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc": "2.0", "method": "mc_blockNumber", "id": 1}'

Available endpoints include: mc_blockNumber, mc_getBlockByNumber, mc_getBalance, and mc_sendTransaction.

---

Contributing

We welcome contributions of all kinds!

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!

Resources

• If you would like to learn blockchain technologies, we recommend reading this book (https://www.marabu.dev/blockchain-foundations.pdf) in addition to inspecting MiniChain's codebase.

---

© 2025 The Stable Order.