Metadata-Version: 2.4
Name: mantle-agent-attest
Version: 0.1.0
Summary: Verifiable agent-run attestations on the Mantle EVM L2. Hash an agent's JSONL audit log into a Merkle root, sign it, post it on-chain, and prove a single run later.
Project-URL: Homepage, https://github.com/MukundaKatta/mantle-agent-attest
Project-URL: Source, https://github.com/MukundaKatta/mantle-agent-attest
Project-URL: Issues, https://github.com/MukundaKatta/mantle-agent-attest/issues
Author-email: Mukunda Rao Katta <mukunda.vjcs6@gmail.com>
License: MIT
License-File: LICENSE
Keywords: agents,ai,attestation,audit,evm,mantle,merkle,turing-test,verifiable-agents
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Requires-Dist: eth-account>=0.11
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.4; extra == 'dev'
Provides-Extra: onchain
Requires-Dist: web3>=6.20; extra == 'onchain'
Description-Content-Type: text/markdown

# mantle-agent-attest

Verifiable AI-agent-run attestations on the [Mantle](https://www.mantle.xyz/)
EVM L2. Built for the
[Mantle Turing Test Phase 2](https://dorahacks.io/) hackathon on DoraHacks.

## The pitch

AI agents are increasingly running unattended (scraping, payments,
trades). The Turing-test question becomes: **how do you prove a given
log came from a specific agent and wasn't doctored?**

`mantle-agent-attest` does this in three steps:

1. **Hash** the agent's JSONL audit log (e.g. from
   [birddog](https://github.com/MukundaKatta/birddog) or
   [agentleash](https://github.com/MukundaKatta/agentleash)) into a
   Merkle root.
2. **Sign** the root with the agent's EVM key (personal-sign).
3. **Post** the `(runId, root, signature)` triple on-chain to a tiny
   `AgentAttestationRegistry` contract on Mantle.

Anyone can later verify:
- *"this single event was part of run X"* (Merkle inclusion proof)
- *"run X was signed by agent Y"* (ecrecover on-chain)

## Install

```bash
pip install mantle-agent-attest                # core (Merkle + sign)
pip install "mantle-agent-attest[onchain]"     # + web3 for on-chain submit/read
```

Python 3.10+.

## Quickstart (offline)

```python
import json
from mantle_agent_attest import build_attestation, verify_inclusion

# any JSONL agent log works (birddog, agentleash, your own)
events = [json.loads(line) for line in open("runs/watchdog.jsonl")]

att = build_attestation(
    events,
    run_id="scrape-2026-05-20",
    signer_key="0x...",   # your agent's EVM private key
)
print(att.root_hex, att.signature, att.signer)

# prove that one event was part of the run:
target = events[3]
proof  = att.proof_for(3)
assert verify_inclusion(target, proof, att.root)
```

## Publish on-chain (Mantle Sepolia)

```bash
# 1. Deploy the registry once (forge / hardhat / foundry — see contracts/README.md)
forge create \
  --rpc-url https://rpc.sepolia.mantle.xyz \
  --private-key $YOUR_KEY \
  contracts/AgentAttestationRegistry.sol:AgentAttestationRegistry

# 2. Use the deployed address to attest a run
export MANTLE_REGISTRY=0xDeployedRegistryAddress
export AGENT_KEY=0xYourAgentPrivateKey
python examples/submit_attestation.py runs/watchdog.jsonl --run-id scrape-2026-05-20
```

Mantle Sepolia testnet has free gas via the public faucet.

## Why Mantle

- Cheap, fast EVM L2 — attestations cost cents, not dollars
- Standard `ecrecover` on personal-sign, so any wallet can verify
- The contract is ~50 lines of Solidity; no admin, no upgrade path

## Companion libraries

`mantle-agent-attest` is the on-chain verification layer for the
[@mukundakatta agent-stack](https://github.com/MukundaKatta):

- [birddog](https://github.com/MukundaKatta/birddog) — audited Bright Data egress (produces the JSONL we hash)
- [agentleash](https://github.com/MukundaKatta/agentleash) — USD/call budget + tool-arg gate (also JSONL)
- [recruitertriage](https://github.com/MukundaKatta/recruitertriage) — small-LM recruiter inbox triage

You can attest any of these audit logs without code changes.

## Security notes

- The deployed registry is permissionless. Anyone can post any `(runId,
  root, sig)`, but `signer` is recovered from the sig, so impersonation
  isn't possible.
- `runId` is locked on first submit; pick collision-resistant IDs.
- `block.timestamp` on `ts` is approximate (~12 sec on Mantle).
- This library is alpha. Don't use the example key on mainnet.

## License

MIT
