diff --git a/deltas/0.2.2/pre.001-fix.001.md b/deltas/0.2.2/pre.001-fix.001.md new file mode 100644 index 0000000..9aff21b --- /dev/null +++ b/deltas/0.2.2/pre.001-fix.001.md @@ -0,0 +1,224 @@ + + + +# 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 +``` + +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`. + +### Évolution 2 — `getVoteAccounts` + +Agave `v4.2.1` expose dans `RpcVoteAccountInfo` : + +```text +inflationRewardsCommissionBps Option +``` + +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`. + +### 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` ; +- confirmation dans Agave `v4.2.1` de `RpcVoteAccountInfo.inflation_rewards_commission_bps: Option` ; +- 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`. diff --git a/docs/plans/009-V0_2_2_HTTP_ACCOUNTS_TOKENS_CLUSTER_PLAN.md b/docs/plans/009-V0_2_2_HTTP_ACCOUNTS_TOKENS_CLUSTER_PLAN.md index 0fa73e8..3d135eb 100644 --- a/docs/plans/009-V0_2_2_HTTP_ACCOUNTS_TOKENS_CLUSTER_PLAN.md +++ b/docs/plans/009-V0_2_2_HTTP_ACCOUNTS_TOKENS_CLUSTER_PLAN.md @@ -1,5 +1,5 @@ - + # 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/v3.1.8/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/v3.1.8/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/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 ``` -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 : -leur source sert seulement à lever les ambiguïtés de la documentation HTTP lorsque nécessaire. +Les liens `Source` actuellement exposés par les pages RPC Solana consultées pointent encore vers Agave `v3.1.8`. Ce constat documentaire ne +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> 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 tpuVote Option tvu Option version Option +clientId Option ``` -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` 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 -nodePubkey Pubkey -activatedStake u64 -commission u8 -epochVoteAccount bool -epochCredits Vec<(epoch u64, credits u64, previousCredits u64)> -lastVote u64 -rootSlot u64 +votePubkey Pubkey +nodePubkey Pubkey +activatedStake u64 +commission u8 +inflationRewardsCommissionBps Option +epochVoteAccount bool +epochCredits Vec<(epoch u64, credits u64, previousCredits 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` 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 :