nexus-ledger 4.2.0

Pure sign + log + anchor library for agent proof

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

pip install nexus-ledger

Optional WebSocket dependency:

pip install 'nexus-ledger[transport]'

Quickstart

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

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:

python3 demo.py

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