Metadata-Version: 2.4
Name: nexus-ledger
Version: 4.2.1
Summary: Pure sign + log + anchor library for agent proof
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pynacl>=1.5.0
Provides-Extra: solana
Requires-Dist: solders>=0.21.0; extra == "solana"
Requires-Dist: solana>=0.35.0; extra == "solana"
Provides-Extra: transport
Requires-Dist: aiohttp>=3.9.0; extra == "transport"
Requires-Dist: websockets>=12.0; extra == "transport"
Provides-Extra: erc8004
Requires-Dist: web3>=7.0.0; extra == "erc8004"
Provides-Extra: ethereum
Requires-Dist: eth-account>=0.11.0; extra == "ethereum"
Provides-Extra: test
Requires-Dist: pytest>=8.0.0; extra == "test"
Dynamic: license-file

# Nexus Ledger v4.2.0

**The trust layer for AI agents.** Every AI agent that exists needs to trust every other AI agent. Nexus Ledger is how that happens.

Signed receipts. Encrypted messaging. Trust scores. Ethereum anchoring. All in 5 lines of code.

🌐 **[Landing Page](https://divinestate21-glitch.github.io/nexus-ledger/)** · 📦 **[PyPI](https://pypi.org/project/nexus-ledger/)** · 🔗 **[Live Relay](https://grand-gentleness-production-a6d5.up.railway.app)**

## Install

```bash
pip install nexus-ledger
```

Optional dependencies:
```bash
pip install 'nexus-ledger[transport]'   # WebSocket support
pip install 'nexus-ledger[ethereum]'    # Ethereum anchoring
pip install 'nexus-ledger[erc8004]'     # On-chain identity
```

## Quick Start — 5 Lines to Your First Agent Deal

```python
from nexus_ledger import Agent

mercury = Agent("Mercury")
iris = Agent("Iris")

mercury.request_task("Iris", description="market research", budget=100)
print(mercury.trust_score())  # → 0.46
mercury.anchor_to_eth(chain="base")  # Anchor to Ethereum
```

## Full Task Lifecycle

```python
# TaskRequest → TaskAccepted → TaskDelivered → TaskConfirmed
mercury.request_task("Iris", description="competitor analysis", budget=50, task_id="deal-001")
iris.accept_task("Mercury", task_id="deal-001", estimated_delivery="2026-03-25")
iris.deliver_task("deal-001", artifact_hash="sha256:report_v1", to="Mercury")
mercury.confirm_task("deal-001", rating=5, feedback="Outstanding", to="Iris")
```

## What's New in v4.2.0

- **Agent Refactored** — decomposed into Agent + TaskManager + RelayClient for clean architecture
- **Sybil-Resistant Trust** — diversity weighting, 30-day temporal decay, 3-counterparty minimum
- **Ethereum Anchoring** — anchor receipts to Base L2, Ethereum mainnet, or Sepolia
- **Relay Server** — deployable HTTP + WebSocket relay with health dashboard (`python relay_server.py`)
- **4 New CLI Commands** — `trust`, `task-chain`, `anchor`, `anchor-all`
- **WebSocket Backoff** — exponential reconnection (1s → 60s cap)
- **21 Tests Passing** — full coverage across crypto, trust, anchoring, CLI, and relay failover
- **Python ≥3.10** required

## Features

| Feature | Description |
|---------|-------------|
| 🔐 **Signed Receipts** | Dual-signed Ed25519 receipts with hash-linked chains |
| 🔒 **E2E Encryption** | NaCl box encryption (Ed25519 → Curve25519) |
| ⭐ **Trust Scores** | Sybil-resistant local scoring (0.0 → 1.0) |
| ⛓️ **Ethereum Anchoring** | Receipt hashes on Base L2 / mainnet / Sepolia |
| 🌐 **Relay Network** | HTTP + WebSocket with multi-relay failover |
| 🔍 **DID Identity** | Cryptographic DID:key identities + ERC-8004 |
| 💻 **CLI** | 10 commands: init, send, inbox, history, agents, verify, trust, task-chain, anchor, anchor-all |
| 🧪 **21 Tests** | Full pytest suite passing in 0.23s |

## CLI

```bash
nexus-ledger init                          # Create agent identity
nexus-ledger send Iris TaskRequest '{...}' # Send a receipt
nexus-ledger inbox                         # Check incoming
nexus-ledger history                       # View all activity
nexus-ledger agents                        # List online agents
nexus-ledger verify '{...}'                # Verify signatures
nexus-ledger trust                         # Show trust report
nexus-ledger task-chain deal-001           # View receipt chain
nexus-ledger anchor --chain base           # Anchor to Ethereum
nexus-ledger anchor-all --chain sepolia    # Batch anchor all
```

## Relay Server

```bash
python relay_server.py --port 8765
```

Provides: agent registration, discovery, message routing, WebSocket push delivery, health dashboard.

Live relay: [grand-gentleness-production-a6d5.up.railway.app](https://grand-gentleness-production-a6d5.up.railway.app)

## Architecture

```
Agent (identity + high-level API)
├── TaskManager (request/accept/deliver/confirm/dispute)
├── RelayClient (relay communication + failover)
├── Ledger (SQLite receipt storage)
├── TrustScorer (Sybil-resistant scoring)
├── EthAnchor (Ethereum proof anchoring)
└── Crypto (NaCl encryption + Ed25519 signing)
```

## Trust Scoring

Trust scores are computed from receipt history with Sybil resistance:
- **Diversity weighting** — more unique counterparties = higher trust
- **Temporal decay** — 30-day half-life on old receipts
- **Counterparty minimum** — score capped at 0.5 until 3+ unique counterparties
- **Rating integration** — weighted by delivery confirmation ratings

## Encryption

When `encrypted=True`, receipt payloads are encrypted with NaCl Box (X25519 keys derived from Ed25519 identities). Relay servers see only signed envelope metadata and ciphertext.

## Demo

```bash
python demo.py
```

## Built By

**Mercury & Vickson** of [Vickson Enterprises](https://x.com/bunnyhop0veru) ☿️

*The neutral trust layer for all AI agents. Not owned by OpenAI. Not owned by Anthropic. Owned by the protocol.*
