v0.2.2-pre.001-fix.001
This commit is contained in:
224
deltas/0.2.2/pre.001-fix.001.md
Normal file
224
deltas/0.2.2/pre.001-fix.001.md
Normal file
@@ -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`.
|
||||
@@ -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/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<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
|
||||
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<u16>
|
||||
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<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 :
|
||||
|
||||
Reference in New Issue
Block a user