[XLM-12] Escrow de Stellar en StellarClient

[grantfox-oss]

Contexto obligatorio: PLAN_STELLAR.md (decisión D4, invariante I3) y ISSUES_STELLAR.md.
Ola 2 — bloqueada por #2, #5 y #6.
Consume el contrato C4 (esquema de chain_data, definido en #5).

Problema

El escrow contra calidad solo existe en XRPL. Es la funcionalidad más distintiva de la plataforma y no tiene equivalente en Stellar.

Por qué importa

Sin escrow, Stellar es un riel de segunda dentro de la propia plataforma. El invariante I3 exige además que sea igual de restrictivo que el de XRPL: los fondos solo pueden terminar en el productor o de vuelta en el operador tras el vencimiento.

Alcance

Llevar a core/ledger/stellar.py el diseño ya validado en #2, con la misma firma que los métodos de XRPLClient:

• create_escrow(...) → CreateAccount + TX_SETUP, devolviendo en el diccionario los datos de chain_data (contrato C4): escrow_account, release_xdr, refund_xdr, sequence.
• finish_escrow(...) → enviar TX_LIBERAR.
• cancel_escrow(...) → enviar TX_REEMBOLSO.
• Extender el Protocol de [XLM-04] Protocolo LedgerClient y shim de XRPLClient #4 con los tres métodos de escrow.
• La comisión de las transacciones preautorizadas se fija holgada (10 000 stroops) porque el hash la incluye; documentar el fee-bump como salida de emergencia.

Fuera de alcance

• Cualquier UI — es [XLM-13].
• Firma remota — es [XLM-19].

Criterios de aceptación

• Las pruebas negativas de [XLM-02] Spike: escrow con transacciones preautorizadas #2 se reproducen como tests automatizados donde sea posible.
• chain_data se serializa exactamente según el contrato C4.
• El ciclo completo corre en testnet por ambos desenlaces (liberación y reembolso).
• Los métodos de escrow de XRPL siguen intactos.

Pruebas

Unitarias con Horizon mockeado para la construcción de las transacciones y la asignación de secuencias; prueba manual en testnet de ambos ciclos, documentada en un comentario con hashes.

Dependencias

• Bloqueada por: [XLM-02] Spike: escrow con transacciones preautorizadas #2 (spike de escrow), [XLM-06] Modelo de datos multicadena #5 (contrato C4), [XLM-05] StellarClient: pagos, saldo, activación #6 (StellarClient base — mismo archivo, va después).
• Bloquea a: [XLM-13].

[ericmt-98]

🔍 Verificación de contracts/htlc-core — 22/07/2026

Se revisaron htlc-core (trait compartido), micopay-escrow y atomic-swap.

Lo que encaja perfecto

Requisito	Contrato
Beneficiario fijo (invariante I3)	✅ LockParams.counterparty se fija en lock(); los fondos solo pueden ir ahí
Llave = preimagen SHA-256	✅ secret_hash: BytesN<32> — la misma preimagen de 32 bytes de generate_escrow_condition() sirve en las dos cadenas
Reembolso permissionless tras vencimiento	✅ refund() — "Can be called by anyone"
Ventana configurable por operación	✅ timeout_minutes
Sin comisión forzada	✅ platform_fee acepta 0

Eso último es el hallazgo bonito: XRPL envuelve sha256(preimagen) en DER y Soroban toma el hash crudo, pero es el mismo secreto. La narrativa del pacs.002 como llave se conservaría idéntica en ambas cadenas, sin la asimetría fulfillment/XDR que hoy tiene el plan.

El bloqueador

// micopay-escrow/src/lib.rs, en release()
trade.buyer.require_auth();

El receptor tiene que firmar para cobrar. atomic-swap tiene lo mismo (counterparty.require_auth()).

Eso invierte el flujo: en XRPL la cooperativa llama a EscrowFinish con el fulfillment y el productor no hace nada — solo recibe. Con estos contratos el productor tendría que invocar un contrato Soroban para cobrar. Los productores de café tienen una dirección, no una app. No es un detalle de implementación, es un cambio de producto.

La restricción existe por el caso de uso de MicoPay: en el intercambio de efectivo el comprador está presente y revela el secreto por QR, así que ya está actuando. No es un requisito de seguridad — el destino está fijo desde lock(), así que conocer el secreto ya es la autorización. Quitar require_auth() da exactamente la semántica de XRPL, sin debilitar nada.

Hallazgos operativos

• Un solo TokenId por despliegue. initialize(admin, token_id, platform_wallet) fija el token para toda la instancia. Café necesitaría su propia instancia (reutilizando el WASM ya auditado, no escribiendo contrato).
• Los vencimientos son por secuencia de ledger, no por reloj. timeout_minutes * 12 asumiendo 5s/ledger. XRPL usa tiempo absoluto y EscrowDetail.cancel_after es un datetime — hay deriva que habría que documentar.
• TTL de almacenamiento Soroban ≈ 30 días. Suficiente para una ventana de 7 días, pero hay que tenerlo presente.

Conclusión

Se mantiene el diseño D4 (cuenta efímera + dos transacciones preautorizadas) como camino de implementación: es Python puro, sin contrato, sin despliegue y sin auditoría pendiente.

La variante de contrato queda como pista paralela: micopay-protocol#325 propone una tercera implementación del trait HashedTimeLock con release permissionless. Si aterriza, sustituye a D4 sin tocar nada por encima de StellarClient — para eso está la abstracción LedgerClient.