# Protocol overview

> The LOPW protocol for engineers: the six roles, the eight-step flow, the three kinds of contract, what is portable across chains and what is not, and what is out of scope.

*LOPW documentation · Protocol reference.* Canonical page: https://lopw.com/docs/protocol/ · This Markdown twin: https://lopw.com/docs/protocol/index.md · Index of all pages: https://lopw.com/llms.txt · Everything in one file: https://lopw.com/llms-full.txt

LOPW is a warranty and slashing primitive for machine payments. This reference describes version 1 exactly as the contracts and SDKs implement it. Where the specification and the decisions log differ, the decisions log wins; this reference follows the decisions.

- [Offer, receipt and terms](https://lopw.com/docs/protocol/offer-and-receipt.html): Every field, type and rule.
- [Hashing and signing](https://lopw.com/docs/protocol/hashing-and-signing.html): Domain separation, exact byte layout, test vectors.
- [Predicates P1 to P6](https://lopw.com/docs/protocol/predicates.html): Exact conditions, edge rules, interactive explorer.
- [Claims](https://lopw.com/docs/protocol/claims.html): Seven checks in order, outcomes, errors, events.
- [Bond Registry](https://lopw.com/docs/protocol/bond-registry.html): Functions, events, states, floors, fees, time locks, unbonding.
- [x402 extension](https://lopw.com/docs/protocol/x402.html): The lopw extension on the wire.
- [HTTP API](https://lopw.com/docs/protocol/api.html): Read-only endpoints and the OpenAPI document.
- [Chain bindings](https://lopw.com/docs/protocol/bindings.html): Portable core and the Stellar binding.

## Roles

Six parties take part. The first three already exist in any x402 payment; LOPW adds the last three.

| Party | Role |
| --- | --- |
| Seller | Runs a paid API, stakes the bond, signs offers and receipts with a dedicated signing key |
| Buyer | An agent or app that pays per request and may file a claim |
| Facilitator | The x402 service that verifies and settles the payment; unchanged |
| Bond Registry | Contract that holds stake per service and stores each service’s terms versions and signing keys |
| Validators | Contracts that each decide one predicate, with one function: `validate` |
| Claims contract | Verifies evidence, applies the checks, calls the validator, pays the buyer or records a rejection |

## Protocol flow

Warranty offer → Payment → Service receipt → Deterministic claim → Validator → Slash or reject

1. The seller registers a service in the Bond Registry with its terms, a signing key and a minimum stake, then deposits stake. The service becomes `Active` when stake reaches the minimum.
2. The buyer requests the resource. The seller answers `402` with the normal x402 payment requirements plus a signed warranty offer under `extensions.lopw`.
3. The buyer verifies the offer signature against the key registered on-chain and reads the service’s state, stake and terms.
4. The buyer pays through standard x402, echoing the offer in its payment payload. The facilitator settles on-chain.
5. The seller returns the response. The settlement response (`PAYMENT-RESPONSE`) carries a signed receipt under `extensions.lopw` that cites the offer and the settlement transaction.
6. The buyer verifies the receipt and evaluates every predicate locally.
7. If a breach is found, anyone may submit the offer and receipt to the Claims contract inside the claim window.
8. The Claims contract runs the matching validator. A proven breach pays the buyer named in the receipt from the seller’s stake. Anything else is rejected or fails.

The x402 payment itself is unchanged: there is no escrow, no arbitration and no response period. The payment settles normally while LOPW runs as an independent accountability layer. An animated version is in [How a warranty works](https://lopw.com/docs/start/how-it-works.html).

## Contracts

| Contract | Holds | Public surface |
| --- | --- | --- |
| Bond Registry | Stake per service (one SEP-41 token per deployment; USDC), terms versions, signing keys, service state, protocol floors, launch limits, fee configuration | [Functions](https://lopw.com/docs/protocol/bond-registry.html#functions); only the Claims contract may call `slash` |
| Claims | Paid-claim records keyed by `(service_id, payment_reference)`; the validator allowlist by predicate ID; the registry address it serves | [Functions](https://lopw.com/docs/protocol/claims.html#functions) |
| Validators P1 to P6 | Nothing; pure functions of their inputs (P6 reads the oracle) | `validate(terms, offer, receipt, extra)` |

Separating custody from claim logic keeps the code that holds money short, and lets predicates be added by allowlisting a new validator without redeploying the contract that holds stake. Contracts have no upgrade function; slashing rights can move only through time-locked admin changes ([time locks](https://lopw.com/docs/protocol/bond-registry.html#time-locks)).

## Portable and binding-specific

| Portable across chains and payment rails | Specific to a chain binding |
| --- | --- |
| The warranty offer and its fields | The encoding (ScVal XDR on Stellar) |
| The service receipt and its fields | The signature scheme (Ed25519 over a domain-separated SHA-256) |
| The validator interface and the six predicates | The contract functions and error codes |
| The claim semantics: checks, outcomes, replay rule, payout rule | The payment-rail binding (x402 `exact` on Stellar) and the oracle interface (SEP-40) |

Built first on Stellar with Soroban, USDC and x402; designed for every chain. See [chain bindings](https://lopw.com/docs/protocol/bindings.html).

## Out of scope in version 1

- Judging whether an answer is correct, useful or well translated.
- Latency or availability witnessed only by the buyer.
- Slashing for missing receipts or invalid signatures.
- Reserved per-call coverage, insurance pools or a custom x402 settlement scheme.
- Arbitration, voting or seller appeals.
- Schema checks on the response body (a possible P7, after P1 to P6 have run in production).

Version 1 pays only on breaches that can be proven deterministically from cryptographic evidence, contract state or a named on-chain oracle.