Capacity Attest

capacity-attest

*Nederlandse versie / Dutch version: README.nl.md*

MCP server for delivery attestations in x402 capacity trading between AI agents.

Status: MVP, published on npm (npm install capacity-attest) and in the official MCP registry (io.github.holistis/capacity-attest).

Independently checked, not just claimed

Every claim about this project below is clickable and independently verifiable, not something you have to take our word for.

Kept honestly separate from the table above, because this is not third-party review: before 0.6.0 (the first version that actually writes to the blockchain), we ran our own adversarial security review. Nine findings, all fixed: seven closed by a dedicated regression test, one verified by a packaging check (npm pack --dry-run) rather than a unit test, and one a documentation-only fix. Not an independent audit by an outside party. Full, checkable report: docs/SECURITY-REVIEW-2026-09-11.md.

Why this exists

When an AI agent pays via the x402 protocol for capacity (GPU hours, storage, API/inference credits, bandwidth) from another agent or service, there is no proof after payment that what was promised was actually delivered. The buying agent knows it firsthand (it saw the output, or didn't), but that knowledge is lost the moment the session ends. The next agent looking to do business with the same seller starts blind again.

capacity-attest closes that specific gap: after settlement, the paying agent leaves behind a cryptographically signed, factual claim (delivered: yes/no/partial + a hash of the evidence). Other agents can pull that history before they do business with that same seller.

No judgment. No reputation score. No "verdict" — just a signed receipt-plus-claim, the same way you'd get a delivery slip for a physical shipment.

What this deliberately is NOT

This is deliberately and permanently not:

• Not a reputation score or rating. get_delivery_history returns the raw, chronological list of claims, no average, no percentage, no "trust score". Summarizing it into a single number is implicitly a judgment, and that was explicitly rejected during this project's design phase.
• Not a financial product. No interest, no time-discounting on payments, no yield on a ledger balance (there is no balance, this is not an escrow), no lending, no collateral, no invoice financing/factoring. assetType is a closed enum of capacity kinds (gpu-hours, storage, api-credits, bandwidth) and deliberately contains nothing resembling a financial instrument.
• Not its own token or coin. Payments run through x402/USDC as usual; this project only records the *receipt* of a settlement that already happened elsewhere.
• Not credit extension. A claim is only created after a completed payment. This project finances nothing; it documents an already-completed ijara (rental/service) transaction.
• Not its own identity, authority, or dispute-resolution layer. externalRefs (see below) is purely a citation to someone else's system (ERC-8004, AP2, Legal Context Protocol, ...). This project never resolves, verifies, or judges that reference itself. See DECISIONS.md D-007 through D-013 for why this deliberately did not become its own protocol.

This is a deliberate, formally reviewed design choice, not an incidental scope limit. See the guardrails section in the project brief if you're considering adding something here: when in doubt whether a field/function brushes against this line, leave it out.

Deliberately deferred features (anchoring, interim status, formal conformance vectors), including the exact condition under which we'd build them anyway: see DECISIONS.md.

Further reading: nine ways to fake a delivery claim, and why none of them fully worked, the public write-up of D-014/D-018 above.

How it works

1. record_delivery

The paying agent (the buyer) calls this after an x402 settlement, once it's known whether what was promised arrived. The claim contains:

The server first validates the schema, then whether claimId really is the hash of the content, then whether signature really recovers to buyerAddress. Only then is the claim appended to the append-only ledger (data/claims.jsonl). An invalid signature or a claim that's already stored (same claimId) is rejected.

2. get_delivery_history

Given a sellerAddress, this returns all known claims against that seller on this installation, chronologically (oldest first). Purely factual, no summarized number. A buying agent calls this before paying, to see the raw delivery history of a prospective seller and judge it themselves.

The response includes sellerAddress, count and claims, plus scope (always "local-ledger") and note: a fixed, factual text explaining that this result only reflects the local ledger of this installation. An empty or short history doesn't mean the seller has a clean record — it can also mean no claims have been recorded here yet.

Since 0.4.0 the response also includes completeness: an analysis of the per-buyer chains (priorClaimId) within exactly this result set. If a claim shown here refers back to a claim that is NOT in the result set, that shows up in possibleOmissions. That's a concrete, checkable signal that the host might be hiding a middle claim, rather than a vague suspicion.

Note, and this is the most important point: that completeness field is computed by the same server that returns the claims. If you don't trust that server, don't trust that field either — a dishonest host can just set "everything's complete" regardless. The real guarantee lives in the signed priorClaimId inside the claims themselves, which a host cannot forge or remove. So recompute the check yourself over the claims you got back:

// recompute-completeness.mjs

import { verifyClaim } from "capacity-attest/dist/signing.js"; import { analyzeCompleteness } from "capacity-attest/dist/completeness.js";

// claims = the array from the get_delivery_history response. const allSigned = claims.every((c) => ve