# `ksp-onchain-transport-lib` `ksp-onchain-transport-lib` est la bibliothèque KSP propriétaire du transport on-chain Solana. Sa première surface est le transport HTTP JSON-RPC ; les extensions WebSocket et gRPC sont introduites séparément lorsque leur release les cible. ## Responsabilités La crate possède : - les settings runtime HTTP publics ; - les endpoints nommés et leurs metadata provider/cluster ; - les rôles, capabilities/request kinds et priorités ; - la sélection/fairness/fallback du pool ; - les limites RPS/burst/concurrence et le cooldown ; - les deadlines et timeouts ; - le retry/backoff borné et la règle no-resend après dispatch ambigu ; - les enveloppes JSON-RPC 2.0 et leur validation ; - le registre audité des méthodes Solana HTTP ; - l'exécution générique des méthodes standard supportées ; - les wrappers typés explicitement livrés par KSP ; - les snapshots runtime sûrs ; - l'observabilité Transport via `ksp-logging-lib`. La crate ne possède ni documents Config, ni persistence Store, ni modèles Program/métier. ## Frontières de dépendances La direction autorisée est : ```text ksp-config-lib -> ksp-onchain-transport-lib -> ksp-core-lib -> ksp-logging-lib -> reqwest / tokio / serde ``` La direction inverse est interdite : ```text ksp-onchain-transport-lib -X-> ksp-config-lib ksp-onchain-transport-lib -X-> Store ksp-onchain-transport-lib -X-> Program ksp-onchain-transport-lib -X-> tracing direct ``` `ksp-config-lib` peut donc charger `std.transport.json` et construire `HttpTransportSettings`, tandis que Transport reste directement utilisable par un consumer qui fournit lui-même ses settings. ## Surface HTTP standard Le registre KSP conserve deux inventaires distincts : ```text 52 méthodes HTTP courantes 14 méthodes historiques Deprecated / runtime Removed ``` Le registre porte notamment : - catégorie ; - request kind ; - statut documentaire ; - statut runtime ; - forme de requête stable/legacy ; - type d'opération ; - classe de retry ; - remplacement historique éventuel ; - release de couverture typée KSP. Les quatre wrappers typés de la foundation sont : ```text getBalance getGenesisHash getHealth getVersion ``` Les autres méthodes courantes peuvent déjà passer par l'exécuteur JSON-RPC standard générique lorsqu'un consumer fournit explicitement descriptor et paramètres JSON. Cette surface raw/générique **ne vaut pas couverture typée** : les wrappers et DTOs typés restants sont introduits selon la matrice HTTP KSP. Les 14 méthodes historiques restent découvrables pour la compliance mais sont `Removed` et ne sont pas simulées comme appelables. ## Résilience L'admission est calculée par couple endpoint/rôle. Le pool applique : 1. rôle et capability ; 2. priorité croissante ; 3. round-robin dans le meilleur tier ; 4. RPS/burst ; 5. concurrence ; 6. cooldown rate-limit ; 7. fallback vers les pairs puis les tiers inférieurs ; 8. deadline commune à l'opération et ses retries. Les retries ne sont autorisés que lorsque la metadata de méthode et l'état de dispatch les rendent sûrs. `WriteSubmission / NeverAfterDispatch` interdit tout resend automatique après un dispatch ambigu. Les erreurs JSON-RPC applicatives ne sont pas transformées en retries transport génériques. ## Sécurité et diagnostics Les URLs d'endpoint peuvent contenir des credentials. Elles ne sont donc pas exposées par les `Debug`, snapshots ou logs ordinaires. Les `reqwest::Error` attachées comme source sont neutralisées avec `without_url()` avant exposition dans le contrat d'erreur KSP. Le target de tracing est possédé explicitement par : ```text src/constants.rs TRACING_TARGET = "ksp-onchain-transport-lib" ``` La configuration Logging de référence conserve un fichier dédié Transport à niveau `info`. Un niveau `debug`/`trace` ciblé peut être réactivé temporairement via Config lors d'un développement ou diagnostic explicite. ## Tests Les tests par défaut sont déterministes et n'exigent pas Internet : fixtures JSON et serveur HTTP local couvrent requêtes, réponses, retry, 429, timeout, redaction et routing. Un smoke Devnet live existe côté `ksp-config-lib` afin de tester la chaîne réelle : ```text Config -> std.transport/devnet_public -> HttpTransportPool -> getHealth/getGenesisHash/getVersion/getBalance ``` Il est `ignored` par défaut et doit être exécuté explicitement. ## Documentation - [`USAGE.md`](USAGE.md) — consommation directe, Config -> Transport, API typed/raw et inspection runtime ; - [`../../docs/plans/008-V0_2_1_ONCHAIN_HTTP_PLAN.md`](../../docs/plans/008-V0_2_1_ONCHAIN_HTTP_PLAN.md) — plan et matrice HTTP ; - [`../../docs/validation/003-V0_2_1_ONCHAIN_HTTP.md`](../../docs/validation/003-V0_2_1_ONCHAIN_HTTP.md) — matrice de clôture ; - [`../../config/std.transport.json`](../../config/std.transport.json) — configuration standard HTTP.