khadhroony-bot3/docs/guides/RPC_BACKFILL_AND_WEBSOCKET.md

Guide RPC, backfill et WebSocket

Séparation des responsabilités

• kb-onchain-transport communique avec les endpoints ;
• kb-pipeline orchestre les campagnes ;
• kb-store persiste les acquisitions canoniques et la progression ;
• kb-app-demo-desktop fournit une interface opérateur ;
• kb-pipeline-demo-scenarios construit et exécute les scénarios réutilisables de démonstration et de validation, notamment sur Devnet.

Passage d’un scénario validé vers le pipeline

kb-pipeline-demo-scenarios n’est pas la destination finale d’une logique réutilisable en production. Son rôle est de composer des APIs publiques existantes, préparer les fixtures, imposer les garde-fous opérateur et démontrer un parcours complet sur un réseau de validation.

Lorsqu’un composant d’un scénario est validé et qu’il est générique, déterministe et utilisable indépendamment de la démonstration, il doit résider dans la couche appropriée :

• kb-lib pour le décodage, la matérialisation, la construction d’instructions, les préflights et les politiques de sécurité ;
• kb-onchain-transport pour les opérations réseau génériques ;
• kb-store pour les contrats de persistance ;
• kb-pipeline pour l’orchestration réutilisable, y compris sur Mainnet lorsque le profil, la politique et l’appelant l’autorisent.

La crate de scénarios conserve :

• les fixtures et valeurs de démonstration ;
• la préparation Devnet ;
• les confirmations opérateur propres aux campagnes de validation ;
• les enchaînements de bout en bout destinés à prouver le comportement ;
• les rapports de validation et contrôles postérieurs au scénario.

Une validation Devnet ne provoque pas automatiquement une promotion vers Mainnet. Le composant promu doit également être indépendant du cluster, couvert par des tests, borné, compatible avec les politiques de sécurité et ne pas contenir d’hypothèse propre aux fixtures Devnet.

Rôles d’endpoints

Un endpoint n’est pas supposé supporter toutes les opérations. La configuration attribue des rôles HTTP ou WebSocket, puis les pools sélectionnent une cible compatible.

Avant une campagne :

1. résoudre le profil ;
2. vérifier la présence du rôle requis ;
3. vérifier les limites du fournisseur ;
4. fixer des bornes de pagination, concurrence et retry ;
5. préparer l’observateur et l’annulation coopérative.

Backfill HTTP

Le backfill parcourt les signatures, charge les transactions et les adapte vers le contrat canonique avant stockage.

let summary = match kb_pipeline::execute_http_backfill(
    request,
    observer,
).await {
    std::result::Result::Ok(value) => value,
    std::result::Result::Err(error) => return std::result::Result::Err(error),
};

println!("completed={}", summary.completed);

La frontière de reprise ne progresse qu’au travers des résultats contigus terminés. Une annulation ne doit pas sauter les candidats inachevés.

WebSocket

La session WebSocket appartient au processus applicatif et non à la fenêtre qui l’affiche. Pour demo_ws :

• fermer la fenêtre ne ferme pas une session active ;
• rouvrir la fenêtre relit l’état courant ;
• la déconnexion résulte d’une commande explicite, de la fermeture de l’application ou d’un timeout prévu ;
• les abonnements et notifications restent bornés.

Adaptation canonique

Les réponses fournisseur sont converties avant le pipeline. Les différences legacy/v0, ALT, CPI, erreurs de transaction et encodages doivent rester explicites.

Erreurs

Distinguer :

• transport indisponible ;
• erreur JSON-RPC distante ;
• réponse invalide ;
• adaptation canonique impossible ;
• erreur de stockage ;
• annulation opérateur.

Tests de référence

• pools et rôles d’endpoints ;
• fixtures getTransaction legacy et v0 ;
• pagination et reprise contiguë du backfill ;
• cycles de connexion, abonnement et déconnexion WebSocket ;
• maintien et restauration de l’état desktop.

Références

• kb-onchain-transport/USAGE.md ;
• kb-pipeline/USAGE.md ;
• kb-app-demo-desktop/USAGE.md.