# Compra y financiación del escrow ### Contexto y supuestos (Importante) Offer Hub modela un **mercado clásico**: * Los vendedores publican bienes o servicios por adelantado * Los compradores navegan por las ofertas existentes * Un comprador crea una orden haciendo clic **Comprar** * Cada orden crea **un escrow** Este flujo asume: * El vendedor y la oferta ya existen * El comprador está iniciando la transacción * Los fondos deben estar asegurados *antes de* que comience la entrega *** ### Objetivo Crear **un escrow por orden** y financiarlo **directamente desde el comprador**, manteniendo la experiencia simple y totalmente abstraída. *** ### Desde la perspectiva del usuario > “Hago clic en Comprar.\ > Si ya tengo dinero, se reserva.\ > Si no, pago de la misma manera de siempre.\ > El vendedor solo recibe el pago si todo está aprobado.” El usuario nunca elige: * blockchains * billeteras * direcciones de escrow * flujos de firma *** ### Actores * **Comprador** * **Vendedor** * **Interfaz de OfferHub** * **Backend de OfferHub (Orquestador)** * **Supabase** (perfil de usuario + vinculación con Airtm) * **Airtm** (cuentas, saldos, railes) * **Trustless Work** (motor de escrow en Stellar) * **Stellar (USDC)** *** ### Precondiciones * El comprador ha iniciado sesión (Supabase) * El comprador tiene una **cuenta Airtm vinculada y aprobada por KYC** * El vendedor tiene una oferta activa * La plataforma está configurada como: * emisor de escrow * resolutor de disputas * firmante de liberación *** ### Flujo a alto nivel ``` El comprador hace clic en Comprar → Escrow creado → Escrow financiado por el comprador → La orden comienza ``` Hay **dos rutas de financiación visibles para el usuario**, dependiendo de si el comprador ya tiene fondos. *** ### Ruta A — El comprador tiene saldo suficiente en Airtm (Ruta principal) #### Cuando sucede esto * El comprador ya tiene suficiente USDC (o equivalente) en su cuenta Airtm * Este es el **flujo predeterminado y preferido** *** #### Experiencia del usuario > “Hago clic en Comprar y el dinero se reserva.” No se requieren pasos de pago adicionales. *** #### Flujo del sistema 1. **El comprador hace clic en Comprar** ``` Comprador → Interfaz de OfferHub: Comprar ``` 2. **OfferHub crea el escrow** ``` OfferHub → Trustless Work: Crear escrow (parámetros de la orden) ``` 3. **El comprador financia el escrow desde el saldo de Airtm** ``` Airtm: Transferir USDC desde la cuenta del comprador → Dirección de escrow en Stellar ``` 4. **El escrow queda financiado** ``` Estado del escrow → Financiado Estado de la orden → En progreso ``` *** #### Propiedades clave * Los fondos se mueven **directamente del comprador al escrow** * El marketplace nunca toca los fondos del usuario * El escrow se financia inmediatamente * El vendedor puede proceder con seguridad Este es el **ruta más limpia y segura**, y la que Offer Hub diseña como prioridad. *** ### Ruta B — El comprador NO tiene saldo suficiente (Pagar al escrow) ⚠️ **Esta ruta requiere validación con el equipo de Airtm**\ Se incluye aquí como un **patrón educativo y con vista al futuro**. *** #### Cuando sucede esto * El comprador está aprobado por KYC en Airtm * El comprador no tiene suficiente saldo * El comprador aún quiere completar la compra inmediatamente *** #### Experiencia del usuario > “Hago clic en Comprar y elijo cómo pagar.” El usuario puede ver: * tarjeta de débito * tarjeta de crédito * transferencia bancaria (ACH, transferencia, etc.) Pero aun así **nunca ve cripto o stablecoins**. *** #### Flujo del sistema (Propuesto / Por validar) 1. **El comprador hace clic en Comprar** ``` Comprador → Interfaz de OfferHub: Comprar ``` 2. **OfferHub crea el escrow (pendiente de financiación)** ``` OfferHub → Trustless Work: Crear escrow ``` 3. **El comprador selecciona el método de pago a través de Airtm** ``` Comprador → Flujo de pago alojado por Airtm ``` 4. **El pago financia el escrow directamente** ``` Rail de pago → Airtm Airtm → dirección de escrow en Stellar ``` 5. **El escrow queda financiado** ``` Estado del escrow → Financiado Estado de la orden → En progreso ``` *** #### Notas importantes * Los fondos **no deberían** liquidarse en una cuenta de la plataforma * La intención es **pago → escrow**, no pago → saldo → escrow * Esto preserva: * garantías no custodiales * contabilidad limpia * límites de confianza correctos Si Airtm puede soportar **flujos de pago directo a escrow** es un **elemento clave de validación** para el piloto. *** ### Qué sucede después (Ambas rutas) Una vez que el escrow está financiado: * Se notifica al vendedor * La orden entra en **En progreso** * La entrega puede comenzar * La lógica de disputas y aprobación se aplica de forma idéntica A partir de este punto, **ambas rutas convergen**. *** ### Resultados * ✅ Escrow creado y financiado * ✅ Estado de la orden actualizado * ✅ Vendedor notificado * ✅ Registro de auditoría creado (off-chain + on-chain) *** ### Escenarios de fallo #### Saldo insuficiente (Ruta A) * Creación de la orden bloqueada * Se solicita al comprador que recargue o use la Ruta B #### Fallo de pago (Ruta B) * El escrow permanece sin financiar * La orden no comienza * El comprador vuelve a intentar el pago #### Fallo en la financiación del escrow * Orden marcada como fallida * No se permite la entrega * Reintento manual o automatizado *** ### Resumen educativo | Escenario | Acción del usuario | Resultado | | ----------------------------- | ----------------------------- | ---------------------------------- | | El comprador tiene fondos | Hacer clic en Comprar | Escrow financiado al instante | | El comprador carece de fondos | Hacer clic en Comprar → Pagar | Escrow financiado después del pago | | Plataforma | — | Nunca retiene fondos | | Vendedor | — | Protegido por escrow | *** ### Invariante clave (Muy importante) > **Ninguna orden puede entrar en “En progreso” a menos que el escrow esté completamente financiado.** Esta es la garantía de seguridad central que Offer Hub aplica.