khadhroony-solana-project/deltas/0.2.3/pre.003.md

Delta 0.2.3-pre.003 — quatre premiers wrappers HTTP Transactions Read

Base requise

Livraison précédente corrigée et validée localement par l'opérateur :

0.2.3-pre.002-fix.001
workspace.package.version = "0.2.3-pre.2.fix.1"

La validation opérateur du 2026-08-18 a confirmé :

cargo fmt --all                         OK
cargo check --workspace                 OK
cargo clippy --workspace --all-targets  OK
cargo test -p ksp-onchain-transport-lib OK

Résultats Transport de cette base :

145 unit tests
14 public API tests
8 release completeness tests
0 warning signalé par check/clippy

Le plan canonique reste docs/plans/010-V0_2_3_HTTP_TRANSACTIONS_PLAN.md version 3.

Objectif

Implémenter les quatre premiers wrappers Transaction Read / RetrySafe prévus par le plan :

getFeeForMessage
getLatestBlockhash
getTransactionCount
isBlockhashValid

Tous passent par le chemin HTTP commun :

wrapper typé
  -> descriptor Transaction audité
  -> execute_standard_rpc
  -> pool/admission/retry/deadline
  -> executor HTTP
  -> validation JSON-RPC
  -> décodage DTO KSP

Aucun wrapper n'appelle reqwest directement et aucune boucle de retry locale n'est ajoutée.

Version Cargo

Conformément à VER-ID-009 :

0.2.3-pre.2.fix.1 -> 0.2.3-pre.3

Aucune dépendance ni feature Cargo n'est ajoutée.

Surface typée ajoutée

getFeeForMessage

Signature publique conceptuelle :

role + message base64 opaque + Option<SolanaContextConfig>
  -> SolanaRpcResponse<Option<u64>>

Le wrapper :

• conserve le message sérialisé comme chaîne opaque et ne tente ni base64 decode ni désérialisation locale ;
• sérialise commitment et minContextSlot lorsqu'ils sont présents ;
• omet la config lorsqu'elle est absente ou vide ;
• préserve value: null sous Option::None ;
• laisse une erreur de décodage/paramètre distante dans le domaine RPC_APPLICATION_ERROR.

getLatestBlockhash

Signature publique conceptuelle :

role + Option<SolanaContextConfig>
  -> SolanaRpcResponse<SolanaLatestBlockhash>

Le wrapper active en production le décodeur SolanaLatestBlockhash préparé en pre.002 et conserve :

blockhash
lastValidBlockHeight
context.slot
context.apiVersion?

Un blockhash de réponse vide est rejeté comme ERROR_CODE_INVALID_RESPONSE. KSP ne décode pas cryptographiquement la chaîne.

getTransactionCount

Signature publique conceptuelle :

role + Option<SolanaContextConfig>
  -> u64

La méthode conserve la forme simple du résultat tout en sérialisant la config contextuelle optionnelle dans le tableau params exact.

isBlockhashValid

Signature publique conceptuelle :

role + blockhash opaque + Option<SolanaContextConfig>
  -> SolanaRpcResponse<bool>

Le blockhash d'entrée est transmis tel quel au runtime : pre.003 n'ajoute ni solana-hash, ni validation base58, ni normalisation silencieuse.

Infrastructure Transaction activée

rpc_transactions.rs ajoute un helper interne unique pour les wrappers de cette famille :

execute_transaction_rpc
  -> transaction_descriptor
  -> execute_standard_rpc

transaction_descriptor refuse de fonctionner si la méthode demandée n'est pas classée :

HttpRpcCategory::Transactions
HttpRpcCoverageRelease::V0_2_3

Les trois réponses contextuelles de cette tranche réutilisent un décodeur interne commun qui préserve SolanaRpcContext avant de décoder la valeur métier.

Seuls les helpers réellement utilisés deviennent production-live dans cette tranche :

SolanaLatestBlockhash::decode_wire
WireLatestBlockhash
invalid_transaction_wire

Les décodeurs/configs préparatoires des sept wrappers suivants restent sous #[cfg(test)] jusqu'à leur tranche propriétaire afin de conserver une build non-test sans dead_code artificiel.

Fixtures HTTP déterministes ajoutées

crates/ksp-onchain-transport-lib/fixtures/http/get_fee_for_message.success.json
crates/ksp-onchain-transport-lib/fixtures/http/get_fee_for_message.null.json
crates/ksp-onchain-transport-lib/fixtures/http/get_fee_for_message.error.json
crates/ksp-onchain-transport-lib/fixtures/http/get_latest_blockhash.success.json
crates/ksp-onchain-transport-lib/fixtures/http/get_latest_blockhash.invalid_empty.json
crates/ksp-onchain-transport-lib/fixtures/http/get_transaction_count.success.json
crates/ksp-onchain-transport-lib/fixtures/http/is_blockhash_valid.success.json

Les tests utilisent un serveur HTTP loopback local et n'accèdent pas à Internet.

Couverture de tests ajoutée

Sept tests HTTP unitaires couvrent :

• getFeeForMessage avec paramètres exacts et config contextuelle complète ;
• getFeeForMessage avec value: null et config absente ;
• propagation d'une erreur JSON-RPC applicative pour un message refusé par le runtime ;
• getLatestBlockhash avec config explicitement vide, donc omise ;
• rejet d'un blockhash vide renvoyé par le provider ;
• getTransactionCount avec commitment ;
• isBlockhashValid avec blockhash opaque, commitment et minContextSlot.

Le test public compile explicitement les quatre nouvelles méthodes sur HttpTransportPool.

Une canarie release fige le sous-ensemble pre.003 :

getFeeForMessage
getLatestBlockhash
getTransactionCount
isBlockhashValid

et vérifie pour chacune :

Transactions / V0_2_3 / Read / RetrySafe

La couverture typed complète 0.2.3 exact == 11 reste volontairement fermée : les sept wrappers restants appartiennent aux tranches pre.004 à pre.007.

Après application, la cible Transport attendue devient :

152 unit tests
15 public API tests
9 release completeness tests

Fichiers ajoutés

crates/ksp-onchain-transport-lib/fixtures/http/get_fee_for_message.success.json
crates/ksp-onchain-transport-lib/fixtures/http/get_fee_for_message.null.json
crates/ksp-onchain-transport-lib/fixtures/http/get_fee_for_message.error.json
crates/ksp-onchain-transport-lib/fixtures/http/get_latest_blockhash.success.json
crates/ksp-onchain-transport-lib/fixtures/http/get_latest_blockhash.invalid_empty.json
crates/ksp-onchain-transport-lib/fixtures/http/get_transaction_count.success.json
crates/ksp-onchain-transport-lib/fixtures/http/is_blockhash_valid.success.json
deltas/0.2.3/pre.003.md

Fichiers modifiés

Cargo.toml
crates/ksp-onchain-transport-lib/src/lib.rs
crates/ksp-onchain-transport-lib/src/rpc_transactions.rs
crates/ksp-onchain-transport-lib/unit_tests/rpc_transactions.rs
crates/ksp-onchain-transport-lib/tests/public_api.rs
crates/ksp-onchain-transport-lib/tests/release_completeness.rs

Fichiers supprimés

Aucun.

Fichiers volontairement inchangés

CHANGELOG.md
ROADMAP.md
docs/plans/010-V0_2_3_HTTP_TRANSACTIONS_PLAN.md
crates/ksp-onchain-transport-lib/Cargo.toml
crates/ksp-onchain-transport-lib/README.md
crates/ksp-onchain-transport-lib/USAGE.md
crates/ksp-onchain-transport-lib/src/executor.rs
crates/ksp-onchain-transport-lib/src/rpc_method.rs
crates/ksp-config-lib/**
config/**

Aucune méthode 0.2.4 n'est avancée.

Validations exécutées

• prise en compte de la validation opérateur propre de pre.002-fix.001 comme base ;
• contrôle JSON syntaxique des sept nouvelles fixtures ;
• contrôle différentiel exact contre la base validée ;
• contrôle statique que les quatre wrappers passent par execute_transaction_rpc -> execute_standard_rpc ;
• contrôle statique de l'absence de reqwest, tracing, client RPC parallèle ou boucle de retry dans rpc_transactions.rs ;
• contrôle statique de l'absence de nouvelle dépendance/feature Cargo ;
• contrôle statique des helpers préparatoires restés sous #[cfg(test)] ;
• contrôle statique de l'absence de unwrap, expect, panic! et ? dans la source de production modifiée ;
• contrôle statique des lignes Rust modifiées à <= 160 colonnes ;
• contrôle que CHANGELOG.md, ROADMAP.md, le plan 010, executor.rs et rpc_method.rs restent inchangés.

Validations non exécutées

Le sandbox d'échange ne fournit pas cargo, rustc ou rustfmt. Les commandes suivantes doivent être exécutées sur le checkout opérateur avant commit :

cargo fmt --all
cargo check --workspace
cargo clippy --workspace --all-targets
cargo test -p ksp-onchain-transport-lib

cargo test --workspace reste réservé au checkpoint de clôture/session. Aucun cargo tree n'est requis par cette tranche puisqu'aucune dépendance ni feature n'a changé.

Le commit attendu après application et validations suit VER-GIT-001 :

v0.2.3-pre.003

Décisions prises

• réutiliser SolanaContextConfig et SolanaRpcResponse<T> sans créer de DTO de config redondant ;
• ne pas décoder localement les messages ou blockhashs d'entrée ;
• omettre une config contextuelle explicitement vide ;
• activer en production uniquement les helpers wire réellement consommés par cette tranche ;
• centraliser la sélection des descriptors Transaction sans contourner execute_standard_rpc ;
• conserver les erreurs JSON-RPC applicatives comme non-retryables au niveau applicatif.

Questions ouvertes

Aucune question bloquante pour pre.004.

Suite

0.2.3-pre.004 : implémenter getRecentPrioritizationFees, getSignaturesForAddress et getSignatureStatuses, avec limites locales exactes 128 / 1000 / 256, ordre serveur, pagination et null positionnels.