# Plan `0.2.4` — HTTP Blocks + Economics + compliance HTTP finale ## Statut Ce plan ouvre `0.2.4` par `0.2.4-pre.001` sur la base stable attendue `v0.2.3`. `0.2.1` a stabilisé la foundation HTTP et 4 wrappers typed, `0.2.2` les 22 wrappers Accounts/Tokens/Cluster et `0.2.3` les 11 wrappers Transactions. La surface acquise au démarrage est donc : ```text 52 méthodes HTTP courantes enregistrées 14 méthodes historiques Deprecated / runtime Removed 37 wrappers typed courants 15 wrappers typed restant sous HttpRpcCoverageRelease::V0_2_4 ``` La mission de `0.2.4` est strictement de compléter les **10 Blocks + 5 Economics** déjà affectées à `V0_2_4`, puis de fermer la compliance HTTP globale **52/52 current + 14/14 historical** sous la règle `KSP-TRANSPORT-007`. ## Gate de sizing `pre.001` Question obligatoire : ```text Les 15 wrappers Blocks/Economics, leurs DTOs/wires, les overloads/legacy, les tests, la compliance 52+14 et la documentation peuvent-ils être clôturés proprement dans cette release/session ? ``` Réponse : ```text OUI. ``` Aucun split de release n'est nécessaire avant implémentation. Le volume est supérieur à `0.2.3` en nombre de wrappers mais reste inférieur à `0.2.2`. La complexité est surtout concentrée dans `getBlock`, `getBlockProduction`, `getInflationReward` et la compliance finale ; ces fils sont donc isolés dans des prereleases dédiées. Si une tranche réelle dépasse le budget KSP d'environ 15–20 minutes, une prerelease supplémentaire sera créée **dans `0.2.4`** sans déplacer silencieusement une méthode vers `0.2.5`. ## Sources normatives réauditées le 2026-08-18 Documentation publique : ```text https://solana.com/docs/rpc/http https://solana.com/docs/rpc/json-structures ``` Pages Blocks : ```text https://solana.com/docs/rpc/http/getblock https://solana.com/docs/rpc/http/getblockcommitment https://solana.com/docs/rpc/http/getblockheight https://solana.com/docs/rpc/http/getblockproduction https://solana.com/docs/rpc/http/getblocks https://solana.com/docs/rpc/http/getblockswithlimit https://solana.com/docs/rpc/http/getblocktime https://solana.com/docs/rpc/http/getfirstavailableblock https://solana.com/docs/rpc/http/getrecentperformancesamples https://solana.com/docs/rpc/http/minimumledgerslot ``` Pages Economics : ```text https://solana.com/docs/rpc/http/getinflationgovernor https://solana.com/docs/rpc/http/getinflationrate https://solana.com/docs/rpc/http/getinflationreward https://solana.com/docs/rpc/http/getstakeminimumdelegation https://solana.com/docs/rpc/http/getsupply ``` La documentation Solana actuelle relie encore plusieurs définitions/source examples à **Agave `v3.1.8`**. Ce pointeur documentaire n'est donc pas utilisé comme preuve que `v3.1.8` représente le runtime stable actuel. Le cross-audit runtime a été effectué contre **Agave `v4.2.1`**, release patch publiée le 2026-08-13 dans la branche stable `4.2.x`. `v4.2.0` est explicitement publiée comme stable pour Mainnet Beta, Devnet et Testnet ; `v4.3.0-beta.0`, plus récente en date, reste une prerelease et n'est pas la baseline normative de cette release KSP. Sources primaires Agave ciblées : ```text https://github.com/anza-xyz/agave/releases/tag/v4.2.1 https://github.com/anza-xyz/agave/blob/v4.2.1/rpc/src/rpc.rs https://github.com/anza-xyz/agave/blob/v4.2.1/rpc-client-types/src/config.rs https://github.com/anza-xyz/agave/blob/v4.2.1/rpc-client-types/src/response.rs ``` ## Inventaire officiel réaudité L'index HTTP Solana actuel contient toujours exactement les catégories suivantes : ```text Accounts 6 Tokens 5 Transactions 11 Blocks 10 Cluster 15 Economics 5 -- Current 52 ``` La navigation Deprecated conserve les 14 noms historiques déjà enregistrés par KSP : ```text confirmTransaction getConfirmedBlock getConfirmedBlocks getConfirmedBlocksWithLimit getConfirmedSignaturesForAddress2 getConfirmedTransaction getFeeCalculatorForBlockhash getFeeRateGovernor getFees getRecentBlockhash getSignatureConfirmation getSignatureStatus getSnapshotSlot getStakeActivation ``` La partition KSP reste donc inchangée : ```text 0.2.1 = 4 0.2.2 = 22 0.2.3 = 11 0.2.4 = 15 -- current = 52 historical = 14 ``` Les 15 descriptors `V0_2_4` sont déjà classés `Read / RetrySafe`. `getBlock` reste le seul de ces descriptors marqué `StableWithDeprecatedLegacy` à cause de son second paramètre bare encoding encore accepté pour compatibilité. ## Règle de complétude `KSP-TRANSPORT-007` Un wrapper de cette release n'est complet que s'il expose sans perte toutes les possibilités RPC retenues par l'audit : paramètres ordonnés, objets de config, overloads, formes legacy encore supportées, contraintes déterministes utiles, variantes de réponse et distinctions `omitted`/`null` nécessaires. Pour `0.2.4`, cela impose notamment : - de ne pas réduire `getBlocks` à la seule forme `[start, end, config]` ; - de conserver le bare encoding legacy de `getBlock` sans le présenter comme forme recommandée ; - de préserver `transactionDetails = full | signatures | none | accounts` et les conséquences sur la présence des champs de bloc ; - de préserver les champs wire riches des transactions/meta/rewards sans importer un client RPC Solana haut niveau ; - de conserver les `null` positionnels de `getInflationReward` et le champ runtime `commissionBps` lorsqu'il est présent ; - de ne pas inventer de limite d'adresses `getInflationReward` si aucune limite sémantique fixe n'est établie par la documentation/runtime courant ; la limite générale de taille de requête HTTP n'est pas transformée artificiellement en cardinalité métier KSP. ## Matrice Blocks — 10 wrappers | Méthode | Requête à couvrir | Résultat à préserver | Contraintes / décisions `KSP-TRANSPORT-007` | |-------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `getBlock` | `slot`; second paramètre absent, bare encoding legacy, ou config `{commitment, encoding, transactionDetails, maxSupportedTransactionVersion, rewards}` | `object ou null`; `previousBlockhash`, `blockhash`, `parentSlot`, transactions/signatures/rewards selon config, `numRewardPartitions`, `blockTime`, `blockHeight` | commitment runtime au moins `confirmed`; réutiliser les encodings/version/transaction wire de `0.2.3`; préserver omission vs null ; garder les erreurs runtime de bloc/version comme erreurs RPC, sans les masquer | | `getBlockCommitment` | `slot` uniquement | `{commitment: array ou null, totalStake: u64}` | aucune config à inventer ; préserver commitment nullable | | `getBlockHeight` | config contextuelle optionnelle `{commitment, minContextSlot}` | `u64` | réutiliser `SolanaContextConfig`; `minContextSlot` est transmis tel quel au runtime | | `getBlockProduction` | config optionnelle `{commitment, identity, range:{firstSlot,lastSlot?}}` | `SolanaRpcResponse<{byIdentity, range}>` | `identity` typée Pubkey ; validation locale déterministe `lastSlot >= firstSlot` lorsque les deux sont fournis ; préserver les couples `[leaderSlots, blocksProduced]` | | `getBlocks` | `[start]`, `[start,end]`, `[start,config]`, `[start,end,config]` | `Vec` | commitment au moins `confirmed`; conserver l'overload untagged du second paramètre ; `end < start` donne `[]`; rejeter localement une différence `end-start > 500_000` | | `getBlocksWithLimit` | `start`, `limit`, config contextuelle optionnelle | `Vec` | commitment au moins `confirmed`; `limit <= 500_000`; `limit = 0` est valide et donne `[]` | | `getBlockTime` | `slot` uniquement | `i64 ou null` | préserver l'absence de timestamp ; les cas cleaned/skipped/not available restent des erreurs RPC runtime, pas des valeurs synthétiques | | `getFirstAvailableBlock` | aucun paramètre | `u64` | requête exacte `params: []` ; aucune config | | `getRecentPerformanceSamples` | `limit?` | tableau de `{slot,numTransactions,numSlots,samplePeriodSecs,numNonVoteTransactions?}` | défaut runtime `720`; maximum `720`; rejeter avant I/O `limit > 720`; préserver `numNonVoteTransactions` nullable/ancien runtime | | `minimumLedgerSlot` | aucun paramètre | `u64` | requête exacte `params: []`; conserver les erreurs ledger/runtime | ### `getBlock` — stratégie wire `getBlock` est le plus gros fil de la release et reçoit une prerelease dédiée. Les primitives déjà acquises de `rpc_transactions` doivent être réutilisées lorsque le wire est réellement commun : ```text SolanaTransactionEncoding SolanaEncodedTransaction SolanaTransactionVersion SolanaWireField ``` `SolanaConfirmedTransaction` ne doit **pas** être réutilisé tel quel pour un élément de bloc : ce DTO contient `slot` et `blockTime`, qui appartiennent au résultat top-level de `getTransaction` et non à chaque élément `transactions[]` d'un bloc. Un type wire de transaction de bloc dédié peut en revanche composer les primitives ci-dessus et préserver `transaction`, `meta` et `version` sans décodage Program. Les champs top-level dont la présence dépend de la config (`transactions`, `signatures`, `rewards`, `numRewardPartitions`) doivent utiliser une représentation capable de distinguer une omission d'un `null` lorsqu'une telle distinction existe sur le wire. Les transactions `accounts` ne doivent pas être forcées dans une structure `full` plus riche que le wire réellement retourné. ## Matrice Economics — 5 wrappers | Méthode | Requête à couvrir | Résultat à préserver | Contraintes / décisions `KSP-TRANSPORT-007` | |---|---|---|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `getInflationGovernor` | config commitment optionnelle | `{initial,terminal,taper,foundation,foundationTerm}` en `f64` | réutiliser `SolanaCommitmentConfig`; aucun contexte de réponse | | `getInflationRate` | aucun paramètre | `{total,validator,foundation,epoch}` | requête exacte `params: []` | | `getInflationReward` | liste ordonnée d'adresses ; config optionnelle `{epoch,commitment,minContextSlot}` | `Vec>` positionnel | ordre/cardinalité identiques aux entrées ; préserver `commission: u8 ou null` **et** `commissionBps: u16` optionnel de Agave `v4.2.1`; aucune limite fixe d'adresses inventée | | `getStakeMinimumDelegation` | config contextuelle optionnelle `{commitment,minContextSlot}` | `SolanaRpcResponse` | réutiliser `SolanaContextConfig` / `SolanaRpcResponse` | | `getSupply` | config optionnelle `{commitment,excludeNonCirculatingAccountsList}` | `SolanaRpcResponse<{total,circulating,nonCirculating,nonCirculatingAccounts}>` | le booléen runtime par défaut est `false`; préserver la liste ordonnée retournée lorsqu'elle est demandée | ### Extension runtime `commissionBps` La documentation publique actuelle de `getInflationReward` énumère encore uniquement `commission`. Agave `v4.2.1` définit cependant aussi : ```text commission_bps: Option ``` sérialisé en `commissionBps` lorsqu'il est présent. Ce champ correspond à l'évolution SIMD-0291 et doit être conservé dans le DTO KSP pour ne pas perdre une capacité/extension du runtime stable courant. ## Contraintes locales retenues Les validations déterministes suivantes doivent être réalisées avant I/O : ```text getBlock commitment >= confirmed getBlocks commitment >= confirmed getBlocks end-start <= 500_000 lorsqu'end >= start getBlocksWithLimit commitment >= confirmed getBlocksWithLimit limit <= 500_000 getRecentPerformanceSamples limit <= 720 getBlockProduction lastSlot >= firstSlot lorsqu'ils sont tous deux présents ``` `getBlocks(end < start)` et `getBlocksWithLimit(limit = 0)` sont des cas valides qui doivent produire un tableau vide plutôt qu'une erreur locale. Ne pas reproduire localement les validations qui nécessiteraient un décodage disproportionné ou l'état du ledger : disponibilité réelle d'un bloc, slot cleaned/skipped, support effectif d'une version de transaction par le caller, présence historique des metadata, epoch disponible, minContextSlot atteint, etc. Ces cas restent des erreurs/réponses RPC validées par le flux central. ## Réutilisation des contrats existants ### À réutiliser directement ```text SolanaCommitment SolanaCommitmentConfig SolanaContextConfig SolanaRpcContext SolanaRpcResponse SolanaTransactionEncoding SolanaEncodedTransaction SolanaTransactionVersion SolanaWireField ``` ### À introduire dans `0.2.4` Noms définitifs ajustables pendant l'implémentation, responsabilités fixes : ```text config getBlock moderne + enum transactionDetails config/range/result getBlockProduction block commitment result confirmed block + transaction-in-block + reward wire performance sample inflation governor/rate/reward supply result/config ``` La déduplication ne doit pas fusionner des contrats ayant des sémantiques différentes uniquement parce que leurs champs se ressemblent. ## Architecture d'exécution Les 15 wrappers restent `Read / RetrySafe` et passent exclusivement par : ```text wrapper typed -> descriptor central -> execute_standard_rpc -> pool/admission -> executor HTTP -> validation JSON-RPC -> decode typed ``` Interdits : ```text client HTTP parallèle reqwest direct dans un wrapper retry/deadline/admission bypass Transport -> Config Transport -> Store/Program tracing direct solana-rpc-client / solana-client pour masquer les possibilités RPC ``` ## Dépendances Aucune nouvelle dépendance n'est nécessaire au vu de l'audit `pre.001`. En particulier : ```text solana-rpc-client NON solana-client NON crate SDK Block NON base64/bs58 NON pour cette release ``` Les primitives `serde`/`serde_json`, `ksp-core-lib::Pubkey` et les wires Transaction déjà présents suffisent à exprimer les contrats sans introduire un SDK RPC haut niveau. ## Tests déterministes attendus Chaque wrapper doit couvrir : - request JSON exacte ; - absence de config et objet vide lorsque ces deux formes sont significatives ; - tous les overloads/configs/encodings pertinents ; - réponse typed nominale ; - `null` et omission lorsque le wire les distingue ; - ordre et cardinalité ; - erreur JSON-RPC propagée ; - validation déterministe avant I/O lorsqu'elle est retenue par ce plan. Cas de régression obligatoires spécifiques : ```text getBlock bare encoding legacy getBlock transactionDetails full/signatures/none/accounts getBlock result null getBlocks [start,config] vs [start,end,config] getBlocks range > 500_000 rejetée avant I/O getBlocksWithLimit 0 et > 500_000 getRecentPerformanceSamples défaut/720/>720 getBlockProduction lastSlot < firstSlot rejeté avant I/O getInflationReward ordre + null positionnels + commissionBps getSupply excludeNonCirculatingAccountsList true/false/omitted ``` ## Compliance finale HTTP La dernière prerelease doit ajouter une preuve explicite que les **52 méthodes courantes enregistrées** possèdent désormais toutes un wrapper typed public réel. Un appel raw/générique ne compte pas. Canaries finales : ```text current registry == 52 historical registry == 14 V0_2_1 exact == 4 V0_2_2 exact == 22 V0_2_3 exact == 11 V0_2_4 exact == 15 typed wrappers current == 52/52 historical Deprecated/Removed == 14/14 KSP-TRANSPORT-007 audited current == 52/52 ``` La compliance `KSP-TRANSPORT-007` des 37 wrappers de `0.2.1`–`0.2.3` reste acquise par `docs/validation/005-V0_2_3_KSP_TRANSPORT_007_RETRO_AUDIT.md`; la clôture `0.2.4` vérifie qu'aucune régression n'a été introduite et applique la même règle aux 15 nouveaux wrappers. ## Smokes live Les smokes restent opt-in et secondaires par rapport aux fixtures locales. Le smoke Transport pur peut être étendu uniquement avec quelques reads robustes, par exemple `getBlockHeight`, `getFirstAvailableBlock`, `minimumLedgerSlot`, `getInflationRate` ou `getStakeMinimumDelegation`. Éviter un `getBlock` dépendant d'un slot fixe ou tout scénario fragile lié à des récompenses d'un epoch précis. Le smoke historique Config -> Transport reste une exception transitoire de composition et ne devient pas la destination générale des futurs scénarios cross-crates. ## Prévision souple des prereleases ```text pre.001 audit officiel actuel + Agave stable + matrice + wires + contraintes + sizing pre.002 primitives/configs/results Blocks/Economics partagés + fixtures communes pre.003 Blocks simples : getBlockCommitment, getBlockHeight, getBlockTime, getFirstAvailableBlock, minimumLedgerSlot pre.004 ranges/performance : getBlocks, getBlocksWithLimit, getRecentPerformanceSamples pre.005 getBlockProduction + range/identity/result contextualisé pre.006 getBlock moderne + bare encoding legacy + transactionDetails + wire bloc riche pre.007 Economics simples : getInflationGovernor, getInflationRate, getStakeMinimumDelegation, getSupply pre.008 getInflationReward + null positionnels + commissionBps + invariants pre.009 compliance finale 52/52 + 14/14 + KSP-TRANSPORT-007 + docs + smokes + graphes + prompt 0.2.5 — Wallet foundation rel.001 publication strictement publicationnelle ``` Cette prévision peut être redécoupée si une tranche dépasse le budget réel. Elle ne doit pas être compressée artificiellement pour conserver un numéro de prerelease prévu. ## Hors périmètre ```text Wallet / .kspwallet WebSocket LaserStream Yellowstone gRPC Store/Program/Materializer modèle métier de transaction/bloc client RPC Solana haut niveau réécriture des deltas historiques ``` ## Critères de clôture `0.2.4` - 15/15 wrappers `V0_2_4` publics, typed et `KSP-TRANSPORT-007` conformes ; - 52/52 méthodes HTTP courantes avec wrapper typed ; - 14/14 historiques conservées en compliance ; - aucun bypass du flux central Transport ; - aucune nouvelle dépendance injustifiée ; - tests déterministes complets ; - smokes live pertinents validés par preuve opérateur ; - graphes Cargo Transport/Config réaudités ; - README/USAGE/matrices/validation synchronisés ; - prompt `0.2.5 — Wallet foundation` finalisé ; - dernière prerelease candidate complète ; - `0.2.4-rel.001` strictement publicationnelle. ## Questions ouvertes Aucune question bloquante pour `pre.002`. Les noms Rust exacts des DTOs peuvent encore être ajustés pendant l'implémentation. En revanche, les formes RPC, overloads, distinctions wire et limites fixées dans ce plan ne doivent pas être réduits pour simplifier l'API KSP.