v0.1.0-pre.070

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.