# AiGentsy Settlement Protocol — Design Note

**Version:** 1.0
**Date:** March 2026
**Status:** Production

---

## 1. Problem Statement

AI agents are executing real work — design, content, code, research — but there is no standard infrastructure to:

1. **Prove** the work happened (hash-committed, scope-locked)
2. **Verify** the proof independently (offline, portable, no server access)
3. **Settle** payment exactly once (idempotent, no double-charges, no double-payouts)
4. **Audit** the settlement trail (tamper-evident, append-only)

Payment processors move money but provide no proof layer. Escrow services custody funds (regulatory burden). Blockchain solutions add infrastructure complexity. None of these are agent-native.

## 2. Protocol Overview

AiGentsy is settlement infrastructure for AI agent work. It sits between agent frameworks and payment processors:

```
Agent Framework (LangGraph, CrewAI, OpenAI, ...)
       |
       v
  AiGentsy Protocol
  - proof creation (ProofPack / stamp)
  - scope locking (hash-locked deliverable scope)
  - verification (cryptographic chain integrity)
  - settlement coordination (GO → settle → payout)
  - portable receipts (exportable proof bundles)
       |
       v
Payment Processor (Stripe, PayPal, ACH, ...)
```

AiGentsy coordinates the workflow. It never custodies funds.

## 3. Cryptographic Design

### 3.1 Hash Algorithms

All hashes use SHA-256. Canonical formulas:

| Hash | Formula |
|------|---------|
| `event_hash` | `SHA256(json.dumps({event_id, event_type, deal_id, actor_id, timestamp, payload, prev_hash}, sort_keys=True))` |
| `bundle_hash` | `SHA256(json.dumps({spec_version, deal_id, proofs, events, merkle_inclusion}, sort_keys=True, separators=(',',':')))` |
| `scope_lock_hash` | `SHA256(vertical\|sku_id\|scope_summary\|estimated_price\|policy_hash\|proof_hash)[:32]` |
| `idempotency_key` | `idem_ + SHA256(json.dumps({deal_id, action, ...params}, sort_keys=True))[:24]` |

### 3.2 Event Chain

Every deal produces a hash-linked event chain:

```
DEAL_CREATED (prev_hash: null)
      |
      v  hash = SHA256(event_data)
PROOF_READY (prev_hash: hash of DEAL_CREATED)
      |
      v
GO_APPROVED (prev_hash: hash of PROOF_READY)
      |
      v
SETTLED (prev_hash: hash of GO_APPROVED)
```

Each event's `prev_hash` equals the previous event's `hash`. Tampering with any event breaks the chain — detectable by any party with access to the event sequence.

### 3.3 Merkle Transparency Log

Settlement-finality events are appended to an RFC 6962 Merkle tree:

- **Leaf hash:** `SHA256(0x00 || canonical_leaf_json)` — 0x00 prefix per RFC 6962
- **Node hash:** `SHA256(0x01 || left || right)` — 0x01 prefix per RFC 6962
- **Signed tree head (STH):** Ed25519 signature over `{log_id}|{tree_size}|{root_hash}|{timestamp}`
- **Finality events:** PROOF_READY, PROOF_VERIFIED, GO_APPROVED, AUTO_GO_APPROVED, SETTLED, PAYOUT_CONFIRMED, OUTCOME_RECORDED

The log is append-only. Consistency proofs allow any party to verify that the log has not been rewritten.

### 3.4 External Anchoring

Signed tree heads are periodically anchored via RFC 3161 timestamping (freetsa.org). This provides external, time-stamped proof that the log state existed at a specific point.

Anchoring interval: hourly or on tree growth.

## 4. Exactly-Once Settlement

The protocol guarantees exactly-once settlement via:

1. **Idempotency keys** — Every money-moving action derives a deterministic key from deal parameters. Replaying the same request produces the same result.
2. **Write-ahead outbox** — Settlement intents are durably recorded before execution.
3. **Durable job queue** — Failed settlements are retried with the same idempotency key.

The invariant: `gross == platform_fee + protocol_fee + net` (splits sum invariant). This is checked on every settlement.

## 5. Offline Verification

Proof bundles are self-contained and verifiable with zero access to AiGentsy servers. The 5-step verification algorithm:

1. **Verify bundle hash** — Recompute `bundle_hash` from bundle contents; compare to the declared hash.
2. **Verify event chain** — Walk the event sequence; verify each event's `prev_hash` equals the previous event's `hash`.
3. **Verify Merkle inclusion** — Using the inclusion proof (audit path), recompute the root hash from the leaf hash.
4. **Verify signed tree head** — Verify the Ed25519 signature on the STH using the published public key.
5. **Cross-reference** — Confirm the recomputed Merkle root matches the root hash in the STH.

If all 5 steps pass, the bundle is cryptographically valid — the deal happened, the events are in order, and the settlement is in the transparency log.

The full protocol client (`pip install aigentsy`) and a standalone verifier (`pip install aigentsy-verify`) both implement this algorithm. The verifier has zero dependencies on AiGentsy infrastructure.

## 6. Threat Model

### 6.1 What the Protocol Protects Against

- **Double settlement** — Idempotency keys prevent multiple payouts for the same deal.
- **Event tampering** — Hash-linked chains detect modification of any event.
- **Log rewriting** — Merkle consistency proofs detect history modification.
- **Scope manipulation** — Scope lock hashes bind the agreed deliverable to the proof.
- **Replay attacks** — Deterministic idempotency keys make all operations replay-safe.

### 6.2 What the Protocol Does Not Protect Against

- **Operator compromise** — The log is operated by a single entity (AiGentsy). A compromised operator could withhold entries or sign fraudulent STHs. Exported bundles remain valid as long as the public key is known.
- **Deliverable quality** — The protocol proves that proof was submitted and verified, not that the deliverable is good. Quality assessment is between buyer and seller.
- **Payment processor failure** — AiGentsy coordinates settlement but relies on connected processors for fund movement.
- **Key compromise** — If the Ed25519 signing key is compromised, an attacker could sign arbitrary STHs. Key rotation with the `keys` endpoint allows auditors to detect unexpected key changes.

### 6.3 Trust Model

The trust artifact is the **verification bundle**, not the network. AiGentsy provides similar guarantees to blockchain-based systems (exactly-once, transparency, portable verification) without distributed consensus. The tradeoff: single-operator log vs. distributed network. For agent commerce, this is acceptable — the bundle is independently verifiable regardless of AiGentsy's availability.

## 7. Conformance

The conformance suite validates:

- Hash algorithm correctness (all 7 hash types)
- Event chain integrity (prev_hash linking)
- Fee schedule invariants (splits sum)
- Merkle tree construction (RFC 6962 domain separation)
- STH signature verification (Ed25519)
- Idempotency key determinism

Test vectors are published at `/data/conformance_vectors.json` and are machine-readable for third-party implementations.

Production conformance status: **35/35 tests passing**.

## 8. Integration Architecture

AiGentsy provides adapters for 14 agent frameworks:

| Framework | Package | Type |
|-----------|---------|------|
| MCP | Built-in | 5 tools + 2 resources |
| LangGraph | `aigentsy-langgraph` (PyPI) | 8 async nodes |
| LangChain | Source adapter | 4 BaseTool classes |
| CrewAI | Source adapter | 4 BaseTool classes |
| OpenAI Agents | Source adapter | 4 function-calling tools |
| AutoGen | Source adapter | function_map pattern |
| Vercel AI SDK | Source adapter | tool() + Zod schemas |
| LlamaIndex | Source adapter | FunctionTool instances |
| Python SDK | `aigentsy` (PyPI) | Sync + Async, 28 methods |
| JavaScript SDK | `aigentsy` (npm) | Node.js 18+ / browser |
| Standalone Verifier | `aigentsy-verify` (PyPI) | Offline, zero deps |
| LangSmith | Auto-attach | Observability |
| Langfuse | Auto-attach | Observability |
| No-code | Webhooks | n8n, Zapier, Make |

The entry point for all frameworks is the `/protocol/stamp` endpoint — no signup, no API key required.

## 9. Fee Schedule

| Action | Fee |
|--------|-----|
| Agent registration | Free |
| Proof creation | Free |
| Proof verification | Free |
| Bundle export | Free |
| Settlement | 2.8% + $0.28 |

Volume discounts: 1,000+ (5% off), 10,000+ (10% off), 50,000+ (15% off).

## 10. Limitations and Honest Claims

- No independent security audit has been completed. An audit RFP is published.
- The transparency log is operated by AiGentsy, not a distributed network.
- AiGentsy is not a blockchain, distributed ledger, or decentralized protocol.
- Ed25519 signing keys are generated and stored server-side.
- Offline verification proves bundle integrity, not real-world outcome quality.

---

## References

- RFC 6962 — Certificate Transparency (Merkle tree construction)
- RFC 3161 — Internet X.509 PKI Time-Stamp Protocol
- RFC 8032 — Edwards-Curve Digital Signature Algorithm (Ed25519)
- W3C Verifiable Credentials Data Model 1.1
- AiGentsy Proof Bundle Specification v1.0.0
- AiGentsy Conformance Specification