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

package/repository/docs/erc-compatibility.md

@@ -0,0 +1,163 @@
+# ERC-8126 and ERC-8196 compatibility
+
+**Status:** draft. Anything marked **Proposed** still has to be agreed with the team building ERC-8126 and
+ERC-8196 on Stellar, which is a separate project with its own grant.
+
+**Specs:** [ERC-8126](references/ercs/erc-8126.md) (AI Agent Verification) and
+[ERC-8196](references/ercs/erc-8196.md) (AI Agent Authenticated Wallet). Provenance is in
+[references/README.md](references/README.md).
+
+## Goal
+
+This repository does **not** implement either ERC. The SOW also excludes "the complete ERC-8126 specification".
+The goal is narrower: when Stellar implementations of these ERCs ship, they plug into what we build now without
+breaking changes on either side.
+
+## How the layers fit
+
+| Layer | Question it answers | Score | Built by |
+| --- | --- | --- | --- |
+| Stellar 8004 (ERC-8004) | Who is this agent? | – | `stellar-8004` (exists) |
+| ERC-8126 | Is this agent safe? | risk 0–100, **lower is better** | parallel project |
+| Provider Standard verifier (this repo) | Does this service follow the standard, take payment correctly and recover jobs? | conformance 0–100, **higher is better** | this repo |
+| ERC-8196 | Is this action allowed right now? | – | parallel project (on-chain); our payment client enforces off-chain first |
+| x402 | How is the service paid? | – | public `@x402/*` packages |
+
+- **Complementary, not overlapping.** Our checks (C1–C7) test conformance, while ERC-8126 tests security risk.
+  They overlap in two places:
+  - ERC-8126 Web Application Verification touches our C1 and C6 (HTTPS, reachability).
+  - ERC-8126 Wallet Verification touches our C4 (the `payTo` wallet).
+- **No compliance claim.** We never say our receipts are ERC-8126.
+
+## Ethereum to Stellar mapping
+
+Both projects need this table. Where we pick different answers, our code and theirs stop fitting together.
+
+| ERC concept | Stellar equivalent |
+| --- | --- |
+| `uint256 agentId` | Stellar 8004 `agent_id: u32` |
+| `address` | strkey: `G…` account or `C…` contract |
+| Chain id / EIP-155 | CAIP-2 `stellar:testnet` / `stellar:pubnet` plus the network passphrase |
+| EIP-712 typed data | Soroban authorization entries for on-chain actions; SEP-53 signed messages off-chain |
+| EIP-3009 gasless USDC | x402 `exact` scheme on Stellar: a signed auth entry and a fee-sponsoring facilitator |
+| ERC-4337 smart account | Soroban custom account contract (`__check_auth`) |
+| `keccak256` | `sha256` (native in Soroban; `BytesN<32>` in the registries) |
+| Value limits in `wei` | Per-asset `i128` amounts (USDC uses 7 decimals) |
+| `agentWallet` | Stellar 8004 `get_agent_wallet(agent_id)` |
+| `eth_getCode` (ETV, SCV) | Soroban contract instance and Wasm hash; SAC or SEP-41 for tokens |
+
+ETV and SCV are Ethereum/Solidity-specific. Their Stellar versions (Soroban Wasm) are for the parallel project to
+define.
+
+## Touchpoints
+
+### T1. Agent identity and the registration file
+
+- **Same starting point.** Both projects start from `agent_id`, then the registration JSON. ERC-8126 does not
+  allow verifying from loose parameters.
+- **Proposed: `payTo` equals the on-chain `agent_wallet`.**
+  - ERC-8004 defines `agentWallet` as "the address where the agent receives payments".
+  - With this rule, ERC-8126 Wallet Verification assesses exactly the address that users pay.
+  - Our verifier enforces it in C2.
+- **Registration file fields.** The provider's registration file lists our manifest under `services`. It keeps the
+  standard ERC-8004 fields (`image`, `services[].endpoint`), so an ERC-8126 resolver finds the HTTPS endpoint
+  without knowing our manifest format.
+
+### T2. Validation Registry records
+
+The two scores run in opposite directions:
+- **ERC-8004 `response`:** 0 means failed and 100 means passed, so higher is better.
+- **ERC-8126 risk score:** 0 is the lowest risk, so lower is better.
+
+Stellar's `get_summary` with an empty tag averages *all* records for an agent. One raw risk score would therefore
+corrupt every average.
+
+**Proposed:**
+- `response` is always higher-is-better. ERC-8126 posts `100 − overallRiskScore`. The raw risk score and the proof
+  ids go in the response document.
+- Each standard uses its own tag. Ours is `provider-standard-v1`; ERC-8126 uses e.g. `erc8126` or one tag per type
+  (`erc8126-wav` and so on).
+- Response documents share an envelope:
+  - `standard`, `agentId`, `network`, `validator`, `checkedAt`
+  - `score`, `scoreDirection`
+  - `results[]`
+  - evidence links
+- Hashing is shared:
+  - `response_hash = sha256(RFC 8785 JCS(document))`
+  - `request_hash = sha256(JCS(request document))`
+  - Both projects use the same canonicalization, so a third party can recompute either hash.
+
+### T3. Reading a risk score
+
+ERC-8196 gates actions on `getLatestRiskScore(agentId)`. The payment client and Stellar Agent Search will want the
+same value.
+
+**Proposed:** the Stellar ERC-8126 project does one of two things:
+- exposes `get_latest_risk_score(agent_id) -> Option<u32>` on a Soroban contract, or
+- documents exactly how to derive it from the Validation Registry (validator address plus tag).
+
+Our code reads it through one small interface (a "risk source"), so either choice works. We don't depend on their
+code.
+
+### T4. Payment policy
+
+This is input to the payment client design, which is still open.
+
+ERC-8196's policy is close to our "spending controls": a per-transaction cap, a daily cap, a validity window,
+allow and block lists, and a verification gate. Applied to x402 on Stellar, it has four gaps that need a shared
+answer:
+
+1. **Limits are in native value (`wei`).** x402 pays USDC through the token contract's `transfer`, so the native
+   value is 0. Limits must be per asset.
+2. **`allowedContracts` would only ever contain the USDC contract.** The real payee is an argument of `transfer`.
+   We need payee allow and block lists.
+3. **The ERC-8126 gate checks the *acting* agent**, which is the policy's `agentId`. In our flow the risk that
+   matters most is the *payee* (the provider). We need a payee-side gate, e.g. a maximum provider risk or a required
+   `provider-standard-v1` record.
+4. **The name `minVerificationScore` is misleading.** It is actually a *maximum* risk score.
+
+**Proposed for the policy:** whichever design we choose, the payment client's policy uses ERC-8196 field names plus
+named Stellar extensions. The same policy can then be registered on an ERC-8196 smart account later.
+
+**Proposed for the journal:** ERC-8196 requires a hash-chained audit trail (`previousHash`). The payment client
+journal uses the same entry chain.
+
+### T5. Paying x402 services from an ERC-8196 smart account
+
+`@x402/stellar` 2.28.0 looks compatible:
+- The facilitator checks the payer's auth entries by simulation.
+- It accepts any address credential, not only `G…` accounts (`validateAuthEntries`).
+- The client signer has the SEP-43 shape (`address`, `signAuthEntry`).
+
+So, in principle, a Soroban smart account whose `__check_auth` enforces an ERC-8196 policy can pay x402 services
+with no provider-side change.
+
+The facilitator imposes these constraints:
+- the auth tree has no sub-invocations
+- signature expiry stays within its ledger bound
+- the facilitator is not in the auth entries
+
+The policy check runs inside `__check_auth`, which is outside the auth tree, so these should hold.
+
+**Not verified yet.** This needs a testnet spike, run jointly with the parallel project.
+
+## What this repository does and doesn't do
+
+**Does** (cheap, and keeps the door open):
+- C2 checks that `payTo` equals `agent_wallet` (T1).
+- Validation records are higher-is-better, use their own tag, and are hashed with JCS (T2).
+- A risk-source interface with no dependency on the parallel project (T3).
+- Payment client policy and journal formats aligned with ERC-8196, once that design is chosen (T4).
+
+**Doesn't do:**
+- ERC-8126 checks, zero-knowledge proofs (PDV) or QCV
+- an ERC-8196 contract
+- block any SOW deliverable on the parallel project's timeline
+
+## Open questions for the parallel project
+
+1. The score direction and tag names in the Validation Registry (T2).
+2. An on-chain risk-score contract, or a score derived from the registry (T3)?
+3. The Stellar profiles for ETV and SCV.
+4. The policy extensions: per-asset limits, payee lists, a payee gate (T4).
+5. Which smart-account base they will build on, and when a testnet x402 spike is possible (T5).

package/repository/docs/job-recovery.md

@@ -0,0 +1,201 @@
+# Job Recovery
+
+The normative rules are in [provider-standard.md §5](provider-standard.md#5-jobs). This document explains how they
+fit together, how the Provider Kit and the payment client implement them, and how the recovery demo is run.
+Short version: [recovery/README.md](recovery/README.md). For AI coding agents:
+[recovery/README-AI.md](recovery/README-AI.md).
+
+**Goal:** if a connection drops after payment, the user collects the same job's result without paying again.
+Nobody is charged twice for one job. A payment whose outcome is unknown is decided from the chain, never by
+charging again.
+
+## Operations
+
+| Operation | Request | Auth |
+| --- | --- | --- |
+| create-job | `POST {baseUrl}/services/{name}/jobs` | x402 payment |
+| check-status | `GET {baseUrl}/jobs/{jobId}` | `Job-Token` |
+| get-result | `GET {baseUrl}/jobs/{jobId}/result` | `Job-Token` |
+
+All three answer with the same job view (§5.5): `200` once the job is `succeeded` or `failed`, otherwise `202`
+with `Retry-After`, plus `Location` on create-job. The paths are fixed under `baseUrl`, so a client that kept
+`baseUrl`, the job id and the token can always reach the job, even if it lost every response. check-status and
+get-result never take a payment and never charge [J11].
+
+## Job identity and binding
+
+1. Before the first request, the client generates the job id (a lowercase UUID, sent as `Idempotency-Key`) and a
+   `Job-Token` (32 random bytes), and saves both. The payment client writes them to its journal and secret store
+   before it calls create-job.
+2. The provider binds the job id, permanently [J4], to:
+   - the binding hash, `sha256(JCS({ service, input }))`;
+   - `sha256(Job-Token)`. The token itself is never stored [J3].
+3. Repeated requests get these answers:
+
+| Request | Answer |
+| --- | --- |
+| create-job with the same id, binding and token | The existing job. No new `402`, and a payment the request carries is not settled [J5]. |
+| create-job with the same id and other input or another token | `422 idempotency_key_reused` [J6] |
+| create-job, check-status or get-result while the payment is still being claimed or settled | `409 request_in_progress` with `Retry-After` [J7] |
+| check-status or get-result with a wrong token, or for an unknown or expired job | `404 job_not_found`, which never says whether the job exists [J10] |
+
+A client that sends neither header (any plain x402 client) gets a provider-generated id and token in the
+create-job response [J2]. It can pay, but if that response is lost, so is the job.
+
+## States
+
+```
+(new)              → queued | running | payment_uncertain | failed
+queued             → running
+running            → succeeded | failed | payment_uncertain    (payment_uncertain: on-success only)
+payment_uncertain  → queued | succeeded | failed               (decided from on-chain data)
+```
+
+| `status` | `charged` |
+| --- | --- |
+| `queued`, `running` | `true` for `upfront`, `false` for `on-success` |
+| `succeeded` | `true` |
+| `failed` | `true` for `upfront` unless `error.code` is `payment_failed`; `false` for `on-success` |
+| `payment_uncertain` | `"unknown"`. The output is withheld [J14]. |
+
+`succeeded` and `failed` are final [J12]. Finished jobs stay retrievable for `jobs.retentionSeconds` [J15]. The
+kit also has an internal `pending` state: an `upfront` job whose settlement has not answered yet. Requests for it
+get `409`.
+
+## When the user is charged
+
+| `charge` | Order | If the work fails |
+| --- | --- | --- |
+| `on-success` | verify → work → settle | Not charged |
+| `upfront` (default) | verify → settle → work | Charged. v1 has no refunds. |
+
+A signed Stellar payment is valid up to an **expiration ledger**, about `maxTimeoutSeconds` (30–300) after
+signing [S2]. `on-success` therefore suits work well inside that window, and the kit refuses an `on-success`
+service whose `expectedDurationSeconds` is more than half of `maxTimeoutSeconds`.
+
+The kit times each `on-success` job by its payment's expiration ledger, using the ledger clock (see
+[Reconciliation](#reconciliation)). It stops 10 s before that ledger closes, to leave time to settle. A job that
+can't finish in time fails with `timeout` and is not charged, even when the client sent its payment long after
+signing [Q8]. Long or expensive work uses `upfront`: it is paid before it starts, and its place in the queue
+survives restarts [Q4].
+
+## Why nobody pays twice
+
+There are five independent guards, and each one alone stops a second charge.
+
+1. **The client fixes the identity before paying.** The job id, token and binding are journaled before the first
+   request, and `sending` is journaled and flushed before the paid request goes out. From then on the client
+   never signs for that job again: `pay()` refuses, and `recover()` only reads.
+2. **The provider binds the job.** One job id has one binding and one token, forever [J4]. A repeated create-job
+   returns the same job and never settles the payment it carries [J5].
+3. **The provider binds the payment.** The payment fingerprint is `sha256(JCS({ network, payer, nonce }))`, taken
+   from the payer's signed Soroban auth entry. Soroban accepts an (address, nonce) pair once, and the store
+   refuses a second job for one fingerprint. A signed payment buys at most one job, however it is re-wrapped
+   [P9].
+4. **Uncertain means don't pay.** When settlement times out, errors or answers something unexpected, the job
+   becomes `payment_uncertain` and is never settled again [J13]. Only a facilitator answer saying the
+   transaction was never submitted counts as failed.
+5. **Recovery never re-sends `PAYMENT-SIGNATURE`.** It calls check-status and get-result only.
+
+The client checks the receipt as well. Before it shows "paid", it confirms on chain that the transaction moved
+the approved amount from the payer to `payTo`, and it accepts one transaction as proof for one job only [J16].
+
+## Reconciliation
+
+A `payment_uncertain` job is decided from on-chain data [J13]. In the kit, `jobs/reconcile.ts` applies the
+decision and `payments/onchain.ts` does the lookup.
+
+**What identifies the payment.** The amount and recipient can't: the same payer may pay the same provider the
+same price for several jobs. Instead the kit looks for the successful transaction that carries the payer's signed
+auth entry **with the job's nonce**, which the provider stored when it claimed the job. Soroban accepts that pair
+once, so that transaction is the job's payment, and no other transaction can be.
+
+**Where it looks.**
+
+1. The transaction hash the facilitator named, if there is one.
+2. Otherwise, or if that transaction failed (a facilitator may retry), the USDC `transfer` events from the payer
+   in every ledger the payment could have landed in: the 320 ledgers up to its expiration ledger. Those cover
+   every possible ledger, because the provider and the facilitator both refuse a signature that expires more than
+   `maxTimeoutSeconds` (at most 300) of ledgers after verification, and a ledger takes at least a second.
+
+**What it decides.**
+
+| Found | Decision | The job becomes |
+| --- | --- | --- |
+| A successful transaction that carries the payment, with its `transfer` event | settled | `upfront`: `queued` with the receipt, and a worker runs it. `on-success`: `succeeded` with the receipt; the output was stored before settling. |
+| Nothing, after the expiration ledger closed and every ledger of the window was searched | not settled | `failed` with `payment_failed`, `charged: false` |
+| Anything less | undecided | Stays `payment_uncertain` |
+
+"Undecided" covers a payment that can still land (its expiration ledger hasn't closed), a window older than the
+RPC's history, an RPC error, and a transaction that used the payment but shows no matching transfer. The job
+waits. Nothing is decided from a guess.
+
+**Who runs it.**
+
+- The provider itself, after every recovery sweep (every 30 s), when it has a Soroban RPC: `rpc` in
+  `createProvider()`, or `rpcUrl` in a gateway config. Testnet defaults to the public RPC. Mainnet has no public
+  RPC, so set your own.
+- The operator, with `provider-kit reconcile`:
+
+```bash
+provider-kit reconcile --config provider.config.json --dry-run   # what would change
+provider-kit reconcile --config provider.config.json             # decide
+provider-kit reconcile --store ./jobs.sqlite --network testnet   # a library provider's store
+```
+
+The command reads the chain and writes only the job store. It is safe to run next to a running provider, and it
+exits 1 while any job is still undecided. `--rpc <url>` uses another RPC, such as one that keeps more history.
+
+Every update is compare-and-set from `payment_uncertain`. A late facilitator answer, another process or a second
+run can't overturn a decision, and they all read the same chain.
+
+**The ledger clock.** The same RPC gives the kit a clock on ledgers (`payments/chain.ts`): the latest ledger, its
+close time, and the average ledger duration over the last 100 ledgers. The clock is used to:
+
+- time `on-success` jobs (see [When the user is charged](#when-the-user-is-charged));
+- let the recovery sweep fail an `on-success` job, uncharged, as soon as its payment's expiration ledger has
+  passed;
+- let create-job refuse a payment that expires too far out.
+
+When the RPC is slow or down, all three fall back to the claim time plus `maxTimeoutSeconds`, and payments keep
+working.
+
+## Clients
+
+The payment client (`packages/payment-client`) recovers like this:
+
+- `pay()` journals `sending` before it sends the paid request. If that request fails in transit, the journal
+  marks the job `uncertain`, and `PaymentUncertainError` says to recover the job, never to pay again.
+- A `409 request_in_progress` means the provider holds the payment and is still settling it. The client polls
+  get-result at the provider's `Retry-After` until it has a job view, for up to `followSeconds`. If settlement
+  takes longer, it hands the job back for `recover()`.
+- `recover(jobId)` (`stellar-pay recover <job-id>`) reads the job id and token from the journal and calls
+  get-result. It never signs.
+- A `payment_uncertain` job comes back at once. Only the provider's reconciliation decides it, so polling doesn't
+  help; recover the job again later.
+
+## Response-loss drill
+
+The SOW recovery demo needs a response lost after a real payment. The kit has a test-only switch for this:
+`loseCreateJobResponse: true`, or `DRILL_LOSE_RESPONSE=1` in the example provider. With it, the provider verifies
+the payment, claims the job, settles and stores the result, then drops the create-job response. It is off by
+default. Never enable it in production.
+
+To run the demo on testnet:
+
+```bash
+# 1. The example provider, with the drill on (after npm install && npm run build at the root)
+cd examples/paid-service
+DRILL_LOSE_RESPONSE=1 PAY_TO=G... npm start
+
+# 2. Pay for a job. The response is lost after the payment.
+MANIFEST=http://localhost:8787/.well-known/stellar-agent-services.json
+npx stellar-pay pay $MANIFEST text-stats '{"text":"lost and found"}' --dev
+#    ⚠ ... The payment may have gone through: recover job <job-id>, do not pay again.
+
+# 3. Collect the result without paying
+npx stellar-pay recover <job-id> --dev
+```
+
+The evidence is the recovered result, plus the payer's account on stellar.expert showing exactly one USDC
+transfer for the job.

package/repository/docs/payment-client.md

@@ -0,0 +1,290 @@
+# Payment Client: design
+
+> Status: **accepted** (2026-10-21). A proof of concept of the core, the local-key signer and a CLI is in
+> [packages/payment-client](../packages/payment-client), and a minimal web page on the same core is in
+> [apps/wallet](../apps/wallet) (2026-10-22). IMPLEMENTATION_PLAN.md §5.6 and principle 3 follow this design.
+
+## Who it is for
+
+- **Developers and their agents** in Claude Code, Codex or their own code. The agent finds and pays services
+  on its own, inside a budget the human set.
+- **Non-technical users** who open a web page, pick a service, fill in a form and pay, with no seed phrase,
+  CLI or browser extension required.
+
+The aim is a product people would use after the grant, not just a demo for the SOW: **a wallet for AI
+agents, with spending rules set by a human**. It is the demand side of the Provider Standard.
+
+## Fixed requirements
+
+- Wallet separation: keys never touch discovery or provider code.
+- Explicit approval of the service, price, recipient, asset, network and when the user is charged (`charge`).
+- Spending controls: a per-payment cap and a rolling budget. A failed limit check blocks the payment.
+- Challenge validation against the approved manifest (provider-standard.md [P4], [P7]).
+- Durable journal before sending: job id, Job-Token and binding hash. Never re-sign the same job.
+- Recovery through check-status and get-result only.
+- On-chain settlement proof before showing "paid": the `transfer` event matches the approved payment
+  (provider-standard.md [J16]).
+- No custody: we never hold a user's key on a server (SOW out of scope, and a regulatory burden).
+
+## Decision
+
+### Shape: one core, two strategies, two surfaces
+
+```
+   Web app (everyone)              MCP server (agents)
+   browse · form · approve ·       find · quote · pay · status ·
+   budget · history · recover      result · budget
+              │                            │
+              └──────────┬─────────────────┘
+                         ▼
+             payment-client core (TypeScript, no UI)
+   manifest → checkChallenge → pick method → policy + budget → approve → sign → journal → send → confirm
+                │                                                           │
+                ▼                                                           ▼
+   PaymentMethod  (how a payment is made)                     Signer  (who holds the key)
+   ┌──────────────────────────────┐                ┌──────────────┬──────────────────┬──────────────────┐
+   │ x402 exact on Stellar (USDC) │                │ local key    │ Stellar Wallets  │ smart account:   │
+   │ later: other schemes/assets  │                │ (dev, CI,    │ Kit: Freighter,  │ passkey owner +  │
+   │ once the standard has them   │                │  allowance)  │ xBull, Lobstr, … │ scoped agent key │
+   └──────────────────────────────┘                └──────────────┴──────────────────┴──────────────────┘
+```
+
+- **Core** (`packages/payment-client`): everything that has to be right for money to be safe. It has no UI and
+  no key storage, and the same code runs in Node and the browser.
+- **Signers** plug in behind one interface, so the core never sees how a key is held.
+- **Payment methods** plug in behind another, so a new way to pay never touches the safety rules. See
+  [Strategies](#strategies-signers-and-payment-methods).
+- **Web app** (`apps/wallet`, static, no backend): the main UI for everyone, and what the D1 video shows. The
+  minimal page is built (2026-10-22): a test wallet, the form from the schema, the approval screen, spending
+  limits, recent payments and recovery, with the local-key signer.
+  - Turns each service's `inputSchema` into a form, so any provider is usable with no frontend work.
+  - Shows price, payee, verification badges and `charge` on one approval screen.
+  - Budget settings, history with explorer links, and a "recover job" button.
+- **MCP server** (`packages/payment-mcp`): a separate server with its own key, apart from the read-only search
+  server. Inside the budget it pays without asking. Above the budget it asks for approval, through MCP
+  elicitation or a link to the web app.
+
+### Where keys live
+
+| Key | Who holds it | Can do |
+| --- | --- | --- |
+| Owner key | The human: a passkey (Face ID / Touch ID) or Freighter | Anything: fund, set and revoke policies, approve large payments |
+| Agent key | The MCP server or SDK, on the developer's machine | Only what the policy allows |
+| — | Our servers | Nothing. There is no key on any server. |
+
+The agent key is what lets an agent pay without a prompt, so how much damage it can do has to be limited:
+- **Weeks 1–2: allowance wallet.** The agent key controls a separate `G…` account that the owner tops up with
+  a small amount. The client enforces the policy off chain. The most it can lose is that account's balance.
+- **Target: smart account.** The owner's passkey and the agent key are both signers on one Soroban smart
+  account, whose `__check_auth` enforces the agent's policy on chain. Even a compromised agent machine can't
+  spend beyond the policy. Contract accounts hold USDC without a trustline, which removes a step for
+  non-technical users.
+
+### Strategies: signers and payment methods
+
+**Built 2026-10-22**, with the built-ins only (`packages/payment-client/src/strategies.ts`).
+
+The core uses the Strategy pattern on two independent axes. Other Stellar wallets and payment infrastructure
+can then be plugged in later without changing the core: ours, existing projects such as Eunomia or an
+ERC-8196 wallet, or new ones. Any signer works with any method that supports it.
+
+```ts
+/** Who holds the key: the SEP-43 shape @x402/stellar signs with. */
+interface Signer {
+  address: string;                       // G… or C…
+  signAuthEntry: SignAuthEntry;
+  signTransaction?: SignTransaction;
+  /** A policy wallet's remaining on-chain budget for `asset`, in base units. Undefined: no limit. */
+  budget?(network: StellarNetwork, asset: string): Promise<string | undefined>;
+}
+
+/** How an x402 challenge entry is paid, and how that payment is proven. */
+interface PaymentMethod {
+  id: string;                            // "x402-exact-stellar", journaled with each payment
+  matches(requirements: PaymentRequirements): boolean;
+  createPayload(requirements: PaymentRequirements, signer: Signer): Promise<SignedPayload>;
+  confirm(transaction: string, expected: ExpectedPayment): Promise<Confirmation>;
+}
+```
+
+The built-ins are `localKeySigner(secret, network)` and `x402ExactStellar({ rpcUrl })`.
+`new PaymentClient({ signer, methods })` uses `[x402ExactStellar()]` when `methods` is not given.
+
+**The core keeps every safety step; adapters can't skip them.** For every signer and method:
+
+1. `checkChallenge()`: the challenge equals the manifest's payment option [P4].
+2. The first installed method whose `matches()` is true pays. If none matches, or `matches()` throws, the
+   payment is refused before anything is signed.
+3. The terms the user approves (network, asset, amount, payTo) come from the challenge entry, never from an
+   adapter, so no adapter can change them.
+4. The spending policy applies, and so does a policy wallet's `budget()`. A budget that is too low, can't be
+   read, or isn't in base units blocks the payment (fail closed). Both run again inside `pay()`.
+5. Approval, then journal `approved`.
+6. `createPayload()` signs. Only one `pay()` per job runs at a time, so a slow wallet popup can't lead to a
+   second signature. If the wallet does not sign, the core journals `refused`. Nothing was sent, so the user
+   can try again.
+7. Journal `sending` with the terms, the payer and the method id, and flush it. Only then send.
+8. The method recorded in `sending` confirms the payment against the journaled terms. If that method is not
+   installed, or it throws, the result is "not confirmed" with a reason, never "paid".
+
+**Conformance checks** (`@stellar-agent-services/payment-client/conformance`). The core enforces the steps
+above whatever is plugged in, so these checks cover what only an adapter can get right. They work with any
+test framework.
+
+| For | Checks |
+| --- | --- |
+| Signers: `signerConformance()` | Has a Stellar `G…` or `C…` address. Signs an auth entry as its own address. For a `G…` key, the signature verifies against it. `budget()`, if present, reports base units. |
+| Payment methods: `paymentMethodConformance()` | Has a stable id. Matches its own entry, but not an unknown scheme, an unknown network or a malformed entry. Confirms a settled payment, but not the same transaction with another payee, amount, asset or payer. |
+
+The built-ins pass them, and the test suite also checks that they fail broken adapters.
+
+**Adapters and trust levels.** An adapter for another wallet or payment infrastructure lives in its own package
+(`signer-<name>` or `method-<name>`). It depends on the core's types, and the core never depends on it. Users
+see how far we vouch for each one:
+
+| Level | Meaning | Shown as |
+| --- | --- | --- |
+| Built-in | Ours, in this package: `localKeySigner`, `x402ExactStellar` | No label |
+| Verified | Passes the conformance checks, and we reviewed it | A "verified" badge |
+| Community | Anyone's adapter that we have not reviewed | A warning at setup |
+
+A wallet's own security, such as how it stores its key, stays its own responsibility. The core guarantees only
+that what leaves through it is what the user approved.
+
+How to build, test and submit an adapter, and what we and the integrator each need, is in
+[client-integration/README.md](client-integration/README.md) (for AI agents:
+[README-AI.md](client-integration/README-AI.md)).
+
+**Integrations, later.** None is built yet. Each will be its own package.
+
+| Integration | Slot | Status and what to check first |
+| --- | --- | --- |
+| [Stellar Wallets Kit](https://stellarwalletskit.dev): Freighter, xBull, Lobstr, Albedo, Hana, … | Signer | Week 1 spike: which wallets' `signAuthEntry` works with `@x402/stellar` |
+| Passkey smart account (OpenZeppelin) | Signer, with `budget()` from its policy | Week 3 spike: a `C…` account paying through the facilitator |
+| [Eunomia](https://github.com/eunomia-finance/eunomia) treasury | Signer with `budget()` if its treasury can authorize the SAC `transfer` that x402 `exact` uses; otherwise a payment method, which needs a Provider Standard change | Testnet only. Read its `packages/x402` first. |
+| ERC-8196 policy wallet (a parallel project) | Signer with `budget()` | In development. Our policy and journal already use ERC-8196 field names. |
+| Other x402 schemes (such as `upto`) or other assets | Payment method | Each needs a Provider Standard change and a provider that offers it |
+
+### Policy (ERC-8196 field names plus Stellar extensions)
+
+| Field | Meaning | Default |
+| --- | --- | --- |
+| `policyId`, `ownerAddress`, `agentAddress` | ERC-8196 | — |
+| `agentId` | The agent's Stellar 8004 id, if it has one | unset |
+| `allowedActions` | `["x402.pay"]` | — |
+| `allowedContracts` / `blockedContracts` | The asset contract (USDC SAC) | USDC only |
+| `maxValuePerTx`, `maxValuePerDay` | In the asset's base units, not a native value | 0.10 / 1.00 USDC |
+| `validAfter`, `validUntil` | ERC-8196 | now / +30 days |
+| `minVerificationScore` | ERC-8196 name: maximum allowed provider risk score (0–100, lower is safer), from a trusted source | unset |
+| `stellar.asset` | The one asset the limits apply to | USDC |
+| `stellar.payees` | `{ allow?, block? }` lists of `payTo` addresses, since the real payee is an argument of `transfer` | unset |
+| `stellar.minProviderLevel` | The lowest `provider-standard-v1` conformance level a payee must have | unset (pilot) |
+| `stellar.autoApproveUpTo` | Payments at or below this amount, and inside the limits, need no prompt | **0: approve every payment** |
+
+`policyHash = sha256(JCS(policy))`. Every journal entry and every approval names the policy hash it ran under.
+Out of the box, every payment asks for approval, which is what the SOW requires. Paying without a prompt is
+something the owner turns on.
+
+### Verification source
+
+The core enforces configured `minVerificationScore` and `stellar.minProviderLevel` at quote time and again before
+signing [V1]. Missing or invalid evidence blocks the payment, including when the configured limit is zero. When
+both limits are unset, no verification read is needed.
+
+`PaymentClientOptions.verificationSource` is application-trusted code implementing:
+
+```ts
+interface VerificationSource {
+  read(subject: VerificationSubject): Promise<ProviderVerification | undefined>;
+}
+```
+
+The subject contains `network`, `payTo`, `manifestUrl`, `manifestSha256` (RFC 8785 canonical JSON) and optional
+`agentId`. The result repeats those fields and adds RFC 3339 `checkedAt` and `expiresAt`, plus optional
+`riskScore` (0–100, lower is safer) and `level` (0–3). The core rejects a different subject, a future check, expired
+evidence or an invalid metric. Each configured restriction requires its own metric.
+
+The source authenticates the evidence: trusted validator selection, registry reads, receipt hashes and the
+validity period it accepts. Its network calls must have deadlines. A raw receipt, a provider's badge or a score
+copied from a manifest is not an authenticated source. No built-in registry/risk-source adapter exists yet.
+
+`minVerificationScore` preserves ERC-8196's maximum-risk meaning despite its name (erc-compatibility.md T4).
+Do not compare it directly with the Provider Standard receipt's higher-is-better `score`.
+
+The web page and CLI do not install a source. Their default policies leave both restrictions unset; importing a
+policy that sets them blocks new payments until a source is installed. Recovery remains available without a
+verification read, because collecting a paid result never requires another payment [J11], [J13].
+
+### Journal (ERC-8196 hash-chained audit trail)
+
+- One entry per step: `intent`, `approved` or `refused` (with the policy rule that refused), `sending`,
+  `settled` or `uncertain`, `recovered`, `result`.
+- Each entry has `seq`, `previousHash`, `policyHash`, `jobId`, `service`, `baseUrl`, `bindingHash`, `amount`,
+  `payTo`, the payment method and, when known, the transaction hash. `hash = sha256(JCS(entry))`.
+- `sending` is written, and flushed to disk, **before** the paid request goes out. Recovery starts from the
+  last `sending` with no `settled` or `result` after it, and never re-signs that job.
+- Job tokens are secrets, so they are stored next to the journal, not in it. The journal can then be exported
+  or anchored without exposing them.
+- Storage is a file in Node (the `./node` entry point) and IndexedDB in the browser (`./browser`, written with
+  strict durability). A journal has one writer, so the web app runs in one tab at a time. Anchoring a Merkle root
+  on chain is later work.
+
+### One payment, step by step
+
+1. Fetch the manifest and validate it (the protocol package).
+2. Build the job: `jobId`, `Job-Token` and binding hash. Journal `intent`.
+3. Call create-job without paying and get the 402. `checkChallenge()` against the manifest, and pick the
+   payment method that matches it. A violation, or no matching method, refuses.
+4. Policy check, plus the wallet's own budget for a policy wallet. If either fails, journal `refused` and
+   stop (fail closed). If the amount is above `autoApproveUpTo`, show the approval screen. `decline()` journals
+   `refused` and never signs.
+5. Journal `approved`, sign, then journal `sending` and send. A busy provider (`429` or `503`, spec §5.8) answers
+   before it takes the payment: the client waits out `Retry-After` and sends the same signed request again, while
+   the payment is still valid and for at most `busyWaitSeconds`. If the provider stays busy, it journals `failed`
+   with `charged: false`. The unpaid request in step 3 is waited out the same way.
+6. Get the job view. Confirm the USDC `transfer` on chain before showing "paid", then journal `settled`.
+7. On `202`, or if the connection drops: check-status, then get-result, never paying again, at the pace the
+   provider's `Retry-After` sets. A `409 request_in_progress` means the provider holds the payment and is still
+   settling it: the client keeps polling, and hands the job back for `recover()` if settlement outlasts
+   `followSeconds`. By default a job marked `payment_uncertain` comes back at once. With
+   `followPaymentUncertain: true`, the client keeps reading that same job within `followSeconds`, at the
+   provider's `Retry-After` pace, while provider reconciliation decides its payment from the chain [J13].
+   It never signs or submits another payment while waiting [J11]. `provider-kit try` enables this bounded wait.
+
+## Sprint plan
+
+| Week | Build | Shows |
+| --- | --- | --- |
+| 1 | Core (policy, journal, x402 flow, recovery skeleton), local-key signer, a minimal approval page. Spike: Stellar Wallets Kit, listing the wallets whose `signAuthEntry` works with `@x402/stellar`. | The first paid testnet transaction; the D1 video of the approval screen |
+| 2 | Web app v1: form from schema, approval, budget, history. MCP server: paying inside the budget, approval above it. | Developers and non-technical users can both run the flow |
+| 3 | Recovery in both surfaces. Spike: a passkey smart account paying an x402 service through the facilitator. | The recovery demo |
+| 4 | Pilot. If the spike passed, non-technical pilot users get passkey wallets. | Five user flows |
+
+The smart account is the flagship, but no SOW deliverable depends on it: the allowance wallet and Freighter
+cover the sprint whatever the spike shows.
+
+## Risks and open points
+
+- **Browser calls need CORS.** The web app calls providers straight from the browser. Provider Standard v1
+  makes this a SHOULD ([J17]) and Provider Kit turns it on by default. A provider without CORS is reachable
+  only through the MCP server or SDK.
+- **Browser wallets:** whether each wallet's `signAuthEntry` output fits what `@x402/stellar` expects is
+  unverified (Week 1 spike, through Stellar Wallets Kit). Freighter is the first to test. Fallback for the D1
+  video: the local-key signer behind the same approval page.
+- **Smart account x402 payments** are unverified (erc-compatibility.md, T5). We use an existing audited
+  smart-account contract, such as OpenZeppelin's Stellar smart accounts, rather than writing our own. Building
+  an ERC-8196 contract stays with the parallel project.
+- **Moving money in and out** for non-technical users on mainnet: many exchanges can't send to a `C…` address.
+  On testnet we pre-fund pilot wallets.
+- **Principle 3** (IMPLEMENTATION_PLAN.md) now reads: the user approves each exact payment, or the payment
+  fits a budget the user explicitly granted.
+
+## Options considered
+
+| Option | Why it was not chosen alone |
+| --- | --- |
+| Node library + CLI with an encrypted keystore | Fine for developers, unusable for non-technical users. It survives as the core plus the local-key signer. |
+| Keyed MCP server with elicitation | Agents only. It survives as one of the two surfaces. |
+| Browser page with Freighter | Needs an extension, and every payment needs a human, so agents can't act on their own. It survives as one signer, through Stellar Wallets Kit. |
+| Payment methods as separate options (`createPayload`, `confirmPayment`, as in the first PoC) | Nothing tied a method's payload to its proof, so a new method could pair them wrongly. Replaced by `PaymentMethod` on 2026-10-22. |
+| Hosted wallet that holds keys | Custody, which is out of scope and a regulatory burden. |