feat: py-libp2p-style peer discovery networking service

[arunabha003]

Addressed Issues:

Part of #8
Depends on #37

Summary

• Implement async P2P node networking with TCP handshake and peer tracking
• Add bootstrap peer connection flow on startup
• Add peer exchange message handling for transitive discovery
• Add mDNS-style multicast discovery loop for local peer discovery
• Add restricted-environment fallback discovery path to keep behavior deterministic in tests
• Add integration tests for bootstrap discovery and mDNS discovery between two live nodes

Validation

• python -m ruff check src tests
• python -m pytest

Checklist

• [ x] My PR addresses a single issue, fixes a single bug or makes a single improvement.
• [ x] My code follows the project's code style and conventions.
• [x ] If applicable, I have made corresponding changes or additions to the documentation.
• [ x] If applicable, I have made corresponding changes or additions to tests.
• [ x] My changes generate no new warnings or errors.
• [ x] I have joined the Stability Nexus's Discord server and I will share a link to this PR with the project maintainers there.
• [x ] I have read the Contribution Guidelines.
• [ x] Once I submit my PR, CodeRabbit AI will automatically review it and I will address CodeRabbit's comments.

AI Usage Disclosure

Check one of the checkboxes below:

• This PR does not contain AI-generated code at all.
• [x ] This PR contains AI-generated code. I have tested the code locally and I am responsible for it.

I have used the following AI models and tools: TODO

⚠️ AI Notice - Important!

We encourage contributors to use AI tools responsibly when creating Pull Requests. While AI can be a valuable aid, it is essential to ensure that your contributions meet the task requirements, build successfully, include relevant tests, and pass all linters. Submissions that do not meet these standards may be closed without warning to maintain the quality and integrity of the project. Please take the time to understand the changes you are proposing and their impact.

Summary by CodeRabbit

Release Notes

• New Features

  • Added comprehensive blockchain node with transaction submission, block mining, and state management
  • Introduced command-line interface for key generation, balance queries, transaction submission, and mining
  • Implemented peer-to-peer networking with MDNS and local discovery for node connectivity
  • Added persistent storage and chain state recovery on restart

• Chores

  • Set up project infrastructure with CI/CD pipeline, Makefile, and build configuration
  • Comprehensive test suite covering all core components and integration scenarios

[coderabbitai]

Caution

Review failed

Failed to post review comments

Walkthrough

This pull request introduces a complete blockchain implementation (MiniChain) with core components for transaction processing, block validation, chain management with consensus, peer-to-peer networking with discovery, transaction mempool, SQLite persistence, and a command-line interface for node operations. Includes comprehensive test coverage and development tooling.

Changes

Cohort / File(s)	Summary
Project Setup & Configuration .github/workflows/ci.yml, Makefile, pyproject.toml, .gitignore, README.md	Adds GitHub Actions CI workflow, Makefile with development/testing targets, project metadata and dependencies via pyproject.toml, and documentation updates.
Core Data Structures src/minichain/transaction.py, src/minichain/block.py, src/minichain/state.py	Implements Transaction, Block, and BlockHeader classes with validation, signing, and state management (Account tracking, balance/nonce updates).
Cryptography & Hashing src/minichain/crypto.py, src/minichain/merkle.py, src/minichain/serialization.py	Provides Ed25519 key generation/signing, address derivation, canonical JSON serialization for consensus, and Merkle tree computation for transaction commitments.
Consensus & Mining src/minichain/consensus.py, src/minichain/mining.py	Implements Proof-of-Work validation, difficulty retargeting, nonce mining, and candidate block construction with transaction selection and fee aggregation.
Chain Management src/minichain/chain.py, src/minichain/genesis.py	Provides ChainManager for canonical chain maintenance, fork resolution, state replay, block validation, and genesis block/state initialization.
Transaction Pool & Ordering src/minichain/mempool.py	Implements transaction mempool with fee-based prioritization, nonce ordering, eviction policy, and mining transaction selection.
Node Orchestration & Persistence src/minichain/node.py, src/minichain/storage.py	Central node coordinator managing chain, mempool, storage lifecycle, and SQLite persistence with block/state/metadata management.
Peer Networking src/minichain/network.py	Asynchronous TCP peer networking with MDNS-based local discovery, peer bootstrapping, handshake, peer exchange, and connection management.
Package & CLI src/minichain/__init__.py, src/minichain/__main__.py	Package initialization with version, comprehensive CLI entrypoint with subcommands (generate-key, balance, submit-tx, mine, chain-info, block query).
Unit Tests tests/test_*.py	Comprehensive test coverage for all core modules: block validation, chain management, consensus, cryptography, genesis, mempool, merkle trees, mining, networking, node persistence, state transitions, storage, serialization, and transactions.

Sequence Diagram(s)

sequenceDiagram
    participant User as User/CLI
    participant Node as MiniChainNode
    participant Mempool as Mempool
    participant ChainMgr as ChainManager
    participant Storage as SQLiteStorage
    participant Consensus as Consensus

    User->>Node: submit_transaction(tx)
    Node->>Mempool: add_transaction(tx, state)
    Mempool-->>Node: transaction_id
    Node-->>User: Transaction queued

    User->>Node: mine_one_block()
    Node->>Mempool: get_transactions_for_mining(state, limit)
    Mempool-->>Node: [ready_txs]
    Node->>Consensus: build_candidate_block(chain, mempool, miner_addr)
    Consensus-->>Node: Block template
    Node->>Consensus: mine_candidate_block(template)
    Consensus-->>Node: Mined block with nonce
    Node->>ChainMgr: add_block(block)
    ChainMgr->>ChainMgr: validate_consensus(block)
    ChainMgr->>ChainMgr: replay_state_for_tip()
    ChainMgr-->>Node: Block accepted
    Node->>Mempool: remove_confirmed_transactions(block.txs)
    Node->>Storage: persist_block_state_and_metadata()
    Storage-->>Node: Persisted
    Node-->>User: Block mined at height N

Loading

sequenceDiagram
    participant NodeA as Node A
    participant Net as Network/MDNS
    participant NodeB as Node B

    NodeA->>Net: start_mdns_discovery()
    NodeB->>Net: start_mdns_discovery()
    Net-->>NodeA: Discovered NodeB
    Net-->>NodeB: Discovered NodeA
    NodeA->>NodeB: connect_to_peer(peer_address)
    NodeA->>NodeB: _hello_payload(node_id, address)
    NodeB-->>NodeA: hello_response
    NodeB->>NodeA: _hello_payload(node_id, address)
    NodeA-->>NodeB: hello_response
    NodeA->>NodeB: _peer_list_payload(known_peers)
    NodeB-->>NodeA: peer_list_response
    NodeA->>NodeB: _peer_reader_loop()
    NodeB->>NodeA: _peer_reader_loop()
    Note over NodeA,NodeB: Mutual peer exchange<br/>and connection established

Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~75 minutes

Suggested labels

Python Lang, Make Lang, Documentation

Suggested reviewers

• Zahnentferner

Poem

🐰 A blockchain blooms in Python code,
With miners toiling down the road,
Transactions pooled, chains intertwined,
And peers discovering humankind!
State replayed, blocks so fine—
This MiniChain hops through time! ✨

🚥 Pre-merge checks | ✅ 2

✅ Passed checks (2 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The PR title 'feat: py-libp2p-style peer discovery networking service' directly and accurately describes the main feature addition—a peer discovery networking service inspired by libp2p patterns.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

• 📝 Generate docstrings (stacked PR)
• 📝 Generate docstrings (commit on current branch)

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[arunabha003]

Superseded by #39. Closing this PR to keep review history in one place.