Metadata-Version: 2.4
Name: trustchain-py
Version: 2.2.0
Summary: TrustChain — decentralized trust primitives for Python
Project-URL: Homepage, https://github.com/viftode4/trustchain-py
Project-URL: Repository, https://github.com/viftode4/trustchain-py
Author: Vlad Levytskyy
License-Expression: MIT
License-File: LICENSE
Keywords: agents,blockchain,decentralized,p2p,trust
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Security
Classifier: Topic :: System :: Distributed Computing
Requires-Python: >=3.11
Requires-Dist: cryptography>=43.0
Requires-Dist: fastapi>=0.115
Requires-Dist: httpx>=0.28
Requires-Dist: networkx>=3.0
Requires-Dist: uvicorn>=0.34
Provides-Extra: all
Requires-Dist: aioquic>=1.2; extra == 'all'
Requires-Dist: crewai>=0.80; extra == 'all'
Requires-Dist: fastmcp>=3.0; extra == 'all'
Requires-Dist: grpcio>=1.68; extra == 'all'
Requires-Dist: hypercorn>=0.17; extra == 'all'
Requires-Dist: langchain-core>=0.3; extra == 'all'
Requires-Dist: protobuf>=5.29; extra == 'all'
Provides-Extra: bench
Requires-Dist: pytest-benchmark>=4.0; extra == 'bench'
Requires-Dist: pytest>=8.0; extra == 'bench'
Provides-Extra: crewai
Requires-Dist: crewai>=0.80; extra == 'crewai'
Provides-Extra: dev
Requires-Dist: aioquic>=1.2; extra == 'dev'
Requires-Dist: grpcio>=1.68; extra == 'dev'
Requires-Dist: hypercorn>=0.17; extra == 'dev'
Requires-Dist: protobuf>=5.29; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Provides-Extra: grpc
Requires-Dist: grpcio>=1.68; extra == 'grpc'
Requires-Dist: protobuf>=5.29; extra == 'grpc'
Provides-Extra: langchain
Requires-Dist: langchain-core>=0.3; extra == 'langchain'
Provides-Extra: mcp
Requires-Dist: fastmcp>=3.0; extra == 'mcp'
Provides-Extra: node
Requires-Dist: hypercorn>=0.17; extra == 'node'
Provides-Extra: quic
Requires-Dist: aioquic>=1.2; extra == 'quic'
Description-Content-Type: text/markdown

# TrustChain Python SDK

[![PyPI](https://img.shields.io/pypi/v/trustchain-py.svg)](https://pypi.org/project/trustchain-py/)
[![CI](https://github.com/viftode4/trustchain-py/actions/workflows/ci.yml/badge.svg)](https://github.com/viftode4/trustchain-py/actions)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)

**Python SDK for TrustChain — decentralized trust primitives for AI agents.**

`trustchain-py` is the Python face of the TrustChain trust primitive. At its simplest it is a one-liner (`trustchain.init()`) that downloads and starts the Rust sidecar binary, sets `HTTP_PROXY`, and makes every outbound HTTP call trust-protected. For agents that need full programmatic control it exposes the complete protocol: Ed25519 identities, half-block creation and validation, chain storage, trust computation, NetFlow Sybil resistance, QUIC transport, and gRPC. 290 tests.

## Installation

```bash
pip install trustchain-py
```

### Optional extras

```bash
pip install trustchain-py[quic]   # QUIC P2P transport (aioquic)
pip install trustchain-py[grpc]   # gRPC client/server (grpcio + protobuf)
pip install trustchain-py[node]   # full Python node (hypercorn ASGI)
pip install trustchain-py[all]    # everything above
```

Requires Python 3.11+.

## Quick Start

### Zero-config sidecar (recommended)

```python
import trustchain

# Downloads the Rust binary if needed, starts the sidecar, sets HTTP_PROXY.
# All outbound HTTP calls from this process are now trust-protected.
trustchain.init()
```

That is the entire integration for most agents. The sidecar runs on port 8203 as a transparent HTTP proxy; agents never call TrustChain directly.

The sidecar binary (`trustchain-node`) must be available. Install it separately:

```bash
# From crates.io
cargo install trustchain-node

# Or place the binary at ~/.trustchain/bin/trustchain-node
# Or download from https://github.com/levvlad/trustchain/releases
```

### Programmatic protocol usage

```python
import trustchain

# Create identities
alice = trustchain.Identity()
bob = trustchain.Identity()

# Create a protocol instance backed by an in-memory block store
store = trustchain.MemoryBlockStore()
protocol = trustchain.TrustChainProtocol(alice, store)

# Alice proposes an interaction with Bob
proposal = protocol.create_proposal(
    bob.pubkey_hex,
    {"type": "service_call", "outcome": "completed"},
)

# Bob validates the proposal and creates the counter-signed agreement
bob_protocol = trustchain.TrustChainProtocol(bob, store)
agreement = bob_protocol.create_agreement(proposal)

print(f"Block pair recorded: seq={proposal.sequence_number}")
```

### Trust scoring

```python
from trustchain.trust import TrustEngine
from trustchain.blockstore import SqliteBlockStore

store = SqliteBlockStore("agent.db")
engine = TrustEngine(store)

score = engine.compute_trust(peer_pubkey)
print(f"Trust score for peer: {score:.3f}")  # 0.0 to 1.0
```

### SQLite-backed node

```python
import asyncio
from trustchain.api import TrustChainNode

async def main():
    node = TrustChainNode(db_path="agent.db")
    await node.start()          # serves HTTP REST on :8202
    await node.run_forever()

asyncio.run(main())
```

## Modules

| Module | Description |
|--------|-------------|
| `trustchain.identity` | Ed25519 keypair generation, loading, and serialization |
| `trustchain.halfblock` | `HalfBlock` data structure, signing, and validation |
| `trustchain.blockstore` | `MemoryBlockStore` and `SqliteBlockStore` |
| `trustchain.protocol` | `TrustChainProtocol` — proposal/agreement state machine |
| `trustchain.trust` | `TrustEngine` — weighted three-component trust scoring |
| `trustchain.netflow` | NetFlow Sybil resistance (max-flow from seed nodes) |
| `trustchain.consensus` | CHECO checkpoint consensus |
| `trustchain.chain` | Chain operations, validation, and gap detection |
| `trustchain.crawler` | Network graph crawler and DAG view builder |
| `trustchain.transport` | QUIC P2P, HTTP connection pooling, peer discovery |
| `trustchain.grpc` | gRPC client and server (requires `[grpc]` extra) |
| `trustchain.api` | FastAPI HTTP node (full REST API, same endpoints as Rust) |
| `trustchain.sidecar` | Rust binary manager — download, start, health-check, proxy setup |
| `trustchain.delegation` | Identity delegation, succession, and revocation |

## Trust Score Components

`TrustEngine.compute_trust(pubkey)` returns a weighted score from three components:

| Component | Weight | What it measures |
|-----------|--------|-----------------|
| **Chain Integrity** | 30% | Hash links valid, no sequence gaps, Ed25519 signatures verify |
| **NetFlow** | 40% | Max-flow from seed nodes — primary Sybil resistance |
| **Statistical** | 30% | Volume, completion rate, counterparty diversity, account age, entropy |

## Architecture

```
Your Python agent
      │
      ├── trustchain.init()          sets HTTP_PROXY → Rust sidecar (:8203)
      │                              (transparent, zero-code-change integration)
      │
      └── trustchain.TrustChainProtocol  (full programmatic control)
              │
              ├── Identity           Ed25519 keypair
              ├── BlockStore         MemoryBlockStore / SqliteBlockStore
              ├── TrustEngine        NetFlow + chain integrity + statistical
              └── Transport          QUIC P2P / HTTP REST / gRPC
```

The Python SDK's `trustchain.api.TrustChainNode` implements the same HTTP REST API as the Rust binary. The Rust binary is recommended for production deployments; the Python node is useful for testing and environments where the binary is unavailable.

> **Note**: The sidecar delegation API endpoints (`/trustchain/delegate` etc.) are implemented in the Python SDK's `TrustChainNode` only. The Rust sidecar does not expose these endpoints — use the standard `/delegate` and `/revoke` REST endpoints on the Rust node's HTTP API instead.

## Development

```bash
git clone https://github.com/levvlad/trustchain-py.git
cd trustchain-py
pip install -e ".[dev]"
pytest tests/ -v
```

## Related Projects

- [trustchain](https://github.com/levvlad/trustchain) — Rust node: production sidecar binary, core crates, QUIC P2P, MCP server
- [trustchain-agent-os](https://github.com/levvlad/trustchain-agent-os) — Agent framework adapters (LangGraph, CrewAI, AutoGen, OpenAI Agents, Google ADK, ElizaOS)

## License

MIT
