Skip to main content
Colibri Logo

Colibri Stateless — Python

Verify Ethereum RPC data cryptographically — without running a full node.

ETH2.0 Spec Version 1.4.0 License PyPI

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_summaries proofs, where other light clients simply fail.
  • eth_getLogs completeness proofs — optional logs_completeness=True proves 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 install with pre-built native extensions.
  • Testing utilities — mock HTTP requests and storage for deterministic tests.
  • Multi-chain — Ethereum Mainnet, Sepolia, Gnosis Chain, and more.
  • Local eth_call proofs — use_accesslist=True (default) uses eth_createAccessList; set False for legacy debug_traceCall.
  • L1 execution RPCs — optional l1_eth_rpcs for requests that target the L1 of the configured chain. Empty uses the built-in defaults. Only an EEZ L2 such as RollupX has an L1 that differs from the chain itself (Ethereum mainnet). Requests for the configured chain keep using eth_rpcs.
  • Privacy-preserving eth_call — combine ProverMode.HYBRID + PrivacyMode.BASIC + oblivious_nodes (default empty; e.g. https://rpc.safe-node.com/, API key for testing). Setting oblivious_nodes auto-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, use_accesslist / prover mode, and other 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)
  • 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.

Metadata

Release files for colibri-stateless 3.1.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Built distributions (wheels)

Table of built distributions (wheels) for colibri-stateless 3.1.0
File Actions
colibri_stateless-3.1.0-cp314-cp314-win_amd64.whl CPython 3.14 CPython 3.14 Windows x86-64 Details for colibri_stateless-3.1.0-cp314-cp314-win_amd64.whl
colibri_stateless-3.1.0-cp314-cp314-manylinux_2_17_x86_64.whl CPython 3.14 CPython 3.14 Linux glibc 2.17+ x86-64 Details for colibri_stateless-3.1.0-cp314-cp314-manylinux_2_17_x86_64.whl
colibri_stateless-3.1.0-cp314-cp314-macosx_26_0_universal2.whl CPython 3.14 CPython 3.14 macOS 26.0+ universal2 (ARM64, x86-64) Details for colibri_stateless-3.1.0-cp314-cp314-macosx_26_0_universal2.whl
colibri_stateless-3.1.0-cp312-cp312-win_amd64.whl CPython 3.12 CPython 3.12 Windows x86-64 Details for colibri_stateless-3.1.0-cp312-cp312-win_amd64.whl
colibri_stateless-3.1.0-cp312-cp312-manylinux_2_17_x86_64.whl CPython 3.12 CPython 3.12 Linux glibc 2.17+ x86-64 Details for colibri_stateless-3.1.0-cp312-cp312-manylinux_2_17_x86_64.whl
colibri_stateless-3.1.0-cp312-cp312-macosx_26_0_universal2.whl CPython 3.12 CPython 3.12 macOS 26.0+ universal2 (ARM64, x86-64) Details for colibri_stateless-3.1.0-cp312-cp312-macosx_26_0_universal2.whl

Total release size: 4.2 MB

Release files / colibri_stateless-3.1.0-cp314-cp314-win_amd64.whl

Download URL colibri_stateless-3.1.0-cp314-cp314-win_amd64.whl
Size 644.0 kB
Tags CPython 3.14 Windows x86-64
SHA-256 checksum
How to use checksums
cd75b83abb77345d33478a5a1f45dcb4d67e13943d4bdc683d9aca3dc282eba9
BLAKE2b-256 checksum
How to use checksums
2752170b058bcf3e8712cd059db3c75e8da1a9a52500adb964adcd5a147d207c
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.10.22

Release files / colibri_stateless-3.1.0-cp314-cp314-manylinux_2_17_x86_64.whl

Download URL colibri_stateless-3.1.0-cp314-cp314-manylinux_2_17_x86_64.whl
Size 839.2 kB
Tags CPython 3.14 Linux glibc 2.17+ x86-64
SHA-256 checksum
How to use checksums
4b229522bfddd52a80773a6eefe949aeb09708cc9f42cf9e3f01555b201bbd35
BLAKE2b-256 checksum
How to use checksums
4dc56eca8c1df752da36a2494ddbca53e1a43b3aeffe451a5dcb4d39765fd886
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.10.22

Release files / colibri_stateless-3.1.0-cp314-cp314-macosx_26_0_universal2.whl

Download URL colibri_stateless-3.1.0-cp314-cp314-macosx_26_0_universal2.whl
Size 614.6 kB
Tags CPython 3.14 macOS 26.0+ universal2 (ARM64, x86-64)
SHA-256 checksum
How to use checksums
be3f1733305ad601fc3cb0d1d8acfcbd3efc35fb48b19a60d12880d9077de3f6
BLAKE2b-256 checksum
How to use checksums
816a59e105907a8ad79083fc3d74dbc4f7dd9bd932bc89b024aea6a9cc32f4f6
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.10.22

Release files / colibri_stateless-3.1.0-cp312-cp312-win_amd64.whl

Download URL colibri_stateless-3.1.0-cp312-cp312-win_amd64.whl
Size 626.9 kB
Tags CPython 3.12 Windows x86-64
SHA-256 checksum
How to use checksums
5c5dd4f0a5e0ed2d6cb218c1f2bec018f5e22b4b8c70b60eea58af0503be0421
BLAKE2b-256 checksum
How to use checksums
597f49b0b1692861b03b8f1a7dedaa5764a57db123713c07edc58f96e79cf95d
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.10.22

Release files / colibri_stateless-3.1.0-cp312-cp312-manylinux_2_17_x86_64.whl

Download URL colibri_stateless-3.1.0-cp312-cp312-manylinux_2_17_x86_64.whl
Size 839.2 kB
Tags CPython 3.12 Linux glibc 2.17+ x86-64
SHA-256 checksum
How to use checksums
b3e4ebd3b0fedb5df8af23d6d9875c8e0712927daf2ec294c0826534615b55b2
BLAKE2b-256 checksum
How to use checksums
e53df950c70521cd85fe2b8452b3776426c946e9449e6cd2e520dd9af6077230
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.10.22

Release files / colibri_stateless-3.1.0-cp312-cp312-macosx_26_0_universal2.whl

Download URL colibri_stateless-3.1.0-cp312-cp312-macosx_26_0_universal2.whl
Size 614.3 kB
Tags CPython 3.12 macOS 26.0+ universal2 (ARM64, x86-64)
SHA-256 checksum
How to use checksums
365812bcd2c74cca0076133e797fb812f8454999bc658913604c638dd0b63a43
BLAKE2b-256 checksum
How to use checksums
d7ddbcf1382e04cf4a4cb07410d3c4f5481e86a7d9d6ac761a037e12ceeb4386
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.10.22

Security for colibri-stateless 3.1.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

3.1.0 This release

6 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page