khadhroony-solana-project/deltas/0.2.2/pre.001-fix.001.md

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 :

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 :

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 :

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 :

https://solana.com/docs/rpc/http
https://solana.com/docs/rpc/json-structures

Source primaire Agave 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/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 :

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 :

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 :

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 :

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é

docs/plans/009-V0_2_2_HTTP_ACCOUNTS_TOKENS_CLUSTER_PLAN.md

Fichier ajouté

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

Fichiers supprimés

Aucun.

Fichiers volontairement inchangés

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 :

0.2.2-pre.1

L'identifiant de livraison est :

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.