@0xopenseeddev/buyer 1.0.0

package/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "@0xopenseeddev/buyer",
+  "version": "1.0.0",
+  "description": "Buyer proxy — local OpenAI/Anthropic-compatible AI gateway",
+  "main": "src/index.js",
+  "type": "module",
+  "scripts": {
+    "dev": "node --watch src/index.js",
+    "start": "node src/index.js"
+  },
+  "dependencies": {
+    "@0xopenseeddev/shared": "*",
+    "@fastify/cors": "^10.0.1",
+    "fastify": "^5.2.1",
+    "undici": "^7.3.0",
+    "viem": "^2.21.19"
+  },
+  "keywords": [],
+  "license": "ISC"
+}

package/src/channel-state.js

@@ -0,0 +1,96 @@
+/**
+ * ChannelState — buyer-side in-memory session tracker.
+ *
+ * Tracks the open payment channel with each pinned seller so the buyer
+ * can attach the correct SpendingAuth signature to every inference request.
+ *
+ * Lifecycle per seller:
+ *   NONE → RESERVING → OPEN → CLOSED
+ */
+
+import { parseUsdc, formatUsdc } from '@0xopenseeddev/shared';
+
+export class ChannelState {
+  constructor() {
+    /** @type {Map<string, ChannelEntry>} sellerAddress → ChannelEntry */
+    this._channels = new Map();
+
+    /** @type {Map<string, number>} sellerAddress → nonce (monotonic) */
+    this._nonces = new Map();
+  }
+
+  // ─── Nonce management ─────────────────────────────────────────────────────
+
+  nextNonce(sellerAddress) {
+    const n = (this._nonces.get(sellerAddress) ?? 0) + 1;
+    this._nonces.set(sellerAddress, n);
+    return n;
+  }
+
+  // ─── Channel entry management ─────────────────────────────────────────────
+
+  /**
+   * Open a new channel entry after the seller acknowledges a ReserveAuth.
+   */
+  openChannel(sellerAddress, { channelId, maxAmount, buyerAddress }) {
+    this._channels.set(sellerAddress, {
+      channelId,
+      buyerAddress,
+      sellerAddress,
+      maxAmount,
+      cumulativeSpend: 0n,
+      requestCount:    0,
+      openedAt:        Date.now(),
+      status:          'open'
+    });
+    console.log(`[channel-state] Opened channel ${channelId.slice(0, 18)}… with ${sellerAddress.slice(0, 10)}…`);
+  }
+
+  /**
+   * Record the cost of a completed inference request and return the
+   * new cumulative spend (used to build SpendingAuth).
+   *
+   * @param {string} sellerAddress
+   * @param {bigint} requestCost  - USDC cost for this specific request
+   * @returns {{ cumulativeSpend: bigint, requestCount: number } | null}
+   */
+  recordSpend(sellerAddress, requestCost) {
+    const ch = this._channels.get(sellerAddress);
+    if (!ch || ch.status !== 'open') return null;
+
+    ch.cumulativeSpend += requestCost;
+    ch.requestCount    += 1;
+
+    if (ch.cumulativeSpend > ch.maxAmount) {
+      console.warn(`[channel-state] ⚠️  Overspend on channel ${ch.channelId.slice(0, 18)}…`);
+    }
+
+    return { cumulativeSpend: ch.cumulativeSpend, requestCount: ch.requestCount };
+  }
+
+  getChannel(sellerAddress) {
+    return this._channels.get(sellerAddress) ?? null;
+  }
+
+  closeChannel(sellerAddress) {
+    const ch = this._channels.get(sellerAddress);
+    if (ch) {
+      ch.status   = 'closed';
+      ch.closedAt = Date.now();
+      console.log(`[channel-state] Closed channel ${ch.channelId.slice(0, 18)}…`);
+    }
+  }
+
+  status() {
+    const channels = [...this._channels.values()].map(ch => ({
+      channelId:      ch.channelId,
+      sellerAddress:  ch.sellerAddress,
+      status:         ch.status,
+      maxAmount:      formatUsdc(ch.maxAmount) + ' USDC',
+      spent:          formatUsdc(ch.cumulativeSpend) + ' USDC',
+      requestCount:   ch.requestCount,
+      openedAt:       new Date(ch.openedAt).toISOString()
+    }));
+    return { channels };
+  }
+}

package/src/config.js

@@ -0,0 +1,23 @@
+// ─── Buyer proxy configuration ────────────────────────────────────────────────
+
+export function loadConfig() {
+  return {
+    // Port the local proxy listens on
+    port: Number(process.env.BUYER_PORT ?? 8377),
+
+    // Registry base URL
+    registryUrl: process.env.REGISTRY_URL ?? 'http://localhost:9000',
+
+    // Pricing caps — reject providers that exceed these rates
+    maxPricing: {
+      inputUsdPerMillion:  Number(process.env.MAX_INPUT_USD  ?? 50),
+      outputUsdPerMillion: Number(process.env.MAX_OUTPUT_USD ?? 100)
+    },
+
+    // Default session budget in USDC (overridden by CONTRACT_ADDRESS / BUYER_PRIVATE_KEY env)
+    defaultBudgetUsdc: Number(process.env.DEFAULT_BUDGET_USDC ?? 1),
+
+    // Minimum peer reputation score (0 = accept all, reserved for Phase 5)
+    minPeerReputation: 0
+  };
+}

package/src/index.js

@@ -0,0 +1,311 @@
+import Fastify from 'fastify';
+import cors from '@fastify/cors';
+import { fetch } from 'undici';
+import { BUYER_PORT, parseUsdc } from '@0xopenseeddev/shared';
+import { loadConfig } from './config.js';
+import { PeerRouter } from './peer-router.js';
+import { BuyerWallet } from './wallet.js';
+import { ChannelState } from './channel-state.js';
+import { RequestTracker } from './request-tracker.js';
+import { createBuyerMetrics } from './metrics.js';
+
+const cfg      = loadConfig();
+const tracker  = new RequestTracker();
+const router   = new PeerRouter(cfg.registryUrl, cfg.maxPricing, tracker);
+const channels = new ChannelState();
+const { reg, m } = createBuyerMetrics();
+const _startTime = Date.now();
+
+// ─── Payment wallet (optional) ────────────────────────────────────────────────
+let wallet = null;
+if (process.env.BUYER_PRIVATE_KEY && process.env.CONTRACT_ADDRESS) {
+  wallet = new BuyerWallet({
+    privateKey:       process.env.BUYER_PRIVATE_KEY,
+    contractAddress:  process.env.CONTRACT_ADDRESS,
+    chainId:          Number(process.env.CHAIN_ID ?? 31337),
+    defaultBudgetUsdc: cfg.defaultBudgetUsdc
+  });
+  console.log(`[buyer] 💳 Payment wallet: ${wallet.address}`);
+} else {
+  console.log('[buyer] ⚠️  No BUYER_PRIVATE_KEY / CONTRACT_ADDRESS — running in no-payment mode.');
+}
+
+// ─── Fastify instance ─────────────────────────────────────────────────────────
+const app = Fastify({ logger: true });
+await app.register(cors, { origin: '*' });
+
+// ─── Generic inference forwarder ──────────────────────────────────────────────
+async function forwardInference(req, reply, upstreamPath) {
+  const requestedModel = req.body?.model;
+  if (!requestedModel) {
+    return reply.status(400).send({
+      error: { code: 'missing_model', message: 'The "model" field is required.' }
+    });
+  }
+
+  const perRequestPeerId = req.headers['x-anteseed-pin-peer'] ?? null;
+
+  let endpoint, resolvedServiceId, peer;
+  try {
+    const resolved = await router.resolve(requestedModel, perRequestPeerId);
+    endpoint          = resolved.endpoint;
+    resolvedServiceId = resolved.resolvedServiceId;
+    peer              = resolved.peer;
+  } catch (err) {
+    return reply.status(503).send({
+      error: { code: err.code ?? 'routing_error', message: err.message, hint: err.hint }
+    });
+  }
+
+  const forwardBody    = { ...req.body, model: resolvedServiceId };
+  const forwardHeaders = { 'content-type': 'application/json' };
+
+  if (req.headers['anthropic-version']) {
+    forwardHeaders['anthropic-version'] = req.headers['anthropic-version'];
+  }
+  if (req.headers['x-402-payment-auth']) {
+    forwardHeaders['x-402-payment-auth'] = req.headers['x-402-payment-auth'];
+  }
+  if (req.headers['x-402-channel-id']) {
+    forwardHeaders['x-402-channel-id'] = req.headers['x-402-channel-id'];
+  }
+  if (req.headers['x-openseed-buyer-address']) {
+    forwardHeaders['x-openseed-buyer-address'] = req.headers['x-openseed-buyer-address'];
+  } else if (wallet) {
+    forwardHeaders['x-openseed-buyer-address'] = wallet.address;
+  }
+
+  const targetUrl = `${endpoint}${upstreamPath}`;
+  const t0 = Date.now();
+
+  const makeRequest = async (headers) => {
+    return fetch(targetUrl, {
+      method:  'POST',
+      headers,
+      body:    JSON.stringify(forwardBody)
+    });
+  };
+
+  try {
+    let peerRes = await makeRequest(forwardHeaders);
+
+    // ── Handle x402 Payment Retry ─────────────────────────────────────────────
+    if (peerRes.status === 402 && wallet) {
+      const paymentRequired = peerRes.headers.get('x-402-payment-required');
+      if (paymentRequired) {
+        const match = paymentRequired.match(/price=(\d+)/);
+        const price = match ? BigInt(match[1]) : parseUsdc(0.01);
+        const sellerAddress = peer?.merchantAddress ?? peer?.peerId ?? endpoint;
+        let ch = channels.getChannel(sellerAddress);
+
+        if (!ch || ch.status !== 'open') {
+          const nonce = channels.nextNonce(sellerAddress);
+          const reserveAuth = await wallet.buildReserveAuth(
+            sellerAddress,
+            nonce,
+            parseUsdc(Math.min(cfg.defaultBudgetUsdc, 1))
+          );
+          try {
+            const sessionRes = await fetch(`${endpoint}/session/start`, {
+              method: 'POST',
+              headers: { 'content-type': 'application/json' },
+              body: JSON.stringify({
+                channelId:     reserveAuth.channelId,
+                buyerAddress:  wallet.address,
+                sellerAddress: sellerAddress,
+                maxAmount:     reserveAuth.maxAmount.toString(),
+                deadline:      reserveAuth.deadline.toString(),
+                signature:     reserveAuth.signature
+              })
+            });
+            const sessionData = await sessionRes.json().catch(() => null);
+            if (!sessionRes.ok) {
+              throw new Error(sessionData?.error?.message || 'Failed to start x402 session');
+            }
+            channels.openChannel(sellerAddress, {
+              channelId:    reserveAuth.channelId,
+              maxAmount:    reserveAuth.maxAmount,
+              buyerAddress: wallet.address
+            });
+            ch = channels.getChannel(sellerAddress);
+            m.activeChannels.set({}, channels.status().channels.filter(c => c.status === 'open').length);
+          } catch (err) {
+            app.log.warn('[buyer] Could not start payment session:', err.message);
+          }
+        }
+
+        if (ch && ch.status === 'open') {
+          const spend = channels.recordSpend(sellerAddress, price);
+          if (spend) {
+            const meta = { inputTokens: 0, outputTokens: 0, requestId: `req-${Date.now()}` };
+            const spendingAuth = await wallet.buildSpendingAuth(ch.channelId, spend.cumulativeSpend, meta);
+            const encoded = Buffer.from(JSON.stringify({
+              cumulativeAmount: spendingAuth.cumulativeAmount.toString(),
+              metadataHash:     spendingAuth.metadataHash,
+              signature:        spendingAuth.signature
+            })).toString('base64');
+            forwardHeaders['x-402-payment-auth'] = encoded;
+            forwardHeaders['x-402-channel-id']   = ch.channelId;
+
+            peerRes = await makeRequest(forwardHeaders);
+          }
+        }
+      }
+    }
+
+    const latencyMs = Date.now() - t0;
+    const success   = peerRes.status >= 200 && peerRes.status < 300;
+    const peerId    = peer?.peerId ?? endpoint;
+
+    // ── Track request + update Prometheus metrics ──────────────────────────
+    tracker.record(peerId, { latencyMs, success, statusCode: peerRes.status, model: resolvedServiceId });
+
+    m.requestsTotal.inc({ peer_id: peerId.slice(0, 12), model: resolvedServiceId, status: String(peerRes.status) });
+    m.requestDurationMs.observe({ peer_id: peerId.slice(0, 12), model: resolvedServiceId }, latencyMs);
+
+    // Refresh peer reputation gauges
+    const stats = tracker.getStats(peerId);
+    if (stats) {
+      m.peerReputationScore.set({ peer_id: peerId.slice(0, 12) }, stats.reputationScore);
+      m.peerSuccessRate.set({ peer_id: peerId.slice(0, 12) }, stats.successRate);
+      m.peerLatencyP95Ms.set({ peer_id: peerId.slice(0, 12) }, stats.latency.p95);
+    }
+
+    reply.status(peerRes.status);
+    const ct = peerRes.headers.get('content-type') ?? 'application/json';
+    reply.header('content-type', ct);
+    if (peerRes.body) return reply.send(peerRes.body);
+    return reply.send(await peerRes.text());
+  } catch (err) {
+    const latencyMs = Date.now() - t0;
+    tracker.record(peer?.peerId ?? endpoint, { latencyMs, success: false, statusCode: 502, model: resolvedServiceId });
+    m.requestsTotal.inc({ peer_id: (peer?.peerId ?? endpoint).slice(0, 12), model: resolvedServiceId, status: '502' });
+    return reply.status(502).send({ error: { code: 'peer_unreachable', message: err.message } });
+  }
+}
+
+// ── Inference routes ──────────────────────────────────────────────────────────
+app.post('/v1/chat/completions', (req, reply) => forwardInference(req, reply, '/v1/chat/completions'));
+app.post('/v1/messages',         (req, reply) => forwardInference(req, reply, '/v1/messages'));
+app.post('/v1/responses',        (req, reply) => forwardInference(req, reply, '/v1/responses'));
+
+// ── Prometheus metrics ────────────────────────────────────────────────────────
+app.get('/metrics', async (req, reply) => {
+  // Refresh gauges that are computed on-demand
+  m.proxyUptimeSeconds.set({}, Math.floor((Date.now() - _startTime) / 1000));
+  m.registeredPeers.set({}, router.cachedPeerCount);
+  m.activeChannels.set({}, channels.status().channels.filter(c => c.status === 'open').length);
+
+  // Refresh all peer reputation gauges
+  for (const stats of tracker.getAllStats()) {
+    const shortId = stats.peerId.slice(0, 12);
+    m.peerReputationScore.set({ peer_id: shortId }, stats.reputationScore);
+    m.peerSuccessRate.set({ peer_id: shortId }, stats.successRate);
+    m.peerLatencyP95Ms.set({ peer_id: shortId }, stats.latency.p95);
+    m.spendUsdcTotal.set({ peer_id: shortId }, Number(stats.totalSpendUsdc));
+  }
+
+  reply.header('content-type', 'text/plain; version=0.0.4; charset=utf-8');
+  return reply.send(reg.format());
+});
+
+// ── Reputation / stats API ────────────────────────────────────────────────────
+app.get('/reputation/peers', async () => ({
+  global: tracker.globalStats(),
+  peers:  tracker.getAllStats()
+}));
+
+app.get('/reputation/peers/:peerId', async (req, reply) => {
+  const stats = tracker.getStats(req.params.peerId);
+  if (!stats) return reply.status(404).send({ error: { code: 'not_found', message: 'No data for this peer yet.' } });
+  return stats;
+});
+
+// ── Buyer management API ──────────────────────────────────────────────────────
+app.get('/buyer/status', async () => ({
+  wallet:          wallet ? { address: wallet.address, paymentsEnabled: true } : { paymentsEnabled: false },
+  pinnedPeerId:    router.pinnedPeerId,
+  pinnedServiceId: router.pinnedServiceId,
+  registryUrl:     cfg.registryUrl,
+  maxPricing:      cfg.maxPricing,
+  global:          tracker.globalStats(),
+  ...channels.status()
+}));
+
+app.post('/buyer/connection', {
+  schema: {
+    body: {
+      type: 'object',
+      properties: { peer: { type: 'string' }, service: { type: 'string' } }
+    }
+  }
+}, async (req) => {
+  const { peer, service } = req.body ?? {};
+  if (peer)    router.setPeer(peer);
+  if (service) router.setService(service);
+  return { ok: true, pinnedPeerId: router.pinnedPeerId, pinnedServiceId: router.pinnedServiceId };
+});
+
+app.delete('/buyer/connection', async () => {
+  router.clearPins();
+  return { ok: true };
+});
+
+app.get('/payments/status', async () => ({
+  paymentsEnabled: !!wallet,
+  wallet:          wallet ? { address: wallet.address } : null,
+  ...channels.status()
+}));
+
+app.get('/network/peers', async (req) => {
+  const { model } = req.query;
+  const url = model
+    ? `${cfg.registryUrl}/peers?model=${encodeURIComponent(model)}`
+    : `${cfg.registryUrl}/peers`;
+  const res = await fetch(url);
+  return res.json();
+});
+
+app.get('/network/peers/:peerId', async (req, reply) => {
+  const res = await fetch(`${cfg.registryUrl}/peers/${req.params.peerId}`);
+  reply.status(res.status);
+  return res.json();
+});
+
+app.get('/health', async () => ({
+  status:   'ok',
+  proxy:    'buyer',
+  port:     cfg.port,
+  payments: !!wallet,
+  ...tracker.globalStats()
+}));
+
+// ─── Start ────────────────────────────────────────────────────────────────────
+try {
+  await app.listen({ port: cfg.port, host: '127.0.0.1' });
+  console.log(`
+🐜 OpenSeed Buyer Proxy  http://localhost:${cfg.port}
+
+  Inference endpoints:
+    POST /v1/chat/completions    (OpenAI format)
+    POST /v1/messages            (Anthropic format)
+
+  Observability:
+    GET  /metrics                (Prometheus text format)
+    GET  /reputation/peers       (per-peer runtime stats + scores)
+    GET  /buyer/status           (full status)
+
+  Payments: ${wallet ? '💳 enabled — wallet ' + wallet.address : '⚠️  disabled (no-payment mode)'}
+`);
+} catch (err) {
+  app.log.error(err);
+  process.exit(1);
+}
+
+async function shutdown() {
+  console.log('\n[buyer] Shutting down…');
+  await app.close();
+  process.exit(0);
+}
+process.on('SIGINT', shutdown);
+process.on('SIGTERM', shutdown);

package/src/metrics.js

@@ -0,0 +1,83 @@
+/**
+ * Buyer Prometheus metrics registry.
+ * Exposes all buyer-proxy metrics at GET /metrics.
+ */
+
+import { PrometheusRegistry } from '@0xopenseeddev/shared';
+
+export function createBuyerMetrics() {
+  const reg = new PrometheusRegistry();
+
+  const m = {
+    // ── Inference requests ───────────────────────────────────────────────────
+    requestsTotal: reg.counter(
+      'openseed_buyer_requests_total',
+      'Total inference requests forwarded by the buyer proxy',
+      ['peer_id', 'model', 'status']
+    ),
+
+    requestDurationMs: reg.histogram(
+      'openseed_buyer_request_duration_ms',
+      'End-to-end latency of forwarded requests in milliseconds',
+      [10, 25, 50, 100, 250, 500, 1000, 2500, 5000],
+      ['peer_id', 'model']
+    ),
+
+    // ── Token accounting ─────────────────────────────────────────────────────
+    inputTokensTotal: reg.counter(
+      'openseed_buyer_input_tokens_total',
+      'Total input tokens sent across all requests',
+      ['peer_id', 'model']
+    ),
+
+    outputTokensTotal: reg.counter(
+      'openseed_buyer_output_tokens_total',
+      'Total output tokens received across all requests',
+      ['peer_id', 'model']
+    ),
+
+    // ── Payments ─────────────────────────────────────────────────────────────
+    spendUsdcTotal: reg.gauge(
+      'openseed_buyer_spend_usdc_total',
+      'Cumulative USDC spent (in base units, 6 decimal)',
+      ['peer_id']
+    ),
+
+    activeChannels: reg.gauge(
+      'openseed_buyer_active_channels',
+      'Number of currently open payment channels'
+    ),
+
+    // ── Peer reputation ───────────────────────────────────────────────────────
+    peerReputationScore: reg.gauge(
+      'openseed_buyer_peer_reputation_score',
+      'Composite reputation score for each peer (0-100)',
+      ['peer_id']
+    ),
+
+    peerSuccessRate: reg.gauge(
+      'openseed_buyer_peer_success_rate',
+      'Success rate for each peer (0-1)',
+      ['peer_id']
+    ),
+
+    peerLatencyP95Ms: reg.gauge(
+      'openseed_buyer_peer_latency_p95_ms',
+      'P95 request latency per peer in milliseconds',
+      ['peer_id']
+    ),
+
+    // ── Proxy internals ───────────────────────────────────────────────────────
+    proxyUptimeSeconds: reg.gauge(
+      'openseed_buyer_uptime_seconds',
+      'Seconds since the buyer proxy started'
+    ),
+
+    registeredPeers: reg.gauge(
+      'openseed_buyer_known_peers_total',
+      'Number of peers known from the last registry fetch'
+    )
+  };
+
+  return { reg, m };
+}

package/src/peer-router.js

@@ -0,0 +1,172 @@
+import { fetch } from 'undici';
+
+/**
+ * PeerRouter is responsible for:
+ *   1. Fetching live peers from the registry
+ *   2. Filtering by model/service and max pricing
+ *   3. Maintaining a "pinned" peer per session
+ *   4. Selecting the BEST peer by reputation score when none is pinned
+ *
+ * Phase 5 addition: accepts an optional RequestTracker to score peers by
+ * runtime latency, reliability, and activity when auto-selecting.
+ */
+export class PeerRouter {
+  /**
+   * @param {string} registryUrl
+   * @param {{ inputUsdPerMillion: number, outputUsdPerMillion: number }} maxPricing
+   * @param {import('./request-tracker.js').RequestTracker} [tracker]
+   */
+  constructor(registryUrl, maxPricing, tracker = null) {
+    this.registryUrl = registryUrl;
+    this.maxPricing  = maxPricing;
+    this.tracker     = tracker;
+
+    /** @type {string|null} peerId of the currently pinned peer */
+    this.pinnedPeerId = null;
+
+    /** @type {string|null} override all model fields to this service id */
+    this.pinnedServiceId = null;
+
+    /** @type {Map<string, any>} in-memory cache of peers fetched from registry */
+    this._peerCache = new Map();
+    this._cacheTs   = 0;
+    this._cacheTtl  = 15_000; // 15 s
+  }
+
+  // ── Pin controls ──────────────────────────────────────────────────────────
+
+  setPeer(peerId) {
+    this.pinnedPeerId = peerId;
+    console.log(`[buyer-router] Pinned peer: ${peerId.slice(0, 16)}…`);
+  }
+
+  setService(serviceId) {
+    this.pinnedServiceId = serviceId;
+    console.log(`[buyer-router] Pinned service: ${serviceId}`);
+  }
+
+  clearPins() {
+    this.pinnedPeerId    = null;
+    this.pinnedServiceId = null;
+    console.log('[buyer-router] Pins cleared.');
+  }
+
+  // ── Peer resolution ───────────────────────────────────────────────────────
+
+  async _fetchPeers(model) {
+    const now = Date.now();
+    if (now - this._cacheTs < this._cacheTtl && this._peerCache.size > 0) {
+      return [...this._peerCache.values()];
+    }
+    const url = model
+      ? `${this.registryUrl}/peers?model=${encodeURIComponent(model)}`
+      : `${this.registryUrl}/peers`;
+    const res  = await fetch(url);
+    const data = await res.json();
+    this._peerCache.clear();
+    for (const p of (data.peers ?? [])) {
+      this._peerCache.set(p.peerId, p);
+    }
+    this._cacheTs = now;
+    return [...this._peerCache.values()];
+  }
+
+  /**
+   * Select the best eligible peer for a model using the reputation scorer.
+   *
+   * Scoring priority:
+   *   1. Reputation score (reliability × latency × activity) — 60%
+   *   2. Price (cheapest output/M tokens) — 40%
+   *
+   * Peers with no history get a neutral score of 50.
+   *
+   * @param {any[]} peers
+   * @param {string} serviceId
+   * @returns {any|null}
+   */
+  _selectBestPeer(peers, serviceId) {
+    if (peers.length === 0) return null;
+    if (peers.length === 1) return peers[0];
+
+    const MAX_OUTPUT_PRICE = this.maxPricing.outputUsdPerMillion;
+
+    const scored = peers.map(p => {
+      const offering  = p.offerings?.find(o => o.services?.includes(serviceId));
+      const price     = offering?.pricing?.outputUsdPerMillion ?? MAX_OUTPUT_PRICE;
+      const repScore  = this.tracker ? this.tracker.score(p.peerId) : 50;
+      const priceScore = Math.max(0, 1 - price / MAX_OUTPUT_PRICE) * 100;
+      const composite  = (repScore * 0.60) + (priceScore * 0.40);
+      return { peer: p, score: composite, repScore, priceScore, price };
+    });
+
+    scored.sort((a, b) => b.score - a.score);
+
+    // Log the selection decision (debug)
+    const top = scored[0];
+    console.log(
+      `[buyer-router] Auto-selected: ${top.peer.peerId.slice(0, 16)}… ` +
+      `(rep=${top.repScore}, price=${top.priceScore.toFixed(1)}, composite=${top.score.toFixed(1)})`
+    );
+
+    return top.peer;
+  }
+
+  /**
+   * Resolve which peer endpoint to use for a given request.
+   * Returns { endpoint, resolvedServiceId, peer } or throws an error.
+   *
+   * @param {string}      requestedModel
+   * @param {string|null} perRequestPeerId - from x-anteseed-pin-peer header
+   */
+  async resolve(requestedModel, perRequestPeerId = null) {
+    const effectivePeerId    = perRequestPeerId ?? this.pinnedPeerId;
+    const effectiveServiceId = this.pinnedServiceId ?? requestedModel;
+
+    if (!effectivePeerId) {
+      // Auto-select: fetch eligible peers and score them
+      const allPeers = await this._fetchPeers(effectiveServiceId);
+      const eligible = allPeers.filter(p =>
+        p.offerings?.some(o =>
+          o.services?.includes(effectiveServiceId) &&
+          o.pricing.inputUsdPerMillion  <= this.maxPricing.inputUsdPerMillion &&
+          o.pricing.outputUsdPerMillion <= this.maxPricing.outputUsdPerMillion
+        )
+      );
+
+      if (eligible.length === 0) {
+        const err = new Error('no_peer_available');
+        err.code  = 'no_peer_available';
+        err.hint  = `No peers offer "${effectiveServiceId}" within your pricing caps. ` +
+                    `Browse peers at GET /network/peers and pin one via POST /buyer/connection.`;
+        throw err;
+      }
+
+      const best = this._selectBestPeer(eligible, effectiveServiceId);
+      return { endpoint: best.endpoint, resolvedServiceId: effectiveServiceId, peer: best };
+    }
+
+    // Pinned peer — look up from cache or registry
+    const cached = this._peerCache.get(effectivePeerId);
+    if (cached) {
+      return { endpoint: cached.endpoint, resolvedServiceId: effectiveServiceId, peer: cached };
+    }
+
+    const res = await fetch(`${this.registryUrl}/peers/${effectivePeerId}`);
+    if (!res.ok) {
+      const err = new Error('pinned_peer_offline');
+      err.code  = 'pinned_peer_offline';
+      err.hint  = `The pinned peer ${effectivePeerId.slice(0, 16)}… is not reachable.`;
+      throw err;
+    }
+    const peer = await res.json();
+    this._peerCache.set(peer.peerId, peer);
+    return { endpoint: peer.endpoint, resolvedServiceId: effectiveServiceId, peer };
+  }
+
+  /**
+   * Return the number of cached peers (for metrics).
+   */
+  get cachedPeerCount() {
+    return this._peerCache.size;
+  }
+}

package/src/request-tracker.js

@@ -0,0 +1,192 @@
+/**
+ * RequestTracker — buyer proxy
+ *
+ * Tracks per-peer runtime statistics:
+ *   - Request counts (success / failure)
+ *   - Latency samples (rolling window of last 100)
+ *   - Token counts (input / output)
+ *   - USDC spend
+ *
+ * These stats feed into the reputation scoring engine so the peer-router
+ * can auto-select the best available peer for each request.
+ */
+
+export class RequestTracker {
+  constructor() {
+    /** @type {Map<string, PeerStats>} peerId → stats */
+    this._peers = new Map();
+    this._globalStart = Date.now();
+    this._totalRequests = 0;
+    this._totalFailed   = 0;
+  }
+
+  // ─── Recording ────────────────────────────────────────────────────────────
+
+  /**
+   * Record the outcome of a forwarded inference request.
+   *
+   * @param {string} peerId
+   * @param {object} opts
+   * @param {number}  opts.latencyMs      - wall-clock time from send → first byte
+   * @param {boolean} opts.success        - whether the upstream returned 2xx
+   * @param {number}  [opts.statusCode]   - HTTP status code
+   * @param {number}  [opts.inputTokens]  - parsed from usage (if available)
+   * @param {number}  [opts.outputTokens]
+   * @param {bigint}  [opts.costUsdc]     - USDC spent in base units
+   * @param {string}  [opts.model]        - resolved service/model name
+   */
+  record(peerId, {
+    latencyMs,
+    success,
+    statusCode  = 200,
+    inputTokens  = 0,
+    outputTokens = 0,
+    costUsdc     = 0n,
+    model        = 'unknown'
+  }) {
+    let s = this._peers.get(peerId);
+    if (!s) {
+      s = this._newStats(peerId);
+      this._peers.set(peerId, s);
+    }
+
+    s.totalRequests++;
+    this._totalRequests++;
+
+    if (!success) {
+      s.failedRequests++;
+      this._totalFailed++;
+      s.lastStatusCode = statusCode;
+    } else {
+      s.successfulRequests++;
+    }
+
+    // Rolling latency window (last 100 samples)
+    s.latencySamples.push(latencyMs);
+    if (s.latencySamples.length > 100) s.latencySamples.shift();
+
+    s.totalInputTokens  += inputTokens;
+    s.totalOutputTokens += outputTokens;
+    s.totalSpendUsdc    += costUsdc;
+    s.lastSeenAt         = Date.now();
+    s.lastModel          = model;
+  }
+
+  // ─── Derived stats ────────────────────────────────────────────────────────
+
+  getStats(peerId) {
+    const s = this._peers.get(peerId);
+    if (!s) return null;
+    return this._enrichStats(s);
+  }
+
+  getAllStats() {
+    return [...this._peers.values()].map(s => this._enrichStats(s));
+  }
+
+  globalStats() {
+    return {
+      totalRequests: this._totalRequests,
+      totalFailed:   this._totalFailed,
+      successRate:   this._totalRequests > 0
+        ? ((this._totalRequests - this._totalFailed) / this._totalRequests)
+        : 1,
+      uptimeSeconds: Math.floor((Date.now() - this._globalStart) / 1000),
+      peerCount:     this._peers.size
+    };
+  }
+
+  _enrichStats(s) {
+    const sorted    = [...s.latencySamples].sort((a, b) => a - b);
+    const p50 = percentile(sorted, 50);
+    const p95 = percentile(sorted, 95);
+    const p99 = percentile(sorted, 99);
+    const avg = sorted.length > 0
+      ? sorted.reduce((a, b) => a + b, 0) / sorted.length
+      : 0;
+    const successRate = s.totalRequests > 0
+      ? s.successfulRequests / s.totalRequests
+      : 1;
+    return {
+      peerId:              s.peerId,
+      totalRequests:       s.totalRequests,
+      successfulRequests:  s.successfulRequests,
+      failedRequests:      s.failedRequests,
+      successRate:         +successRate.toFixed(4),
+      latency:             { avg: +avg.toFixed(1), p50, p95, p99, sampleCount: sorted.length },
+      totalInputTokens:    s.totalInputTokens,
+      totalOutputTokens:   s.totalOutputTokens,
+      totalSpendUsdc:      s.totalSpendUsdc.toString(),
+      lastSeenAt:          s.lastSeenAt ? new Date(s.lastSeenAt).toISOString() : null,
+      lastModel:           s.lastModel,
+      lastStatusCode:      s.lastStatusCode,
+      reputationScore:     this.score(s.peerId)
+    };
+  }
+
+  _newStats(peerId) {
+    return {
+      peerId,
+      totalRequests:      0,
+      successfulRequests: 0,
+      failedRequests:     0,
+      latencySamples:     [],
+      totalInputTokens:   0,
+      totalOutputTokens:  0,
+      totalSpendUsdc:     0n,
+      lastSeenAt:         null,
+      lastModel:          null,
+      lastStatusCode:     null
+    };
+  }
+
+  // ─── Reputation scoring ───────────────────────────────────────────────────
+
+  /**
+   * Composite reputation score for a peer: 0 (worst) → 100 (best).
+   *
+   * Weights:
+   *   40% — reliability (success rate)
+   *   35% — latency    (lower p95 is better; baseline 2000ms)
+   *   25% — activity   (logarithmic request volume, normalized to 200 req)
+   *
+   * On-chain volume score is reserved for Phase 5+ once we have a public
+   * chain indexer set up; for now activity is proxy-measured locally.
+   *
+   * @param {string} peerId
+   * @returns {number} 0-100
+   */
+  score(peerId) {
+    const s = this._peers.get(peerId);
+    if (!s || s.totalRequests === 0) return 50; // neutral for unseen peers
+
+    const successRate = s.successfulRequests / s.totalRequests;
+
+    const sorted = [...s.latencySamples].sort((a, b) => a - b);
+    const p95    = percentile(sorted, 95);
+    const BASELINE_LATENCY_MS = 2000;
+    const latencyScore = Math.max(0, 1 - p95 / BASELINE_LATENCY_MS);
+
+    const MAX_REQUESTS = 200;
+    const activityScore = Math.min(1, Math.log1p(s.totalRequests) / Math.log1p(MAX_REQUESTS));
+
+    const composite = (0.40 * successRate) + (0.35 * latencyScore) + (0.25 * activityScore);
+    return Math.round(composite * 100);
+  }
+
+  /**
+   * Sort a list of peer IDs by descending reputation score.
+   * Peers with no history score 50 (neutral).
+   */
+  rankPeers(peerIds) {
+    return [...peerIds].sort((a, b) => this.score(b) - this.score(a));
+  }
+}
+
+// ─── Helpers ──────────────────────────────────────────────────────────────────
+
+function percentile(sortedArr, p) {
+  if (sortedArr.length === 0) return 0;
+  const idx = Math.ceil((p / 100) * sortedArr.length) - 1;
+  return +(sortedArr[Math.max(0, idx)] ?? 0).toFixed(1);
+}

package/src/wallet.js

@@ -0,0 +1,85 @@
+/**
+ * Buyer wallet — wraps the buyer's private key and manages EIP-712 signing
+ * for ReserveAuth and SpendingAuth messages.
+ *
+ * In production, the private key never leaves this process.
+ * On-chain actions (reserve, settle, close) are initiated by the seller node.
+ * The buyer only signs typed-data messages — it never needs gas.
+ */
+
+import { privateKeyToAccount } from 'viem/accounts';
+import {
+  signReserveAuth,
+  signSpendingAuth,
+  buildChannelId,
+  buildMetadataHash,
+  parseUsdc
+} from '@0xopenseeddev/shared';
+
+export class BuyerWallet {
+  /**
+   * @param {object} opts
+   * @param {string} opts.privateKey         - 0x-prefixed hex private key
+   * @param {string} opts.contractAddress    - AntseedDeposits contract address
+   * @param {number} opts.chainId
+   * @param {number} [opts.defaultBudgetUsdc=1] - Default session budget in USDC
+   */
+  constructor({ privateKey, contractAddress, chainId, defaultBudgetUsdc = 1 }) {
+    if (!privateKey) throw new Error('BUYER_PRIVATE_KEY env var is required for payment mode');
+    this.account         = privateKeyToAccount(privateKey);
+    this.contractAddress = contractAddress;
+    this.chainId         = chainId;
+    this.defaultBudget   = parseUsdc(defaultBudgetUsdc);
+    this._signerOpts     = { privateKey, contractAddress, chainId };
+  }
+
+  get address() {
+    return this.account.address;
+  }
+
+  // ── ReserveAuth ─────────────────────────────────────────────────────────────
+
+  /**
+   * Sign a ReserveAuth for a new session with a seller.
+   *
+   * @param {string} sellerAddress
+   * @param {number} nonce          - increments per buyer-seller pair
+   * @param {bigint} [maxAmount]    - defaults to defaultBudget
+   * @param {number} [ttlSeconds]   - defaults to 24h
+   * @returns {Promise<{ channelId: string, signature: string, maxAmount: bigint, deadline: bigint }>}
+   */
+  async buildReserveAuth(sellerAddress, nonce, maxAmount, ttlSeconds = 86_400) {
+    const channelId = buildChannelId(this.address, sellerAddress, nonce);
+    const amount    = maxAmount ?? this.defaultBudget;
+    const deadline  = BigInt(Math.floor(Date.now() / 1000) + ttlSeconds);
+
+    const signature = await signReserveAuth(this._signerOpts, {
+      channelId,
+      seller:    sellerAddress,
+      maxAmount: amount,
+      deadline
+    });
+
+    return { channelId, signature, maxAmount: amount, deadline };
+  }
+
+  // ── SpendingAuth ─────────────────────────────────────────────────────────────
+
+  /**
+   * Sign a SpendingAuth after a successful inference request.
+   *
+   * @param {string} channelId
+   * @param {bigint} cumulativeAmount - total USDC spent in this session so far
+   * @param {{ inputTokens: number, outputTokens: number, requestId: string }} meta
+   * @returns {Promise<{ cumulativeAmount: bigint, metadataHash: string, signature: string }>}
+   */
+  async buildSpendingAuth(channelId, cumulativeAmount, meta) {
+    const metadataHash = buildMetadataHash(meta);
+    const signature    = await signSpendingAuth(this._signerOpts, {
+      channelId,
+      cumulativeAmount,
+      metadataHash
+    });
+    return { cumulativeAmount, metadataHash, signature };
+  }
+}