225 lines
7.7 KiB
Markdown
225 lines
7.7 KiB
Markdown
<!-- 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`.
|