Colibri Stateless — Python
Verify Ethereum RPC data cryptographically — without running a full node.
Colibri Stateless is a highly efficient prover/verifier for Ethereum (with upcoming support for Layer-2s such as OP-Stack). These Python bindings wrap the C core and give you an async API that verifies every RPC response against the beacon chain — no full node, no continuous sync.
Website · Docs · Whitepaper · Privacy (PAP)
Why Colibri?
- Stateless — verification needs nothing but the proof and the sync committee it is checked against. The committee is cached locally so it does not have to travel with every request, but it works just as well with an empty cache or none at all. No persistent state, no full node.
- Cryptographically verified RPC — every RPC response is checked against BLS signatures.
- Offline verification — proofs are fully self-contained and verify without any network connection, thanks to zk-proofs for the sync committee and signed checkpoints.
- On-demand, not always-on — work happens only when you make a request; no background sync burning bandwidth, CPU, or battery.
- Verifies historical data (older than ~27h / 8192 blocks) — via
historical_summariesproofs, where other light clients simply fail. eth_getLogscompleteness proofs — optionallogs_completeness=Trueproves no matching log was omitted in the requested range.- Fully verified local transaction simulation — simulate a transaction against verified state before signing.
- Privacy-aware — Pragmatic Adaptive Privacy (PAP) mode (
privacy_mode=PrivacyMode.BASIC). Experimental.
Quick Start
Installation
python3 -m pip install colibri-stateless
Basic Usage
import asyncio
from colibri import Colibri
async def main():
# Initialize client for Ethereum Mainnet
client = Colibri(chain_id=1, provers=["https://mainnet.colibri-proof.tech"])
# Make verified RPC call
result = await client.rpc("eth_blockNumber", [])
print(f"Current block: {result}")
# Get account balance with proof verification
balance = await client.rpc("eth_getBalance", [
"0x95222290DD7278Aa3Ddd389Cc1E1d165CC4BAfe5",
"latest"
])
print(f"Balance: {balance}")
# Run async function
asyncio.run(main())
Python-specific features
- Async/await — modern async API for all network operations.
- Pluggable storage — customizable storage backends for caching.
- Easy integration —
pip installwith pre-built native extensions. - Testing utilities — mock HTTP requests and storage for deterministic tests.
- Multi-chain — Ethereum Mainnet, Sepolia, Gnosis Chain, and more.
- Privacy-preserving
eth_call— combineProverMode.HYBRID+PrivacyMode.BASIC+oblivious_nodes(default empty; e.g.https://rpc.safe-node.com/, API key for testing). Settingoblivious_nodesauto-enables PAP. TEE/ORAM background: Oblivious Labs.
Documentation
Full documentation: GitBook Guide
- API Reference — complete class and method documentation
- Storage System — custom storage implementations
- Testing Framework — mock data and integration tests
- Configuration — chain setup and advanced options
- Building from Source — development and contribution guide
Development
Building from Source
# Clone repository
git clone https://github.com/corpus-core/colibri-stateless.git
cd colibri-stateless/bindings/python
# Build native extension
./build.sh
# Option 1: Use virtual environment (recommended)
python3 -m venv venv
source venv/bin/activate
pip install -e .
pip install -r requirements-dev.txt
# Run tests
pytest tests/ -v
# Deactivate when done
deactivate
Alternative without virtual environment:
# Install test dependencies with --user flag
python3 -m pip install --user pytest pytest-asyncio aiohttp
# Run tests directly with PYTHONPATH
PYTHONPATH=src python3 -m pytest tests/ -v
Quick Debug Build
For faster iteration during development:
# Build in debug mode
./build_debug.sh
# Run tests without installation
PYTHONPATH=src python3 -m pytest tests/ -v
Integration Tests
# Run with real blockchain data (offline)
from colibri.testing import discover_tests, run_test_case
tests = discover_tests()
for test_name, test_config in tests.items():
result = await run_test_case(test_name, test_config)
print(f"Test {test_name}: {'PASSED' if result else 'FAILED'}")
System Requirements
- Python 3.8+
- CMake 3.20+ (for building from source)
- C++17 compiler (for building from source)
Related Projects
- Core Library: colibri-stateless
- Swift Bindings: iOS/macOS native integration
- Kotlin Bindings: Android/JVM integration
- JavaScript Bindings: Web/Node.js integration
License
MIT License - see LICENSE for details.
Contributing
Contributions welcome! Please read our Contributing Guide and check the Development Documentation.
1 maintainer
Release files for colibri-stateless 2.0.2
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Built distributions (wheels)
| File | Reset | |||
|---|---|---|---|---|
| colibri_stateless-2.0.2-cp314-cp314-win_amd64.whl | CPython 3.14 | CPython 3.14 | Windows x86-64 | Details |
| colibri_stateless-2.0.2-cp314-cp314-manylinux_2_17_x86_64.whl | CPython 3.14 | CPython 3.14 | Linux glibc 2.17+ x86-64 | Details |
| colibri_stateless-2.0.2-cp314-cp314-macosx_26_0_universal2.whl | CPython 3.14 | CPython 3.14 | macOS 26.0+ universal2 (ARM64, x86-64) | Details |
| colibri_stateless-2.0.2-cp312-cp312-win_amd64.whl | CPython 3.12 | CPython 3.12 | Windows x86-64 | Details |
| colibri_stateless-2.0.2-cp312-cp312-manylinux_2_17_x86_64.whl | CPython 3.12 | CPython 3.12 | Linux glibc 2.17+ x86-64 | Details |
| colibri_stateless-2.0.2-cp312-cp312-macosx_26_0_universal2.whl | CPython 3.12 | CPython 3.12 | macOS 26.0+ universal2 (ARM64, x86-64) | Details |
Total release size: 3.3 MB
Release files / colibri_stateless-2.0.2-cp314-cp314-win_amd64.whl
| Download URL | colibri_stateless-2.0.2-cp314-cp314-win_amd64.whl |
|---|---|
| Size | 547.3 kB |
| Tags | CPython 3.14 Windows x86-64 |
|
SHA-256 checksum How to use checksums |
a82826072ae97a648ab9a3edd1cb0cfac3ce1215bb2334487462bbe903bddf0f
|
|
BLAKE2b-256 checksum How to use checksums |
c2c5ba2f9c429ffff8779246e031a669ff768b5669e79b5be8727f0acc7ffd5d
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.10.20
|
Release files / colibri_stateless-2.0.2-cp314-cp314-manylinux_2_17_x86_64.whl
| Download URL | colibri_stateless-2.0.2-cp314-cp314-manylinux_2_17_x86_64.whl |
|---|---|
| Size | 632.1 kB |
| Tags | CPython 3.14 Linux glibc 2.17+ x86-64 |
|
SHA-256 checksum How to use checksums |
62198e8ab1525cb56e7aa12faea9992feed8da4c6aca06298a344234d105a1f7
|
|
BLAKE2b-256 checksum How to use checksums |
2147f0698f2fe3c2cbe36c62fb65ee212271d2d7ca48ba07453f9b721d866303
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.10.20
|
Release files / colibri_stateless-2.0.2-cp314-cp314-macosx_26_0_universal2.whl
| Download URL | colibri_stateless-2.0.2-cp314-cp314-macosx_26_0_universal2.whl |
|---|---|
| Size | 486.1 kB |
| Tags | CPython 3.14 macOS 26.0+ universal2 (ARM64, x86-64) |
|
SHA-256 checksum How to use checksums |
2e9dbafbef7357ae7d0d483594751fea374db3fca94619171834d3e0c9d8f461
|
|
BLAKE2b-256 checksum How to use checksums |
af69eca7dc9880d02661170ca1eb0158b4ec220f45727fa2597491adf5cf2a42
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.10.20
|
Release files / colibri_stateless-2.0.2-cp312-cp312-win_amd64.whl
| Download URL | colibri_stateless-2.0.2-cp312-cp312-win_amd64.whl |
|---|---|
| Size | 534.0 kB |
| Tags | CPython 3.12 Windows x86-64 |
|
SHA-256 checksum How to use checksums |
b5ce6ffcfd2a8b0e63d76d94ca26d695ac937706f8e2f01fb6ece6cfc41c1265
|
|
BLAKE2b-256 checksum How to use checksums |
5865a6412c77c8410cb45da0e8070e37b26b31b4976ccb4dbc0dba065322b064
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.10.20
|
Release files / colibri_stateless-2.0.2-cp312-cp312-manylinux_2_17_x86_64.whl
| Download URL | colibri_stateless-2.0.2-cp312-cp312-manylinux_2_17_x86_64.whl |
|---|---|
| Size | 632.2 kB |
| Tags | CPython 3.12 Linux glibc 2.17+ x86-64 |
|
SHA-256 checksum How to use checksums |
d81de1b1f180a345a08fc39cc0181afad4c3725d4e9d848d155127d202b198e4
|
|
BLAKE2b-256 checksum How to use checksums |
c688bfd6aa53501498896d5c79da681442e32753cb4d859c9ba0fbaa05ddc441
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.10.20
|
Release files / colibri_stateless-2.0.2-cp312-cp312-macosx_26_0_universal2.whl
| Download URL | colibri_stateless-2.0.2-cp312-cp312-macosx_26_0_universal2.whl |
|---|---|
| Size | 485.6 kB |
| Tags | CPython 3.12 macOS 26.0+ universal2 (ARM64, x86-64) |
|
SHA-256 checksum How to use checksums |
953f64c7c7b8d3a62a4166bc48b2ec722064efd7308d79def82e20fbc1356dc1
|
|
BLAKE2b-256 checksum How to use checksums |
b15c7bf2102306bfe94a1f555e6f4c0fe75b0a62d5aa1632488a4bdb3c3f7e41
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.10.20
|
