How akcelero/merkle-zeppelin works
Project type and purpose
• This is an open-source Python library (“merkle-zeppelin”) providing Merkle Tree construction, proof collection, and verification aligned with OpenZeppelin standards.
• It ships as a PyPI package; clients import it to generate Merkle roots, collect proofs, serialize/deserialize data, and verify proofs.
File structure
• Top-level:
• src/merkle_zeppelin/ — core library code
• src/merkle_zeppelin/binary.py — binary data helper
• src/merkle_zeppelin/merkle.py — core MerkleTree class and algorithms
• src/merkle_zeppelin/data_io/ — importer/exporter abstraction and JSON support
– base_importer.py, base_exporter.py define plugin interfaces
– json_importer.py, json_exporter.py concrete implementations
– dto.py defines data transfer objects (schemas)
• src/merkle_zeppelin/exceptions.py — custom exception types
• tests/ — unit tests for core algorithms and I/O modules
• images/ — documentation assets
• CI/CD config (GitHub Actions), pre-commit, Justfile, pyproject.toml
Key points from the README
• Core functionality: build tree, compute root, gather proofs, verify proofs
• Supports pluggable hash function (default keccak256)
• JSON import/export as a built-in use case
a. Main components
• Client Application (user code)
• MerkleEngine (core module in merkle.py)
• HashFunction Layer (abstracted; default keccak256)
• Data I/O Layer
– BaseImporter, BaseExporter (extension/plugin interfaces)
– JsonImporter, JsonExporter (concrete adapters)
• DTOs (schemas passed between I/O and core)
• Exception Layer (centralized error types)
b. Relationships & interactions
1. Client calls MerkleEngine.build_tree(data_items) → returns Tree object
2. Client invokes MerkleEngine.get_proof(tree, item) → returns proof list
3. Client uses MerkleEngine.verify_proof(root, item, proofs) → boolean
4. For persistence/transfer, client selects exporter/importer:
• JsonExporter.serialize(tree) → JSON payload
• JsonImporter.deserialize(json_payload) → Tree object
5. All hashing operations route through the HashFunction Layer
6. Exceptions thrown by any layer propagate to client or can be caught
c. Architectural patterns & design principles
• Plugin/Strategy pattern for importers & exporters
• Single Responsibility: core algorithm vs serialization vs error handling
• Dependency inversion: core doesn’t hard-code JSON; uses abstract base classes
d. Relevant technologies & libraries
• Python 3.x runtime
• pyproject.toml / Poetry packaging
• sha3.keccak256 hash function (via eth-hash or similar)
• JSON standard library or json module for (de)serialization