proxy-shopping: buy anywhere with crypto through a proxy shopper

proxy-shopping-web

Buy from cash-only shops with crypto, or earn as a proxy shopper: the browser app, guided demo, TypeScript protocol library and MCP server of proxy-shopping, a P2P network where a local shopper buys for remote users who pay through a 2-of-3 escrow with timelocks. Agents: MCP server io.github.pad01g/proxy-shopping (packages/mcp), skills npx skills add pad01g/proxy-shopping-go, AGENTS.md; overview for machines: https://pad01g.github.io/proxy-shopping-docs/llms.txt.

Documentation in 14 languages: https://pad01g.github.io/proxy-shopping-docs/

Browser side of proxy-shopping (spec: ../proxy-shopping-go/docs/spec.md, lab: docs/lab.md there).

packages/core   @proxy-shopping/core — protocol library (TypeScript, ESM, browsers and Node 22)
apps/web        React + Vite single-page app for every role (Japanese UI)
apps/demo       the lab's integrated demo page: every role with its own key in one browser, a guide per scenario
scripts/        docker helpers for integration and browser tests

Host tools are not required; everything runs in docker.

# install, build, unit tests
docker run --rm -v "$PWD":/src -v ps-npm:/root/.npm -w /src node:22-bookworm npm ci
docker run --rm -v "$PWD":/src -v ps-npm:/root/.npm -w /src node:22-bookworm npm run build
docker run --rm -v "$PWD":/src -v "$PWD/../proxy-shopping-go":/proxy-shopping-go:ro -v ps-npm:/root/.npm -w /src node:22-bookworm npm test

# integration: bitcoind signet + anvil (lab contracts) + nostr-rs-relay
scripts/integration.sh
# the built web app in Chromium against a mini lab (TS shopper, faucet, escrow …)
scripts/e2e-web.sh
# the demo in mock mode (GitHub Pages build) in Chromium: every scenario, nothing leaves the page
scripts/e2e-demo-mock.sh

# web image (config.json is mounted at runtime)
docker build -f apps/web/Dockerfile -t proxy-shopping-web .
docker run -p 8080:80 -v $PWD/config.json:/usr/share/nginx/html/config.json:ro proxy-shopping-web

Mounting ../proxy-shopping-go read-only lets the unit tests check docs/test-vectors.json and lab/keys/public.json. Without the vectors file npm test fails, so CI cannot pass silently; set SKIP_VECTORS=1 to run the other tests without it.

apps/demo

Try it in your browser: https://pad01g.github.io/proxy-shopping-web/ (everything simulated in the page). That build runs in mock mode (?mock=1, header switch モック / Mock): the relays, the BTC chain (with script checks), a real EVM with the lab's Safe and escrow-module bytecode, the faucet, the rates, the shops and the shopper-1 node run inside the browser (a SharedWorker shared by all windows), while the four roles use core's real clients. Details, what is simulated and its limits: apps/demo/README.md. The mock e2e (all scenarios, English, separate windows, no request leaving the page): scripts/e2e-demo-mock.sh; Pages is deployed by .github/workflows/pages-demo.yaml.

The integrated demo for the docker compose lab (../proxy-shopping-go, compose service demo, http://localhost:8888/; usage in ../proxy-shopping-go/docs/lab.md「デモ画面」). User, escrow, operator and coordinator each have their own key (localStorage, lab only) and their own Session + client in the page; the shopper is the lab's Go node. A guide walks through seven scenarios (normal BTC / USDC, dispute refund, sold out, risky shop, fraudulent escrow, T2 refund); ?role=user / ?role=escrow,operator,coordinator runs only those roles in a window. The page is in Japanese or English (header switch 日本語 / English, kept in localStorage; ?lang=en|ja overrides it): one message catalog per language in apps/demo/src/i18n (ja.ts defines the keys, en.ts must match them), core's timeline lines are rendered from their kind. Protocol logic is core's (UserClient, EscrowClient, OperatorClient, CoordinatorClient); the page wires them over core's MappedTransport (logical relay URLs such as wss://relay-1.test stay protocol-visible, the connection goes to the demo server's /relay-1).

docker build -f apps/demo/Dockerfile -t proxy-shopping-demo .   # static files; the lab mounts its nginx.conf + demo-config.json
DEMO_SERVER=http://localhost:8888 npm run dev -w @proxy-shopping/demo   # dev server proxying to a running lab demo server

Scenario steps are data (apps/demo/src/scenarios); test ids in apps/demo/TESTIDS.md; the e2e that follows the guide is ../proxy-shopping-go/e2e/src/demo (docker compose run --rm runner demo).

@proxy-shopping/core

Entry points: @proxy-shopping/core (portable), /node (+ FileStorage), /browser (+ IndexedDBStorage), /testing (in-memory relays/chain, scripted shopper, createWorld), /testing/node (bitcoind RPC + Esplora shim). Build output with declarations is in dist/.

Notes

• The mnemonic is stored in the origin's IndexedDB encrypted with a passphrase (PBKDF2-SHA256, 600k iterations, AES-GCM via WebCrypto); plaintext only if the user explicitly opts out at onboarding. WebCrypto needs a secure context (https or localhost) — scripts/e2e-web.sh forwards localhost:8080 in the browser container for that.
• Funds never move without a click and an in-page confirmation (fund, resume funding, release, countersign, refunds). The shopper's cooperative refund is shown for review, never auto-signed. Terminal states (completed, settled, refunded) wait for the chain, also after our own broadcast (BTC /tx/{txid}/outspend/{vout}; USDC: Safe balance below lock_amount and a receipt with a Transfer out of the Safe — anyone can send dust to a Safe, §4.8).
• Funding persists every transaction before it is sent (BTC txid + raw tx; EVM: signed locally, hash + raw tx stored, then sent), so an interrupted funding is resumed with the same transactions, never paid twice.
• The escrow opens a case only when a notice / dispute names a request whose request + quote recompute to the funded output (P2WSH, or the Safe with its owners / module configuration) on chain (§4.7); its ruling fee is exactly dispute_fee_bps of what is split, and it owes rulings only for upfront fees ≥ its own published minimum.
• config.json fields beyond the endpoints: timelock_policy (§4.5.1; names as in proxy-shopping-go/lab/web-config.json, spec defaults when absent), max_clock_skew_seconds (§4.5.1: largest accepted difference between the chain's clock — BTC tip header time, EVM latest block time — and ours, default 7200; the lab sets 315360000 because anvil's time is warped), allow_private_endpoints (lab only: http/ws and private hosts), max_fee_rate (sat/vB, default 50). Endpoints must otherwise be https / wss; relays from peers' kind 10050 are limited to 8 public wss relays.
• Messaging (§4.10): 120 messages / min per sender after EOSE, 60 / min for all non-counterparty senders together, higher per-sender limits for the stored backlog (older pages are read when the first 1000 wraps are full); messages no attached role accepts are neither stored nor acked. Sends go to k (2) inbox relays, the next ones only when one fails; resends 1, 2, 4, 8, … get a fresh wrap. A signed inner is at most 28000 bytes (§4.9); dispute evidence is split over several messages.
• The Safe address is predicted with the factory's proxyCreationCode only if its keccak256 is a known Safe v1.4.1 build (the lab's and the canonical one, KNOWN_PROXY_CREATION_CODE_HASHES).
• Only one tab runs the protocol at a time (Web Locks, BroadcastChannel fallback).
• apps/web/nginx.conf sets CSP, X-Content-Type-Options, Referrer-Policy, Permissions-Policy, X-Frame-Options; HSTS belongs to the TLS terminator. Production builds have no source maps.
• The browser talks to Esplora, the EVM RPC, rate sources and the faucet directly, so those endpoints must send CORS headers.
• UI test ids: apps/web/TESTIDS.md.

Contributing — pull requests welcome

Pull requests are welcome: shop drivers for shopper-bot, new payment methods and chains, translations, protocol and security reviews, bug fixes. Want to earn in your own town? You need nobody's permission: make a coordinator key, delegate to your operator key and list yourself as a shopper for your region (guide: https://pad01g.github.io/proxy-shopping-docs/en/quickstart/, section 3); a home machine reached over Tailscale or any VPN is enough. To be found by everyone, open a pull request to https://github.com/pad01g/proxy-shopping-registry.

License

MIT (LICENSE).