<!-- 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.