# LOPW

> LOPW (Layer of Onchain Programmable Warranties) is a chain-agnostic protocol for machine-enforceable warranties in autonomous commerce. Sellers bond USDC behind machine-readable promises. Every paid response carries a seller-signed receipt. When the receipt, or a named on-chain oracle, proves a promise was broken, a validator contract confirms it and the buyer is paid from the seller's stake automatically. x402 proves the agent paid; LOPW puts capital behind what the seller promised. Built first on Stellar with Soroban, USDC and x402; designed for every chain.

Every documentation page exists as HTML and as a Markdown twin at the same path with a .md extension. The complete documentation as one Markdown file is at https://lopw.com/llms-full.txt. Key facts: protocol version 1; predicates P1 Equivocation, P2 Terms mismatch, P3 Stale data, P4 Bad status, P5 Size limit, P6 Oracle deviation; payout = min(max_claim, stake remaining) to the buyer named in the receipt; service states Pending, Active, Suspended, Unbonding, Closed; floors: min_stake at least 100 USDC, claim window at most 24 h (1 h with P6), unbonding delay = largest claim window ever + 1 h, slash cap 50% of epoch-start stake per epoch.

## Start here

- [What is LOPW](https://lopw.com/docs/index.md): LOPW in plain words: a seller puts money behind a promise, every paid answer comes with a signed receipt, and a broken promise pays the buyer automatically. Start here.
- [How a warranty works](https://lopw.com/docs/start/how-it-works.md): An animated, step-by-step walk through a LOPW warranty: offer, payment, receipt, local check, claim, validator, and payout or rejection.
- [Who it is for](https://lopw.com/docs/start/who-it-is-for.md): What LOPW gives agents, API sellers and platforms, what each has to do, and where each should start reading.
- [Glossary](https://lopw.com/docs/start/glossary.md): Every LOPW term in one place, from stake and terms to predicates, epochs and key versions, with links to where each is specified.
- [FAQ](https://lopw.com/docs/start/faq.md): Short answers to the first questions people ask about LOPW: what it costs, what it covers, what it cannot do, and how it relates to x402.

## Guides

- [Getting started](https://lopw.com/docs/getting-started.md): Pick your track: make an agent pay only bonded x402 services, add a stake-backed warranty to your x402 API, or read bonds and claims from any app over HTTP.
- [Getting started for agents](https://lopw.com/docs/guides/agents.md): Make an agent pay only bonded x402 services with @lopw/buyer-sdk: install, set a policy, fetch with warranty checks before and after payment, and claim when a promise is broken.
- [Getting started for sellers](https://lopw.com/docs/guides/sellers.md): Add a stake-backed warranty to an x402 API: generate a signing key, choose terms, register and stake in the Bond Registry, and add @lopw/seller-middleware to your resource server.
- [Getting started for app builders](https://lopw.com/docs/guides/apps.md): Read bonded services, claims, events and live streams from the public LOPW HTTP API: JSON, cursor pagination, ETags, problem+json errors and Server-Sent Events, with open CORS.
- [How-to guides](https://lopw.com/docs/guides.md): Task-focused recipes for sellers, agents and apps: add a warranty, pay only bonded services, file a claim, choose predicates, rotate keys, unbond, read a bond, run the scenarios.
- [Add a warranty to an x402 API](https://lopw.com/docs/guides/add-warranty.md): Checklist to turn an existing x402 endpoint into a bonded one: signing key, terms, registration, stake, the lopw extension and the freshness header.
- [Make an agent pay only bonded services](https://lopw.com/docs/guides/bonded-only.md): Configure the buyer policy so an agent refuses unbonded, under-staked or under-covered sellers before any money moves, and handle refusals.
- [File a claim](https://lopw.com/docs/guides/file-claim.md): From a breached receipt to a payout: what the SDK checks, when to claim, what the Claims contract returns, and every error you can meet.
- [Choose predicates and limits](https://lopw.com/docs/guides/predicates-limits.md): How a seller picks which predicates to promise and sets limits it can keep: parameters per predicate, claim window, max_claim and min_stake, and the registry's validity rules.
- [Rotate a signing key](https://lopw.com/docs/guides/rotate-key.md): Replace a service's Ed25519 signing key without stranding any receipt: what rotate_key does, what happens to old receipts, and what a leaked key can no longer do.
- [Withdraw stake safely](https://lopw.com/docs/guides/unbonding.md): Partial and full withdrawals through request_unbond, the unbonding delay, cancel_unbond, withdraw, and what remains slashable, with the exact contract rules.
- [Read a bond from any app](https://lopw.com/docs/guides/read-bond.md): Three ways to read a service's bond without a wallet: the service's own GET /v1/warranty, the public API, and a direct chain read with the protocol package.
- [Run the scenarios yourself](https://lopw.com/docs/guides/run-scenarios.md): Reproduce every demonstrated scenario with the demo agent against the reference services: honest quote, each predicate's breach, tampered signature, replay, honest claim rejected and policy refusal.

## Protocol reference

- [Protocol overview](https://lopw.com/docs/protocol/index.md): 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.
- [Offer, receipt and terms](https://lopw.com/docs/protocol/offer-and-receipt.md): Field-by-field reference for the LOPW Terms, Offer, Receipt and oracle types, exactly as the contract types define them, with validity rules and JSON Schemas.
- [Hashing and signing](https://lopw.com/docs/protocol/hashing-and-signing.md): Exactly which bytes are hashed and signed in LOPW: ScVal XDR encoding, the domain-separated message, request and terms hashes, service IDs, key rotation, replay protection and the shared test vectors.
- [Predicates P1 to P6](https://lopw.com/docs/protocol/predicates.md): The six LOPW breach conditions with their exact proven conditions and edge rules (data_as_of 0, oracle tick rounding, the exact deviation test), the validator interface, and an interactive explorer.
- [Claims](https://lopw.com/docs/protocol/claims.md): The LOPW Claims contract: the seven checks in order (animated), outcomes, every error code, the payout rule, records, events and functions.
- [Bond Registry](https://lopw.com/docs/protocol/bond-registry.md): The LOPW Bond Registry: every function, event and error, the five service states with an animated state machine, protocol floors, launch limits, fees, time locks, the slash rate limit and the unbonding maths with a calculator.
- [x402 extension](https://lopw.com/docs/protocol/x402.md): The LOPW x402 v2 extension on the wire: where the signed offer and receipt travel, the exact JSON shapes, the buyer echo, the handler headers, and why verify and settle are untouched.
- [HTTP API](https://lopw.com/docs/protocol/api.md): The read-only LOPW HTTP API: every public endpoint, parameters, response shapes, pagination, caching, errors and the Server-Sent Events stream, with the OpenAPI 3.1 document.
- [Chain bindings](https://lopw.com/docs/protocol/bindings.md): What a LOPW chain binding supplies, and the Stellar binding in detail: Soroban contracts, USDC stake, x402 exact payments, SEP-40 oracles, ScVal XDR and Ed25519.

## Networks

- [Networks](https://lopw.com/docs/networks/index.md): LOPW is one protocol with the same semantics on every chain. What a chain binding is, what differs per chain (signatures, hashing, token, oracle, x402 scheme), a comparison table, and the networks: Stellar as the reference binding, the EVM networks, and the planned Solana binding.
- [Stellar](https://lopw.com/docs/networks/stellar.md): The reference LOPW binding: Soroban contracts, Ed25519 signatures, SHA-256 over domain-separated ScVal XDR, the USDC Stellar Asset Contract with 7 decimals, Reflector SEP-40 oracles, x402 exact with SEP-41, network names testnet and mainnet, and the live contract addresses on Stellar testnet.
- [EVM binding](https://lopw.com/docs/networks/evm.md): The LOPW binding shared by Base, Ethereum, Arbitrum, Optimism, Polygon and Avalanche: Solidity contracts, EIP-712 typed data with the exact type strings, keccak-256 termsHash, secp256k1 signatures, Chainlink getRoundData(roundId) with the round id as the citation, EIP-3009 for x402, ABI-hex wire encoding, and confirmations before indexing.
- [Base](https://lopw.com/docs/networks/base.md): LOPW on Base through the EVM binding: chain ids and CAIP-2 ids for Base Sepolia and Base, native USDC addresses, explorers, the Chainlink oracle note, and the LOPW contract addresses or the deployment status for each network.
- [Ethereum](https://lopw.com/docs/networks/ethereum.md): LOPW on Ethereum through the EVM binding: chain ids and CAIP-2 ids for Ethereum Sepolia and Ethereum, native USDC addresses, explorers, the Chainlink oracle note, and the LOPW contract addresses or the deployment status for each network.
- [Arbitrum](https://lopw.com/docs/networks/arbitrum.md): LOPW on Arbitrum through the EVM binding: chain ids and CAIP-2 ids for Arbitrum Sepolia and Arbitrum One, native USDC addresses, explorers, the Chainlink oracle note, and the LOPW contract addresses or the deployment status for each network.
- [Optimism](https://lopw.com/docs/networks/optimism.md): LOPW on Optimism through the EVM binding: chain ids and CAIP-2 ids for OP Sepolia and OP Mainnet, native USDC addresses, explorers, the Chainlink oracle note, and the LOPW contract addresses or the deployment status for each network.
- [Polygon](https://lopw.com/docs/networks/polygon.md): LOPW on Polygon through the EVM binding: chain ids and CAIP-2 ids for Polygon Amoy and Polygon PoS, native USDC addresses, explorers, the Chainlink oracle note, and the LOPW contract addresses or the deployment status for each network.
- [Avalanche](https://lopw.com/docs/networks/avalanche.md): LOPW on Avalanche through the EVM binding: chain ids and CAIP-2 ids for Avalanche Fuji and Avalanche C-Chain, native USDC addresses, explorers, the Chainlink oracle note, and the LOPW contract addresses or the deployment status for each network.
- [Solana](https://lopw.com/docs/networks/solana.md): The planned LOPW binding for Solana, as a design: Anchor programs, Ed25519 over domain-separated SHA-256 of Borsh bytes, USDC SPL with 6 decimals, Pyth price updates verified in-program, x402 exact with an SPL transfer, and the network names solana-devnet and solana. Nothing is deployed.

## Deep dive

- [Security model](https://lopw.com/docs/deep-dive/security.md): LOPW's security model: what is protected, trust assumptions, the threats and their mitigations, residual risks, and the known limits accepted in version 1.
- [Economics](https://lopw.com/docs/deep-dive/economics.md): What a seller risks and pays, what a buyer gains and pays, how the payout, caps, epochs and fees interact, with exact fee maths and worked examples.
- [The decisions log, explained](https://lopw.com/docs/deep-dive/decisions.md): Why each LOPW rule exists: the twenty-two recorded decisions that refine the specification, in plain language, with what they changed and why.
- [Proofs and scenarios](https://lopw.com/docs/deep-dive/proofs-and-scenarios.md): What LOPW has demonstrated on a live network: every predicate's payout after a real x402 payment, the stake lifecycle, governance safety and the automated test suites, with links to the demo and proofs pages.

## For AI agents

- [Agents start here](https://lopw.com/docs/agents/index.md): Machine-readable entry point to LOPW: Markdown twins of every page, llms.txt, llms-full.txt, the protocol descriptor, JSON Schemas for Offer, Receipt and Terms, shared test vectors and the OpenAPI document, plus the facts an agent needs to decide and act.

## Chain bindings and networks

One protocol, the same semantics on every chain; a binding supplies only the carriers (signatures, hashing, token, oracle, x402 scheme, wire encoding of the lopw extension). Network names are the `{network}` segment of API paths (/v1/{network}/...).

- **Stellar binding** (reference binding, live on Stellar testnet): Soroban contracts, Ed25519 over domain-separated SHA-256 of ScVal XDR, USDC SAC (7 decimals), Reflector SEP-40 oracle, x402 exact with SEP-41; wire form base64 ScVal XDR
  - `testnet` (stellar:testnet, Stellar testnet): LOPW contracts deployed: Bond Registry CBNGZB5GL3FEZKIQK73BTJYCQAC76N7SZCLN34JRMTQCUWER4GB3WHPL, Claims CBUBZC2AHVKFKYTAO3DIF6CZFQVM4UYCNABYVTPQNUUJGLOIBSIWONSC, Validator P1 Equivocation CBEBETGU7AFDBYSP5VGUIKJ7FHLLDOG5LM56MHYWYWT4M4S7FZEZ7TU3, Validator P2 Terms mismatch CCDRQUWK5JHLNJRAMT6P37K4RS4B3SNELLZPP6LMM64IZ357MSSGSDW4, Validator P3 Stale data CDUIB7ZPIRXMUZLIXRTALEFLXMAYLLIBJ6TDN5HWDR77CPLLPIG44DVJ, Validator P4 Bad status CA5FBH3RUW65UXIHU4YP2GSTQNUXHXTB4NIEVICPHHV7ISXY2VB6A2LV, Validator P5 Size limit CDJGYTFQOGMY3UX7CPYLJPNZF2SPFEHJRJGY3VOOHVVIPLNS4NWL5BEE, Validator P6 Oracle deviation CDPLC6G732LTARGLAKNA5TRR4DAERXKMWGWI4TS4XQ6WLHRSPHQNEWGV; [docs](https://lopw.com/docs/networks/stellar.md)
  - `mainnet` (stellar:pubnet, Stellar mainnet): No LOPW deployment is published on this network yet.; [docs](https://lopw.com/docs/networks/stellar.md)
- **EVM binding** (one Solidity binding for Base, Ethereum, Arbitrum, Optimism, Polygon and Avalanche; Base first): Solidity contracts, secp256k1 over EIP-712 typed data (keccak-256), native USDC (6 decimals), Chainlink getRoundData(roundId), x402 exact with EIP-3009; wire form 0x-hex ABI encoding
  - `base-sepolia` (eip155:84532, Base Sepolia): No LOPW deployment is published on this network yet.; [docs](https://lopw.com/docs/networks/base.md)
  - `base` (eip155:8453, Base): No LOPW deployment is published on this network yet.; [docs](https://lopw.com/docs/networks/base.md)
  - `sepolia` (eip155:11155111, Ethereum Sepolia): No LOPW deployment is published on this network yet.; [docs](https://lopw.com/docs/networks/ethereum.md)
  - `ethereum` (eip155:1, Ethereum): No LOPW deployment is published on this network yet.; [docs](https://lopw.com/docs/networks/ethereum.md)
  - `arbitrum-sepolia` (eip155:421614, Arbitrum Sepolia): No LOPW deployment is published on this network yet.; [docs](https://lopw.com/docs/networks/arbitrum.md)
  - `arbitrum` (eip155:42161, Arbitrum One): No LOPW deployment is published on this network yet.; [docs](https://lopw.com/docs/networks/arbitrum.md)
  - `optimism-sepolia` (eip155:11155420, OP Sepolia): No LOPW deployment is published on this network yet.; [docs](https://lopw.com/docs/networks/optimism.md)
  - `optimism` (eip155:10, OP Mainnet): No LOPW deployment is published on this network yet.; [docs](https://lopw.com/docs/networks/optimism.md)
  - `polygon-amoy` (eip155:80002, Polygon Amoy): No LOPW deployment is published on this network yet.; [docs](https://lopw.com/docs/networks/polygon.md)
  - `polygon` (eip155:137, Polygon PoS): No LOPW deployment is published on this network yet.; [docs](https://lopw.com/docs/networks/polygon.md)
  - `avalanche-fuji` (eip155:43113, Avalanche Fuji): No LOPW deployment is published on this network yet.; [docs](https://lopw.com/docs/networks/avalanche.md)
  - `avalanche` (eip155:43114, Avalanche C-Chain): No LOPW deployment is published on this network yet.; [docs](https://lopw.com/docs/networks/avalanche.md)
- **Solana binding** (planned binding (design only; nothing deployed)): Anchor programs, Ed25519 over domain-separated SHA-256 of Borsh, USDC SPL (6 decimals), Pyth, x402 exact with SPL transfer; a design, not a deployment
  - `solana-devnet` (solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1, Solana devnet): Planned binding; no program is deployed and the API serves no Solana network.; [docs](https://lopw.com/docs/networks/solana.md)
  - `solana` (solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp, Solana mainnet): Planned binding; no program is deployed and the API serves no Solana network.; [docs](https://lopw.com/docs/networks/solana.md)

## Machine-readable files

- [Protocol descriptor (JSON)](https://lopw.com/.well-known/lopw.json): names, flow, predicates, states, SDK exports, chain bindings, every network, documentation links
- [Offer JSON Schema](https://lopw.com/docs/schemas/offer.json): the signed warranty offer, field by field (Stellar reference binding, base64 ScVal XDR on the wire)
- [Receipt JSON Schema](https://lopw.com/docs/schemas/receipt.json): the signed service receipt, including the oracle evidence block (Stellar reference binding)
- [Terms JSON Schema](https://lopw.com/docs/schemas/terms.json): registered warranty terms and their validity rules (Stellar reference binding)
- [Offer JSON Schema, EVM binding](https://lopw.com/docs/schemas/offer-evm.json): the Solidity Offer struct, its EIP-712 type string and the 0x-hex ABI wire form of SignedOffer
- [Receipt JSON Schema, EVM binding](https://lopw.com/docs/schemas/receipt-evm.json): the Solidity Receipt struct, Chainlink round evidence, EIP-712 type strings and the 0x-hex ABI wire form of SignedReceipt
- [Terms JSON Schema, EVM binding](https://lopw.com/docs/schemas/terms-evm.json): the Solidity Terms struct hashed with keccak256(abi.encode(terms))
- [Shared test vectors v1 (JSON)](https://lopw.com/docs/vectors/v1.json): exact XDR bytes, hashes and signatures every implementation must reproduce
- [Public API OpenAPI 3.1 document](https://lopw.com/docs/api/openapi.json): read-only HTTP API for services, claims, events, stats and scenarios

## Optional

- [Live demo](https://lopw.com/demo/): a real claim paid on testnet, step by step
- [Proofs](https://lopw.com/proofs/): every transaction and test that demonstrates the protocol
- [Status](https://lopw.com/status/): live health of the services that sell, verify and settle warranties