148 lines
4.3 KiB
Markdown
148 lines
4.3 KiB
Markdown
<!-- 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.
|