v0.1.0-pre.070

kb-onchain-transport/CHANGELOG.md

@@ -0,0 +1,19 @@
+<!-- file: kb-onchain-transport/CHANGELOG.md -->
+<!-- version: 1 -->
+
+# CHANGELOG — kb-onchain-transport
+
+## 0.1.0-pre.070
+
+- enrichissement du `USAGE.md` avec plusieurs exemples couvrant les principales familles d’API publiques ;
+- ajout du contrat documentaire de la crate ;
+- description des APIs publiques HTTP, WebSocket, JSON-RPC et exécution ;
+- clarification de la séparation entre transport, pipeline, décodage et stockage ;
+- classement des travaux futurs de streaming et résilience dans le TODO.
+
+## 0.1.0-pre.062
+
+- migration et consolidation des anciennes crates RPC de bot2 ;
+- renommage en `kb-onchain-transport` ;
+- conservation des transports HTTP, WebSocket, acquisition canonique, simulation, soumission et confirmation ;
+- adaptation aux normes Rust 2024 et Khadhroony bot3.

kb-onchain-transport/README.md

@@ -0,0 +1,37 @@
+<!-- file: kb-onchain-transport/README.md -->
+<!-- version: 1 -->
+
+# kb-onchain-transport
+
+`kb-onchain-transport` fournit les transports Solana on-chain de `khadhroony-bot3`.
+
+## Responsabilités
+
+- requêtes JSON-RPC HTTP standard ;
+- sessions et pools WebSocket ;
+- routage par rôle d’endpoint ;
+- adaptation des réponses RPC vers les contrats canoniques ;
+- simulation, soumission et confirmation de transactions ;
+- acquisition de signatures et transactions pour le backfill ;
+- validation bornée des paramètres et réponses réseau.
+
+La crate ne décode pas les programmes Solana et ne persiste pas directement les données. Elle alimente `kb-pipeline`, qui orchestre l’acquisition, l’extraction et le replay, et utilise les contrats de `kb-core` et `kb-lib`.
+
+## Surfaces publiques principales
+
+- `HttpClient`, `HttpEndpointPool` ;
+- `SolanaRpcClient`, `RpcEndpoint` ;
+- contrats JSON-RPC ;
+- méthodes HTTP standard et leurs types de configuration ;
+- `WsClient`, `WsEndpointPool`, sessions et abonnements WebSocket ;
+- adaptateurs `getTransaction`, `getSignaturesForAddress` et méthodes d’exécution RPC.
+
+Voir [USAGE.md](USAGE.md) pour les APIs publiques et les exemples.
+
+## Documentation
+
+- [USAGE.md](USAGE.md)
+- [TODO.md](TODO.md)
+- [CHANGELOG.md](CHANGELOG.md)
+- [Architecture du pipeline](../docs/architecture/PIPELINE_ARCHITECTURE.md)
+- [Carte des crates](../docs/architecture/CRATE_MAP.md)

kb-onchain-transport/TODO.md

@@ -0,0 +1,11 @@
+<!-- file: kb-onchain-transport/TODO.md -->
+<!-- version: 1 -->
+
+# TODO — kb-onchain-transport
+
+- [ ] Transport temps réel - étendre le support WebSocket Helius selon les contrats retenus pour `0.13.x`.
+- [ ] Transport temps réel - auditer l’état réel de LaserStream et définir les compléments nécessaires.
+- [ ] Transport temps réel - concevoir l’intégration Yellowstone gRPC sans coupler le pipeline à un fournisseur.
+- [ ] Résilience - formaliser les politiques de reprise, continuité, reconnexion, backpressure et métriques des transports streaming.
+- [ ] Documentation - créer le guide transversal RPC, backfill et streaming à partir des APIs bot3 actuelles.
+- [ ] Tests - compléter les tests d’intégration opt-in pour les rôles d’endpoints et les scénarios de reconnexion.

kb-onchain-transport/USAGE.md

@@ -0,0 +1,147 @@
+<!-- file: kb-onchain-transport/USAGE.md -->
+<!-- version: 2 -->
+
+# Utilisation de kb-onchain-transport
+
+## Objectif
+
+La crate expose les contrats publics nécessaires aux communications RPC HTTP et WebSocket avec Solana.
+
+## Prérequis
+
+- une configuration `kb-config` contenant au moins un endpoint compatible ;
+- un runtime Tokio pour les opérations asynchrones ;
+- des limites et engagements adaptés à l’opération demandée.
+
+## Construire un client HTTP
+
+```rust
+fn build_http_client(
+    endpoint: kb_config::HttpEndpointConfig,
+) -> kb_core::Result<kb_onchain_transport::HttpClient> {
+    let result = kb_onchain_transport::HttpClient::new(endpoint);
+
+    match result {
+        Ok(client) => Ok(client),
+        Err(error) => Err(error),
+    }
+}
+```
+
+## Construire et interroger un pool HTTP
+
+```rust
+fn select_query_client(
+    profile: &kb_config::ProfileConfig,
+) -> kb_core::Result<kb_onchain_transport::HttpClient> {
+    let pool_result = kb_onchain_transport::HttpEndpointPool::from_profile(profile);
+    let pool = match pool_result {
+        Ok(pool) => pool,
+        Err(error) => return Err(error),
+    };
+
+    pool.select_client_for_role_and_method("http_queries", "getBalance")
+}
+```
+
+`HttpEndpointPool::snapshot` fournit un état sérialisable des endpoints actifs et de leurs rôles.
+
+## Classer une méthode RPC
+
+```rust
+fn classify_method(method: &str) -> String {
+    kb_onchain_transport::request_kind_from_method(method)
+}
+
+assert_eq!(classify_method("getTransaction"), "transaction_read");
+```
+
+La valeur retournée sert au routage par rôle. Elle ne remplace pas le nom RPC exact utilisé sur le wire.
+
+## Parser une réponse JSON-RPC
+
+```rust
+fn parse_response(
+    text: &str,
+) -> kb_core::Result<kb_onchain_transport::JsonRpcResponse> {
+    let result = kb_onchain_transport::parse_json_rpc_text(text);
+
+    match result {
+        Ok(response) => Ok(response),
+        Err(error) => Err(error),
+    }
+}
+```
+
+Le parseur distingue les réponses de succès, les erreurs JSON-RPC et les notifications.
+
+## Charger un solde
+
+```rust
+async fn load_balance(
+    client: &kb_onchain_transport::HttpClient,
+    address: &str,
+) -> kb_core::Result<u64> {
+    let result = client
+        .get_balance(
+            address,
+            kb_onchain_transport::GetBalanceConfig::default(),
+        )
+        .await;
+
+    match result {
+        Ok(balance) => Ok(balance.value),
+        Err(error) => Err(error),
+    }
+}
+```
+
+## Adapter une transaction canonique
+
+`GetTransactionAdapter` et `CanonicalTransactionAdapter` convertissent une réponse RPC standard en acquisition canonique sans imposer au pipeline le format brut du fournisseur.
+
+```rust
+fn adapt_transaction(
+    raw: serde_json::Value,
+    config: &kb_onchain_transport::GetTransactionConfig,
+) -> kb_core::Result<kb_onchain_transport::GetTransactionAcquisition> {
+    let result = kb_onchain_transport::adapt_get_transaction_result(raw, config);
+
+    match result {
+        Ok(acquisition) => Ok(acquisition),
+        Err(error) => Err(error),
+    }
+}
+```
+
+## Exécution RPC
+
+Les types suivants couvrent les opérations d’exécution :
+
+- `SimulateTransactionConfig` et `SimulateTransactionResult` ;
+- `SendTransactionConfig` et `SendTransactionResult` ;
+- `ConfirmTransactionConfig` ;
+- `GetLatestBlockhashConfig` ;
+- `GetSignatureStatusesConfig`.
+
+La soumission ne remplace pas les contrôles de sécurité, préflights et confirmations opérateur réalisés par les couches supérieures.
+
+## Erreurs et invariants
+
+- les réponses sont validées et adaptées avant exposition aux couches supérieures ;
+- les tailles, encodages et listes sont bornés par les contrats de la crate ;
+- une erreur RPC distante reste distincte d’une erreur de transport ou d’adaptation ;
+- les endpoints ne doivent pas être supposés interchangeables lorsqu’ils ont des rôles différents.
+
+## Tests de référence
+
+- tests d’équivalence des fixtures `getTransaction` ;
+- tests legacy, v0, ALT, CPI et Token-2022 dans `tests/fixtures/` ;
+- tests de `standard_methods.rs` vérifiant la matrice contractuelle RPC ;
+- tests des pools HTTP/WebSocket et du routage par rôle.
+
+## Limites durables
+
+- la crate traite les transports on-chain ; elle ne gère pas les métadonnées HTTP, IPFS ou Arweave ;
+- elle ne décode pas les instructions de programmes ;
+- elle ne décide pas seule de l’autorisation d’envoyer une transaction.