@stellar-agent-services/dev-mcp 0.0.0-stage → 0.1.1

package/repository/IMPLEMENTATION_PLAN.md

@@ -0,0 +1,560 @@
+# Stellar Agent Services: Implementation Plan
+
+Phase 2 of [Stellar Agent Search](https://github.com/berkingurcan/stellar-agent-search). It covers the Provider
+Standard, Provider Kit, safe Payment Client, verification receipts, Stellar 8004 Validation Registry records and
+Job Recovery, delivered and piloted within one 30-day Instaward sprint.
+
+- **Source of truth:** Instawards SOW "Stellar Agent MCP" (submitted 29.09.2026, $4,000, 30 days).
+- **Background:** `stellar-agent-search/docs/provider-network-phase-2.md` and `issues/P3-23-provider-network-phase-2.md`.
+- **Network:** Stellar **testnet** for the whole build. Mainnet is a later, separate decision (see [Open decisions](#10-open-decisions)).
+- **Status (2026-11-06):** the core packages are released at 0.1.0. The kit, client, recovery and C1–C7 verifier
+  are implemented. This checkout adds fail-closed enforcement of configured verification restrictions [V1].
+  Sample approval/payment and recovery demos are recorded with screenshots and on-chain proofs in `evidence/`.
+  [The recordings and proofs are public](https://algorialabs.github.io/stellar-agent-services/); live verification
+  runs and badges are documented in [receipt evidence](evidence/receipts/README.md). Permanent sample
+  registration, an anchored Validation Registry response and the independent pilot remain.
+  Newer implementation notes report testnet discovery implemented in `stellar-agent-search`;
+  the pilot must confirm the full discovery-to-result path. See [SOW closeout](docs/sow-closeout.md) for the
+  handoff and [readiness evidence](evidence/readiness.md) for checks and public release/CI references.
+
+---
+
+## 1. What the SOW commits us to
+
+| SOW deliverable | Contents | Evidence promised |
+| --- | --- | --- |
+| **D1:** Provider Standard + Safe Payment Client | Provider Standard v1 (purpose, input, output, price, network, job status, result). Payment client that shows payment details, applies spending controls and requires approval. | Public spec, short demo video, screenshots, payment tx link |
+| **D2:** Provider Kit, Verification, Job Recovery | Open-source kit, setup guide, sample service. Provider checks, verification receipts and badges, Stellar 8004 Validation Registry publishing. Job Recovery (create-job, check-status, get-result) without paying twice. | Public repo, setup guide, verification receipt, Validation Registry record, recovery demo |
+| **D3:** Independent Provider Pilot + Public Evidence | Independent providers each complete at least one paid call. Users run the full flow. Job Recovery demo. Pilot report. Incentives included. | Provider links, payment references, screenshots, pilot report, public evidence page |
+
+**Out of scope (SOW):**
+- a new registry or protocol
+- the full ERC-8126 specification
+- zero-knowledge proofs
+- a formal audit
+- a consumer marketplace
+- custody
+- guaranteed adoption or availability
+
+### 1.1 Inconsistencies in the SOW, and the reading we plan against
+
+The SOW gives conflicting numbers. The working interpretation below still needs Chapter Lead agreement; it
+does not literally satisfy D3's phrase "three independent providers".
+
+| Topic | What the SOW says | We plan for |
+| --- | --- | --- |
+| Providers | "two independent providers" (objective, W4, evidence). "three independent providers" (D3). "not more than two" (out of scope). "three working provider integrations" (W4 output). | **3 integrations = our sample provider + 2 independent providers** |
+| Users | "five users" (D3, W4 output). "two users" (objective, W4 work, evidence). "not more than five" (out of scope). | **5 distinct users**, each completing the flow |
+| Where it lives | "add … to Stellar Agent Search" | Phase 2 of Stellar Agent Search, built in this repo. Discovery stays in `stellar-agent-search`. |
+
+> Action: confirm this reading with the Ambassador Chapter Lead before the sprint starts.
+
+---
+
+## 2. Principles
+
+1. **Discovery holds no keys.** `stellar-agent-search` stays read-only and keyless. Nothing in this repo is
+   imported into it except read-only types or schemas.
+2. **The provider runtime holds no keys.** A provider server only knows its `payTo` public address. The
+   facilitator verifies and settles. The owner's transactions (USDC trustline, registration, validation requests)
+   are signed only in the owner's own wallet, on a local approval page the CLI opens, or with `--source` through
+   the Stellar CLI keychain. The CLI never holds a key.
+3. **Signing happens only in the payment client.** The approved payment is signed exactly once, and only after
+   the user approves the exact price, recipient, asset and network, or when the payment fits a budget the user
+   explicitly granted.
+4. **Never pay twice for one job.** The job identity is fixed before payment. The provider binds it to one
+   request and one payment, and recovery never re-sends a payment credential.
+5. **Fail closed.** A failed spending-limit check, an unknown settlement, a mismatched challenge or an
+   unreadable journal stops the flow. None of them is ever treated as a pass.
+6. **One network per flow.** A demo, test or pilot run uses testnet from discovery to feedback, never a mix.
+7. **Independent codebase.** No code, schemas or names are taken from Algoria. The foundations are the public
+   x402 v2 spec, the `@x402/*` packages, `@stellar/stellar-sdk`, `@trionlabs/stellar8004` and Stellar Agent
+   Search's own Phase 1 reference (`examples/x402-demo.ts`).
+8. **Stay compatible with ERC-8126 and ERC-8196.** We don't implement them, because a parallel project does. Our
+   identity, Validation Registry, policy and journal formats must not block their Stellar versions. See
+   [docs/erc-compatibility.md](docs/erc-compatibility.md).
+9. **Universal standard.** Any service in any language can implement Provider Standard v1. The spec is
+   language-neutral and reuses existing standards (x402, JSON Schema, MCP tool fields, IETF Idempotency-Key,
+   RFC 9457). The TypeScript kit and its gateway mode make adoption easier but are never required.
+
+---
+
+## 3. Architecture
+
+```
+      ┌──────────────────────────┐   read-only    ┌──────────────────────────────┐
+      │ stellar-agent-search     │ ─────────────▶ │ Stellar 8004 registries      │
+      │ (discovery, no keys)     │                │ Identity · Reputation ·      │
+      └────────────┬─────────────┘                │ Validation (Soroban)         │
+                   │ finds provider + manifest URL└──────────────▲───────────────┘
+                   ▼                                             │ validation_request (provider owner)
+      ┌──────────────────────────┐  create-job (402 → pay)       │ validation_response (verifier)
+      │ payment-client  (keys)   │ ───────────────────────────┐  │
+      │ approval · limits ·      │  check-status / get-result │  │
+      │ journal · recovery       │ ◀──────────────────────────┤  │
+      └──────────────────────────┘                            ▼  │
+                                                 ┌──────────────────────────┐
+      ┌──────────────────────────┐   test calls  │ provider (provider-kit)  │
+      │ verifier  (verifier key) │ ────────────▶ │ manifest · x402 server · │
+      │ checks · receipt · badge │               │ job store · services     │
+      └──────────────────────────┘               └────────────┬─────────────┘
+                                                              │ verify / settle
+                                                              ▼
+                                                 ┌──────────────────────────┐
+                                                 │ x402 facilitator         │
+                                                 │ (fee-sponsored USDC SAC) │
+                                                 └──────────────────────────┘
+```
+
+### 3.1 Who holds which key
+
+| Actor | Holds | Must never hold |
+| --- | --- | --- |
+| `stellar-agent-search` (discovery) | nothing | any secret |
+| Provider server (`provider-kit` runtime, library or gateway mode) | `payTo` **public** address, facilitator URL; in gateway mode, the upstream API's own credential if it has one | any Stellar secret key |
+| Provider operator (`provider-kit` CLI) | no key: the owner's own wallet signs the USDC trustline, registration and `validation_request` on the local approval page; `--source` uses a Stellar CLI keychain key instead | payer or verifier keys |
+| `payment-client` | the payer's key or wallet connection (§5.6) | provider or verifier keys |
+| `verifier` | verifier key (`validation_response`), plus a dedicated testnet test-payer key for the paid-call check | provider owner keys |
+
+### 3.2 Repository layout
+
+```
+packages/
+  protocol/        Provider Standard v1 as code: types, schemas, header names, job states, receipts,
+                   canonical JSON, network constants. Shared by every other package.
+  provider-kit/    Server toolkit: defineService, createProvider (Fetch-API handler), gateway mode
+                   (any existing HTTP API), x402 resource server, job store + runner,
+                   manifest + 8004 registration, operator CLI.
+  payment-client/  Buyer side: policy, journal, payment, recovery (§5.6).
+  verifier/        Provider checks → verification receipt → badges → Validation Registry response.
+  create-stellar-service/
+                   npm create stellar-service: a new provider project (gateway, library or Python), ready to
+                   run, try and deploy.
+apps/
+  wallet/          Web approval page: static, no backend, the payment-client core in the browser (§5.6).
+examples/
+  paid-service/    Sample provider built only with provider-kit (one on-success + one upfront service).
+  python-upstream/ An existing Python API made a paid service by gateway mode, with only a config file.
+docs/              Provider Standard v1, setup guide, job recovery, verification, payment client, pilot.
+evidence/          Receipts, payment references, validation records, pilot report (filled during the sprint).
+```
+
+**Tooling:**
+- npm workspaces, matching `stellar-agent-search`, with TypeScript project references (`tsc -b`) and vitest.
+- Node `>=22.13`; `.node-version` pins 24. Node 22.13 is needed for the built-in `node:sqlite` with no native
+  dependency and for `@x402/stellar`.
+
+---
+
+## 4. Network and dependencies (testnet)
+
+| Item | Value or source |
+| --- | --- |
+| CAIP-2 | `stellar:testnet` (`STELLAR_TESTNET_CAIP2` from `@x402/stellar`) |
+| Asset | USDC Stellar Asset Contract: import `USDC_TESTNET_ADDRESS` from `@x402/stellar`, never retype it |
+| USDC issuer (trustline check) | `GBBD47IF6LWK7P7MDEVSCWR7DPUWV3NY3DTQEVFL4NAT4AQH3ZLLFLA5` |
+| Soroban RPC / Horizon | `https://soroban-testnet.stellar.org` / `https://horizon-testnet.stellar.org` |
+| 8004 contracts | `TESTNET_CONFIG` from `@trionlabs/stellar8004`. Validation: `CC5USZRO26MOIAVNYTTJDS63C2OBBLREOAOET4CPF2EZWO3YFKLMO3SL` |
+| Facilitator | `https://x402.org/facilitator`. Confirmed: it supports `stellar:testnet` + `exact` with sponsored fees, and sets no authorization window of its own (the window follows `maxTimeoutSeconds`). |
+| Decimals | 7 (`0.01 USDC = 100000` base units) |
+
+| Package | Version | Note |
+| --- | --- | --- |
+| `@x402/core`, `@x402/fetch`, `@x402/stellar` | 2.28.0 | `@x402/stellar` needs `@stellar/stellar-sdk ^16.3.0` |
+| `@stellar/stellar-sdk` | 16.4.1 | Root `overrides` put `@trionlabs/stellar8004` (declares `^15`) on the same copy, and only it: `@creit.tech/stellar-wallets-kit` (approval page, dev only) keeps its `^17`. 16.4.1 is the first 16.x that pins a fixed axios (1.20.0); 16.3.1 pinned a vulnerable 1.18.0. |
+| `@trionlabs/stellar8004` | 0.0.11 | Identity, Reputation and Validation clients; `generateRequestNonce`; metadata helpers |
+| `hono`, `@hono/node-server` | 4.x / 2.x | Example service only. The kit itself is framework-agnostic (Fetch `Request`/`Response`). |
+
+---
+
+## 5. Components
+
+### 5.1 Provider Standard v1 (`docs/provider-standard.md`, `packages/protocol`)
+
+The draft spec is in [docs/provider-standard.md](docs/provider-standard.md). It is a thin layer over existing
+standards, so the SOW's "no new protocol" holds, and any language can implement it.
+
+| Concern | Standard reused |
+| --- | --- |
+| Payment | x402 v2 `exact` on Stellar; the manifest's payment option uses x402 `PaymentRequirements` field names |
+| Service description | JSON Schema 2020-12 with MCP tool field names (`name`, `title`, `description`, `inputSchema`, `outputSchema`) |
+| Discovery inside the 402 | x402 Bazaar extension |
+| Idempotency | IETF Idempotency-Key draft-07 (422 for a reused key, 409 while in progress) |
+| Long jobs | `202 Accepted` + `Location` + `Retry-After` |
+| Errors | RFC 9457 problem details with a stable `code` |
+| Identity | Stellar 8004 registration `services[]` entry pointing at the manifest |
+
+**What the spec adds:** the manifest, the `Job-Token` header, and the rules that bind one job to one request and
+one payment.
+
+**Main rules:**
+- The manifest is at `/.well-known/stellar-agent-services.json` by default, or any HTTPS URL the 8004
+  registration names. Job endpoints are fixed paths under one `baseUrl` on the same origin.
+- Small required core: `standard`, provider `name`, `baseUrl`, one payment option, and per service `name`,
+  `description`, `price.amount`, `inputSchema`, `outputSchema`. Clients ignore unknown fields.
+- No sync/async flag. Each service declares `charge: "on-success" | "upfront"` and `expectedDurationSeconds`.
+- The 402 challenge equals the manifest payment option plus the service price, field by field.
+- Input is validated and capacity checked *before* the 402.
+- Conformance levels: Described (C1, C6), Payable (+ C3, C4), Recoverable (+ C5), plus Registered (C2).
+
+**Ways to implement:** gateway mode (any existing HTTP API), the TypeScript library, or natively from the spec,
+checked with `verifier check`. The manifest JSON Schema and language-neutral test vectors are in
+`packages/protocol` (`schemas/`, `test-vectors/`).
+
+### 5.2 Job Recovery protocol (`docs/job-recovery.md`)
+
+The SOW names three operations.
+
+| Operation | HTTP | Notes |
+| --- | --- | --- |
+| **create-job** | `POST {baseUrl}/services/{name}/jobs` | x402-protected. Headers: `Idempotency-Key: <uuid>` (becomes the job id) and `Job-Token: <32 random bytes, base64url>` |
+| **check-status** | `GET {baseUrl}/jobs/{jobId}` | `Job-Token` required. Returns the job view: status, `charged`, receipt and timestamps |
+| **get-result** | `GET {baseUrl}/jobs/{jobId}/result` | `Job-Token` required. Returns the job view with the output |
+
+All three return the same job view: `200` when the job has finished, otherwise `202` with `Retry-After`. A client
+that sends neither header (any plain x402 client) gets a provider-generated job id and token in the create-job
+response, without the guarantee for lost responses.
+
+**Job states:** `queued → running → succeeded | failed`, plus `payment_uncertain`.
+
+**How double-charging is prevented:**
+1. **The client fixes the identity before paying.** It generates `jobId` and the token, then persists both
+   together with the binding hash *before* the first request. Because the status URL is a fixed path under
+   `baseUrl`, a lost response never loses the handle.
+2. **The provider binds the job.** `jobId → (sha256(JCS({ service, input })), sha256(token))`.
+   - Repeating create-job with the same binding returns the existing job, with no new 402 and no new charge.
+   - A different binding or token gets `422`; a request while the job is still being claimed or settled gets
+     `409` (IETF Idempotency-Key draft-07).
+   - A wrong token gets `404`, so the response does not reveal whether the job exists.
+3. **The provider binds the payment.** A unique payment fingerprint (network, payer, signed auth entry)
+   means one signed payment can buy at most one job.
+4. **Uncertain means don't pay.** If settlement times out or fails transiently, the job becomes
+   `payment_uncertain` and is never re-charged. The provider resolves it from on-chain data after every sweep,
+   and operators with `provider-kit reconcile`: the tx hash the facilitator named, or the payer's USDC
+   `transfer` events, matched to the job by the payer's signed auth entry and its nonce. "Not settled" needs the
+   expiration ledger closed and every ledger the payment could have landed in searched (docs/job-recovery.md).
+5. **Recovery never re-sends `PAYMENT-SIGNATURE`.** It only calls check-status and get-result.
+
+**When the user is charged** is set per service with `charge`:
+- `on-success`: verify → run → settle. Work that fails is never charged. The signed payment expires about
+  `maxTimeoutSeconds` after signing, so this only suits work well inside that window.
+- `upfront` (default): verify → settle → run. Expensive or long work starts only once it is paid.
+
+The **response-loss drill** is test-only, needs an explicit flag, and is off by default. The provider settles and
+persists the result, then drops the response. This is how the SOW recovery demo is produced.
+
+### 5.3 Provider Kit (`packages/provider-kit`)
+
+| Module | Responsibility |
+| --- | --- |
+| `define-service.ts` | `defineService({ name, title, description, price, charge, expectedDurationSeconds, capacity, inputSchema, outputSchema, examples, handler })`, with schema validation of input (before the 402) and output (before settling) |
+| `provider.ts` | `createProvider(config)` → `{ fetch(request): Promise<Response> }`, which wires every part together |
+| `http/router.ts` | Manifest, create-job, check-status and get-result routes, in the spec's processing order. RFC 9457 errors, body size caps, no redirects. |
+| `gateway/config.ts`, `gateway/upstream.ts` | Gateway mode: a config file describes services whose handler forwards the input to an existing HTTP API in any language |
+| `gateway/openapi.ts` | The gateway config from an existing API's OpenAPI 3 document (`provider-kit init --openapi`): its callable POST endpoints as services, schemas in JSON Schema 2020-12 |
+| `payments/x402-server.ts` | The challenge, built from the manifest, with the Bazaar extension while the header stays under 8 KiB; reading the paid request |
+| `payments/payload-checks.ts` | Local checks run before calling the facilitator: exactly one SAC `transfer(payer → payTo, amount)` on the manifest's asset, authorized by the payer's own signed auth entry and nothing else. The fingerprint is `sha256(JCS({ network, payer, nonce }))`, so re-wrapping one signed auth entry can't buy a second job. Signature validity stays with the facilitator's simulation. |
+| `payments/facilitator.ts` | The kit's own facilitator client: HTTPS-only, no redirects, deadlines (settle: `maxTimeoutSeconds` + 30 s), bounded answers, only the fields the facilitator needs; `checkFacilitator()` at startup (network, `exact`, sponsored fees) |
+| `payments/settlement.ts` | Classifies settlement as `settled` (hash, checked payer and network), `failed` (no hash and a reason from the never-submitted allowlist) or `uncertain` (everything else) |
+| `jobs/store.ts` | `JobStore` contract: atomic claim, compare-and-set transitions that never leave a final state, fingerprint uniqueness, and the queue (admission counts, FIFO starts, worker leases, sweeps); `test/job-store.test.ts` is the contract test |
+| `jobs/memory-store.ts`, `jobs/sqlite-store.ts` | Reference stores. SQLite (`node:sqlite`, WAL, fsync on commit, `BEGIN IMMEDIATE`) is shared safely by several processes on one machine. Providers may add Postgres. |
+| `jobs/runner.ts` | Both charge policies; the output and `settlingSince` are stored before settling; leased upfront workers with renewals and at most 3 starts |
+| `jobs/scheduler.ts` | Capacity (spec §5.8) on the store's queue: admission before the 402 from store counts plus local reservations, the claim under the same lock, FIFO turns for on-success jobs, lease-based workers for upfront jobs, queue positions |
+| `jobs/recovery.ts` | Sweeps at startup and every 30 s: a settlement that never answered becomes `payment_uncertain`; an on-success job whose payment expired (by ledger, or by time) fails uncharged; retention |
+| `jobs/reconcile.ts`, `payments/onchain.ts` | Decides `payment_uncertain` jobs after every sweep [J13]: finds the transaction carrying the payer's auth entry with the job's nonce (the facilitator's hash, else the payer's `transfer` events up to the expiration ledger); settled → queued or succeeded, provably not settled → failed uncharged, anything else waits |
+| `payments/chain.ts` | Soroban RPC reads (`rpc`, default the public testnet RPC) and the ledger clock: on-success deadlines from the payment's expiration ledger, and a create-job check that a signature does not expire too far out |
+| `http/rate-limit.ts` | Optional per-caller limit on create-job: `429` with `Retry-After` |
+| `http/node-server.ts` | `listen()`: Node's HTTP server for a provider, with `/healthz` and graceful close |
+| `manifest.ts` | Builds the manifest and checks it at startup with the JSON Schema and `checkManifestRules()` |
+| `registration.ts` | The 8004 registration file from the manifest [I1], and `checkRegistration()` (I1–I3, read-only), with `inspectRegistration()` also returning the file it read |
+| `validation-request.ts` | The validation request, checked before anything is signed (I1–I3, a signer the registry accepts, a validator that is not the provider itself) and sent as canonical JSON in a `data:` URI |
+| `testing.ts` | `signTestPayment()`: real x402 payments signed offline, for provider and client tests |
+| `cli/` | `serve --config` (gateway mode), `init` (a starter config, or `--openapi` from an OpenAPI document), `check` (self-check, then how agents see the provider: `cli/discovery.ts`), `try` (one paid testnet call from a throwaway payer), `trustline`, `register`, `request-validation`, `reconcile` |
+| `Dockerfile`, `schemas/gateway-config.schema.json` | The gateway image; the config file's JSON Schema |
+
+**Developer experience targets (W2 exit criteria):**
+- Library: starting from a clean machine, `npm i`, defining one service and running the server produces a
+  working paid testnet request, using only the setup guide.
+- Gateway: an existing non-TypeScript API (a small Python service) becomes a paid service with only a config
+  file and `provider-kit serve`, also from the Docker image.
+
+### 5.4 Verification, receipts, badges and Validation Registry (`packages/verifier`)
+
+**Checks** (each one records evidence):
+
+| # | Check | Pass condition |
+| --- | --- | --- |
+| C1 | Manifest | Fetched over HTTPS without redirects, schema-valid v1, size limits respected, no remote `$ref`, examples valid |
+| C2 | Identity | `agentId` exists in the 8004 Identity registry, its registration points to this manifest, and the manifest `payTo` equals the on-chain `agent_wallet` |
+| C3 | Challenge | Invalid input returns `400` before any `402`. Valid unpaid create-job returns `402` whose single `accepts` entry equals the manifest payment option plus the price. `payTo` has a USDC trustline. |
+| C4 | Paid call | Test payer pays → result matches the `output` schema; on-chain USDC `transfer` to `payTo` for the exact amount |
+| C5 | Recovery | Repeating create-job returns the same job with no second transfer; the same key with other input returns `422`; check-status and get-result work with the token and return `404` without it |
+| C6 | Hygiene | No redirects, no secrets in responses, bounded bodies |
+| C7 | Load | A burst of unpaid create-job requests is answered with `402`, `429` or `503` plus `Retry-After`, never another error or a timeout. With `--pay`, `concurrency + 1` paid jobs are each accepted or refused before settlement. |
+
+**Conformance levels** (each maps to one badge): Described = C1 + C6, Payable = + C3 + C4,
+Recoverable = + C5, Registered = C2 plus a Validation Registry record, and Load-safe = C7. `verifier check` runs the no-payment
+checks against any URL. With `--dev` it also accepts a local `http://` server (spec [M6]), so providers can test
+themselves before going live.
+
+**Verification receipt:**
+- Canonical JSON containing: standard version, provider `agentId`, manifest sha256, network, a status and
+  evidence for each check, payment tx hash, verifier address and timestamps.
+- It is stored under `evidence/receipts/` and published through the evidence page (GitHub Pages).
+
+**Badges:** SVGs derived **only** from a receipt.
+- Badge set: one per level, `Standard v1`, `Payment verified`, `Recovery verified`; plus `Load-safe` (C7) and
+  `8004 validated` (C2 and a Validation Registry record of the receipt, confirmed on chain).
+- Each badge shows the network.
+
+**Validation Registry flow** (contract read from `stellar-8004/contracts/validation-registry`):
+
+1. **Provider owner** runs `provider-kit request-validation`, which calls
+   `validation_request(caller = owner, validator_address = verifier G…, agent_id, request_uri, request_hash)`.
+   - `request_uri` is the verification request document.
+   - `request_hash = sha256(document)`, the spec-compliant `contentHash` mode of `generateRequestNonce`.
+2. **Verifier** runs the checks and calls
+   `validation_response(caller = verifier, request_hash, response = score 0–100, response_uri = receipt URL, response_hash = sha256(receipt), tag = "provider-standard-v1")`.
+3. Anyone can read the result with `get_validation_status(request_hash)` or `get_agent_validations_paginated`.
+
+`response` is higher-is-better (ERC-8004: 0 = failed, 100 = passed). Documents are hashed as
+`sha256(RFC 8785 JCS)`. Both rules are shared with the planned Stellar ERC-8126 records, so the two kinds of
+record never get mixed up in `get_summary` (docs/erc-compatibility.md, T2).
+
+Mainnet currently reports `totalValidations: 0`, so these will be among the first real Validation Registry
+records. Stellar Agent Search's deferred P3-10 (validation trust axis) can then read them.
+
+### 5.5 Example paid service (`examples/paid-service`)
+
+The example is built only with the public `provider-kit` API, so it doubles as the template for pilot providers.
+
+| Service | Charge | Price | Behavior |
+| --- | --- | --- | --- |
+| `text-stats` | on-success | 0.01 USDC | Deterministic. Answers `200` at once; failed work is never charged. |
+| `delayed-report` | upfront | 0.02 USDC | Configurable delay. Answers `202`. Used for the Job Recovery demo. |
+
+It runs on Hono with `@hono/node-server`. The `.env` holds only the `payTo` public address and the facilitator URL.
+
+### 5.6 Payment Client: decided
+
+**Decided 2026-10-21.** The design is in [docs/payment-client.md](docs/payment-client.md):
+- One core (`packages/payment-client`) that keeps every safety rule.
+- Two strategies behind it (Strategy pattern, built 2026-10-22 with the built-ins only):
+  - signers: a local key, browser wallets through Stellar Wallets Kit, then a passkey smart account
+  - payment methods: x402 `exact` on Stellar, the only one v1 allows
+  - adapters for other projects (such as Eunomia or an ERC-8196 wallet) come later as separate packages that
+    must pass the conformance checks
+- Two surfaces: a static web app for everyone and a keyed MCP server for agents.
+- Policy and journal use ERC-8196 field names. Out of the box, every payment needs approval.
+
+The core, the local-key signer, the `stellar-pay` CLI and a minimal web approval page (`apps/wallet`) work end to
+end on testnet. Settlement proof checks the `transfer` event against the approved payment ([J16]).
+
+### 5.7 Discovery integration (changes in `stellar-agent-search`, not this repo)
+
+- **Testnet discovery gap:** the default explorer (`stellar8004.com`) indexes **mainnet only**, and testnet mode
+  refuses to start without `EXPLORER_BASE_URL` (P1-07). The full "find → approve → pay → receive" flow on
+  testnet therefore needs one of:
+  - **(a, recommended)** a keyless direct-registry mode for testnet: resolve allowlisted agent IDs through
+    Soroban reads, then fetch their manifest.
+  - (b) running a testnet indexer.
+  - (c) doing the pilot on mainnet.
+- **Manifest awareness:** when an agent's service points to a Provider Standard manifest, show its price,
+  network, recovery support and badges, with the badges taken from Validation Registry reads.
+- These changes stay read-only and keyless, each in its own small PR to that repo.
+
+---
+
+## 6. Four-week schedule
+
+The sprint start date is still TBD; day 1 is the date the SOW is signed.
+
+### Week 1: Standard, payment client, first paid flow (D1)
+
+- [x] Day 1:
+  - Testnet accounts: provider `payTo` and test payer. The verifier account waits for the verifier (Week 3).
+  - USDC trustlines and testnet USDC.
+  - Facilitator `getSupported()` probe: `stellar:testnet` + `exact` is supported, and the facilitator adds no
+    limit of its own on the payment authorization window, so the spec's 30–300 range stands.
+- [x] Day 1–2: **Payment client design decision** (§5.6).
+- [x] `docs/provider-standard.md` v1 draft.
+- [x] Manifest JSON Schema, test vectors and reference checks in `packages/protocol` (canonical JSON, binding
+  hash, manifest rules, challenge check).
+- [x] Remaining protocol types (job view, job states, errors, receipts), with test vectors.
+- [x] Freeze v1 (2026-10-21, open decision 6).
+- [x] Verification receipt format defined (spec only).
+- [x] Thin provider slice: manifest, create-job with an on-success service, x402 resource server, memory store.
+- [x] Payment client, first working version: approval screen, caps, signing, journal.
+  - [x] Core, local-key signer and `stellar-pay` CLI (approval prompt, caps, journal, on-chain check).
+  - [x] Minimal web approval page (`apps/wallet`), for the D1 video.
+- [x] One successful testnet payment flow, recorded ([video, screenshots and RPC proof](evidence/d1/README.md)).
+  - [x] Testnet tx links.
+  - [x] Screenshots and the short video, captured 2026-11-06; public publication remains outstanding.
+- [ ] Start pilot outreach: shortlist 4–5 candidate providers and 6–7 users.
+
+**Exit:** spec published, approval-before-payment video, testnet tx link.
+
+### Week 2: Provider Kit (D2, part 1)
+
+- [x] Full `provider-kit`:
+  - `defineService` with schemas, checked at definition time (name, S2, S9) and in the manifest at startup
+  - strict payload checks
+  - settlement classification
+  - SQLite store
+  - background runner: leased workers, recovery sweeps, retention
+  - both charge policies
+- [x] Gateway mode: `provider-kit serve --config`, a Docker image, tested with a small Python API as upstream.
+  - `serve --config`, tested end to end with [examples/python-upstream](examples/python-upstream).
+  - Docker image (`packages/provider-kit/Dockerfile`, 295 MB): built and run against the Python API. Real testnet
+    facilitator check at startup, a paid call settled once, health check, non-root user, and the job recovered
+    from the `/data` volume after a container restart.
+- [ ] Manifest builder and 8004 registration (`provider-kit register`) on testnet.
+  - [x] Manifest builder with startup checks; `register` and `check` (reads I1–I3 from the testnet registry).
+  - [ ] Run `provider-kit register` for the sample provider on testnet, approved in the owner's wallet.
+  - [x] Approving in a wallet: `trustline`, `register` and `request-validation` open a local page (Stellar Wallets
+    Kit) where the owner's own wallet signs; `--source` keeps the Stellar CLI keychain for CI. `register` saves the
+    new `agentId` to the config. Tested on testnet end to end with `trustline`.
+- [x] `examples/paid-service` with both services, on the SQLite store.
+- [ ] Setup guide (`docs/provider-setup-guide.md`), tested on a clean machine.
+  - [x] Written for both paths.
+  - [ ] Followed on a clean machine.
+- [x] Payment-safety test suite (§7), provider side.
+- [x] Capacity (spec §5.8): per-service lanes, `429`/`503` before payment and queue positions, on a shared queue
+  with worker leases in the store, so queued `upfront` jobs survive a restart [Q4] and workers scale apart from
+  the HTTP servers (`runQueuedJobs: false` / `serve --no-workers`).
+
+**Exit:** a developer installs the kit from scratch, starts the sample provider and completes a paid request. An
+existing Python API becomes a paid service through gateway mode.
+
+### Week 3: Verification and Job Recovery (D2, part 2)
+
+- [x] Complete Job Recovery (docs/job-recovery.md):
+  - create-job, check-status and get-result
+  - `payment_uncertain`
+  - reconciliation: automatic after every sweep, and `provider-kit reconcile` (`--dry-run`, `--rpc`)
+  - the response-loss drill
+  - [x] Record the recovery demo on testnet: one interrupted job, recovered, with exactly one on-chain transfer
+    ([video, screenshots and bounded event scan](evidence/d2/README.md), 2026-11-06).
+- [x] Payment client recovery: resume from the journal, never re-sign.
+- [x] Payment client: treat `409 request_in_progress` on create-job and while polling as "ask again later".
+- [x] A ledger clock, shared by reconciliation and the kit: an on-success job's deadline from its payment's
+  expiration ledger rather than from its claim, so a payment resent late [Q8] isn't worked on after it expired.
+  It reads Soroban RPC (latest ledger, close time, average ledger duration) rather than Horizon, so one endpoint
+  serves the clock and reconciliation.
+- [x] `verifier`: checks C1–C7, conformance levels, receipt, badges, and the no-payment `check` command
+  (docs/verification.md). Paid checks prove payments on chain by the signed nonce, and that refused payments never
+  landed; receipts are stored under their own SHA-256, the on-chain `response_hash`.
+  - [x] Capture live testnet verification receipts and earned badges; retain failed and skipped checks honestly
+    ([results](evidence/receipts/README.md)). Bounded polling now lets the same uncertain job reconcile [J13].
+- [x] Validation Registry publishing: `request-validation` (provider) and `validation_response` (verifier) on testnet.
+  - [x] `verifier publish`: `validation_response` through the Stellar CLI keychain, after checking the request, the
+    receipt and the `response_uri`; the request document is defined in docs/verification.md.
+  - [x] `provider-kit request-validation`: the request document as a protocol type, JSON Schema and test vectors;
+    the command checks the registration, the signer and the validator, then the owner's wallet signs it (or the
+    Stellar CLI keychain, with `--source`).
+  - [x] Run both on testnet for registered Oracle sample agent 163; C1–C7 passed, score 100, receipt anchored
+    ([confirmed registration, request and response](evidence/validation/README.md), 2026-11-06).
+- [x] Testnet direct-registry discovery and manifest service matching reported implemented in `stellar-agent-search`
+  ([DX phase 4](docs/dx-improvements.md#phase-4-from-nothing-to-live-dev-launch-status)).
+- [ ] Confirm the released discovery path, price/network information and validation-derived badges during the pilot.
+- [ ] Pilot providers start integrating: send them the guide and template.
+
+**Exit:**
+- The sample provider has a verification receipt and a Validation Registry record (tx).
+- One interrupted job has been recovered, with exactly one on-chain transfer.
+
+### Week 4: Pilot and evidence (D3)
+
+- [ ] Two independent providers live: each verified, each with at least one paid call.
+- [ ] Five distinct users complete find → approve → pay → receive, and at least one runs a recovery.
+- [ ] Fix pilot-blocking issues and record them in the pilot report.
+- [x] Sample approval/payment and recovery videos, screenshots and payment references captured.
+- [x] Publish the evidence page, videos, payment references, anchored receipt and registry records.
+- [ ] Add the completed independent pilot report after real participant sessions.
+
+**Exit:** every row of the SOW §6.1 evidence table is linked from `evidence/README.md`.
+
+---
+
+## 7. Testing strategy
+
+**Unit:**
+- canonical JSON (key order and whitespace don't change the hash)
+- manifest schema and test vectors
+- challenge ↔ manifest matching
+- settlement classification
+- job state transitions
+
+**Payment safety:** these tests must exist before the pilot.
+- [x] A repeated create-job with the same key and input → same job, no facilitator call, no second charge.
+- [x] The same key with different input or token → `422`. A request while still claiming or settling → `409`.
+  A wrong token → `404`.
+- [x] Invalid input → `400` before any `402`.
+- [x] One signed payment presented for two jobs → rejected (fingerprint), also re-signed with the same nonce.
+- [x] A facilitator timeout or 5xx → `payment_uncertain`, never `failed`, never re-charged.
+- [x] An `on-success` handler failure or invalid output → no settlement.
+- [x] `on-success` work that outlasts the payment authorization → job failed, nothing charged.
+- [x] A client without `Idempotency-Key` and `Job-Token` → provider-generated id and token, one charge.
+- [x] A challenge whose amount, payTo, asset or network differs from the manifest → the client refuses to sign.
+- [x] A failed spending-limit check → the payment is blocked (fail closed).
+- [x] A lost response → recovery returns the stored result, with one on-chain transfer. Provider/client behavior
+  is tested offline, and [the recorded testnet demo](evidence/d2/README.md) includes a complete bounded transfer scan.
+- [x] An uncertain settlement is decided from the transaction carrying the job's nonce: another job's equal
+  transfer never counts, and "not settled" comes only after the expiration ledger closed and the whole window
+  was searched. An RPC outage, a window older than the RPC's history, or a ledger still to come leave the job
+  waiting.
+- [x] A `409` while the provider settles → the client follows the job and never signs again.
+
+**Integration (testnet, manual or CI-gated):** sample provider + verifier + payment client, end to end.
+
+**Test hygiene:** use fixed transaction timebounds in fixtures. This is the lesson from the Phase 1 timebounds
+flake.
+
+---
+
+## 8. Evidence plan (maps to SOW §6.1)
+
+| Deliverable | Evidence | Location |
+| --- | --- | --- |
+| D1 | Provider Standard v1 | `docs/provider-standard.md` |
+| D1 | Video (price, recipient, spending control, approval → payment), screenshots, testnet tx link | `evidence/d1/` |
+| D2 | Public repo, setup guide | this repo, `docs/provider-setup-guide.md` |
+| D2 | Verification receipt + badges | `evidence/receipts/` |
+| D2 | Validation Registry record (request + response tx) | `evidence/validation/` |
+| D2 | Recovery demo (video + single-transfer proof) | `evidence/d2/` |
+| D3 | Provider links, per-provider paid-call references, screenshots | `evidence/pilot/` |
+| D3 | Pilot report (what worked, failed, was fixed) | `evidence/pilot/report.md` |
+| D3 | Public evidence page | GitHub Pages from `evidence/` |
+
+Every transaction is listed with network, hash, ledger and explorer link. Testnet evidence is labeled as testnet
+everywhere.
+
+---
+
+## 9. Risks
+
+| Risk | Impact | Mitigation |
+| --- | --- | --- |
+| Payment client design not settled by W1 day 2 | Misses the D1 Week 1 output | Build the design-independent core first: policy, validation, journal |
+| No testnet 8004 indexer | Discovery step of the pilot flow doesn't work on testnet | Direct-registry testnet mode in `stellar-agent-search` (§5.7) |
+| Testnet facilitator unavailable or unsupported | No settlement | Probe on day 1. If needed, look for another facilitator or self-host a settlement path. |
+| Independent providers late or unresponsive | D3 missed | Start outreach in W1, use the template repo, offer incentives (SOW), keep a backup provider |
+| `validation_request` must be signed by the provider owner | Friction for independent providers | One-command `provider-kit request-validation`, approved in the owner's own wallet |
+| A CLI key for `payTo`, then importing it into a browser wallet to use the income | Friction and a secret key on disk | The owner's existing wallet is `payTo` and signs every owner step on a local approval page (`trustline`, `register`, `request-validation`) |
+| `stellar8004` declares stellar-sdk `^15`; x402 needs `^16.3` | Duplicate SDK copies: 18 MB and a vulnerable axios, and an XDR type mismatch if SDK objects ever cross between them | Root `overrides`, which `create-stellar-service` writes into each project. `scaffold:check` fails a project with two copies; the rehearsal warns about a plain install. |
+| Reviewers expect mainnet evidence (Phase 1 was mainnet) | Evidence questioned | Agree on testnet with the Ambassador Chapter Lead up front; mainnet is optional follow-up |
+| Users need testnet USDC | Pilot friction | Pre-fund pilot wallets from the team test account |
+
+---
+
+## 10. Open decisions
+
+| # | Decision | Owner | Needed by |
+| --- | --- | --- | --- |
+| 1 | ~~Payment client design (§5.6)~~ **Decided 2026-10-21:** docs/payment-client.md | Berkin | W1 day 2 |
+| 2 | SOW provider/user counts reading (§1.1) | Berkin + Ambassador Chapter Lead | Before sprint start |
+| 3 | **Implemented per DX phase 4:** direct Identity Registry scan on testnet; confirm the released flow in the pilot | Berkin | Pilot |
+| 4 | Testnet-only evidence accepted, or a final mainnet run | Berkin + Ambassador Chapter Lead | W2 |
+| 5 | **Released 2026-11-02:** `@stellar-agent-services/*` and `create-stellar-service`, version 0.1.0 | Berkin | Done |
+| 6 | ~~Provider Standard v1 freeze~~ **Decided 2026-10-21, frozen as drafted, except the URL:** `Job-Token` header, manifest path, `maxTimeoutSeconds` range, the URL for the schema `$id` and problem `type` values (`algorialabs.github.io/stellar-agent-services`), plus CORS as SHOULD [J17] | Berkin | W1 |
+| 7 | Shared ERC-8126/8196 conventions: score direction, tags, hashing, policy extensions (docs/erc-compatibility.md) | Berkin + ERC-8126/8196 Stellar team | W1 for hashing, W3 for validation records |

package/repository/README.md

@@ -0,0 +1,80 @@
+# Stellar Agent Services
+
+Phase 2 of [Stellar Agent Search](https://github.com/berkingurcan/stellar-agent-search). It makes it easy for
+developers to offer paid AI services on Stellar, and easy for users to find, hire and pay them safely.
+
+Stellar Agent Search finds and evaluates agents (read-only, keyless). This repository adds the provider and
+payment side:
+
+| Package | Purpose |
+| --- | --- |
+| [`packages/protocol`](packages/protocol) | Provider Standard v1 as code (manifest, jobs, receipts) |
+| [`packages/provider-kit`](packages/provider-kit) | Turn a function, or an existing API in any language (gateway mode), into a paid service: pricing, x402 USDC payments, Job Recovery, capacity and queuing |
+| [`packages/payment-client`](packages/payment-client) | Buyer side: approval, spending controls, payment, recovery (proof of concept) |
+| [`packages/verifier`](packages/verifier) | Checks a provider against the standard (C1–C7), issues verification receipts and badges, publishes to the Stellar 8004 Validation Registry. `verifier watch` answers validation requests by itself. |
+| [`packages/dev-mcp`](packages/dev-mcp) | MCP server for coding agents: spec rules, docs, manifest validation, unpaid provider checks. It never pays. |
+| [`packages/create-stellar-service`](packages/create-stellar-service) | `npm create stellar-service`: a new project (an existing API, a TypeScript or a Python service), ready to run, try and deploy |
+| [`apps/wallet`](apps/wallet) | Web page where a person approves and pays a service (testnet) |
+| [`examples/paid-service`](examples/paid-service) | Sample provider and template for pilot providers |
+| [`examples/python-upstream`](examples/python-upstream) | An existing Python API made a paid service with gateway mode |
+
+**Status (2026-11-06):** the core packages are released at 0.1.0. The kit, payment client, recovery and verifier
+are implemented. [Sample payment/recovery evidence is public](https://algorialabs.github.io/stellar-agent-services/),
+and live verification receipts and badges are captured in [evidence/](evidence/README.md). Permanent sample
+registration, an anchored validation response and the independent pilot remain. This checkout
+also enforces configured verification policies through an application-trusted source [V1]. The
+[SOW closeout guide](docs/sow-closeout.md) lists the remaining acceptance work, and
+[readiness evidence](evidence/readiness.md) records checks and release references. The full build history is in
+[IMPLEMENTATION_PLAN.md](IMPLEMENTATION_PLAN.md). Development and pilot evidence use Stellar **testnet**.
+
+To offer a service, start with [`npm create stellar-service`](packages/create-stellar-service), then:
+
+```bash
+npm create stellar-service my-service
+cd my-service
+npm run dev       # runs it, paid to a throwaway testnet account: no wallet needed yet
+npm run try       # pays for one call with test money
+npm run launch    # goes live: one approval in your wallet registers and verifies it, then Fly.io
+npm run status    # where it stands, and what to run next
+```
+
+The [provider setup guide](docs/provider-setup-guide.md) explains each step.
+
+**The standard in short:** [for people](docs/standard/README.md) and [for AI coding agents](docs/standard/README-AI.md).
+The full text is [docs/provider-standard.md](docs/provider-standard.md).
+
+## For AI coding agents
+
+- [AGENTS.md](AGENTS.md) picks a path (new service, existing API, another language, paying client, verification,
+  contributing) and names its reference, rules and definition of done. `CLAUDE.md` points to it.
+- [llms.txt](llms.txt) indexes every document, and [llms-full.txt](llms-full.txt) holds them all in one file.
+- The [Claude Code plugin](plugins/stellar-agent-services) adds a skill for each path:
+  `/plugin marketplace add AlgoriaLabs/stellar-agent-services`.
+- The [MCP server](packages/dev-mcp) answers spec questions and checks manifests and providers.
+
+## Compatibility
+
+We stay compatible with ERC-8126 (agent verification) and ERC-8196 (agent authenticated wallet). See
+[docs/erc-compatibility.md](docs/erc-compatibility.md). Copies of both specs are in [docs/references/](docs/references).
+
+## Development
+
+```bash
+npm install
+npm run typecheck
+npm test
+```
+
+Requires Node 22.13 or later (`.node-version` pins 24).
+
+## Security
+
+See [SECURITY.md](SECURITY.md). In short:
+
+- discovery and provider servers hold no keys
+- only the payment client signs, once, after explicit approval
+- nobody pays twice for one job
+
+## License
+
+MIT