# Nexus Ledger v4.1.0

Nexus Ledger is an agent-to-agent trust layer with signed, linked receipts, relay messaging, and local auditability.

## What Is New In v4.0

- Multiple relay support with transparent failover (`primary -> fallback`) via `RelayManager`.
- Live receipt transport with WebSocket-first delivery and HTTP polling fallback.
- Typed task receipt vocabulary:
  - `TaskRequest(task_id, description, budget, deadline)`
  - `TaskAccepted(task_id, estimated_delivery)`
  - `TaskDelivered(task_id, artifact_hash, artifact_url)`
  - `TaskConfirmed(task_id, rating, feedback)`
  - `TaskDisputed(task_id, reason)`
- Receipt chains using `parent_receipt_hash` for full task lineage.
- End-to-end encrypted receipts with NaCl box (X25519 keys derived from Ed25519 identities).
- New CLI (`nexus-ledger ...`) for init/send/inbox/history/agents/verify.
- Local trust scoring (`0.0 - 1.0`) from receipt history.

## Install

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

Optional WebSocket dependency:

```bash
pip install 'nexus-ledger[transport]'
```

## Quickstart

```python
from nexus_ledger import Agent

mercury = Agent("Mercury", relays=["http://104.236.251.94:8765", "http://localhost:8765"])
iris = Agent("Iris")

request = mercury.request_task("Iris", description="market research", budget=100)
iris.check_inbox()  # Iris receives + countersigns
mercury.check_inbox()  # Mercury receives final countersigned receipt

chain = mercury.get_task_chain(request["data"]["task_id"])
print(len(chain))
```

## API Highlights

- `Agent(name, relays=[...])`
- `agent.send(event_type, data, to="Iris", encrypted=True)`
- `agent.on_receipt(callback)`
- `agent.request_task(...)`
- `agent.accept_task(...)`
- `agent.deliver_task(...)`
- `agent.confirm_task(...)`
- `agent.dispute_task(...)`
- `agent.get_task_chain(task_id)`
- `agent.trust_score()`
- `agent.get_trust_report(agent_pubkey)`

## CLI

```bash
nexus-ledger init --name Mercury
nexus-ledger send Iris TaskRequest '{"task_id":"t1","description":"research","budget":100,"deadline":"2026-03-22T12:00:00+00:00"}'
nexus-ledger inbox
nexus-ledger history
nexus-ledger agents
nexus-ledger verify '{"timestamp":"...","event_type":"TaskConfirmed",...}'
```

Global CLI options:

- `--name` (default `Mercury`)
- `--keys-dir` (default `keys`)
- `--db-path` (default `nexus.db`)
- `--relays` (default `http://104.236.251.94:8765 http://localhost:8765`)

## Encryption Model

When `encrypted=True` is used, receipt payloads are encrypted with NaCl `Box` so relay servers see only the signed envelope metadata and ciphertext. Receivers decrypt automatically before verification/countersigning.

## Demo

Run:

```bash
python3 demo.py
```

The demo shows multi-relay config, live callback registration, typed task flow, chained receipts, encrypted transport, and trust report output.
