Saltar al contenido principal

Known limitations

Hallazgos reales, confirmados en el código (o confirmados en vivo) — varios de los cuales ninguna prueba unitaria aislada había detectado antes de que existiera este Business Case. La versión técnica completa, con citas de archivo:línea, vive en examples/marketplace-mercatto/GAPS.md; esta página es el índice legible para humanos, en el orden en que los capítulos las referencian.

F.1 — El Settlement no depende del estado del Workflow​

executeSettlement() puede llamarse con o sin que se haya ingerido nunca un evento de entrega — Ishtaran valida invariantes financieros, nunca hechos del mundo físico. Este es un diseño deliberado, no un bug: confirmar la entrega antes del settlement es trabajo del integrador. Ver Confirming delivery.

F.2 — No hay clawback después de un Settlement completo​

Una vez que un Settlement distribuyó por completo el Distributable Amount, no existe ningún mecanismo de la plataforma para revertir lo que ya se acreditó. Cualquier corrección después de ese punto es un movimiento nuevo y separado — nunca una edición al Settlement histórico.

F.3 — No hay ruta pública para leer la Pricing Policy por adelantado​

Un integrador solo conoce el porcentaje de Fee real a partir del resultado de un Settlement en sí — nunca antes de llamarlo. Ver Settlement and Split.

F.4 — No hay mecanismo oficial de Sandbox para saltar los cooldowns de Withdrawal​

Ni el cooldown de activación de destino de 24h ni el cooldown de cambio de destino de 168h pueden adelantarse. Este Business Case nunca los salta — ver Withdrawal.

F.9 — Algunas llamadas necesitan una sesión de Member, no una API Key​

accounts.authorizeApplication, cada mutación de workflows.*, y events.ingest rechazan hoy una Application API Key. Ver Architecture.

F.10 — No hay API financiera self-service para AccountHolders​

El propio login de un vendedor solo puede gestionar su propia identidad — no revisar su balance ni solicitar un retiro. Cada llamada financiera en su nombre usa las credenciales propias del marketplace. Ver Seller balance.

F.15 — Los Settlements parciales rápidos pueden producir un conflicto de concurrencia transitorio​

Comportamiento estándar y esperado de concurrencia optimista (409 CONCURRENT_MODIFICATION) cuando llamadas de Settlement caen muy cerca una de otra sobre el mismo pedido — la respuesta correcta es un reintento acotado, igual que en cualquier API de concurrencia optimista. Ver Partial Settlement.

F.16 — El camino de ejecución real del Settlement es SelfCustody, no "calcula el Fee y registra el Ledger"​

Versiones anteriores de este tutorial (y de su propio diagrama de arquitectura) describían executeSettlement como si registrara Ledger Entries directamente. Eso era correcto para el modelo ManagedCustody de la plataforma, pero SelfCustody — el único modo que este Sandbox realmente corre hoy (DEC-037, docs/architecture/CUSTODY-EXECUTION-MODES.md) — es distinto: executeSettlement construye un SigningRequest real y retorna con el Settlement en Executing; nada es final, y no existe ninguna Ledger Entry todavía, hasta que cada execution leg se firma, se transmite, y se confirma. Ver Settlement and Split para la mecánica completa, y self-custody-settlement.ts para el código de firmar/confirmar/esperar que reutiliza cada capítulo desde ahí en adelante.

F.17 — El Settlement ahora requiere un NetworkCostPayerAccount registrado​

Transmitir las execution legs de un Settlement cuesta recursos de red reales, cobrados por separado del Platform Fee — Mercatto tiene que decirle a Ishtaran, una vez por AssetNetwork, cuál de sus propias Accounts paga eso. Sin esto, executeSettlement falla antes incluso de construir ningún SigningRequest. Ver Settlement and Split y register-network-cost-payer-account.ts.

F.18 — Pregunta de producto abierta: ¿cómo recibe su primer saldo un NetworkCostPayerAccount nuevo?​

Registrar un NetworkCostPayerAccount (F.17) no basta por sí solo — la plataforma también verifica el saldo Available real de esa Account antes de dejarla pagar nada, y hoy no existe ninguna ruta para financiar una Account de forma independiente de una Transaction. Para el primer Settlement real de un marketplace nuevo, esto es un problema real de huevo-y-gallina que la plataforma todavía no resuelve: nada se ha liquidado todavía para financiar la cuenta, pero financiarla requiere una liquidación. La verificación local de este tutorial sorteó esto con una herramienta solo de desarrollo, nunca algo utilizable en Sandbox o Production — esto queda registrado como una decisión abierta para el dueño de la plataforma, no resuelta aquí. Ver GAPS.md §F.18 para el detalle completo.

Lo demás​

GAPS.md también documenta hallazgos de ejecución de la plataforma fuera del alcance propio de este tutorial, del mismo pase de auditoría:

  • Todavía nada conecta la aprobación de Settlement/Withdrawals directamente con la creación automática de un SigningRequest — el propio código de este tutorial (release-order.ts, withdraw.ts) es quien cumple ese rol hoy, llamando a executeSettlement/request y luego manejando el protocolo de firma explícitamente. Es trabajo real de cualquier forma, tanto en Sandbox como en Production — no es un gap exclusivo de Production.
  • La ejecución blockchain real — una transacción firmada realmente llegando a una red real — es exclusiva de Production y todavía no está disponible; el broadcast/confirmación de Sandbox es simulado de principio a fin, deliberadamente, no un atajo que este tutorial esconda.

Dos hallazgos anteriores de esta lista — el modelo de Network Fee sin distinguir el activo transferido del recurso que paga la ejecución en red, y la falta de una verificación previa al broadcast — se resolvieron con el Network Execution Engine de la plataforma (ver Settlement and Split y Withdrawal); GAPS.md §F.13/F.14 mantiene los hallazgos originales registrados junto con lo que realmente cambió.

Ninguno de estos se corrige inventando una solución alternativa: cada uno o bien se corrigió de raíz (ver el propio rastro de auditoría de Ledger/Settlement de la plataforma) o está documentado con la precisión suficiente para que una sesión futura retome exactamente donde esta lo dejó.