Skip to content

logiccrafterdz/OpenLens

BranchesTags

Repository files navigation

OpenLens

OpenLens v0.3.0 — Verify with Consensus

Verify with Consensus
Check on-chain events using math + majority agreement — no payments, no trust, no excuses.

✅ This is not a product. It's a promise:
"You deserve to know the truth — without asking permission."
This tool is free because knowledge should be free.

🎯 What OpenLens Does

Verifies blockchain events by:

  1. Asking 3 independent RPCs for the same data
  2. Checking they all agree (if not → security alert)
  3. Proving the receipt exists mathematically (MPT proof when available)
  4. Verifying the event signature matches

No API keys. No subscriptions. No daemon. No trust.

✨ Why This Exists

The blockchain ethos is "don't trust, verify" — but verification has become gatekept by infrastructure costs. Running an Ethereum full node requires hundreds of GB of storage and significant bandwidth. Commercial RPC providers charge for API access or impose rate limits. Light clients are still experimental.

OpenLens makes verification practically possible for everyone:

  • ✅ Zero-cost: No API keys, no subscriptions, no hidden dependencies
  • ✅ Self-contained: Proofs can be cached and re-verified offline
  • ✅ Lightweight: <10 MB RAM, works on Raspberry Pi
  • ✅ Open-source: MIT licensed, fork-friendly, community-owned
  • ✅ Educational: Clear code and examples to understand how verification works

This is a public good project, not a product.

🚀 Quick Start

Installation

# Clone the repository
git clone https://github.com/openlens/openlens.git
cd openlens

# Install (requires Python 3.9+)
pip install .

Basic Usage

# Verify any transaction (uses 3 RPC quorum by default)
openlens verify \
  --tx 0x1c08d40f5e48299cc6d94bf8b9edb15c09bc7fffff2a3cf2c13ea9a31b4e8b8e \
  --event "Transfer(address,address,uint256)" \
  --chain ethereum

# Output:
# ✅ VERIFIED (Level: HIGH)
# 3/3 RPCs agree | MPT proof confirmed | Event signature matches

That's it. Simple, honest verification.

🔐 Trust Model: What We Verify vs. What We Trust

OpenLens is trust-minimized, not trustless. Here's exactly what we verify cryptographically and what we currently trust:

✅ What OpenLens Verifies Cryptographically (v0.2)

Verification How It Works Trust Required
Event Signature Computes keccak256 of event signature, matches against log topic[0] None - pure cryptography
Bloom Filter Verifies log address and topics appear in receipt's bloom filter None - deterministic algorithm
Receipt Structure Validates receipt has all required fields and succeeded None - data validation
Block Header (Trustless Mode) RLP-encodes header fields, computes keccak256, matches block hash You verify 1 block hash from multiple sources

⚠️ What OpenLens Cannot Verify Yet (Requires RPC Honesty)

Data Current Status Reason Roadmap
Receipt Content ❌ Not cryptographically proven Requires MPT proof from receiptsRoot ✅ Planned for v0.3
Log Data ❌ Not cryptographically proven Logs are inside receipt (see above) ✅ Planned for v0.3
Transaction Ordering ❌ Not cryptographically proven Would require full MPT traversal ✅ Planned for v0.4

What this means in practice:

  • ✅ We CAN detect if RPC sends you a log with the wrong event signature or address
  • ✅ We CAN detect if RPC gives you a block header that doesn't match the block hash you verified
  • ❌ We CANNOT detect if RPC fabricates an entire log with a matching event signature (requires MPT proof)
  • ❌ We CANNOT detect if RPC gives you the wrong receipt for a transaction (requires MPT proof)

🛡️ How to Minimize Trust Today

  1. Use multiple RPC providers - Verify same transaction from 2-3 different RPCs
  2. Verify block hash independently - Check Etherscan + your own node + another RPC
  3. Use --trustless mode - Verifies block headers cryptographically
  4. Run your own archive node - Full control (when MPT proofs are implemented)
  5. Wait for v0.3+ - Full MPT proof verification (see roadmap below)

Custom RPC Endpoints

By default, OpenLens uses free public RPCs. You can override these:

# Via CLI flag
openlens verify --tx 0x... --event "Transfer(...)" --rpc https://your-rpc-url.com

# Via environment variable
export OPENLENS_RPC_ETHEREUM=https://your-ethereum-rpc.com
export OPENLENS_RPC_BASE=https://your-base-rpc.com
openlens verify --tx 0x... --event "Transfer(...)"

🔍 How It Works

Verification Algorithm

When you verify a log event, OpenLens:

  1. Fetches blockchain data via RPC:

    • Transaction receipt (contains logs)
    • Block header (contains cryptographic roots)

  2. Locates the specific log:

    • Computes expected topic[0]: keccak256("Transfer(address,address,uint256)")
    • Finds matching log in receipt

  3. Verifies cryptographically:

    • ✅ Log exists at claimed index in receipt
    • ✅ Event signature matches (topic[0] verification)
    • ✅ Log appears in receipt's Bloom filter (probabilistic check)
    • ✅ Receipt integrity (all required fields present, transaction succeeded)

  4. Caches proof to ~/.openlens/proofs/ for offline re-verification

🗺️ MPT Proof Roadmap 🛣️

The path to full trustless verification:

OpenLens has a clear roadmap to achieve full cryptographic verification without trusting RPC providers. This requires implementing Merkle Patricia Trie (MPT) proofs.

What are MPT Proofs?

Ethereum blocks contain three Merkle Patricia Trie roots:

  • stateRoot - All account states
  • transactionsRoot - All transactions in block
  • receiptsRoot - All transaction receipts in block

An MPT proof is a cryptographic proof that a specific receipt exists in the receiptsRoot trie. With this, you only need to trust a single block hash (verified from multiple sources), and everything else is mathematically proven.

Implementation Phases

Phase 1 - v0.2 (CURRENT): Design & Documentation ✅

  • Comprehensive MPT algorithm design (src/openlens/mpt.py)
  • Trie node decoding pseudocode
  • Proof verification algorithm
  • Clear documentation of current limitations

Phase 2 - v0.3 (Q2 2025): Basic MPT Implementation 🚧

  • Implement trie node decoding (RLP + HP encoding)
  • Implement proof verification algorithm
  • Integration with archive node RPC providers
  • Tests using real blockchain data

Phase 3 - v0.4 (Q3 2025): Light Client Integration 🔮

  • Integrate with Helios or similar light client
  • Use consensus layer (Beacon Chain) for full verification
  • No archive node needed - works with any RPC

Phase 4 - v0.5 (Q4 2025): Production 🚀

  • Portal network integration
  • Decentralized proof distribution
  • Multi-chain support (Optimism, Arbitrum, Polygon)

Verify a log event in a transaction.

openlens verify --tx <hash> --event <signature> [options]

Options:

  • --tx: Transaction hash (required for online mode)
  • --event: Event signature, e.g., "Transfer(address,address,uint256)" (required for online mode)
  • --chain: Chain to verify on (ethereum or base, default: ethereum)
  • --rpc: Custom RPC URL (overrides defaults)
  • --proof: Path to cached proof file (for offline verification)
  • --offline: Enable offline mode (requires --proof)
  • --json: Output as JSON (default: human-readable)

openlens bridge-check

Verify Optimism bridge flow (L1→L2).

openlens bridge-check --tx <l1_hash> --l2-tx <l2_hash> [options]

Options:

  • --tx: L1 transaction hash (required)
  • --l2-tx: L2 transaction hash (required)
  • --chain: L2 chain (base, default: base)
  • --l1-rpc: Custom L1 RPC URL
  • --l2-rpc: Custom L2 RPC URL
  • --json: Output as JSON

openlens export-proof

Export verification proof to file.

openlens export-proof --tx <hash> --event <signature> --output <path> [options]

Options:

  • --tx: Transaction hash (required)
  • --event: Event signature (required)
  • --output: Output file path (required)
  • --chain: Chain (ethereum or base, default: ethereum)
  • --rpc: Custom RPC URL

🌍 Philosophy: This Is Not an Indexer

OpenLens does one thing well: verify that a specific on-chain event happened as claimed.

We do NOT:

  • ❌ Index all blockchain data
  • ❌ Provide block explorers or analytics dashboards
  • ❌ Aggregate or search across transactions
  • ❌ Run servers or databases

We DO:

  • ✅ Fetch minimal data needed for cryptographic verification
  • ✅ Cache proofs locally for offline access
  • ✅ Provide understandable, educational verification
  • ✅ Respect user sovereignty (no telemetry, no tracking)

If you need to explore blockchain data, use a block explorer.
If you need to verify data is authentic, use OpenLens.

🔐 Security Model

Current Trust Assumptions (v0.2)

What you must trust:

  • ✅ One block hash - Verified from 2+ independent sources (Etherscan + RPC + your node)
  • ✅ RPC provider honesty - For receipt and log content (until MPT proofs in v0.3+)

What you don't need to trust:

  • ❌ Third-party indexers or explorers (we verify directly)
  • ❌ API aggregators
  • ❌ Off-chain databases
  • ❌ Event signature correctness (we compute it ourselves)
  • ❌ Bloom filter integrity (we verify it against block header)

How to Minimize Trust Today

  1. Use --trustless mode - Cryptographically verify block headers
  2. Query multiple RPCs - Cross-check same transaction from 2-3 providers
  3. Verify block hash - Check against Etherscan, another RPC, your own node
  4. Run your own RPC - Maximum control (archive node for future MPT proofs)
  5. Inspect the code - OpenLens is fully open-source (MIT license)

Path to Full Trustlessness

See MPT Proof Roadmap above. When MPT proofs are implemented (v0.3+), you will only need to trust a single block hash verified from multiple sources. Everything else will be cryptographically proven.

🧱 Technical Stack

  • Language: Python 3.9+ (for wide compatibility)
  • Dependencies (all MIT/BSD licensed):
    • web3.py - Ethereum RPC client
    • rlp - RLP encoding
    • eth-hash[pycryptodome] - Keccak-256 hashing

No frameworks, ORMs, or heavy abstractions. Just pure, readable code.

🤝 Contributing

OpenLens is a community project. Contributions welcome:

  • Found a bug? Open an issue
  • Want a feature? Propose it (aligned with our minimalist philosophy)
  • Fixed something? Submit a PR
  • Used OpenLens for research? Share your findings

Development Setup

git clone https://github.com/openlens/openlens.git
cd openlens
pip install -e .  # Editable install for development

Code Principles

  1. Clarity over cleverness - code should be educational
  2. Minimalism - no unnecessary dependencies
  3. Zero telemetry - respect user privacy
  4. Honest documentation - document limitations transparently

📜 License

MIT License - See LICENSE for details.

Copyright (c) 2025 OpenLens Contributors

This is a public good. Use it freely. Fork it. Improve it. Make verification accessible.

🙏 Acknowledgments

Built for developers, auditors, and researchers in:

  • 🌍 Everywhere

Because verification shouldn't be a luxury.

📞 Support

Have questions, suggestions, or collaboration ideas? Feel free to reach out!

No Discord. No Telegram. No "community manager."
Just code, docs, and GitHub issues. Simple.

Don't trust. Verify. 🔍

About

Check on-chain events using math + majority agreement, no payments, no trust, no excuses.

Topics

python open-source cryptography ethereum smart-contracts mpt web3 trustless merkle-proof security-tool auditing-tool proof-of-inclusion base-network blockchain-verification verification-framework

Resources

Readme

License

MIT license
Activity

Stars

1 star

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages