Metas de la semana

• [x] El facilitador como paquete de npm, con Docker, documentación y runbook
• [x] Una segunda instancia, instalada desde npm, que liquide pagos en testnet
• [x] Liquidar un pago para el proyecto de otro desarrollador

Resumen

Qué es Local402. Local402 permite cobrar por una API en la moneda local, con x402 en Stellar. x402 es un estándar abierto para pagar por HTTP: la API responde "402 Payment Required" con el precio, y el cliente (una persona o un agente de IA) paga y repite la petición. El vendedor pone el precio en cualquiera de 24 monedas o en UF; quien paga usa USDC, XLM o EURC en una sola transacción y el vendedor recibe el monto exacto en USDC.

Esta semana. El facilitador es el servicio que recibe el pago firmado, lo revisa, lo envía a la red y paga la comisión de la transacción. Hasta ahora solo existía el nuestro. Desde esta semana es un paquete de npm, local402-facilitator, que cualquiera puede correr con un comando o con Docker, y trae su documentación y un runbook. Una segunda instancia, instalada desde npm en una carpeta vacía sin nada de nuestro repositorio, liquidó pagos en testnet. Uno de ellos fue para kuyfi, un proyecto de otro desarrollador que corrió tal como está en GitHub.

Changelog

Agregado

• local402-facilitator 1.0.0 en npm: se corre con npx local402-facilitator o con su Dockerfile.
  • keys crea las cuentas que pagan las comisiones, las fondea en testnet y solo imprime las direcciones públicas. Si ya hay llaves, no las pisa.
  • check revisa el RPC (el servidor que conecta con la red de Stellar), el saldo de cada cuenta y el contrato FxPay antes de recibir tráfico, y sale con error si algo falla. Sirve para que un mal despliegue falle al arrancar o en CI, y no en el primer pago.
  • /health (el proceso está vivo) y /ready (puede liquidar ahora; responde 503 si una cuenta se queda sin saldo, si el RPC no responde o si falta FxPay).
  • Una lista de vendedores (PAY_TO_ALLOWLIST): la instancia solo liquida para ellos y a cualquier otro le dice que no antes de gastar nada.
  • Límites separados para verify (60 por minuto, solo simula) y settle (20 por minuto, gasta XLM).
  • Cada variable se valida al arrancar, sin repetir llaves ni la URL del RPC en los errores.
• docs/facilitator.md (configuración de testnet y mainnet) y docs/facilitator-runbook.md: cuántas cuentas usar, cuánto XLM ponerles, cuándo recargar y cómo rotarlas si una llave se filtra.
• 14 tests del facilitador.

Cambiado

• El facilitador dejó de ser una app dentro del repositorio (apps/facilitator) y pasó a ser el paquete packages/facilitator. Nuestro despliegue en Vercel sigue igual.
• En mainnet el facilitador no arranca sin el contrato FxPay y sin la lista de vendedores. Una lista vacía cuenta como no puesta.
• El facilitador no confía en ningún proxy salvo que TRUST_PROXY lo diga.

Corregido

• Con un proxy de confianza por defecto, un cliente que se conectaba directo podía escribir su propio X-Forwarded-For (la cabecera que dice la IP original) y saltarse el límite de llamadas. Comprobado: 25 llamadas con una IP falsa distinta cada una, todas rechazadas con 429.
• PAY_TO_ALLOWLIST= vacío en un host de mainnet liquidaba para cualquier vendedor.