Metadata-Version: 2.4
Name: colibri-stateless
Version: 0.5.0
Summary: Python bindings for Colibri stateless Ethereum proof library
Home-page: https://github.com/corpus-core/colibri-stateless
Author: corpus.core
Author-email: "corpus.core" <contact@corpus.core>
Maintainer-email: "corpus.core" <contact@corpus.core>
License: MIT
Project-URL: Homepage, https://github.com/corpus-core/colibri-stateless
Project-URL: Documentation, https://corpus-core.gitbook.io/specification-colibri-stateless/developer-guide/bindings/python
Project-URL: Repository, https://github.com/corpus-core/colibri-stateless
Project-URL: Bug Tracker, https://github.com/corpus-core/colibri-stateless/issues
Keywords: ethereum,blockchain,proof,verification,web3,rpc
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Networking
Classifier: Topic :: Security :: Cryptography
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: aiohttp>=3.8.0
Requires-Dist: typing-extensions>=4.0.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: black>=22.0.0; extra == "dev"
Requires-Dist: mypy>=1.0.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Provides-Extra: test
Requires-Dist: pytest>=7.0.0; extra == "test"
Requires-Dist: pytest-asyncio>=0.21.0; extra == "test"
Requires-Dist: pytest-mock>=3.10.0; extra == "test"
Dynamic: author
Dynamic: home-page
Dynamic: requires-python

<img src="https://github.com/corpus-core/colibri-stateless/raw/dev/c4_logo.png" alt="C4 Logo" width="300"/>

# Colibri Python Bindings (corpus core colibri client)

![ETH2.0_Spec_Version 1.4.0](https://img.shields.io/badge/ETH2.0_Spec_Version-1.4.0-2e86c1.svg)

The colibri client is a stateless and trustless ethereum client, which is optimized for the mobile apps or embedded devices, because it does not hols the state, but verifies on demand. 

## 🚀 Quick Start

### Installation

```bash
pip install colibri-stateless
```

### Basic Usage

```python
import asyncio
from colibri import Colibri

async def main():
    # Initialize client for Ethereum Mainnet
    client = Colibri(chain_id=1, proofers=["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())
```

## ✨ Key Features

- **🔐 Cryptographic Verification** - All RPC responses verified with Merkle proofs
- **🚀 Async/Await Support** - Modern Python async support for network operations  
- **💾 Pluggable Storage** - Customizable storage backends for caching
- **🧪 Comprehensive Testing** - Mock HTTP requests and storage for testing
- **🌐 Multi-Chain Support** - Ethereum Mainnet, Sepolia, Gnosis Chain, and more
- **📦 Easy Integration** - Simple pip install with pre-built native extensions

## 📖 Documentation

**Full Documentation**: [GitBook Guide](https://corpus-core.gitbook.io/specification-colibri-stateless/developer-guide/bindings/python)

- **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

```bash
# Clone repository
git clone https://github.com/corpus-core/colibri-stateless.git
cd colibri-stateless/bindings/python

# Build native extension
./build.sh

# Install in development mode
pip install -e .

# Run tests
python -m pytest tests/
```

### Integration Tests

```python
# 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](https://github.com/corpus-core/colibri-stateless)
- **Swift Bindings**: iOS/macOS native integration
- **Kotlin Bindings**: Android/JVM integration
- **JavaScript Bindings**: Web/Node.js integration

## 📄 License

MIT License - see [LICENSE](../../LICENSE) for details.

## 🤝 Contributing

Contributions welcome! Please read our [Contributing Guide](../../CONTRIBUTING.md) and check the [Development Documentation](https://corpus-core.gitbook.io/specification-colibri-stateless/developer-guide/bindings/python).
