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

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

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

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

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

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.

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.

4.3 KiB Raw Blame History Unescape Escape