v0.2.2-pre.001-fix.001

deltas/0.2.2/pre.001-fix.001.md

@@ -0,0 +1,224 @@
+<!-- file: deltas/0.2.2/pre.001-fix.001.md -->
+<!-- version: 1 -->
+
+# Delta `0.2.2-pre.001-fix.001` — réaudit Agave `v4.2.1` et complétude des DTOs Cluster
+
+## Base requise
+
+Livraison précédente :
+
+```text
+0.2.2-pre.001
+workspace.package.version = "0.2.2-pre.1"
+```
+
+Le fichier `docs/plans/009-V0_2_2_HTTP_ACCOUNTS_TOKENS_CLUSTER_PLAN.md` fourni pour correction porte déjà `version: 2`; le présent correctif
+l'incrémente à `version: 3` conformément à `GEN-FILE-004`.
+
+Le delta historique :
+
+```text
+deltas/0.2.2/pre.001.md
+```
+
+reste inchangé. Conformément à `KSP-REL-003` et `VER-DELTA-007`, l'audit incomplet de `pre.001` n'est pas réécrit silencieusement : ce fix
+trace explicitement sa correction avant `pre.002`.
+
+## Objectif
+
+Corriger la source Agave complémentaire utilisée par le plan `0.2.2` et réauditer les contrats wire concernés avant l'implémentation des DTOs.
+
+`pre.001` avait pris Agave `v3.1.8` comme source complémentaire parce que les liens `Source` actuellement exposés par les pages RPC de
+`solana.com` pointent encore vers ce snapshot. Ce constat reste utile pour expliquer la documentation publiée, mais il ne suffit pas à qualifier
+`v3.1.8` de source Agave actuelle.
+
+Le présent fix recoupe donc les pages Solana avec le tag Agave plus récent :
+
+```text
+v4.2.1
+```
+
+et utilise directement ses sources primaires pour les structures/configurations RPC qui intéressent `0.2.2`.
+
+## Sources réauditées
+
+Documentation RPC :
+
+```text
+https://solana.com/docs/rpc/http
+https://solana.com/docs/rpc/json-structures
+```
+
+Source primaire Agave `v4.2.1` :
+
+```text
+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/filter.rs
+https://github.com/anza-xyz/agave/blob/v4.2.1/rpc-client-types/src/request.rs
+https://github.com/anza-xyz/agave/blob/v4.2.1/rpc-client-types/src/response.rs
+```
+
+Le `Cargo.toml` racine du tag `v4.2.1` déclare lui-même `workspace.package.version = "4.2.1"`.
+
+## Résultat du réaudit
+
+### Invariants confirmés
+
+Le passage de la référence complémentaire `v3.1.8` à `v4.2.1` ne remet pas en cause le périmètre `0.2.2` ni les principales limites déjà
+retenues :
+
+```text
+MAX_MULTIPLE_ACCOUNTS                           = 100
+MAX_GET_PROGRAM_ACCOUNT_FILTERS                 = 4
+MAX_GET_SLOT_LEADERS                            = 5000
+MAX_RPC_VOTE_ACCOUNT_INFO_EPOCH_CREDITS_HISTORY = 5
+```
+
+Les filtres Program Accounts restent :
+
+```text
+DataSize
+Memcmp
+TokenAccountState
+```
+
+et `Memcmp` conserve les formes `base58`, `base64` et octets bruts, avec 128 octets décodés maximum et rejet de l'ancien libellé `binary`.
+
+Les configurations Accounts, Token selector, Leader Schedule et Vote Accounts retenues dans le plan restent également compatibles avec
+`v4.2.1`.
+
+### Évolution 1 — `getClusterNodes`
+
+Agave `v4.2.1` expose dans `RpcContactInfo` le champ supplémentaire :
+
+```text
+clientId Option<String>
+```
+
+La page RPC Solana courante ne le liste pas encore. KSP doit néanmoins pouvoir accepter et préserver ce champ lorsqu'un noeud/provider le
+retourne, sans le rendre obligatoire pour les réponses qui ne le contiennent pas.
+
+Le DTO Cluster prévu par le plan est donc complété avec `clientId: Option<String>`.
+
+### Évolution 2 — `getVoteAccounts`
+
+Agave `v4.2.1` expose dans `RpcVoteAccountInfo` :
+
+```text
+inflationRewardsCommissionBps Option<u16>
+```
+
+La source précise que ce champ est absent/`None` pour les noeuds antérieurs à son introduction. KSP doit le préserver comme optionnel et ne doit
+pas le déduire artificiellement du champ historique `commission: u8`.
+
+Le DTO Vote Account prévu par le plan est donc complété avec `inflationRewardsCommissionBps: Option<u16>`.
+
+### Tests à préserver dans la suite
+
+La stratégie de tests du plan exige désormais explicitement :
+
+- `getClusterNodes` avec présence et absence de `clientId` ;
+- `getVoteAccounts` avec présence et absence de `inflationRewardsCommissionBps` ;
+- conservation des tests déjà prévus sur les autres champs optionnels/nullables et sur les limites `100 / 4 / 5000 / 5`.
+
+## Périmètre inchangé
+
+Le correctif ne modifie pas :
+
+- les 22 méthodes affectées à `0.2.2` ;
+- la partition globale `4 / 22 / 11 / 15` ;
+- le gate de sizing positif de `0.2.2` ;
+- l'architecture `wrapper -> descriptor -> execute_standard_rpc -> pool -> reqwest -> JSON-RPC -> decode` ;
+- Config ;
+- les dépendances Cargo ;
+- les sources Rust ;
+- les canaris `0.2.1` ;
+- le planning `pre.002` à `pre.007`.
+
+Aucun nouveau besoin `base64`, `bs58`, SPL, `solana-client` ou SDK RPC haut niveau n'est introduit par ce réaudit.
+
+## Fichier modifié
+
+```text
+docs/plans/009-V0_2_2_HTTP_ACCOUNTS_TOKENS_CLUSTER_PLAN.md
+```
+
+## Fichier ajouté
+
+```text
+deltas/0.2.2/pre.001-fix.001.md
+```
+
+## Fichiers supprimés
+
+Aucun.
+
+## Fichiers volontairement inchangés
+
+```text
+Cargo.toml
+ROADMAP.md
+CHANGELOG.md
+deltas/0.2.2/pre.001.md
+docs/000-README.md
+docs/plans/000-README.md
+docs/plans/002-FUNCTIONAL_RELEASE_SEQUENCE.md
+docs/plans/008-V0_2_1_ONCHAIN_HTTP_PLAN.md
+docs/validation/003-V0_2_1_ONCHAIN_HTTP.md
+crates/ksp-onchain-transport-lib/**
+crates/ksp-config-lib/**
+config/**
+```
+
+Le plan `009` reste le fichier canonique ; aucun fichier parallèle `*.corrected.md` n'est ajouté au dépôt.
+
+## Version Cargo
+
+Ce correctif est exclusivement documentaire et ne touche aucun fichier consommé par le code, le build, le runtime, la configuration exécutable
+ou une migration. Conformément à `VER-ID-008`, `workspace.package.version` reste :
+
+```text
+0.2.2-pre.1
+```
+
+L'identifiant de livraison est :
+
+```text
+0.2.2-pre.001-fix.001
+```
+
+## Validations exécutées
+
+- relecture de `RULES.md`, `docs/rules/VERSION_WORKFLOW.md`, `docs/rules/FILE_CONTRACTS.md`, `docs/rules/RULES_GENERAL.md`,
+  `docs/rules/RULES_KSP.md` et `docs/rules/PROMPT_STRUCTURE.md` ;
+- contrôle des règles `GEN-FILE-004`, `VER-ID-003`, `VER-ID-008`, `VER-DELTA-003`, `VER-DELTA-007`, `VER-ARCHIVE-002`,
+  `VER-ARCHIVE-004` et `KSP-REL-003` applicables à ce correctif ;
+- comparaison de la source Agave `v3.1.8` utilisée par `pre.001` avec Agave `v4.2.1` sur les structures/configs RPC nécessaires à
+  Accounts/Tokens/Cluster ;
+- confirmation dans Agave `v4.2.1` des limites `100 / 4 / 5000 / 5` et des variantes Program Account filters ;
+- confirmation dans Agave `v4.2.1` de `RpcContactInfo.client_id: Option<String>` ;
+- confirmation dans Agave `v4.2.1` de `RpcVoteAccountInfo.inflation_rewards_commission_bps: Option<u16>` ;
+- contrôle que le plan canonique référence désormais `v4.2.1` pour les cinq sources Agave complémentaires ;
+- contrôle que les seules mentions restantes de `v3.1.8` expliquent le snapshot encore lié par le site Solana ;
+- contrôle que `clientId` et `inflationRewardsCommissionBps` sont présents dans les DTOs prévus et dans la stratégie de tests ;
+- contrôle qu'aucune autre famille de fichier n'est modifiée par ce fix.
+
+## Validations non exécutées
+
+Aucune validation Cargo n'est requise spécifiquement pour ce fix documentaire : aucune source Rust, dépendance, feature, configuration runtime ou
+manifest Cargo n'est modifié.
+
+Les validations Rust prévues pour `0.2.2-pre.002` restent inchangées et devront être réellement exécutées après ses modifications de code.
+
+## Questions ouvertes
+
+Aucune question bloquante nouvelle.
+
+Le plan garde comme règle de mise en oeuvre que les champs optionnels/versionnés observés dans Agave doivent être représentés sans rendre leur
+présence obligatoire chez tous les providers.
+
+## Suite
+
+Après application/commit de `0.2.2-pre.001-fix.001`, reprendre `0.2.2-pre.002` sur le plan `009` corrigé, en incluant dès la conception des DTOs
+Cluster/Vote les deux champs optionnels confirmés par Agave `v4.2.1`.

docs/plans/009-V0_2_2_HTTP_ACCOUNTS_TOKENS_CLUSTER_PLAN.md

@@ -1,5 +1,5 @@
 <!-- file: docs/plans/009-V0_2_2_HTTP_ACCOUNTS_TOKENS_CLUSTER_PLAN.md -->
-<!-- version: 2 -->
+<!-- version: 3 -->
 
 # Plan `0.2.2` — HTTP Accounts + Tokens + Cluster
 
@@ -13,7 +13,7 @@ registry des méthodes, exécution HTTP générique, adapter Config -> Transport
 Cette release ne reconstruit aucun transport par famille. Elle complète uniquement la surface typée des 22 méthodes déjà attribuées à
 `HttpRpcCoverageRelease::V0_2_2`.
 
-## Sources normatives réauditées le 2026-08-17
+## Sources normatives réauditées les 2026-08-17 et 2026-08-18
 
 Source documentaire principale :
 
@@ -25,15 +25,19 @@ Références complémentaires officielles utilisées pour les formes wire commun
 
 ```text
 https://solana.com/docs/rpc/json-structures
-https://github.com/anza-xyz/agave/blob/v3.1.8/rpc/src/rpc.rs
+https://github.com/anza-xyz/agave/blob/v4.2.1/rpc/src/rpc.rs
-https://github.com/anza-xyz/agave/blob/v3.1.8/rpc-client-types/src/config.rs
+https://github.com/anza-xyz/agave/blob/v4.2.1/rpc-client-types/src/config.rs
-https://github.com/anza-xyz/agave/blob/v3.1.8/rpc-client-types/src/filter.rs
+https://github.com/anza-xyz/agave/blob/v4.2.1/rpc-client-types/src/filter.rs
-https://github.com/anza-xyz/agave/blob/v3.1.8/rpc-client-types/src/request.rs
+https://github.com/anza-xyz/agave/blob/v4.2.1/rpc-client-types/src/request.rs
-https://github.com/anza-xyz/agave/blob/v3.1.8/rpc-client-types/src/response.rs
+https://github.com/anza-xyz/agave/blob/v4.2.1/rpc-client-types/src/response.rs
 ```
 
-Les liens `Source` des pages RPC Solana consultées pointent actuellement vers Agave `v3.1.8`. KSP ne prend pas de dépendance sur ces crates :
+Les liens `Source` actuellement exposés par les pages RPC Solana consultées pointent encore vers Agave `v3.1.8`. Ce constat documentaire ne
-leur source sert seulement à lever les ambiguïtés de la documentation HTTP lorsque nécessaire.
+signifie pas que `v3.1.8` soit la source Agave la plus récente à auditer. Le 2026-08-18, KSP recoupe donc ces pages avec le tag Agave `v4.2.1`,
+dont le workspace déclare lui-même la version `4.2.1`, afin de détecter les évolutions wire plus récentes que les liens du site Solana.
+
+KSP ne prend pas de dépendance sur ces crates : leurs sources servent seulement à lever les ambiguïtés de la documentation HTTP et à préserver
+les champs optionnels/versionnés réellement exposés par Agave `v4.2.1`, plus récent que le snapshot `v3.1.8` encore lié par le site Solana.
 
 ## Résultat de l'audit global
 
@@ -135,7 +139,7 @@ true         -> RpcResponse<Vec<KeyedAccount>>
 
 Le contrat public doit refléter cette union au lieu de supprimer le contexte ou d'inventer un contexte lorsque le serveur n'en renvoie pas.
 
-Les filtres KSP doivent distinguer les trois variantes acceptées par la source primaire Agave actuelle :
+Les filtres KSP doivent distinguer les trois variantes acceptées par la source primaire Agave `v4.2.1` :
 
 ```text
 DataSize(u64)
@@ -215,11 +219,16 @@ tpuQuic              Option<String>
 tpuVote              Option<String>
 tvu                  Option<String>
 version              Option<String>
+clientId             Option<String>
 ```
 
-Même si Agave utilise actuellement `SocketAddr` en interne pour plusieurs endpoints, le DTO public Transport ne doit pas imposer davantage que
+Même si Agave `v4.2.1` utilise `SocketAddr` en interne pour plusieurs endpoints, le DTO public Transport ne doit pas imposer davantage que
 le contrat JSON. Les adresses réseau restent donc des chaînes wire optionnelles à moins qu'un invariant officiel plus strict soit nécessaire.
 
+La page Solana courante ne liste pas encore `clientId`, mais Agave `v4.2.1` expose `client_id: Option<String>` dans `RpcContactInfo`. KSP doit donc
+accepter et préserver ce champ optionnel sans le rendre obligatoire, afin de rester compatible avec les noeuds/providers qui l'émettent comme
+avec ceux qui suivent encore la forme documentée sans ce champ.
+
 ### `EpochInfo` et `EpochSchedule`
 
 `EpochInfo` conserve :
@@ -276,20 +285,25 @@ delinquentSlotDistance
 Chaque record conserve au minimum :
 
 ```text
-votePubkey        Pubkey
+votePubkey                    Pubkey
-nodePubkey        Pubkey
+nodePubkey                    Pubkey
-activatedStake    u64
+activatedStake                u64
-commission        u8
+commission                    u8
-epochVoteAccount  bool
+inflationRewardsCommissionBps Option<u16>
-epochCredits      Vec<(epoch u64, credits u64, previousCredits u64)>
+epochVoteAccount              bool
-lastVote          u64
+epochCredits                  Vec<(epoch u64, credits u64, previousCredits u64)>
-rootSlot          u64
+lastVote                      u64
+rootSlot                      u64
 ```
 
 Un petit DTO nommé pour une entrée `epochCredits` est préférable à exposer un tuple public opaque, tout en conservant la forme tableau du wire
-au décodage. La source Agave courante limite la réponse à cinq entrées d'historique `epochCredits` par validator; KSP ne doit pas supposer que
+au décodage. La source Agave `v4.2.1` limite la réponse à cinq entrées d'historique `epochCredits` par validator; KSP ne doit pas supposer que
 l'historique complet d'un vote account est exposé par cette méthode RPC.
 
+Agave `v4.2.1` ajoute également `inflationRewardsCommissionBps`, sérialisé comme champ optionnel. La source précise que ce champ vaut `None` pour
+un noeud antérieur à son introduction. Le DTO KSP doit donc le conserver en `Option<u16>` et ne jamais le déduire artificiellement de
+`commission`.
+
 ## DTOs communs et organisation prévue
 
 `pre.002` doit introduire des types partagés ciblés, pas un « mega DTO ». Le découpage prévu est conceptuellement :
@@ -405,11 +419,11 @@ Cas transversaux prioritaires :
 - `getAccountInfo` et `getMultipleAccounts` avec comptes absents ;
 - `getProgramAccounts` bare vs `withContext` ;
 - `TokenAmount.uiAmount: null` ;
-- fields optionnels de `getClusterNodes` ;
+- fields optionnels de `getClusterNodes`, dont présence/absence de `clientId` ;
 - `EpochInfo.transactionCount: null` ;
 - `SnapshotSlotInfo.incremental: null` et erreur NoSnapshot ;
 - `getLeaderSchedule: null` + overloads ;
-- `getVoteAccounts` current/delinquent et epoch credits ;
+- `getVoteAccounts` current/delinquent, epoch credits et présence/absence de `inflationRewardsCommissionBps` ;
 - limites 100, 4 filtres Program Accounts et 5000; variantes/encodages `memcmp`.
 
 Les canaries de release doivent maintenir :