Interoperabilità dei partecipanti

(Sezione Ecosistema e Rete)

1) Cos'è l'interoperabilità dei partecipanti

Interoperabilità è la capacità di diverse organizzazioni (operatori, studi, PSP, KYC/AML provider, ponti, affiliati, analisti e governance) di interagire in modo affidabile tra loro attraverso protocolli e contratti concordati, mantenendo la sicurezza, la privacy e la riproduzione dei risultati aziendali.

• Velocità di integrazione e scalabilità (time-to-integration).
• Prevedibilità (SLO/SLA stabili per flussi critici).
• Sicurezza e compilazione (diritti minimi, verifiche).
• Evoluzione senza interruzioni (versioning, backward-compatibilità).

2) Livelli di interoperabilità (modello di livelli)

1. Trasporti e rete: HTTP/2/3, gRPC/QUIC, WebSockets, P2P, mTLS.
2. Identità e fiducia: org _ id, peer _ id, X.509/mTLS, firme, rotazione delle chiavi.
3. Eventi e dati: diagrammi di eventi unificati, cataloghi di risorse/reti, idempotency.
4. Processi e contratti aziendali: payout/settement, attribuzione, rischio-segnale, replica dei limiti.
5. Controllo/livello legale: SLA/SLO, DPA, licenze, regolamenti di governance.
6. Osservabilità e qualità: SLI/SLO, logica, traccia, controllo.

Ogni strato ha i propri contratti, test e criteri di compatibilità.

3) Principi di progettazione

Contract-first: API/schemi/eventi vengono formalizzati prima dell'implementazione.
Modifiche Backward-compatibile: strategia «solo aggiunta di campi» e finestra di deprecazione per 90 giorni.
Capability negotion: i membri condividono le funzionalità supportate e selezionano un sottoinsieme condiviso.
Isolamento e PoLP: la disponibilità e i limiti sono «minimi necessari».
Idermotica e determinismo: operazioni di ripetizione-sicurezza, regole di conflitto prevedibili.
Osservabilità predefinita: correlazione query/eventi (trace-id), ricevute verificabili.
Data minimization: assenza di PII nella telemetria/etichetta, alias.

4) Capability negotion (negoziazione opportunità)

Durante la stretta di mano, i partecipanti pubblicano un manifesto di opportunità e versioni.

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 }

Il motore di compatibilità associa i manifesti delle parti e seleziona un profilo di lavoro (ad esempio, 'payouts: v2', 'events: v1. 9`).

5) Contratti API/eventi e schemi

Appalti API: IDL, codici di errore chiari, chiavi Idempotent («Idempotency-Key»), limiti di corpo

Il modello di evento è «deposit», «payout», «bridge», «kyc.», «risk», «product», con campi stabili.
Guide/cataloghi: reti, risorse, metodi di pagamento, versioni SDK, regioni/giurisdizioni.
Contratti dati (Data Contracts) - Vengono testate in CI, le modifiche vengono apportate tramite 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) Versioning e compatibilità

Versioni semantiche: 'MAJOR. MINOR. PATCH`.
Regole MINOR/PATCH - Posteriori; MAJOR - Un'esistenza parallela con «perimetri» (adattati), un deprecato di 90 giorni.
Migration playbooks: modelli di migrazione per API/eventi/directory; emulatori di vecchi formati.

7) Modelli di integrazione (pattern)

Richiest-Reply + Idempotency: rimborsi/limiti/riserve sicuri.
Event-Driven: «sorgenti di verità» inviano le modifiche; Gli iscritti materializzano le vetrine.
Outbox/Inbox: pubblicazione atomatica degli eventi del database; appuntamento idoneo dal sottoscritto.
SAGA (orchestrazione/coreografia) - Operazioni multi-domini coerenti (ad esempio « »).
Dual-write guard - Disattiva le doppie voci dirette senza outbox.
Replay/Backfill: ripristino di emergenza mantenendo l'ordine e la finalizzazione.

8) Sicurezza e fiducia

mTLS e allega le chiavi a «org _ id/peer _ id».
Firma eventi, registro di fiducia (chi e cosa ha firmato/ricevuto).
RBAC/ABAC e quote: diritti di ruolo, limiti di transazione/volume.
Il segreto-gestione è la rotazione, il divieto dei token «lunghi», scorciatoie brevi.
PII/privacy: tornizzazione, segregazione regionale dei dati (EU/ROW), processi DSR (rimozione/esportazione).
Protezione contro gli abusi: limiti velocity, segnali anti-frode, controlli sanzionatori.

9) SLI/SLO e osservabilità dell'interoperabilità

• «p95 Time-to-Acknowledge».
• «p95 End-to-End» (creazione di finalizzazione/esecuzione).
• «Success Rate» per tipo di evento/operazione.
• «Schema/Contract Compliance%» (messaggi validi).
• Proof Coverage% (percentuale di prove sottoscritte/allegate).
• `Error Budget Burn` по P0/P1.

• P0 (pagamenti/ponte): p95 E2E da 5 min, Success da 99. 5%, Ack 2.
• P1: Freshness p95 da 3 min, Compliance da 99. 9%.
• Contratti dati: Draft MTTA da 5 min, Breaking changes = 0 senza MAJOR.

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

10) Matrice di compatibilità (test-design)

• Script: payouts, deposits, bridge, risk, product, telemetry.
• API v2. 6/v2. 5, events v1. 9/v1. 8.
• Modalità di rete: normale, degrado, riorghi, ritardi DA.
• Giurisdizioni: EU/UK/TR/LA - diverse directory e regole.

Autostop: test contrattuali (producer/consumer), idempotency, retry/compensation, schema-linters, profili di carico.

11) Diagrammi e cartelle

Directory funzionalità (SQL)

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

Registro contratti/versioni

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

Monitoraggio della 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) Configurazioni (YAML)

Criteri di versioning

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

Idempotency e ripetizioni

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

Classi di 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) Regolamenti operativi

Ogni giorno: rapporto compliance su contratti/schemi, chiavi scadute, SLO burn.
Settimanale: Comitato interoperabilità (nuove opportunità, migrazioni, deprecati).
Prima del rilascio, il contratto-test, il canary con le metriche di vetro, i piani di ritocco.
Gli incidenti sono un unico canale di stato, modelli di comunicazione ai partner, post mortem da 72 ore.

14) Playbook incidenti

A. Schema/Contract Drift

1. Abilita modalità rigorosa (ritaglia i messaggi non conformi),

2. aprire l'incidente e avvisare le fonti,

3. generare diff,

4. rilascia la scheda/fix,

5. post mortem e aggiornamento dei linter.

B. Ripetizioni di massa/ripresa-messaggi

1. Controlla idempotenza/chiavi,

2. abilitare i filtri di deduplicazione,

3. limitare il rumoroso produttore,

4. ricalcolare le vetrine.

C. Aumento della latitanza/errori ack

1. Priorità P0, aumento dei consumatori,

2. ridurre temporaneamente il P2 sampling,

3. Analisi delle rotte e dei colli di rete.

D. Compromissione della chiave del partecipante

1. Revoke, rotazione, aggiornamento del registro di sicurezza,

2. Riscrivere battaglie e certificati critici,

3. verifica delle attività, report ai partner.

E. Non corrispondenza di directory (asset/reti)

1. Quarantena di messaggi in conflitto,

2. ripristinare la directory,

3. ricalcolare le unità,

4. Pubblicazione delle correzioni.

15) Assegno-foglio di implementazione

1. Definire livelli e contratti (API, eventi, directory, chiavi).
2. Avviare capability negotion e Registro versioni/funzionalità.
3. Attivate Idampotenza, Quote, QoS, Firme e mTLS.
4. Regolare SLI/SLO, dashboard e alert (Ack, E2E, Compliance).
5. Automatizzare i test contrattuali e la matrice di prova di compatibilità.
6. Immettere le regole relative ai deprecati e alle migrazioni (MAJOR).
7. Rivedere regolarmente cataloghi/regole di privacy e accessibilità.

16) Glossario

Capability negotion - Allineamento delle funzionalità e del profilo di lavoro supportati.
Contract-first - Progettazione di interfacce attraverso contratti formali prima dell'implementazione.
Idempotency - ripetizione-sicurezza delle operazioni.
Schema/Contract Drivt - La soluzione dei messaggi effettivi con i contratti dichiarati.
PoLP è il principio dei diritti minimi necessari.
Compliance% è la percentuale di messaggi/richieste corrispondenti al contratto.

L'interoperabilità dei partecipanti è un sistema gestito di contratti, versioni, capacità e osservabilità. In base a questo framework, l'ecosistema garantisce una rapida integrazione, flussi aziendali sostenibili e un'evoluzione sicura senza interruzioni, dai livelli di rete e identità ai processi e ai processi.