Sasedev/khadhroony-solana-project
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

v0.2.4-pre.001

Browse Source
This commit is contained in:
SinuS von SifriduS
2026-08-18 19:36:57 +02:00
parent f7acac3fc8
commit c03a3eaf5d
7 changed files with 621 additions and 9 deletions
Download Patch File Download Diff File Expand all files Collapse all files

7
docs/000-README.md
View File

@@ -1,5 +1,5 @@
<!-- file: docs/000-README.md -->
<!-- version: 30 -->
<!-- version: 31 -->
# Documentation KSP
@@ -42,7 +42,8 @@ docs/
│ ├── 007-V0_2_0_SERIES_PLANNING.md
│ ├── 008-V0_2_1_ONCHAIN_HTTP_PLAN.md
│ ├── 009-V0_2_2_HTTP_ACCOUNTS_TOKENS_CLUSTER_PLAN.md
│ └── 010-V0_2_3_HTTP_TRANSACTIONS_PLAN.md
│ ├── 010-V0_2_3_HTTP_TRANSACTIONS_PLAN.md
│ └── 011-V0_2_4_HTTP_BLOCKS_ECONOMICS_PLAN.md
├── validation/
│ ├── 000-README.md
│ ├── 001-V0_1_4_CONFIG_DESKTOP.md
@@ -67,7 +68,7 @@ D'autres sous-répertoires seront ajoutés uniquement lorsque leur rôle aura é
## Documents de planification
Le plan historique de la phase fondatrice clôturée est conservé dans [`plans/001-V0_0_3_PLAN.md`](plans/001-V0_0_3_PLAN.md). La séquence active des premières releases fonctionnelles est définie dans [`plans/002-FUNCTIONAL_RELEASE_SEQUENCE.md`](plans/002-FUNCTIONAL_RELEASE_SEQUENCE.md). Le plan détaillé de la release stable `0.1.1` est conservé comme historique clôturé dans [`plans/003-V0_1_1_CORE_FOUNDATION_PLAN.md`](plans/003-V0_1_1_CORE_FOUNDATION_PLAN.md). Le plan détaillé de la release stable `0.1.2` est conservé comme historique clôturé dans [`plans/004-V0_1_2_LOGGING_FOUNDATION_PLAN.md`](plans/004-V0_1_2_LOGGING_FOUNDATION_PLAN.md). Le plan détaillé de la release stable `0.1.3 — Configuration foundation` est conservé comme historique clôturé dans [`plans/005-V0_1_3_CONFIG_FOUNDATION_PLAN.md`](plans/005-V0_1_3_CONFIG_FOUNDATION_PLAN.md). Le plan détaillé de la release stable `0.1.4 — ksp-app-config-desk` est conservé comme historique clôturé dans [`plans/006-V0_1_4_CONFIG_DESKTOP_PLAN.md`](plans/006-V0_1_4_CONFIG_DESKTOP_PLAN.md), avec sa matrice finale [`validation/001-V0_1_4_CONFIG_DESKTOP.md`](validation/001-V0_1_4_CONFIG_DESKTOP.md). Son prompt d'ouverture historique reste [`../prompts/004-V0_1_4_START_PROMPT.md`](../prompts/004-V0_1_4_START_PROMPT.md). La release stable `0.2.0` clôt l'audit de bot3 et le découpage de la série. Son plan directeur est conservé comme historique clôturé dans [`plans/007-V0_2_0_SERIES_PLANNING.md`](plans/007-V0_2_0_SERIES_PLANNING.md), avec sa matrice finale [`validation/002-V0_2_0_SERIES_PLANNING.md`](validation/002-V0_2_0_SERIES_PLANNING.md). La release stable `0.2.1 — HTTP Solana foundation` a été ouverte par [`../prompts/006-V0_2_1_START_PROMPT.md`](../prompts/006-V0_2_1_START_PROMPT.md). Son gate de sizing et sa matrice exhaustive sont conservés dans [`plans/008-V0_2_1_ONCHAIN_HTTP_PLAN.md`](plans/008-V0_2_1_ONCHAIN_HTTP_PLAN.md), avec la validation finale [`validation/003-V0_2_1_ONCHAIN_HTTP.md`](validation/003-V0_2_1_ONCHAIN_HTTP.md), README/USAGE Transport et le smoke Devnet opt-in de composition Config -> Transport. Le prompt [`../prompts/007-V0_2_2_START_PROMPT.md`](../prompts/007-V0_2_2_START_PROMPT.md) a ouvert la release stable `0.2.2 — HTTP Accounts + Tokens + Cluster`. Son plan clôturé [`plans/009-V0_2_2_HTTP_ACCOUNTS_TOKENS_CLUSTER_PLAN.md`](plans/009-V0_2_2_HTTP_ACCOUNTS_TOKENS_CLUSTER_PLAN.md) conserve l'audit et l'implémentation des 22 wrappers typés, tandis que [`validation/004-V0_2_2_HTTP_ACCOUNTS_TOKENS_CLUSTER.md`](validation/004-V0_2_2_HTTP_ACCOUNTS_TOKENS_CLUSTER.md) enregistre les validations déterministes, les graphes Cargo et les deux smokes Devnet passés avant publication. Le prompt [`../prompts/008-V0_2_3_START_PROMPT.md`](../prompts/008-V0_2_3_START_PROMPT.md) a ouvert la release stable `0.2.3 — HTTP Transactions`. Son plan clôturé [`plans/010-V0_2_3_HTTP_TRANSACTIONS_PLAN.md`](plans/010-V0_2_3_HTTP_TRANSACTIONS_PLAN.md) conserve l'audit et l'implémentation des 11 wrappers ; le réaudit [`validation/005-V0_2_3_KSP_TRANSPORT_007_RETRO_AUDIT.md`](validation/005-V0_2_3_KSP_TRANSPORT_007_RETRO_AUDIT.md) confirme la complétude des 37 wrappers HTTP typés et [`validation/006-V0_2_3_HTTP_TRANSACTIONS.md`](validation/006-V0_2_3_HTTP_TRANSACTIONS.md) enregistre les validations finales, graphes Cargo et deux smokes Devnet passés avant publication. Le prompt [`../prompts/009-V0_2_4_START_PROMPT.md`](../prompts/009-V0_2_4_START_PROMPT.md) ouvre `0.2.4 — HTTP Blocks + Economics + compliance HTTP finale`.
Le plan historique de la phase fondatrice clôturée est conservé dans [`plans/001-V0_0_3_PLAN.md`](plans/001-V0_0_3_PLAN.md). La séquence active des premières releases fonctionnelles est définie dans [`plans/002-FUNCTIONAL_RELEASE_SEQUENCE.md`](plans/002-FUNCTIONAL_RELEASE_SEQUENCE.md). Le plan détaillé de la release stable `0.1.1` est conservé comme historique clôturé dans [`plans/003-V0_1_1_CORE_FOUNDATION_PLAN.md`](plans/003-V0_1_1_CORE_FOUNDATION_PLAN.md). Le plan détaillé de la release stable `0.1.2` est conservé comme historique clôturé dans [`plans/004-V0_1_2_LOGGING_FOUNDATION_PLAN.md`](plans/004-V0_1_2_LOGGING_FOUNDATION_PLAN.md). Le plan détaillé de la release stable `0.1.3 — Configuration foundation` est conservé comme historique clôturé dans [`plans/005-V0_1_3_CONFIG_FOUNDATION_PLAN.md`](plans/005-V0_1_3_CONFIG_FOUNDATION_PLAN.md). Le plan détaillé de la release stable `0.1.4 — ksp-app-config-desk` est conservé comme historique clôturé dans [`plans/006-V0_1_4_CONFIG_DESKTOP_PLAN.md`](plans/006-V0_1_4_CONFIG_DESKTOP_PLAN.md), avec sa matrice finale [`validation/001-V0_1_4_CONFIG_DESKTOP.md`](validation/001-V0_1_4_CONFIG_DESKTOP.md). Son prompt d'ouverture historique reste [`../prompts/004-V0_1_4_START_PROMPT.md`](../prompts/004-V0_1_4_START_PROMPT.md). La release stable `0.2.0` clôt l'audit de bot3 et le découpage de la série. Son plan directeur est conservé comme historique clôturé dans [`plans/007-V0_2_0_SERIES_PLANNING.md`](plans/007-V0_2_0_SERIES_PLANNING.md), avec sa matrice finale [`validation/002-V0_2_0_SERIES_PLANNING.md`](validation/002-V0_2_0_SERIES_PLANNING.md). La release stable `0.2.1 — HTTP Solana foundation` a été ouverte par [`../prompts/006-V0_2_1_START_PROMPT.md`](../prompts/006-V0_2_1_START_PROMPT.md). Son gate de sizing et sa matrice exhaustive sont conservés dans [`plans/008-V0_2_1_ONCHAIN_HTTP_PLAN.md`](plans/008-V0_2_1_ONCHAIN_HTTP_PLAN.md), avec la validation finale [`validation/003-V0_2_1_ONCHAIN_HTTP.md`](validation/003-V0_2_1_ONCHAIN_HTTP.md), README/USAGE Transport et le smoke Devnet opt-in de composition Config -> Transport. Le prompt [`../prompts/007-V0_2_2_START_PROMPT.md`](../prompts/007-V0_2_2_START_PROMPT.md) a ouvert la release stable `0.2.2 — HTTP Accounts + Tokens + Cluster`. Son plan clôturé [`plans/009-V0_2_2_HTTP_ACCOUNTS_TOKENS_CLUSTER_PLAN.md`](plans/009-V0_2_2_HTTP_ACCOUNTS_TOKENS_CLUSTER_PLAN.md) conserve l'audit et l'implémentation des 22 wrappers typés, tandis que [`validation/004-V0_2_2_HTTP_ACCOUNTS_TOKENS_CLUSTER.md`](validation/004-V0_2_2_HTTP_ACCOUNTS_TOKENS_CLUSTER.md) enregistre les validations déterministes, les graphes Cargo et les deux smokes Devnet passés avant publication. Le prompt [`../prompts/008-V0_2_3_START_PROMPT.md`](../prompts/008-V0_2_3_START_PROMPT.md) a ouvert la release stable `0.2.3 — HTTP Transactions`. Son plan clôturé [`plans/010-V0_2_3_HTTP_TRANSACTIONS_PLAN.md`](plans/010-V0_2_3_HTTP_TRANSACTIONS_PLAN.md) conserve l'audit et l'implémentation des 11 wrappers ; le réaudit [`validation/005-V0_2_3_KSP_TRANSPORT_007_RETRO_AUDIT.md`](validation/005-V0_2_3_KSP_TRANSPORT_007_RETRO_AUDIT.md) confirme la complétude des 37 wrappers HTTP typés et [`validation/006-V0_2_3_HTTP_TRANSACTIONS.md`](validation/006-V0_2_3_HTTP_TRANSACTIONS.md) enregistre les validations finales, graphes Cargo et deux smokes Devnet passés avant publication. Le prompt [`../prompts/009-V0_2_4_START_PROMPT.md`](../prompts/009-V0_2_4_START_PROMPT.md) ouvre `0.2.4 — HTTP Blocks + Economics + compliance HTTP finale`. Son plan actif [`plans/011-V0_2_4_HTTP_BLOCKS_ECONOMICS_PLAN.md`](plans/011-V0_2_4_HTTP_BLOCKS_ECONOMICS_PLAN.md), établi par `0.2.4-pre.001`, fixe les 15 wrappers restants, la baseline Agave stable `v4.2.1`, le gate de sizing positif et la compliance finale `52/52 + 14/14`.
`IDEAS.md` conserve les pistes et questions qui ne sont pas encore des engagements du roadmap ni des décisions architecturales.

3
docs/plans/000-README.md
View File

@@ -1,5 +1,5 @@
<!-- file: docs/plans/000-README.md -->
<!-- version: 37 -->
<!-- version: 38 -->
# Plans KSP
@@ -19,6 +19,7 @@ Un plan décrit le périmètre, les décisions déjà acquises, les questions ou
- [`008-V0_2_1_ONCHAIN_HTTP_PLAN.md`](008-V0_2_1_ONCHAIN_HTTP_PLAN.md) — plan de `0.2.1`, établi par `0.2.1-pre.001`, recalibré par `pre.001-fix.001` et amené en clôture candidate par `pre.007`; il conserve l'inventaire 52 méthodes HTTP courantes + 14 Deprecated historiques, le design Transport/Config et le split de couverture typée sur `0.2.1`–`0.2.4`.
- [`009-V0_2_2_HTTP_ACCOUNTS_TOKENS_CLUSTER_PLAN.md`](009-V0_2_2_HTTP_ACCOUNTS_TOKENS_CLUSTER_PLAN.md) — plan clôturé de la release stable `0.2.2`, établi par `pre.001`, corrigé après réaudit Agave v4.2.1 puis exécuté jusqu'à `pre.007-fix.002`; il couvre les 22 wrappers Accounts/Tokens/Cluster, le smoke Transport opt-in et la préparation de `0.2.3`.
- [`010-V0_2_3_HTTP_TRANSACTIONS_PLAN.md`](010-V0_2_3_HTTP_TRANSACTIONS_PLAN.md) — plan historique clôturé de la release stable `0.2.3 — HTTP Transactions`, ouvert par `pre.001`, exécuté jusqu'à `pre.009` puis publié par `rel.001`; il couvre les 11 méthodes, la classification `8 Read / 2 WriteSubmission / 1 Simulation`, `KSP-TRANSPORT-007`, le no-resend et la préparation de `0.2.4`.
- [`011-V0_2_4_HTTP_BLOCKS_ECONOMICS_PLAN.md`](011-V0_2_4_HTTP_BLOCKS_ECONOMICS_PLAN.md) — plan actif de `0.2.4`, ouvert par `pre.001`; il fixe les 10 Blocks + 5 Economics, les overloads/legacy, les wires réutilisables, les limites runtime et la compliance finale `52/52 + 14/14` sous `KSP-TRANSPORT-007`.
Le `pre.001` de chaque release fonctionnelle peut introduire son propre plan détaillé lorsque la release s'ouvre.

4
docs/plans/002-FUNCTIONAL_RELEASE_SEQUENCE.md
View File

@@ -1,5 +1,5 @@
<!-- file: docs/plans/002-FUNCTIONAL_RELEASE_SEQUENCE.md -->
<!-- version: 39 -->
<!-- version: 40 -->
# Séquence des releases fonctionnelles KSP
@@ -394,6 +394,8 @@ Chaque `pre.001` réaudite la documentation officielle actuelle. Les méthodes D
`0.2.3-pre.001` réaudite le 2026-08-18 la catégorie Transactions contre la documentation Solana actuelle et Agave v4.2.1 : les 11 méthodes prévues restent exactes, la classification `8 Read / RetrySafe`, `2 WriteSubmission / NeverAfterDispatch` et `1 Simulation / RetrySafe` reste correcte, et le gate de sizing est positif. `pre.002`–`pre.007` livrent ensuite les primitives wire puis les 11 wrappers, `pre.008` réaudite rétroactivement `KSP-TRANSPORT-007` sur les 37 wrappers HTTP typés sans remédiation fonctionnelle, et `pre.009` prépare la candidate finale avec documentation, smoke Transport read-only étendu et prompt `0.2.4`. `0.2.3-rel.001` publie cette surface stable après validation du workspace, des graphes Cargo Transport/Config et des deux smokes Devnet. Aucun `base64`, `bs58`, `wincode` ni client RPC Solana supplémentaire n'est ajouté : les payloads sérialisés restent opaques dans Transport tant qu'un besoin de décodage local n'est pas démontré. Le plan détaillé clôturé est `docs/plans/010-V0_2_3_HTTP_TRANSACTIONS_PLAN.md`.
`0.2.4-pre.001` réaudite le même jour l'inventaire HTTP officiel et la baseline runtime actuelle : les 15 méthodes réservées restent exactement 10 Blocks + 5 Economics, la navigation Deprecated reste à 14 historiques et Agave stable `v4.2.1` confirme les overloads/limites/extensions sensibles (`getBlock` legacy, `getBlocks`, plafond 500_000, performance samples 720, `commissionBps`). Le gate de sizing est positif sans split de release. Le plan actif `docs/plans/011-V0_2_4_HTTP_BLOCKS_ECONOMICS_PLAN.md` prévoit des tranches dédiées à `getBlock`, `getBlockProduction`, `getInflationReward`, puis une compliance finale `52/52 current + 14/14 historical` sous `KSP-TRANSPORT-007` avant `0.2.5 — Wallet foundation`.
## `0.2.5` — Wallet foundation
Mission : créer `ksp-wallet-lib` et le format `.kspwallet`.

398
docs/plans/011-V0_2_4_HTTP_BLOCKS_ECONOMICS_PLAN.md Normal file
View File

@@ -0,0 +1,398 @@
<!-- file: docs/plans/011-V0_2_4_HTTP_BLOCKS_ECONOMICS_PLAN.md -->
<!-- version: 1 -->
# 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<u64> 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<u64>` | 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<u64>` | 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<T>
```
`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<Option<Reward>>` 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<u64>` | réutiliser `SolanaContextConfig` / `SolanaRpcResponse<T>` |
| `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<u16>
```
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<T>
SolanaTransactionEncoding
SolanaEncodedTransaction
SolanaTransactionVersion
SolanaWireField<T>
```
### À 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.