Interopérabilité des participants

(Section : Écosystème et réseau)

1) Qu'est-ce que l'interopérabilité des participants

L'interopérabilité est la capacité des différentes organisations (opérateurs, studios, PSP, KYC/AML-fournisseurs, ponts, affiliations, analystes et howernance) à communiquer de manière fiable par le biais de protocoles et de contrats convenus, tout en préservant la sécurité, la confidentialité et la reproductibilité des résultats commerciaux.

• Vitesse d'intégration et mise à l'échelle (time-to-integration ↓).
• Prévisibilité (SLO/SLA stables sur les flux critiques).
• Sécurité et conformité (droits minimaux suffisants, audit).
• Évolution sans rupture (versioning, compatibilité backward).

2) Niveaux d'interopérabilité (modèle de calque)

1. Transport et réseau : HTTP/2/3, gRPC/QUIC, WebSockets, P2P, mTLS.
2. Identité et confiance : org_id, peer_id, X.509/mTLS, signatures, rotation des clés.
3. Événements et données : schémas d'événements unifiés, répertoires d'actifs/réseaux, idempotency.
4. Processus et contrats : payout/settlement, attribution, signaux de risque, réplication des limites.
5. Gestion/couche juridique : SLA/SLO, DPA, licences, règlements de howernance.
6. Observabilité et qualité : SLI/SLO, loging, traçabilité, audit.

Chaque couche a ses propres contrats, tests et politiques d'interopérabilité.

3) Principes de conception

Contrat-first : les API/schémas/événements sont formalisés avant l'implémentation.
Modifications backward-compatibles : stratégie « addition de champs uniquement » et deprecate-fenêtre ≥ 90 jours.
Capability negotiation : les participants échangent les capacités prises en charge et choisissent un sous-ensemble commun.
Isolation et PoLP : accès et limites émis « minimum nécessaire ».
Idempotence et déterminisme : opérations de répétition-sécurité, règles prévisibles du conflit.
Observation par défaut : corrélation requêtes/événements (trace-id), reçus vérifiables.
Minimisation des données : absence de PII dans la télémétrie/labels, pseudonymisation.

4) Capability negotiation (négociation des capacités)

En cas de poignée de main, les participants publient un manifeste des possibilités et des versions.

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 }

Le moteur de compatibilité fait correspondre les manifestes des parties et sélectionne le profil de travail (par exemple, 'payouts : v2', 'events : v1. 9`).

5) Contrats API/événements et schémas

Contrats API : OpenAPI/gRPC IDL, codes d'erreur clairs, clés idempotentes ('Idempotency-Key'), limites de corps.
Modèle d'événement : 'deposit.', 'payout.', 'bridge.', 'kyc.', 'risk.', 'product.' - avec des champs stables.
Annuaires/catalogues : réseaux, actifs, méthodes de paiement, versions SDK, régions/juridictions.
Contrats de données (Data Contracts) : sont testés dans CI, les modifications sont via governance avec 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) Versioning et compatibilité

Versions sémantiques : 'MAJOR. MINOR. PATCH`.
Règles : MINEUR/PATCH - rétrocompatible ; MAJOR est une existence parallèle avec des « traverses » (adapters), deprecate ≥ 90 jours.
Migration playbooks : modèles de migration pour API/événements/répertoires ; émulateurs d'anciens formats.

7) Modèles d'intégration (modèles)

Request-Reply + Idempotency : paiements sécurisés/limites/réserves.
Event-Driven : Les « sources de vérité » envoient le changement ; les abonnés matérialisent les vitrines.
Outbox/Inbox : publication atomique des événements de la base de données ; accueil idempotent chez l'abonné.
SAGA (orchestration/chorégraphie) : opérations multi-domaines concertées (par exemple « popolneniye→igrovoye sobytiye→vyplata »).
Dual-write guard : interdiction des doubles enregistrements directs sans outbox.
Replay/Backfill : Récupération après défaillance avec maintien de l'ordre et finalisation.

8) Sécurité et confiance

mTLS et référence des clés à 'org _ id/peer _ id'.
Signatures d'événements, journal de confiance (qui et ce qu'il a signé/reçu).
RBAC/ABAC et quotas : droits par rôle, limites par activité/volume.
Gestion secrète : rotation, interdiction des tokens « longs », boules courtes.
PII/vie privée : Tokénisation, ségrégation régionale des données (EU/ROW), processus DSR (suppression/exportation).
Protection contre les abus : limites de velocity, signaux anti-frod, contrôles de sanctions.

9) SLI/SLO et l'observabilité de l'interopérabilité

• 'P95 Time-to-Acknowledge '.
• « p95 End-to-End » (création → finalisation/exécution).
• « Taux de réussite » par type d'événement/opération.
• Schema/Contract Compliance % (messages valides).
• « Proof Coverage % » (proportion de preuves signées/jointes).
• `Error Budget Burn` по P0/P1.

• P0 (paiements/pont) : p95 E2E ≤ 5 min, Success ≥ 99. 5 %, Ack ≤ 2 s.
• P1 (produits) : Freshness p95 ≤ 3 min, Conformité ≥ 99. 9%.
• Contrats de données : Drift MTTA ≤ 5 min, Breaking changes = 0 sans MAJOR.

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

10) Matrice de compatibilité (conception de test)

• Scénarios : payouts, deposits, bridge, risk, product, telemetry.
• Versions : API v2. 6/v2. 5, events v1. 9/v1. 8.
• Modes réseau : normal, dégradation, réorgues, retards DA.
• Juridictions : EU/UK/TR/LA - différents catalogues et règles.

Autotests : tests contractuels (producteur/consommateur), idempotency, retry/compensation, schema-linters, profils de charge.

11) Schémas et catalogues de référence

Répertoire des capacités (SQL)

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

Registre des contrats/versions

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)
);

Surveillance de la compatibilité

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) Configurations (YAML)

Politique de versioning

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

Idempotency et répétitions

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

Classes 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) Règlements opérationnels

Quotidien : rapport de conformité sur les contrats/schémas, clés périmées, SLO burn.
Hebdomadaire : Comité d'interopérabilité (nouvelles possibilités, migrations, déprécations).
Avant la sortie : tests contractuels, canary avec métriques « verre », plans de retour.
Incidents : Canal de statut unique, modèles de messages aux partenaires, post-mortem ≤ 72 h.

14) Playbook des incidents

A. Schema/Contract Drift

1. Activer le « mode strict » (couper les messages non conformes),

2. ouvrir l'incident et en informer les sources,

3. générer le diff,

4. libérer l'adaptateur/fix,

5. post-mortem et mise à jour des linters.

B. Répétitions massives/doublons

1. Vérifier l'idempotence/clés,

2. activer les filtres dedup,

3. limiter le producteur bruyant,

4. recalculer les vitrines.

C. Augmentation de la latence/suintement ack

1. Hiérarchiser P0, augmenter les consumers,

2. réduire temporairement le sample P2,

3. analyse des itinéraires et des goulets d'étranglement du réseau.

D. Compromettre la clé du participant

1. Revoke, rotation, mise à jour du registre de confiance,

2. la réécriture des trampolines/certificats critiques,

3. audit des actions, rapport aux partenaires.

E. Incohérence des répertoires (actifs/réseaux)

1. Mise en quarantaine des messages de conflit,

2. le retrait du catalogue,

3. recalculer les agrégats,

4. publication des corrections.

15) Chèque de mise en œuvre

1. Identifiez les niveaux et les contrats (API, événements, répertoires, clés).
2. Exécutez capability negotiation et le registre des versions/fonctionnalités.
3. Inclure idempotence, quotas, QoS, signatures et mTLS.
4. Configurez SLI/SLO, dashboards et alertes (Ack, E2E, Compliance).
5. Automatisez les tests contractuels et la matrice de test de compatibilité.
6. Entrez les règlements de déprécation et de migration (MAJOR en parallèle).
7. Révisez régulièrement les catalogues/règles de confidentialité et d'accès.

16) Glossaire

Capability negotiation - concilier les capacités prises en charge et le profil de travail.
Contrat-first - conception d'interfaces via des contrats formels avant la mise en œuvre.
Idempotency - Sécurité des opérations.
Schema/Contract Drift - divergence des messages réels avec les contrats annoncés.
PoLP est le principe des droits minimaux nécessaires.
Conformité % est la proportion de messages/demandes conformes au contrat.

Résultat : L'interopérabilité des participants est un système géré de contrats, de versions, de capacités et d'observation. En suivant ce cadre, l'écosystème permet des intégrations rapides, des flux d'affaires durables et une évolution sûre et sans rupture, du niveau du réseau et des identités aux processus et aux howernance.