khadhroony-solana-project/crates/ksp-onchain-transport-lib/README.md

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 :

ksp-config-lib
    -> ksp-onchain-transport-lib
        -> ksp-core-lib
        -> ksp-logging-lib
        -> reqwest / tokio / serde

La direction inverse est interdite :

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 :

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.

La candidate 0.2.3-pre.009 porte la surface typée à 37 méthodes courantes :

0.2.1 foundation   : 4
0.2.2 Accounts     : 5
0.2.2 Tokens       : 5
0.2.2 Cluster      : 12
0.2.3 Transactions : 11

Les quatre canaris foundation restent getBalance, getGenesisHash, getHealth et getVersion. 0.2.2 ajoute les 22 wrappers Accounts/Tokens/Cluster. 0.2.3 ajoute les 11 wrappers Transactions, dont requestAirdrop et sendTransaction en WriteSubmission / NeverAfterDispatch et simulateTransaction en Simulation / RetrySafe.

Les 15 méthodes Blocks/Economics encore affectées à 0.2.4 peuvent déjà passer par l'exécuteur JSON-RPC standard générique lorsqu'un consumer fournit explicitement descriptor et paramètres JSON, mais cette surface raw/générique ne vaut pas couverture typée.

KSP-TRANSPORT-007 impose qu'un wrapper typé couvre toutes les possibilités RPC supportées retenues par l'audit : paramètres/options, overloads et formes legacy encore supportées, contraintes déterministes utiles et variantes de réponse pertinentes sans perte. Le réaudit 0.2.3-pre.008 confirme cette complétude sur les 37 wrappers courants.

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 :

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.

Deux smokes Devnet opt-in sont séparés par responsabilité :

Transport pur : settings programmatiques -> HttpTransportPool
             -> Accounts/Tokens/Cluster représentatifs
             -> getLatestBlockhash/isBlockhashValid/getTransactionCount

Composition historique : Config -> std.transport/devnet_public -> HttpTransportPool
                       -> getHealth/getGenesisHash/getVersion/getBalance

Le smoke Transport utilise pour sa branche Token la forme Devnet documentée getTokenAccountsByOwner(owner, { programId }, { commitment: finalized, encoding: jsonParsed }). L'owner est une Pubkey ordinaire de l'exemple officiel ; aucune présence de token account n'est exigée, donc une liste vide reste valide.

Les deux sont ignored par défaut. Le smoke Transport appartient durablement à cette crate ; le smoke cross-crates hébergé dans Config reste transitoire jusqu'à l'existence d'une surface KSP d'intégration/orchestration appropriée.

Documentation

• USAGE.md — consommation directe, Config -> Transport, API typed/raw, smokes et inspection runtime ;
• ../../docs/plans/008-V0_2_1_ONCHAIN_HTTP_PLAN.md — foundation HTTP stable ;
• ../../docs/plans/009-V0_2_2_HTTP_ACCOUNTS_TOKENS_CLUSTER_PLAN.md — extension typed Accounts/Tokens/Cluster ;
• ../../docs/validation/004-V0_2_2_HTTP_ACCOUNTS_TOKENS_CLUSTER.md — matrice finale validée 0.2.2 ;
• ../../docs/plans/010-V0_2_3_HTTP_TRANSACTIONS_PLAN.md — plan de la candidate 0.2.3 ;
• ../../docs/validation/006-V0_2_3_HTTP_TRANSACTIONS.md — matrice de clôture candidate 0.2.3 ;
• ../../config/std.transport.json — configuration standard HTTP.