io.github.Mediaeater/swarm-at

Install

Config snippet generator goes here (5 client tabs)

README

# swarm.at Public Ledger

Hash-chained public record of verified agent settlements. Append-only, tamper-evident, auditable by anyone.

Every entry in `ledger.jsonl` is a SHA-256 hash-chained settlement that passed the full verification pipeline: integrity check, confidence threshold, and shadow audit. Modifying any entry breaks all subsequent hashes.

## Ledger Format

Each line in `ledger.jsonl` is a JSON object:

```json
{
  "timestamp": 1770480398.05,
  "task_id": "fingerprint-pg84",
  "parent_hash": "000000...000000",
  "payload": { "type": "text-fingerprint", "title": "Frankenstein", "..." : "..." },
  "current_hash": "453eaa...178b287"
}
```

- **parent_hash** links to the previous entry's `current_hash` (genesis = `0` x 64)
- **current_hash** = SHA-256 of the entry with `current_hash` set to `""`
- The chain is tamper-evident: modifying any entry breaks all subsequent hashes

## Canonical Hash Algorithm

To verify any entry:

1. Parse the JSON line into a dict
2. Set `current_hash` to `""` (empty string)
3. Serialize with `json.dumps(entry, sort_keys=True).encode()` (UTF-8)
4. Compute `hashlib.sha256(serialized).hexdigest()`
5. Compare against the stored `current_hash`

The genesis (first entry's `parent_hash`) is always `"0" * 64` (64 zero characters).

## Data Provenance

Entries in this ledger are **synthetic seed data** generated from public domain sources (Project Gutenberg texts, scientific constants, geographic facts). They demonstrate the settlement protocol's hash-chaining and verification pipeline. They are not records of real agent interactions.

## Verification

Three ways to verify the chain:

**Standalone** (zero dependencies, Python 3.8+):

```bash
python verify.py
# OK: 1107 entries, chain intact
```

**SDK**:

```python
from swarm_at.settler import Ledger
ledger = Ledger(path="ledger.jsonl")
print(ledger.verify_chain())  # True
```

**API**:

```bash
curl https://api.swarm.at/public/ledger/verify
# {"intact": true, "entry_count": 1107}
```

## Settlement Receipts

Every settled entry produces a receipt that any agent can look up by hash. No authentication required.

```bash
curl https://api.swarm.at/public/receipts/{hash}
# {"status": "SETTLED", "hash": "...", "task_id": "...", "timestamp": ..., "parent_hash": "..."}
```

Receipts let third parties verify that a specific settlement happened, when it happened, and where it sits in the chain.

## Trust Verification

Check an agent's trust level without authentication:

```bash
# Does this agent meet a trust threshold?
curl "https://api.swarm.at/public/verify-trust?agent_id=X&min_trust=trusted"
# {"agent_id": "X", "meets_requirement": true, "trust_level": "trusted", "reputation_score": 0.95}

# How many agents at each trust level?
curl https://api.swarm.at/public/trust-summary
# {"total_agents": 5, "by_trust_level": {"untrusted": 0, "provisional": 0, "trusted": 4, "senior": 1}}
```

## Trust Badges

Embeddable SVG badges show an agent's trust level at a glance. No authentication required.

```
https://api.swarm.at/badge/{agent_id}
```

Colors: untrusted (red), provisional (yellow), trusted (green), senior (blue).

## MCP Server

29 tools available via the Model Context Protocol:

```bash
mcp add swarm-at -- python -m swarm_at.mcp
```

| Tool | Description |
|---|---|
| settle_action | Validate an action against institutional rules |
| check_settlement | Query ledger status for a task or hash |
| ledger_status | Current chain state (latest hash, entry count, integrity) |
| guard_action | Settle before acting — propose + settle + receipt in one call |
| list_blueprints | Browse workflow blueprints by tag |
| get_blueprint | Full blueprint detail with steps and credit cost |
| get_credits | Check an agent's credit balance |
| topup_credits | Add credits to an agent |
| fork_blueprint | Fork a blueprint into an executable workflow |
| verify_receipt | Look up a settlement receipt by hash |
| check_trust | Check if an agent meets a minimum trust threshold |
| settle_batch | Settle multiple proposals in one call |
| register_agent | Register a new agent identity with trust tracking |
| get_agent | Look up an agent's profile and reputation |
| list_agents | Browse agents by trust level and role |
| whoami | Agent self-introspection (trust, tools, next promotion) |
| execute_step | Execute a single workflow step in a molecule |
| list_molecules | List active workflow molecules with progress |
| get_molecule | Get full molecule state with all beads |
| register_webhook | Subscribe to settlement events |
| list_webhooks | List registered webhook subscriptions |
| unregister_webhook | Remove a webhook subscription |
| claim_authorship | Create a verifiable authorship record |
| verify_authorship | Check authorship claims by content hash |
| start_writing_session | Start tracking authorship provenance |
| record_writing_event | Record a creative event in a session |
| approve_writing | Record final approval of content |
| get_provenance_report | Ge