Skip to content

Commit a3bd70e

Browse files
omoshola-oomoshola-o
committed
docs: update README with streamlined protocol description
1 parent 959f57a commit a3bd70e

1 file changed

Lines changed: 33 additions & 191 deletions

File tree

‎README.md‎

Lines changed: 33 additions & 191 deletions
Original file line numberDiff line numberDiff line change
@@ -18,13 +18,11 @@ AI agents can think, reason, code, search, and orchestrate. But when two agents
1818

1919
No standard way to negotiate a price. No way to escrow funds against a conditional outcome. No way to split payment across five agents that contributed to one result. No way to prove, months later, exactly why a settlement resolved the way it did.
2020

21-
Stripe and OpenAI built [ACP](https://github.com/agentic-commerce-protocol/agentic-commerce-protocol) for agent-assisted shopping. Google built [AP2](https://github.com/google-agentic-commerce/AP2) for human-authorized agent payments. Coinbase built [x402](https://github.com/coinbase/x402) for pay-per-request API access.
21+
Stripe and OpenAI built ACP for agent-assisted shopping. Google built AP2 for human-authorized agent payments. Coinbase built x402 for pay-per-request API access.
2222

2323
All of them assume a human in the loop. A human clicking buy. A human signing a mandate. A human approving a charge.
2424

25-
XAP is built for a different world. A world where agents negotiate with agents, commit capital autonomously, coordinate to produce outcomes, and trust is not assumed — it is proven and replayable.
26-
27-
XAP provides the missing layer: a deterministic, verifiable system for agent-to-agent economic coordination.
25+
XAP is for when there is no human in the loop. When agents negotiate with agents, settle with agents, and prove what happened to humans after the fact.
2826

2927
---
3028

@@ -53,11 +51,11 @@ Nothing outside this sequence is part of XAP. Simplicity is a design constraint.
5351

5452
## What Makes XAP Different
5553

56-
### Verified Discovery — Not Just a Directory
54+
### Verified Discovery
5755

58-
Every other agent discovery mechanism is a claim: "here is what I can do." XAP is the only protocol where discovery includes cryptographic proof of past performance.
56+
Every other agent discovery mechanism is a claim. XAP is the only protocol where discovery includes cryptographic proof of past performance.
5957

60-
The `AgentManifest` carries Verity receipt hashes for prior executions of each capability. Any party can replay those decisions independently using the Verity engine and verify the claimed success rate mathematically. Before a negotiation begins, trust is verified — not assumed.
58+
The `AgentManifest` carries Verity receipt hashes for prior executions of each capability. Any party can replay those decisions independently and verify the claimed success rate mathematically. Before a negotiation begins, trust is verified — not assumed.
6159

6260
```
6361
Every other protocol: discover -> negotiate
@@ -66,51 +64,37 @@ XAP: discover -> verify (Verity receipts) -> decide -> negoti
6664

6765
### Autonomous Negotiation
6866

69-
Other protocols assume a fixed price or a human approval. XAP agents negotiate in real time.
70-
7167
```
7268
OFFER -> COUNTER -> ACCEPT or REJECT
7369
```
7470

75-
Four states. Time-bound offers. Conditional pricing — "pay $X if completed in 2 seconds, $Y if 5 seconds." SLA declared before execution begins. Every state transition signed and permanent.
71+
Four states. Time-bound offers. Conditional pricing. SLA declared before execution. Every state transition signed and permanent.
7672

7773
### Conditional Escrow
7874

79-
XAP does not do payments. It does conditional release.
80-
81-
The primitive is not "Agent A pays Agent B." It is: Agent A locks funds. Agent B performs work. A verifiable condition is checked. Funds release if the condition passes.
82-
83-
Three verification types: deterministic (API returned 200), probabilistic (quality score above threshold), or human-approved (for high-value transactions). Every failure mode has a pre-declared outcome. No money ever sits in limbo.
75+
The primitive is not "Agent A pays Agent B." It is: Agent A locks funds. Agent B performs work. A verifiable condition is checked. Funds release if the condition passes. No money ever sits in limbo.
8476

8577
### Split Settlement
8678

87-
An orchestrator delegates a task to five specialist agents. Each contributes to the result. XAP distributes payment proportionally in one atomic operation.
88-
89-
Agent A did 40% of the value. Agent B did 30%. Agent C did 20%. Agent D did 10% but only scored 0.82 when the SLA guaranteed 0.90, so Agent D gets a pro-rata reduction. The settlement engine handles this automatically. No invoicing. No reconciliation. Nobody else does this.
79+
An orchestrator delegates to five agents. Each contributes. XAP distributes payment proportionally in one atomic operation. Nobody else does this.
9080

9181
### Verity — The Truth Engine
9282

93-
Every settlement decision is captured with its complete reasoning state. Not just what was decided. Why.
94-
95-
Given the same inputs and the same rules, any decision can be replayed to produce the same outcome deterministically. This is how a human reviews what their agent did three months ago and verifies the outcome was correct. This is how a regulator audits autonomous commerce. This is how enterprises govern agent fleets.
96-
97-
Outcomes are explicit:
83+
Every settlement decision is captured with its complete reasoning state. Given the same inputs and rules, any decision can be replayed to produce the same outcome deterministically.
9884

9985
```
10086
SUCCESS -> conditions met, funds released
10187
FAIL -> conditions not met, funds returned
102-
UNKNOWN -> verification is ambiguous, declared resolution path executes
88+
UNKNOWN -> verification ambiguous, declared resolution path executes
10389
DISPUTED -> one party challenges, deterministic arbitration engages
104-
REVERSED -> settlement was final but has been reversed via journal entry
90+
REVERSED -> settlement reversed via journal entry
10591
```
10692

10793
`UNKNOWN` is first-class. The system never pretends to know something it does not.
10894

10995
### Append-Only Reputation
11096

111-
An agent's execution history, settlement outcomes, and dispute record are permanently attached to its identity. You cannot erase a bad track record. Trust is computable rather than assumed.
112-
113-
An agent evaluating a potential counterparty reads its `AgentIdentity` and sees: 14,823 total settlements, 97% success rate, 12 disputes, 100% dispute resolution rate. That data compounds with every transaction and cannot be faked.
97+
An agent's execution history is permanently attached to its identity. Trust is computable rather than assumed.
11498

11599
---
116100

@@ -130,121 +114,20 @@ An agent evaluating a potential counterparty reads its `AgentIdentity` and sees:
130114
+------------------------v-------------------------+
131115
| Verity Truth Engine |
132116
| (open source, Rust, MIT) |
133-
| github.com/agentra-commerce/verity-engine |
134-
+------------------------+-------------------------+
135-
|
136-
+------------------------v-------------------------+
137-
| Settlement Engine |
138-
| (Rust core) |
117+
| github.com/agentra-commerce/verity-engine |
139118
+------------------------+-------------------------+
140119
|
141120
+------------------------v-------------------------+
142-
| Settlement Adapters |
143-
| |
144-
| +----------+ +----------+ +--------------+ |
145-
| | Stripe | | USDC | | Test (dev) | |
146-
| +----------+ +----------+ +--------------+ |
121+
| Settlement Engine + Adapters |
122+
| Stripe | USDC | Test (dev) |
147123
+--------------------------------------------------+
148124
```
149125

150-
XAP is the language. Verity is the truth engine. The settlement engine executes. Adapters move money. Each layer is independent. Replace any adapter without touching the protocol.
151-
152-
---
153-
154-
## Quick Look: Verified Discovery
155-
156-
An agent querying the registry gets back not just a list, but verifiable proof:
157-
158-
```json
159-
{
160-
"manifest_id": "mnf_4a7b2c1d",
161-
"agent_id": "agnt_01JD8K2M...",
162-
"capabilities": [{
163-
"name": "code_review",
164-
"attestation": {
165-
"total_settlements": 847,
166-
"success_rate_bps": 9430,
167-
"receipt_hashes": [
168-
"vrt_a1b2c3d4...",
169-
"vrt_7890abcd..."
170-
],
171-
"verification_endpoint": "https://verity.zexrail.com/receipts"
172-
}
173-
}],
174-
"signature": { "algorithm": "Ed25519", "value": "..." }
175-
}
176-
```
177-
178-
`receipt_hashes` are publicly replayable. Before entering negotiation, the querying agent verifies the claimed `success_rate_bps` by replaying those decisions independently. Trust is mathematical, not assumed.
179-
180-
---
181-
182-
## Quick Look: A Negotiation
183-
184-
```json
185-
{
186-
"negotiation_id": "neg_8a2f4c1d",
187-
"state": "OFFER",
188-
"from_agent": "agent_7f3a9b2c",
189-
"to_agent": "agent_2d8e5f1a",
190-
"task": {
191-
"type": "text_summarization",
192-
"input_spec": { "format": "plaintext", "max_tokens": 10000 },
193-
"output_spec": { "format": "plaintext", "max_tokens": 500 }
194-
},
195-
"pricing": {
196-
"amount_minor_units": 500,
197-
"currency": "USD",
198-
"conditions": [
199-
{ "metric": "latency_ms", "threshold": 2000, "modifier": 10000 },
200-
{ "metric": "latency_ms", "threshold": 5000, "modifier": 7000 }
201-
]
202-
},
203-
"sla": { "max_latency_ms": 5000, "min_quality_score": 8500 },
204-
"expires_at": "2026-03-15T14:30:00Z",
205-
"signature": "ed25519:..."
206-
}
207-
```
208-
209-
This offer says: pay $5.00 if finished in 2 seconds, $3.50 if up to 5 seconds, quality must be at least 0.85, offer expires at 2:30 PM UTC. Cryptographically signed.
210-
211-
**All amounts are integer minor units. No floating point. Ever.**
212-
213-
---
214-
215-
## Quick Look: A Split Settlement
216-
217-
```json
218-
{
219-
"settlement_id": "stl_4b7c9e2f",
220-
"negotiation_id": "neg_8a2f4c1d",
221-
"payer_agent": "agent_7f3a9b2c",
222-
"payee_agents": [
223-
{ "agent_id": "agent_2d8e5f1a", "share_bps": 6000, "role": "primary_executor" },
224-
{ "agent_id": "agent_9c4b3e7d", "share_bps": 2500, "role": "data_provider" },
225-
{ "agent_id": "agent_platform", "share_bps": 1500, "role": "orchestrator" }
226-
],
227-
"total_amount_minor_units": 500,
228-
"currency": "USD",
229-
"conditions": [
230-
{ "type": "deterministic", "check": "http_status_200" },
231-
{ "type": "probabilistic", "check": "quality_score", "threshold": 8500 }
232-
],
233-
"on_timeout": "full_refund",
234-
"on_partial_completion": "pro_rata",
235-
"chargeback_policy": "proportional",
236-
"adapter": "stripe",
237-
"signature": "ed25519:..."
238-
}
239-
```
240-
241-
Shares are basis points summing to exactly 10000. 60% to the executor, 25% to the data provider, 15% to the orchestrator. One atomic operation. No invoicing. No reconciliation.
242-
243126
---
244127

245128
## Schema Reference
246129

247-
All schemas are JSON Schema Draft 2020-12, located in `/xap/schemas/`.
130+
All schemas in `/xap/schemas/`. JSON Schema Draft 2020-12.
248131

249132
| Schema | File | Status |
250133
|---|---|---|
@@ -262,15 +145,15 @@ All schemas are JSON Schema Draft 2020-12, located in `/xap/schemas/`.
262145

263146
## What XAP Is Not
264147

265-
**Not a payment processor.** XAP does not move money. It coordinates when, how much, to whom, and under what conditions. Stripe, USDC, and other rails move funds.
148+
**Not a payment processor.** XAP coordinates when, how much, to whom, and under what conditions. Stripe, USDC, and other rails move funds.
266149

267-
**Not a blockchain protocol.** No chain required. Settles on-chain if desired. Works equally well on traditional rails.
150+
**Not a blockchain protocol.** No chain required.
268151

269152
**Not a marketplace.** Does not match buyers to sellers. Defines what happens after they find each other.
270153

271154
**Not model-specific.** GPT, Claude, Gemini, Llama — any agent on any model.
272155

273-
**Not a checkout flow.** Stripe's ACP helps humans buy things through AI. XAP is for when agents hire other agents to do work, autonomously, in milliseconds, without any human present.
156+
**Not a checkout flow.** Stripe's ACP helps humans buy things through AI. XAP is for when agents hire other agents, autonomously, without any human present.
274157

275158
---
276159

@@ -280,83 +163,42 @@ All schemas are JSON Schema Draft 2020-12, located in `/xap/schemas/`.
280163
|---|---|---|
281164
| `xap-protocol` (this repo) | The open protocol. Schemas, spec, examples. | MIT |
282165
| `verity-engine` | The truth engine. Deterministic replay of every settlement decision. | MIT |
283-
| `xap-sdk` | Python SDK. `pip install xap-sdk`. Build XAP-native agents in minutes. | MIT |
284-
| Agentra Rail | Production implementation. Settlement at scale, enterprise dashboards, Verity explorer. | Commercial |
285-
286-
XAP belongs to the community. You do not need Agentra Rail to implement XAP. But if you want production settlement, enterprise governance, and the full Verity truth engine in production, Rail is the reference implementation.
166+
| `xap-sdk` | Python SDK. `pip install xap-sdk`. | MIT |
167+
| Agentra Rail | Production implementation. Settlement at scale. | Commercial |
287168

288169
---
289170

290171
## How To Implement XAP
291172

292-
An XAP-compatible system must:
293-
294173
1. Produce valid objects — every object validates against the JSON schema
295-
2. Sign every object — using Ed25519, key corresponding to a registered `AgentIdentity`
296-
3. Enforce state machines — `NegotiationContract` and `SettlementIntent` follow declared transitions only
297-
4. Handle idempotency — same `idempotency_key` returns existing result without duplicates
174+
2. Sign every object — using Ed25519
175+
3. Enforce state machines — declared transitions only
176+
4. Handle idempotency — same `idempotency_key` returns existing result
298177
5. Issue receipts — every settled `SettlementIntent` produces an `ExecutionReceipt`
299-
6. Capture decisions — every significant decision point produces a `VerityReceipt`
178+
6. Capture decisions — every significant decision produces a `VerityReceipt`
300179
7. Serve a manifest — every registered agent exposes `/.well-known/xap.json`
301180

302-
If your system does these seven things, it is XAP-compatible.
303-
304-
---
305-
306-
## Design Principles
307-
308-
**Escrow over payment.** The primitive is conditional release, not transfer. Funds lock, conditions verify, funds release or return.
309-
310-
**UNKNOWN over assumption.** When verification is ambiguous, the system declares uncertainty explicitly. It never pretends to know.
311-
312-
**Deterministic over probabilistic.** Every failure mode has a pre-declared outcome. Every decision is replayable. No undefined behavior in a financial protocol.
313-
314-
**Agent-native over human-friendly.** Schemas are machine-readable first. If an LLM can parse the spec and integrate without human help, the design is working.
315-
316-
**Append-only truth.** Reputation is never deleted. Receipts are never amended. The past is permanent.
317-
318-
**Protocol over product.** XAP defines behavior, not implementation. Any system that produces and consumes the six primitives correctly is XAP-compatible.
319-
320-
---
321-
322-
## Contributing
323-
324-
XAP is an early-stage open standard. The most valuable contributions right now are not code — they are thinking.
325-
326-
**Schema feedback (most urgent):** Read the schemas. Try to build with them. Tell us where they break, where they are too rigid, where a field is missing. Every issue found now prevents a breaking change later. Label: `schema-feedback`
327-
328-
**Edge cases:** What happens in the weird situations? Every edge case surfaced now prevents a breaking change later. Label: `edge-case`
329-
330-
**Vertical schemas:** Agents in finance, healthcare, legal, logistics all need domain-specific capability definitions. Label: `vertical-schema`
331-
332-
**Alternative implementation feedback:** Building an XAP-compatible system that is not Agentra Rail? Tell us what was hard. Label: `implementation-feedback`
333-
334-
**Security review:** Find a vulnerability. See [SECURITY.md](SECURITY.md) for responsible disclosure.
335-
336-
Read [CONTRIBUTING.md](CONTRIBUTING.md) before opening a PR.
337-
338181
---
339182

340183
## Roadmap
341184

342185
| Milestone | Status |
343186
|---|---|
344187
| v0.1 Draft schemas (5 primitives) | Complete |
345-
| v0.2 Schema hardening + AgentManifest + RegistryQuery | Complete |
346-
| Protocol specification document (PDF) | Next |
347-
| Verity truth engine (Rust, open source) | Complete — `verity-engine` repo |
348-
| Python SDK (`pip install xap-sdk`) | Live — v0.4.0 on PyPI |
188+
| v0.2 AgentManifest + RegistryQuery | Complete |
189+
| Protocol specification document | Next |
190+
| Verity truth engine (Rust) | Complete — `verity-engine` repo |
191+
| Python SDK | Live — v0.4.0 on PyPI |
349192
| Validation test suite | 115 tests passing |
350193
| v1.0 Specification lock | Target: Q3 2026 |
351-
| Federation protocol (cross-registry discovery) | v1.1 |
194+
| Federation protocol | v1.1 |
352195

353196
---
354197

355198
## Community
356199

357-
**Spec homepage:** [xap-protocol.org](https://xap-protocol.org)
358200
**Discord:** [Join @agentralabs](https://discord.gg/agentralabs)
359-
**X / Twitter:** [Follow @agentralab](https://x.com/agentralab)
201+
**X:** [Follow @agentralab](https://x.com/agentralab)
360202
**Email:** [hello@agentralabs.tech](mailto:hello@agentralabs.tech)
361203

362204
---
@@ -377,8 +219,8 @@ Read [CONTRIBUTING.md](CONTRIBUTING.md) before opening a PR.
377219

378220
## License
379221

380-
MIT. The protocol is free. Forever. The goal is adoption, not control.
222+
MIT. The protocol is free. Forever.
381223

382224
---
383225

384-
*XAP is maintained by [Agentra Labs](https://www.agentralabs.tech). The protocol belongs to the community. The reference implementation is [Agentra Rail](https://www.agentralabs.tech).*
226+
*XAP is maintained by [Agentra Labs](https://www.agentralabs.tech). The reference implementation is [Agentra Rail](https://www.agentralabs.tech).*

0 commit comments

Comments
 (0)