# Stellar Agent Merchant Lab

**Independent Stellar testnet merchant for reproducible agent purchase validation.**

Merchant Lab is the seller-side counterpart to Stellar Agent Spend Hub. An agent discovers resources through MCP, receives a machine-readable quote, requests a purchase URL, handles an MPP `402 Payment Required` challenge, and receives a resource plus a privacy-safe merchant receipt.

The local mode is explicitly simulated. It never emits a transaction hash or claims settlement. Real testnet settlement activates only with official Stellar MPP configuration, a separate merchant account, and atomic Upstash storage.

## Why a separate project

A buyer paying a seller in another repository, process, deployment, and Stellar account proves more than an application calling itself. Merchant Lab creates that independent trust boundary and doubles as a reusable Provider Kit acceptance harness.

```mermaid
flowchart LR
  Agent["AI agent"] --> MCP["Merchant MCP quote"]
  MCP --> URL["Purchase URL"]
  URL --> Challenge["MPP 402"]
  Challenge --> Hub["Spend Hub policy"]
  Hub --> Human["Human confirmation"]
  Human --> Merchant["Merchant USDC account"]
  Merchant --> Delivery["Resource and receipt"]
```

## Current capabilities

- Three machine-purchasable resources priced from `0.001` to `0.01 USDC`.
- Provider definition at `/.well-known/agent-provider.json`.
- MCP stdio and stateless Streamable HTTP transports.
- Official Stellar MPP Charge integration for testnet USDC.
- Local `402 -> credential -> delivery -> receipt` simulation.
- One-time local credentials and replay rejection.
- Eight adversarial scenarios for buyer-policy tests.
- Sanitized merchant receipts with no PII, secrets, XDR, or fake hashes.
- Stateless checksummed simulated receipts that survive Vercel cold starts.
- Independent buyer script and ten automated tests.
- Zero known npm vulnerabilities.

## Quick start

```powershell
npm install
npm run qa
npm run build
npm run dev
```

Open `http://localhost:4180`.

In another terminal:

```powershell
npm run demo:buyer -- --resource=market-signal --yes
```

Without `--yes`, the buyer stops at the human-confirmation boundary.

## Public interfaces

| Interface | Purpose |
| --- | --- |
| `GET /.well-known/agent-provider.json` | Machine-readable provider definition |
| `GET /api/catalog` | Resource catalog and purchase URLs |
| `GET /.well-known/legal-context.json` | LCP terms and verifiable ATR hash |
| `GET /api/resource/:id` | MPP-protected delivery |
| `GET /api/scenarios` | Valid and adversarial buyer tests |
| `GET /api/receipts/:id` | Sanitized merchant evidence |
| `GET /api/health` | Public readiness without secrets |
| `POST /mcp` | Stateless MCP Streamable HTTP |
| `npm run mcp:serve` | Local MCP stdio server |

## MCP tools

- `list_resources`
- `quote_resource`
- `list_test_scenarios`
- `get_merchant_receipt`

There is no MCP payment-execution tool. The MCP server quotes resources; Spend Hub owns policy and confirmation.

## Test scenarios

- `happy`
- `over-budget`
- `wrong-recipient`
- `wrong-asset`
- `wrong-network`
- `expired`
- `unavailable`
- `delivery-failure`

Only `happy` is executable. Adversarial scenarios generate non-chargeable challenges or failures for buyer validation.

## Real Stellar testnet mode

Configure private Vercel environment variables:

- `MERCHANT_SIMULATION_ENABLED=false`
- `MPP_ENABLED=true`
- `MPP_STELLAR_RECIPIENT=<merchant G address>`
- `MPP_SECRET_KEY=<32+ random characters>`
- `UPSTASH_REDIS_REST_URL`
- `UPSTASH_REDIS_REST_TOKEN`

Server-side public configuration:

- `PUBLIC_BASE_URL`
- `MPP_NETWORK=stellar:testnet`
- `MPP_PRICE_USDC=0.01`
- `STELLAR_HORIZON_URL`
- `SOROBAN_RPC_URL`

No buyer secret belongs in this project or Vercel deployment.

## Acceptance gate

Real evidence requires:

1. A distinct merchant testnet account and USDC trustline.
2. Official MPP challenge for the quoted resource.
3. Spend Hub buyer validates price, recipient, asset and network.
4. Human confirmation occurs before signing.
5. Merchant receives USDC and delivers the resource.
6. Merchant and buyer receipts reference the same public hash.
7. Replay produces no second debit.
8. Pending/simulated evidence never contains a hash.

See [architecture](./docs/architecture.md), [threat model](./docs/threat-model.md), and [deployment runbook](./docs/deployment.md).