Interoperabilidad de los participantes

(Sección: Ecosistema y Red)

1) Qué es la interoperabilidad de los participantes

La interoperabilidad es la capacidad de diferentes organizaciones (operadores, estudios, PSP, proveedores KYC/AML, puentes, afiliados, análisis y gobierno) para interactuar de manera segura entre sí a través de protocolos y contratos negociados, manteniendo la seguridad, privacidad y reproducibilidad de los resultados del negocio.

• Velocidad de integración y escala (time-to-integration ↓).
• Previsibilidad (SLO/SLA estables sobre flujos críticos).
• Seguridad y cumplimiento (derechos mínimos suficientes, auditoría).
• Evolución sin roturas (versionamiento, compatibilidad con backward).

2) Niveles de interoperabilidad (modelo de capas)

1. Transporte y red: HTTP/2/3, gRPC/QUIC, WebSockets, P2P, mTLS.
2. Identidades y confianza: org_id, peer_id, X.509/mTLS, firmas, rotación de claves.
3. Eventos y datos: esquemas de eventos unificados, directorios de activos/redes, idempotency.
4. Procesos y contratos comerciales: payout/settlement, atribución, señales de riesgo, replicación de límites.
5. Gestión/capa legal: SLA/SLO, DPA, licencias, reglamentos de gobierno.
6. Observabilidad y calidad: SLI/SLO, lógica, seguimiento, auditoría.

Cada capa tiene sus propios contratos, pruebas y políticas de compatibilidad.

3) Principios de diseño

Contract-first: API/diagramas/eventos se formalizan antes de la implementación.
Cambios compatibles con backward: estrategia de «sólo agregar campos» y una ventana de depreciación ≥ 90 días.
Capability negotiation: los participantes intercambian capacidades soportadas y seleccionan un subconjunto común.
Aislamiento y PoLP: los accesos y límites emitidos son «mínimos necesarios».
Idempotencia y determinismo: operaciones repetitivas-seguras, reglas predecibles del conflicto.
Observabilidad predeterminada: correlación de solicitudes/eventos (trace-id), recibos verificables.
Minimización de datos: ausencia de PII en telemetría/etiquetas, pseudonimización.

4) Capability negotiation (negociación de oportunidades)

En el apretón de manos, los participantes publican un manifiesto de posibilidades y versiones.

yaml participant:
org_id: "ORG:ACME"
versions:
api: "2. 6. 1"
events: "1. 9. 0"
capabilities:
payouts: { create: true, cancel: true, currencies: [USD, EUR, USDC] }
kyc: { level: ["basic","enhanced"], sla_minutes_p95: 15 }
bridge: { proof: ["light","zk"], challenge_supported: true }
telemetry: { qos: ["P0","P1"], traces: true }
limits:
payouts_daily_usd: 1_000_000 rate_limits: { create_per_minute: 500 }

El motor de compatibilidad asigna los manifiestos de las partes y selecciona un perfil de trabajo (por ejemplo, 'payouts: v2', 'events: v1. 9`).

5) Contratos API/eventos y esquemas

API-Contracts: OpenAPI/gRPC IDL, códigos de error claros, claves idempotentes ('Idempotency-Key'), limitaciones corporales.
Modelo de eventos: 'depósito.', 'payout.', 'puente.', 'kyc.', 'riesgo.', 'producto.' - con campos estables.
Directorios/directorios: redes, activos, métodos de pago, versiones SDK, regiones/jurisdicciones.
Contratos de datos: se prueban en CI, los cambios son a través de governance con timelock.

yaml event:
id: uuid ts: timestamp_utc type: payout. created    payout. finalized    bridge. lock...
src_org: string dst_org: string payload: object trace_id: string idempotency_key: string signature: string # source signature

6) Versificación e interoperabilidad

Versiones semánticas: 'MAJOR. MINOR. PATCH`.
Reglas: MINOR/PATCH - atrás-compatible; MAJOR es una existencia paralela con «travesaños» (adaptadores), deprechate ≥ 90 días.
Migration playbooks: plantillas de migración para API/eventos/directorios; emuladores de formatos antiguos.

7) Plantillas de integración (patrones)

Request-Reply + Idempotency: pagos seguros/límites/reservas.
Event-Driven: las «fuentes de la verdad» envían cambios; los suscriptores materializarán las vitrinas.
Outbox/Inbox: publicación atómica de eventos de la DB; recepción idempotiva por parte del suscriptor.
SAGA (orquestación/coreografía): operaciones multi-dominio coherentes (por ejemplo, «popolneniye→igrovoye sobytiye→vyplata»).
Guardia de escritura dual: prohibición de grabaciones dobles directas sin outbox.
Replay/Backfill: recuperación de fallos con orden y finalización.

8) Seguridad y confianza

mTLS y el enlace de claves a 'org _ id/peer _ id'.
Firmas de eventos, registro de confianza (quién y qué firmó/recibió).
RBAC/ABAC y cuotas: derechos por función, límites por operación/volumen.
Gestión de secretos: rotación, prohibición de fichas «de larga duración», escopetas cortas.
PII/privacidad: tokenización, segregación regional de datos (EU/ROW), procesos DSR (eliminación/exportación).
Protección contra abusos: velocity-limites, señales antifraude, controles sancionadores.

9) SLI/SLO y observabilidad de la interoperabilidad

• 'p95 Time-to-Acknowledge' (recibo del evento).
• 'p95 End-to-End' (creación → finalización/ejecución).
• 'Tasa de éxito' por tipo de evento/operación.
• 'Schema/Aprox Compliance%' (mensajes válidos).
• 'Proof Coverage%' (porcentaje de pruebas firmadas/adjuntas).
• `Error Budget Burn` по P0/P1.

• P0 (pagos/puente): p95 E2E ≤ 5 min, éxito ≥ 99. 5%, Ack ≤ 2 s.
• P1 (productos): Freshness p95 ≤ 3 min, Compliance ≥ 99. 9%.
• Contratos de datos: Drift MTTA ≤ 5 min, Breaking changes = 0 sin MAJOR.

Дашборды: Interop Ops, Contract Health, Latency & Success, Schema Drift, Security & Keys.

10) Matriz de compatibilidad (diseño de prueba)

• Scripts: payouts, deposits, bridge, risk, product, telemetry.
• Versiones: API v2. 6/v2. 5, events v1. 9/v1. 8.
• Modos de red: normal, degradación, reorgía, latencia DA.
• Jurisdicciones: EU/UK/TR/LA - diferentes catálogos y normas.

Autotestas: pruebas contractuales (producer/consumer), idempotency, retry/compensation, schema-linters, perfiles de carga.

11) Diagramas de referencia y catálogos

Catálogo de capacidades (SQL)

sql
CREATE TABLE capabilities (
org_id TEXT,
cap_name TEXT,
version TEXT,
params JSONB,
PRIMARY KEY (org_id, cap_name)
);

Registro de contratos/versiones

sql
CREATE TABLE contracts (
name TEXT, kind TEXT,     -- api    events    catalog version TEXT, status TEXT,  -- active    deprecated    retired breaking BOOLEAN DEFAULT FALSE,
effective_from TIMESTAMPTZ,
deprecates_at TIMESTAMPTZ,
PRIMARY KEY (name, version)
);

Monitor

sql
SELECT name, version, 100. 0SUM(CASE WHEN compliant THEN 1 END)/COUNT() AS compliance_pct
FROM contract_checks
WHERE ts >= now() - INTERVAL '7 days'
GROUP BY name, version;

12) Configuraciones (YAML)

Política de versionamiento

yaml versioning:
events: { compatibility: "BACKWARD", deprecate_days: 90 }
api:  { parallel_majors: true, support_minors: 2 }

Idempotency y repeticiones

yaml idempotency:
header: "Idempotency-Key"
ttl_hours: 72 conflict_policy: "prefer-latest-payload-with-signature"

Clases QoS

yaml qos:
P0: { ack_timeout_ms: 2000, retries: 3, backoff_ms: [100,400,800] }
P1: { ack_timeout_ms: 5000, retries: 2 }
P2: { best_effort: true }

13) Normas de funcionamiento

Diariamente: informe de cumplimiento de contratos/esquemas, claves vencidas, SLO burn.
Semanalmente: comité de interoperabilidad (nuevas oportunidades, migraciones, deprecates).
Antes del lanzamiento: pruebas de contrato, canario con métricas de «cristal», planes de retroceso.
Incidentes: un único canal de estado, plantillas de mensajes a los socios, post-mortem ≤ 72 h.

14) Incidentes de Playbook

A. Schema/Contract Drift

1. Habilitar el «modo estricto» (cortar mensajes no conformes),

2. abrir el incidente y notificar a las fuentes,

3. generar diff,

4. liberar el adaptador/fix,

5. post-mortem y actualización de linternas.

B. Repeticiones masivas/mensajes de toma

1. Comprobar la idempotencia/llaves,

2. habilitar filtros de dedoup

3. limitar al productor ruidoso,

4. volver a calcular las vitrinas.

C. Aumento de la latencia/reducción de ack

1. Priorizar P0, aumentar los consumidores,

2. reducir temporalmente el P2 sampling,

3. análisis de rutas y cuellos de botella de red.

D. Compromiso de clave de miembro

1. Revoke, rotación, actualización del registro de confianza,

2. reescritura de batches/certificados críticos,

3. auditoría de acciones, informe a los socios.

E. Discrepancia de directorios (activos/redes)

1. Cuarentena de mensajes de conflicto,

2. revertir el directorio,

3. volver a calcular las unidades,

4. Publicación de correcciones.

15) Lista de verificación de implementación

1. Definir niveles y contratos (API, eventos, directorios, claves).
2. Ejecute capability negotiation y el registro de versiones/capacidades.
3. Incluya idempotencia, cuotas, QoS, firmas y mTLS.
4. Configure SLI/SLO, dashboards y alertas (Ack, E2E, Compliance).
5. Automatice las pruebas de contrato y la matriz de prueba de compatibilidad.
6. Introduzca las regulaciones de depreciados y migraciones (MAJOR en paralelo).
7. Revise regularmente los directorios/reglas de privacidad y acceso.

16) Glosario

Capability negotiation - Alinear las capacidades soportadas y el perfil de trabajo.
Contract-first - Diseño de interfaces a través de contratos formales antes de la implementación.
Idempotency - repetición-seguridad de las operaciones.
Schema/Contract Drift - discrepancia de los mensajes reales con los contratos anunciados.
PoLP es el principio de los derechos mínimos necesarios.
Compliance% es la proporción de mensajes/solicitudes que corresponden al contrato.

En pocas palabras: la interoperabilidad de los participantes es un sistema gestionado de contratos, versiones, capacidades y observabilidad. Siguiendo este marco, el ecosistema proporciona integraciones rápidas, flujos de negocio sostenibles y una evolución segura sin interrupciones, desde el nivel de red e identidad hasta los procesos y el gobierno.