Skip to content

[FEATURE]: Introduce Merkle Tree for Transaction Verification (SPV Support) #27

@Muneerali199

Description

@Muneerali199

Feature and its Use Cases

🌟 Feature Description

Upgrade the current block hashing mechanism to use a Merkle Tree structure instead of hashing the raw transaction list directly.

This enhancement will enable Simplified Payment Verification (SPV) and support light-client transaction verification, aligning the project more closely with real-world blockchain architectures.


🔍 Problem Statement

Currently, the block hashing mechanism hashes the full list of transactions directly.

While functional for a minimal educational blockchain, this design has several limitations:

  • Does not support SPV-style verification
  • Requires downloading the entire block to verify a transaction
  • Does not reflect real-world blockchain architectures (e.g., Bitcoin, Ethereum)
  • Limits scalability and educational realism

Without a merkle_root stored in the block header, cryptographic inclusion proofs cannot be generated.


🎯 Expected Outcome

The implementation should include:

1️⃣ Merkle Tree Utility

Create a MerkleTree class in the Python backend that supports:

  • Merkle root computation
  • Merkle proof generation
  • Merkle proof verification

2️⃣ Block Header Update

Modify the block structure to store a merkle_root instead of hashing raw transaction data directly.

Example:

class Block:
    index: int
    previous_hash: str
    timestamp: float
    merkle_root: str
    nonce: int

## 3️⃣ SPV Verification API Endpoints

Add API endpoints such as:

### `GET /verify_transaction?tx_hash=<hash>&block_index=<index>`

**Returns:**

- Inclusion proof  
- Merkle path  
- Verification status (`true` / `false`)  

---

### `GET /block/<index>`

Returns block data including Merkle-based verification support.

This enables frontends and light clients to verify transaction inclusion cryptographically without downloading the full block data.

---

## 🛠 Proposed Implementation Plan

1. Create `core/merkle.py` containing the `MerkleTree` class  
2. Update `core/block.py` to integrate the Merkle root during block creation  
3. Introduce FastAPI endpoints for SPV verification  
4. Add comprehensive unit tests validating:
   - Root consistency  
   - Proof correctness  
   - Cross-verification integrity  

---

## 📦 Dependencies to Add

- `fastapi`
- `uvicorn`

---

## 📚 Why This Is Important

This enhancement:

- Aligns the project with real-world blockchain architecture  
- Introduces practical cryptographic proof concepts  
- Improves scalability design  
- Enhances educational value  
- Enables simulation of light-client verification  

---

## 🙋 Contribution

I would like to work on implementing the Merkle Tree logic, updating the block architecture, and building the SPV verification endpoints, subject to maintainer approval.

### Additional Context

_No response_

### Code of Conduct

- [x] I have joined the [Discord server](https://discord.gg/hjUhu33uAn) and will post updates there
- [x] I have searched existing issues to avoid duplicates

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request

    Type

    No type
    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions